api-provider-setup

API Provider Setup

Add and configure third-party API relay station providers for OpenClaw.

Configuration location

Configuration file:~/.openclaw/openclaw.json

In the models.providers section, add a custom provider.

Configuration template

Anthropic-compatible API (such as anapi, Zhipu)

{
  "models": {
    "mode": "merge",
    "providers": {
      "供应商名称": {
        "baseUrl": "https://api.example.com",
        "apiKey": "sk-your-api-key",
        "auth": "api-key",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "model-id",
            "name": "显示名称",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 200000,
            "maxTokens": 8192,
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            }
          }
        ]
      }
    }
  }
}

OpenAI-compatible API (such as OpenRouter)

{
  "models": {
    "mode": "merge",
    "providers": {
      "供应商名称": {
        "baseUrl": "https://api.example.com/v1",
        "apiKey": "sk-your-api-key",
        "auth": "api-key",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-4",
            "name": "GPT-4",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 128000,
            "maxTokens": 4096
          }
        ]
      }
    }
  }
}

Key field descriptions

Field	Required	Description
`baseUrl`	✅	API endpoint address (excluding paths such as /v1/messages)
`apiKey`	✅	API key
`auth`	✅	Authentication method, usually `api-key`
`api`	✅	API format:`anthropic-messages` or `openai-completions`
`models`	✅	List of models supported by this provider
`models[].id`	✅	Model ID (used when calling)
`models[].name`	❌	Display name
`models[].contextWindow`	❌	Context window size
`models[].maxTokens`	❌	Maximum number of output tokens
`models[].reasoning`	❌	Whether reasoning mode is supported

Add model alias

In agents.defaults.models , add an alias:

{
  "agents": {
    "defaults": {
      "models": {
        "供应商/模型id": {
          "alias": "简短别名"
        }
      }
    }
  }
}

⚠️ Important constraints：alias fieldmust be a string, not an array!
// ✅ 正确
"alias": "opus46"

// ❌ 错误 - 会导致 Config validation failed
"alias": ["opus46", "aixn/opus46"]
If multiple aliases need to point to the same model, you need to add multiple entries in models :
"供应商/模型id": { "alias": "别名1" }

Set as default model

In agents.defaults.model , set:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "供应商/模型id",
        "fallbacks": [
          "备选供应商1/模型id",
          "备选供应商2/模型id"
        ]
      }
    }
  }
}

Adding process

Obtain provider information
- Base URL
- API Key
- API format (Anthropic or OpenAI compatible)
- List of supported models

Add using gateway config.patch

gateway config.patch 添加供应商配置

Restart Gateway to take effect
```
gateway restart
```

Test the new model

session_status(model="新供应商/模型id")

Common relay station configuration examples

Anapi (Anthropic relay)

"anapi": {
  "baseUrl": "https://anapi.9w7.cn",
  "apiKey": "sk-xxx",
  "auth": "api-key",
  "api": "anthropic-messages",
  "models": [{"id": "opus-4.5", "name": "Opus 4.5", "contextWindow": 200000}]
}

Zhipu ZAI

"zai": {
  "baseUrl": "https://open.bigmodel.cn/api/anthropic",
  "apiKey": "xxx.xxx",
  "auth": "api-key",
  "api": "anthropic-messages",
  "models": [{"id": "glm-4.7", "name": "GLM-4.7", "contextWindow": 200000}]
}

OpenRouter VIP

"openrouter-vip": {
  "baseUrl": "https://openrouter.vip/v1",
  "apiKey": "sk-xxx",
  "auth": "api-key",
  "api": "openai-completions",
  "models": [{"id": "gpt-5.2", "name": "GPT-5.2", "contextWindow": 200000}]
}

Troubleshooting

401 Unauthorized - API Key error or expired
404 Not Found - baseUrl path error or API format mismatch
Model does not exist - Check whether models[].id is correct
Format error - Check whether the api field matches the provider's API format

Common issues and solutions

API format mismatch causes 404

Symptom: The message is sent successfully, but the AI returns 404 status code (no body)

Cause: The provider's API format is configured incorrectly.

Diagnosis：

# 测试 Anthropic Messages API 格式
curl -X POST "https://your-api-endpoint/v1/messages" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"model-id","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

# 测试 OpenAI Completions API 格式
curl -X POST "https://your-api-endpoint/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"model":"model-id","messages":[{"role":"user","content":"hi"}],"max_tokens":10}'

Solution：

Confirm the API format used by the provider:
- Anthropic format: Use /v1/messages, the request body contains the messages array
- OpenAI format: Use /v1/chat/completions, the request body contains the messages array

Modify the models.json field in api :

{
  "providers": {
    "your-provider": {
      "api": "anthropic-messages"  // 或 "openai-completions"
    }
  }
}

Restart Gateway:
```
openclaw gateway restart
```

Case：

Anapi uses Anthropic Messages API, must set "api": "anthropic-messages"
OpenRouter VIP uses OpenAI Completions API, must set "api": "openai-completions"
Zhipu ZAI uses Anthropic Messages API, must set "api": "anthropic-messages"