Appearance

OpenClaw 常见问题 ​

使用 OpenClaw 接入 Mirrorstages 时的常见问题排查指南。

403 被拦截 ​

症状：provider 配好了，curl 直接请求 API 正常返回 200，但 OpenClaw 发出去就是 403 Your request was blocked。

原因：OpenClaw 底层使用 @anthropic-ai/sdk，发请求时会携带官方 SDK 的 User-Agent（如 Anthropic/JS 0.73.0），部分 CDN 或 WAF 会拦截这类 UA。

解决：在 provider 配置里添加 headers 字段覆盖 UA：

json
{
  "anthropic": {
    "baseUrl": "https://api.mirrorstages.com/anthropic",
    "apiKey": "your-api-key",
    "api": "anthropic-messages",
    "headers": {
      "User-Agent": "Mozilla/5.0"
    },
    "models": [...]
  }
}

baseUrl 不要带 /v1 ​

症状：请求直接 404，日志中看到请求路径变成了 /v1/v1/messages。

原因：Anthropic SDK 会在 baseURL 后面自动拼接 /v1/messages。如果你的 baseUrl 已经写了 /v1，实际请求会变成双重路径。

解决：Anthropic 协议的 baseUrl 只写到域名，不带 /v1：

json
{
  "baseUrl": "https://api.mirrorstages.com/anthropic"
}

TIP

OpenAI 协议需要带 /v1，即 https://api.mirrorstages.com/openai/v1。这是因为两种 SDK 的路径拼接逻辑不同。

api 字段只认三个值 ​

症状：启动报 Config invalid，或者模型列表里看不到你配的 provider。

原因：OpenClaw 的 api 字段做了严格校验，只接受以下三个值：

值对应格式
anthropic-messagesAnthropic Messages API
openai-completionsOpenAI Chat Completions
openai-responsesOpenAI Responses API

写成 openai-chat、openai、anthropic 等都会报错。

解决：通过 Mirrorstages 使用时，Claude 模型填 anthropic-messages，GPT 模型填 openai-completions。

openai-completions 收到空回复 ​

症状：api 设为 openai-completions，请求成功（日志 isError=false），但 UI 上显示空消息。

原因：OpenClaw 内部使用 Anthropic 格式处理消息流，openai-completions 返回的 OpenAI 格式响应在某些情况下无法正确映射。

解决：如果你的模型同时支持 Anthropic 和 OpenAI 格式，优先使用 anthropic-messages。

配置了但没生效 ​

症状：修改了 openclaw.json 但 OpenClaw 仍使用旧配置。

原因：OpenClaw 有两处 provider 配置需要同步：

~/.openclaw/openclaw.json              → models.providers
~/.openclaw/agents/main/agent/models.json → providers

只改一个可能会出现不生效的情况。

解决：修改后用以下命令确认：

bash
openclaw models status

或者重启 OpenClaw Gateway：

bash
openclaw gateway restart

api 字段填什么？ ​

OpenClaw 支持三种 API 协议：

api 值适用场景对应接口
anthropic-messagesClaude 系列模型Anthropic Messages API
openai-completionsGPT 系列及 OpenAI 兼容模型/v1/chat/completions
openai-responsesOpenAI Responses API/v1/responses

通过 Mirrorstages 使用时：Claude 模型填 anthropic-messages，GPT 模型填 openai-completions。

"mode": "merge" 是什么？ ​

"mode": "merge" 表示你的自定义 provider 配置会与 OpenClaw 内置的默认 provider 列表合并。如果不加，你的配置可能会完全覆盖内置配置。强烈建议始终加上。

JSON 格式报错 ​

JSON 格式常见错误：

  • 多余逗号：最后一个元素后面不能有逗号
  • 缺少逗号：两个并列的键值对之间必须用逗号分隔
  • 引号问题：JSON 只接受英文双引号 "，不能用中文引号或单引号
  • 括号不匹配：每个 { 都要有对应的 }，每个 [ 都要有对应的 ]

可以使用以下命令验证格式：

bash
python3 -m json.tool ~/.openclaw/openclaw.json

reasoning 字段是什么？ ​

reasoning 控制是否启用模型的推理/思考模式。设为 true 时，模型会先进行内部推理再输出回复，但会消耗更多 token。GPT-5.x Codex 系列通常支持 reasoning，Claude 模型根据版本而定。如果不确定，设为 false。

openai-completions 和 openai-responses 有什么区别？ ​

  • openai-completions — 对应 OpenAI Chat Completions API（/v1/chat/completions），最通用的格式，绝大多数服务都支持。通过 Mirrorstages 使用 GPT 模型时用这个。
  • openai-responses — 对应 OpenAI Responses API（/v1/responses），主要用于 Azure OpenAI 或原生 OpenAI 新版 API，一般不使用。

排查工具速查 ​

命令用途
openclaw models status查看当前模型和认证状态
openclaw models list查看已配置的模型列表
openclaw doctor综合诊断
openclaw gateway restart重启 Gateway

排查核心思路：先用 curl 确认 Mirrorstages API 本身正常，再检查 OpenClaw 端发出的请求有什么不同（UA、路径、格式）。