OpenClaw 接入 AI Gateway：完整配置与协议选择指南

本文面向第一次使用 Terminal、第一次配置 OpenClaw，或者需要把 OpenClaw 接入第三方 AI Gateway 的用户。

完成本文后，你将能够：

• 安装并初始化 OpenClaw；
• 安全输入 AI Gateway 的 Base URL 和 API Key；
• 查询自己的 API Key 可以看到的模型；
• 判断模型应使用 OpenAI Chat、OpenAI Responses 还是 Anthropic Messages；
• 把通过测试的模型写入 OpenClaw；
• 启动 Gateway，并用一条真实消息确认连接；
• 根据错误信息判断是网络、认证、模型路由还是 OpenClaw 配置问题。

本文以 macOS、zsh 和以下 AI Gateway 为例：

<https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1>

本文命令已按 OpenClaw

2026.7.1-2

--help

如果你的地址不同，只需替换 Base URL。不同 API Key 能看到的模型可能不同；模型 ID 必须从你自己的

/models

先看结论：模型厂商和请求协议是两件事

OpenClaw 不会根据模型名称自动选择协议。真正决定请求格式的是 OpenClaw provider 中的

api

本文使用三个容易识别的本地 provider 名称：

api

relay-chat

openai-completions

/chat/completions

relay-responses

openai-responses

/responses

relay-anthropic

anthropic-messages

/messages

这些 provider 名称只是 OpenClaw 本机配置名称，不是 AI Gateway 规定的名称，也不是模型厂商名称。

如果 OpenClaw 中已经存在其他 provider 名称（例如

my-relay

my-relay-claude

PROVIDER_ID

按模型厂商选择协议

下面的矩阵用于选择第一条测试路径，不代表某个厂商的所有版本都开放相同协议。具体模型必须以你的目录和对应

curl

relay-anthropic

relay-chat

relay-responses

relay-chat

relay-anthropic

relay-chat

relay-anthropic

厂商的原生 API 与 AI Gateway 暴露的兼容协议可能不同；例如同一个模型可以同时出现在 OpenAI 和 Anthropic 两个目录视图中，也可能只出现在其中一个视图。不要只根据模型前缀或厂商名称选择 provider。

最重要的规则是：

模型厂商 ≠ 请求协议 模型出现在目录中 ≠ 该模型已经可以调用 标准 curl 成功 ≠ OpenClaw 已经配置完成

你只需要为准备使用的协议配置 provider。只用 Claude 时可以只配置

relay-anthropic

relay-chat

0. 完整操作路线

第一次配置时，请按以下顺序操作：

1. 安装并初始化 OpenClaw 2. 输入 Base URL 和 API Key 3. 查询自己 API Key 的模型目录 4. 选择一个模型和一个目标协议 5. 用对应协议的 curl 取得最终文字 6. 只配置这个已经成功的 provider 7. 校验配置并启动 Gateway 8. 用 openclaw agent 发送真实消息 9. 需要时再添加其他模型或协议

完成第 8 步后，你已经具备基础文本对话能力。工具调用、图片、文件、结构化输出和其他高级能力的适用范围见第 12 节。

1. 准备信息

开始前准备三项内容。

1.1 Base URL

本示例使用：

<https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1>

该地址已经包含

/v1

<https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/v1>

1.2 API Key

请从 AI Gateway 后台创建或复制 API Key，并确认：

• API Key 没有过期；
• API Key 有模型调用权限；
• Base URL 和 API Key 属于同一个环境；
• 复制时没有多余空格或换行。

不要把真实 API Key 发到聊天、工单、截图、Git 仓库或公开网页。

1.3 Terminal

本文所有命令都在 macOS Terminal 中执行。

打开方式：按 Command + Space，输入

Terminal

你可能看到类似提示符：

user@Mac ~ %

不要复制提示符本身，只复制本文代码框中的命令。

2. 安装或确认 OpenClaw

2.1 检查基础工具

执行：

command -v curl command -v jq

如果两条命令都返回文件路径，可以继续。

如果没有

jq

brew install jq jq --version

2.2 检查 OpenClaw

执行：

command -v openclaw openclaw --version type -a openclaw

command -v

openclaw --version

type -a openclaw

2.3 没有安装时

macOS、Linux 或 WSL 可以使用 OpenClaw 官方安装脚本：

curl -fsSL --proto '=https' --tlsv1.2 \ https://openclaw.ai/install.sh | bash

安装完成后关闭 Terminal，重新打开，再执行：

openclaw --version

如果安装成功但仍提示

openclaw: command not found

node -v npm prefix -g echo "$PATH"

把

npm prefix -g

bin

3. 初始化 OpenClaw

3.1 已有配置

先执行：

openclaw config validate

如果看到：

Config valid: ~/.openclaw/openclaw.json

说明现有配置可以读取，直接进入第 4 节。

3.2 第一次使用

执行：

openclaw onboard

向导中建议：

1. 选择本机运行

   local

   local
   ；
2. 接受安全风险提示；
3. 模型认证可以先选择跳过，本文第 7 节会直接配置 AI Gateway；
4. 没有聊天频道时先跳过频道配置；
5. Gateway 选择安装为本机服务；
6. 搜索、技能和插件不确定时先跳过，完成基础连接后再配置。

向导完成后执行：

openclaw config validate openclaw agents list

正常情况下，配置校验通过，并且至少能看到默认 agent：

main

如果你之前在向导中创建过

custom

4. 在当前 Terminal 安全输入连接信息

在同一个 Terminal 中执行：

export RELAY_BASE_URL='https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1' RELAY_BASE_URL="${RELAY_BASE_URL%/}" read -s "RELAY_API_KEY?请粘贴 AI Gateway API Key，然后按回车：" echo

粘贴 API Key 时屏幕不显示字符是正常现象。

只检查变量是否存在，不显示 API Key：

if [ -n "$RELAY_API_KEY" ]; then echo 'API Key 已载入当前 Terminal' else echo 'API Key 为空，请重新输入' fi

正常返回：

API Key 已载入当前 Terminal

为了让重启后的后台 Gateway 也能读取令牌，把它保存到 OpenClaw 用户目录下的环境文件。该文件只保存在本机，并将权限限制为当前用户：

mkdir -p "$HOME/.openclaw" (umask 077; printf 'RELAY_API_KEY=%s\n' "$RELAY_API_KEY" > "$HOME/.openclaw/.env") chmod 600 "$HOME/.openclaw/.env"

后面的 provider 配置使用 SecretRef，不会把令牌明文写入

openclaw.json

~/.openclaw/.env

关闭 Terminal 后变量会消失。完成第 7 节之前，请继续使用当前窗口。

5. 检查网络并查询模型目录

5.1 先检查 OpenAI 风格连接

执行：

curl -sS -o /tmp/openclaw-gateway-models-openai.json \ --max-time 30 \ -w 'HTTP %{http_code}\n' \ "$RELAY_BASE_URL/models" \ -H "Authorization: Bearer $RELAY_API_KEY"

返回含义：

/v1

/v1

如果已经收到 200、401、403、404、429 或 5xx，说明域名能够访问，通常不是“必须开 VPN”才能解决的问题。只有域名解析失败、连接超时或网络策略拦截时，才需要检查代理或 VPN。

5.2 查看 OpenAI 视图

HTTP 200 后执行：

jq -r ' if (.data | type) == "array" then .data[].id else .error.message // .message // "没有读取到模型目录" end ' /tmp/openclaw-gateway-models-openai.json

这个列表用于选择 OpenAI Chat 或 OpenAI Responses 的候选模型。列表只表示当前 API Key 可以看到这些模型，接下来仍要测试具体端点。

5.3 查看 Anthropic 视图

只有准备使用 Anthropic Messages 或 Claude 时才需要执行：

curl -sS -o /tmp/openclaw-gateway-models-anthropic.json \ --max-time 30 \ -w 'HTTP %{http_code}\n' \ "$RELAY_BASE_URL/models" \ -H "x-api-key: $RELAY_API_KEY" \ -H 'anthropic-version: 2023-06-01' jq -r ' if (.data | type) == "array" then .data[].id else .error.message // .message // "没有读取到 Anthropic 模型目录" end ' /tmp/openclaw-gateway-models-anthropic.json

如果 OpenAI 视图和 Anthropic 视图不同，这是正常现象。请求头和协议上下文不同，AI Gateway 可以返回不同的模型目录。

5.4 模型 ID 必须原样复制

模型 ID 是 AI Gateway 的路由键。版本号、点号、连字符和厂商前缀都可能是 ID 的一部分。

不要：

• 根据网上的展示名称手写模型 ID；
• 删除模型 ID 中的厂商前缀；
• 把点号改成连字符；
• 因为同系列某个版本可用，就推断其他版本也可用。

如果目标模型不在自己的目录中，先确认 API Key 权限，不要继续强行配置。

6. 用对应协议验证目标模型

只需测试自己准备使用的协议。每个测试都必须同时满足：HTTP 200，并且响应中有最终文字。

6.1 OpenAI Chat Completions

从第 5.2 节的结果中复制一个完整模型 ID：

read "CHAT_MODEL_ID?请粘贴准备使用 Chat 协议的完整模型 ID："

执行：

curl -sS -o /tmp/openclaw-test-chat.json \ --max-time 60 \ -w 'HTTP %{http_code}\n' \ "$RELAY_BASE_URL/chat/completions" \ -H "Authorization: Bearer $RELAY_API_KEY" \ -H 'Content-Type: application/json' \ -d "$(jq -cn \ --arg model "$CHAT_MODEL_ID" \ '{ model: $model, max_tokens: 512, messages: [{role: "user", content: "请只回复：Chat连接成功"}] }')" jq -r ' .choices[0].message.content // .error.message // .message // "HTTP 已返回，但没有找到最终文字" ' /tmp/openclaw-test-chat.json

成功时应看到：

HTTP 200 Chat连接成功

如果成功，可以使用第 7.2 节的

relay-chat

6.2 OpenAI Responses

从第 5.2 节的结果中复制一个完整模型 ID：

read "RESPONSES_MODEL_ID?请粘贴准备使用 Responses 协议的完整模型 ID："

执行：

curl -sS -o /tmp/openclaw-test-responses.json \ --max-time 60 \ -w 'HTTP %{http_code}\n' \ "$RELAY_BASE_URL/responses" \ -H "Authorization: Bearer $RELAY_API_KEY" \ -H 'Content-Type: application/json' \ -d "$(jq -cn \ --arg model "$RESPONSES_MODEL_ID" \ '{ model: $model, input: "请只回复：Responses连接成功", max_output_tokens: 512 }')" jq -r ' ([.output[]?.content[]? | select(.type == "output_text" or .type == "text") | .text] | join("\n")) as $text | if ($text | length) > 0 then $text else .error.message // .message // "HTTP 已返回，但没有找到最终文字" end ' /tmp/openclaw-test-responses.json

成功时应看到：

HTTP 200 Responses连接成功

如果成功，可以使用第 7.3 节的

relay-responses

6.3 Anthropic Messages

从第 5.3 节的结果中复制一个完整模型 ID：

read "ANTHROPIC_MODEL_ID?请粘贴准备使用 Anthropic 协议的完整模型 ID："

执行：

curl -sS -o /tmp/openclaw-test-anthropic.json \ --max-time 60 \ -w 'HTTP %{http_code}\n' \ "$RELAY_BASE_URL/messages" \ -H "x-api-key: $RELAY_API_KEY" \ -H 'anthropic-version: 2023-06-01' \ -H 'Content-Type: application/json' \ -d "$(jq -cn \ --arg model "$ANTHROPIC_MODEL_ID" \ '{ model: $model, max_tokens: 1024, messages: [{role: "user", content: "请只回复：Anthropic连接成功"}] }')" jq -r ' ([.content[]? | select(.type == "text") | .text] | join("\n")) as $text | if ($text | length) > 0 then $text else .error.message // .message // "HTTP 已返回，但没有找到最终文字" end ' /tmp/openclaw-test-anthropic.json

成功时应看到：

HTTP 200 Anthropic连接成功

如果成功，可以使用第 7.4 节的

relay-anthropic

6.4 HTTP 200 但没有最终文字

部分推理模型可能先生成 thinking 或 reasoning 内容。输出预算太小时，请求可能返回 HTTP 200，但没有最终文本。

可以把对应请求中的：

max_tokens: 512 max_output_tokens: 512

提高到 1024 或 4096 后再测试。

如果提高后仍没有最终文字，请查看完整 JSON，确认响应结构是否与当前协议一致。

7. 把通过测试的模型写入 OpenClaw

本节提供三个独立方案。请选择刚才 curl 成功的一个方案完成首次配置，不要一次性复制三个方案。

7.1 先备份配置

执行：

CONFIG_FILE="$HOME/.openclaw/openclaw.json" if [ -f "$CONFIG_FILE" ]; then cp "$CONFIG_FILE" \ "$CONFIG_FILE.backup-$(date +%Y%m%d-%H%M%S)" echo '已创建 OpenClaw 配置备份' else echo '当前没有配置文件，OpenClaw 将创建新配置' fi

7.2 方案 A：配置 OpenAI Chat

只有第 6.1 节成功时才执行：

CHAT_PROVIDER=$(jq -cn \ --arg base "$RELAY_BASE_URL" \ --arg model "$CHAT_MODEL_ID" \ '{ baseUrl: $base, apiKey: {source: "env", provider: "default", id: "RELAY_API_KEY"}, api: "openai-completions", models: [{id: $model, name: $model}] }') openclaw config set \ models.providers.relay-chat \ "$CHAT_PROVIDER" \ --strict-json CHAT_MODEL_REF="relay-chat/$CHAT_MODEL_ID" CHAT_CATALOG_ENTRY=$(jq -cn \ --arg ref "$CHAT_MODEL_REF" \ '{($ref): {}}') openclaw config set \ agents.defaults.models \ "$CHAT_CATALOG_ENTRY" \ --strict-json \ --merge openclaw models set "$CHAT_MODEL_REF" openclaw config validate

7.3 方案 B：配置 OpenAI Responses

只有第 6.2 节成功时才执行：

RESPONSES_PROVIDER=$(jq -cn \ --arg base "$RELAY_BASE_URL" \ --arg model "$RESPONSES_MODEL_ID" \ '{ baseUrl: $base, apiKey: {source: "env", provider: "default", id: "RELAY_API_KEY"}, api: "openai-responses", models: [{id: $model, name: $model}] }') openclaw config set \ models.providers.relay-responses \ "$RESPONSES_PROVIDER" \ --strict-json RESPONSES_MODEL_REF="relay-responses/$RESPONSES_MODEL_ID" RESPONSES_CATALOG_ENTRY=$(jq -cn \ --arg ref "$RESPONSES_MODEL_REF" \ '{($ref): {}}') openclaw config set \ agents.defaults.models \ "$RESPONSES_CATALOG_ENTRY" \ --strict-json \ --merge openclaw models set "$RESPONSES_MODEL_REF" openclaw config validate

7.4 方案 C：配置 Anthropic Messages

只有第 6.3 节成功时才执行：

ANTHROPIC_PROVIDER=$(jq -cn \ --arg base "$RELAY_BASE_URL" \ --arg model "$ANTHROPIC_MODEL_ID" \ '{ baseUrl: $base, apiKey: {source: "env", provider: "default", id: "RELAY_API_KEY"}, api: "anthropic-messages", models: [{id: $model, name: $model}] }') openclaw config set \ models.providers.relay-anthropic \ "$ANTHROPIC_PROVIDER" \ --strict-json ANTHROPIC_MODEL_REF="relay-anthropic/$ANTHROPIC_MODEL_ID" ANTHROPIC_CATALOG_ENTRY=$(jq -cn \ --arg ref "$ANTHROPIC_MODEL_REF" \ '{($ref): {}}') openclaw config set \ agents.defaults.models \ "$ANTHROPIC_CATALOG_ENTRY" \ --strict-json \ --merge openclaw models set "$ANTHROPIC_MODEL_REF" openclaw config validate

7.5 正常结果

最后必须看到：

Config valid: ~/.openclaw/openclaw.json

上述命令只修改选中的 provider，并使用

--merge

openclaw models set

--model

本文没有给所有模型统一写入

contextWindow

maxTokens

reasoning

8. 启动 Gateway 并检查模型

8.1 重启 Gateway

执行：

openclaw gateway restart

如果提示 Gateway 服务没有安装：

openclaw gateway install openclaw gateway start

8.2 检查运行状态

执行：

openclaw gateway status

重点查看：

Runtime: running Connectivity probe: ok

如果版本信息中 CLI 和 Gateway 不一致，先重启 Gateway；仍不一致时检查

type -a openclaw

8.3 查看刚配置的 provider

根据实际选择，只执行对应的一条命令。

配置了 OpenAI Chat：

openclaw models list --provider relay-chat --plain

配置了 OpenAI Responses：

openclaw models list --provider relay-responses --plain

配置了 Anthropic Messages：

openclaw models list --provider relay-anthropic --plain

你应该看到类似结构：

relay-chat/<从目录复制的模型 ID> relay-responses/<从目录复制的模型 ID> relay-anthropic/<从目录复制的模型 ID>

尖括号中的文字只是说明，不要原样输入。

查看默认模型：

openclaw models status --plain

9. 用 OpenClaw 发送第一条消息

9.1 测试默认模型

执行：

openclaw agent \ --agent main \ --message '请只回复：OpenClaw连接成功'

正常最终文字：

OpenClaw连接成功

成功标准是：命令最终返回模型文字，而不是仅仅看到 Gateway 已启动或模型出现在列表中。

9.2 测试指定模型

如果要绕过默认模型，使用完整的 OpenClaw 模型引用：

openclaw agent \ --agent main \ --model "relay-chat/$CHAT_MODEL_ID" \ --message '请只回复：指定模型连接成功'

如果配置的是 Responses 或 Anthropic，把

--model

relay-responses/<模型 ID> relay-anthropic/<模型 ID>

9.3 为什么必须写

--agent main

--agent main

如果只执行：

openclaw agent --message '你好'

可能出现：

Error: No target session selected.

加入

--agent main

9.4 插件警告不一定是模型错误

如果回复前出现：

plugins.allow is empty discovered non-bundled plugins may auto-load

这是插件信任提示。只要最后返回了预期模型文字，AI Gateway 连接已经成功。插件是否启用应根据插件来源单独处理。

10. 添加第二种协议或更多模型

10.1 添加第二种协议

例如已经配置

relay-chat

1. 执行第 5.3 节查询 Anthropic 目录；
2. 执行第 6.3 节测试目标模型；
3. 执行第 7.4 节添加

   relay-anthropic

   relay-anthropic
   ；
4. 重启 Gateway；
5. 使用

   --model relay-anthropic/<模型 ID>

   --model relay-anthropic/<模型 ID>
   发送测试消息。

添加第二个 provider 不需要重新运行

openclaw onboard

10.2 向已有 provider 添加模型

先用第 6 节的对应协议测试新模型。成功后设置：

PROVIDER_ID='relay-chat' read "NEW_MODEL_ID?请粘贴已经通过同协议测试的新模型 ID："

PROVIDER_ID

PROVIDER_ID

relay-chat

relay-responses

relay-anthropic

执行：

CURRENT_PROVIDER_MODELS=$(openclaw config get \ "models.providers.$PROVIDER_ID.models") UPDATED_PROVIDER_MODELS=$(printf '%s' "$CURRENT_PROVIDER_MODELS" | jq \ --arg id "$NEW_MODEL_ID" \ '. + [{id: $id, name: $id}] | unique_by(.id)') openclaw config set \ "models.providers.$PROVIDER_ID.models" \ "$UPDATED_PROVIDER_MODELS" \ --strict-json \ --replace NEW_MODEL_REF="$PROVIDER_ID/$NEW_MODEL_ID" NEW_CATALOG_ENTRY=$(jq -cn \ --arg ref "$NEW_MODEL_REF" \ '{($ref): {}}') openclaw config set \ agents.defaults.models \ "$NEW_CATALOG_ENTRY" \ --strict-json \ --merge openclaw config validate openclaw gateway restart

测试新模型：

openclaw agent \ --agent main \ --model "$NEW_MODEL_REF" \ --message '请只回复：新模型连接成功'

需要把它设为默认模型时执行：

openclaw models set "$NEW_MODEL_REF"

11. 请求协议和配置边界

11.1 三种协议不能混用

/chat/completions

/responses

/messages

Authorization: Bearer

Authorization: Bearer

x-api-key

anthropic-version

messages

input

messages

system

max_tokens

max_output_tokens

max_tokens

choices[].message.content

output[].content[].text

content[]

type=text

api

openai-completions

openai-responses

anthropic-messages

只修改 URL 或模型名称，不能把一种协议变成另一种协议。端点、认证头、请求体、流式事件和工具调用结构必须一起匹配。

11.2 模型 ID 前缀不会切换协议

假设模型 ID 以

anthropic/

relay-chat/anthropic/<模型名称>

仍然会使用 OpenAI Chat，因为本地 provider 是

relay-chat

只有：

relay-anthropic/anthropic/<模型名称>

才会按本文配置使用 Anthropic Messages。

同理，

openai/

deepseek/

qwen/

11.3 同一个模型可能支持多个协议

如果同一个模型分别通过 Chat 和 Anthropic Messages 测试，可以在两个 provider 中各添加一次：

relay-chat/<同一个模型 ID> relay-anthropic/<同一个模型 ID>

这是两个不同的 OpenClaw 模型引用。它们使用不同请求格式，错误和能力表现也可能不同。

11.4 一个协议成功不能推断另一个协议

下面这些情况都可能出现：

Chat 成功，Responses 失败 Responses 成功，Chat 失败 Anthropic 成功，OpenAI 协议失败 同一模型在两个协议成功，但工具调用表现不同

因此，每个 provider 都必须先执行对应 curl，再执行 OpenClaw 实际消息测试。

11.5 目录、curl 和 OpenClaw 分别说明什么

/models

openclaw models list

openclaw agent

11.6 不要猜上下文窗口和输出上限

contextWindow

contextTokens

maxTokens

reasoning

本文的最小 provider 配置只写入：

id name

只有在 AI Gateway 或模型文档明确提供数值，并且经过实际验证后，才应增加其他字段。

12. 配置完成后可以使用哪些能力

完成第 9 节表示基础文本链路已经成功：你可以向 OpenClaw 发送文字，并收到模型的最终文字回复。

以下能力是否可用，还取决于模型、请求协议、AI Gateway 和 OpenClaw provider 的共同实现：

• 流式输出和中途取消；
• 工具调用以及多轮工具结果回传；
• JSON Schema 或结构化输出；
• 图片、PDF、音频和其他多模态输入；
• Prompt Cache 或其他缓存能力；
• Web Search；
• Extended Thinking、reasoning effort 或其他推理参数；
• 超长上下文；
• 自动故障转移和 fallback 模型。

如果你只需要普通文本对话，第 9 节成功后即可开始使用。如果需要上述能力，请对准备使用的模型和协议分别进行专项测试。

OpenClaw 的 agent 还可能拥有读取文件、运行命令或调用工具的权限。启用此类能力前，请同时检查 agent、workspace、sandbox、工具权限和聊天频道访问控制；模型连接成功不等于应该开放所有本机权限。

13. 常见问题排查

13.1 API Key 粘贴时没有字符

正常。

read -s

13.2

expected object, received string

expected object, received string

这通常表示把省略号或普通字符串写进了 provider 对象。例如：

openclaw config set models.providers.relay-anthropic ...

...

13.3

No target session selected

No target session selected

给 agent 命令加入：

--agent main

如果没有

main

openclaw agents list

并把

main

13.4

Model ... is not allowed

Model ... is not allowed

或

model not found

model not found

按顺序检查：

1. 执行

   openclaw models list --provider <provider> --plain

   openclaw models list --provider <provider> --plain
   ；
2. 确认使用完整 OpenClaw 引用：

   provider/AI-Gateway-模型-ID

   provider/AI-Gateway-模型-ID
   ；
3. 确认模型已经加入

   models.providers.<provider>.models

   models.providers.<provider>.models
   ；
4. 确认模型已经使用

   --merge

   --merge
   加入

   agents.defaults.models

   agents.defaults.models
   ；
5. 执行

   openclaw config validate

   openclaw config validate
   ；
6. 重启 Gateway 后再试。

13.5 HTTP 401 或 403

常见原因：

• API Key 错误、失效或没有权限；
• Chat/Responses 请求错误地使用了

  x-api-key

  x-api-key
  ；
• Anthropic 请求遗漏

  x-api-key

  x-api-key
  或

  anthropic-version

  anthropic-version
  ；
• Base URL 和 API Key 不属于同一个环境。

先回到第 5 节重新检查认证头和目录请求。

13.6

No upstream candidates

No upstream candidates

表示当前“模型 ID + 协议 + API Key/租户”组合没有可用上游。常见原因：

• 模型 ID 写错；
• provider 使用了错误协议；
• API Key 没有对应模型权限；
• AI Gateway 没有为该协议配置模型路由；
• 上游暂时下线。

处理顺序：重新查询对应目录，原样复制模型 ID，再用第 6 节的同协议 curl 测试。

13.7 HTTP 502 或 503

Upstream failed

Upstream failed

请求已经到达 AI Gateway，但上游模型调用失败。稍后重试；如果持续失败，请保存以下信息：

• 发生时间和时区；
• 完整模型 ID；
• 请求协议和路径；
• HTTP 状态码；
• 删除 API Key 后的错误 JSON。

不要通过修改 OpenClaw provider 名称来解决上游 5xx。

13.8 HTTP 200 但没有最终文字

提高输出预算，并检查当前协议的正确文本字段：

Chat → choices[].message.content Responses → output[].content[].text Anthropic → content[] 中 type=text

如果 JSON 中只有 thinking 或 reasoning 内容，说明输出预算可能被推理过程占满。

13.9 curl 成功，但 OpenClaw 失败

执行：

openclaw config validate openclaw gateway status openclaw models status --plain openclaw agents list

重点检查：

• provider 的

  api

  api
  是否与 curl 协议一致；
• provider 的

  baseUrl

  baseUrl
  是否与 curl 使用的地址一致；
• 完整模型引用是否包含正确的本地 provider；
• Gateway 是否在修改配置后重启；

• --agent

  --agent
  是否使用实际 agent ID。

13.10 Gateway 不是

running

running

执行：

openclaw gateway install openclaw gateway start openclaw gateway status

仍失败时执行：

openclaw config validate openclaw doctor

13.11 CLI 和 Gateway 版本不同

执行：

type -a openclaw openclaw --version openclaw gateway status

如果系统安装了多个 OpenClaw，先统一 PATH，再重新安装或重启 Gateway 服务。

13.12 恢复配置备份

查看备份：

ls -lt "$HOME/.openclaw"/openclaw.json.backup-* 2>/dev/null \ | sed -n '1,5p'

复制准确的备份文件名后恢复：

cp "$HOME/.openclaw/openclaw.json.backup-实际时间" \ "$HOME/.openclaw/openclaw.json" openclaw config validate openclaw gateway restart

不要原样输入“实际时间”，应替换为上一个命令列出的文件名。

13.13 重启后提示认证失败

如果当前 Terminal 中的 curl 可以成功，但重启 Gateway 后 OpenClaw 提示 401、403 或 API Key 缺失，通常是后台服务没有读取用户级环境文件。按顺序检查：

1. 确认文件存在且权限正确：

ls -l "$HOME/.openclaw/.env"

应看到文件属于当前用户，权限不应允许其他用户读取。

2. 重新写入环境文件（不会在屏幕显示令牌）：

read -s "RELAY_API_KEY?请重新粘贴 AI Gateway API Key，然后按回车：" echo (umask 077; printf 'RELAY_API_KEY=%s\n' "$RELAY_API_KEY" > "$HOME/.openclaw/.env") chmod 600 "$HOME/.openclaw/.env"

3. 重启服务并重新检查：

openclaw gateway restart openclaw gateway status

如果仍然失败，执行：

openclaw doctor openclaw gateway diagnostics

检查结果中不能包含 API Key；向服务支持提交信息前再次脱敏。也可以执行

openclaw gateway --help

14. API Key 和本机安全

OpenClaw 配置文件通常位于：

~/.openclaw/openclaw.json

本文的 provider 配置使用 SecretRef，

openclaw.json

~/.openclaw/.env

chmod 600 "$HOME/.openclaw/openclaw.json" chmod 600 "$HOME/.openclaw/.env" find "$HOME/.openclaw" -maxdepth 1 \ -name 'openclaw.json.backup-*' \ -exec chmod 600 {} \;

历史配置备份可能包含旧 API Key，因此需要同样保护。

不要：

• 上传

  openclaw.json

  openclaw.json
  ；
• 对完整配置截图；
• 执行

  echo "$RELAY_API_KEY"

  echo "$RELAY_API_KEY"
  ；
• 把完整请求头粘贴到公开工单；
• 把 API Key 写入项目仓库；
• 与他人共用长期有效的高权限 API Key。

配置完成后，可以清除当前 Terminal 中的临时变量：

unset RELAY_API_KEY unset RELAY_BASE_URL unset CHAT_MODEL_ID unset RESPONSES_MODEL_ID unset ANTHROPIC_MODEL_ID

如果 API Key 已经出现在公开截图、聊天或命令输出中，请立即在 AI Gateway 后台撤销并重新创建。

OpenClaw Gateway 默认建议绑定本机 loopback。除非明确需要远程访问并已经配置认证、防火墙和访问控制，否则不要把 Gateway 直接暴露到局域网或公网。

15. 完成检查清单

完成配置后逐项确认：

[ ] curl 和 jq 可以执行 [ ] openclaw --version 返回版本 [ ] openclaw config validate 返回 Config valid [ ] Base URL 正确，/v1 没有重复 [ ] API Key 已安全输入，没有公开 [ ] 已查询目标协议对应的模型目录 [ ] 模型 ID 从自己的目录原样复制 [ ] 目标协议 curl 返回 HTTP 200 [ ] curl 响应中存在最终文字 [ ] OpenClaw provider 的 api 与 curl 协议一致 [ ] agents.defaults.models 使用 --merge 添加模型 [ ] openclaw gateway status 显示 Runtime: running [ ] Connectivity probe 显示 ok [ ] openclaw models list 能看到完整 provider/model 引用 [ ] openclaw agent --agent main 返回最终文字 [ ] 需要高级能力时已经逐项测试 [ ] openclaw.json 文件权限已经限制 [ ] ~/.openclaw/.env 和配置备份的文件权限已经限制

全部完成后，OpenClaw 已经通过 AI Gateway 接入成功。

如果

/models

api

16. 相关资料

• OpenClaw 安装说明
• OpenClaw Model Providers
• OpenClaw Models CLI
• OpenClaw Agent CLI
• OpenClaw Gateway CLI

OpenClaw 和 AI Gateway 都可能升级。遇到命令参数差异时，先执行：

openclaw --version openclaw config set --help openclaw agent --help openclaw gateway --help

以当前安装版本显示的参数为准。