如何把 OpenClaw 接入 OpenAI 兼容 AI 网关

OpenClaw 是一个通用 Agent 工具,它本身不绑定任何模型厂商,而是要求你给它一个 OpenAI 兼容的 API 地址。这套接入方式不是 OpenClaw 独有的 —— 几十个 Agent 框架、CLI 工具、IDE 插件都用同一套约定,所以下面的配置方法远不止对 OpenClaw 有用:只要一个工具要你填"base URL"和"API key",这套思路就适用。

这篇文章只讲两件真正重要的事:base URL 和 key 怎么填、模型 id 怎么选,以及接入过程中会实际碰到的错误码。

为什么只需要 base URL + key

绝大多数支持"OpenAI 兼容"协议的 Agent 工具,对接任何后端只需要三样东西:

1. base URL —— /chat/completions(通常还有 /models)实际所在的地址。
2. API key —— 以 Authorization: Bearer <key> 的形式发送。
3. 模型 id —— 后端认识的一个字符串。

只要网关实现了和 OpenAI API 一致的请求/响应结构,任何基于这套结构写的工具就能直接对接这个网关,不用改一行代码 —— 你不是在写新的集成,只是在改两个配置值。这正是"OpenAI 兼容 AI 网关"这个思路的核心:OpenClaw 的代码不用变,变的只是它被告知去调用的端点和 key。

这也意味着接入是厂商无关的。一旦 OpenClaw 指向了网关,你就可以只靠改 model 字符串,在不同底层厂商的对话模型之间切换 —— 不需要新的 SDK,不需要新的鉴权流程,OpenClaw 本身也不用改代码。

第一步:拿到 base URL 和 API key

每个 OpenAI 兼容网关都会区分两个不同的地址:

• 网关地址(数据面)—— 真正对外提供 /v1/chat/completions 服务的地址,这是 OpenClaw 需要填的。
• 厂商控制台—— 用来注册、创建 key、查看用量的地方,它是一个独立的域名,本身不承接 /v1 流量。

先注册、打开控制台、创建一个 API key。完整的 key(sk-…)只会显示一次,拿到后立刻存进密钥管理工具或环境变量,因为它之后不会再显示第二次。新账号通常会自动获得一些试用额度,所以你可以先跑几个请求,不用急着绑卡。

同时记下网关的 base URL,形如 https://<你的网关地址>/v1。把这两个值放进环境变量,不要直接写进可能被提交到版本库的配置文件里:

export GATEWAY_BASE_URL="https://api.apiko.example/v1"
export GATEWAY_API_KEY="sk-..."

(api.apiko.example 只是占位地址,请替换成你实际部署的网关域名。)

第二步:把 OpenClaw 指向网关

这两个值具体填在哪里,取决于你用的 OpenClaw 版本和部署方式 —— 可能是配置文件,也可能是环境变量,或者是设置界面。不管是哪种形式,这两个值的结构是固定的:一个以 /v1 结尾的 base URL,一个 bearer token。

如果 OpenClaw 用的是配置文件,字段通常长这样:

provider:
  base_url: https://api.apiko.example/v1
  api_key: ${GATEWAY_API_KEY}
  model: gpt-5.1

如果它直接读环境变量(很多 OpenAI 兼容工具都是这样),常见约定是:

export OPENAI_BASE_URL="https://api.apiko.example/v1"
export OPENAI_API_KEY="$GATEWAY_API_KEY"

有些工具用的是自己的变量前缀而不是 OPENAI_*,具体名字要查 OpenClaw 的文档确认。但值本身不会变:还是网关的 base URL、网关的 key。

先脱离 OpenClaw,单独验证连通性

在 Agent 工具的界面里排查问题往往看不到真实的 HTTP 报错,所以建议先用一条 curl 确认网关本身能正常响应:

curl "$GATEWAY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.1",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

正常响应长得和标准 OpenAI chat completion 对象一样 —— choices[0].message.content 有内容,还有一个带 token 计数的 usage 块。如果这一步能跑通,那么 OpenClaw 里出现的任何失败都是配置层面的问题(变量名错了、base URL 路径不对、key 过期了),而不是网关本身有问题。如果这一步就跑不通,下面的错误码表能告诉你该改什么。

第三步:选一个模型 id

请求里的 model 字符串必须匹配网关实际提供的 id —— 不是"看起来应该能用"的名字。不要凭记忆或者照抄别的厂商文档里的模型名,直接从网关的 models 接口拉当前列表,这个接口返回的是你能调用的 id,以及实时的单 token 计费:

curl "$GATEWAY_BASE_URL/models" \
  -H "Authorization: Bearer $GATEWAY_API_KEY"

也可以直接在浏览器里打开 /models 浏览目录,按厂商和能力筛选,上面显示的价格和实际计费用的是同一份数据。把从这里拿到的 id 填进 OpenClaw 的 model 字段就行 —— 请求/响应结构、流式输出、可用字段的完整参考文档在 /docs。

常见错误和对应的解决办法

OpenClaw 接好之后,大部分失败都落在几个固定的 HTTP 状态码上。在怀疑是 OpenClaw 本身的 bug 之前,先对照下面这张表:

| 状态码 | 含义 | 处理方式 | |---|---|---| | 401 | key 缺失或无效 | 确认 Authorization: Bearer 请求头确实被发出去了 —— 有些工具在环境变量名不匹配时会悄悄丢掉这个头。同时检查 key 有没有被吊销。 | | 402 / 403 | 余额不足 | 账户余额不够支撑这次请求,去控制台充值后重试。 | | 404 | 模型或路径不存在 | model 字符串没有匹配到当前提供的任何 id —— 去 /models 重新核对。同时确认 base URL 路径以 /v1 结尾,调用的是 /chat/completions 而不是别的路径。 | | 429 | 触发限流 | 用指数退避重试。这通常是请求节奏问题,不是账户状态问题。 | | 5xx | 上游故障 | 网关会自动跨渠道重试。如果最终还是失败,这次请求不会被计费 —— 预扣的额度会自动退回。可以重试;如果持续失败,去状态页查一下。 |

如果 OpenClaw 只报一个笼统的"请求失败"、看不到具体状态码,打开 OpenClaw 的详细/调试日志(或者退回上面的 curl 测试)看真实的 HTTP 响应 —— 网关返回的报文里通常会指明具体是哪个字段出了问题。

流式响应

如果希望 OpenClaw 边生成边显示 token,要确认请求里带了 stream: true(base URL/key 配好之后 OpenClaw 通常会自动处理这个,但如果发现输出是一次性全部出现而不是逐字流出,值得检查一下)。加上 stream_options: {"include_usage": true} 会在最后一个 chunk 里拿到真实的 token 用量 —— 如果你想核对某次 OpenClaw 运行实际花了多少,这个字段很有用。

小结

这里讲的这套模式不是 OpenClaw 专属的 —— 任何 OpenAI 兼容的 Agent 工具接的都是同样的两个输入(base URL、key),排查问题的路径也是同样的(先用 curl 单独测试,再对照状态码表)。接好之后,换模型就是改一行字符串,而不是重新做一次集成。

新账号在注册时会自动获得试用额度,不需要绑卡就能先跑通上面这套流程、发出几个真实请求再决定要不要继续用。等你要规划大规模用量时,去 /pricing 查当前的按模型计费标准。