OpenClaw API Relay Integration Guide: Autonomous Agent Framework Configuration

1. What is OpenClaw

OpenClaw is an open-source AI Agent framework: point it to a model (local or cloud gateway), and it can automate tasks on your computer—operating interfaces, running commands, managing files, etc. Its core is "configuring a model endpoint," making it perfectly suited for integrating with our gateway.

2. Installing OpenClaw

We recommend the one-click installation script:

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard

You can also install via Docker or from source:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
# Docker: ./scripts/docker/setup.sh
# Source (pnpm): corepack enable && pnpm install && pnpm openclaw setup

3. Connecting to our Gateway (Two Methods)

Method 1: Interactive Onboarding

Run openclaw onboard, select an option that supports custom addresses when prompted for the Provider, and enter:

Base URL : https://www.relay-api.com
API Key  : sk-your-api-key
Model ID : claude-sonnet-5

(The openai/gemini endpoints correspond to https://www.relay-api.com/v1 and https://www.relay-api.com/v1beta)

Method 2: Directly Editing the Configuration File

OpenClaw reads ~/.openclaw/openclaw.json (Linux/macOS) or %USERPROFILE%\.openclaw\openclaw.json (Windows). Add a new Provider under models.providers:

{
  "gateway": {
    "mode": "local"
  },
  "agents": {
    "defaults": {
      "model": {"primary": "jizhi/claude-sonnet-5"}
    }
  },
  "models": {
    "providers": {
      "jizhi": {
        "baseUrl": "https://www.relay-api.com",
        "apiKey": "sk-your-api-key",
        "api": "openai-completions"
      }
    }
  }
}

Replace primary with your model slug to have all OpenClaw agent tasks route through our gateway.

4. Startup and Common Commands

openclaw gateway --port 18789

After starting, visit http://localhost:18789 to access the dashboard. Common commands:

openclaw doctor              # Diagnose issues
openclaw security audit      # Security check
openclaw config set key x    # Update configuration
openclaw channels add --channel telegram  # Add message channels

5. Troubleshooting

Symptom	Resolution
401 / 403	Invalid key, inactive, or insufficient balance; verify the sk- key and top up if necessary.
404 / Model unavailable	Model slug mismatch or model not enabled; verify the Model ID.
Cannot connect to model	Ensure the baseUrl uses our platform's entry point.

Security Suggestion: Never commit your sk- key to public repositories; agent tasks consume tokens quickly, so keep an eye on your balance.

Base URL Note: Our platform accepts both /v1beta/models/... and /v1beta/v1beta/models/... (as well as /v1/... and /v1/v1/...), so it does not matter if the client automatically appends /v1 or /v1beta; both the domain root and the address including /v1beta will work. Please check and copy the Model ID from the "Model ID" section in the top-right corner of the "Tokens" page in the dashboard.