三道门详解

  1. 注册模型 — 在全局 openclaw.json 的 providers.models 里声明 provider 名称、API 地址、支持的模型列表
  2. 加入白名单 — 在 agent 级 models.json 的 defaults.models 里把模型加进去。==这一步没做 = 注册了也调不到==
  3. 配置认证 — 在 auth-profiles.json 里写入 API key 或 OAuth token。token 有过期时间的要定期同步

API 类型踩坑

anthropic-messages vs anthropic

典型表现
Anthropic 的 API 类型必须用 anthropic-messages，不能用 anthropic。用错了不会报错，但请求会失败。这是一个静默失败的经典案例——HTTP 200 但 body 是错误信息。
判断标准
解决方向

openai-completions

典型表现
OpenAI 兼容接口的标准类型。cliproxy 和大部分第三方站点用这个。
判断标准
解决方向

openai-responses

典型表现
OpenAI Responses API 类型，用于较新的模型接口。
判断标准
解决方向

当前 Provider 一览

ProviderAPI 类型角色特点
foxcodeanthropic-messages默认主力直连 Anthropic 官方 API，独立 rate limit，cooldown 后自动恢复
cliproxyopenai-completions备选多站点 round-robin 路由，端口 8317，有黑名单机制
代理通道openai-completions备选代理转发 Claude 系列
zaiopenai-completions终极兜底GLM 系列模型，走智谱 API，最后防线
openai-codexopenai-responses按需Codex 系列，OAuth token 认证，需定期同步

重启 Gateway

改完任何配置，必须重启 Gateway。Gateway 是常驻进程，启动时把 JSON 配置缓存到内存里。你改了文件但没重启，它用的还是旧配置。

# 重启 Gateway
systemctl --user restart openclaw-gateway.service

# 确认状态
systemctl --user status openclaw-gateway.service --no-pager

实操清单

✓推荐做法
  • 注册 provider 后立即验证：openclaw models list --json
  • 改配置后立刻重启 Gateway
  • 用 manage.sh sync-models 做幂等同步，不要手动改远端文件
  • 新 provider 上线先用 manage.sh status 确认注册状态
✗不推荐
  • 不要直接改远端的 openclaw.json，下次同步会覆盖
  • 不要忘了白名单这一步（第二步）
  • 不要用 anthropic 作为 API 类型，必须用 anthropic-messages
  • 不要在 agent 级 models.json 里注册新 provider
⚠常见误区
  • HTTP 200 不代表成功——部分站点认证失效返回 200 + 错误 body
  • Provider 注册了但没加白名单 = 静默不可用
  • token 过期后不会自动刷新，需要手动从本地同步到远端
  • 远端 IP 可能被限流（负载上限），本地同 key 可用不代表远端也行