chore(i18n): refresh zh-CN translations

2026-04-07 15:03:07 +00:00 · 2026-04-07 15:03:07 +00:00 · efe97c94f2
commit efe97c94f2
parent 1ded8e6d0d
6 changed files with 1023 additions and 794 deletions
--- a/docs/zh-CN/gateway/configuration-reference.md
+++ b/docs/zh-CN/gateway/configuration-reference.md
--- a/docs/zh-CN/gateway/local-models.md
+++ b/docs/zh-CN/gateway/local-models.md
@ -1,28 +1,28 @@
 ---
 read_when:
-    - 你想从自己的 GPU 服务器提供模型服务
-    - 你正在接入 LM Studio 或 OpenAI 兼容代理
-    - 你需要最安全的本地模型使用指导
+    - 你想从你自己的 GPU 主机提供模型
+    - 你正在连接 LM Studio 或兼容 OpenAI 的代理
+    - 你需要最安全的本地模型指导
 summary: 在本地 LLM 上运行 OpenClaw（LM Studio、vLLM、LiteLLM、自定义 OpenAI 端点）
 title: 本地模型
 x-i18n:
-    generated_at: "2026-04-05T08:23:44Z"
+    generated_at: "2026-04-07T14:57:30Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 3b99c8fb57f65c0b765fc75bd36933221b5aeb94c4a3f3428f92640ae064f8b6
+    source_hash: d619d72b0e06914ebacb7e9f38b746caf1b9ce8908c9c6638c3acdddbaa025e8
    source_path: gateway/local-models.md
    workflow: 15
 ---

 # 本地模型

-本地部署是可行的，但 OpenClaw 需要大上下文窗口以及对 prompt injection 的强防护。小显存卡会截断上下文，并削弱安全性。目标尽量拉高：**至少 2 台满配 Mac Studio，或同等 GPU 设备（约 3 万美元以上）**。单张 **24 GB** GPU 只适合更轻量的提示词，并且延迟更高。请使用**你能运行的最大 / 完整尺寸模型变体**；激进量化或 “small” 检查点会提高 prompt injection 风险（参见 [Security](/gateway/security)）。
+本地部署是可行的，但 OpenClaw 需要大上下文窗口以及对提示注入的强防护。小显卡会截断上下文并削弱安全性。尽量配置更高：**≥2 台满配 Mac Studio 或同等 GPU 主机（约 3 万美元以上）**。单张 **24 GB** GPU 只适用于较轻的提示词，而且延迟更高。使用**你能运行的最大 / 完整尺寸模型变体**；激进量化或“小型”检查点会提高提示注入风险（参见[安全](/zh-CN/gateway/security)）。

-如果你想要摩擦最小的本地部署方式，请从 [Ollama](/providers/ollama) 和 `openclaw onboard` 开始。本页是针对更高端本地栈和自定义 OpenAI 兼容本地服务器的偏好型指南。
+如果你想要最低摩擦的本地配置，先从 [Ollama](/zh-CN/providers/ollama) 和 `openclaw onboard` 开始。本页是面向更高端本地栈和自定义兼容 OpenAI 的本地服务器的推荐指南。

 ## 推荐：LM Studio + 大型本地模型（Responses API）

-这是当前最推荐的本地方案。在 LM Studio 中加载一个大型模型（例如完整尺寸的 Qwen、DeepSeek 或 Llama 构建），启用本地服务器（默认 `http://127.0.0.1:1234`），并使用 Responses API 将推理过程与最终文本分离。
+这是当前最推荐的本地方案。在 LM Studio 中加载一个大型模型（例如完整尺寸的 Qwen、DeepSeek 或 Llama 构建），启用本地服务器（默认 `http://127.0.0.1:1234`），并使用 Responses API 将推理内容与最终文本分离。

 ```json5
 {
@ -62,15 +62,15 @@ x-i18n:
 **设置清单**

 - 安装 LM Studio：[https://lmstudio.ai](https://lmstudio.ai)
- 在 LM Studio 中，下载**可用的最大模型构建**（避免 “small”/重度量化变体），启动服务器，并确认 `http://127.0.0.1:1234/v1/models` 能列出该模型。
+- 在 LM Studio 中，下载**可用的最大模型构建**（避免“小型”/重度量化变体），启动服务器，并确认 `http://127.0.0.1:1234/v1/models` 已列出该模型。
 - 将 `my-local-model` 替换为 LM Studio 中显示的实际模型 ID。
 - 保持模型处于已加载状态；冷加载会增加启动延迟。
- 如果你的 LM Studio 构建不同，请调整 `contextWindow`/`maxTokens`。
- 对于 WhatsApp，请坚持使用 Responses API，这样只会发送最终文本。
+- 如果你的 LM Studio 构建不同，请调整 `contextWindow` / `maxTokens`。
+- 对于 WhatsApp，坚持使用 Responses API，这样只会发送最终文本。

-即使你在本地运行模型，也请保留托管模型配置；使用 `models.mode: "merge"`，以便在需要时仍可使用回退模型。
+即使在本地运行，也请保留托管模型配置；使用 `models.mode: "merge"`，这样回退模型仍然可用。

-### 混合配置：托管主模型，本地回退
+### 混合配置：托管模型为主，本地模型回退

 ```json5
 {
@ -111,18 +111,18 @@ x-i18n:
 }
 ```

-### 本地优先，并保留托管安全网
+### 本地优先，托管模型作安全兜底

-交换主模型和回退模型的顺序；保留相同的 providers 配置块和 `models.mode: "merge"`，这样在本地机器不可用时，你仍可以回退到 Sonnet 或 Opus。
+交换 primary 和 fallback 的顺序；保留相同的 providers 配置块以及 `models.mode: "merge"`，这样当本地主机不可用时，你仍然可以回退到 Sonnet 或 Opus。

 ### 区域托管 / 数据路由

- 托管版 MiniMax/Kimi/GLM 变体也存在于 OpenRouter 上，并提供区域固定端点（例如美国托管）。你可以在那里选择区域变体，以便让流量保持在你选择的司法辖区内，同时仍通过 `models.mode: "merge"` 使用 Anthropic/OpenAI 回退。
- 纯本地仍然是隐私最强的路径；当你需要提供商功能但又希望控制数据流时，托管区域路由是折中方案。
+- 托管版的 MiniMax / Kimi / GLM 变体也可通过 OpenRouter 的区域固定端点提供（例如托管在美国的端点）。你可以在那里选择区域变体，使流量保留在你指定的司法辖区内，同时仍然使用 `models.mode: "merge"` 作为 Anthropic / OpenAI 的回退。
+- 纯本地仍然是隐私性最强的方案；当你需要提供商功能，但又希望控制数据流向时，区域托管路由是折中方案。

-## 其他 OpenAI 兼容本地代理
+## 其他兼容 OpenAI 的本地代理

-如果 vLLM、LiteLLM、OAI-proxy 或自定义 Gateway 网关暴露的是 OpenAI 风格的 `/v1` 端点，它们也可以使用。将上面的 provider 配置块替换为你的端点和模型 ID：
+只要 vLLM、LiteLLM、OAI-proxy 或自定义 Gateway 网关 暴露的是兼容 OpenAI 风格的 `/v1` 端点，就可以使用。将上面的 provider 配置块替换为你的端点和模型 ID：

 ```json5
 {
@ -150,20 +150,41 @@ x-i18n:
 }
 ```

-请保留 `models.mode: "merge"`，这样托管模型仍可作为回退使用。
+保留 `models.mode: "merge"`，这样托管模型仍然可以作为回退使用。

-关于本地/代理 `/v1` 后端的行为说明：
+关于本地 / 代理 `/v1` 后端的行为说明：

- OpenClaw 会将这些后端视为代理风格的 OpenAI 兼容路由，而不是原生
+- OpenClaw 将这些视为代理风格的兼容 OpenAI 路由，而不是原生
  OpenAI 端点
- 这里不会应用仅适用于原生 OpenAI 的请求塑形：没有
-  `service_tier`，没有 Responses `store`，没有 OpenAI reasoning 兼容负载
-  塑形，也没有 prompt-cache 提示
- 不会在这些自定义代理 URL 上注入隐藏的 OpenClaw 归属头（`originator`、`version`、`User-Agent`）
+- 仅适用于原生 OpenAI 的请求整形不会在这里生效：没有
+  `service_tier`，没有 Responses `store`，没有 OpenAI 推理兼容负载
+  整形，也没有提示缓存提示
+- 隐藏的 OpenClaw 归因头（`originator`、`version`、`User-Agent`）
+  不会注入到这些自定义代理 URL 上
+
+对于更严格的兼容 OpenAI 后端的兼容性说明：
+
+- 某些服务器在 Chat Completions 中只接受字符串类型的 `messages[].content`，而不接受
+  结构化的内容片段数组。对于这类端点，请设置
+  `models.providers.<provider>.models[].compat.requiresStringContent: true`。
+- 某些更小型或更严格的本地后端无法稳定处理 OpenClaw 完整的
+  智能体运行时提示结构，尤其是在包含工具 schema 时。如果该
+  后端可以处理很小的直接 `/v1/chat/completions` 调用，但在正常
+  OpenClaw 智能体轮次中失败，请先尝试设置
+  `models.providers.<provider>.models[].compat.supportsTools: false`。
+- 如果后端仅在更大的 OpenClaw 运行中仍然失败，剩余问题通常
+  是上游模型 / 服务器容量不足，或后端自身的 bug，而不是 OpenClaw 的
+  传输层问题。

 ## 故障排除

- Gateway 网关能访问代理吗？`curl http://127.0.0.1:1234/v1/models`
- LM Studio 模型未加载？请重新加载；冷启动是常见的“卡住”原因。
- 上下文错误？降低 `contextWindow`，或提高服务器限制。
- 安全性：本地模型会跳过提供商侧过滤；请保持智能体范围狭窄，并启用 Compaction，以限制 prompt injection 的影响半径。
+- Gateway 网关 能连接到代理吗？`curl http://127.0.0.1:1234/v1/models`。
+- LM Studio 模型被卸载了？重新加载；冷启动是常见的“卡住”原因。
+- 上下文报错？降低 `contextWindow` 或提高你的服务器限制。
+- 兼容 OpenAI 的服务器返回 `messages[].content ... expected a string`？
+  在该模型条目上添加 `compat.requiresStringContent: true`。
+- 直接的小型 `/v1/chat/completions` 调用可以工作，但 `openclaw infer model run`
+  在 Gemma 或其他本地模型上失败？先使用
+  `compat.supportsTools: false` 禁用工具 schema，然后重新测试。如果服务器仍然只在
+  更大的 OpenClaw 提示上崩溃，请将其视为上游服务器 / 模型限制。
+- 安全性：本地模型会跳过提供商侧过滤；请保持智能体范围收窄，并启用压缩，以限制提示注入的影响范围。
--- a/docs/zh-CN/gateway/troubleshooting.md
+++ b/docs/zh-CN/gateway/troubleshooting.md
@ -1,14 +1,14 @@
 ---
 read_when:
-    - 故障排除中心将你引导到这里以进行更深入的诊断
-    - 你需要按症状组织且带有精确命令的稳定操作手册章节
-summary: 针对 Gateway 网关、渠道、自动化、节点和浏览器的深度故障排除操作手册
+    - 故障排除中心将你引导到这里，以便进行更深入的诊断
+    - 你需要按症状划分且带有精确命令的稳定操作手册章节
+summary: 关于 Gateway 网关、渠道、自动化、节点和浏览器的深度故障排除操作手册
 title: 故障排除
 x-i18n:
-    generated_at: "2026-04-06T15:28:55Z"
+    generated_at: "2026-04-07T14:58:07Z"
    model: gpt-5.4
    provider: openai
-    source_hash: e0202e8858310a0bfc1c994cd37b01c3b2d6c73c8a74740094e92dc3c4c36729
+    source_hash: 02c9537845248db0c9d315bf581338a93215fe6fe3688ed96c7105cbb19fe6ba
    source_path: gateway/troubleshooting.md
    workflow: 15
 ---
@ -16,7 +16,7 @@ x-i18n:
 # Gateway 网关故障排除

 本页是深度操作手册。
-如果你想先使用快速分诊流程，请先从 [/help/troubleshooting](/zh-CN/help/troubleshooting) 开始。
+如果你想先使用快速分诊流程，请从 [/help/troubleshooting](/zh-CN/help/troubleshooting) 开始。

 ## 命令阶梯

@ -33,12 +33,12 @@ openclaw channels status --probe
 预期的健康信号：

 - `openclaw gateway status` 显示 `Runtime: running` 和 `RPC probe: ok`。
- `openclaw doctor` 报告没有阻塞性的配置/服务问题。
- `openclaw channels status --probe` 显示每个账号的实时传输状态，并在支持的情况下显示探测/审计结果，例如 `works` 或 `audit ok`。
+- `openclaw doctor` 报告没有阻塞性的配置或服务问题。
+- `openclaw channels status --probe` 显示每个账号的实时传输状态，并且在支持的情况下显示探测或审计结果，例如 `works` 或 `audit ok`。

-## Anthropic 429：长上下文需要额外用量权限
+## Anthropic 429：长上下文请求需要额外使用额度

-当日志/错误中包含以下内容时，请使用本节：
+当日志或错误中包含以下内容时使用本节：
 `HTTP 429: rate_limit_error: Extra usage is required for long context requests`。

 ```bash
@ -49,15 +49,15 @@ openclaw config get agents.defaults.models

 检查以下内容：

- 选定的 Anthropic Opus/Sonnet 模型设置了 `params.context1m: true`。
- 当前的 Anthropic 凭证没有长上下文用量资格。
- 请求只会在需要走 1M beta 路径的长会话/模型运行中失败。
+- 所选的 Anthropic Opus/Sonnet 模型启用了 `params.context1m: true`。
+- 当前的 Anthropic 凭证不具备长上下文使用资格。
+- 请求仅在需要 1M beta 路径的长会话或模型运行中失败。

 修复选项：

-1. 为该模型禁用 `context1m`，回退到普通上下文窗口。
-2. 使用有资格发起长上下文请求的 Anthropic 凭证，或切换为 Anthropic API key。
-3. 配置回退模型，以便在 Anthropic 长上下文请求被拒绝时，运行仍可继续。
+1. 为该模型禁用 `context1m`，以回退到普通上下文窗口。
+2. 使用具备长上下文请求资格的 Anthropic 凭证，或切换为 Anthropic API 密钥。
+3. 配置回退模型，以便在 Anthropic 长上下文请求被拒绝时继续运行。

 相关内容：

@ -65,9 +65,51 @@ openclaw config get agents.defaults.models
 - [/reference/token-use](/zh-CN/reference/token-use)
 - [/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/zh-CN/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)

+## 本地 OpenAI 兼容后端可通过直接探测，但智能体运行失败
+
+当出现以下情况时使用本节：
+
+- `curl ... /v1/models` 可用
+- 很小的直接 `/v1/chat/completions` 调用可用
+- OpenClaw 模型运行仅在正常智能体轮次中失败
+
+```bash
+curl http://127.0.0.1:1234/v1/models
+curl http://127.0.0.1:1234/v1/chat/completions \
+  -H 'content-type: application/json' \
+  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'
+openclaw infer model run --model <provider/model> --prompt "hi" --json
+openclaw logs --follow
+```
+
+检查以下内容：
+
+- 很小的直接调用成功，但 OpenClaw 运行仅在更大的提示词下失败
+- 后端报错指出 `messages[].content` 需要字符串
+- 后端崩溃仅出现在更大的提示词 token 数或完整智能体运行时提示词下
+
+常见特征：
+
+- `messages[...].content: invalid type: sequence, expected a string` → 后端拒绝结构化的 Chat Completions 内容片段。修复方法：设置 `models.providers.<provider>.models[].compat.requiresStringContent: true`。
+- 很小的直接请求成功，但 OpenClaw 智能体运行因后端或模型崩溃而失败（例如某些 `inferrs` 版本中的 Gemma）→ OpenClaw 传输层很可能已经正确；失败的是后端在处理更大的智能体运行时提示词形状。
+- 禁用工具后失败有所减少但未消失 → 工具 schema 是压力来源之一，但剩余问题仍然是上游模型或服务器容量限制，或后端 bug。
+
+修复选项：
+
+1. 为仅支持字符串 Chat Completions 的后端设置 `compat.requiresStringContent: true`。
+2. 为无法可靠处理 OpenClaw 工具 schema 接口的模型或后端设置 `compat.supportsTools: false`。
+3. 尽可能降低提示词压力：更小的工作区引导、更短的会话历史、更轻量的本地模型，或使用对长上下文支持更强的后端。
+4. 如果很小的直接请求持续成功，而 OpenClaw 智能体轮次仍在后端内部崩溃，请将其视为上游服务器或模型限制，并在对应上游提交包含可接受负载形状的复现案例。
+
+相关内容：
+
+- [/gateway/local-models](/zh-CN/gateway/local-models)
+- [/gateway/configuration#models](/zh-CN/gateway/configuration#models)
+- [/gateway/configuration-reference#openai-compatible-endpoints](/zh-CN/gateway/configuration-reference#openai-compatible-endpoints)
+
 ## 没有回复

-如果渠道已连通但没有任何响应，在重新连接任何内容之前，请先检查路由和策略。
+如果渠道已上线但没有任何响应，请先检查路由和策略，再决定是否重新连接任何内容。

 ```bash
 openclaw status
@ -79,15 +121,15 @@ openclaw logs --follow

 检查以下内容：

- 私信发送者的配对是否仍在等待中。
+- 私信发送者存在待处理配对。
 - 群组提及门控（`requireMention`、`mentionPatterns`）。
- 渠道/群组允许列表是否不匹配。
+- 渠道或群组 allowlist 不匹配。

 常见特征：

- `drop guild message (mention required` → 群组消息会被忽略，直到出现提及。
- `pairing request` → 发送者需要批准。
- `blocked` / `allowlist` → 发送者/渠道被策略过滤。
+- `drop guild message (mention required` → 群组消息在被提及之前会被忽略。
+- `pairing request` → 发送者需要获批。
+- `blocked` / `allowlist` → 发送者或渠道被策略过滤。

 相关内容：

@ -95,9 +137,9 @@ openclaw logs --follow
 - [/channels/pairing](/zh-CN/channels/pairing)
 - [/channels/groups](/zh-CN/channels/groups)

-## 仪表板 Control UI 连接问题
+## Dashboard 控制 UI 连接问题

-当仪表板/Control UI 无法连接时，请验证 URL、认证模式和安全上下文假设。
+当 dashboard/控制 UI 无法连接时，请验证 URL、认证模式以及安全上下文相关假设。

 ```bash
 openclaw gateway status
@ -109,34 +151,34 @@ openclaw gateway status --json

 检查以下内容：

- 正确的探测 URL 和仪表板 URL。
- 客户端与 Gateway 网关之间的认证模式/token 是否不匹配。
- 在需要设备身份时是否仍在使用 HTTP。
+- 正确的探测 URL 和 dashboard URL。
+- 客户端与 Gateway 网关之间的认证模式或 token 不匹配。
+- 在需要设备身份的情况下使用了 HTTP。

 常见特征：

 - `device identity required` → 非安全上下文或缺少设备认证。
- `origin not allowed` → 浏览器 `Origin` 不在 `gateway.controlUi.allowedOrigins` 中（或者你正从非 loopback 的浏览器 origin 连接，但没有显式允许列表）。
- `device nonce required` / `device nonce mismatch` → 客户端没有完成基于挑战的设备认证流程（`connect.challenge` + `device.nonce`）。
- `device signature invalid` / `device signature expired` → 客户端为当前握手签署了错误的负载（或使用了过期时间戳）。
- `AUTH_TOKEN_MISMATCH` 且 `canRetryWithDeviceToken=true` → 客户端可以使用缓存的设备 token 执行一次受信任重试。
- 该缓存 token 重试会复用与已配对设备 token 一起存储的缓存 scope 集合。显式 `deviceToken` / 显式 `scopes` 调用方则会保留自己请求的 scope 集合。
- 除该重试路径外，连接认证优先级依次为：显式共享 token/password、然后显式 `deviceToken`、然后存储的设备 token、最后是引导 token。
- 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, ip}` 的失败尝试会在限流器记录失败之前串行化。因此，同一客户端的两个错误并发重试，第二次可能会显示 `retry later`，而不是两个普通的不匹配。
- 来自浏览器 origin loopback 客户端的 `too many failed authentication attempts (retry later)` → 来自同一归一化 `Origin` 的重复失败会被临时锁定；另一个 localhost origin 会使用独立的桶。
- 在那次重试后仍反复出现 `unauthorized` → 共享 token/设备 token 已漂移；如有需要，请刷新 token 配置并重新批准/轮换设备 token。
- `gateway connect failed:` → 主机/端口/url 目标错误。
+- `origin not allowed` → 浏览器 `Origin` 不在 `gateway.controlUi.allowedOrigins` 中（或者你正在从非 loopback 浏览器来源连接，且没有显式 allowlist）。
+- `device nonce required` / `device nonce mismatch` → 客户端未完成基于质询的设备认证流程（`connect.challenge` + `device.nonce`）。
+- `device signature invalid` / `device signature expired` → 客户端为当前握手签署了错误的负载，或使用了过期时间戳。
+- `AUTH_TOKEN_MISMATCH` 且带有 `canRetryWithDeviceToken=true` → 客户端可以使用缓存的设备 token 执行一次可信重试。
+- 该缓存 token 重试会复用与已配对设备 token 一起存储的缓存作用域集合。显式 `deviceToken` / 显式 `scopes` 调用方则保留其请求的作用域集合。
+- 除该重试路径外，连接认证优先级依次为：显式共享 token/密码优先，然后是显式 `deviceToken`，再然后是已存储的设备 token，最后是 bootstrap token。
+- 在异步 Tailscale Serve 控制 UI 路径中，相同 `{scope, ip}` 的失败尝试会在限流器记录失败之前被串行化。因此，同一客户端的两个错误并发重试中，第二次尝试可能显示 `retry later`，而不是两个普通的不匹配。
+- 来自浏览器来源 loopback 客户端的 `too many failed authentication attempts (retry later)` → 来自相同规范化 `Origin` 的重复失败会被临时锁定；另一个 localhost 来源会使用单独的桶。
+- 在该重试之后仍然反复出现 `unauthorized` → 共享 token 或设备 token 已漂移；如有需要，请刷新 token 配置并重新批准或轮换设备 token。
+- `gateway connect failed:` → 主机、端口或 URL 目标错误。

-### 认证详情代码速查表
+### 认证细节代码快速对照表

-使用失败的 `connect` 响应中的 `error.details.code` 来选择下一步操作：
+使用失败 `connect` 响应中的 `error.details.code` 来选择下一步操作：

-| 详情代码 | 含义 | 建议操作 |
-| ---------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `AUTH_TOKEN_MISSING` | 客户端没有发送所需的共享 token。 | 在客户端中粘贴/设置 token 后重试。对于仪表板路径：`openclaw config get gateway.auth.token`，然后将其粘贴到 Control UI 设置中。 |
-| `AUTH_TOKEN_MISMATCH` | 共享 token 与 Gateway 网关认证 token 不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许一次受信任重试。缓存 token 重试会复用已存储且批准的 scopes；显式 `deviceToken` / `scopes` 调用方保留请求的 scopes。如果仍失败，请运行 [token 漂移恢复检查清单](/cli/devices#token-drift-recovery-checklist)。 |
-| `AUTH_DEVICE_TOKEN_MISMATCH` | 缓存的按设备 token 已过期或被撤销。 | 使用 [devices CLI](/cli/devices) 轮换/重新批准设备 token，然后重新连接。 |
-| `PAIRING_REQUIRED` | 设备身份已知，但尚未为此角色批准。 | 批准待处理请求：`openclaw devices list`，然后 `openclaw devices approve <requestId>`。 |
+| Detail code                  | 含义                                                     | 建议操作                                                                                                                                                                                                                                                                             |
+| ---------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `AUTH_TOKEN_MISSING`         | 客户端未发送必需的共享 token。                           | 在客户端中粘贴或设置 token 后重试。对于 dashboard 路径：`openclaw config get gateway.auth.token`，然后将其粘贴到 Control UI 设置中。                                                                                                                                               |
+| `AUTH_TOKEN_MISMATCH`        | 共享 token 与 Gateway 网关认证 token 不匹配。            | 如果 `canRetryWithDeviceToken=true`，允许一次可信重试。缓存 token 重试会复用已存储的已批准作用域；显式 `deviceToken` / `scopes` 调用方保留请求的作用域。如果仍然失败，请运行 [token 漂移恢复清单](/cli/devices#token-drift-recovery-checklist)。                                 |
+| `AUTH_DEVICE_TOKEN_MISMATCH` | 每设备缓存 token 已过期或已被撤销。                      | 使用 [devices CLI](/cli/devices) 轮换或重新批准设备 token，然后重新连接。                                                                                                                                                                                                           |
+| `PAIRING_REQUIRED`           | 设备身份已知，但尚未批准此角色。                         | 批准待处理请求：`openclaw devices list`，然后 `openclaw devices approve <requestId>`。                                                                                                                                                                                              |

 设备认证 v2 迁移检查：

@ -146,7 +188,7 @@ openclaw doctor
 openclaw gateway status
 ```

-如果日志显示 nonce/signature 错误，请更新正在连接的客户端，并确认它：
+如果日志显示 nonce 或签名错误，请更新连接客户端，并验证它是否：

 1. 等待 `connect.challenge`
 2. 对绑定该 challenge 的负载进行签名
@ -154,8 +196,8 @@ openclaw gateway status

 如果 `openclaw devices rotate` / `revoke` / `remove` 被意外拒绝：

- 已配对设备 token 会话只能管理**它们自己的**设备，除非调用方还拥有 `operator.admin`
- `openclaw devices rotate --scope ...` 只能请求调用方会话已持有的 operator scopes
+- 已配对设备的 token 会话只能管理**它们自己的**设备，除非调用方还拥有 `operator.admin`
+- `openclaw devices rotate --scope ...` 只能请求调用方会话已持有的 operator 作用域

 相关内容：

@ -167,30 +209,30 @@ openclaw gateway status

 ## Gateway 网关服务未运行

-当服务已安装但进程无法保持运行时，请使用本节。
+当服务已安装，但进程无法持续运行时，请使用本节。

 ```bash
 openclaw gateway status
 openclaw status
 openclaw logs --follow
 openclaw doctor
-openclaw gateway status --deep   # also scan system-level services
+openclaw gateway status --deep   # 也会扫描系统级服务
 ```

 检查以下内容：

- `Runtime: stopped` 以及退出提示。
- 服务配置不匹配（`Config (cli)` vs `Config (service)`）。
- 端口/监听器冲突。
- 使用 `--deep` 时，是否存在多余的 launchd/systemd/schtasks 安装。
+- `Runtime: stopped` 及其退出提示。
+- 服务配置不匹配（`Config (cli)` 与 `Config (service)`）。
+- 端口或监听器冲突。
+- 使用 `--deep` 时出现额外的 launchd/systemd/schtasks 安装。
 - `Other gateway-like services detected (best effort)` 清理提示。

 常见特征：

- `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → 未启用本地 Gateway 网关模式，或者配置文件被覆盖导致丢失了 `gateway.mode`。修复方法：在你的配置中设置 `gateway.mode="local"`，或重新运行 `openclaw onboard --mode local` / `openclaw setup` 以重新写入预期的本地模式配置。如果你通过 Podman 运行 OpenClaw，默认配置路径是 `~/.openclaw/openclaw.json`。
- `refusing to bind gateway ... without auth` → 非 loopback 绑定，但没有有效的 Gateway 网关认证路径（token/password，或在已配置时使用 trusted-proxy）。
+- `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → 未启用本地 Gateway 网关模式，或者配置文件被破坏，导致丢失了 `gateway.mode`。修复方法：在你的配置中设置 `gateway.mode="local"`，或重新运行 `openclaw onboard --mode local` / `openclaw setup` 以重新写入预期的本地模式配置。如果你通过 Podman 运行 OpenClaw，默认配置路径是 `~/.openclaw/openclaw.json`。
+- `refusing to bind gateway ... without auth` → 非 loopback 绑定缺少有效的 Gateway 网关认证路径（token/密码，或在已配置场景下使用 trusted-proxy）。
 - `another gateway instance is already listening` / `EADDRINUSE` → 端口冲突。
- `Other gateway-like services detected (best effort)` → 存在过期或并行的 launchd/systemd/schtasks 单元。大多数配置应保持每台机器一个 Gateway 网关；如果你确实需要多个，请隔离端口 + 配置/状态/工作区。参见 [/gateway#multiple-gateways-same-host](/zh-CN/gateway#multiple-gateways-same-host)。
+- `Other gateway-like services detected (best effort)` → 存在过期或并行的 launchd/systemd/schtasks 单元。大多数部署应该每台机器只保留一个 Gateway 网关；如果你确实需要多个，请隔离端口 + 配置/状态/工作区。参见 [/gateway#multiple-gateways-same-host](/zh-CN/gateway#multiple-gateways-same-host)。

 相关内容：

@ -200,7 +242,7 @@ openclaw gateway status --deep   # also scan system-level services

 ## Gateway 网关探测警告

-当 `openclaw gateway probe` 确实探测到某个目标，但仍输出警告块时，请使用本节。
+当 `openclaw gateway probe` 已经探测到某个目标，但仍然打印警告块时，请使用本节。

 ```bash
 openclaw gateway probe
@ -211,14 +253,14 @@ openclaw gateway probe --ssh user@gateway-host
 检查以下内容：

 - JSON 输出中的 `warnings[].code` 和 `primaryTargetId`。
- 警告是否与 SSH 回退、多个 Gateway 网关、缺少 scopes 或未解析的 auth 引用有关。
+- 该警告是否与 SSH 回退、多个 Gateway 网关、缺少作用域或未解析的认证引用有关。

 常见特征：

- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但命令仍尝试了直接配置的/loopback 目标。
- `multiple reachable gateways detected` → 有多个目标做出了响应。这通常意味着你有意配置了多个 Gateway 网关，或者存在过期/重复监听器。
- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接成功，但详细 RPC 受 scope 限制；请配对设备身份或使用带有 `operator.read` 的凭证。
- 未解析的 `gateway.auth.*` / `gateway.remote.*` SecretRef 警告文本 → 在该命令路径中，失败目标的认证材料不可用。
+- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但命令仍然尝试了已配置的直接目标或 loopback 目标。
+- `multiple reachable gateways detected` → 超过一个目标作出了响应。这通常意味着有意的多 Gateway 网关部署，或存在过期/重复的监听器。
+- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接成功，但详细 RPC 受作用域限制；请配对设备身份，或使用带有 `operator.read` 的凭证。
+- 未解析的 `gateway.auth.*` / `gateway.remote.*` SecretRef 警告文本 → 在该命令路径中，失败目标所需的认证材料不可用。

 相关内容：

@ -226,9 +268,9 @@ openclaw gateway probe --ssh user@gateway-host
 - [/gateway#multiple-gateways-same-host](/zh-CN/gateway#multiple-gateways-same-host)
 - [/gateway/remote](/zh-CN/gateway/remote)

-## 渠道已连接但消息不流转
+## 渠道已连接但消息不流动

-如果渠道状态显示已连接，但消息流转中断，请重点检查策略、权限和渠道特定的投递规则。
+如果渠道状态显示已连接，但消息流已中断，请重点检查策略、权限和渠道特定的投递规则。

 ```bash
 openclaw channels status --probe
@ -241,14 +283,14 @@ openclaw config get channels
 检查以下内容：

 - 私信策略（`pairing`、`allowlist`、`open`、`disabled`）。
- 群组允许列表和提及要求。
- 是否缺少渠道 API 权限/scopes。
+- 群组 allowlist 和提及要求。
+- 缺少渠道 API 权限或作用域。

 常见特征：

 - `mention required` → 消息因群组提及策略而被忽略。
- `pairing` / 待批准跟踪 → 发送者尚未获批。
- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → 渠道认证/权限问题。
+- `pairing` / 待批准痕迹 → 发送者尚未获批。
+- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → 渠道认证或权限问题。

 相关内容：

@ -259,7 +301,7 @@ openclaw config get channels

 ## Cron 和心跳投递

-如果 cron 或心跳没有运行，或者运行了但未投递，请先验证调度器状态，再检查投递目标。
+如果 cron 或心跳没有运行，或者运行了但未成功投递，请先验证调度器状态，再检查投递目标。

 ```bash
 openclaw cron status
@ -272,18 +314,18 @@ openclaw logs --follow
 检查以下内容：

 - Cron 已启用，并且存在下一次唤醒时间。
- 任务运行历史状态（`ok`、`skipped`、`error`）。
+- 作业运行历史状态（`ok`、`skipped`、`error`）。
 - 心跳跳过原因（`quiet-hours`、`requests-in-flight`、`alerts-disabled`、`empty-heartbeat-file`、`no-tasks-due`）。

 常见特征：

 - `cron: scheduler disabled; jobs will not run automatically` → cron 已禁用。
- `cron: timer tick failed` → 调度器 tick 失败；请检查文件/日志/运行时错误。
- `heartbeat skipped` 且 `reason=quiet-hours` → 当前不在活跃时间窗口内。
- `heartbeat skipped` 且 `reason=empty-heartbeat-file` → `HEARTBEAT.md` 存在，但只包含空行 / Markdown 标题，因此 OpenClaw 会跳过模型调用。
- `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 包含 `tasks:` 块，但这一轮 tick 中没有任务到期。
- `heartbeat: unknown accountId` → 心跳投递目标的 account id 无效。
- `heartbeat skipped` 且 `reason=dm-blocked` → 心跳目标被解析为私信式目标，而 `agents.defaults.heartbeat.directPolicy`（或按智能体覆盖项）设置为 `block`。
+- `cron: timer tick failed` → 调度器 tick 失败；请检查文件、日志或运行时错误。
+- `heartbeat skipped` 且 `reason=quiet-hours` → 当前处于活跃时段窗口之外。
+- `heartbeat skipped` 且 `reason=empty-heartbeat-file` → `HEARTBEAT.md` 存在，但只包含空行或 markdown 标题，因此 OpenClaw 会跳过模型调用。
+- `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 包含 `tasks:` 块，但本次 tick 没有任务到期。
+- `heartbeat: unknown accountId` → 心跳投递目标使用了无效的账号 id。
+- `heartbeat skipped` 且 `reason=dm-blocked` → 心跳目标被解析为私信风格目标，而 `agents.defaults.heartbeat.directPolicy`（或每个智能体的覆盖值）设置为 `block`。

 相关内容：

@ -293,7 +335,7 @@ openclaw logs --follow

 ## 已配对节点的工具失败

-如果节点已配对，但工具仍然失败，请分别检查前台状态、权限和批准状态。
+如果节点已配对但工具失败，请分别隔离前台状态、权限和批准状态。

 ```bash
 openclaw nodes status
@ -305,16 +347,16 @@ openclaw status

 检查以下内容：

- 节点在线，并具有预期能力。
- 相机/麦克风/定位/屏幕的 OS 权限已授予。
- exec 批准和允许列表状态。
+- 节点在线，并具备预期能力。
+- 相机、麦克风、位置、屏幕等 OS 权限已授予。
+- exec 批准和 allowlist 状态。

 常见特征：

- `NODE_BACKGROUND_UNAVAILABLE` → 节点应用必须位于前台。
+- `NODE_BACKGROUND_UNAVAILABLE` → 节点应用必须处于前台。
 - `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → 缺少 OS 权限。
- `SYSTEM_RUN_DENIED: approval required` → exec 批准仍在等待。
- `SYSTEM_RUN_DENIED: allowlist miss` → 命令被允许列表阻止。
+- `SYSTEM_RUN_DENIED: approval required` → exec 批准待处理。
+- `SYSTEM_RUN_DENIED: allowlist miss` → 命令被 allowlist 拦截。

 相关内容：

@ -324,7 +366,7 @@ openclaw status

 ## 浏览器工具失败

-当浏览器工具操作失败，但 Gateway 网关本身是健康的，请使用本节。
+当浏览器工具操作失败，但 Gateway 网关本身健康时，请使用本节。

 ```bash
 openclaw browser status
@ -336,39 +378,39 @@ openclaw doctor

 检查以下内容：

- 是否设置了 `plugins.allow` 且其中包含 `browser`。
+- 是否设置了 `plugins.allow`，以及其中是否包含 `browser`。
 - 浏览器可执行文件路径是否有效。
- CDP profile 是否可达。
- `existing-session` / `user` profiles 是否有本地 Chrome 可用。
+- CDP 配置文件是否可达。
+- 用于 `existing-session` / `user` 配置文件的本地 Chrome 是否可用。

 常见特征：

- `unknown command "browser"` 或 `unknown command 'browser'` → 内置 browser 插件被 `plugins.allow` 排除。
- 在 `browser.enabled=true` 时 browser 工具缺失 / 不可用 → `plugins.allow` 排除了 `browser`，因此插件从未加载。
+- `unknown command "browser"` 或 `unknown command 'browser'` → 内置浏览器插件被 `plugins.allow` 排除。
+- 浏览器工具缺失或不可用，而 `browser.enabled=true` → `plugins.allow` 排除了 `browser`，因此插件从未加载。
 - `Failed to start Chrome CDP on port` → 浏览器进程启动失败。
 - `browser.executablePath not found` → 配置的路径无效。
 - `browser.cdpUrl must be http(s) or ws(s)` → 配置的 CDP URL 使用了不受支持的协议，例如 `file:` 或 `ftp:`。
- `browser.cdpUrl has invalid port` → 配置的 CDP URL 端口错误或超出范围。
- `No Chrome tabs found for profile="user"` → Chrome MCP attach profile 没有打开的本地 Chrome 标签页。
- `Remote CDP for profile "<name>" is not reachable` → 从 Gateway 网关主机无法访问配置的远程 CDP 端点。
- `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → attach-only profile 没有可达目标，或者 HTTP 端点虽然响应了，但 CDP WebSocket 仍无法打开。
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → 当前 Gateway 网关安装缺少完整的 Playwright 包；ARIA 快照和基础页面截图仍可能可用，但导航、AI 快照、基于 CSS 选择器的元素截图和 PDF 导出仍不可用。
+- `browser.cdpUrl has invalid port` → 配置的 CDP URL 包含错误或超出范围的端口。
+- `No Chrome tabs found for profile="user"` → Chrome MCP 附加配置文件没有打开的本地 Chrome 标签页。
+- `Remote CDP for profile "<name>" is not reachable` → 配置的远程 CDP 端点从 Gateway 网关主机无法访问。
+- `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → attach-only 配置文件没有可访问目标，或者 HTTP 端点虽有响应，但 CDP WebSocket 仍无法打开。
+- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → 当前 Gateway 网关安装不包含完整的 Playwright 包；ARIA 快照和基础页面截图仍可用，但导航、AI 快照、基于 CSS 选择器的元素截图以及 PDF 导出不可用。
 - `fullPage is not supported for element screenshots` → 截图请求同时使用了 `--full-page` 和 `--ref` 或 `--element`。
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` 截图调用必须使用页面捕获或快照 `--ref`，而不是 CSS `--element`。
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP 上传钩子需要使用快照引用，而不是 CSS 选择器。
- `existing-session file uploads currently support one file at a time.` → 在 Chrome MCP profiles 上，每次调用只能发送一个上传文件。
- `existing-session dialog handling does not support timeoutMs.` → Chrome MCP profiles 上的对话框钩子不支持超时覆盖。
- `response body is not supported for existing-session profiles yet.` → `responsebody` 仍然需要托管浏览器或原始 CDP profile。
- attach-only 或远程 CDP profiles 上出现陈旧的视口 / 深色模式 / 语言环境 / 离线覆盖 → 运行 `openclaw browser stop --browser-profile <name>` 关闭活动控制会话，并释放 Playwright/CDP 模拟状态，而无需重启整个 Gateway 网关。
+- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` 的截图调用必须使用页面捕获或快照 `--ref`，不能使用 CSS `--element`。
+- `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP 上传钩子需要使用快照引用，不能使用 CSS 选择器。
+- `existing-session file uploads currently support one file at a time.` → 在 Chrome MCP 配置文件中，每次调用只能发送一个上传文件。
+- `existing-session dialog handling does not support timeoutMs.` → Chrome MCP 配置文件中的对话框钩子不支持超时覆盖。
+- `response body is not supported for existing-session profiles yet.` → `responsebody` 目前仍然需要托管浏览器或原始 CDP 配置文件。
+- 在 attach-only 或远程 CDP 配置文件上出现过期的 viewport、深色模式、语言区域或离线覆盖状态 → 运行 `openclaw browser stop --browser-profile <name>` 以关闭活动控制会话，并释放 Playwright/CDP 模拟状态，而无需重启整个 Gateway 网关。

 相关内容：

 - [/tools/browser-linux-troubleshooting](/zh-CN/tools/browser-linux-troubleshooting)
 - [/tools/browser](/zh-CN/tools/browser)

-## 如果你升级后突然出现问题
+## 如果你升级后突然出问题了

-大多数升级后的故障都源于配置漂移，或是现在开始强制执行更严格的默认值。
+大多数升级后的故障都来自配置漂移，或现在开始强制执行更严格的默认值。

 ### 1) 认证和 URL 覆盖行为发生了变化

@ -379,9 +421,9 @@ openclaw config get gateway.remote.url
 openclaw config get gateway.auth.mode
 ```

-检查什么：
+需要检查的内容：

- 如果 `gateway.mode=remote`，CLI 调用可能会指向远程，而你的本地服务本身其实没问题。
+- 如果 `gateway.mode=remote`，CLI 调用可能正在访问远程目标，而你的本地服务其实是正常的。
 - 显式 `--url` 调用不会回退到已存储的凭证。

 常见特征：
@ -389,7 +431,7 @@ openclaw config get gateway.auth.mode
 - `gateway connect failed:` → URL 目标错误。
 - `unauthorized` → 端点可达，但认证错误。

-### 2) 绑定和认证防护更严格了
+### 2) 绑定和认证保护规则更严格了

 ```bash
 openclaw config get gateway.bind
@ -399,15 +441,15 @@ openclaw gateway status
 openclaw logs --follow
 ```

-检查什么：
+需要检查的内容：

- 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 Gateway 网关认证路径：共享 token/password 认证，或正确配置的非 loopback `trusted-proxy` 部署。
- 像 `gateway.token` 这样的旧键不能替代 `gateway.auth.token`。
+- 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 Gateway 网关认证路径：共享 token/密码认证，或正确配置的非 loopback `trusted-proxy` 部署。
+- 旧键如 `gateway.token` 不能替代 `gateway.auth.token`。

 常见特征：

- `refusing to bind gateway ... without auth` → 非 loopback 绑定，但没有有效的 Gateway 网关认证路径。
- `RPC probe: failed` 且运行时正在运行 → Gateway 网关是活的，但以当前 auth/url 无法访问。
+- `refusing to bind gateway ... without auth` → 非 loopback 绑定缺少有效的 Gateway 网关认证路径。
+- `RPC probe: failed` 且运行时正在运行 → Gateway 网关存活，但当前认证或 URL 无法访问。

 ### 3) 配对和设备身份状态发生了变化

@ -418,17 +460,17 @@ openclaw logs --follow
 openclaw doctor
 ```

-检查什么：
+需要检查的内容：

- 仪表板/节点是否存在待批准的设备审批。
- 策略或身份变更后，是否存在待批准的私信配对审批。
+- dashboard/节点是否存在待处理的设备批准。
+- 在策略或身份变化后，私信是否存在待处理的配对批准。

 常见特征：

 - `device identity required` → 设备认证未满足。
- `pairing required` → 发送者/设备必须先获批。
+- `pairing required` → 发送者或设备必须先获批。

-如果检查后服务配置和运行时仍不一致，请使用相同的 profile/state 目录重新安装服务元数据：
+如果在完成这些检查后，服务配置与运行时状态仍然不一致，请从相同的配置文件或状态目录重新安装服务元数据：

 ```bash
 openclaw gateway install --force
--- a/docs/zh-CN/help/troubleshooting.md
+++ b/docs/zh-CN/help/troubleshooting.md
@ -1,25 +1,25 @@
 ---
 read_when:
    - OpenClaw 无法正常工作，而你需要最快的修复路径
-    - 你想先进行分诊流程，再深入阅读详细运行手册
-summary: OpenClaw 的按症状优先故障排除中心
+    - 在深入查看详细运行手册之前，你想先进行分诊流程
+summary: OpenClaw 的症状优先故障排除中心
 title: 通用故障排除
 x-i18n:
-    generated_at: "2026-04-05T08:26:14Z"
+    generated_at: "2026-04-07T14:58:00Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 23ae9638af5edf5a5e0584ccb15ba404223ac3b16c2d62eb93b2c9dac171c252
+    source_hash: 8abda90ef80234c2f91a51c5e1f2c004d4a4da12a5d5631b5927762550c6d5e3
    source_path: help/troubleshooting.md
    workflow: 15
 ---

 # 故障排除

-如果你只有 2 分钟，请把本页当作分诊入口。
+如果你只有 2 分钟，请把此页面作为分诊入口。

 ## 最初的六十秒

-按顺序运行以下精确命令阶梯：
+按顺序运行以下这组准确的步骤：

 ```bash
 openclaw status
@ -31,33 +31,44 @@ openclaw channels status --probe
 openclaw logs --follow
 ```

-一行说明什么才算正常输出：
+单行中的正常输出：

- `openclaw status` → 显示已配置渠道，且没有明显的鉴权错误。
- `openclaw status --all` → 完整报告存在且可分享。
- `openclaw gateway probe` → 预期的 Gateway 网关目标可访问（`Reachable: yes`）。`RPC: limited - missing scope: operator.read` 表示诊断能力降级，不是连接失败。
- `openclaw gateway status` → `Runtime: running` 且 `RPC probe: ok`。
- `openclaw doctor` → 没有阻塞性的配置/服务错误。
- `openclaw channels status --probe` → 当 Gateway 网关可访问时，会返回按账户划分的实时
-  传输状态，以及诸如 `works` 或 `audit ok` 之类的探测/审计结果；如果
-  Gateway 网关不可访问，该命令会回退到仅基于配置的摘要。
- `openclaw logs --follow` → 持续有活动，没有重复出现的致命错误。
+- `openclaw status` → 显示已配置的渠道，且没有明显的认证错误。
+- `openclaw status --all` → 存在完整报告，并且可以分享。
+- `openclaw gateway probe` → 预期的 Gateway 网关目标可达（`Reachable: yes`）。`RPC: limited - missing scope: operator.read` 表示诊断能力受限，不是连接失败。
+- `openclaw gateway status` → `Runtime: running` 和 `RPC probe: ok`。
+- `openclaw doctor` → 没有阻塞性的配置或服务错误。
+- `openclaw channels status --probe` → 可达的 Gateway 网关会返回每个账户的实时传输状态，以及诸如 `works` 或 `audit ok` 的探测/审计结果；如果 Gateway 网关不可达，该命令会回退为仅配置摘要。
+- `openclaw logs --follow` → 活动稳定，没有重复出现的致命错误。

 ## Anthropic 长上下文 429

 如果你看到：
 `HTTP 429: rate_limit_error: Extra usage is required for long context requests`，
-请前往 [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context)。
+请前往 [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/zh-CN/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context)。

-## 插件安装失败，提示缺少 openclaw extensions
+## 本地 OpenAI 兼容后端可直接工作，但在 OpenClaw 中失败

-如果安装失败并提示 `package.json missing openclaw.extensions`，说明该插件包
-使用了 OpenClaw 已不再接受的旧结构。
+如果你的本地或自托管 `/v1` 后端能够响应较小的直接
+`/v1/chat/completions` 探测请求，但在 `openclaw infer model run` 或常规
+智能体轮次中失败：
+
+1. 如果错误提到 `messages[].content` 需要字符串，请设置
+   `models.providers.<provider>.models[].compat.requiresStringContent: true`。
+2. 如果后端仍然只在 OpenClaw 智能体轮次中失败，请设置
+   `models.providers.<provider>.models[].compat.supportsTools: false` 并重试。
+3. 如果极小的直接调用仍然有效，但更大的 OpenClaw 提示词会使后端崩溃，请将剩余问题视为上游模型/服务器限制，并继续查看详细运行手册：
+   [/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail](/zh-CN/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail)
+
+## 插件安装因缺少 openclaw extensions 而失败
+
+如果安装失败并显示 `package.json missing openclaw.extensions`，则说明该插件包
+使用了 OpenClaw 不再接受的旧格式。

 在插件包中修复：

 1. 在 `package.json` 中添加 `openclaw.extensions`。
-2. 将条目指向已构建的运行时文件（通常是 `./dist/index.js`）。
+2. 将条目指向已构建的运行时文件（通常为 `./dist/index.js`）。
 3. 重新发布插件，然后再次运行 `openclaw plugins install <package>`。

 示例：
@ -72,17 +83,17 @@ openclaw logs --follow
 }
 ```

-参考：[插件架构](/plugins/architecture)
+参考：[插件架构](/zh-CN/plugins/architecture)

 ## 决策树

 ```mermaid
 flowchart TD
-  A[OpenClaw 无法正常工作] --> B{最先出问题的是哪一环}
+  A[OpenClaw 无法正常工作] --> B{首先出问题的是什么}
  B --> C[没有回复]
-  B --> D[Dashboard 或 Control UI 无法连接]
+  B --> D[仪表板或 Control UI 无法连接]
  B --> E[Gateway 网关无法启动或服务未运行]
-  B --> F[渠道已连接，但消息不流动]
+  B --> F[渠道已连接，但消息未流动]
  B --> G[Cron 或 heartbeat 未触发或未送达]
  B --> H[节点已配对，但 camera canvas screen exec 工具失败]
  B --> I[浏览器工具失败]
@ -106,12 +117,12 @@ flowchart TD
    openclaw logs --follow
    ```

-    正常输出应类似于：
+    正常输出如下所示：

    - `Runtime: running`
    - `RPC probe: ok`
    - 你的渠道显示传输已连接，并且在支持的情况下，`channels status --probe` 中会显示 `works` 或 `audit ok`
-    - 发送者显示为已批准（或私信策略为 open/allowlist）
+    - 发送者显示为已获批准（或私信策略为开放/允许列表）

    常见日志特征：

@ -119,15 +130,15 @@ flowchart TD
    - `pairing request` → 发送者尚未获批，正在等待私信配对批准。
    - 渠道日志中的 `blocked` / `allowlist` → 发送者、房间或群组被过滤。

-    深入页面：
+    详细页面：

-    - [/gateway/troubleshooting#no-replies](/gateway/troubleshooting#no-replies)
-    - [/channels/troubleshooting](/channels/troubleshooting)
-    - [/channels/pairing](/channels/pairing)
+    - [/gateway/troubleshooting#no-replies](/zh-CN/gateway/troubleshooting#no-replies)
+    - [/channels/troubleshooting](/zh-CN/channels/troubleshooting)
+    - [/channels/pairing](/zh-CN/channels/pairing)

  </Accordion>

-  <Accordion title="Dashboard 或 Control UI 无法连接">
+  <Accordion title="仪表板或 Control UI 无法连接">
    ```bash
    openclaw status
    openclaw gateway status
@ -136,34 +147,28 @@ flowchart TD
    openclaw channels status --probe
    ```

-    正常输出应类似于：
+    正常输出如下所示：

-    - `openclaw gateway status` 中显示 `Dashboard: http://...`
+    - 在 `openclaw gateway status` 中显示 `Dashboard: http://...`
    - `RPC probe: ok`
-    - 日志中没有鉴权循环
+    - 日志中没有认证循环

    常见日志特征：

-    - `device identity required` → HTTP/非安全上下文无法完成设备鉴权。
-    - `origin not allowed` → 该浏览器 `Origin` 不被该 Control UI
-      Gateway 网关目标允许。
-    - `AUTH_TOKEN_MISMATCH` 并带有重试提示（`canRetryWithDeviceToken=true`）→ 可能会自动执行一次受信任的设备 token 重试。
-    - 该缓存 token 重试会复用与已配对
-      设备 token 一起存储的缓存 scope 集。显式 `deviceToken` / 显式 `scopes` 调用方则保持
-      其请求的 scope 集不变。
-    - 在异步 Tailscale Serve Control UI 路径上，同一个
-      `{scope, ip}` 的失败尝试会在限流器记录失败前被串行化，因此第二个并发的错误重试可能已经显示 `retry later`。
-    - 来自 localhost 浏览器来源的 `too many failed authentication attempts (retry later)` →
-      来自同一 `Origin` 的重复失败会被暂时
-      锁定；另一个 localhost 来源会使用独立的桶。
-    - 在该次重试后仍反复出现 `unauthorized` → token/password 错误、鉴权模式不匹配，或已配对设备 token 过期。
-    - `gateway connect failed:` → UI 指向了错误的 URL/端口，或 Gateway 网关不可访问。
+    - `device identity required` → HTTP/非安全上下文无法完成设备认证。
+    - `origin not allowed` → 浏览器 `Origin` 不在 Control UI 的 Gateway 网关目标允许范围内。
+    - 带有重试提示的 `AUTH_TOKEN_MISMATCH`（`canRetryWithDeviceToken=true`）→ 可能会自动进行一次可信设备令牌重试。
+    - 该缓存令牌重试会复用与已配对设备令牌一起存储的缓存作用域集合。显式 `deviceToken` / 显式 `scopes` 调用方则会保留其请求的作用域集合。
+    - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, ip}` 的失败尝试会在限制器记录失败之前被串行化，因此第二个并发的错误重试可能已经显示 `retry later`。
+    - 来自 localhost 浏览器来源的 `too many failed authentication attempts (retry later)` → 来自同一 `Origin` 的重复失败会被临时锁定；另一个 localhost 来源会使用单独的桶。
+    - 在该次重试之后仍重复出现 `unauthorized` → 错误的令牌/密码、认证模式不匹配，或已配对设备令牌已过期。
+    - `gateway connect failed:` → UI 正在指向错误的 URL/端口，或 Gateway 网关不可达。

-    深入页面：
+    详细页面：

-    - [/gateway/troubleshooting#dashboard-control-ui-connectivity](/gateway/troubleshooting#dashboard-control-ui-connectivity)
+    - [/gateway/troubleshooting#dashboard-control-ui-connectivity](/zh-CN/gateway/troubleshooting#dashboard-control-ui-connectivity)
    - [/web/control-ui](/web/control-ui)
-    - [/gateway/authentication](/gateway/authentication)
+    - [/gateway/authentication](/zh-CN/gateway/authentication)

  </Accordion>

@ -176,7 +181,7 @@ flowchart TD
    openclaw channels status --probe
    ```

-    正常输出应类似于：
+    正常输出如下所示：

    - `Service: ... (loaded)`
    - `Runtime: running`
@ -184,19 +189,19 @@ flowchart TD

    常见日志特征：

-    - `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → Gateway 网关模式为 remote，或配置文件缺少本地模式标记，需要修复。
-    - `refusing to bind gateway ... without auth` → 非 loopback 绑定，但没有有效的 Gateway 网关鉴权路径（token/password，或已配置的 trusted-proxy）。
+    - `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → Gateway 网关模式为 remote，或者配置文件缺少本地模式标记，需要修复。
+    - `refusing to bind gateway ... without auth` → 在没有有效 Gateway 网关认证路径的情况下进行非 loopback 绑定（令牌/密码，或按配置启用的 trusted-proxy）。
    - `another gateway instance is already listening` 或 `EADDRINUSE` → 端口已被占用。

-    深入页面：
+    详细页面：

-    - [/gateway/troubleshooting#gateway-service-not-running](/gateway/troubleshooting#gateway-service-not-running)
-    - [/gateway/background-process](/gateway/background-process)
-    - [/gateway/configuration](/gateway/configuration)
+    - [/gateway/troubleshooting#gateway-service-not-running](/zh-CN/gateway/troubleshooting#gateway-service-not-running)
+    - [/gateway/background-process](/zh-CN/gateway/background-process)
+    - [/gateway/configuration](/zh-CN/gateway/configuration)

  </Accordion>

-  <Accordion title="渠道已连接，但消息不流动">
+  <Accordion title="渠道已连接，但消息未流动">
    ```bash
    openclaw status
    openclaw gateway status
@ -205,22 +210,22 @@ flowchart TD
    openclaw channels status --probe
    ```

-    正常输出应类似于：
+    正常输出如下所示：

    - 渠道传输已连接。
-    - 配对/allowlist 检查通过。
-    - 在要求提及时，提及已被检测到。
+    - 配对/允许列表检查通过。
+    - 在需要时能够检测到提及。

    常见日志特征：

    - `mention required` → 群组提及门控阻止了处理。
    - `pairing` / `pending` → 私信发送者尚未获批。
-    - `not_in_channel`、`missing_scope`、`Forbidden`、`401/403` → 渠道权限 token 问题。
+    - `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → 渠道权限令牌问题。

-    深入页面：
+    详细页面：

-    - [/gateway/troubleshooting#channel-connected-messages-not-flowing](/gateway/troubleshooting#channel-connected-messages-not-flowing)
-    - [/channels/troubleshooting](/channels/troubleshooting)
+    - [/gateway/troubleshooting#channel-connected-messages-not-flowing](/zh-CN/gateway/troubleshooting#channel-connected-messages-not-flowing)
+    - [/channels/troubleshooting](/zh-CN/channels/troubleshooting)

  </Accordion>

@ -234,30 +239,30 @@ flowchart TD
    openclaw logs --follow
    ```

-    正常输出应类似于：
+    正常输出如下所示：

-    - `cron.status` 显示已启用，并有下一次唤醒时间。
+    - `cron.status` 显示已启用，并带有下次唤醒时间。
    - `cron runs` 显示最近的 `ok` 条目。
-    - Heartbeat 已启用，且不在活跃时段之外。
+    - heartbeat 已启用，且当前不在活跃时段之外。

    常见日志特征：

 - `cron: scheduler disabled; jobs will not run automatically` → cron 已禁用。
- `heartbeat skipped` 且带有 `reason=quiet-hours` → 位于配置的活跃时段之外。
- `heartbeat skipped` 且带有 `reason=empty-heartbeat-file` → `HEARTBEAT.md` 存在，但只包含空白内容/仅标题骨架。
- `heartbeat skipped` 且带有 `reason=no-tasks-due` → `HEARTBEAT.md` 任务模式已启用，但尚未有任何任务到达执行间隔。
- `heartbeat skipped` 且带有 `reason=alerts-disabled` → 所有 heartbeat 可见性均被禁用（`showOk`、`showAlerts` 和 `useIndicator` 全部关闭）。
- `requests-in-flight` → 主通道繁忙；heartbeat 唤醒被延后。 - `unknown accountId` → heartbeat 投递目标账户不存在。
+- `heartbeat skipped` 且 `reason=quiet-hours` → 当前处于已配置的非活跃时段。
+- `heartbeat skipped` 且 `reason=empty-heartbeat-file` → `HEARTBEAT.md` 存在，但只包含空白内容或仅标题脚手架。
+- `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 任务模式已启用，但目前还没有任何任务间隔到期。
+- `heartbeat skipped` 且 `reason=alerts-disabled` → 所有 heartbeat 可见性均已禁用（`showOk`、`showAlerts` 和 `useIndicator` 全部关闭）。
+- `requests-in-flight` → 主通道繁忙；heartbeat 唤醒已延后。- `unknown accountId` → heartbeat 投递目标账户不存在。

-      深入页面：
+      详细页面：

-      - [/gateway/troubleshooting#cron-and-heartbeat-delivery](/gateway/troubleshooting#cron-and-heartbeat-delivery)
-      - [/automation/cron-jobs#troubleshooting](/automation/cron-jobs#troubleshooting)
-      - [/gateway/heartbeat](/gateway/heartbeat)
+      - [/gateway/troubleshooting#cron-and-heartbeat-delivery](/zh-CN/gateway/troubleshooting#cron-and-heartbeat-delivery)
+      - [/automation/cron-jobs#troubleshooting](/zh-CN/automation/cron-jobs#troubleshooting)
+      - [/gateway/heartbeat](/zh-CN/gateway/heartbeat)

    </Accordion>

-    <Accordion title="节点已配对，但 tool 的 camera canvas screen exec 失败">
+    <Accordion title="节点已配对，但工具 camera canvas screen exec 失败">
      ```bash
      openclaw status
      openclaw gateway status
@ -266,24 +271,24 @@ flowchart TD
      openclaw logs --follow
      ```

-      正常输出应类似于：
+      正常输出如下所示：

-      - 节点被列为已连接且已配对，角色为 `node`。
-      - 你调用的命令对应的能力存在。
-      - 该工具的权限状态为已授予。
+      - 节点已列为已连接，并且以 `node` 角色完成配对。
+      - 你正在调用的命令具备相应能力。
+      - 该工具的权限状态已授予。

      常见日志特征：

-      - `NODE_BACKGROUND_UNAVAILABLE` → 将节点应用切到前台。
+      - `NODE_BACKGROUND_UNAVAILABLE` → 将节点应用切换到前台。
      - `*_PERMISSION_REQUIRED` → 操作系统权限被拒绝或缺失。
      - `SYSTEM_RUN_DENIED: approval required` → exec 批准正在等待中。
-      - `SYSTEM_RUN_DENIED: allowlist miss` → 命令不在 exec allowlist 中。
+      - `SYSTEM_RUN_DENIED: allowlist miss` → 命令不在 exec 允许列表中。

-      深入页面：
+      详细页面：

-      - [/gateway/troubleshooting#node-paired-tool-fails](/gateway/troubleshooting#node-paired-tool-fails)
-      - [/nodes/troubleshooting](/nodes/troubleshooting)
-      - [/tools/exec-approvals](/tools/exec-approvals)
+      - [/gateway/troubleshooting#node-paired-tool-fails](/zh-CN/gateway/troubleshooting#node-paired-tool-fails)
+      - [/nodes/troubleshooting](/zh-CN/nodes/troubleshooting)
+      - [/tools/exec-approvals](/zh-CN/tools/exec-approvals)

    </Accordion>

@ -297,14 +302,14 @@ flowchart TD

      发生了什么变化：

-      - 如果未设置 `tools.exec.host`，默认值是 `auto`。
-      - 当沙箱运行时处于活动状态时，`host=auto` 解析为 `sandbox`，否则为 `gateway`。
-      - `host=auto` 只负责路由；无提示的 “YOLO” 行为来自 gateway/node 上的 `security=full` 加 `ask=off`。
-      - 在 `gateway` 和 `node` 上，未设置的 `tools.exec.security` 默认是 `full`。
-      - 未设置的 `tools.exec.ask` 默认是 `off`。
-      - 结果：如果你现在看到了批准请求，说明某些主机本地或按会话的策略把 exec 收紧到了偏离当前默认值的状态。
+      - 如果 `tools.exec.host` 未设置，默认值为 `auto`。
+      - 当沙箱运行时处于活动状态时，`host=auto` 会解析为 `sandbox`，否则解析为 `gateway`。
+      - `host=auto` 只影响路由；无提示的 “YOLO” 行为来自 gateway/node 上的 `security=full` 加 `ask=off`。
+      - 在 `gateway` 和 `node` 上，未设置的 `tools.exec.security` 默认值为 `full`。
+      - 未设置的 `tools.exec.ask` 默认值为 `off`。
+      - 结果：如果你现在看到了批准请求，说明某些主机本地或当前会话策略已经将 exec 收紧，不再符合当前默认值。

-      恢复当前默认的“无需批准”行为：
+      恢复当前默认的无批准行为：

      ```bash
      openclaw config set tools.exec.host gateway
@ -315,21 +320,21 @@ flowchart TD

      更安全的替代方案：

-      - 如果你只想要稳定的主机路由，仅设置 `tools.exec.host=gateway`。
-      - 如果你想要主机 exec，但仍希望在 allowlist 未命中时进行审查，请使用 `security=allowlist` 和 `ask=on-miss`。
-      - 如果你希望 `host=auto` 再次解析回 `sandbox`，请启用沙箱模式。
+      - 如果你只是想要稳定的主机路由，只设置 `tools.exec.host=gateway`。
+      - 如果你希望使用主机 exec，但在允许列表未命中时仍进行审查，请使用 `security=allowlist` 和 `ask=on-miss`。
+      - 如果你希望 `host=auto` 重新解析为 `sandbox`，请启用沙箱模式。

      常见日志特征：

      - `Approval required.` → 命令正在等待 `/approve ...`。
-      - `SYSTEM_RUN_DENIED: approval required` → 节点宿主 exec 批准正在等待中。
-      - `exec host=sandbox requires a sandbox runtime for this session` → 发生了隐式/显式的沙箱选择，但沙箱模式处于关闭状态。
+      - `SYSTEM_RUN_DENIED: approval required` → 节点主机 exec 批准正在等待中。
+      - `exec host=sandbox requires a sandbox runtime for this session` → 隐式/显式选择了沙箱，但沙箱模式处于关闭状态。

-      深入页面：
+      详细页面：

-      - [/tools/exec](/tools/exec)
-      - [/tools/exec-approvals](/tools/exec-approvals)
-      - [/gateway/security#runtime-expectation-drift](/gateway/security#runtime-expectation-drift)
+      - [/tools/exec](/zh-CN/tools/exec)
+      - [/tools/exec-approvals](/zh-CN/tools/exec-approvals)
+      - [/gateway/security#runtime-expectation-drift](/zh-CN/gateway/security#runtime-expectation-drift)

    </Accordion>

@ -342,37 +347,37 @@ flowchart TD
      openclaw doctor
      ```

-      正常输出应类似于：
+      正常输出如下所示：

-      - 浏览器状态显示 `running: true`，并有已选定的浏览器/profile。
-      - `openclaw` 能启动，或 `user` 能看到本地 Chrome 标签页。
+      - 浏览器状态显示 `running: true`，并且有已选定的浏览器/配置文件。
+      - `openclaw` 能够启动，或者 `user` 能看到本地 Chrome 标签页。

      常见日志特征：

-      - `unknown command "browser"` 或 `unknown command 'browser'` → 设置了 `plugins.allow`，但其中不包含 `browser`。
+      - `unknown command "browser"` 或 `unknown command 'browser'` → 已设置 `plugins.allow`，且其中不包含 `browser`。
      - `Failed to start Chrome CDP on port` → 本地浏览器启动失败。
      - `browser.executablePath not found` → 配置的二进制路径错误。
      - `browser.cdpUrl must be http(s) or ws(s)` → 配置的 CDP URL 使用了不受支持的协议。
      - `browser.cdpUrl has invalid port` → 配置的 CDP URL 端口错误或超出范围。
-      - `No Chrome tabs found for profile="user"` → Chrome MCP 附加 profile 没有打开的本地 Chrome 标签页。
+      - `No Chrome tabs found for profile="user"` → Chrome MCP 附加配置文件没有打开的本地 Chrome 标签页。
      - `Remote CDP for profile "<name>" is not reachable` → 配置的远程 CDP 端点从此主机无法访问。
-      - `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加 profile 没有可用的 CDP 目标。
-      - attach-only 或远程 CDP profile 上存在陈旧的 viewport / dark-mode / locale / offline 覆盖状态 → 运行 `openclaw browser stop --browser-profile <name>` 以关闭活动控制会话并释放模拟状态，而无需重启 Gateway 网关。
+      - `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加配置文件没有可用的实时 CDP 目标。
+      - 对于仅附加或远程 CDP 配置文件，出现过期的 viewport / dark-mode / locale / offline 覆盖状态 → 运行 `openclaw browser stop --browser-profile <name>` 以关闭当前控制会话并释放仿真状态，而无需重启 Gateway 网关。

-      深入页面：
+      详细页面：

-      - [/gateway/troubleshooting#browser-tool-fails](/gateway/troubleshooting#browser-tool-fails)
-      - [/tools/browser#missing-browser-command-or-tool](/tools/browser#missing-browser-command-or-tool)
-      - [/tools/browser-linux-troubleshooting](/tools/browser-linux-troubleshooting)
-      - [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/tools/browser-wsl2-windows-remote-cdp-troubleshooting)
+      - [/gateway/troubleshooting#browser-tool-fails](/zh-CN/gateway/troubleshooting#browser-tool-fails)
+      - [/tools/browser#missing-browser-command-or-tool](/zh-CN/tools/browser#missing-browser-command-or-tool)
+      - [/tools/browser-linux-troubleshooting](/zh-CN/tools/browser-linux-troubleshooting)
+      - [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/zh-CN/tools/browser-wsl2-windows-remote-cdp-troubleshooting)

    </Accordion>
  </AccordionGroup>

 ## 相关内容

- [常见问题](/help/faq) — 常见问题
- [Gateway 故障排除](/gateway/troubleshooting) — Gateway 网关专属问题
- [Doctor](/gateway/doctor) — 自动健康检查与修复
- [渠道故障排除](/channels/troubleshooting) — 渠道连接问题
- [自动化故障排除](/automation/cron-jobs#troubleshooting) — cron 和 heartbeat 问题
+- [常见问题](/zh-CN/help/faq) — 常见问题
+- [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting) — Gateway 网关特定问题
+- [Doctor](/zh-CN/gateway/doctor) — 自动健康检查与修复
+- [渠道故障排除](/zh-CN/channels/troubleshooting) — 渠道连接问题
+- [自动化故障排除](/zh-CN/automation/cron-jobs#troubleshooting) — cron 和 heartbeat 问题
--- a/docs/zh-CN/providers/index.md
+++ b/docs/zh-CN/providers/index.md
@ -5,10 +5,10 @@ read_when:
 summary: OpenClaw 支持的模型提供商（LLM）
 title: 提供商目录
 x-i18n:
-    generated_at: "2026-04-06T18:55:00Z"
+    generated_at: "2026-04-07T14:57:15Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 39d9ace35fd9452a4fb510fd980d251b6e51480e4647f051020bee2f1f2222e1
+    source_hash: e7bee5528b7fc9a982b3d0eaa4930cb77f7bded19a47aec00572b6fcbd823a70
    source_path: providers/index.md
    workflow: 15
 ---
@ -17,11 +17,11 @@ x-i18n:

 OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份验证，然后将默认模型设置为 `provider/model`。

-在找聊天渠道文档（WhatsApp/Telegram/Discord/Slack/Mattermost（插件）/ 等）吗？请参阅 [Channels](/zh-CN/channels)。
+在找聊天渠道文档（WhatsApp/Telegram/Discord/Slack/Mattermost（插件）/ 等）？请参阅 [渠道](/zh-CN/channels)。

 ## 快速开始

-1. 使用提供商完成身份验证（通常通过 `openclaw onboard`）。
+1. 使用该提供商完成身份验证（通常通过 `openclaw onboard`）。
 2. 设置默认模型：

 ```json5
@ -47,7 +47,8 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份
 - [GLM 模型](/zh-CN/providers/glm)
 - [Google（Gemini）](/zh-CN/providers/google)
 - [Groq（LPU 推理）](/zh-CN/providers/groq)
- [Hugging Face（Inference）](/zh-CN/providers/huggingface)
+- [Hugging Face（推理）](/zh-CN/providers/huggingface)
+- [inferrs（本地模型）](/zh-CN/providers/inferrs)
 - [Kilocode](/zh-CN/providers/kilocode)
 - [LiteLLM（统一 Gateway 网关）](/zh-CN/providers/litellm)
 - [MiniMax](/zh-CN/providers/minimax)
@ -59,7 +60,7 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份
 - [OpenCode](/zh-CN/providers/opencode)
 - [OpenCode Go](/zh-CN/providers/opencode-go)
 - [OpenRouter](/zh-CN/providers/openrouter)
- [Perplexity（网页搜索）](/zh-CN/providers/perplexity-provider)
+- [Perplexity（Web 搜索）](/zh-CN/providers/perplexity-provider)
 - [Qianfan](/zh-CN/providers/qianfan)
 - [Qwen Cloud](/zh-CN/providers/qwen)
 - [Runway](/zh-CN/providers/runway)
@ -91,4 +92,4 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份

 - [Claude Max API Proxy](/zh-CN/providers/claude-max-api-proxy) - 用于 Claude 订阅凭证的社区代理（使用前请确认 Anthropic 的政策/条款）

-有关完整的提供商目录（xAI、Groq、Mistral 等）和高级配置，请参阅 [模型提供商](/zh-CN/concepts/model-providers)。
+如需查看完整的提供商目录（xAI、Groq、Mistral 等）和高级配置，请参阅 [模型提供商](/zh-CN/concepts/model-providers)。
--- a/docs/zh-CN/providers/inferrs.md
+++ b/docs/zh-CN/providers/inferrs.md
@ -0,0 +1,161 @@
+---
+read_when:
+    - 你想让 OpenClaw 连接本地 inferrs 服务器运行
+    - 你正通过 inferrs 提供 Gemma 或其他模型
+    - 你需要 inferrs 的精确 OpenClaw 兼容标志
+summary: 通过 inferrs（兼容 OpenAI 的本地服务器）运行 OpenClaw
+title: inferrs
+x-i18n:
+    generated_at: "2026-04-07T14:57:21Z"
+    model: gpt-5.4
+    provider: openai
+    source_hash: d84f660d49a682d0c0878707eebe1bc1e83dd115850687076ea3938b9f9c86c6
+    source_path: providers/inferrs.md
+    workflow: 15
+---
+
+# inferrs
+
+[inferrs](https://github.com/ericcurtin/inferrs) 可以通过兼容 OpenAI 的 `/v1` API 提供本地模型服务。OpenClaw 可通过通用的 `openai-completions` 路径与 `inferrs` 配合使用。
+
+目前，最好将 `inferrs` 视为一个自定义的自托管、兼容 OpenAI 的后端，而不是 OpenClaw 的专用提供商插件。
+
+## 快速开始
+
+1. 使用一个模型启动 `inferrs`。
+
+示例：
+
+```bash
+inferrs serve gg-hf-gg/gemma-4-E2B-it \
+  --host 127.0.0.1 \
+  --port 8080 \
+  --device metal
+```
+
+2. 验证服务器可访问。
+
+```bash
+curl http://127.0.0.1:8080/health
+curl http://127.0.0.1:8080/v1/models
+```
+
+3. 添加一个显式的 OpenClaw 提供商条目，并将你的默认模型指向它。
+
+## 完整配置示例
+
+此示例在本地 `inferrs` 服务器上使用 Gemma 4。
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "inferrs/gg-hf-gg/gemma-4-E2B-it" },
+      models: {
+        "inferrs/gg-hf-gg/gemma-4-E2B-it": {
+          alias: "Gemma 4 (inferrs)",
+        },
+      },
+    },
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      inferrs: {
+        baseUrl: "http://127.0.0.1:8080/v1",
+        apiKey: "inferrs-local",
+        api: "openai-completions",
+        models: [
+          {
+            id: "gg-hf-gg/gemma-4-E2B-it",
+            name: "Gemma 4 E2B (inferrs)",
+            reasoning: false,
+            input: ["text"],
+            cost: { input: 0, output: 0, cache读取: 0, cache写入: 0 },
+            contextWindow: 131072,
+            maxTokens: 4096,
+            compat: {
+              requiresStringContent: true,
+            },
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+## 为什么 `requiresStringContent` 很重要
+
+某些 `inferrs` Chat Completions 路由只接受字符串形式的 `messages[].content`，不接受结构化的内容片段数组。
+
+如果 OpenClaw 运行时出现如下错误：
+
+```text
+messages[1].content: invalid type: sequence, expected a string
+```
+
+请设置：
+
+```json5
+compat: {
+  requiresStringContent: true
+}
+```
+
+OpenClaw 会在发送请求前，将纯文本内容片段压平成普通字符串。
+
+## Gemma 和工具 schema 注意事项
+
+某些当前的 `inferrs` + Gemma 组合可以接受较小的直接 `/v1/chat/completions` 请求，但在完整的 OpenClaw 智能体运行时轮次中仍然会失败。
+
+如果发生这种情况，请先尝试：
+
+```json5
+compat: {
+  requiresStringContent: true,
+  supportsTools: false
+}
+```
+
+这会禁用该模型的 OpenClaw 工具 schema 接口，并可减轻对更严格本地后端的提示词压力。
+
+如果很小的直接请求仍然可用，但正常的 OpenClaw 智能体轮次继续在 `inferrs` 内部崩溃，那么剩余问题通常是上游模型或服务器行为导致的，而不是 OpenClaw 的传输层问题。
+
+## 手动冒烟测试
+
+配置完成后，同时测试这两层：
+
+```bash
+curl http://127.0.0.1:8080/v1/chat/completions \
+  -H 'content-type: application/json' \
+  -d '{"model":"gg-hf-gg/gemma-4-E2B-it","messages":[{"role":"user","content":"What is 2 + 2?"}],"stream":false}'
+
+openclaw infer model run \
+  --model inferrs/gg-hf-gg/gemma-4-E2B-it \
+  --prompt "What is 2 + 2? Reply with one short sentence." \
+  --json
+```
+
+如果第一条命令成功但第二条失败，请使用下面的故障排除说明。
+
+## 故障排除
+
+- `curl /v1/models` 失败：`inferrs` 未运行、无法访问，或未绑定到预期的主机/端口。
+- `messages[].content ... expected a string`：设置 `compat.requiresStringContent: true`。
+- 直接的小型 `/v1/chat/completions` 调用通过，但 `openclaw infer model run` 失败：尝试设置 `compat.supportsTools: false`。
+- OpenClaw 不再出现 schema 错误，但 `inferrs` 在更大的智能体轮次中仍然崩溃：将其视为上游 `inferrs` 或模型的限制，并减少提示词压力，或切换本地后端/模型。
+
+## 代理式行为
+
+`inferrs` 被视为代理式的、兼容 OpenAI 的 `/v1` 后端，而不是原生 OpenAI 端点。
+
+- 此处不适用仅限原生 OpenAI 的请求整形
+- 不支持 `service_tier`、Responses `store`、提示词缓存提示，以及 OpenAI 推理兼容负载整形
+- 在自定义 `inferrs` base URL 上，不会注入隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）
+
+## 另请参见
+
+- [本地模型](/zh-CN/gateway/local-models)
+- [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail)
+- [模型提供商](/zh-CN/concepts/model-providers)