From b3901b9fb818703f15fcfa2f642dd245877d054c Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 20 Apr 2026 06:39:57 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/channels/troubleshooting.md | 111 +- docs/zh-CN/gateway/index.md | 146 +- docs/zh-CN/gateway/troubleshooting.md | 271 ++-- docs/zh-CN/help/faq.md | 2009 ++++++++++++------------ docs/zh-CN/help/troubleshooting.md | 175 ++- 5 files changed, 1363 insertions(+), 1349 deletions(-) diff --git a/docs/zh-CN/channels/troubleshooting.md b/docs/zh-CN/channels/troubleshooting.md index 160a27755..8eca5c991 100644 --- a/docs/zh-CN/channels/troubleshooting.md +++ b/docs/zh-CN/channels/troubleshooting.md @@ -1,23 +1,23 @@ --- read_when: - 渠道传输显示已连接，但回复失败 - - 在深入查看提供商文档之前，你需要先进行渠道专属检查 -summary: 按渠道划分的快速故障排除，包含各渠道的故障特征和修复方法 + - 在深入查看提供商文档之前，你需要先进行渠道专项检查 +summary: 按渠道划分的快速故障排除，包含各渠道的失败特征和修复方法 title: 渠道故障排除 x-i18n: - generated_at: "2026-04-05T08:18:13Z" + generated_at: "2026-04-20T06:31:00Z" model: gpt-5.4 provider: openai - source_hash: d45d8220505ea420d970b20bc66e65216c2d7024b5736db1936421ffc0676e1f + source_hash: 0aef31742cd5cc4af3fa3d3ea1acba51875ad4a1423c0e8c87372c3df31b0528 source_path: channels/troubleshooting.md workflow: 15 --- # 渠道故障排除 -当某个渠道已连接但行为不正确时，请使用此页面。 +当渠道已连接但行为异常时，请使用本页。 -## 命令排查阶梯 +## 命令检查阶梯 请先按顺序运行以下命令： @@ -32,109 +32,110 @@ openclaw channels status --probe 健康基线： - `Runtime: running` -- `RPC probe: ok` +- `Connectivity probe: ok` +- `Capability: read-only`、`write-capable` 或 `admin-capable` - 渠道探测显示传输已连接，并且在支持的情况下显示 `works` 或 `audit ok` ## WhatsApp -### WhatsApp 故障特征 +### WhatsApp 失败特征 -| 症状 | 最快检查方式 | 修复方法 | +| 症状 | 最快检查 | 修复方法 | | ------------------------------- | --------------------------------------------------- | ------------------------------------------------------- | -| 已连接但没有私信回复 | `openclaw pairing list whatsapp` | 批准发送者，或切换私信策略/允许列表。 | +| 已连接但没有 私信 回复 | `openclaw pairing list whatsapp` | 批准发送者，或切换 私信 策略 / 允许列表。 | | 群组消息被忽略 | 检查配置中的 `requireMention` 和提及模式 | 提及机器人，或放宽该群组的提及策略。 | -| 随机断开/重复登录循环 | `openclaw channels status --probe` + 日志 | 重新登录，并确认凭证目录状态正常。 | +| 随机断开 / 反复重新登录 | `openclaw channels status --probe` + 日志 | 重新登录，并确认凭证目录状态正常。 | -完整故障排除：[/channels/whatsapp#troubleshooting](/channels/whatsapp#troubleshooting) +完整故障排除：[/channels/whatsapp#troubleshooting](/zh-CN/channels/whatsapp#troubleshooting) ## Telegram -### Telegram 故障特征 +### Telegram 失败特征 -| 症状 | 最快检查方式 | 修复方法 | +| 症状 | 最快检查 | 修复方法 | | ----------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------- | -| 有 `/start` 但没有可用的回复流程 | `openclaw pairing list telegram` | 批准配对，或更改私信策略。 | -| 机器人在线，但群组始终没有响应 | 验证提及要求和机器人的隐私模式 | 关闭隐私模式以获得群组可见性，或提及机器人。 | -| 发送失败并伴随网络错误 | 检查日志中的 Telegram API 调用失败 | 修复到 `api.telegram.org` 的 DNS/IPv6/代理路由。 | -| 启动时 `setMyCommands` 被拒绝 | 检查日志中的 `BOT_COMMANDS_TOO_MUCH` | 减少插件/Skills/自定义 Telegram 命令，或禁用原生菜单。 | -| 升级后允许列表将你拦截 | `openclaw security audit` 和配置允许列表 | 运行 `openclaw doctor --fix`，或将 `@username` 替换为数字发送者 ID。 | +| `/start` 之后没有可用的回复流程 | `openclaw pairing list telegram` | 批准配对，或更改 私信 策略。 | +| 机器人在线，但群组始终无响应 | 验证提及要求和机器人的隐私模式 | 为群组可见性禁用隐私模式，或提及机器人。 | +| 发送失败并出现网络错误 | 检查日志中的 Telegram API 调用失败 | 修复到 `api.telegram.org` 的 DNS / IPv6 / 代理路由。 | +| 启动时 `setMyCommands` 被拒绝 | 检查日志中的 `BOT_COMMANDS_TOO_MUCH` | 减少插件 / Skills / 自定义 Telegram 命令，或禁用原生菜单。 | +| 升级后允许列表把你拦住了 | `openclaw security audit` 和配置允许列表 | 运行 `openclaw doctor --fix`，或将 `@username` 替换为数字发送者 ID。 | -完整故障排除：[/channels/telegram#troubleshooting](/channels/telegram#troubleshooting) +完整故障排除：[/channels/telegram#troubleshooting](/zh-CN/channels/telegram#troubleshooting) ## Discord -### Discord 故障特征 +### Discord 失败特征 -| 症状 | 最快检查方式 | 修复方法 | +| 症状 | 最快检查 | 修复方法 | | ------------------------------- | ----------------------------------- | --------------------------------------------------------- | -| 机器人在线，但没有服务器回复 | `openclaw channels status --probe` | 允许该服务器/频道，并验证消息内容 intent。 | -| 群组消息被忽略 | 检查日志中是否有提及门控丢弃记录 | 提及机器人，或将服务器/频道的 `requireMention: false`。 | -| 私信回复缺失 | `openclaw pairing list discord` | 批准私信配对，或调整私信策略。 | +| 机器人在线，但没有服务器回复 | `openclaw channels status --probe` | 允许对应服务器 / 渠道，并验证消息内容 intent。 | +| 群组消息被忽略 | 检查日志中因提及门控而丢弃的记录 | 提及机器人，或将服务器 / 渠道的 `requireMention: false`。 | +| 私信 回复缺失 | `openclaw pairing list discord` | 批准 私信 配对，或调整 私信 策略。 | -完整故障排除：[/channels/discord#troubleshooting](/channels/discord#troubleshooting) +完整故障排除：[/channels/discord#troubleshooting](/zh-CN/channels/discord#troubleshooting) ## Slack -### Slack 故障特征 +### Slack 失败特征 -| 症状 | 最快检查方式 | 修复方法 | +| 症状 | 最快检查 | 修复方法 | | -------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| Socket mode 已连接但没有响应 | `openclaw channels status --probe` | 验证 app token + bot token 以及所需权限范围；对于使用 SecretRef 的配置，留意 `botTokenStatus` / `appTokenStatus = configured_unavailable`。 | -| 私信被阻止 | `openclaw pairing list slack` | 批准配对，或放宽私信策略。 | -| 频道消息被忽略 | 检查 `groupPolicy` 和频道允许列表 | 允许该频道，或将策略切换为 `open`。 | +| Socket 模式已连接但没有响应 | `openclaw channels status --probe` | 验证 app token + bot token 以及所需作用域；在使用 SecretRef 的配置中，注意查看 `botTokenStatus` / `appTokenStatus = configured_unavailable`。 | +| 私信 被拦截 | `openclaw pairing list slack` | 批准配对，或放宽 私信 策略。 | +| 渠道消息被忽略 | 检查 `groupPolicy` 和渠道允许列表 | 允许该渠道，或将策略切换为 `open`。 | -完整故障排除：[/channels/slack#troubleshooting](/channels/slack#troubleshooting) +完整故障排除：[/channels/slack#troubleshooting](/zh-CN/channels/slack#troubleshooting) ## iMessage 和 BlueBubbles -### iMessage 和 BlueBubbles 故障特征 +### iMessage 和 BlueBubbles 失败特征 -| 症状 | 最快检查方式 | 修复方法 | +| 症状 | 最快检查 | 修复方法 | | -------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------- | -| 没有入站事件 | 验证 webhook/服务器可达性和应用权限 | 修复 webhook URL 或 BlueBubbles 服务器状态。 | -| 在 macOS 上可以发送但无法接收 | 检查 Messages 自动化的 macOS 隐私权限 | 重新授予 TCC 权限并重启渠道进程。 | -| 私信发送者被阻止 | `openclaw pairing list imessage` 或 `openclaw pairing list bluebubbles` | 批准配对，或更新允许列表。 | +| 没有入站事件 | 验证 webhook / 服务器可达性和应用权限 | 修复 webhook URL 或 BlueBubbles 服务器状态。 | +| 在 macOS 上能发送但不能接收 | 检查 macOS 中 Messages 自动化的隐私权限 | 重新授予 TCC 权限并重启渠道进程。 | +| 私信 发送者被拦截 | `openclaw pairing list imessage` 或 `openclaw pairing list bluebubbles` | 批准配对，或更新允许列表。 | 完整故障排除： -- [/channels/imessage#troubleshooting](/channels/imessage#troubleshooting) -- [/channels/bluebubbles#troubleshooting](/channels/bluebubbles#troubleshooting) +- [/channels/imessage#troubleshooting](/zh-CN/channels/imessage#troubleshooting) +- [/channels/bluebubbles#troubleshooting](/zh-CN/channels/bluebubbles#troubleshooting) ## Signal -### Signal 故障特征 +### Signal 失败特征 -| 症状 | 最快检查方式 | 修复方法 | +| 症状 | 最快检查 | 修复方法 | | ------------------------------- | ------------------------------------------ | -------------------------------------------------------- | -| 守护进程可达，但机器人无响应 | `openclaw channels status --probe` | 验证 `signal-cli` 守护进程 URL/账号和接收模式。 | -| 私信被阻止 | `openclaw pairing list signal` | 批准发送者，或调整私信策略。 | -| 群组回复未触发 | 检查群组允许列表和提及模式 | 添加发送者/群组，或放宽门控规则。 | +| 守护进程可达，但机器人无响应 | `openclaw channels status --probe` | 验证 `signal-cli` 守护进程 URL / 账户以及接收模式。 | +| 私信 被拦截 | `openclaw pairing list signal` | 批准发送者，或调整 私信 策略。 | +| 群组回复未触发 | 检查群组允许列表和提及模式 | 添加发送者 / 群组，或放宽门控条件。 | -完整故障排除：[/channels/signal#troubleshooting](/channels/signal#troubleshooting) +完整故障排除：[/channels/signal#troubleshooting](/zh-CN/channels/signal#troubleshooting) ## QQ Bot -### QQ Bot 故障特征 +### QQ Bot 失败特征 -| 症状 | 最快检查方式 | 修复方法 | +| 症状 | 最快检查 | 修复方法 | | ------------------------------- | ------------------------------------------- | --------------------------------------------------------------- | | 机器人回复“去了火星” | 验证配置中的 `appId` 和 `clientSecret` | 设置凭证，或重启 Gateway 网关。 | | 没有入站消息 | `openclaw channels status --probe` | 在 QQ 开放平台上验证凭证。 | | 语音未转写 | 检查 STT 提供商配置 | 配置 `channels.qqbot.stt` 或 `tools.media.audio`。 | -| 主动消息未送达 | 检查 QQ 平台的交互要求 | 如果近期没有交互，QQ 可能会阻止机器人主动发送消息。 | +| 主动消息未送达 | 检查 QQ 平台的交互要求 | 如果近期没有交互，QQ 可能会阻止机器人主动发消息。 | -完整故障排除：[/channels/qqbot#troubleshooting](/channels/qqbot#troubleshooting) +完整故障排除：[/channels/qqbot#troubleshooting](/zh-CN/channels/qqbot#troubleshooting) ## Matrix -### Matrix 故障特征 +### Matrix 失败特征 -| 症状 | 最快检查方式 | 修复方法 | +| 症状 | 最快检查 | 修复方法 | | ----------------------------------- | -------------------------------------- | ------------------------------------------------------------------------- | | 已登录但忽略房间消息 | `openclaw channels status --probe` | 检查 `groupPolicy`、房间允许列表和提及门控。 | -| 私信不处理 | `openclaw pairing list matrix` | 批准发送者，或调整私信策略。 | +| 私信 不处理 | `openclaw pairing list matrix` | 批准发送者，或调整 私信 策略。 | | 加密房间失败 | `openclaw matrix verify status` | 重新验证设备，然后检查 `openclaw matrix verify backup status`。 | -| 备份恢复处于待处理/损坏状态 | `openclaw matrix verify backup status` | 运行 `openclaw matrix verify backup restore`，或使用恢复密钥重新运行。 | -| 交叉签名/bootstrap 看起来不正常 | `openclaw matrix verify bootstrap` | 一次性修复密钥存储、交叉签名和备份状态。 | +| 备份恢复处于待处理 / 已损坏 | `openclaw matrix verify backup status` | 运行 `openclaw matrix verify backup restore`，或使用恢复密钥重新运行。 | +| 交叉签名 / 引导看起来异常 | `openclaw matrix verify bootstrap` | 一次性修复密钥存储、交叉签名和备份状态。 | -完整设置和配置：[Matrix](/channels/matrix) +完整设置和配置：[Matrix](/zh-CN/channels/matrix) diff --git a/docs/zh-CN/gateway/index.md b/docs/zh-CN/gateway/index.md index e326846b8..d7bef276b 100644 --- a/docs/zh-CN/gateway/index.md +++ b/docs/zh-CN/gateway/index.md @@ -1,33 +1,33 @@ --- read_when: - 运行或调试 Gateway 网关进程 -summary: Gateway 网关服务、生命周期和运维的运行手册 -title: Gateway 网关运行手册 +summary: Gateway 网关服务、生命周期与运维的操作手册 +title: Gateway 网关操作手册 x-i18n: - generated_at: "2026-04-06T15:28:29Z" + generated_at: "2026-04-20T06:30:59Z" model: gpt-5.4 provider: openai - source_hash: fd2c21036e88612861ef2195b8ff7205aca31386bb11558614ade8d1a54fdebd + source_hash: e1004cdd43b1db6794f3ca83da38dbdb231a1976329d9d6d851e2b02405278d8 source_path: gateway/index.md workflow: 15 --- -# Gateway 网关运行手册 +# Gateway 网关操作手册 -将此页面用于 Gateway 网关服务的首日启动和后续运维。 +将此页面用于 Gateway 网关服务的第 1 天启动和第 2 天运维操作。 - 按症状优先的诊断，附带精确的命令步骤和日志特征。 + 按症状优先的诊断，提供精确的命令步骤和日志特征。 面向任务的设置指南 + 完整配置参考。 - SecretRef 合约、运行时快照行为，以及迁移/重载操作。 + `SecretRef` 合约、运行时快照行为，以及迁移/重新加载操作。 - 精确的 `secrets apply` 目标/路径规则，以及仅 ref 的 auth-profile 行为。 + 精确的 `secrets apply` 目标/路径规则，以及仅引用的 auth-profile 行为。 @@ -38,7 +38,7 @@ x-i18n: ```bash openclaw gateway --port 18789 -# 调试/跟踪输出镜像到 stdio +# debug/trace 镜像输出到 stdio openclaw gateway --port 18789 --verbose # 强制终止所选端口上的监听器，然后启动 openclaw gateway --force @@ -54,7 +54,7 @@ openclaw status openclaw logs --follow ``` -健康基线：`Runtime: running` 和 `RPC probe: ok`。 +健康基线：`Runtime: running`、`Connectivity probe: ok`，以及与你预期匹配的 `Capability: ...`。当你需要读取范围的 RPC 证明，而不仅仅是可达性时，请使用 `openclaw gateway status --require-rpc`。 @@ -64,33 +64,35 @@ openclaw logs --follow openclaw channels status --probe ``` -当 Gateway 网关可达时，这会运行按账户划分的实时渠道探测和可选审计。 -如果 Gateway 网关不可达，CLI 会回退为仅基于配置的渠道摘要，而不是实时探测输出。 +当 Gateway 网关可达时，这会按账户运行实时的渠道探测和可选审计。 +如果 Gateway 网关不可达，CLI 会回退到仅基于配置的渠道摘要， +而不是实时探测输出。 -Gateway 网关配置重载会监听活动配置文件路径（从 profile/state 默认值解析，或在设置了 `OPENCLAW_CONFIG_PATH` 时使用该值）。 +Gateway 网关配置重载会监视当前激活的配置文件路径（从 profile/state 默认值解析，或在设置时使用 `OPENCLAW_CONFIG_PATH`）。 默认模式为 `gateway.reload.mode="hybrid"`。 -首次成功加载后，运行中的进程会提供当前内存中的活动配置快照；成功重载后会以原子方式替换该快照。 +首次成功加载后，运行中的进程会提供当前激活的内存配置快照；成功重载后会原子性地替换该快照。 ## 运行时模型 -- 一个始终在线的进程，用于路由、控制平面和渠道连接。 -- 一个复用的单端口，用于： +- 一个始终运行的进程，用于路由、控制平面和渠道连接。 +- 一个用于以下内容的单一复用端口： - WebSocket 控制/RPC - - HTTP API、与 OpenAI 兼容（`/v1/models`、`/v1/embeddings`、`/v1/chat/completions`、`/v1/responses`、`/tools/invoke`） + - HTTP API、OpenAI 兼容接口（`/v1/models`、`/v1/embeddings`、`/v1/chat/completions`、`/v1/responses`、`/tools/invoke`） - Control UI 和 hooks - 默认绑定模式：`loopback`。 -- 默认要求身份验证。共享密钥设置使用 +- 默认需要认证。共享密钥设置使用 `gateway.auth.token` / `gateway.auth.password`（或 - `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`），非 loopback 的反向代理设置可以使用 `gateway.auth.mode: "trusted-proxy"`。 + `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`），而非 `loopback` + 的反向代理设置可以使用 `gateway.auth.mode: "trusted-proxy"`。 -## 与 OpenAI 兼容的端点 +## OpenAI 兼容端点 -OpenClaw 当前最有价值的兼容性接口是： +OpenClaw 现在最有价值的兼容性接口为： - `GET /v1/models` - `GET /v1/models/{id}` @@ -98,19 +100,19 @@ OpenClaw 当前最有价值的兼容性接口是： - `POST /v1/chat/completions` - `POST /v1/responses` -为什么这组接口很重要： +为什么这一组很重要： -- 大多数 Open WebUI、LobeChat 和 LibreChat 集成都会先探测 `/v1/models`。 -- 许多 RAG 和记忆管道都依赖 `/v1/embeddings`。 +- 大多数 Open WebUI、LobeChat 和 LibreChat 集成会先探测 `/v1/models`。 +- 许多 RAG 和 memory 流水线依赖 `/v1/embeddings`。 - 原生面向智能体的客户端越来越倾向于使用 `/v1/responses`。 规划说明： - `/v1/models` 以智能体优先：它会返回 `openclaw`、`openclaw/default` 和 `openclaw/`。 - `openclaw/default` 是稳定别名，始终映射到已配置的默认智能体。 -- 当你想覆盖后端提供商/模型时，请使用 `x-openclaw-model`；否则，选定智能体的常规模型和嵌入设置仍然会保持控制权。 +- 如果你想覆盖后端 provider/model，请使用 `x-openclaw-model`；否则将继续由所选智能体的常规模型和 embedding 设置进行控制。 -所有这些都运行在主 Gateway 网关端口上，并与 Gateway 网关其余 HTTP API 共享同一个受信任操作员身份验证边界。 +所有这些都运行在 Gateway 网关主端口上，并使用与 Gateway 网关其余 HTTP API 相同的可信操作员认证边界。 ### 端口和绑定优先级 @@ -124,9 +126,9 @@ OpenClaw 当前最有价值的兼容性接口是： | `gateway.reload.mode` | 行为 | | --------------------- | ------------------------------------------ | | `off` | 不进行配置重载 | -| `hot` | 仅应用热安全变更 | -| `restart` | 遇到需要重载的变更时重启 | -| `hybrid`（默认） | 安全时热应用，需要时重启 | +| `hot` | 仅应用热更新安全的变更 | +| `restart` | 遇到需要重启的变更时重启 | +| `hybrid` （默认） | 安全时热应用，需要时重启 | ## 操作员命令集 @@ -143,14 +145,14 @@ openclaw doctor ``` `gateway status --deep` 用于额外的服务发现（LaunchDaemons/systemd 系统 -单元/schtasks），而不是更深入的 RPC 健康探测。 +units/schtasks），而不是更深入的 RPC 健康探测。 ## 多个 Gateway 网关（同一主机） -大多数安装应当每台机器运行一个 Gateway 网关。单个 Gateway 网关可以托管多个 +大多数安装应在每台机器上运行一个 Gateway 网关。单个 Gateway 网关可以承载多个 智能体和渠道。 -只有当你有意需要隔离或救援机器人时，才需要多个 Gateway 网关。 +只有当你明确需要隔离或一个救援 bot 时，才需要多个 Gateway 网关。 有用的检查： @@ -159,12 +161,12 @@ openclaw gateway status --deep openclaw gateway probe ``` -预期结果： +预期表现： - `gateway status --deep` 可能会报告 `Other gateway-like services detected (best effort)` - 并在仍然存在陈旧的 launchd/systemd/schtasks 安装时打印清理提示。 -- 当有多个目标响应时，`gateway probe` 可能会警告 `multiple reachable gateways`。 -- 如果这是有意的，请为每个 Gateway 网关隔离端口、配置/state 和工作区根目录。 + 并在仍存在陈旧的 launchd/systemd/schtasks 安装时打印清理提示。 +- 当多个目标都有响应时，`gateway probe` 可能会警告 `multiple reachable gateways`。 +- 如果这是有意为之，请为每个 Gateway 网关隔离端口、配置/state 和 workspace 根目录。 详细设置：[/gateway/multiple-gateways](/zh-CN/gateway/multiple-gateways)。 @@ -177,18 +179,19 @@ openclaw gateway probe ssh -N -L 18789:127.0.0.1:18789 user@host ``` -然后在本地将客户端连接到 `ws://127.0.0.1:18789`。 +然后让客户端在本地连接到 `ws://127.0.0.1:18789`。 -SSH 隧道不会绕过 Gateway 网关身份验证。对于共享密钥身份验证，即使通过隧道，客户端仍然 -必须发送 `token`/`password`。对于带身份模式，请求仍然必须满足该身份验证路径。 +SSH 隧道不会绕过 Gateway 网关认证。对于共享密钥认证，即使通过隧道，客户端 +仍然必须发送 `token`/`password`。对于带身份的模式， +请求仍然必须满足该认证路径。 -参见：[Remote Gateway](/zh-CN/gateway/remote)、[Authentication](/zh-CN/gateway/authentication)、[Tailscale](/zh-CN/gateway/tailscale)。 +参见：[远程 Gateway 网关](/zh-CN/gateway/remote)、[认证](/zh-CN/gateway/authentication)、[Tailscale](/zh-CN/gateway/tailscale)。 -## 监督与服务生命周期 +## 监管和服务生命周期 -对于接近生产环境的可靠性，请使用受监督的运行方式。 +为了获得接近生产环境的可靠性，请使用受监管的运行方式。 @@ -200,7 +203,7 @@ openclaw gateway restart openclaw gateway stop ``` -LaunchAgent 标签是 `ai.openclaw.gateway`（默认）或 `ai.openclaw.`（命名 profile）。`openclaw doctor` 会审计并修复服务配置漂移。 +LaunchAgent 标签为 `ai.openclaw.gateway`（默认）或 `ai.openclaw.`（命名 profile）。`openclaw doctor` 会审计并修复服务配置漂移。 @@ -212,13 +215,13 @@ systemctl --user enable --now openclaw-gateway[-].service openclaw gateway status ``` -要在注销后继续持久运行，请启用 lingering： +要在登出后保持持久运行，请启用 lingering： ```bash sudo loginctl enable-linger ``` -当你需要自定义安装路径时，可使用以下手动用户单元示例： +当你需要自定义安装路径时，可使用手动用户 unit 示例： ```ini [Unit] @@ -251,30 +254,31 @@ openclaw gateway stop ``` 原生 Windows 托管启动使用名为 `OpenClaw Gateway` -的计划任务（命名 profile 则为 `OpenClaw Gateway ()`）。如果计划任务 -创建被拒绝，OpenClaw 会回退到每用户 Startup 文件夹启动器，该启动器指向 state 目录中的 `gateway.cmd`。 +的计划任务（对于命名 profile，则为 `OpenClaw Gateway ()`）。如果计划任务 +创建被拒绝，OpenClaw 会回退到每用户 Startup 文件夹启动器， +其指向 state 目录中的 `gateway.cmd`。 -对多用户/始终在线的主机，请使用系统单元。 +对多用户/始终在线主机，请使用系统 unit。 ```bash sudo systemctl daemon-reload sudo systemctl enable --now openclaw-gateway[-].service ``` -使用与用户单元相同的服务主体，但将其安装到 -`/etc/systemd/system/openclaw-gateway[-].service` 下，并在你的 `openclaw` 二进制位于其他位置时调整 -`ExecStart=`。 +使用与用户 unit 相同的服务主体，但将其安装到 +`/etc/systemd/system/openclaw-gateway[-].service` 下，并在你的 +`openclaw` 二进制文件位于其他位置时调整 `ExecStart=`。 ## 一台主机上的多个 Gateway 网关 -大多数设置应该只运行**一个** Gateway 网关。 +大多数设置应只运行**一个** Gateway 网关。 只有在需要严格隔离/冗余时才使用多个（例如救援 profile）。 每个实例的检查清单： @@ -291,7 +295,7 @@ OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a opencla OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002 ``` -参见：[Multiple gateways](/zh-CN/gateway/multiple-gateways)。 +参见：[多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。 ### 开发 profile 快速路径 @@ -301,25 +305,25 @@ openclaw --dev gateway --allow-unconfigured openclaw --dev status ``` -默认值包括隔离的 state/config 和基础 Gateway 网关端口 `19001`。 +默认值包括隔离的 state/config，以及基础 Gateway 网关端口 `19001`。 ## 协议快速参考（操作员视角） - 第一个客户端帧必须是 `connect`。 - Gateway 网关返回 `hello-ok` 快照（`presence`、`health`、`stateVersion`、`uptimeMs`、limits/policy）。 - `hello-ok.features.methods` / `events` 是保守的发现列表，而不是 - 对每个可调用辅助路由的自动生成完整导出。 + 每个可调用辅助路由的自动生成清单。 - 请求：`req(method, params)` → `res(ok/payload|error)`。 - 常见事件包括 `connect.challenge`、`agent`、`chat`、 `session.message`、`session.tool`、`sessions.changed`、`presence`、`tick`、 - `health`、`heartbeat`、配对/审批生命周期事件，以及 `shutdown`。 + `health`、`heartbeat`、pairing/approval 生命周期事件以及 `shutdown`。 -智能体运行分两个阶段： +智能体运行分为两个阶段： 1. 立即接受确认（`status:"accepted"`） -2. 最终完成响应（`status:"ok"|"error"`），中间会流式发送 `agent` 事件。 +2. 最终完成响应（`status:"ok"|"error"`），其间会流式发送 `agent` 事件。 -完整协议文档参见：[Gateway Protocol](/zh-CN/gateway/protocol)。 +查看完整协议文档：[Gateway 协议](/zh-CN/gateway/protocol)。 ## 运维检查 @@ -328,7 +332,7 @@ openclaw --dev status - 打开 WS 并发送 `connect`。 - 预期收到带快照的 `hello-ok` 响应。 -### 就绪性 +### 就绪状态 ```bash openclaw gateway status @@ -336,26 +340,26 @@ openclaw channels status --probe openclaw health ``` -### 间隙恢复 +### 缺口恢复 -事件不会重放。遇到序列缺口时，请先刷新状态（`health`、`system-presence`）再继续。 +事件不会重放。出现序列缺口时，在继续之前刷新状态（`health`、`system-presence`）。 ## 常见故障特征 | 特征 | 可能问题 | | -------------------------------------------------------------- | ------------------------------------------------------------------------------- | -| `refusing to bind gateway ... without auth` | 非 loopback 绑定且没有有效的 Gateway 网关身份验证路径 | +| `refusing to bind gateway ... without auth` | 非 `loopback` 绑定，但没有有效的 Gateway 网关认证路径 | | `another gateway instance is already listening` / `EADDRINUSE` | 端口冲突 | | `Gateway start blocked: set gateway.mode=local` | 配置被设为远程模式，或损坏配置中缺少本地模式标记 | -| `unauthorized` during connect | 客户端与 Gateway 网关之间的身份验证不匹配 | +| `unauthorized` during connect | 客户端与 Gateway 网关之间的认证不匹配 | -如需完整诊断步骤，请使用 [Gateway 故障排除](/zh-CN/gateway/troubleshooting)。 +如需完整的诊断步骤，请使用 [Gateway 故障排除](/zh-CN/gateway/troubleshooting)。 ## 安全保证 -- 当 Gateway 网关不可用时，Gateway 网关协议客户端会快速失败（不会隐式回退到直接渠道）。 -- 无效的首帧或非 `connect` 首帧会被拒绝并关闭连接。 -- 优雅关闭会在 socket 关闭前发送 `shutdown` 事件。 +- 当 Gateway 网关不可用时，Gateway 协议客户端会快速失败（不会隐式回退到直接渠道）。 +- 无效的/非 `connect` 的首帧会被拒绝并关闭连接。 +- 优雅关闭会在 socket 关闭前发出 `shutdown` 事件。 --- @@ -364,6 +368,6 @@ openclaw health - [故障排除](/zh-CN/gateway/troubleshooting) - [后台进程](/zh-CN/gateway/background-process) - [配置](/zh-CN/gateway/configuration) -- [健康状态](/zh-CN/gateway/health) +- [健康](/zh-CN/gateway/health) - [Doctor](/zh-CN/gateway/doctor) -- [身份验证](/zh-CN/gateway/authentication) +- [认证](/zh-CN/gateway/authentication) diff --git a/docs/zh-CN/gateway/troubleshooting.md b/docs/zh-CN/gateway/troubleshooting.md index 1b8462174..99f147980 100644 --- a/docs/zh-CN/gateway/troubleshooting.md +++ b/docs/zh-CN/gateway/troubleshooting.md @@ -1,14 +1,14 @@ --- read_when: - - 故障排除中心已将你引导到此处，以进行更深入的诊断 - - 你需要按症状分类且稳定的运行手册章节，并提供精确命令 + - 故障排除中心将你指向这里，以便进行更深入的诊断 + - 你需要基于稳定症状的运行手册章节，并提供精确命令 summary: Gateway 网关、渠道、自动化、节点和浏览器的深度故障排除运行手册 title: 故障排除 x-i18n: - generated_at: "2026-04-10T20:41:20Z" + generated_at: "2026-04-20T06:31:00Z" model: gpt-5.4 provider: openai - source_hash: 7ef2faccba26ede307861504043a6415bc1f12dc64407771106f63ddc5b107f5 + source_hash: 853275aaf4ebddb9d2fd358df2e9fdc893dafdc7960d69c4f145ce615d5cbc1e source_path: gateway/troubleshooting.md workflow: 15 --- @@ -16,11 +16,11 @@ x-i18n: # Gateway 网关故障排除 此页面是深度运行手册。 -如果你想先使用快速分诊流程，请从 [/help/troubleshooting](/zh-CN/help/troubleshooting) 开始。 +如果你想先走快速分诊流程，请从 [/help/troubleshooting](/zh-CN/help/troubleshooting) 开始。 ## 命令阶梯 -先运行以下命令，按此顺序执行： +先按以下顺序运行这些命令： ```bash openclaw status @@ -32,13 +32,13 @@ openclaw channels status --probe 预期的健康信号： -- `openclaw gateway status` 显示 `Runtime: running` 和 `RPC probe: ok`。 +- `openclaw gateway status` 显示 `Runtime: running`、`Connectivity probe: ok` 和一行 `Capability: ...`。 - `openclaw doctor` 报告没有阻塞性的配置或服务问题。 -- `openclaw channels status --probe` 显示每个账号的实时传输状态，并在支持的情况下显示探测/审计结果，例如 `works` 或 `audit ok`。 +- `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 @@ -47,17 +47,17 @@ openclaw models status openclaw config get agents.defaults.models ``` -请检查： +检查以下内容： -- 所选的 Anthropic Opus/Sonnet 模型设置了 `params.context1m: true`。 -- 当前的 Anthropic 凭证不具备长上下文使用资格。 +- 选中的 Anthropic Opus/Sonnet 模型设置了 `params.context1m: true`。 +- 当前的 Anthropic 凭证没有长上下文使用资格。 - 请求只会在需要走 1M beta 路径的长会话或模型运行中失败。 修复选项： -1. 为该模型禁用 `context1m`，回退到普通上下文窗口。 +1. 为该模型禁用 `context1m`，回退到正常上下文窗口。 2. 使用具备长上下文请求资格的 Anthropic 凭证，或切换到 Anthropic API key。 -3. 配置回退模型，以便在 Anthropic 长上下文请求被拒绝时运行仍可继续。 +3. 配置回退模型，这样当 Anthropic 长上下文请求被拒绝时，运行仍可继续。 相关内容： @@ -65,12 +65,12 @@ 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 兼容后端可通过直接探测，但智能体运行失败 +## 本地 OpenAI 兼容后端直接探测通过，但智能体运行失败 -在以下情况使用本节： +当出现以下情况时，使用本节： -- `curl ... /v1/models` 可用 -- 很小的直接 `/v1/chat/completions` 调用可用 +- `curl ... /v1/models` 可以工作 +- 很小的直接 `/v1/chat/completions` 调用可以工作 - OpenClaw 模型运行只在正常智能体轮次中失败 ```bash @@ -82,24 +82,24 @@ openclaw infer model run --model --prompt "hi" --json openclaw logs --follow ``` -请检查： +检查以下内容： -- 直接的小请求成功，但 OpenClaw 运行只在较大提示词时失败 -- 后端报错指出 `messages[].content` 期望的是字符串 -- 后端崩溃只出现在较大的提示词 token 数或完整智能体运行时提示词下 +- 很小的直接调用成功，但 OpenClaw 运行只在更大的提示词下失败 +- 后端报错 `messages[].content` 期望是字符串 +- 后端只会在更大的提示词 token 数量或完整智能体运行时提示词下崩溃 常见特征： - `messages[...].content: invalid type: sequence, expected a string` → 后端拒绝结构化的 Chat Completions 内容片段。修复方法：设置 `models.providers..models[].compat.requiresStringContent: true`。 -- 直接的小请求成功，但 OpenClaw 智能体运行因后端/模型崩溃而失败（例如某些 `inferrs` 版本上的 Gemma）→ OpenClaw 传输层很可能已经正确；失败的是后端无法处理更大的智能体运行时提示词形态。 -- 禁用工具后失败有所减少但未消失 → 工具 schema 是压力来源之一，但剩余问题仍然是上游模型/服务端容量限制或后端 bug。 +- 很小的直接请求成功，但 OpenClaw 智能体运行因后端或模型崩溃而失败（例如某些 `inferrs` 构建上的 Gemma）→ OpenClaw 传输层很可能已经正确；失败的是后端无法处理更大的智能体运行时提示词形状。 +- 禁用工具后失败减少但没有消失 → 工具 schema 是压力来源之一，但剩余问题仍然是上游模型/服务器容量不足，或后端 bug。 修复选项： -1. 为仅支持字符串 Chat Completions 的后端设置 `compat.requiresStringContent: true`。 -2. 对无法可靠处理 OpenClaw 工具 schema 表面的模型/后端设置 `compat.supportsTools: false`。 -3. 尽可能降低提示词压力：更小的工作区启动内容、更短的会话历史、更轻量的本地模型，或选择对长上下文支持更强的后端。 -4. 如果直接的小请求持续成功，而 OpenClaw 智能体轮次仍在后端内部崩溃，请将其视为上游服务端/模型限制，并向上游提交一个基于已接受载荷形态的复现问题。 +1. 为仅支持字符串内容的 Chat Completions 后端设置 `compat.requiresStringContent: true`。 +2. 为无法可靠处理 OpenClaw 工具 schema 表面的模型或后端设置 `compat.supportsTools: false`。 +3. 在可能的情况下减轻提示词压力：更小的工作区引导、更短的会话历史、更轻量的本地模型，或更强长上下文支持的后端。 +4. 如果很小的直接请求持续通过，但 OpenClaw 智能体轮次仍在后端内部崩溃，请将其视为上游服务器或模型限制，并基于已接受的 payload 形状向上游提交复现案例。 相关内容： @@ -107,9 +107,9 @@ openclaw logs --follow - [/gateway/configuration](/zh-CN/gateway/configuration) - [/gateway/configuration-reference#openai-compatible-endpoints](/zh-CN/gateway/configuration-reference#openai-compatible-endpoints) -## 无回复 +## 没有回复 -如果渠道已上线但没有任何回复，请先检查路由和策略，不要急着重连任何东西。 +如果渠道已连通但没有任何响应，在重新连接任何内容之前，先检查路由和策略。 ```bash openclaw status @@ -119,17 +119,17 @@ openclaw config get channels openclaw logs --follow ``` -请检查： +检查以下内容： -- 私信发送者的配对是否处于待处理状态。 -- 群组提及限制（`requireMention`、`mentionPatterns`）。 -- 渠道/群组 allowlist 是否不匹配。 +- 私信发送者的配对仍在等待批准。 +- 群组提及门控（`requireMention`、`mentionPatterns`）。 +- 渠道或群组允许列表不匹配。 常见特征： -- `drop guild message (mention required` → 群消息在被提及之前会被忽略。 -- `pairing request` → 发送者需要获批。 -- `blocked` / `allowlist` → 发送者或渠道被策略过滤。 +- `drop guild message (mention required` → 群消息会被忽略，直到出现提及。 +- `pairing request` → 发送者需要审批。 +- `blocked` / `allowlist` → 发送者或渠道被策略过滤了。 相关内容： @@ -137,9 +137,9 @@ openclaw logs --follow - [/channels/pairing](/zh-CN/channels/pairing) - [/channels/groups](/zh-CN/channels/groups) -## Dashboard 控制 UI 连接问题 +## 仪表板控制 UI 连接问题 -当 dashboard/控制 UI 无法连接时，请验证 URL、认证模式和安全上下文假设。 +当仪表板 / 控制 UI 无法连接时，请验证 URL、认证模式和安全上下文假设。 ```bash openclaw gateway status @@ -149,36 +149,36 @@ openclaw doctor openclaw gateway status --json ``` -请检查： +检查以下内容： -- 探测 URL 和 dashboard URL 是否正确。 -- 客户端与 Gateway 网关之间的认证模式或令牌是否不匹配。 -- 是否在需要设备身份的场景下使用了 HTTP。 +- 正确的探测 URL 和仪表板 URL。 +- 客户端与 Gateway 网关之间的认证模式或 token 不匹配。 +- 在需要设备身份的情况下使用了 HTTP。 常见特征： -- `device identity required` → 非安全上下文，或缺少设备认证。 -- `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` → 客户端可以使用缓存的设备令牌执行一次可信重试。 -- 该缓存令牌重试会复用与已配对设备令牌一同存储的缓存作用域集合。显式 `deviceToken` / 显式 `scopes` 调用方则保持其请求的作用域集合不变。 -- 在该重试路径之外，连接认证优先级依次为：显式共享令牌/密码优先，然后是显式 `deviceToken`，再然后是已存储设备令牌，最后是 bootstrap 令牌。 -- 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, ip}` 的失败尝试会在限流器记录失败之前被串行化。因此，同一客户端的两个错误并发重试，第二次可能显示 `retry later`，而不是出现两个普通的不匹配错误。 -- 浏览器源 loopback 客户端出现 `too many failed authentication attempts (retry later)` → 来自同一规范化 `Origin` 的重复失败会被临时锁定；另一个 localhost 源会使用单独的桶。 -- 在该重试之后仍反复出现 `unauthorized` → 共享令牌或设备令牌已漂移；如果需要，请刷新令牌配置，并重新批准/轮换设备令牌。 -- `gateway connect failed:` → 主机、端口或 URL 目标错误。 +- `device identity required` → 非安全上下文或缺少设备认证。 +- `origin not allowed` → 浏览器的 `Origin` 不在 `gateway.controlUi.allowedOrigins` 中（或者你正从非 loopback 的浏览器源发起连接，但未显式加入允许列表）。 +- `device nonce required` / `device nonce mismatch` → 客户端未完成基于质询的设备认证流程（`connect.challenge` + `device.nonce`）。 +- `device signature invalid` / `device signature expired` → 客户端为当前握手签署了错误的 payload（或使用了过期时间戳）。 +- 带有 `canRetryWithDeviceToken=true` 的 `AUTH_TOKEN_MISMATCH` → 客户端可以使用缓存的设备 token 执行一次可信重试。 +- 该缓存 token 重试会复用与已配对设备 token 一起存储的缓存 scope 集。显式传入 `deviceToken` / 显式传入 `scopes` 的调用方则保留其请求的 scope 集。 +- 在该重试路径之外，连接认证优先级依次为：显式共享 token / password，接着是显式 `deviceToken`，再接着是已存储的设备 token，最后是 bootstrap token。 +- 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, ip}` 的失败尝试会在限流器记录失败之前被串行化。因此，同一客户端并发发起两次错误重试时，第二次可能会返回 `retry later`，而不是两个普通的不匹配错误。 +- 来自浏览器源 loopback 客户端的 `too many failed authentication attempts (retry later)` → 来自同一标准化 `Origin` 的重复失败会被临时锁定；另一个 localhost 源会使用单独的桶。 +- 在该重试之后仍然重复出现 `unauthorized` → 共享 token 或设备 token 已漂移；如有需要，请刷新 token 配置并重新批准或轮换设备 token。 +- `gateway connect failed:` → host / port / url 目标错误。 -### 认证详情代码速查表 +### 认证细节代码快速对照表 -使用失败的 `connect` 响应中的 `error.details.code` 来决定下一步操作： +使用失败 `connect` 响应中的 `error.details.code` 来决定下一步操作： -| 详情代码 | 含义 | 建议操作 | -| ---------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AUTH_TOKEN_MISSING` | 客户端未发送必需的共享令牌。 | 在客户端中粘贴/设置令牌后重试。对于 dashboard 路径：`openclaw config get gateway.auth.token`，然后将其粘贴到 Control UI 设置中。 | -| `AUTH_TOKEN_MISMATCH` | 共享令牌与 Gateway 网关认证令牌不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许一次可信重试。缓存令牌重试会复用已存储的已批准作用域；显式 `deviceToken` / `scopes` 调用方则保持请求的作用域不变。如果仍失败，请运行 [token drift recovery checklist](/cli/devices#token-drift-recovery-checklist)。 | -| `AUTH_DEVICE_TOKEN_MISMATCH` | 每设备缓存令牌已过期或被撤销。 | 使用 [devices CLI](/cli/devices) 轮换或重新批准设备令牌，然后重新连接。 | -| `PAIRING_REQUIRED` | 设备身份已知，但未获批用于此角色。 | 批准待处理请求：`openclaw devices list`，然后 `openclaw devices approve `。 | +| 细节代码 | 含义 | 建议操作 | +| ---------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AUTH_TOKEN_MISSING` | 客户端没有发送必需的共享 token。 | 在客户端中粘贴或设置该 token，然后重试。对于仪表板路径：`openclaw config get gateway.auth.token`，然后将其粘贴到 Control UI 设置中。 | +| `AUTH_TOKEN_MISMATCH` | 共享 token 与 Gateway 网关认证 token 不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许一次可信重试。缓存 token 重试会复用已存储的已批准 scope；显式 `deviceToken` / `scopes` 调用方则保留请求的 scope。如果仍然失败，请运行 [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 `。 | 设备认证 v2 迁移检查： @@ -188,16 +188,16 @@ openclaw doctor openclaw gateway status ``` -如果日志显示 nonce/签名错误，请更新正在连接的客户端，并验证它是否： +如果日志显示 nonce 或 signature 错误，请更新正在连接的客户端，并确认它： 1. 等待 `connect.challenge` -2. 对绑定该 challenge 的载荷进行签名 -3. 在 `connect.params.device.nonce` 中发送相同的 challenge nonce +2. 对绑定到 challenge 的 payload 进行签名 +3. 使用相同的 challenge nonce 发送 `connect.params.device.nonce` -如果 `openclaw devices rotate` / `revoke` / `remove` 意外被拒绝： +如果 `openclaw devices rotate` / `revoke` / `remove` 被意外拒绝： -- 已配对设备令牌会话只能管理**它们自己的**设备，除非调用方同时具有 `operator.admin` -- `openclaw devices rotate --scope ...` 只能请求调用方会话已经持有的 operator 作用域 +- 已配对设备的 token 会话只能管理**它们自己的**设备，除非调用方同时具有 `operator.admin` +- `openclaw devices rotate --scope ...` 只能请求调用方当前会话已经持有的 operator scope 相关内容： @@ -209,7 +209,7 @@ openclaw gateway status ## Gateway 网关服务未运行 -当服务已安装但进程无法持续运行时使用本节。 +当服务已安装但进程无法保持运行时，使用本节。 ```bash openclaw gateway status @@ -219,20 +219,20 @@ openclaw doctor openclaw gateway status --deep # 也会扫描系统级服务 ``` -请检查： +检查以下内容： -- `Runtime: stopped` 以及退出提示。 -- 服务配置不匹配（`Config (cli)` 对比 `Config (service)`）。 +- `Runtime: stopped`，并带有退出提示。 +- 服务配置不匹配（`Config (cli)` 与 `Config (service)`）。 - 端口或监听器冲突。 -- 使用 `--deep` 时是否存在额外的 launchd/systemd/schtasks 安装。 +- 使用 `--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 网关认证路径（令牌/密码，或在已配置时使用 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` → 在没有有效 Gateway 网关认证路径的情况下绑定到非 loopback 地址（token / password，或已配置的 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)。 相关内容： @@ -242,7 +242,7 @@ openclaw gateway status --deep # 也会扫描系统级服务 ## Gateway 网关探测警告 -当 `openclaw gateway probe` 能探测到目标，但仍打印警告块时使用本节。 +当 `openclaw gateway probe` 能探测到目标，但仍打印出警告块时，使用本节。 ```bash openclaw gateway probe @@ -250,17 +250,18 @@ openclaw gateway probe --json openclaw gateway probe --ssh user@gateway-host ``` -请检查： +检查以下内容： - JSON 输出中的 `warnings[].code` 和 `primaryTargetId`。 -- 警告是否与 SSH 回退、多个 Gateway 网关、缺少作用域或未解析的认证引用有关。 +- 警告是否与 SSH 回退、多个 Gateway 网关、缺失 scope，或未解析的认证引用有关。 常见特征： -- `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 警告文本 → 在该命令路径中，失败目标所需的认证材料不可用。 +- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但该命令仍尝试了直接配置目标或 loopback 目标。 +- `multiple reachable gateways detected` → 检测到多个可达目标有响应。通常意味着这是有意的多 Gateway 网关部署，或存在过期/重复监听器。 +- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接成功，但详细 RPC 受 scope 限制；请配对设备身份或使用带有 `operator.read` 的凭证。 +- `Capability: pairing-pending` 或 `gateway closed (1008): pairing required` → Gateway 网关已响应，但该客户端在获得正常 operator 访问前仍需要完成配对或审批。 +- 未解析的 `gateway.auth.*` / `gateway.remote.*` SecretRef 警告文本 → 在此命令路径中，失败目标的认证材料不可用。 相关内容： @@ -268,9 +269,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 @@ -280,16 +281,16 @@ openclaw logs --follow openclaw config get channels ``` -请检查： +检查以下内容： - 私信策略（`pairing`、`allowlist`、`open`、`disabled`）。 -- 群组 allowlist 和提及要求。 +- 群组允许列表和提及要求。 - 缺失的渠道 API 权限或 scopes。 常见特征： - `mention required` → 消息因群组提及策略而被忽略。 -- `pairing` / 待批准痕迹 → 发送者尚未获批。 +- `pairing` / 待审批痕迹 → 发送者尚未获批。 - `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → 渠道认证或权限问题。 相关内容： @@ -301,7 +302,7 @@ openclaw config get channels ## Cron 和 heartbeat 投递 -如果 cron 或 heartbeat 没有运行，或者运行了但未投递，请先验证调度器状态，再检查投递目标。 +如果 cron 或 heartbeat 没有运行，或者运行了但没有投递，请先验证调度器状态，再检查投递目标。 ```bash openclaw cron status @@ -311,9 +312,9 @@ openclaw system heartbeat last openclaw logs --follow ``` -请检查： +检查以下内容： -- Cron 已启用，并存在下一次唤醒时间。 +- Cron 已启用，并且存在下次唤醒时间。 - 作业运行历史状态（`ok`、`skipped`、`error`）。 - Heartbeat 跳过原因（`quiet-hours`、`requests-in-flight`、`alerts-disabled`、`empty-heartbeat-file`、`no-tasks-due`）。 @@ -321,11 +322,11 @@ openclaw logs --follow - `cron: scheduler disabled; jobs will not run automatically` → cron 已禁用。 - `cron: timer tick failed` → 调度器 tick 失败；请检查文件、日志或运行时错误。 -- `heartbeat skipped` 且 `reason=quiet-hours` → 当前处于活跃时间窗口之外。 +- `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` → heartbeat 投递目标使用了无效账号 id。 -- `heartbeat skipped` 且 `reason=dm-blocked` → heartbeat 目标被解析为私信类目的地，而 `agents.defaults.heartbeat.directPolicy`（或每个智能体的覆盖设置）被设为 `block`。 +- `heartbeat: unknown accountId` → heartbeat 投递目标使用了无效的 account id。 +- `heartbeat skipped` 且 `reason=dm-blocked` → heartbeat 目标被解析为私信式目标，而 `agents.defaults.heartbeat.directPolicy`（或每个智能体的覆盖配置）被设置为 `block`。 相关内容： @@ -335,7 +336,7 @@ openclaw logs --follow ## 已配对节点的工具失败 -如果某个节点已完成配对，但工具调用失败，请分别隔离前台状态、权限状态和批准状态。 +如果节点已配对，但工具失败，请分别排查前台状态、权限状态和审批状态。 ```bash openclaw nodes status @@ -345,18 +346,18 @@ openclaw logs --follow openclaw status ``` -请检查： +检查以下内容： -- 节点在线，并具有预期能力。 -- 相机、麦克风、位置、屏幕等操作系统权限是否已授予。 -- Exec 批准和 allowlist 状态。 +- 节点在线，并具备预期能力。 +- 相机、麦克风、位置、屏幕等操作系统权限已授予。 +- Exec 审批和允许列表状态。 常见特征： - `NODE_BACKGROUND_UNAVAILABLE` → 节点应用必须位于前台。 - `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → 缺少操作系统权限。 -- `SYSTEM_RUN_DENIED: approval required` → exec 批准待处理。 -- `SYSTEM_RUN_DENIED: allowlist miss` → 命令被 allowlist 拦截。 +- `SYSTEM_RUN_DENIED: approval required` → exec 审批待处理。 +- `SYSTEM_RUN_DENIED: allowlist miss` → 命令被允许列表拦截。 相关内容： @@ -366,7 +367,7 @@ openclaw status ## 浏览器工具失败 -当浏览器工具操作失败，但 Gateway 网关本身健康时使用本节。 +当浏览器工具操作失败，但 Gateway 网关本身是健康的时，使用本节。 ```bash openclaw browser status @@ -376,7 +377,7 @@ openclaw logs --follow openclaw doctor ``` -请检查： +检查以下内容： - 是否设置了 `plugins.allow`，并且其中包含 `browser`。 - 浏览器可执行文件路径是否有效。 @@ -385,34 +386,34 @@ openclaw doctor 常见特征： -- `unknown command "browser"` 或 `unknown command 'browser'` → 内置的 browser 插件被 `plugins.allow` 排除了。 -- 浏览器工具缺失或不可用，而 `browser.enabled=true` → `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 附加配置文件没有任何已打开的本地 Chrome 标签页。 -- `Remote CDP for profile "" is not reachable` → 从 Gateway 网关主机无法访问所配置的远程 CDP 端点。 -- `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; '' 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 配置文件中，每次调用只能上传一个文件。 -- `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 配置文件中存在陈旧的视口 / 深色模式 / 语言区域 / 离线覆盖状态 → 运行 `openclaw browser stop --browser-profile ` 关闭当前控制会话，释放 Playwright/CDP 模拟状态，而无需重启整个 Gateway 网关。 +- `No Chrome tabs found for profile="user"` → Chrome MCP 附加配置文件没有打开的本地 Chrome 标签页。 +- `Remote CDP for profile "" is not reachable` → 配置的远程 CDP 端点从 Gateway 网关主机不可达。 +- `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加配置文件没有可达目标，或者 HTTP 端点虽有响应，但 CDP WebSocket 仍无法打开。 +- `Playwright is not available in this gateway build; '' 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 配置文件上，每次调用只发送一个上传文件。 +- `existing-session dialog handling does not support timeoutMs.` → Chrome MCP 配置文件上的对话框钩子不支持超时覆盖。 +- `response body is not supported for existing-session profiles yet.` → `responsebody` 仍需要托管浏览器或原始 CDP 配置文件。 +- 在仅附加或远程 CDP 配置文件上出现陈旧的 viewport / dark-mode / locale / offline 覆盖状态 → 运行 `openclaw browser stop --browser-profile ` 以关闭当前活动控制会话，并释放 Playwright/CDP 仿真状态，而无需重启整个 Gateway 网关。 相关内容： - [/tools/browser-linux-troubleshooting](/zh-CN/tools/browser-linux-troubleshooting) - [/tools/browser](/zh-CN/tools/browser) -## 如果你升级后某些功能突然损坏 +## 如果你升级后突然出现问题 -大多数升级后的故障都源于配置漂移，或者当前开始强制执行了更严格的默认值。 +大多数升级后的故障都源于配置漂移，或更严格的默认行为现在开始生效。 -### 1）认证和 URL 覆盖行为已更改 +### 1) 认证和 URL 覆盖行为已改变 ```bash openclaw gateway status @@ -421,17 +422,17 @@ openclaw config get gateway.remote.url openclaw config get gateway.auth.mode ``` -检查内容： +需要检查的内容： -- 如果 `gateway.mode=remote`，CLI 调用可能正在访问远程目标，而你的本地服务其实是正常的。 -- 显式 `--url` 调用不会回退到已存储的凭证。 +- 如果 `gateway.mode=remote`，CLI 调用可能会指向远程端，而你的本地服务本身其实是正常的。 +- 显式的 `--url` 调用不会回退到已存储的凭证。 常见特征： - `gateway connect failed:` → URL 目标错误。 - `unauthorized` → 端点可达，但认证错误。 -### 2）绑定和认证护栏更严格了 +### 2) 绑定和认证护栏更加严格 ```bash openclaw config get gateway.bind @@ -441,17 +442,17 @@ openclaw gateway status openclaw logs --follow ``` -检查内容： +需要检查的内容： -- 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 Gateway 网关认证路径：共享令牌/密码认证，或已正确配置的非 loopback `trusted-proxy` 部署。 +- 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 Gateway 网关认证路径：共享 token / password 认证，或正确配置的非 loopback `trusted-proxy` 部署。 - 旧键如 `gateway.token` 不能替代 `gateway.auth.token`。 常见特征： -- `refusing to bind gateway ... without auth` → 非 loopback 绑定但没有有效的 Gateway 网关认证路径。 -- `RPC probe: failed` 而运行时仍在运行 → Gateway 网关存活，但当前认证或 URL 无法访问。 +- `refusing to bind gateway ... without auth` → 在没有有效 Gateway 网关认证路径的情况下绑定到非 loopback 地址。 +- `Connectivity probe: failed`，但运行时处于运行状态 → Gateway 网关活着，但用当前认证或 URL 无法访问。 -### 3）配对和设备身份状态已更改 +### 3) 配对和设备身份状态已改变 ```bash openclaw devices list @@ -460,17 +461,17 @@ openclaw logs --follow openclaw doctor ``` -检查内容： +需要检查的内容： -- dashboard/节点是否存在待批准的设备请求。 -- 在策略或身份变化后，私信是否存在待批准配对。 +- 仪表板或节点是否有待批准的设备审批。 +- 在策略或身份变更后，私信配对审批是否仍待处理。 常见特征： -- `device identity required` → 未满足设备认证要求。 -- `pairing required` → 发送者或设备必须先获批。 +- `device identity required` → 设备认证未满足。 +- `pairing required` → 发送者或设备必须获批。 -如果在这些检查之后，服务配置和运行时仍然不一致，请使用相同的 profile/状态目录重新安装服务元数据： +如果在完成以上检查后，服务配置与运行时仍然不一致，请从相同的 profile / 状态目录重新安装服务元数据： ```bash openclaw gateway install --force diff --git a/docs/zh-CN/help/faq.md b/docs/zh-CN/help/faq.md index 15ba6a742..f0e43fa69 100644 --- a/docs/zh-CN/help/faq.md +++ b/docs/zh-CN/help/faq.md @@ -1,39 +1,39 @@ --- read_when: - - 回答常见的设置、安装、新手引导或运行时支持问题 - - 在进行更深入的调试之前，对用户报告的问题进行初步分类和排查 + - 解答常见的设置、安装、新手引导或运行时支持问题 + - 在深入调试之前，对用户报告的问题进行初步分诊 summary: 关于 OpenClaw 设置、配置和使用的常见问题 title: 常见问题 x-i18n: - generated_at: "2026-04-20T04:35:02Z" + generated_at: "2026-04-20T06:31:00Z" model: gpt-5.4 provider: openai - source_hash: 6bdb17fc4d8c61a36f3a9fc3ca4a20f723cfa6c9bbbc92f963d6e313181f3451 + source_hash: ae8efda399e34f59f22f6ea8ce218eaf7b872e4117d8596ec19c09891d70813b source_path: help/faq.md workflow: 15 --- # 常见问题 -针对真实世界部署场景的快速解答与更深入的故障排除（本地开发、VPS、多智能体、OAuth/API 密钥、模型故障转移）。如需运行时诊断，请参阅 [故障排除](/zh-CN/gateway/troubleshooting)。如需完整的配置参考，请参阅 [Configuration](/zh-CN/gateway/configuration)。 +针对真实环境设置的快速解答和更深入的故障排除（本地开发、VPS、多智能体、OAuth/API 密钥、模型故障切换）。如需运行时诊断，请参阅 [故障排除](/zh-CN/gateway/troubleshooting)。如需完整的配置参考，请参阅 [Configuration](/zh-CN/gateway/configuration)。 -## 如果出了问题，最初的六十秒 +## 如果出现问题，最初的六十秒 -1. **快速状态（第一步检查）** +1. **快速状态（首次检查）** ```bash openclaw status ``` - 快速本地摘要：操作系统 + 更新、Gateway 网关/服务可达性、智能体/会话、提供商配置 + 运行时问题（当 Gateway 网关可达时）。 + 快速的本地摘要：操作系统 + 更新、Gateway 网关 / 服务可达性、智能体 / 会话、提供商配置 + 运行时问题（当 Gateway 网关 可达时）。 -2. **可粘贴分享的报告（可安全共享）** +2. **可粘贴的报告（可安全分享）** ```bash openclaw status --all ``` - 只读诊断，附带日志尾部（令牌已打码）。 + 只读诊断，附带日志尾部（令牌已脱敏）。 3. **守护进程 + 端口状态** @@ -41,7 +41,7 @@ x-i18n: openclaw gateway status ``` - 显示 supervisor 运行时状态与 RPC 可达性、探测目标 URL，以及服务可能使用了哪个配置。 + 显示 supervisor 运行时与 RPC 可达性、探测目标 URL，以及服务可能使用了哪个配置。 4. **深度探测** @@ -49,8 +49,8 @@ x-i18n: openclaw status --deep ``` - 运行实时 Gateway 网关健康探测，包括在支持时进行渠道探测 - （需要 Gateway 网关可达）。参见 [Health](/zh-CN/gateway/health)。 + 运行实时的 Gateway 网关 健康探测，包括支持时的渠道探测 + （需要 Gateway 网关 可达）。请参阅 [Health](/zh-CN/gateway/health)。 5. **跟踪最新日志** @@ -64,7 +64,7 @@ x-i18n: tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" ``` - 文件日志与服务日志是分开的；参见 [Logging](/zh-CN/logging) 和 [故障排除](/zh-CN/gateway/troubleshooting)。 + 文件日志与服务日志是分开的；请参阅 [Logging](/zh-CN/logging) 和 [故障排除](/zh-CN/gateway/troubleshooting)。 6. **运行 Doctor（修复）** @@ -72,47 +72,48 @@ x-i18n: openclaw doctor ``` - 修复/迁移配置与状态 + 运行健康检查。参见 [Doctor](/zh-CN/gateway/doctor)。 + 修复 / 迁移配置与状态 + 运行健康检查。请参阅 [Doctor](/zh-CN/gateway/doctor)。 -7. **Gateway 网关快照** +7. **Gateway 网关 快照** ```bash openclaw health --json - openclaw health --verbose # 出错时显示目标 URL + 配置路径 + openclaw health --verbose # shows the target URL + config path on errors ``` - 向正在运行的 Gateway 网关请求完整快照（仅 WS）。参见 [Health](/zh-CN/gateway/health)。 + 向正在运行的 Gateway 网关 请求完整快照（仅 WS）。请参阅 [Health](/zh-CN/gateway/health)。 ## 快速开始和首次运行设置 - - 使用一个可以**看到你的机器**的本地 AI 智能体。这比在 Discord 里提问有效得多， - 因为大多数“我卡住了”的情况都是**本地配置或环境问题**，远程协助者无法直接检查。 + + 使用一个能够**看到你的机器**的本地 AI 智能体。这比在 Discord 里提问有效得多， + 因为大多数“我卡住了”的情况其实都是**本地配置或环境问题**， + 远程协助者无法直接检查。 - - **Claude Code**：[https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) - - **OpenAI Codex**：[https://openai.com/codex/](https://openai.com/codex/) + - **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) + - **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/) - 这些工具可以读取仓库、运行命令、检查日志，并帮助修复你机器层面的 + 这些工具可以读取仓库、运行命令、检查日志，并帮助修复你机器级别的 设置问题（PATH、服务、权限、认证文件）。通过可修改的（git）安装方式， - 把**完整的源码检出**提供给它们： + 把**完整的源代码检出**提供给它们： ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - 这会从一个 git 检出安装 OpenClaw，因此智能体可以读取代码 + 文档， - 并根据你正在运行的确切版本进行推理。你之后随时都可以重新运行安装程序， - 且不带 `--install-method git`，切换回稳定版。 + 这会**从一个 git 检出版本**安装 OpenClaw，因此智能体可以读取代码 + 文档， + 并基于你正在运行的确切版本进行推理。之后你随时都可以通过不带 + `--install-method git` 重新运行安装器，切换回稳定版。 - 提示：让智能体**规划并监督**修复过程（分步骤进行），然后只执行 - 必要的命令。这样改动会更小，也更容易审计。 + 提示：让智能体先**规划并监督**修复过程（逐步进行），然后只执行 + 必要的命令。这样改动会更少，也更容易审计。 如果你发现了真实的 bug 或修复，请提交 GitHub issue 或发送 PR： [https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues) [https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls) - 先从这些命令开始（在求助时分享输出）： + 先从这些命令开始（在寻求帮助时分享输出）： ```bash openclaw status @@ -122,35 +123,35 @@ x-i18n: 它们的作用： - - `openclaw status`：快速查看 Gateway 网关/智能体健康状态 + 基本配置。 + - `openclaw status`：快速查看 Gateway 网关 / 智能体健康状态 + 基本配置。 - `openclaw models status`：检查提供商认证 + 模型可用性。 - - `openclaw doctor`：验证并修复常见的配置/状态问题。 + - `openclaw doctor`：验证并修复常见的配置 / 状态问题。 其他有用的 CLI 检查：`openclaw status --all`、`openclaw logs --follow`、 `openclaw gateway status`、`openclaw health --verbose`。 - 快速调试循环：[如果出了问题，最初的六十秒](#如果出了问题最初的六十秒)。 + 快速调试循环：[如果出现问题，最初的六十秒](#first-60-seconds-if-something-is-broken)。 安装文档：[Install](/zh-CN/install)、[Installer flags](/zh-CN/install/installer)、[Updating](/zh-CN/install/updating)。 - + 常见的 Heartbeat 跳过原因： - - `quiet-hours`：当前不在已配置的 active-hours 时间窗口内 - - `empty-heartbeat-file`：`HEARTBEAT.md` 存在，但只包含空白内容或仅有标题的脚手架 - - `no-tasks-due`：`HEARTBEAT.md` 任务模式已启用，但当前还没有任何任务间隔到期 - - `alerts-disabled`：所有 Heartbeat 可见性都已禁用（`showOk`、`showAlerts` 和 `useIndicator` 都已关闭） + - `quiet-hours`：不在已配置的 active-hours 时间窗口内 + - `empty-heartbeat-file`：`HEARTBEAT.md` 存在，但只包含空白 / 仅标题的脚手架内容 + - `no-tasks-due`：`HEARTBEAT.md` 任务模式已启用，但还没有任何任务间隔到期 + - `alerts-disabled`：所有 Heartbeat 可见性都已禁用（`showOk`、`showAlerts` 和 `useIndicator` 全部关闭） - 在任务模式下，只有在一次真实的 Heartbeat 运行 - 完成后，到期时间戳才会推进。被跳过的运行不会将任务标记为已完成。 + 在任务模式下，只有在真正的 Heartbeat 运行 + 完成后，才会推进到期时间戳。被跳过的运行不会将任务标记为已完成。 文档：[Heartbeat](/zh-CN/gateway/heartbeat)、[Automation & Tasks](/zh-CN/automation)。 - 仓库推荐从源码运行，并使用新手引导： + 仓库建议从源码运行，并使用新手引导： ```bash curl -fsSL https://openclaw.ai/install.sh | bash @@ -159,7 +160,7 @@ x-i18n: 向导也可以自动构建 UI 资源。完成新手引导后，你通常会在 **18789** 端口运行 Gateway 网关。 - 从源码开始（贡献者/开发者）： + 从源码开始（贡献者 / 开发者）： ```bash git clone https://github.com/openclaw/openclaw.git @@ -170,90 +171,90 @@ x-i18n: openclaw onboard ``` - 如果你还没有全局安装，请通过 `pnpm openclaw onboard` 运行。 + 如果你还没有全局安装，可以通过 `pnpm openclaw onboard` 运行它。 - - 向导会在新手引导完成后立即用浏览器打开一个干净的（不带 token 的）控制台 URL，并且也会在摘要中打印该链接。请保持该标签页打开；如果没有自动启动，请在同一台机器上复制/粘贴打印出的 URL。 + + 向导会在新手引导完成后立即用浏览器打开一个干净的（不带令牌的）仪表板 URL，并且也会在摘要中打印该链接。请保持该标签页打开；如果没有自动启动，就在同一台机器上复制 / 粘贴打印出来的 URL。 - - **localhost（同一台机器）：** + + **Localhost（同一台机器）：** - 打开 `http://127.0.0.1:18789/`。 - - 如果它要求共享密钥认证，请将已配置的 token 或密码粘贴到 Control UI 设置中。 - - token 来源：`gateway.auth.token`（或 `OPENCLAW_GATEWAY_TOKEN`）。 + - 如果它要求 shared-secret 认证，请把已配置的令牌或密码粘贴到 Control UI 设置中。 + - 令牌来源：`gateway.auth.token`（或 `OPENCLAW_GATEWAY_TOKEN`）。 - 密码来源：`gateway.auth.password`（或 `OPENCLAW_GATEWAY_PASSWORD`）。 - - 如果尚未配置共享密钥，可使用 `openclaw doctor --generate-gateway-token` 生成 token。 + - 如果还没有配置 shared secret，请使用 `openclaw doctor --generate-gateway-token` 生成令牌。 - **不在 localhost：** + **不在 localhost 上：** - - **Tailscale Serve**（推荐）：保持绑定到 loopback，运行 `openclaw gateway --tailscale serve`，打开 `https:///`。如果 `gateway.auth.allowTailscale` 为 `true`，身份头会满足 Control UI/WebSocket 认证要求（无需粘贴共享密钥，前提是信任 Gateway 网关主机）；HTTP API 仍然需要共享密钥认证，除非你明确使用 private-ingress `none` 或 trusted-proxy HTTP 认证。 - 来自同一客户端的错误并发 Serve 认证尝试会先被串行化，然后失败认证限速器才会记录它们，因此第二次错误重试可能已经显示 `retry later`。 - - **Tailnet 绑定**：运行 `openclaw gateway --bind tailnet --token ""`（或配置密码认证），打开 `http://:18789/`，然后在控制台设置中粘贴匹配的共享密钥。 - - **具备身份感知能力的反向代理**：让 Gateway 网关继续位于非 loopback 的 trusted proxy 后面，配置 `gateway.auth.mode: "trusted-proxy"`，然后打开代理 URL。 - - **SSH 隧道**：`ssh -N -L 18789:127.0.0.1:18789 user@host`，然后打开 `http://127.0.0.1:18789/`。通过隧道时仍然会应用共享密钥认证；如果出现提示，请粘贴已配置的 token 或密码。 + - **Tailscale Serve**（推荐）：保持 bind loopback，运行 `openclaw gateway --tailscale serve`，打开 `https:///`。如果 `gateway.auth.allowTailscale` 为 `true`，身份标头会满足 Control UI/WebSocket 认证（无需粘贴 shared secret，前提是假定 Gateway 网关 主机可信）；HTTP API 仍然需要 shared-secret 认证，除非你有意使用 private-ingress `none` 或 trusted-proxy HTTP 认证。 + 来自同一客户端的错误并发 Serve 认证尝试，会在失败认证限流器记录之前被串行化，因此第二次错误重试就可能已经显示 `retry later`。 + - **Tailnet 绑定**：运行 `openclaw gateway --bind tailnet --token ""`（或配置密码认证），打开 `http://:18789/`，然后在仪表板设置中粘贴匹配的 shared secret。 + - **支持身份感知的反向代理**：将 Gateway 网关 保持在非 loopback 的 trusted proxy 后面，配置 `gateway.auth.mode: "trusted-proxy"`，然后打开代理 URL。 + - **SSH 隧道**：`ssh -N -L 18789:127.0.0.1:18789 user@host`，然后打开 `http://127.0.0.1:18789/`。shared-secret 认证在隧道上仍然适用；如果出现提示，请粘贴已配置的令牌或密码。 - 有关绑定模式和认证详情，请参阅 [Dashboard](/web/dashboard) 和 [Web surfaces](/web)。 + 有关 bind 模式和认证细节，请参阅 [Dashboard](/web/dashboard) 和 [Web surfaces](/web)。 - + 它们控制的是不同层级： - `approvals.exec`：将审批提示转发到聊天目标 - `channels..execApprovals`：让该渠道作为 exec 审批的原生审批客户端 - 主机 exec 策略仍然是真正的审批关卡。聊天配置只控制审批 - 提示出现在哪里，以及人们可以如何回复。 + 主机的 exec 策略仍然是真正的审批门控。聊天配置只控制审批提示出现在哪里， + 以及人们如何进行回应。 - 在大多数部署中，你**不**需要同时配置两者： + 在大多数设置中，你**不需要**同时启用两者： - - 如果聊天本身已经支持命令和回复，那么同一聊天中的 `/approve` 会通过共享路径工作。 - - 如果某个受支持的原生渠道可以安全推断审批人，那么当 `channels..execApprovals.enabled` 未设置或为 `"auto"` 时，OpenClaw 现在会自动启用“优先私信”的原生审批。 - - 当原生审批卡片/按钮可用时，该原生 UI 是主要路径；只有在工具结果表明聊天审批不可用，或者手动审批是唯一方式时，智能体才应包含手动 `/approve` 命令。 - - 只有当提示还必须转发到其他聊天或专门的运维房间时，才使用 `approvals.exec`。 - - 只有当你明确希望将审批提示回发到原始房间/话题中时，才使用 `channels..execApprovals.target: "channel"` 或 `"both"`。 - - 插件审批则是另外一套：默认使用同一聊天中的 `/approve`，可选 `approvals.plugin` 转发，并且只有部分原生渠道会在此基础上保留插件审批原生处理。 + - 如果聊天已经支持命令和回复，那么同一聊天中的 `/approve` 会通过共享路径工作。 + - 如果受支持的原生渠道能够安全地推断审批人，OpenClaw 现在会在 `channels..execApprovals.enabled` 未设置或为 `"auto"` 时，自动启用私信优先的原生审批。 + - 当原生审批卡片 / 按钮可用时，该原生 UI 是主要路径；只有在工具结果说明聊天审批不可用，或手动审批是唯一途径时，智能体才应包含手动 `/approve` 命令。 + - 仅当提示还必须被转发到其他聊天或明确的运维房间时，才使用 `approvals.exec`。 + - 仅当你明确希望将审批提示也发回发起来源的房间 / 话题时，才使用 `channels..execApprovals.target: "channel"` 或 `"both"`。 + - 插件审批则是另一套机制：默认使用同一聊天中的 `/approve`，可选使用 `approvals.plugin` 转发，并且只有部分原生渠道会额外保留原生插件审批处理。 - 简而言之：转发用于路由，原生客户端配置用于更丰富的渠道专属 UX。 - 参见 [Exec Approvals](/zh-CN/tools/exec-approvals)。 + 简而言之：转发用于路由，原生客户端配置用于更丰富的渠道特定 UX。 + 请参阅 [Exec Approvals](/zh-CN/tools/exec-approvals)。 - 需要 Node **>= 22**。推荐使用 `pnpm`。Gateway 网关**不推荐**使用 Bun。 + 需要 Node **>= 22**。推荐使用 `pnpm`。Gateway 网关 **不推荐**使用 Bun。 - 可以。Gateway 网关很轻量——文档中写明，个人使用场景下 **512MB-1GB RAM**、**1 个核心**以及约 **500MB** - 磁盘空间就足够，并且注明 **Raspberry Pi 4 可以运行它**。 + 可以。Gateway 网关 很轻量——文档中说明个人使用时，**512MB-1GB RAM**、**1 个核心**以及大约 **500MB** + 磁盘空间就足够了，并指出 **Raspberry Pi 4 可以运行它**。 - 如果你想要更多余量（日志、媒体、其他服务），推荐使用 **2GB**，但这 - 并不是硬性最低要求。 + 如果你想保留更多余量（日志、媒体、其他服务），**推荐 2GB**，但这 + 不是硬性最低要求。 - 提示：一个小型 Pi/VPS 可以托管 Gateway 网关，而你可以在笔记本电脑/手机上配对 **nodes**， - 用于本地屏幕/摄像头/canvas 或命令执行。参见 [Nodes](/zh-CN/nodes)。 + 提示：小型 Pi/VPS 可以托管 Gateway 网关，而你可以在笔记本电脑 / 手机上配对**节点**，用于 + 本地屏幕 / 摄像头 / 画布或命令执行。请参阅 [Nodes](/zh-CN/nodes)。 - - 简短回答：可以运行，但要预期会遇到一些粗糙边角。 + + 简短回答：它可以运行，但要预期会有一些棘手边角问题。 - 使用 **64 位**操作系统，并保持 Node >= 22。 - - 优先选择**可修改的（git）安装**，这样你可以查看日志并快速更新。 - - 先不要启用渠道/Skills，然后逐个添加。 - - 如果你遇到奇怪的二进制问题，通常都是 **ARM 兼容性** 问题。 + - 优先使用**可修改的（git）安装方式**，这样你可以查看日志并快速更新。 + - 先不要启用渠道 / Skills，然后一个一个地添加。 + - 如果你遇到奇怪的二进制问题，通常都是 **ARM 兼容性**问题。 文档：[Linux](/zh-CN/platforms/linux)、[Install](/zh-CN/install)。 - - 该界面依赖 Gateway 网关可达且已认证。TUI 还会在首次 hatch 时自动发送 - “Wake up, my friend!”。如果你看到这一行但**没有回复**， - 并且 token 仍为 0，说明智能体根本没有运行。 + + 这个界面依赖于 Gateway 网关 可达并且已认证。TUI 也会在首次 hatch 时自动发送 + “Wake up, my friend!”。如果你看到这行内容但**没有回复**， + 且令牌始终为 0，就表示智能体根本没有运行。 1. 重启 Gateway 网关： @@ -269,54 +270,54 @@ x-i18n: openclaw logs --follow ``` - 3. 如果仍然卡住，运行： + 3. 如果仍然卡住，请运行： ```bash openclaw doctor ``` - 如果 Gateway 网关是远程的，请确保隧道/Tailscale 连接已建立，并且 UI - 指向了正确的 Gateway 网关。参见 [Remote access](/zh-CN/gateway/remote)。 + 如果 Gateway 网关 是远程的，请确保隧道 / Tailscale 连接正常，并且 UI + 指向了正确的 Gateway 网关。请参阅 [Remote access](/zh-CN/gateway/remote)。 - - 可以。复制**状态目录**和**工作区**，然后运行一次 Doctor。这会 - 让你的机器人“完全保持不变”（记忆、会话历史、认证以及渠道 + + 可以。复制**状态目录**和**工作区**，然后运行一次 Doctor。这样 + 就能让你的机器人“完全保持不变”（记忆、会话历史、认证和渠道 状态），前提是你复制了**这两个**位置： 1. 在新机器上安装 OpenClaw。 2. 从旧机器复制 `$OPENCLAW_STATE_DIR`（默认：`~/.openclaw`）。 3. 复制你的工作区（默认：`~/.openclaw/workspace`）。 - 4. 运行 `openclaw doctor` 并重启 Gateway 网关服务。 + 4. 运行 `openclaw doctor` 并重启 Gateway 网关 服务。 - 这会保留配置、认证配置文件、WhatsApp 凭据、会话和记忆。如果你处于 - 远程模式，请记住会话存储和工作区归 Gateway 网关主机所有。 + 这会保留配置、认证配置文件、WhatsApp 凭证、会话和记忆。如果你处于 + 远程模式，请记住会话存储和工作区归 Gateway 网关 主机所有。 - **重要：** 如果你只是将工作区提交/推送到 GitHub，你备份的是 - **记忆 + 引导文件**，但**不会**备份会话历史或认证信息。那些内容保存在 + **重要：**如果你只是将工作区提交 / 推送到 GitHub，你备份的是 + **记忆 + bootstrap 文件**，但**不会**备份会话历史或认证。它们位于 `~/.openclaw/` 下（例如 `~/.openclaw/agents//sessions/`）。 - 相关内容：[Migrating](/zh-CN/install/migrating)、[磁盘上的文件位置](#where-things-live-on-disk)、 - [Agent workspace](/zh-CN/concepts/agent-workspace)、[Doctor](/zh-CN/gateway/doctor)、 + 相关内容：[Migrating](/zh-CN/install/migrating)、[磁盘上的内容位置](#where-things-live-on-disk)、 + [智能体工作区](/zh-CN/concepts/agent-workspace)、[Doctor](/zh-CN/gateway/doctor)、 [Remote mode](/zh-CN/gateway/remote)。 - - 请查看 GitHub 更新日志： + + 查看 GitHub 更新日志： [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - 最新条目在最上方。如果最上面的部分标记为 **Unreleased**，那么下一个带日期的 - 部分就是最新发布的版本。条目按 **Highlights**、**Changes** 和 - **Fixes** 分组（在需要时还会有 docs/其他部分）。 + 最新条目位于最上方。如果顶部部分标记为 **Unreleased**，那么下一个带日期的 + 部分就是最近发布的版本。条目按 **Highlights**、**Changes** 和 + **Fixes** 分组（如有需要，还会有文档 / 其他部分）。 - 某些 Comcast/Xfinity 连接会因为 Xfinity - Advanced Security 而错误地屏蔽 `docs.openclaw.ai`。请禁用它或将 `docs.openclaw.ai` 加入允许列表，然后重试。 - 也请通过这里帮助我们解除拦截：[https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status)。 + 一些 Comcast/Xfinity 连接会因为 Xfinity + Advanced Security 而错误地拦截 `docs.openclaw.ai`。请禁用它，或将 `docs.openclaw.ai` 加入允许列表，然后重试。 + 也请通过这里的链接帮助我们解除拦截：[https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status)。 如果你仍然无法访问该站点，文档在 GitHub 上也有镜像： [https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs) @@ -324,28 +325,28 @@ x-i18n: - **Stable** 和 **beta** 是 **npm dist-tag**，不是独立的代码线： + **Stable** 和 **beta** 是 **npm dist-tag**，而不是独立的代码分支： - `latest` = stable - `beta` = 用于测试的早期构建 - 通常，一个稳定版本会先发布到 **beta**，然后通过一个显式的 - 提升步骤把同一个版本移动到 `latest`。维护者也可以在必要时 - 直接发布到 `latest`。这就是为什么 beta 和 stable 在提升后可能 + 通常，稳定版本会先发布到 **beta**，然后再通过一个明确的 + 提升步骤将同一版本移动到 `latest`。维护者也可以在需要时 + 直接发布到 `latest`。这就是为什么 beta 和 stable 在提升之后可能会 指向**同一个版本**。 查看变更内容： [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - 关于安装单行命令以及 beta 和 dev 的区别，请参阅下面的折叠项。 + 关于安装一行命令以及 beta 和 dev 的区别，请参阅下方的折叠项。 - **Beta** 是 npm dist-tag `beta`（在提升后可能与 `latest` 相同）。 - **Dev** 是 `main` 的移动头部（git）；发布时，它使用 npm dist-tag `dev`。 + **Beta** 是 npm dist-tag `beta`（提升后可能与 `latest` 一致）。 + **Dev** 是不断移动的 `main` 头部（git）；发布时使用 npm dist-tag `dev`。 - 单行命令（macOS/Linux）： + 一行命令（macOS/Linux）： ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta @@ -355,14 +356,14 @@ x-i18n: curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Windows 安装程序（PowerShell）： + Windows 安装器（PowerShell）： [https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1) 更多细节：[Development channels](/zh-CN/install/development-channels) 和 [Installer flags](/zh-CN/install/installer)。 - + 有两种方式： 1. **Dev 渠道（git 检出）：** @@ -379,9 +380,9 @@ x-i18n: curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - 这会给你一个可在本地编辑的仓库，然后你可以通过 git 更新。 + 这会给你一个可本地编辑的仓库，然后你可以通过 git 更新。 - 如果你更喜欢手动进行干净克隆，请使用： + 如果你更喜欢手动进行干净的克隆，请使用： ```bash git clone https://github.com/openclaw/openclaw.git @@ -398,22 +399,22 @@ x-i18n: 大致参考： - - **安装：** 2-5 分钟 - - **新手引导：** 5-15 分钟，取决于你配置了多少渠道/模型 + - **安装：**2-5 分钟 + - **新手引导：**5-15 分钟，取决于你配置了多少渠道 / 模型 - 如果卡住了，请使用 [安装程序卡住了？](#quick-start-and-first-run-setup) - 和 [我卡住了](#quick-start-and-first-run-setup) 中的快速调试循环。 + 如果卡住了，请使用 [安装器卡住了](#quick-start-and-first-run-setup) + 以及 [我卡住了](#quick-start-and-first-run-setup) 中的快速调试循环。 - - 使用**详细输出**重新运行安装程序： + + 使用**详细输出**重新运行安装器： ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose ``` - 带详细输出的 beta 安装： + 使用详细输出安装 beta： ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose @@ -428,7 +429,7 @@ x-i18n: Windows（PowerShell）等效方式： ```powershell - # install.ps1 目前还没有专用的 -Verbose 标志。 + # install.ps1 has no dedicated -Verbose flag yet. Set-PSDebug -Trace 1 & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard Set-PSDebug -Trace 0 @@ -438,15 +439,15 @@ x-i18n: - + 两个常见的 Windows 问题： - **1) npm 错误 spawn git / git not found** + **1）npm 错误 spawn git / git not found** - 安装 **Git for Windows**，并确保 `git` 在你的 PATH 中。 - - 关闭并重新打开 PowerShell，然后重新运行安装程序。 + - 关闭并重新打开 PowerShell，然后重新运行安装器。 - **2) 安装后 openclaw is not recognized** + **2）安装后 openclaw is not recognized** - 你的 npm 全局 bin 目录不在 PATH 中。 - 检查路径： @@ -458,20 +459,20 @@ x-i18n: - 将该目录添加到你的用户 PATH 中（Windows 上不需要 `\bin` 后缀；在大多数系统上它是 `%AppData%\npm`）。 - 更新 PATH 后，关闭并重新打开 PowerShell。 - 如果你想获得最顺畅的 Windows 设置体验，请使用 **WSL2** 而不是原生 Windows。 + 如果你想获得最顺滑的 Windows 设置体验，请使用 **WSL2**，而不是原生 Windows。 文档：[Windows](/zh-CN/platforms/windows)。 - + 这通常是原生 Windows shell 中控制台代码页不匹配导致的。 症状： - `system.run`/`exec` 输出中的中文显示为乱码 - - 同一条命令在另一个终端配置中显示正常 + - 同一命令在另一个终端配置中显示正常 - PowerShell 中的快速解决方法： + 在 PowerShell 中的快速解决方法： ```powershell chcp 65001 @@ -480,21 +481,21 @@ x-i18n: $OutputEncoding = [System.Text.UTF8Encoding]::new($false) ``` - 然后重启 Gateway 网关并重试你的命令： + 然后重启 Gateway 网关 并重试你的命令： ```powershell openclaw gateway restart ``` - 如果你在最新版本的 OpenClaw 中仍然能复现此问题，请在这里跟踪/报告： + 如果你在最新的 OpenClaw 上仍然能复现这个问题，请在这里跟踪 / 报告： - [Issue #30640](https://github.com/openclaw/openclaw/issues/30640) - 使用**可修改的（git）安装**，这样你就能在本地获得完整源码和文档，然后 - 在_该文件夹中_向你的机器人（或 Claude/Codex）提问，这样它就可以读取仓库并给出精确答案。 + 使用**可修改的（git）安装方式**，这样你就能在本地拥有完整的源代码和文档，然后 + 在_该目录中_询问你的机器人（或 Claude/Codex），这样它就可以读取仓库并给出准确答案。 ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git @@ -509,43 +510,43 @@ x-i18n: - Linux 快速路径 + 服务安装：[Linux](/zh-CN/platforms/linux)。 - 完整演练：[入门指南](/zh-CN/start/getting-started)。 - - 安装程序 + 更新：[Install & updates](/zh-CN/install/updating)。 + - 安装器 + 更新：[Install & updates](/zh-CN/install/updating)。 - 任何 Linux VPS 都可以。安装到服务器上，然后使用 SSH/Tailscale 访问 Gateway 网关。 + 任何 Linux VPS 都可以。在服务器上安装，然后使用 SSH/Tailscale 访问 Gateway 网关。 指南：[exe.dev](/zh-CN/install/exe-dev)、[Hetzner](/zh-CN/install/hetzner)、[Fly.io](/zh-CN/install/fly)。 远程访问：[Gateway remote](/zh-CN/gateway/remote)。 - - 我们提供了一个**托管中心**，汇总常见提供商。请选择一个并按照指南操作： + + 我们维护了一个**托管中心**，汇总常见提供商。选择一个并按照指南操作： - - [VPS hosting](/zh-CN/vps)（所有提供商集中在一个地方） + - [VPS hosting](/zh-CN/vps)（所有提供商集中在一处） - [Fly.io](/zh-CN/install/fly) - [Hetzner](/zh-CN/install/hetzner) - [exe.dev](/zh-CN/install/exe-dev) - 它在云端的工作方式是：**Gateway 网关运行在服务器上**，而你通过 - Control UI（或 Tailscale/SSH）从笔记本电脑/手机访问它。你的状态 + 工作区 - 都保存在服务器上，因此请将主机视为事实来源并做好备份。 + 它在云中的工作方式是：**Gateway 网关 运行在服务器上**，而你通过 + Control UI（或 Tailscale/SSH）从笔记本电脑 / 手机上访问它。你的状态和工作区 + 都位于服务器上，因此请将该主机视为真实数据源并做好备份。 - 你可以将 **nodes**（Mac/iOS/Android/headless）配对到这个云端 Gateway 网关， - 以访问本地屏幕/摄像头/canvas，或者在保留 - Gateway 网关位于云端的同时，在你的笔记本电脑上运行命令。 + 你可以将**节点**（Mac/iOS/Android/无头环境）配对到这个云端 Gateway 网关，以访问 + 本地屏幕 / 摄像头 / 画布，或在你的笔记本电脑上运行命令，同时保持 + Gateway 网关 在云中运行。 - 中心：[Platforms](/zh-CN/platforms)。远程访问：[Gateway remote](/zh-CN/gateway/remote)。 - Nodes：[Nodes](/zh-CN/nodes)、[Nodes CLI](/cli/nodes)。 + 中心页：[Platforms](/zh-CN/platforms)。远程访问：[Gateway remote](/zh-CN/gateway/remote)。 + 节点：[Nodes](/zh-CN/nodes)、[Nodes CLI](/cli/nodes)。 简短回答：**可以，但不推荐**。更新流程可能会重启 - Gateway 网关（这会中断当前活跃会话），可能需要一个干净的 git 检出，并且 - 可能会提示确认。更安全的做法是：由操作人员在 shell 中执行更新。 + Gateway 网关（这会中断当前会话），可能需要一个干净的 git 检出，并且 + 可能要求确认。更安全的做法是：由操作员在 shell 中执行更新。 使用 CLI： @@ -557,7 +558,7 @@ x-i18n: openclaw update --no-restart ``` - 如果你必须从智能体自动化执行： + 如果你必须从智能体中自动化执行： ```bash openclaw update --yes --no-restart @@ -569,34 +570,34 @@ x-i18n: - `openclaw onboard` 是推荐的设置路径。在**本地模式**下，它会引导你完成： + `openclaw onboard` 是推荐的设置方式。在**本地模式**下，它会引导你完成： - - **模型/认证设置**（提供商 OAuth、API 密钥、Anthropic setup-token，以及 LM Studio 等本地模型选项） - - **工作区**位置 + 引导文件 - - **Gateway 网关设置**（绑定/端口/认证/tailscale） + - **模型 / 认证设置**（提供商 OAuth、API 密钥、Anthropic setup-token，以及 LM Studio 等本地模型选项） + - **工作区**位置 + bootstrap 文件 + - **Gateway 网关 设置**（bind/port/auth/tailscale） - **渠道**（WhatsApp、Telegram、Discord、Mattermost、Signal、iMessage，以及像 QQ Bot 这样的内置渠道插件） - **守护进程安装**（macOS 上为 LaunchAgent；Linux/WSL2 上为 systemd 用户单元） - **健康检查**和 **Skills** 选择 - 如果你配置的模型未知或缺少认证信息，它也会发出警告。 + 如果你配置的模型未知或缺少认证，它也会发出警告。 - - 不需要。你可以使用 **API 密钥**（Anthropic/OpenAI/其他）运行 OpenClaw，也可以使用 - **纯本地模型**，这样你的数据就会保留在你的设备上。订阅（Claude - Pro/Max 或 OpenAI Codex）只是为这些提供商进行认证的可选方式。 + + 不需要。你可以通过 **API 密钥**（Anthropic/OpenAI/其他）运行 OpenClaw，或者使用 + **纯本地模型**，这样你的数据就会保留在设备上。订阅（Claude + Pro/Max 或 OpenAI Codex）只是认证这些提供商的可选方式。 - 对于 OpenClaw 中的 Anthropic，实际区分如下： + 对于 OpenClaw 中的 Anthropic，实际上的区分是： - - **Anthropic API key**：普通的 Anthropic API 计费 - - **OpenClaw 中的 Claude CLI / Claude 订阅认证**：Anthropic 员工 - 告诉我们这种用法再次被允许，OpenClaw 目前将 `claude -p` - 的用法视为该集成下被认可的方式，除非 Anthropic 发布新的 + - **Anthropic API key**：正常的 Anthropic API 计费 + - **Claude CLI / OpenClaw 中的 Claude 订阅认证**：Anthropic 员工 + 告诉我们这种用法再次被允许，OpenClaw 当前将 `claude -p` + 的使用视为此集成的认可方式，除非 Anthropic 发布新的 政策 - 对于长期运行的 Gateway 网关主机，Anthropic API 密钥仍然是更 - 可预测的配置方式。OpenAI Codex OAuth 明确支持像 OpenClaw 这样的外部 + 对于长期运行的 Gateway 网关 主机，Anthropic API 密钥仍然是 + 更可预测的设置方式。OpenAI Codex OAuth 已明确支持像 OpenClaw 这样的外部 工具。 OpenClaw 还支持其他托管式订阅选项，包括 @@ -615,18 +616,20 @@ x-i18n: Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此 除非 Anthropic 发布新的政策，否则 OpenClaw 会将 Claude 订阅认证和 `claude -p` 的使用视为 - 此集成下被认可的方式。如果你想要最可预测的服务器端部署方式，请改用 Anthropic API 密钥。 + 该集成下被认可的方式。如果你想要 + 最可预测的服务端设置，请改用 Anthropic API key。 - + 支持。 - Anthropic 员工告诉我们，这种用法再次被允许，因此除非 Anthropic 发布新的政策，否则 OpenClaw 会将 - Claude CLI 复用和 `claude -p` 的使用视为此集成下被认可的方式。 + Anthropic 员工告诉我们，这种用法再次被允许，因此 OpenClaw 将 + Claude CLI 复用和 `claude -p` 的使用视为该集成下被认可的方式， + 除非 Anthropic 发布新的政策。 - Anthropic setup-token 仍然是受支持的 OpenClaw token 路径，但 OpenClaw 现在在可用时更倾向于使用 Claude CLI 复用和 `claude -p`。 - 对于生产环境或多用户工作负载，Anthropic API 密钥认证仍然是 + Anthropic setup-token 仍然是 OpenClaw 支持的令牌路径，但在可用时，OpenClaw 现在更偏好 Claude CLI 复用和 `claude -p`。 + 对于生产环境或多用户工作负载，Anthropic API key 认证仍然是 更安全、更可预测的选择。如果你想在 OpenClaw 中使用其他订阅式托管 选项，请参阅 [OpenAI](/zh-CN/providers/openai)、[Qwen / Model Cloud](/zh-CN/providers/qwen)、[MiniMax](/zh-CN/providers/minimax) 和 [GLM @@ -635,33 +638,33 @@ x-i18n: - -这表示你当前窗口中的 **Anthropic 配额/速率限制** 已用尽。如果你 -使用 **Claude CLI**，请等待窗口重置或升级你的套餐。如果你 -使用的是 **Anthropic API key**，请检查 Anthropic Console -中的用量/计费情况，并根据需要提高限制。 + +这表示你当前时间窗口中的 **Anthropic 配额 / 速率限制** 已耗尽。如果你 +使用 **Claude CLI**，请等待时间窗口重置或升级你的套餐。如果你 +使用 **Anthropic API key**，请检查 Anthropic Console +中的用量 / 计费，并根据需要提高限额。 如果消息明确是： - `Extra usage is required for long context requests`，说明请求正在尝试使用 - Anthropic 的 1M 上下文 beta（`context1m: true`）。这只有在你的 - 凭证具备长上下文计费资格时才可用（API 密钥计费，或启用了 Extra Usage 的 - OpenClaw Claude 登录路径）。 + `Extra usage is required for long context requests`，则说明该请求正在尝试使用 + Anthropic 的 1M 上下文 beta（`context1m: true`）。这仅在你的 + 凭证符合长上下文计费条件时才可用（API key 计费，或者 + 启用了 Extra Usage 的 OpenClaw Claude 登录路径）。 - 提示：设置一个**回退模型**，这样在某个提供商被限速时，OpenClaw 仍然可以继续回复。 - 参见 [Models](/cli/models)、[OAuth](/zh-CN/concepts/oauth) 和 + 提示：设置一个**回退模型**，这样当某个提供商受到速率限制时，OpenClaw 仍然可以继续回复。 + 请参阅 [Models](/cli/models)、[OAuth](/zh-CN/concepts/oauth) 和 [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/zh-CN/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context)。 - 支持。OpenClaw 内置了 **Amazon Bedrock（Converse）** 提供商。当 AWS 环境标记存在时，OpenClaw 可以自动发现支持流式/文本的 Bedrock 目录，并将其合并为隐式的 `amazon-bedrock` 提供商；否则，你也可以显式启用 `plugins.entries.amazon-bedrock.config.discovery.enabled`，或添加手动提供商条目。参见 [Amazon Bedrock](/zh-CN/providers/bedrock) 和 [Model providers](/zh-CN/providers/models)。如果你更倾向于托管密钥流程，在 Bedrock 前面使用一个兼容 OpenAI 的代理仍然是可行的选择。 + 支持。OpenClaw 内置了 **Amazon Bedrock（Converse）** 提供商。存在 AWS 环境标记时，OpenClaw 可以自动发现支持流式 / 文本的 Bedrock 目录，并将其作为隐式 `amazon-bedrock` 提供商合并；否则你也可以显式启用 `plugins.entries.amazon-bedrock.config.discovery.enabled` 或添加手动提供商条目。请参阅 [Amazon Bedrock](/zh-CN/providers/bedrock) 和 [Model providers](/zh-CN/providers/models)。如果你更偏好托管密钥流程，在 Bedrock 前面使用 OpenAI 兼容代理仍然是有效选项。 - OpenClaw 通过 OAuth（ChatGPT 登录）支持 **OpenAI Code（Codex）**。新手引导可以运行 OAuth 流程，并会在适当时将默认模型设置为 `openai-codex/gpt-5.4`。参见 [Model providers](/zh-CN/concepts/model-providers) 和 [设置向导（CLI）](/zh-CN/start/wizard)。 + OpenClaw 通过 OAuth（ChatGPT 登录）支持 **OpenAI Code（Codex）**。新手引导可以运行 OAuth 流程，并会在适当时将默认模型设置为 `openai-codex/gpt-5.4`。请参阅 [Model providers](/zh-CN/concepts/model-providers) 和 [新手引导（CLI）](/zh-CN/start/wizard)。 - + OpenClaw 将这两条路径分开处理： - `openai-codex/gpt-5.4` = ChatGPT/Codex OAuth @@ -675,129 +678,129 @@ x-i18n: - `openai-codex/*` 使用 Codex OAuth 路径，其可用配额窗口 - 由 OpenAI 管理，并取决于套餐。实际上，这些限制可能与 - ChatGPT 网站/应用中的体验不同，即使它们都绑定到同一个账户。 + `openai-codex/*` 使用 Codex OAuth 路径，而它可用的配额窗口由 + OpenAI 管理，并取决于你的套餐。实际上，这些限制可能与 + ChatGPT 网站 / 应用的体验不同，即使二者绑定的是同一个账户。 OpenClaw 可以在 - `openclaw models status` 中显示当前可见的提供商用量/配额窗口，但它不会凭空生成， - 也不会把 ChatGPT 网页版权益标准化为直接 API 访问。如果你想使用直接的 OpenAI Platform - 计费/限额路径，请使用带 API 密钥的 `openai/*`。 + `openclaw models status` 中显示当前可见的提供商用量 / 配额窗口，但它不会凭空生成或将 ChatGPT 网页版的 + 权益规范化为直接 API 访问。如果你想使用直接的 OpenAI Platform + 计费 / 限额路径，请配合 API key 使用 `openai/*`。 - + 支持。OpenClaw 完全支持 **OpenAI Code（Codex）订阅 OAuth**。 - OpenAI 明确允许在像 OpenClaw 这样的外部工具/工作流中 - 使用订阅 OAuth。新手引导可以为你运行 OAuth 流程。 + OpenAI 明确允许在像 OpenClaw 这样的外部工具 / 工作流中 + 使用订阅 OAuth。新手引导可以为你运行该 OAuth 流程。 - 参见 [OAuth](/zh-CN/concepts/oauth)、[Model providers](/zh-CN/concepts/model-providers) 和 [设置向导（CLI）](/zh-CN/start/wizard)。 + 请参阅 [OAuth](/zh-CN/concepts/oauth)、[Model providers](/zh-CN/concepts/model-providers) 和 [新手引导（CLI）](/zh-CN/start/wizard)。 - Gemini CLI 使用的是**插件认证流程**，而不是在 `openclaw.json` 中填写 client id 或 secret。 + Gemini CLI 使用的是**插件认证流程**，而不是在 `openclaw.json` 中配置 client id 或 secret。 步骤： - 1. 在本地安装 Gemini CLI，确保 `gemini` 位于 `PATH` 中 + 1. 在本地安装 Gemini CLI，使 `gemini` 位于 `PATH` 中 - Homebrew：`brew install gemini-cli` - npm：`npm install -g @google/gemini-cli` 2. 启用插件：`openclaw plugins enable google` 3. 登录：`openclaw models auth login --provider google-gemini-cli --set-default` 4. 登录后的默认模型：`google-gemini-cli/gemini-3-flash-preview` - 5. 如果请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID` + 5. 如果请求失败，请在 Gateway 网关 主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID` - 这会将 OAuth token 存储在 Gateway 网关主机上的认证配置文件中。详情参见：[Model providers](/zh-CN/concepts/model-providers)。 + 这会将 OAuth 令牌存储在 Gateway 网关 主机上的认证配置文件中。详情请参阅：[Model providers](/zh-CN/concepts/model-providers)。 - 通常不适合。OpenClaw 需要大上下文 + 强安全性；小显存卡上的模型会截断并泄漏。如果你必须这样做，请在本地运行你能使用的**最大**模型构建（LM Studio），并参见 [/gateway/local-models](/zh-CN/gateway/local-models)。更小/量化的模型会增加 prompt injection 风险——参见 [Security](/zh-CN/gateway/security)。 + 通常不适合。OpenClaw 需要大上下文 + 强安全性；小模型会截断并泄漏。如果你确实要用，请在本地运行你能承载的**最大**模型构建（LM Studio），并查看 [/gateway/local-models](/zh-CN/gateway/local-models)。更小 / 量化的模型会增加提示注入风险——请参阅 [Security](/zh-CN/gateway/security)。 - 请选择固定区域的端点。OpenRouter 为 MiniMax、Kimi 和 GLM 提供美国托管选项；选择美国托管变体即可让数据保留在该区域内。你仍然可以通过使用 `models.mode: "merge"` 将 Anthropic/OpenAI 一并列出，这样在遵守所选区域提供商要求的同时，回退路径仍然可用。 + 选择区域固定的端点。OpenRouter 为 MiniMax、Kimi 和 GLM 提供了美国托管选项；选择美国托管变体即可让数据保留在该区域内。你仍然可以通过使用 `models.mode: "merge"` 将 Anthropic/OpenAI 与这些选项一并列出，这样既能保持回退可用，又能遵循你选择的区域化提供商。 - - 不需要。OpenClaw 可运行在 macOS 或 Linux 上（Windows 通过 WSL2）。Mac mini 是可选的——有些人 - 会买一台作为常驻主机，但小型 VPS、家用服务器或 Raspberry Pi 级别的设备也可以。 + + 不需要。OpenClaw 可以运行在 macOS 或 Linux 上（Windows 通过 WSL2）。Mac mini 是可选的——有些人 + 会买一台作为常开主机，但小型 VPS、家用服务器或 Raspberry Pi 级别的机器也可以。 - 只有在你需要 **仅限 macOS 的工具** 时才需要 Mac。对于 iMessage，请使用 [BlueBubbles](/zh-CN/channels/bluebubbles)（推荐）——BlueBubbles 服务器可以运行在任何 Mac 上，而 Gateway 网关可以运行在 Linux 或其他地方。如果你想使用其他仅限 macOS 的工具，请在 Mac 上运行 Gateway 网关，或配对一个 macOS 节点。 + 只有在你需要**仅限 macOS 的工具**时才需要 Mac。对于 iMessage，请使用 [BlueBubbles](/zh-CN/channels/bluebubbles)（推荐）——BlueBubbles 服务器可以运行在任何 Mac 上，而 Gateway 网关 可以运行在 Linux 或其他地方。如果你想使用其他仅限 macOS 的工具，请在 Mac 上运行 Gateway 网关 或配对一个 macOS 节点。 文档：[BlueBubbles](/zh-CN/channels/bluebubbles)、[Nodes](/zh-CN/nodes)、[Mac remote mode](/zh-CN/platforms/mac/remote)。 - - 你需要**某台已登录 Messages 的 macOS 设备**。它**不必**是 Mac mini—— - 任何 Mac 都可以。对于 iMessage，请**使用 [BlueBubbles](/zh-CN/channels/bluebubbles)**（推荐）——BlueBubbles 服务器运行在 macOS 上，而 Gateway 网关可以运行在 Linux 或其他地方。 + + 你需要**某台已登录 Messages 的 macOS 设备**。它**不一定**必须是 Mac mini—— + 任何 Mac 都可以。对于 iMessage，**请使用 [BlueBubbles](/zh-CN/channels/bluebubbles)**（推荐）——BlueBubbles 服务器运行在 macOS 上，而 Gateway 网关 可以运行在 Linux 或其他地方。 - 常见部署方式： + 常见设置： - - 在 Linux/VPS 上运行 Gateway 网关，并在任何已登录 Messages 的 Mac 上运行 BlueBubbles 服务器。 - - 如果你想要最简单的单机部署，也可以把所有内容都运行在这台 Mac 上。 + - 在 Linux/VPS 上运行 Gateway 网关，并在任意已登录 Messages 的 Mac 上运行 BlueBubbles 服务器。 + - 如果你想要最简单的单机设置，也可以把所有内容都运行在那台 Mac 上。 文档：[BlueBubbles](/zh-CN/channels/bluebubbles)、[Nodes](/zh-CN/nodes)、 [Mac remote mode](/zh-CN/platforms/mac/remote)。 - + 可以。**Mac mini 可以运行 Gateway 网关**，而你的 MacBook Pro 可以作为 - **节点**（配套设备）进行连接。节点不运行 Gateway 网关——它们提供额外的 - 能力，例如该设备上的 screen/camera/canvas 和 `system.run`。 + **节点**（配套设备）连接。节点不运行 Gateway 网关——它们提供额外的 + 能力，例如该设备上的屏幕 / 摄像头 / 画布以及 `system.run`。 常见模式： - - Gateway 网关运行在 Mac mini 上（常驻）。 - - MacBook Pro 运行 macOS 应用或节点主机，并与 Gateway 网关配对。 + - Gateway 网关 运行在 Mac mini 上（始终在线）。 + - MacBook Pro 运行 macOS 应用或节点主机，并与 Gateway 网关 配对。 - 使用 `openclaw nodes status` / `openclaw nodes list` 查看它。 文档：[Nodes](/zh-CN/nodes)、[Nodes CLI](/cli/nodes)。 - - **不推荐**使用 Bun。我们观察到运行时 bug，尤其是在 WhatsApp 和 Telegram 方面。 - 如需稳定的 Gateway 网关，请使用 **Node**。 + + **不推荐**使用 Bun。我们观察到运行时 bug，尤其是在 WhatsApp 和 Telegram 上。 + 对于稳定的 Gateway 网关，请使用 **Node**。 - 如果你仍想尝试 Bun，请只在非生产 Gateway 网关上进行， + 如果你仍想尝试 Bun，请在不用于生产的 Gateway 网关 上进行， 并且不要启用 WhatsApp/Telegram。 - - `channels.telegram.allowFrom` 填的是**人工发送者的 Telegram 用户 ID**（数字）。它不是机器人用户名。 + + `channels.telegram.allowFrom` 填的是**人工发送者的 Telegram 用户 ID**（数字），不是机器人用户名。 设置流程只接受数字用户 ID。如果你的配置中已经有遗留的 `@username` 条目，`openclaw doctor --fix` 可以尝试解析它们。 更安全的方式（无需第三方机器人）： - - 给你的机器人发私信，然后运行 `openclaw logs --follow` 并读取 `from.id`。 + - 私信你的机器人，然后运行 `openclaw logs --follow`，读取 `from.id`。 官方 Bot API： - - 给你的机器人发私信，然后调用 `https://api.telegram.org/bot/getUpdates` 并读取 `message.from.id`。 + - 私信你的机器人，然后调用 `https://api.telegram.org/bot/getUpdates`，读取 `message.from.id`。 第三方方式（隐私性较差）： - - 给 `@userinfobot` 或 `@getidsbot` 发私信。 + - 私信 `@userinfobot` 或 `@getidsbot`。 - 参见 [/channels/telegram](/zh-CN/channels/telegram#access-control-and-activation)。 + 请参阅 [/channels/telegram](/zh-CN/channels/telegram#access-control-and-activation)。 - - 可以，通过**多智能体路由**实现。将每个发送者的 WhatsApp **私信**（peer `kind: "direct"`，发送者 E.164，如 `+15551234567`）绑定到不同的 `agentId`，这样每个人都会拥有自己的工作区和会话存储。回复仍然来自**同一个 WhatsApp 账户**，而私信访问控制（`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`）对于每个 WhatsApp 账户是全局的。参见 [Multi-Agent Routing](/zh-CN/concepts/multi-agent) 和 [WhatsApp](/zh-CN/channels/whatsapp)。 + + 可以，通过**多智能体路由**实现。将每个发送者的 WhatsApp **私信**（peer `kind: "direct"`，发送者 E.164 格式如 `+15551234567`）绑定到不同的 `agentId`，这样每个人都会有自己的工作区和会话存储。回复仍然来自**同一个 WhatsApp 账户**，而私信访问控制（`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`）对每个 WhatsApp 账户都是全局的。请参阅 [Multi-Agent Routing](/zh-CN/concepts/multi-agent) 和 [WhatsApp](/zh-CN/channels/whatsapp)。 - - 可以。使用多智能体路由：为每个智能体配置各自的默认模型，然后将入站路由（提供商账户或特定 peers）绑定到对应智能体。示例配置见 [Multi-Agent Routing](/zh-CN/concepts/multi-agent)。另请参阅 [Models](/zh-CN/concepts/models) 和 [Configuration](/zh-CN/gateway/configuration)。 + + 可以。使用多智能体路由：给每个智能体设置各自的默认模型，然后将入站路由（提供商账户或特定 peer）绑定到对应智能体。示例配置见 [Multi-Agent Routing](/zh-CN/concepts/multi-agent)。另请参阅 [Models](/zh-CN/concepts/models) 和 [Configuration](/zh-CN/gateway/configuration)。 - + 可以。Homebrew 支持 Linux（Linuxbrew）。快速设置： ```bash @@ -807,23 +810,23 @@ x-i18n: brew install ``` - 如果你通过 systemd 运行 OpenClaw，请确保服务的 PATH 包含 `/home/linuxbrew/.linuxbrew/bin`（或你的 brew 前缀），这样 `brew` 安装的工具才能在非登录 shell 中被解析。 - 较新的构建还会在 Linux systemd 服务中预置常见的用户 bin 目录（例如 `~/.local/bin`、`~/.npm-global/bin`、`~/.local/share/pnpm`、`~/.bun/bin`），并在设置时识别 `PNPM_HOME`、`NPM_CONFIG_PREFIX`、`BUN_INSTALL`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`NVM_DIR` 和 `FNM_DIR`。 + 如果你通过 systemd 运行 OpenClaw，请确保服务的 PATH 包含 `/home/linuxbrew/.linuxbrew/bin`（或你的 brew 前缀），这样通过 `brew` 安装的工具才能在非登录 shell 中被解析。 + 较新的构建也会在 Linux systemd 服务中预置常见用户 bin 目录（例如 `~/.local/bin`、`~/.npm-global/bin`、`~/.local/share/pnpm`、`~/.bun/bin`），并在已设置时遵循 `PNPM_HOME`、`NPM_CONFIG_PREFIX`、`BUN_INSTALL`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`NVM_DIR` 和 `FNM_DIR`。 - - **可修改的（git）安装：** 完整源码检出，可编辑，最适合贡献者。 - 你可以在本地运行构建，并修改代码/文档。 - - **npm install：** 全局 CLI 安装，不包含仓库，最适合“只想跑起来”。 + - **可修改的（git）安装：**完整的源码检出，可编辑，最适合贡献者。 + 你可以在本地运行构建并修改代码 / 文档。 + - **npm install：**全局 CLI 安装，不带仓库，最适合“直接运行”。 更新来自 npm dist-tag。 文档：[入门指南](/zh-CN/start/getting-started)、[Updating](/zh-CN/install/updating)。 - - 可以。安装另一种方式后，运行 Doctor，让 Gateway 网关服务指向新的入口点。 + + 可以。安装另一种方式，然后运行 Doctor，让 Gateway 网关 服务指向新的入口点。 这**不会删除你的数据**——它只会更改 OpenClaw 的代码安装方式。你的状态 （`~/.openclaw`）和工作区（`~/.openclaw/workspace`）都会保持不变。 @@ -846,48 +849,48 @@ x-i18n: openclaw gateway restart ``` - Doctor 会检测 Gateway 网关服务入口点不匹配的问题，并提供将服务配置重写为与当前安装一致的选项（在自动化中使用 `--repair`）。 + Doctor 会检测 Gateway 网关 服务入口点不匹配的问题，并提供重写服务配置以匹配当前安装的选项（在自动化中使用 `--repair`）。 - 备份提示：参见 [备份策略](#where-things-live-on-disk)。 + 备份建议：请参阅 [备份策略](#where-things-live-on-disk)。 - + 简短回答：**如果你想要 24/7 的可靠性，就用 VPS**。如果你想要 - 最低的使用门槛，并且能接受睡眠/重启带来的影响，就在本地运行。 + 最低的使用门槛，并且能接受睡眠 / 重启带来的影响，那就在本地运行。 **笔记本电脑（本地 Gateway 网关）** - - **优点：** 无服务器成本，可直接访问本地文件，有可见的浏览器窗口。 - - **缺点：** 睡眠/网络中断 = 连接断开，操作系统更新/重启会中断，必须保持唤醒。 + - **优点：**没有服务器成本，可直接访问本地文件，有可见的实时浏览器窗口。 + - **缺点：**睡眠 / 网络中断 = 连接断开，操作系统更新 / 重启会打断运行，必须保持唤醒状态。 **VPS / 云端** - - **优点：** 常驻在线，网络稳定，没有笔记本电脑睡眠问题，更容易保持持续运行。 - - **缺点：** 通常是无头运行（使用截图），只能远程访问文件，你必须通过 SSH 更新。 + - **优点：**始终在线，网络稳定，没有笔记本睡眠问题，更容易保持持续运行。 + - **缺点：**通常以无头方式运行（使用截图），只能远程访问文件，更新时你必须通过 SSH 操作。 - **OpenClaw 特有说明：** WhatsApp/Telegram/Slack/Mattermost/Discord 在 VPS 上都能正常运行。唯一真正的权衡是**无头浏览器**还是可见窗口。参见 [Browser](/zh-CN/tools/browser)。 + **OpenClaw 特定说明：**WhatsApp/Telegram/Slack/Mattermost/Discord 在 VPS 上都能正常工作。唯一真正的权衡是**无头浏览器**与可见窗口之间的区别。请参阅 [Browser](/zh-CN/tools/browser)。 - **推荐默认方案：** 如果你之前遇到过 Gateway 网关断连，请选择 VPS。本地方案很适合你正在积极使用 Mac，并希望访问本地文件或通过可见浏览器进行 UI 自动化的情况。 + **推荐默认方案：**如果你之前遇到过 Gateway 网关 断开连接的问题，就用 VPS。本地运行非常适合你正在积极使用 Mac，并且想要访问本地文件或通过可见浏览器执行 UI 自动化的时候。 - - 不是必需的，但**为了可靠性和隔离性，推荐这样做**。 + + 不是必须，但**出于可靠性和隔离考虑，推荐这样做**。 - - **专用主机（VPS/Mac mini/Pi）：** 常驻在线，更少睡眠/重启中断，权限更干净，更容易保持持续运行。 - - **共享笔记本电脑/台式机：** 对测试和主动使用来说完全没问题，但机器睡眠或更新时预计会有暂停。 + - **专用主机（VPS/Mac mini/Pi）：**始终在线，更少受到睡眠 / 重启中断影响，权限更清晰，更容易保持持续运行。 + - **共享笔记本 / 台式机：**用于测试和活跃使用完全没问题，但机器进入睡眠或更新时，预期会出现暂停。 - 如果你想兼顾两者，请将 Gateway 网关放在专用主机上运行，并将你的笔记本电脑配对为一个**节点**，用于本地 screen/camera/exec 工具。参见 [Nodes](/zh-CN/nodes)。 - 有关安全指导，请阅读 [Security](/zh-CN/gateway/security)。 + 如果你想两者兼得，可以将 Gateway 网关 放在专用主机上运行，并将你的笔记本配对为一个**节点**，用于本地屏幕 / 摄像头 / exec 工具。请参阅 [Nodes](/zh-CN/nodes)。 + 有关安全建议，请阅读 [Security](/zh-CN/gateway/security)。 - - OpenClaw 很轻量。对于一个基础 Gateway 网关 + 一个聊天渠道： + + OpenClaw 很轻量。对于基础的 Gateway 网关 + 一个聊天渠道： - - **绝对最低配置：** 1 vCPU、1GB RAM、约 500MB 磁盘空间。 - - **推荐配置：** 1-2 vCPU、2GB RAM 或更多余量（日志、媒体、多个渠道）。节点工具和浏览器自动化可能比较吃资源。 + - **绝对最低配置：**1 vCPU、1GB RAM、约 500MB 磁盘。 + - **推荐配置：**1-2 vCPU、2GB RAM 或更多余量（日志、媒体、多个渠道）。节点工具和浏览器自动化可能比较吃资源。 操作系统：使用 **Ubuntu LTS**（或任何现代 Debian/Ubuntu）。Linux 安装路径在这些系统上测试最充分。 @@ -896,18 +899,18 @@ x-i18n: - 可以。把虚拟机视作 VPS 即可：它需要始终在线、可访问，并且有足够的 - RAM 供 Gateway 网关和你启用的任何渠道使用。 + 可以。将虚拟机视作 VPS 即可：它需要始终在线、可访问，并且有足够的 + RAM 来运行 Gateway 网关 以及你启用的所有渠道。 - 基线建议： + 基本建议： - - **绝对最低配置：** 1 vCPU、1GB RAM。 - - **推荐配置：** 如果你运行多个渠道、浏览器自动化或媒体工具，建议使用 2GB RAM 或更多。 - - **操作系统：** Ubuntu LTS 或其他现代 Debian/Ubuntu。 + - **绝对最低配置：**1 vCPU、1GB RAM。 + - **推荐配置：**如果你运行多个渠道、浏览器自动化或媒体工具，建议使用 2GB RAM 或更多。 + - **操作系统：**Ubuntu LTS 或其他现代 Debian/Ubuntu。 - 如果你使用的是 Windows，**WSL2 是最容易的虚拟机式部署方式**，而且工具兼容性最好。 - 参见 [Windows](/zh-CN/platforms/windows)、[VPS hosting](/zh-CN/vps)。 - 如果你是在虚拟机中运行 macOS，请参见 [macOS VM](/zh-CN/install/macos-vm)。 + 如果你使用的是 Windows，**WSL2 是最简单的类虚拟机设置方式**，并且拥有最佳的工具 + 兼容性。请参阅 [Windows](/zh-CN/platforms/windows)、[VPS hosting](/zh-CN/vps)。 + 如果你是在虚拟机中运行 macOS，请参阅 [macOS VM](/zh-CN/install/macos-vm)。 @@ -916,83 +919,82 @@ x-i18n: - OpenClaw 是一个运行在你自己设备上的个人 AI 助手。它会在你已经使用的消息界面上回复你（WhatsApp、Telegram、Slack、Mattermost、Discord、Google Chat、Signal、iMessage、WebChat，以及像 QQ Bot 这样的内置渠道插件），并且在受支持的平台上还可以提供语音 + 实时 Canvas。**Gateway 网关**是始终在线的控制平面；这个助手本身才是产品。 + OpenClaw 是一个运行在你自己设备上的个人 AI 助手。它会在你已经使用的消息界面上回复你（WhatsApp、Telegram、Slack、Mattermost、Discord、Google Chat、Signal、iMessage、WebChat，以及像 QQ Bot 这样的内置渠道插件），并且在受支持的平台上还可以提供语音 + 实时 Canvas。**Gateway 网关**是始终在线的控制平面；而这个助手本身才是产品。 - OpenClaw 不只是“Claude 的封装”。它是一个**local-first 控制平面**，让你能够在**自己的硬件上** - 运行一个强大的助手，并通过你已经使用的聊天应用访问它，同时具备 - 有状态会话、记忆和工具——而不必把你的工作流控制权交给托管式 + OpenClaw 并不只是“Claude 的一层封装”。它是一个**本地优先的控制平面**，让你能够在**自己的硬件上** + 运行一个功能强大的助手，并通过你已经在使用的聊天应用访问它，同时具备 + 有状态会话、记忆和工具能力——而无需将你的工作流控制权交给托管式 SaaS。 亮点： - - **你的设备，你的数据：** 你可以在任何地方运行 Gateway 网关（Mac、Linux、VPS），并让 + - **你的设备，你的数据：**你可以将 Gateway 网关 运行在任何你想要的地方（Mac、Linux、VPS），并将 工作区 + 会话历史保留在本地。 - - **真实渠道，而不是网页沙箱：** WhatsApp/Telegram/Slack/Discord/Signal/iMessage 等， - 并且在受支持的平台上还支持移动语音和 Canvas。 - - **模型无关：** 使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，并支持按智能体路由 - 和故障转移。 - - **纯本地选项：** 如果你愿意，可以运行本地模型，让**所有数据都保留在你的设备上**。 - - **多智能体路由：** 按渠道、账户或任务拆分不同智能体，每个都有自己的 + - **真实渠道，而不是 Web 沙箱：**WhatsApp/Telegram/Slack/Discord/Signal/iMessage 等， + 并且在受支持平台上还提供移动端语音和 Canvas。 + - **与模型无关：**可以使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，并支持按智能体路由 + 和故障切换。 + - **纯本地选项：**运行本地模型，这样**所有数据都可以保留在你的设备上**，如果你愿意的话。 + - **多智能体路由：**按渠道、账户或任务拆分不同智能体，每个智能体都有自己的 工作区和默认设置。 - - **开源且可修改：** 可检查、可扩展、可自托管，无供应商锁定。 + - **开源且可修改：**可以检查、扩展和自托管，无需被供应商锁定。 - 文档：[Gateway 网关](/zh-CN/gateway)、[渠道](/zh-CN/channels)、[Multi-agent](/zh-CN/concepts/multi-agent)、 + 文档：[Gateway 网关](/zh-CN/gateway)、[Channels](/zh-CN/channels)、[多智能体](/zh-CN/concepts/multi-agent)、 [Memory](/zh-CN/concepts/memory)。 - - 很好的起步项目包括： + + 很适合作为起步的项目包括： - - 搭建一个网站（WordPress、Shopify 或简单的静态站点）。 - - 制作一个移动应用原型（大纲、界面、API 方案）。 + - 搭建网站（WordPress、Shopify 或简单的静态站点）。 + - 制作移动应用原型（大纲、界面、API 计划）。 - 整理文件和文件夹（清理、命名、打标签）。 - - 连接 Gmail，并自动化摘要或后续跟进。 + - 连接 Gmail，并自动化生成摘要或后续跟进。 - 它可以处理大型任务，但当你把任务拆成多个阶段，并 - 使用子智能体并行工作时，效果通常最好。 + 它可以处理大型任务，但当你将任务拆分成多个阶段并 + 使用子智能体并行处理时，效果通常最好。 - + 日常收益通常体现在这些方面： - - **个人简报：** 总结你关心的收件箱、日历和新闻。 - - **研究与起草：** 快速研究、摘要，以及邮件或文档的初稿。 - - **提醒和后续跟进：** 由 cron 或 Heartbeat 驱动的提醒和清单。 - - **浏览器自动化：** 填表、采集数据、重复执行网页任务。 - - **跨设备协同：** 从手机发起任务，让 Gateway 网关在服务器上执行，再把结果返回到聊天中。 + - **个人简报：**对收件箱、日历和你关心的新闻进行摘要。 + - **研究与起草：**快速研究、摘要，以及邮件或文档的初稿。 + - **提醒与跟进：**由 cron 或 Heartbeat 驱动的提示和清单。 + - **浏览器自动化：**填写表单、采集数据、重复执行网页任务。 + - **跨设备协同：**在手机上发送任务，让 Gateway 网关 在服务器上执行，然后把结果返回到聊天中。 - - 对于**研究、筛选和起草**，可以。它可以扫描网站、建立候选名单、 - 总结潜在客户，并撰写外联文案或广告文案草稿。 + + 可以，用于**研究、筛选和起草**。它可以扫描网站、建立候选清单、 + 汇总潜在客户信息，并撰写外联或广告文案草稿。 - 对于**外联或广告投放**，请保留人工参与。避免垃圾信息，遵守当地法律和 - 平台政策，并在发送前审核所有内容。最安全的模式是让 + 对于**外联或广告投放**，请始终保留人工参与。避免垃圾信息，遵守当地法律和 + 平台政策，并在发送前审查所有内容。最安全的模式是让 OpenClaw 起草，由你审批。 文档：[Security](/zh-CN/gateway/security)。 - - OpenClaw 是一个**个人助手**和协同层，而不是 IDE 替代品。对于仓库中的 - 最高效直接编码循环，请使用 Claude Code 或 Codex。当你 - 需要持久记忆、跨设备访问和工具编排时，请使用 OpenClaw。 + + OpenClaw 是一个**个人助手**和协调层，而不是 IDE 替代品。想要在仓库中获得最快的直接编码循环， + 请使用 Claude Code 或 Codex。想要持久记忆、跨设备访问和工具编排时，再使用 OpenClaw。 优势： - - **跨会话的持久记忆 + 工作区** + - **持久记忆 + 工作区**，跨会话保留 - **多平台访问**（WhatsApp、Telegram、TUI、WebChat） - **工具编排**（浏览器、文件、调度、hooks） - **始终在线的 Gateway 网关**（可运行在 VPS 上，随时随地交互） - - 用于本地 browser/screen/camera/exec 的 **Nodes** + - 用于本地浏览器 / 屏幕 / 摄像头 / exec 的 **Nodes** - 展示：[https://openclaw.ai/showcase](https://openclaw.ai/showcase) + 展示页：[https://openclaw.ai/showcase](https://openclaw.ai/showcase) @@ -1000,69 +1002,69 @@ x-i18n: ## Skills 和自动化 - - 使用托管覆盖，而不是直接编辑仓库副本。把你的修改放到 `~/.openclaw/skills//SKILL.md`（或通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加文件夹）。优先级为 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`，因此托管覆盖仍会在不触碰 git 的情况下覆盖内置 Skills。如果你需要全局安装某个 skill，但只希望某些智能体可见，请把共享副本放在 `~/.openclaw/skills` 中，并通过 `agents.defaults.skills` 和 `agents.list[].skills` 控制可见性。只有值得上游提交的修改才应该放在仓库里并以 PR 形式提交。 + + 使用受管覆盖，而不是直接编辑仓库副本。把你的改动放到 `~/.openclaw/skills//SKILL.md`（或通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加文件夹）。优先级顺序是 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`，因此受管覆盖仍然会在不触碰 git 的情况下覆盖内置 Skills。如果你需要全局安装某个 skill，但只让部分智能体可见，请将共享副本保存在 `~/.openclaw/skills` 中，并通过 `agents.defaults.skills` 和 `agents.list[].skills` 控制可见性。只有值得上游合并的修改才应保留在仓库中，并通过 PR 提交。 - - 可以。通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加额外目录（最低优先级）。默认优先级是 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`。`clawhub` 默认安装到 `./skills`，OpenClaw 会在下一次会话中将其视为 `/skills`。如果该 skill 只应对某些智能体可见，请同时配合 `agents.defaults.skills` 或 `agents.list[].skills` 使用。 + + 可以。通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加额外目录（最低优先级）。默认优先级是 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`。`clawhub` 默认安装到 `./skills`，OpenClaw 会在下一个会话中将其视为 `/skills`。如果该 skill 只应对特定智能体可见，请结合 `agents.defaults.skills` 或 `agents.list[].skills` 使用。 - + 当前支持的模式有： - - **Cron jobs：** 隔离作业可以为每个作业设置 `model` 覆盖。 - - **子智能体：** 将任务路由到具有不同默认模型的独立智能体。 - - **按需切换：** 使用 `/model` 随时切换当前会话模型。 + - **Cron 作业**：隔离的作业可以为每个作业设置 `model` 覆盖。 + - **子智能体**：将任务路由到默认模型不同的独立智能体。 + - **按需切换**：使用 `/model` 随时切换当前会话模型。 - 参见 [Cron jobs](/zh-CN/automation/cron-jobs)、[Multi-Agent Routing](/zh-CN/concepts/multi-agent) 和 [Slash commands](/zh-CN/tools/slash-commands)。 + 请参阅 [Cron jobs](/zh-CN/automation/cron-jobs)、[Multi-Agent Routing](/zh-CN/concepts/multi-agent) 和 [Slash commands](/zh-CN/tools/slash-commands)。 - - 对于长时间运行或并行任务，请使用**子智能体**。子智能体会在自己的会话中运行， - 返回摘要，并保持你的主聊天保持响应。 + + 对于长时间运行或并行任务，请使用**子智能体**。子智能体会在自己的会话中运行、 + 返回摘要，并让你的主聊天保持响应。 - 让你的机器人“为这个任务启动一个子智能体”，或使用 `/subagents`。 - 使用聊天中的 `/status` 查看 Gateway 网关当前正在做什么（以及它是否繁忙）。 + 你可以让机器人“为这个任务启动一个子智能体”，或者使用 `/subagents`。 + 使用聊天中的 `/status` 可以查看 Gateway 网关 当前正在做什么（以及它是否正忙）。 - token 提示：长任务和子智能体都会消耗 token。如果你关心成本，请通过 `agents.defaults.subagents.model` - 为子智能体设置一个更便宜的模型。 + 令牌提示：长任务和子智能体都会消耗令牌。如果你关心成本，可以通过 `agents.defaults.subagents.model` 为子智能体设置一个 + 更便宜的模型。 文档：[Sub-agents](/zh-CN/tools/subagents)、[Background Tasks](/zh-CN/automation/tasks)。 - - 使用线程绑定。你可以把 Discord 线程绑定到某个子智能体或会话目标，这样该线程中的后续消息就会始终停留在这个已绑定的会话上。 + + 使用线程绑定。你可以把一个 Discord 线程绑定到某个子智能体或会话目标，这样该线程中的后续消息就会持续停留在那个绑定的会话上。 基本流程： - - 使用 `sessions_spawn` 并设置 `thread: true` 启动（也可选 `mode: "session"` 以支持持久后续交互）。 + - 使用 `sessions_spawn` 并设置 `thread: true` 启动（如需持久跟进，也可额外设置 `mode: "session"`）。 - 或者通过 `/focus ` 手动绑定。 - - 使用 `/agents` 检查绑定状态。 + - 使用 `/agents` 查看绑定状态。 - 使用 `/session idle ` 和 `/session max-age ` 控制自动取消聚焦。 - 使用 `/unfocus` 解除线程绑定。 必需配置： - 全局默认值：`session.threadBindings.enabled`、`session.threadBindings.idleHours`、`session.threadBindings.maxAgeHours`。 - - Discord 覆盖：`channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours`。 - - 在 spawn 时自动绑定：设置 `channels.discord.threadBindings.spawnSubagentSessions: true`。 + - Discord 覆盖项：`channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours`。 + - 启动时自动绑定：设置 `channels.discord.threadBindings.spawnSubagentSessions: true`。 文档：[Sub-agents](/zh-CN/tools/subagents)、[Discord](/zh-CN/channels/discord)、[Configuration Reference](/zh-CN/gateway/configuration-reference)、[Slash commands](/zh-CN/tools/slash-commands)。 - - 先检查已解析的请求方路由： + + 先检查解析后的请求者路由： - - 当存在绑定线程或会话路由时，完成模式的子智能体投递会优先使用它。 - - 如果完成来源只携带一个渠道，OpenClaw 会回退到请求方会话中存储的路由（`lastChannel` / `lastTo` / `lastAccountId`），以便直接投递仍然可以成功。 - - 如果既没有绑定路由，也没有可用的存储路由，直接投递可能会失败，结果会回退为排队的会话投递，而不是立即发到聊天中。 - - 无效或陈旧的目标仍然可能导致回退到队列，或最终投递失败。 - - 如果子智能体最后一个可见的助手回复恰好是静默 token `NO_REPLY` / `no_reply`，或恰好是 `ANNOUNCE_SKIP`，OpenClaw 会有意抑制公告，而不是发送更早的陈旧进度。 - - 如果子智能体在仅进行了工具调用之后超时，公告可能会将其压缩为一段简短的部分进度摘要，而不是回放原始工具输出。 + - 完成模式的子智能体投递会在存在绑定线程或会话路由时优先使用它们。 + - 如果完成来源只携带一个渠道，OpenClaw 会回退到请求者会话中存储的路由（`lastChannel` / `lastTo` / `lastAccountId`），这样直接投递仍然可能成功。 + - 如果既没有绑定路由，也没有可用的存储路由，直接投递可能失败，结果会回退为排队的会话投递，而不是立即发到聊天中。 + - 无效或过期的目标仍然可能强制回退到队列，或导致最终投递失败。 + - 如果子会话最后一条可见的助手回复恰好是静默令牌 `NO_REPLY` / `no_reply`，或恰好是 `ANNOUNCE_SKIP`，OpenClaw 会有意抑制公告，而不是发布过时的更早进度。 + - 如果子会话在只有工具调用后超时，公告可能会将其折叠成一条简短的部分进度摘要，而不是重放原始工具输出。 调试： @@ -1075,14 +1077,14 @@ x-i18n: - Cron 在 Gateway 网关进程内运行。如果 Gateway 网关没有持续运行， + Cron 在 Gateway 网关 进程内部运行。如果 Gateway 网关 没有持续运行， 定时作业就不会执行。 检查清单： - 确认 cron 已启用（`cron.enabled`），并且没有设置 `OPENCLAW_SKIP_CRON`。 - - 检查 Gateway 网关是否在 24/7 持续运行（没有睡眠/重启）。 - - 验证作业的时区设置（`--tz` 与主机时区）。 + - 检查 Gateway 网关 是否在 24/7 持续运行（没有睡眠 / 重启）。 + - 验证作业的时区设置（`--tz` 与主机时区是否一致）。 调试： @@ -1098,14 +1100,14 @@ x-i18n: 先检查投递模式： - - `--no-deliver` / `delivery.mode: "none"` 表示不会发送任何外部消息。 - - 缺失或无效的公告目标（`channel` / `to`）表示运行器跳过了出站投递。 - - 渠道认证失败（`unauthorized`、`Forbidden`）表示运行器尝试投递了，但被凭证阻止。 - - 静默的隔离结果（仅有 `NO_REPLY` / `no_reply`）会被视为有意不投递，因此运行器也会抑制排队回退投递。 + - `--no-deliver` / `delivery.mode: "none"` 表示不期望有任何外部消息。 + - 缺少或无效的公告目标（`channel` / `to`）意味着运行器跳过了出站投递。 + - 渠道认证失败（`unauthorized`、`Forbidden`）意味着运行器尝试了投递，但被凭证阻止。 + - 静默的隔离结果（仅有 `NO_REPLY` / `no_reply`）会被视为有意不投递，因此运行器也会抑制排队的回退投递。 - 对于隔离的 cron 作业，最终投递由运行器负责。期望智能体 + 对于隔离的 cron 作业，运行器负责最终投递。智能体应当 返回一段纯文本摘要，供运行器发送。`--no-deliver` 会让 - 该结果保持内部状态；它不会让智能体改为通过 + 结果保持内部可见；它并不会让智能体改为通过 message 工具直接发送。 调试： @@ -1119,22 +1121,22 @@ x-i18n: - + 这通常是实时模型切换路径，而不是重复调度。 - 隔离的 cron 在活动运行抛出 `LiveSessionModelSwitchError` 时， - 可以持久化一次运行时模型切换并重试。重试会保留已切换的 - provider/model；如果切换还携带了新的认证配置文件覆盖，cron - 也会在重试前一并持久化。 + 隔离的 cron 可以在活动运行抛出 `LiveSessionModelSwitchError` 时， + 持久化运行时模型切换并重试。重试会保留切换后的 + 提供商 / 模型；如果切换还携带了新的认证配置文件覆盖，cron + 也会在重试前将其持久化。 相关选择规则： - - 当适用时，Gmail hook 模型覆盖优先级最高。 + - 如果适用，Gmail hook 模型覆盖优先级最高。 - 然后是每个作业的 `model`。 - 然后是任何已存储的 cron 会话模型覆盖。 - - 最后是常规的智能体/默认模型选择。 + - 最后是正常的智能体 / 默认模型选择。 - 重试循环是有边界的。初始尝试加上 2 次切换重试之后， + 重试循环是有上限的。在初始尝试加上 2 次切换重试之后， cron 会中止，而不是无限循环。 调试： @@ -1149,8 +1151,8 @@ x-i18n: - 使用原生 `openclaw skills` 命令，或直接把 Skills 放进你的工作区。macOS 的 Skills UI 在 Linux 上不可用。 - 可在 [https://clawhub.ai](https://clawhub.ai) 浏览 Skills。 + 使用原生 `openclaw skills` 命令，或将 Skills 放入你的工作区。macOS 的 Skills UI 在 Linux 上不可用。 + 你可以在 [https://clawhub.ai](https://clawhub.ai) 浏览 Skills。 ```bash openclaw skills search "calendar" @@ -1165,18 +1167,18 @@ x-i18n: 原生 `openclaw skills install` 会写入当前活动工作区的 `skills/` 目录。只有当你想发布或 - 同步你自己的 Skills 时，才需要单独安装 `clawhub` CLI。对于跨智能体共享安装，请把 skill 放到 - `~/.openclaw/skills` 下，并使用 `agents.defaults.skills` 或 - `agents.list[].skills` 来缩小可见范围（如果需要）。 + 同步自己的 Skills 时，才需要单独安装 `clawhub` CLI。对于跨智能体共享安装，请将 skill 放在 + `~/.openclaw/skills` 下，并在你想限制哪些智能体可见时使用 `agents.defaults.skills` 或 + `agents.list[].skills`。 - - 可以。使用 Gateway 网关调度器： + + 可以。使用 Gateway 网关 调度器： - - **Cron jobs**：用于定时或周期性任务（重启后仍会保留）。 + - **Cron jobs**：用于定时或周期性任务（重启后依然保留）。 - **Heartbeat**：用于“主会话”的周期性检查。 - - **隔离作业**：用于自主智能体，可发布摘要或投递到聊天。 + - **隔离作业**：用于能够发布摘要或投递到聊天中的自治智能体。 文档：[Cron jobs](/zh-CN/automation/cron-jobs)、[Automation & Tasks](/zh-CN/automation)、 [Heartbeat](/zh-CN/gateway/heartbeat)。 @@ -1184,18 +1186,18 @@ x-i18n: - 不能直接运行。macOS Skills 受 `metadata.openclaw.os` 和所需二进制文件的限制，且只有在 **Gateway 网关主机** 上满足条件时，这些 Skills 才会出现在 system prompt 中。在 Linux 上，`darwin` 专属的 Skills（如 `apple-notes`、`apple-reminders`、`things-mac`）不会加载，除非你覆盖这些限制。 + 不能直接运行。macOS Skills 受 `metadata.openclaw.os` 和所需二进制文件共同控制，并且只有在 **Gateway 网关 主机**上符合条件时，Skills 才会出现在系统提示中。在 Linux 上，`darwin` 专用 Skills（如 `apple-notes`、`apple-reminders`、`things-mac`）默认不会加载，除非你覆盖这层限制。 - 你有三种受支持的模式： + 你有三种受支持的方式： **方案 A - 在 Mac 上运行 Gateway 网关（最简单）。** - 在 macOS 二进制文件所在的机器上运行 Gateway 网关，然后通过 [远程模式](#gateway-ports-already-running-and-remote-mode) 或 Tailscale 从 Linux 连接。因为 Gateway 网关主机是 macOS，这些 Skills 会正常加载。 + 在存在 macOS 二进制文件的地方运行 Gateway 网关，然后通过 [远程模式](#gateway-ports-already-running-and-remote-mode) 或 Tailscale 从 Linux 连接。由于 Gateway 网关 主机是 macOS，这些 Skills 会正常加载。 **方案 B - 使用 macOS 节点（无需 SSH）。** - 在 Linux 上运行 Gateway 网关，配对一个 macOS 节点（菜单栏应用），并在 Mac 上将 **Node Run Commands** 设置为 “Always Ask” 或 “Always Allow”。当节点上存在所需二进制文件时，OpenClaw 可以将仅限 macOS 的 Skills 视为可用。智能体会通过 `nodes` 工具运行这些 Skills。如果你选择 “Always Ask”，在提示中批准 “Always Allow” 会将该命令加入允许列表。 + 在 Linux 上运行 Gateway 网关，配对一个 macOS 节点（菜单栏应用），并将 Mac 上的**节点运行命令**设为“Always Ask”或“Always Allow”。当节点上存在所需二进制文件时，OpenClaw 可以将仅限 macOS 的 Skills 视为符合条件。智能体会通过 `nodes` 工具运行这些 Skills。如果你选择“Always Ask”，在提示中批准“Always Allow”会将该命令加入允许列表。 **方案 C - 通过 SSH 代理 macOS 二进制文件（高级）。** - 让 Gateway 网关继续运行在 Linux 上，但将所需 CLI 二进制文件解析为在 Mac 上执行的 SSH 包装器。然后覆盖该 skill，使其允许 Linux，从而保持可用。 + 将 Gateway 网关 保留在 Linux 上，但让所需的 CLI 二进制文件解析为在 Mac 上运行的 SSH 包装器。然后覆盖该 skill，使其允许 Linux，从而保持可用。 1. 为该二进制文件创建 SSH 包装器（示例：Apple Notes 的 `memo`）： @@ -1205,35 +1207,35 @@ x-i18n: exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@" ``` - 2. 将该包装器放到 Linux 主机的 `PATH` 中（例如 `~/bin/memo`）。 - 3. 覆盖 skill 元数据（工作区或 `~/.openclaw/skills`）以允许 Linux： + 2. 将该包装器放入 Linux 主机的 `PATH` 中（例如 `~/bin/memo`）。 + 3. 覆盖该 skill 的元数据（工作区或 `~/.openclaw/skills`）以允许 Linux： ```markdown --- name: apple-notes - description: 通过 macOS 上的 memo CLI 管理 Apple Notes。 + description: Manage Apple Notes via the memo CLI on macOS. metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } } --- ``` - 4. 启动一个新会话，以刷新 Skills 快照。 + 4. 启动一个新会话，以便刷新 Skills 快照。 目前没有内置。 - 可选方案： + 可选方式： - - **自定义 skill / 插件：** 最适合稳定的 API 访问（Notion/HeyGen 都有 API）。 - - **浏览器自动化：** 无需写代码即可使用，但速度更慢，也更脆弱。 + - **自定义 skill / 插件：**最适合可靠的 API 访问（Notion/HeyGen 都有 API）。 + - **浏览器自动化：**无需编写代码即可工作，但更慢，也更脆弱。 如果你想为每个客户保留上下文（代理机构工作流），一种简单模式是： - 每个客户一个 Notion 页面（上下文 + 偏好 + 当前工作）。 - 让智能体在会话开始时获取该页面。 - 如果你想要原生集成，可以提交功能请求，或构建一个 + 如果你想要原生集成，请提交功能请求，或构建一个 面向这些 API 的 skill。 安装 Skills： @@ -1243,32 +1245,32 @@ x-i18n: openclaw skills update --all ``` - 原生安装会落到当前活动工作区的 `skills/` 目录。对于跨智能体共享的 Skills，请将它们放到 `~/.openclaw/skills//SKILL.md`。如果只希望某些智能体看到共享安装，请配置 `agents.defaults.skills` 或 `agents.list[].skills`。某些 Skills 依赖通过 Homebrew 安装的二进制文件；在 Linux 上这意味着 Linuxbrew（参见上面的 Homebrew Linux 常见问题条目）。参见 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 和 [ClawHub](/zh-CN/tools/clawhub)。 + 原生安装会落到当前活动工作区的 `skills/` 目录中。对于跨智能体共享的 Skills，请将它们放在 `~/.openclaw/skills//SKILL.md`。如果只希望部分智能体看到共享安装，请配置 `agents.defaults.skills` 或 `agents.list[].skills`。有些 Skills 依赖通过 Homebrew 安装的二进制文件；在 Linux 上这意味着 Linuxbrew（请参阅上面的 Homebrew Linux 常见问题条目）。请参阅 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 和 [ClawHub](/zh-CN/tools/clawhub)。 - - 使用内置的 `user` 浏览器配置文件，它会通过 Chrome DevTools MCP 连接： + + 使用内置的 `user` 浏览器配置文件，它会通过 Chrome DevTools MCP 进行连接： ```bash openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot ``` - 如果你想自定义名称，可以创建一个显式 MCP 配置文件： + 如果你想使用自定义名称，请创建一个显式 MCP 配置文件： ```bash openclaw browser create-profile --name chrome-live --driver existing-session openclaw browser --browser-profile chrome-live tabs ``` - 这种方式既可以使用本地主机浏览器，也可以使用已连接的浏览器节点。如果 Gateway 网关运行在其他地方，请在浏览器所在机器上运行一个节点主机，或者改用远程 CDP。 + 这种方式可以使用本地主机浏览器，也可以使用已连接的浏览器节点。如果 Gateway 网关 运行在其他地方，请在浏览器所在机器上运行节点主机，或改用远程 CDP。 当前 `existing-session` / `user` 的限制： - 操作基于 ref，而不是基于 CSS 选择器 - - 上传需要 `ref` / `inputRef`，且目前一次只支持一个文件 - - `responsebody`、PDF 导出、下载拦截和批量操作仍然需要托管浏览器或原始 CDP 配置文件 + - 上传需要 `ref` / `inputRef`，并且当前一次只支持一个文件 + - `responsebody`、PDF 导出、下载拦截和批量操作仍然需要受管浏览器或原始 CDP 配置文件 @@ -1277,147 +1279,147 @@ x-i18n: - 有。参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。对于 Docker 专属设置（Docker 中的完整 Gateway 网关或沙箱镜像），请参见 [Docker](/zh-CN/install/docker)。 + 有。请参阅 [沙箱隔离](/zh-CN/gateway/sandboxing)。如需 Docker 专用设置（Docker 中的完整 Gateway 网关 或沙箱镜像），请参阅 [Docker](/zh-CN/install/docker)。 - - 默认镜像以安全优先方式构建，并以 `node` 用户运行，因此不包含 - 系统包、Homebrew 或内置浏览器。若要获得更完整的部署： + + 默认镜像以安全优先为原则，并以 `node` 用户身份运行，因此它 + 不包含系统包、Homebrew 或内置浏览器。要获得更完整的设置： - - 持久化 `/home/node` 并使用 `OPENCLAW_HOME_VOLUME`，这样缓存可以保留。 - - 使用 `OPENCLAW_DOCKER_APT_PACKAGES` 将系统依赖烘焙进镜像。 + - 持久化 `/home/node`，使用 `OPENCLAW_HOME_VOLUME`，这样缓存就能保留下来。 + - 通过 `OPENCLAW_DOCKER_APT_PACKAGES` 将系统依赖烘焙进镜像。 - 通过内置 CLI 安装 Playwright 浏览器： `node /app/node_modules/playwright-core/cli.js install chromium` - - 设置 `PLAYWRIGHT_BROWSERS_PATH`，并确保该路径会被持久化。 + - 设置 `PLAYWRIGHT_BROWSERS_PATH`，并确保该路径被持久化。 文档：[Docker](/zh-CN/install/docker)、[Browser](/zh-CN/tools/browser)。 - - 可以——前提是你的私密流量是 **私信**，而公开流量是 **群组**。 + + 可以——前提是你的私密流量是**私信**，而公开流量是**群组**。 - 使用 `agents.defaults.sandbox.mode: "non-main"`，这样群组/渠道会话（非主键）会在 Docker 中运行，而主私信会话仍在主机上运行。然后通过 `tools.sandbox.tools` 限制沙箱隔离会话中可用的工具。 + 使用 `agents.defaults.sandbox.mode: "non-main"`，这样群组 / 渠道会话（非主键）会在 Docker 中运行，而主私信会话仍留在主机上。然后通过 `tools.sandbox.tools` 限制沙箱隔离会话中可用的工具。 - 设置演练 + 示例配置：[群组：私密私信 + 公开群组](/zh-CN/channels/groups#pattern-personal-dms-public-groups-single-agent) + 设置演练 + 示例配置：[群组：个人私信 + 公开群组](/zh-CN/channels/groups#pattern-personal-dms-public-groups-single-agent) - 关键配置参考：[Gateway 网关配置](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox) + 关键配置参考：[Gateway 网关 配置](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox) - - 将 `agents.defaults.sandbox.docker.binds` 设置为 `["host:path:mode"]`（例如 `"/home/user/src:/src:ro"`）。全局和每智能体绑定会合并；当 `scope: "shared"` 时，每智能体绑定会被忽略。对于任何敏感内容都请使用 `:ro`，并记住绑定会绕过沙箱文件系统边界。 + + 设置 `agents.defaults.sandbox.docker.binds` 为 `["host:path:mode"]`（例如 `"/home/user/src:/src:ro"`）。全局和每智能体绑定会合并；当 `scope: "shared"` 时，每智能体绑定会被忽略。对任何敏感内容都使用 `:ro`，并记住绑定会绕过沙箱文件系统边界。 - OpenClaw 会同时根据规范化路径以及通过最深已存在祖先解析得到的规范路径来验证绑定源。这意味着即使最后一个路径段尚不存在，通过父级符号链接逃逸的情况仍会以失败关闭的方式被拦截，并且在符号链接解析之后，允许根目录检查仍然适用。 + OpenClaw 会根据规范化路径以及通过最深已存在祖先解析得到的规范路径，同时校验绑定源。也就是说，即使最后一个路径段尚不存在，通过符号链接父目录逃逸的情况也仍会以失败关闭的方式被阻止，并且允许根目录检查在符号链接解析后依然适用。 - 示例和安全说明请参见 [沙箱隔离](/zh-CN/gateway/sandboxing#custom-bind-mounts) 和 [Sandbox vs Tool Policy vs Elevated](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check)。 + 示例和安全说明请参阅 [沙箱隔离](/zh-CN/gateway/sandboxing#custom-bind-mounts) 和 [Sandbox vs Tool Policy vs Elevated](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check)。 - OpenClaw 的记忆本质上就是智能体工作区中的 Markdown 文件： + OpenClaw 的记忆其实就是智能体工作区中的 Markdown 文件： - `memory/YYYY-MM-DD.md` 中的每日笔记 - - `MEMORY.md` 中整理过的长期笔记（仅主会话/私密会话） + - `MEMORY.md` 中整理过的长期笔记（仅主 / 私密会话） OpenClaw 还会运行一个**静默的预压缩记忆刷新**，以提醒模型 - 在自动压缩之前写入持久笔记。只有在工作区 - 可写时才会运行这一过程（只读沙箱会跳过）。参见 [Memory](/zh-CN/concepts/memory)。 + 在自动压缩前写入持久笔记。它仅在工作区 + 可写时运行（只读沙箱会跳过）。请参阅 [Memory](/zh-CN/concepts/memory)。 - - 让机器人**把这个事实写入记忆**。长期笔记应写入 `MEMORY.md`， - 短期上下文则放入 `memory/YYYY-MM-DD.md`。 + + 让机器人**把该事实写入记忆**。长期笔记应写入 `MEMORY.md`， + 短期上下文则写入 `memory/YYYY-MM-DD.md`。 - 这仍然是我们正在持续改进的领域。提醒模型存储记忆会有帮助； - 它知道该怎么做。如果它仍然总是遗忘，请确认 Gateway 网关每次运行时 - 使用的是同一个工作区。 + 这是我们仍在持续改进的领域。提醒模型存储记忆会有帮助； + 它会知道该怎么做。如果它还是总忘，请确认 Gateway 网关 每次运行时使用的都是同一个 + 工作区。 - 文档：[Memory](/zh-CN/concepts/memory)、[Agent workspace](/zh-CN/concepts/agent-workspace)。 + 文档：[Memory](/zh-CN/concepts/memory)、[智能体工作区](/zh-CN/concepts/agent-workspace)。 - - 记忆文件保存在磁盘上，除非你删除它们，否则会一直存在。限制来自你的 - 存储空间，而不是模型。**会话上下文** - 仍受模型上下文窗口限制，因此长对话可能会被压缩或截断。这就是为什么 - 需要记忆搜索——它只会将相关部分重新拉回上下文。 + + 记忆文件保存在磁盘上，会一直保留，直到你删除它们。限制来自你的 + 存储空间，而不是模型。**会话上下文**仍然受模型 + 上下文窗口限制，因此长对话可能会被压缩或截断。这就是为什么 + 存在记忆搜索——它只会将相关部分重新拉回上下文中。 文档：[Memory](/zh-CN/concepts/memory)、[Context](/zh-CN/concepts/context)。 - 只有当你使用 **OpenAI embeddings** 时才需要。Codex OAuth 仅涵盖聊天/补全， - **不会**授予 embeddings 访问权限，因此**使用 Codex 登录（OAuth 或 - Codex CLI 登录）** 对语义记忆搜索没有帮助。OpenAI embeddings - 仍然需要真实的 API 密钥（`OPENAI_API_KEY` 或 `models.providers.openai.apiKey`）。 + 只有当你使用 **OpenAI embeddings** 时才需要。Codex OAuth 仅覆盖聊天 / 补全， + **不**授予 embeddings 访问权限，因此**使用 Codex 登录（OAuth 或 + Codex CLI 登录）**并不能帮助进行语义记忆搜索。OpenAI embeddings + 仍然需要真实的 API key（`OPENAI_API_KEY` 或 `models.providers.openai.apiKey`）。 - 如果你没有显式设置提供商，OpenClaw 会在能够解析 API 密钥时 - 自动选择提供商（认证配置文件、`models.providers.*.apiKey` 或环境变量）。 - 如果能够解析到 OpenAI 密钥，它会优先选择 OpenAI；否则如果能解析到 Gemini 密钥， - 就选择 Gemini；再之后是 Voyage，然后是 Mistral。如果没有可用的远程密钥，记忆 - 搜索会保持禁用状态，直到你完成配置。如果你配置了本地模型路径 + 如果你没有显式设置提供商，只要 OpenClaw 能解析到 API key，它就会自动选择提供商 + （认证配置文件、`models.providers.*.apiKey` 或环境变量）。 + 如果能解析到 OpenAI key，它会优先选择 OpenAI；否则如果能解析到 Gemini key， + 就选择 Gemini；然后是 Voyage，再然后是 Mistral。如果没有可用的远程 key， + 记忆搜索会保持禁用，直到你完成配置。如果你已经配置了本地模型路径 且该路径存在，OpenClaw - 会优先选择 `local`。当你显式设置 + 会优先选择 `local`。在你显式设置 `memorySearch.provider = "ollama"` 时，也支持 Ollama。 - 如果你更想保持本地化，请设置 `memorySearch.provider = "local"`（并可选设置 + 如果你更希望保持本地化，请设置 `memorySearch.provider = "local"`（并可选设置 `memorySearch.fallback = "none"`）。如果你想使用 Gemini embeddings，请设置 `memorySearch.provider = "gemini"` 并提供 `GEMINI_API_KEY`（或 `memorySearch.remote.apiKey`）。我们支持 **OpenAI、Gemini、Voyage、Mistral、Ollama 或 local** embedding - 模型——有关设置详情，请参见 [Memory](/zh-CN/concepts/memory)。 + 模型——具体设置详情请参阅 [Memory](/zh-CN/concepts/memory)。 -## 磁盘上的文件位置 +## 磁盘上的内容位置 - - 不会——**OpenClaw 的状态在本地**，但**外部服务仍然会看到你发给它们的内容**。 + + 不会——**OpenClaw 的状态是本地的**，但**外部服务仍然会看到你发送给它们的内容**。 - - **默认本地：** 会话、记忆文件、配置和工作区都位于 Gateway 网关主机上 + - **默认本地：**会话、记忆文件、配置和工作区都位于 Gateway 网关 主机上 （`~/.openclaw` + 你的工作区目录）。 - - **出于必要而远程：** 你发送给模型提供商（Anthropic/OpenAI 等）的消息会发送到 - 它们的 API，而聊天平台（WhatsApp/Telegram/Slack 等）会在它们的 - 服务器上存储消息数据。 - - **足迹由你控制：** 使用本地模型可以让提示内容保留在你的机器上，但渠道 - 流量仍然会经过该渠道的服务器。 + - **因需求而远程：**你发送给模型提供商（Anthropic/OpenAI 等）的消息会发送到 + 它们的 API，而聊天平台（WhatsApp/Telegram/Slack 等）会将消息数据存储在 + 它们的服务器上。 + - **足迹由你控制：**使用本地模型可让提示保留在你的机器上，但渠道 + 流量仍然会经过对应渠道的服务器。 - 相关内容：[Agent workspace](/zh-CN/concepts/agent-workspace)、[Memory](/zh-CN/concepts/memory)。 + 相关内容：[智能体工作区](/zh-CN/concepts/agent-workspace)、[Memory](/zh-CN/concepts/memory)。 - + 所有内容都位于 `$OPENCLAW_STATE_DIR` 下（默认：`~/.openclaw`）： - | 路径 | 用途 | + | Path | 用途 | | --------------------------------------------------------------- | ------------------------------------------------------------------ | | `$OPENCLAW_STATE_DIR/openclaw.json` | 主配置（JSON5） | - | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | 遗留 OAuth 导入（首次使用时复制到认证配置文件中） | - | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | 认证配置文件（OAuth、API 密钥，以及可选的 `keyRef`/`tokenRef`） | + | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | 旧版 OAuth 导入（首次使用时复制到 auth profiles） | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Auth profiles（OAuth、API keys，以及可选的 `keyRef`/`tokenRef`） | | `$OPENCLAW_STATE_DIR/secrets.json` | `file` SecretRef 提供商的可选文件后备 secret 负载 | - | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | 遗留兼容文件（静态 `api_key` 条目已清理） | + | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | 旧版兼容文件（静态 `api_key` 条目已清理） | | `$OPENCLAW_STATE_DIR/credentials/` | 提供商状态（例如 `whatsapp//creds.json`） | - | `$OPENCLAW_STATE_DIR/agents/` | 每个智能体的状态（agentDir + 会话） | - | `$OPENCLAW_STATE_DIR/agents//sessions/` | 对话历史与状态（按智能体） | + | `$OPENCLAW_STATE_DIR/agents/` | 每智能体状态（agentDir + sessions） | + | `$OPENCLAW_STATE_DIR/agents//sessions/` | 对话历史和状态（按智能体） | | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | 会话元数据（按智能体） | - 遗留的单智能体路径：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移）。 + 旧版单智能体路径：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移）。 - 你的**工作区**（AGENTS.md、记忆文件、Skills 等）是独立的，通过 `agents.defaults.workspace` 配置（默认：`~/.openclaw/workspace`）。 + 你的**工作区**（AGENTS.md、记忆文件、Skills 等）是分开的，并通过 `agents.defaults.workspace` 配置（默认：`~/.openclaw/workspace`）。 这些文件位于**智能体工作区**中，而不是 `~/.openclaw`。 - - **工作区（每个智能体）**：`AGENTS.md`、`SOUL.md`、`IDENTITY.md`、`USER.md`、 - `MEMORY.md`（如果没有 `MEMORY.md`，则使用遗留回退 `memory.md`）， - `memory/YYYY-MM-DD.md`，以及可选的 `HEARTBEAT.md`。 - - **状态目录（`~/.openclaw`）**：配置、渠道/提供商状态、认证配置文件、会话、日志， + - **工作区（每智能体）**：`AGENTS.md`、`SOUL.md`、`IDENTITY.md`、`USER.md`、 + `MEMORY.md`（如果不存在 `MEMORY.md`，则使用旧版回退 `memory.md`）， + `memory/YYYY-MM-DD.md`、可选的 `HEARTBEAT.md`。 + - **状态目录（`~/.openclaw`）**：配置、渠道 / 提供商状态、auth profiles、会话、日志， 以及共享 Skills（`~/.openclaw/skills`）。 默认工作区是 `~/.openclaw/workspace`，可通过以下方式配置： @@ -1428,27 +1430,27 @@ x-i18n: } ``` - 如果机器人在重启后“遗忘”了内容，请确认 Gateway 网关每次启动时 - 使用的是同一个工作区（并记住：远程模式使用的是**Gateway 网关主机的** - 工作区，而不是你的本地笔记本电脑）。 + 如果机器人在重启后“忘记了”内容，请确认 Gateway 网关 每次启动时使用的都是同一个 + 工作区（并记住：远程模式使用的是**Gateway 网关 主机的** + 工作区，而不是你本地笔记本上的工作区）。 - 提示：如果你想保留某种持久行为或偏好，请让机器人**把它写入 - AGENTS.md 或 MEMORY.md**，而不要依赖聊天历史。 + 提示：如果你想要一种持久的行为或偏好，请让机器人**将其写入 + AGENTS.md 或 MEMORY.md**，而不是依赖聊天历史。 - 参见 [Agent workspace](/zh-CN/concepts/agent-workspace) 和 [Memory](/zh-CN/concepts/memory)。 + 请参阅 [智能体工作区](/zh-CN/concepts/agent-workspace) 和 [Memory](/zh-CN/concepts/memory)。 - 把你的**智能体工作区**放进一个**私有** git 仓库，并将其备份到某个 - 私密位置（例如 GitHub 私有仓库）。这样可以保存记忆 + AGENTS/SOUL/USER - 文件，并让你之后恢复助手的“思维”。 + 将你的**智能体工作区**放入一个**私有** git 仓库，并备份到某个 + 私有位置（例如 GitHub 私有仓库）。这样可以捕获记忆 + AGENTS/SOUL/USER + 文件，并让你日后可以恢复这个助手的“心智”。 - **不要**提交 `~/.openclaw` 下的任何内容（凭证、会话、token 或加密的 secret 负载）。 + **不要**提交 `~/.openclaw` 下的任何内容（凭证、会话、令牌或加密后的 secret 负载）。 如果你需要完整恢复，请分别备份工作区和状态目录 - （参见上面的迁移问题）。 + （请参阅上面的迁移问题）。 - 文档：[Agent workspace](/zh-CN/concepts/agent-workspace)。 + 文档：[智能体工作区](/zh-CN/concepts/agent-workspace)。 @@ -1457,13 +1459,13 @@ x-i18n: - 可以。工作区是**默认 cwd** 和记忆锚点，而不是硬性沙箱。 - 相对路径会解析到工作区内，但绝对路径仍然可以访问主机上的其他 + 可以。工作区是**默认 cwd** 和记忆锚点，而不是硬性的沙箱。 + 相对路径会在工作区内解析，但绝对路径仍然可以访问主机上的其他 位置，除非启用了沙箱隔离。如果你需要隔离，请使用 - [`agents.defaults.sandbox`](/zh-CN/gateway/sandboxing) 或每个智能体的沙箱设置。如果你 + [`agents.defaults.sandbox`](/zh-CN/gateway/sandboxing) 或每智能体沙箱设置。如果你 想让某个仓库成为默认工作目录，请将该智能体的 - `workspace` 指向仓库根目录。OpenClaw 仓库本身只是源码；除非你明确希望智能体在其中工作，否则请保持 - 工作区与其分离。 + `workspace` 指向仓库根目录。OpenClaw 仓库本身只是源代码；除非你有意让 + 智能体在其中工作，否则请将工作区与其分开。 示例（将仓库作为默认 cwd）： @@ -1480,29 +1482,29 @@ x-i18n: - 会话状态归**Gateway 网关主机**所有。如果你处于远程模式，那么你关心的会话存储位于远程机器上，而不是你的本地笔记本电脑。参见 [会话管理](/zh-CN/concepts/session)。 + 会话状态归**Gateway 网关 主机**所有。如果你处于远程模式，你需要关注的会话存储位于远程机器上，而不是本地笔记本。请参阅 [会话管理](/zh-CN/concepts/session)。 ## 配置基础 - + OpenClaw 会从 `$OPENCLAW_CONFIG_PATH` 读取可选的 **JSON5** 配置（默认：`~/.openclaw/openclaw.json`）： ``` $OPENCLAW_CONFIG_PATH ``` - 如果文件不存在，它会使用相对安全的默认值（包括默认工作区 `~/.openclaw/workspace`）。 + 如果该文件缺失，它会使用相对安全的默认值（包括默认工作区 `~/.openclaw/workspace`）。 - - 非 loopback 绑定**需要有效的 Gateway 网关认证路径**。实际来说，这意味着： + + 非 loopback 绑定**要求存在有效的 Gateway 网关 认证路径**。实际通常意味着： - - 共享密钥认证：token 或密码 - - `gateway.auth.mode: "trusted-proxy"`，并位于正确配置的非 loopback 身份感知反向代理之后 + - shared-secret 认证：令牌或密码 + - 位于正确配置的非 loopback 身份感知反向代理之后的 `gateway.auth.mode: "trusted-proxy"` ```json5 { @@ -1518,26 +1520,26 @@ x-i18n: 说明： - - `gateway.remote.token` / `.password` **不会**单独启用本地 Gateway 网关认证。 - - 只有在 `gateway.auth.*` 未设置时，本地调用路径才可以将 `gateway.remote.*` 用作回退。 + - `gateway.remote.token` / `.password` **不会**单独启用本地 Gateway 网关 认证。 + - 只有在 `gateway.auth.*` 未设置时，本地调用路径才可以把 `gateway.remote.*` 用作回退。 - 对于密码认证，请改为设置 `gateway.auth.mode: "password"` 加 `gateway.auth.password`（或 `OPENCLAW_GATEWAY_PASSWORD`）。 - - 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但无法解析，解析会以失败关闭的方式结束（不会被远程回退掩盖）。 - - 共享密钥的 Control UI 部署通过 `connect.params.auth.token` 或 `connect.params.auth.password` 进行认证（存储在 app/UI 设置中）。像 Tailscale Serve 或 `trusted-proxy` 这样的带身份信息模式则改用请求头。避免将共享密钥放入 URL。 - - 使用 `gateway.auth.mode: "trusted-proxy"` 时，同主机 loopback 反向代理仍然**不能**满足 trusted-proxy 认证。trusted proxy 必须是已配置的非 loopback 来源。 + - 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 但无法解析，则解析会以失败关闭方式处理（不会用远程回退掩盖问题）。 + - shared-secret 的 Control UI 设置通过 `connect.params.auth.token` 或 `connect.params.auth.password` 进行认证（存储在应用 / UI 设置中）。像 Tailscale Serve 或 `trusted-proxy` 这类带身份的模式则改用请求标头。避免把 shared secrets 放进 URL。 + - 当使用 `gateway.auth.mode: "trusted-proxy"` 时，同主机的 loopback 反向代理**仍然不能**满足 trusted-proxy 认证。trusted proxy 必须是一个已配置的非 loopback 来源。 - - OpenClaw 默认强制执行 Gateway 网关认证，包括 loopback。在常规默认路径下，这意味着 token 认证：如果没有配置显式认证路径，Gateway 网关启动时会解析为 token 模式，并自动生成一个 token，保存到 `gateway.auth.token`，因此**本地 WS 客户端也必须认证**。这样可以阻止其他本地进程调用 Gateway 网关。 + + OpenClaw 默认强制启用 Gateway 网关 认证，包括 loopback。在正常默认路径下，这意味着令牌认证：如果没有显式配置认证路径，Gateway 网关 启动时会解析为令牌模式并自动生成一个令牌，将其保存到 `gateway.auth.token`，因此**本地 WS 客户端必须进行认证**。这样可以阻止其他本地进程调用 Gateway 网关。 - 如果你更喜欢其他认证方式，可以显式选择密码模式（或者对于非 loopback 身份感知反向代理，选择 `trusted-proxy`）。如果你**确实**想开放 loopback，请在配置中显式设置 `gateway.auth.mode: "none"`。Doctor 可以随时为你生成 token：`openclaw doctor --generate-gateway-token`。 + 如果你更喜欢其他认证方式，可以显式选择密码模式（或者对于非 loopback 的身份感知反向代理，选择 `trusted-proxy`）。如果你**确实**想要开放的 loopback，请在配置中显式设置 `gateway.auth.mode: "none"`。Doctor 随时都可以为你生成令牌：`openclaw doctor --generate-gateway-token`。 - - Gateway 网关会监视配置并支持热重载： + + Gateway 网关 会监视配置，并支持热重载： - - `gateway.reload.mode: "hybrid"`（默认）：安全更改热应用，关键更改则重启 + - `gateway.reload.mode: "hybrid"`（默认）：安全变更热应用，关键变更则重启 - 也支持 `hot`、`restart`、`off` @@ -1555,24 +1557,24 @@ x-i18n: } ``` - - `off`：隐藏标语文本，但保留横幅标题/版本行。 + - `off`：隐藏标语文本，但保留横幅标题 / 版本行。 - `default`：每次都使用 `All your chats, one OpenClaw.`。 - - `random`：轮换显示有趣/季节性的标语（默认行为）。 + - `random`：轮换显示有趣的 / 季节性标语（默认行为）。 - 如果你想完全不显示横幅，请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 - - `web_fetch` 无需 API 密钥即可使用。`web_search` 取决于你选择的 + + `web_fetch` 无需 API key 即可使用。`web_search` 取决于你选择的 提供商： - - Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Perplexity 和 Tavily 等基于 API 的提供商需要按其常规方式配置 API 密钥。 - - Ollama Web 搜索不需要密钥，但它会使用你配置的 Ollama 主机，并要求执行 `ollama signin`。 - - DuckDuckGo 不需要密钥，但它是一个非官方的基于 HTML 的集成。 - - SearXNG 不需要密钥/可自托管；请配置 `SEARXNG_BASE_URL` 或 `plugins.entries.searxng.config.webSearch.baseUrl`。 + - Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Perplexity 和 Tavily 等基于 API 的提供商需要它们各自的常规 API key 配置。 + - Ollama Web 搜索不需要 key，但它使用你已配置的 Ollama 主机，并要求执行 `ollama signin`。 + - DuckDuckGo 不需要 key，但它是一个非官方、基于 HTML 的集成。 + - SearXNG 不需要 key / 可自托管；配置 `SEARXNG_BASE_URL` 或 `plugins.entries.searxng.config.webSearch.baseUrl`。 - **推荐方式：** 运行 `openclaw configure --section web` 并选择一个提供商。 - 环境变量替代方案： + **推荐做法：**运行 `openclaw configure --section web` 并选择一个提供商。 + 环境变量替代方式： - Brave：`BRAVE_API_KEY` - Exa：`EXA_API_KEY` @@ -1607,66 +1609,66 @@ x-i18n: }, fetch: { enabled: true, - provider: "firecrawl", // 可选；省略则自动检测 + provider: "firecrawl", // optional; omit for auto-detect }, }, }, } ``` - 提供商专属的 Web 搜索配置现在位于 `plugins.entries..config.webSearch.*` 下。 - 出于兼容性考虑，遗留的 `tools.web.search.*` 提供商路径暂时仍会加载，但新配置不应再使用它们。 - Firecrawl Web 抓取回退配置位于 `plugins.entries.firecrawl.config.webFetch.*` 下。 + 提供商特定的 Web 搜索配置现在位于 `plugins.entries..config.webSearch.*` 下。 + 出于兼容性考虑，旧版 `tools.web.search.*` 提供商路径目前仍可加载，但不应再用于新配置。 + Firecrawl 的 web-fetch 回退配置位于 `plugins.entries.firecrawl.config.webFetch.*` 下。 说明： - - 如果你使用 allowlist，请加入 `web_search`/`web_fetch`/`x_search` 或 `group:web`。 - - `web_fetch` 默认启用（除非被显式禁用）。 - - 如果省略 `tools.web.fetch.provider`，OpenClaw 会从可用凭证中自动检测第一个可用的抓取回退提供商。目前内置提供商是 Firecrawl。 + - 如果你使用允许列表，请添加 `web_search`/`web_fetch`/`x_search` 或 `group:web`。 + - `web_fetch` 默认启用（除非显式禁用）。 + - 如果省略 `tools.web.fetch.provider`，OpenClaw 会从可用凭证中自动检测第一个可用的 fetch 回退提供商。当前内置提供商是 Firecrawl。 - 守护进程会从 `~/.openclaw/.env`（或服务环境）读取环境变量。 文档：[Web tools](/zh-CN/tools/web)。 - - `config.apply` 会替换**整个配置**。如果你发送的是部分对象，其他所有内容 + + `config.apply` 会替换**整个配置**。如果你传入的是部分对象，其他所有内容 都会被移除。 恢复方式： - - 从备份恢复（git 或复制过的 `~/.openclaw/openclaw.json`）。 - - 如果没有备份，请重新运行 `openclaw doctor`，并重新配置渠道/模型。 - - 如果这不符合预期，请提交 bug，并附上你最后一次可用的配置或任何备份。 - - 本地编码智能体通常可以根据日志或历史重建一个可工作的配置。 + - 从备份恢复（git 或复制出来的 `~/.openclaw/openclaw.json`）。 + - 如果你没有备份，请重新运行 `openclaw doctor` 并重新配置渠道 / 模型。 + - 如果这不是你预期的行为，请提交 bug，并附上你最后已知的配置或任何备份。 + - 本地编码智能体通常可以根据日志或历史记录重建出一个可工作的配置。 避免方式： - 小改动请使用 `openclaw config set`。 - 交互式编辑请使用 `openclaw configure`。 - - 如果你不确定精确路径或字段结构，请先使用 `config.schema.lookup`；它会返回一个浅层 schema 节点以及直接子项摘要，便于逐步向下查看。 - - 局部 RPC 编辑请使用 `config.patch`；仅在需要完整替换配置时才使用 `config.apply`。 - - 如果你在智能体运行中使用 owner-only 的 `gateway` 工具，它仍然会拒绝写入 `tools.exec.ask` / `tools.exec.security`（包括会被规范化为同一受保护 exec 路径的遗留 `tools.bash.*` 别名）。 + - 当你不确定精确路径或字段结构时，先使用 `config.schema.lookup`；它会返回浅层 schema 节点以及直接子节点摘要，便于逐级深入。 + - 对于部分 RPC 编辑，请使用 `config.patch`；仅在需要完整替换配置时使用 `config.apply`。 + - 如果你是在智能体运行中使用仅限所有者的 `gateway` 工具，它仍会拒绝对 `tools.exec.ask` / `tools.exec.security` 的写入（包括会规范化到同一受保护 exec 路径的旧版 `tools.bash.*` 别名）。 文档：[Config](/cli/config)、[Configure](/cli/configure)、[Doctor](/zh-CN/gateway/doctor)。 - + 常见模式是**一个 Gateway 网关**（例如 Raspberry Pi）加上**节点**和**智能体**： - - **Gateway 网关（中心）：** 拥有渠道（Signal/WhatsApp）、路由和会话。 - - **节点（设备）：** Mac/iOS/Android 作为外设连接，并暴露本地工具（`system.run`、`canvas`、`camera`）。 - - **智能体（工作器）：** 用于特殊角色的独立“大脑”/工作区（例如 “Hetzner 运维”、“个人数据”）。 - - **子智能体：** 当你需要并行处理时，从主智能体启动后台工作。 - - **TUI：** 连接到 Gateway 网关并切换智能体/会话。 + - **Gateway 网关（中心）：**负责渠道（Signal/WhatsApp）、路由和会话。 + - **节点（设备）：**Mac、iOS、Android 作为外设连接，并暴露本地工具（`system.run`、`canvas`、`camera`）。 + - **智能体（worker）：**拥有不同角色的独立“大脑” / 工作区（例如“Hetzner 运维”、“个人数据”）。 + - **子智能体：**当你需要并行处理时，从主智能体中启动后台工作。 + - **TUI：**连接到 Gateway 网关，并切换智能体 / 会话。 文档：[Nodes](/zh-CN/nodes)、[Remote access](/zh-CN/gateway/remote)、[Multi-Agent Routing](/zh-CN/concepts/multi-agent)、[Sub-agents](/zh-CN/tools/subagents)、[TUI](/web/tui)。 - 可以。这是一个配置选项： + 可以。这是一个配置项： ```json5 { @@ -1679,28 +1681,28 @@ x-i18n: } ``` - 默认值是 `false`（有头模式）。无头模式在某些网站上更容易触发反机器人检查。参见 [Browser](/zh-CN/tools/browser)。 + 默认值为 `false`（有头模式）。在某些网站上，无头模式更容易触发反机器人检测。请参阅 [Browser](/zh-CN/tools/browser)。 - 无头模式使用**同一个 Chromium 引擎**，适用于大多数自动化场景（表单、点击、抓取、登录）。主要区别在于： + 无头模式使用**相同的 Chromium 引擎**，适用于大多数自动化任务（表单、点击、抓取、登录）。主要区别是： - - 没有可见的浏览器窗口（如果你需要视觉信息，请使用截图）。 - - 有些网站在无头模式下对自动化更严格（CAPTCHA、反机器人）。 - 例如，X/Twitter 通常会阻止无头会话。 + - 没有可见的浏览器窗口（如果你需要视觉效果，请使用截图）。 + - 某些网站在无头模式下对自动化更严格（CAPTCHA、反机器人）。 + 例如，X/Twitter 经常会阻止无头会话。 将 `browser.executablePath` 设置为你的 Brave 二进制文件（或任何基于 Chromium 的浏览器），然后重启 Gateway 网关。 - 完整配置示例请参见 [Browser](/zh-CN/tools/browser#use-brave-or-another-chromium-based-browser)。 + 完整配置示例请参阅 [Browser](/zh-CN/tools/browser#use-brave-or-another-chromium-based-browser)。 -## 远程 Gateway 网关和节点 +## 远程 Gateway 网关 和节点 - - Telegram 消息由**Gateway 网关**处理。Gateway 网关运行智能体， - 只有在需要节点工具时，才会通过 **Gateway WebSocket** 调用节点： + + Telegram 消息由**Gateway 网关**处理。Gateway 网关 会先运行智能体， + 然后仅在需要节点工具时，才通过 **Gateway WebSocket** 调用节点： Telegram → Gateway 网关 → 智能体 → `node.*` → 节点 → Gateway 网关 → Telegram @@ -1708,18 +1710,18 @@ x-i18n: - - 简短回答：**将你的电脑配对为一个节点**。Gateway 网关运行在别处，但它可以 - 通过 Gateway WebSocket 调用你本地机器上的 `node.*` 工具（screen、camera、system）。 + + 简短回答：**把你的电脑配对为一个节点**。Gateway 网关 运行在其他地方，但它可以 + 通过 Gateway WebSocket 调用你本地机器上的 `node.*` 工具（屏幕、摄像头、系统）。 - 典型部署方式： + 典型设置： - 1. 在始终在线的主机（VPS/家用服务器）上运行 Gateway 网关。 - 2. 将 Gateway 网关主机和你的电脑放到同一个 tailnet 中。 - 3. 确保 Gateway 网关 WS 可达（tailnet 绑定或 SSH 隧道）。 - 4. 在本地打开 macOS 应用，并以**通过 SSH 远程连接**模式（或直接 tailnet） - 连接，这样它就可以注册为一个节点。 - 5. 在 Gateway 网关上批准该节点： + 1. 在始终在线的主机（VPS / 家用服务器）上运行 Gateway 网关。 + 2. 将 Gateway 网关 主机和你的电脑放到同一个 tailnet 中。 + 3. 确保 Gateway WS 可达（tailnet 绑定或 SSH 隧道）。 + 4. 在本地打开 macOS 应用，并以**Remote over SSH** 模式（或直接 tailnet） + 连接，以便它注册为节点。 + 5. 在 Gateway 网关 上批准该节点： ```bash openclaw devices list @@ -1728,8 +1730,8 @@ x-i18n: 不需要单独的 TCP bridge；节点通过 Gateway WebSocket 连接。 - 安全提醒：配对一个 macOS 节点意味着允许在那台机器上执行 `system.run`。只 - 配对你信任的设备，并阅读 [Security](/zh-CN/gateway/security)。 + 安全提醒：配对一个 macOS 节点将允许在该机器上执行 `system.run`。请只 + 配对你信任的设备，并查看 [Security](/zh-CN/gateway/security)。 文档：[Nodes](/zh-CN/nodes)、[Gateway protocol](/zh-CN/gateway/protocol)、[macOS remote mode](/zh-CN/platforms/mac/remote)、[Security](/zh-CN/gateway/security)。 @@ -1738,90 +1740,91 @@ x-i18n: 先检查基础项： - - Gateway 网关是否在运行：`openclaw gateway status` - - Gateway 网关健康状态：`openclaw status` + - Gateway 网关 正在运行：`openclaw gateway status` + - Gateway 网关 健康状态：`openclaw status` - 渠道健康状态：`openclaw channels status` 然后验证认证和路由： - - 如果你使用 Tailscale Serve，请确保 `gateway.auth.allowTailscale` 设置正确。 - - 如果你通过 SSH 隧道连接，请确认本地隧道已建立，并且指向了正确的端口。 - - 确认你的 allowlist（私信或群组）包含你的账户。 + - 如果你使用 Tailscale Serve，请确认 `gateway.auth.allowTailscale` 设置正确。 + - 如果你通过 SSH 隧道连接，请确认本地隧道已启动，并且指向正确端口。 + - 确认你的允许列表（私信或群组）包含你的账户。 文档：[Tailscale](/zh-CN/gateway/tailscale)、[Remote access](/zh-CN/gateway/remote)、[Channels](/zh-CN/channels)。 - 可以。虽然没有内置的“机器人对机器人”桥接，但你可以通过几种 - 可靠方式把它搭起来： + 可以。虽然没有内置的“bot 对 bot”桥接，但你可以通过几种 + 可靠方式来实现： - **最简单：** 使用两个机器人都能访问的普通聊天渠道（Telegram/Slack/WhatsApp）。 - 让机器人 A 给机器人 B 发消息，然后由机器人 B 正常回复。 + **最简单：**使用两个机器人都能访问的普通聊天渠道（Telegram/Slack/WhatsApp）。 + 让机器人 A 给机器人 B 发送消息，然后让机器人 B 像平常一样回复。 - **CLI bridge（通用）：** 运行一个脚本，通过 - `openclaw agent --message ... --deliver` 调用另一个 Gateway 网关，目标设为另一个机器人 - 监听的聊天。如果其中一个机器人位于远程 VPS 上，请让你的 CLI 指向那个远程 Gateway 网关， - 可通过 SSH/Tailscale 完成（参见 [Remote access](/zh-CN/gateway/remote)）。 + **CLI 桥接（通用）：**运行一个脚本，通过 + `openclaw agent --message ... --deliver` 调用另一个 Gateway 网关，目标是另一个机器人 + 正在监听的聊天。如果其中一个机器人位于远程 VPS 上，请让你的 CLI 指向那个远程 Gateway 网关， + 可通过 SSH/Tailscale 连接（请参阅 [Remote access](/zh-CN/gateway/remote)）。 - 示例模式（在可以访问目标 Gateway 网关的机器上运行）： + 示例模式（在能够访问目标 Gateway 网关 的机器上运行）： ```bash openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to ``` - 提示：添加一条保护规则，避免两个机器人无休止地互相循环（仅在被提及时回复、渠道 - allowlist，或“不要回复机器人消息”的规则）。 + 提示：请加上一条防护规则，避免两个机器人无限循环回复（仅响应提及、渠道 + 允许列表，或“不要回复机器人消息”的规则）。 文档：[Remote access](/zh-CN/gateway/remote)、[Agent CLI](/cli/agent)、[Agent send](/zh-CN/tools/agent-send)。 - 不需要。一个 Gateway 网关可以托管多个智能体，每个智能体都有自己的工作区、默认模型 - 和路由。这是正常的部署方式，比为每个智能体运行 - 一个单独 VPS 更便宜也更简单。 + 不需要。一个 Gateway 网关 就可以托管多个智能体，每个智能体都有自己的工作区、默认模型 + 和路由。这是正常设置，而且比每个智能体都运行 + 一个 VPS 更便宜也更简单。 - 只有在你需要强隔离（安全边界）或完全不同、且不想共享的配置时，才需要使用不同 VPS。 - 否则，请保留一个 Gateway 网关，并使用多个智能体或子智能体。 + 只有当你需要硬隔离（安全边界）或非常 + 不同、且不想共享的配置时，才需要分开使用多个 VPS。否则，保留一个 Gateway 网关，并 + 使用多个智能体或子智能体即可。 - - 有——节点是从远程 Gateway 网关访问你的笔记本电脑的第一选择方式，而且它们 - 提供的不只是 shell 访问。Gateway 网关运行在 macOS/Linux 上（Windows 通过 WSL2），并且 - 很轻量（小型 VPS 或 Raspberry Pi 级别设备就足够；4 GB RAM 已很充裕），所以一种常见 - 部署方式是使用一台常驻主机，再把你的笔记本电脑作为一个节点。 + + 有——节点是从远程 Gateway 网关 访问你笔记本电脑的一等方式，而且它们 + 提供的不仅仅是 shell 访问。Gateway 网关 运行在 macOS/Linux 上（Windows 通过 WSL2），并且 + 很轻量（小型 VPS 或 Raspberry Pi 级别的机器就足够；4 GB RAM 很充裕），因此一种常见 + 设置是始终在线的主机加上你的笔记本作为节点。 - - **无需入站 SSH。** 节点会主动向 Gateway WebSocket 发起连接，并使用设备配对。 - - **更安全的执行控制。** `system.run` 在该笔记本电脑上受节点 allowlist/审批控制。 - - **更多设备工具。** 节点除了 `system.run` 外，还暴露 `canvas`、`camera` 和 `screen`。 - - **本地浏览器自动化。** 保持 Gateway 网关在 VPS 上运行，但通过笔记本电脑上的节点主机在本地运行 Chrome，或通过 Chrome MCP 连接到主机上的本地 Chrome。 + - **不需要入站 SSH。**节点会主动连出到 Gateway WebSocket，并使用设备配对。 + - **更安全的执行控制。**`system.run` 在那台笔记本上受节点允许列表 / 审批控制。 + - **更多设备工具。**节点除了 `system.run` 外，还会暴露 `canvas`、`camera` 和 `screen`。 + - **本地浏览器自动化。**将 Gateway 网关 放在 VPS 上，但通过笔记本上的节点主机在本地运行 Chrome，或者通过 Chrome MCP 连接到主机上的本地 Chrome。 - SSH 适合临时 shell 访问，但对于持续性的智能体工作流和 + SSH 适合临时的 shell 访问，但对于持续性的智能体工作流和 设备自动化，节点更简单。 文档：[Nodes](/zh-CN/nodes)、[Nodes CLI](/cli/nodes)、[Browser](/zh-CN/tools/browser)。 - - 不会。每台主机通常只应运行**一个 Gateway 网关**，除非你有意运行隔离配置文件（参见 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)）。节点是连接到 - Gateway 网关的外设（iOS/Android 节点，或菜单栏应用中的 macOS “节点模式”）。对于无头节点 - 主机和 CLI 控制，请参见 [Node host CLI](/cli/node)。 + + 不会。除非你有意运行隔离配置文件（请参阅 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)），否则每台主机上应该只运行**一个 Gateway 网关**。节点是连接到 + Gateway 网关 的外设（iOS/Android 节点，或菜单栏应用中的 macOS“节点模式”）。有关无头节点 + 主机和 CLI 控制，请参阅 [Node host CLI](/cli/node)。 对 `gateway`、`discovery` 和 `canvasHost` 的更改需要完整重启。 - + 有。 - - `config.schema.lookup`：在写入前检查一个配置子树，包括其浅层 schema 节点、匹配的 UI 提示以及直接子项摘要 - - `config.get`：获取当前快照 + hash - - `config.patch`：安全的局部更新（大多数 RPC 编辑的首选）；在可能时热重载，必要时重启 - - `config.apply`：校验并替换完整配置；在可能时热重载，必要时重启 - - owner-only 的 `gateway` 运行时工具仍然会拒绝重写 `tools.exec.ask` / `tools.exec.security`；遗留的 `tools.bash.*` 别名会规范化为相同的受保护 exec 路径 + - `config.schema.lookup`：在写入前检查某个配置子树，包括其浅层 schema 节点、匹配的 UI 提示和直接子节点摘要 + - `config.get`：获取当前快照 + 哈希 + - `config.patch`：安全的部分更新（大多数 RPC 编辑的首选）；在可能时热重载，必要时重启 + - `config.apply`：验证并替换完整配置；在可能时热重载，必要时重启 + - 仅限所有者的 `gateway` 运行时工具仍然拒绝重写 `tools.exec.ask` / `tools.exec.security`；旧版 `tools.bash.*` 别名会规范化到相同的受保护 exec 路径 @@ -1837,23 +1840,23 @@ x-i18n: - + 最小步骤： - 1. **在 VPS 上安装 + 登录** + 1. **在 VPS 上安装并登录** ```bash curl -fsSL https://tailscale.com/install.sh | sh sudo tailscale up ``` - 2. **在你的 Mac 上安装 + 登录** + 2. **在你的 Mac 上安装并登录** - 使用 Tailscale 应用，并登录到同一个 tailnet。 3. **启用 MagicDNS（推荐）** - - 在 Tailscale 管理控制台中启用 MagicDNS，这样 VPS 就会有一个稳定名称。 + - 在 Tailscale 管理控制台中启用 MagicDNS，这样 VPS 就会有一个稳定的名称。 4. **使用 tailnet 主机名** - SSH：`ssh user@your-vps.tailnet-xxxx.ts.net` - - Gateway 网关 WS：`ws://your-vps.tailnet-xxxx.ts.net:18789` + - Gateway WS：`ws://your-vps.tailnet-xxxx.ts.net:18789` 如果你想在不使用 SSH 的情况下使用 Control UI，请在 VPS 上使用 Tailscale Serve： @@ -1861,19 +1864,19 @@ x-i18n: openclaw gateway --tailscale serve ``` - 这会让 Gateway 网关保持绑定到 loopback，并通过 Tailscale 暴露 HTTPS。参见 [Tailscale](/zh-CN/gateway/tailscale)。 + 这会让 Gateway 网关 保持绑定到 loopback，并通过 Tailscale 暴露 HTTPS。请参阅 [Tailscale](/zh-CN/gateway/tailscale)。 - Serve 会暴露 **Gateway 网关 Control UI + WS**。节点通过同一个 Gateway 网关 WS 端点连接。 + Serve 暴露的是**Gateway 网关 Control UI + WS**。节点通过同一个 Gateway WS 端点连接。 - 推荐部署方式： + 推荐设置： 1. **确保 VPS 和 Mac 位于同一个 tailnet 中**。 2. **在远程模式下使用 macOS 应用**（SSH 目标可以是 tailnet 主机名）。 - 应用会隧道化 Gateway 网关端口，并作为一个节点进行连接。 - 3. **在 Gateway 网关上批准该节点**： + 应用会隧道转发 Gateway 端口，并作为节点连接。 + 3. **在 Gateway 网关 上批准该节点**： ```bash openclaw devices list @@ -1884,30 +1887,30 @@ x-i18n: - - 如果你只需要在第二台笔记本电脑上使用**本地工具**（screen/camera/exec），那就把它添加为一个 - **节点**。这样可以保持单一 Gateway 网关，避免重复配置。本地节点工具 - 目前仅支持 macOS，但我们计划扩展到其他操作系统。 + + 如果你只需要在第二台笔记本上使用**本地工具**（屏幕 / 摄像头 / exec），就把它添加为 + **节点**。这样可以保留单个 Gateway 网关，并避免重复配置。当前本地节点工具 + 仅支持 macOS，但我们计划将其扩展到其他操作系统。 - 只有在你需要**强隔离**或两个完全独立的机器人时，才安装第二个 Gateway 网关。 + 只有在你需要**硬隔离**或两个完全独立的机器人时，才安装第二个 Gateway 网关。 文档：[Nodes](/zh-CN/nodes)、[Nodes CLI](/cli/nodes)、[多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。 -## 环境变量和 `.env` 加载 +## 环境变量和 .env 加载 - OpenClaw 会从父进程（shell、launchd/systemd、CI 等）读取环境变量，并额外加载： + OpenClaw 会从父进程（shell、launchd/systemd、CI 等）读取环境变量，并另外加载： - 当前工作目录中的 `.env` - `~/.openclaw/.env`（即 `$OPENCLAW_STATE_DIR/.env`）中的全局回退 `.env` 这两个 `.env` 文件都不会覆盖现有环境变量。 - 你也可以在配置中定义内联环境变量（仅在进程环境中缺失时才应用）： + 你也可以在配置中定义内联环境变量（仅在进程环境中缺失时应用）： ```json5 { @@ -1918,15 +1921,15 @@ x-i18n: } ``` - 完整优先级和来源请参见 [/environment](/zh-CN/help/environment)。 + 完整优先级和来源请参阅 [/environment](/zh-CN/help/environment)。 - - 两种常见修复方式： + + 两个常见修复方式： - 1. 将缺失的 key 放到 `~/.openclaw/.env` 中，这样即使服务没有继承你的 shell 环境，它们也会被读取。 - 2. 启用 shell 导入（自选便利功能）： + 1. 把缺失的 key 放进 `~/.openclaw/.env`，这样即使服务没有继承你的 shell 环境，也能被读取。 + 2. 启用 shell 导入（自选的便利功能）： ```json5 { @@ -1939,36 +1942,36 @@ x-i18n: } ``` - 这会运行你的登录 shell，并且只导入缺失的预期键名（绝不会覆盖已有值）。对应的环境变量为： + 这会运行你的登录 shell，并仅导入缺失的预期键名（永不覆盖）。对应环境变量： `OPENCLAW_LOAD_SHELL_ENV=1`、`OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`。 - - `openclaw models status` 报告的是**shell 环境导入**是否已启用。“Shell env: off” - **不**表示你的环境变量丢失了——它只表示 OpenClaw 不会 - 自动加载你的登录 shell。 + + `openclaw models status` 报告的是是否启用了**shell 环境导入**。“Shell env: off” + **并不**意味着你的环境变量缺失——它只是表示 OpenClaw 不会自动加载 + 你的登录 shell。 - 如果 Gateway 网关作为服务运行（launchd/systemd），它不会继承你的 shell - 环境。可通过以下任一方式修复： + 如果 Gateway 网关 作为服务运行（launchd/systemd），它不会继承你的 shell + 环境。可用以下方式修复： - 1. 将 token 放到 `~/.openclaw/.env` 中： + 1. 将令牌放入 `~/.openclaw/.env`： ``` COPILOT_GITHUB_TOKEN=... ``` 2. 或启用 shell 导入（`env.shellEnv.enabled: true`）。 - 3. 或将其添加到配置的 `env` 块中（仅在缺失时应用）。 + 3. 或把它添加到配置中的 `env` 块（仅在缺失时应用）。 - 然后重启 Gateway 网关并重新检查： + 然后重启 Gateway 网关 并重新检查： ```bash openclaw models status ``` - Copilot token 会从 `COPILOT_GITHUB_TOKEN` 读取（也支持 `GH_TOKEN` / `GITHUB_TOKEN`）。 - 参见 [/concepts/model-providers](/zh-CN/concepts/model-providers) 和 [/environment](/zh-CN/help/environment)。 + Copilot 令牌会从 `COPILOT_GITHUB_TOKEN` 读取（也支持 `GH_TOKEN` / `GITHUB_TOKEN`）。 + 请参阅 [/concepts/model-providers](/zh-CN/concepts/model-providers) 和 [/environment](/zh-CN/help/environment)。 @@ -1976,15 +1979,15 @@ x-i18n: ## 会话和多个聊天 - - 发送 `/new` 或 `/reset` 作为独立消息即可。参见 [会话管理](/zh-CN/concepts/session)。 + + 发送单独的一条 `/new` 或 `/reset` 消息。请参阅 [会话管理](/zh-CN/concepts/session)。 - - 会话可以在 `session.idleMinutes` 之后过期，但默认**禁用**（默认值为 **0**）。 - 将其设为正值即可启用空闲过期。启用后，空闲期结束后的**下一条** + + 会话可以在 `session.idleMinutes` 后过期，但这**默认是关闭的**（默认值为 **0**）。 + 将其设置为正数即可启用空闲过期。启用后，空闲期后的**下一条** 消息会为该聊天键启动一个新的会话 ID。 - 这不会删除对话记录——只是启动一个新会话。 + 这不会删除转录内容——它只是开始一个新会话。 ```json5 { @@ -1996,29 +1999,30 @@ x-i18n: - - 可以，通过**多智能体路由**和**子智能体**实现。你可以创建一个协调型 - 智能体和若干个拥有各自工作区与模型的工作智能体。 + + 可以，通过**多智能体路由**和**子智能体**。你可以创建一个协调者 + 智能体和若干个拥有各自工作区和模型的工作智能体。 - 不过，最好把这视为一个**有趣的实验**。它会消耗大量 token，而且通常 - 不如使用一个机器人配合多个独立会话高效。我们设想的典型模型是：你与一个机器人对话， - 同时用不同会话处理并行工作。这个机器人也可以在需要时启动子智能体。 + 不过，最好把这看作是一个**有趣的实验**。它非常耗费令牌，而且通常 + 不如使用一个机器人配合多个独立会话来得高效。我们更典型设想的模型是： + 你与一个机器人对话，用不同会话来处理并行工作。该 + 机器人也可以在需要时启动子智能体。 文档：[多智能体路由](/zh-CN/concepts/multi-agent)、[Sub-agents](/zh-CN/tools/subagents)、[Agents CLI](/cli/agents)。 - - 会话上下文受模型窗口限制。长聊天、大量工具输出或许多 + + 会话上下文受模型窗口限制。长聊天、大量工具输出或过多 文件都可能触发压缩或截断。 有帮助的做法： - 让机器人总结当前状态并写入文件。 - - 在长任务前使用 `/compact`，切换话题时使用 `/new`。 + - 在长任务前使用 `/compact`，在切换主题时使用 `/new`。 - 将重要上下文保存在工作区中，并让机器人重新读取。 - - 对于长时间或并行工作，使用子智能体，这样主聊天会保持更小。 - - 如果这种情况经常发生，请选择上下文窗口更大的模型。 + - 对于长时间或并行任务使用子智能体，这样主聊天会保持更小。 + - 如果这种情况经常发生，请选择具有更大上下文窗口的模型。 @@ -2029,7 +2033,7 @@ x-i18n: openclaw reset ``` - 非交互式完整重置： + 非交互式完全重置： ```bash openclaw reset --scope full --yes --non-interactive @@ -2043,24 +2047,24 @@ x-i18n: 说明： - - 如果检测到现有配置，新手引导也会提供**重置**选项。参见 [设置向导（CLI）](/zh-CN/start/wizard)。 - - 如果你使用了配置文件（`--profile` / `OPENCLAW_PROFILE`），请重置每个状态目录（默认是 `~/.openclaw-`）。 - - 开发环境重置：`openclaw gateway --dev --reset`（仅限开发环境；会清除开发配置 + 凭证 + 会话 + 工作区）。 + - 如果检测到现有配置，新手引导也会提供**重置**选项。请参阅 [新手引导（CLI）](/zh-CN/start/wizard)。 + - 如果你使用了 profiles（`--profile` / `OPENCLAW_PROFILE`），请重置每个状态目录（默认是 `~/.openclaw-`）。 + - 开发重置：`openclaw gateway --dev --reset`（仅开发模式；会清除开发配置 + 凭证 + 会话 + 工作区）。 - - 使用以下任一方式： + + 使用以下任一方法： - - **压缩**（保留对话，但总结较早轮次）： + - **压缩**（保留对话，但总结较早的轮次）： ``` /compact ``` - 或使用 `/compact ` 来引导摘要内容。 + 或使用 `/compact ` 来指导总结内容。 - - **重置**（为同一个聊天键生成新的会话 ID）： + - **重置**（为相同聊天键创建全新的会话 ID）： ``` /new @@ -2069,50 +2073,50 @@ x-i18n: 如果这种情况持续发生： - - 启用或调整**会话修剪**（`agents.defaults.contextPruning`），以裁剪旧的工具输出。 - - 使用上下文窗口更大的模型。 + - 启用或调整**会话修剪**（`agents.defaults.contextPruning`）以裁剪旧工具输出。 + - 使用具有更大上下文窗口的模型。 文档：[Compaction](/zh-CN/concepts/compaction)、[Session pruning](/zh-CN/concepts/session-pruning)、[会话管理](/zh-CN/concepts/session)。 - 这是提供商校验错误：模型输出了一个缺少必需 - `input` 的 `tool_use` 块。通常意味着会话历史陈旧或已损坏（常见于长线程 - 或工具/schema 变更之后）。 + 这是一个提供商校验错误：模型发出了一个 `tool_use` 块，但缺少必需的 + `input`。这通常意味着会话历史已过时或损坏（常见于长线程 + 或工具 / schema 更改之后）。 - 修复方式：使用 `/new`（独立消息）开启一个全新会话。 + 修复方法：使用 `/new` 开始一个新会话（单独发送一条消息）。 - Heartbeat 默认每 **30 分钟**运行一次（使用 OAuth 认证时为 **1 小时**）。可调整或禁用： + Heartbeat 默认每 **30m** 运行一次（使用 OAuth 认证时为 **1h**）。你可以调整或禁用它们： ```json5 { agents: { defaults: { heartbeat: { - every: "2h", // 或设为 "0m" 以禁用 + every: "2h", // or "0m" to disable }, }, }, } ``` - 如果 `HEARTBEAT.md` 存在但实际上为空（只有空行和 markdown - 标题，如 `# Heading`），OpenClaw 会跳过 Heartbeat 运行以节省 API 调用。 - 如果该文件不存在，Heartbeat 仍会运行，并由模型决定该做什么。 + 如果 `HEARTBEAT.md` 存在但实际上是空的（只有空行和 Markdown + 标题，例如 `# Heading`），OpenClaw 会跳过 Heartbeat 运行以节省 API 调用。 + 如果文件不存在，Heartbeat 仍会运行，并由模型决定要做什么。 - 每个智能体的覆盖项使用 `agents.list[].heartbeat`。文档：[Heartbeat](/zh-CN/gateway/heartbeat)。 + 每智能体覆盖使用 `agents.list[].heartbeat`。文档：[Heartbeat](/zh-CN/gateway/heartbeat)。 - - 不需要。OpenClaw 运行在**你自己的账号**上，所以只要你在群里，OpenClaw 就能看到它。 + + 不需要。OpenClaw 运行在**你自己的账号**上，所以如果你在群组里，OpenClaw 就能看到它。 默认情况下，在你允许发送者之前，群组回复会被阻止（`groupPolicy: "allowlist"`）。 - 如果你希望只有**你自己**能够触发群组回复： + 如果你只想让**你自己**能够触发群组回复： ```json5 { @@ -2128,7 +2132,7 @@ x-i18n: - 方式 1（最快）：跟踪日志，然后在群里发送一条测试消息： + 方式 1（最快）：跟踪日志，并在群组里发送一条测试消息： ```bash openclaw logs --follow --json @@ -2137,7 +2141,7 @@ x-i18n: 查找以 `@g.us` 结尾的 `chatId`（或 `from`），例如： `1234567890-1234567890@g.us`。 - 方式 2（如果已经配置/加入 allowlist）：从配置中列出群组： + 方式 2（如果已配置 / 已加入允许列表）：从配置中列出群组： ```bash openclaw directory groups list --channel whatsapp @@ -2150,48 +2154,48 @@ x-i18n: 两个常见原因： - - 提及触发已开启（默认）。你必须 @ 提及机器人（或匹配 `mentionPatterns`）。 - - 你配置了 `channels.whatsapp.groups`，但没有包含 `"*"`，且该群组不在 allowlist 中。 + - 提及门控是开启的（默认）。你必须 @ 提及机器人（或匹配 `mentionPatterns`）。 + - 你配置了 `channels.whatsapp.groups`，但没有包含 `"*"`，且该群组不在允许列表中。 - 参见 [Groups](/zh-CN/channels/groups) 和 [Group messages](/zh-CN/channels/group-messages)。 + 请参阅 [Groups](/zh-CN/channels/groups) 和 [Group messages](/zh-CN/channels/group-messages)。 - - 直接聊天默认会收敛到主会话。群组/渠道有各自独立的会话键，而 Telegram 话题 / Discord 线程也都是独立会话。参见 [Groups](/zh-CN/channels/groups) 和 [Group messages](/zh-CN/channels/group-messages)。 + + 直接聊天默认会折叠到主会话。群组 / 渠道拥有各自的会话键，而 Telegram 话题 / Discord 线程则是独立会话。请参阅 [Groups](/zh-CN/channels/groups) 和 [Group messages](/zh-CN/channels/group-messages)。 - 没有硬性限制。几十个（甚至上百个）都没问题，但请注意： + 没有硬性限制。几十个（甚至上百个）都没问题，但要注意： - - **磁盘增长：** 会话 + 转录内容保存在 `~/.openclaw/agents//sessions/` 下。 - - **token 成本：** 智能体越多，意味着并发模型使用越多。 - - **运维开销：** 每个智能体都有各自的认证配置文件、工作区和渠道路由。 + - **磁盘增长：**会话 + 转录内容位于 `~/.openclaw/agents//sessions/` 下。 + - **令牌成本：**智能体越多，并发模型使用就越多。 + - **运维开销：**每智能体的 auth profiles、工作区和渠道路由。 提示： - - 每个智能体保持一个**活动**工作区（`agents.defaults.workspace`）。 - - 如果磁盘增长，清理旧会话（删除 JSONL 或存储条目）。 - - 使用 `openclaw doctor` 发现零散工作区和配置文件不匹配问题。 + - 每个智能体保留一个**活动**工作区（`agents.defaults.workspace`）。 + - 如果磁盘增长过快，清理旧会话（删除 JSONL 或存储条目）。 + - 使用 `openclaw doctor` 发现散落的工作区和 profile 不匹配问题。 可以。使用**多智能体路由**来运行多个相互隔离的智能体，并按 - 渠道/账户/peer 路由入站消息。Slack 作为渠道受支持，也可以绑定到特定智能体。 + 渠道 / 账户 / peer 路由入站消息。Slack 作为渠道受支持，也可以绑定到特定智能体。 - 浏览器访问能力很强，但并不等于“能做人类能做的任何事”——反机器人机制、CAPTCHA 和 MFA - 仍然可能阻止自动化。若要获得最可靠的浏览器控制，请在主机上使用本地 Chrome MCP， + 浏览器访问功能很强，但并不等于“能做到人类能做的一切”——反机器人机制、CAPTCHA 和 MFA + 仍然可能阻止自动化。要获得最可靠的浏览器控制，请在主机上使用本地 Chrome MCP， 或在实际运行浏览器的机器上使用 CDP。 - 最佳实践部署方式： + 最佳实践设置： - - 始终在线的 Gateway 网关主机（VPS/Mac mini）。 - - 每个角色一个智能体（bindings）。 + - 始终在线的 Gateway 网关 主机（VPS / Mac mini）。 + - 每个角色一个智能体（绑定）。 - 将 Slack 渠道绑定到这些智能体。 - 在需要时通过 Chrome MCP 或节点使用本地浏览器。 - 文档：[Multi-Agent Routing](/zh-CN/concepts/multi-agent)、[Slack](/zh-CN/channels/slack)、 + 文档：[多智能体路由](/zh-CN/concepts/multi-agent)、[Slack](/zh-CN/channels/slack)、 [Browser](/zh-CN/tools/browser)、[Nodes](/zh-CN/nodes)。 @@ -2201,76 +2205,76 @@ x-i18n: - OpenClaw 的默认模型就是你设置在以下位置的内容： + OpenClaw 的默认模型就是你设置在这里的内容： ``` agents.defaults.model.primary ``` - 模型以 `provider/model` 的形式引用（例如：`openai/gpt-5.4`）。如果你省略了 provider，OpenClaw 会先尝试别名，然后尝试与该精确模型 id 匹配的唯一已配置 provider，最后才会退回到已配置的默认 provider，这是一条已弃用的兼容路径。如果该 provider 不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider/model，而不是暴露一个陈旧的、已移除 provider 的默认值。你仍然应该**显式**设置 `provider/model`。 + 模型使用 `provider/model` 的形式引用（例如：`openai/gpt-5.4`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该精确模型 id 唯一匹配的已配置提供商，最后才会退回到已配置默认提供商这一已弃用的兼容路径。如果该提供商不再暴露已配置的默认模型，OpenClaw 会退回到第一个已配置的提供商 / 模型，而不是继续使用一个陈旧、已移除提供商的默认值。你仍然应该**显式**设置 `provider/model`。 - - **推荐默认值：** 使用你的提供商栈中可用的最强、最新一代模型。 - **对于启用工具或处理不可信输入的智能体：** 优先考虑模型能力，而不是成本。 - **对于日常/低风险聊天：** 使用更便宜的回退模型，并按智能体角色进行路由。 + + **推荐默认值：**使用你提供商栈中可用的最强、最新一代模型。 + **对于启用了工具或接收不可信输入的智能体：**优先考虑模型能力，而不是成本。 + **对于日常 / 低风险聊天：**使用更便宜的回退模型，并按智能体角色进行路由。 - MiniMax 有自己的文档：[MiniMax](/zh-CN/providers/minimax) 和 + MiniMax 有单独文档：[MiniMax](/zh-CN/providers/minimax) 和 [Local models](/zh-CN/gateway/local-models)。 - 经验法则：对于高风险工作，使用你**负担得起的最佳模型**；而对于日常聊天或摘要， - 使用更便宜的模型。你可以按智能体路由模型，并使用子智能体来 - 并行处理长任务（每个子智能体都会消耗 token）。参见 [Models](/zh-CN/concepts/models) 和 + 经验法则：对于高风险工作，使用你**负担得起的最佳模型**；对于日常 + 聊天或摘要，使用更便宜的模型。你可以按智能体路由模型，并使用子智能体来 + 并行处理长任务（每个子智能体都会消耗令牌）。请参阅 [Models](/zh-CN/concepts/models) 和 [Sub-agents](/zh-CN/tools/subagents)。 - 强烈警告：较弱/过度量化的模型更容易受到 prompt - injection 和不安全行为的影响。参见 [Security](/zh-CN/gateway/security)。 + 强烈警告：较弱或过度量化的模型更容易受到提示 + 注入和不安全行为的影响。请参阅 [Security](/zh-CN/gateway/security)。 - 更多背景信息：[Models](/zh-CN/concepts/models)。 + 更多背景：[Models](/zh-CN/concepts/models)。 - 使用**模型命令**，或只编辑**模型**字段。避免整份配置替换。 + 使用**模型命令**，或仅编辑**模型**字段。避免完整替换配置。 - 安全方式： + 安全的选项： - - 在聊天中使用 `/model`（快速、按会话） + - 在聊天中使用 `/model`（快速，按会话） - `openclaw models set ...`（只更新模型配置） - `openclaw configure --section model`（交互式） - 编辑 `~/.openclaw/openclaw.json` 中的 `agents.defaults.model` - 除非你确实打算替换整份配置，否则不要对部分对象使用 `config.apply`。 - 对于 RPC 编辑，请先用 `config.schema.lookup` 检查，并优先使用 `config.patch`。 - lookup 负载会提供规范化路径、浅层 schema 文档/约束，以及直接子项摘要， - 以便进行局部更新。 + 除非你确实打算替换整个配置，否则避免对部分对象使用 `config.apply`。 + 对于 RPC 编辑，先用 `config.schema.lookup` 检查，并优先使用 `config.patch`。 + lookup 载荷会给你规范化路径、浅层 schema 文档 / 约束以及直接子节点摘要， + 便于进行部分更新。 如果你确实覆盖了配置，请从备份恢复，或重新运行 `openclaw doctor` 进行修复。 文档：[Models](/zh-CN/concepts/models)、[Configure](/cli/configure)、[Config](/cli/config)、[Doctor](/zh-CN/gateway/doctor)。 - + 可以。Ollama 是使用本地模型最简单的方式。 最快设置方式： 1. 从 `https://ollama.com/download` 安装 Ollama 2. 拉取一个本地模型，例如 `ollama pull gemma4` - 3. 如果你也想使用云模型，执行 `ollama signin` + 3. 如果你还想使用云模型，运行 `ollama signin` 4. 运行 `openclaw onboard` 并选择 `Ollama` 5. 选择 `Local` 或 `Cloud + Local` 说明： - `Cloud + Local` 会同时提供云模型和你的本地 Ollama 模型 - - 像 `kimi-k2.5:cloud` 这样的云模型不需要本地 pull - - 如需手动切换，请使用 `openclaw models list` 和 `openclaw models set ollama/` + - 像 `kimi-k2.5:cloud` 这样的云模型不需要本地拉取 + - 若要手动切换，请使用 `openclaw models list` 和 `openclaw models set ollama/` - 安全说明：较小或高度量化的模型更容易受到 prompt - injection 影响。对于任何可以使用工具的机器人，我们强烈推荐使用**大模型**。 - 如果你仍想使用小模型，请启用沙箱隔离和严格的工具 allowlist。 + 安全提示：较小或高度量化的模型更容易受到提示 + 注入影响。对于任何可以使用工具的机器人，我们强烈建议使用**大模型**。 + 如果你仍然想使用小模型，请启用沙箱隔离并使用严格的工具允许列表。 文档：[Ollama](/zh-CN/providers/ollama)、[Local models](/zh-CN/gateway/local-models)、 [Model providers](/zh-CN/concepts/model-providers)、[Security](/zh-CN/gateway/security)、 @@ -2279,13 +2283,13 @@ x-i18n: - - 这些部署可能不同，而且会随时间变化；没有固定的提供商推荐。 - - 使用 `openclaw models status` 检查每个 Gateway 网关上的当前运行时设置。 - - 对于安全敏感/启用工具的智能体，请使用当前可用的最强最新一代模型。 + - 这些部署可能不同，也可能随时间变化；没有固定的提供商推荐。 + - 使用 `openclaw models status` 检查每个 Gateway 网关 上当前的运行时设置。 + - 对于安全敏感 / 启用工具的智能体，请使用可用的最强、最新一代模型。 - 将 `/model` 命令作为独立消息发送： + 使用 `/model` 命令，作为单独的一条消息发送： ``` /model sonnet @@ -2301,23 +2305,23 @@ x-i18n: 你可以使用 `/model`、`/model list` 或 `/model status` 列出可用模型。 - `/model`（以及 `/model list`）会显示一个紧凑的编号选择器。按编号选择： + `/model`（以及 `/model list`）会显示一个紧凑的编号选择器。通过数字选择： ``` /model 3 ``` - 你还可以为 provider 强制指定某个认证配置文件（按会话）： + 你还可以为提供商强制指定一个特定的认证配置文件（按会话）： ``` /model opus@anthropic:default /model opus@anthropic:work ``` - 提示：`/model status` 会显示当前激活的是哪个智能体、正在使用哪个 `auth-profiles.json` 文件，以及接下来将尝试哪个认证配置文件。 - 如果可用，它还会显示已配置的 provider 端点（`baseUrl`）和 API 模式（`api`）。 + 提示：`/model status` 会显示当前活动的是哪个智能体、正在使用哪个 `auth-profiles.json` 文件，以及接下来会尝试哪个认证配置文件。 + 如果可用，它还会显示已配置的提供商端点（`baseUrl`）和 API 模式（`api`）。 - **如何取消用 `@profile` 设置的固定配置文件？** + **如何取消固定我用 @profile 设置的 profile？** 重新运行 `/model`，**不要**带 `@profile` 后缀： @@ -2325,28 +2329,28 @@ x-i18n: /model anthropic/claude-opus-4-6 ``` - 如果你想恢复默认值，请从 `/model` 中选择它（或发送 `/model `）。 - 使用 `/model status` 确认当前激活的是哪个认证配置文件。 + 如果你想回到默认值，就从 `/model` 中选择默认项（或发送 `/model `）。 + 使用 `/model status` 确认当前活动的是哪个认证配置文件。 - - 可以。将一个设为默认值，并按需切换： + + 可以。设置一个为默认值，并在需要时切换： - - **快速切换（按会话）：** 日常任务使用 `/model gpt-5.4`，编码时使用 `/model openai-codex/gpt-5.4` 配合 Codex OAuth。 - - **默认值 + 切换：** 将 `agents.defaults.model.primary` 设为 `openai/gpt-5.4`，然后在编码时切换到 `openai-codex/gpt-5.4`（反过来也可以）。 - - **子智能体：** 将编码任务路由到默认模型不同的子智能体。 + - **快速切换（按会话）：**日常任务使用 `/model gpt-5.4`，使用 Codex OAuth 编码时切换到 `/model openai-codex/gpt-5.4`。 + - **默认值 + 切换：**将 `agents.defaults.model.primary` 设置为 `openai/gpt-5.4`，然后在编码时切换到 `openai-codex/gpt-5.4`（或者反过来）。 + - **子智能体：**将编码任务路由到使用不同默认模型的子智能体。 - 参见 [Models](/zh-CN/concepts/models) 和 [Slash commands](/zh-CN/tools/slash-commands)。 + 请参阅 [Models](/zh-CN/concepts/models) 和 [Slash commands](/zh-CN/tools/slash-commands)。 - - 使用会话开关或配置默认值中的任一种： + + 你可以使用会话级切换，或配置默认值： - - **按会话：** 当会话使用 `openai/gpt-5.4` 或 `openai-codex/gpt-5.4` 时，发送 `/fast on`。 - - **每模型默认值：** 将 `agents.defaults.models["openai/gpt-5.4"].params.fastMode` 设为 `true`。 - - **Codex OAuth 也一样：** 如果你也使用 `openai-codex/gpt-5.4`，也在那边设置相同标志。 + - **按会话：**当会话正在使用 `openai/gpt-5.4` 或 `openai-codex/gpt-5.4` 时，发送 `/fast on`。 + - **按模型默认值：**将 `agents.defaults.models["openai/gpt-5.4"].params.fastMode` 设为 `true`。 + - **Codex OAuth 同样适用：**如果你也使用 `openai-codex/gpt-5.4`，请在那里设置相同标志。 示例： @@ -2371,39 +2375,39 @@ x-i18n: } ``` - 对于 OpenAI，快速模式会映射为受支持原生 Responses 请求中的 `service_tier = "priority"`。会话级 `/fast` 覆盖优先于配置默认值。 + 对于 OpenAI，fast mode 会在受支持的原生 Responses 请求中映射为 `service_tier = "priority"`。会话级 `/fast` 覆盖优先于配置默认值。 - 参见 [Thinking and fast mode](/zh-CN/tools/thinking) 和 [OpenAI fast mode](/zh-CN/providers/openai#openai-fast-mode)。 + 请参阅 [Thinking and fast mode](/zh-CN/tools/thinking) 和 [OpenAI fast mode](/zh-CN/providers/openai#openai-fast-mode)。 - - 如果设置了 `agents.defaults.models`，它就会成为 `/model` 以及任何 - 会话覆盖的**allowlist**。选择不在列表中的模型会返回： + + 如果设置了 `agents.defaults.models`，它就会成为 `/model` 和任何 + 会话覆盖的**允许列表**。选择一个不在该列表中的模型会返回： ``` Model "provider/model" is not allowed. Use /model to list available models. ``` 该错误会**替代**正常回复返回。修复方式：将该模型加入 - `agents.defaults.models`，移除 allowlist，或从 `/model list` 中选择一个模型。 + `agents.defaults.models`，删除该允许列表，或从 `/model list` 中选择一个模型。 - 这意味着**provider 未配置**（未找到 MiniMax provider 配置或认证 + 这意味着**提供商未配置**（未找到 MiniMax 提供商配置或认证 配置文件），因此无法解析该模型。 - 修复检查清单： + 修复清单： - 1. 升级到当前的 OpenClaw 版本（或从源码 `main` 运行），然后重启 Gateway 网关。 - 2. 确保已配置 MiniMax（通过向导或 JSON），或者在环境变量/认证配置文件中 - 存在 MiniMax 认证，以便注入匹配的 provider + 1. 升级到当前 OpenClaw 版本（或从源码 `main` 运行），然后重启 Gateway 网关。 + 2. 确保已配置 MiniMax（通过向导或 JSON），或者存在 MiniMax 认证， + 位于环境变量 / 认证配置文件中，以便注入匹配的提供商 （`minimax` 使用 `MINIMAX_API_KEY`，`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或已存储的 MiniMax OAuth）。 - 3. 对你的认证路径使用精确模型 id（区分大小写）： - API 密钥方式使用 `minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed`， - OAuth 方式使用 `minimax-portal/MiniMax-M2.7` / + 3. 对你的认证路径使用精确的模型 id（区分大小写）： + API key 设置使用 `minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed`， + OAuth 设置使用 `minimax-portal/MiniMax-M2.7` / `minimax-portal/MiniMax-M2.7-highspeed`。 4. 运行： @@ -2411,15 +2415,15 @@ x-i18n: openclaw models list ``` - 然后从列表中选择（或在聊天中使用 `/model list`）。 + 并从列表中选择一个（或在聊天中使用 `/model list`）。 - 参见 [MiniMax](/zh-CN/providers/minimax) 和 [Models](/zh-CN/concepts/models)。 + 请参阅 [MiniMax](/zh-CN/providers/minimax) 和 [Models](/zh-CN/concepts/models)。 - - 可以。将**MiniMax 设为默认**，并在需要时**按会话**切换模型。 - 回退是为**错误**准备的，不是为“高难度任务”准备的，因此请使用 `/model` 或单独的智能体。 + + 可以。将 **MiniMax 设为默认值**，并在需要时**按会话**切换模型。 + 回退适用于**错误**，而不是“困难任务”，所以请使用 `/model` 或单独的智能体。 **方案 A：按会话切换** @@ -2444,18 +2448,18 @@ x-i18n: /model gpt ``` - **方案 B：分成不同智能体** + **方案 B：分离智能体** - 智能体 A 默认：MiniMax - 智能体 B 默认：OpenAI - - 按智能体路由，或使用 `/agent` 进行切换 + - 按智能体路由，或使用 `/agent` 切换 文档：[Models](/zh-CN/concepts/models)、[Multi-Agent Routing](/zh-CN/concepts/multi-agent)、[MiniMax](/zh-CN/providers/minimax)、[OpenAI](/zh-CN/providers/openai)。 - - 是的。OpenClaw 附带了一些默认简写（仅当该模型存在于 `agents.defaults.models` 中时才会生效）： + + 是。OpenClaw 内置了一些默认简写（仅当模型存在于 `agents.defaults.models` 中时才会生效）： - `opus` → `anthropic/claude-opus-4-6` - `sonnet` → `anthropic/claude-sonnet-4-6` @@ -2466,11 +2470,11 @@ x-i18n: - `gemini-flash` → `google/gemini-3-flash-preview` - `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview` - 如果你设置了同名的自定义别名，则以你的值为准。 + 如果你使用了同名自定义别名，则以你的值为准。 - + 别名来自 `agents.defaults.models..alias`。示例： ```json5 @@ -2488,12 +2492,12 @@ x-i18n: } ``` - 然后 `/model sonnet`（或在支持时使用 `/`）就会解析为该模型 ID。 + 然后 `/model sonnet`（或在支持时使用 `/`）就会解析到对应模型 ID。 - OpenRouter（按 token 计费；模型众多）： + OpenRouter（按令牌付费；模型众多）： ```json5 { @@ -2521,12 +2525,11 @@ x-i18n: } ``` - 如果你引用了某个 provider/model，但缺少所需的 provider key，就会收到运行时认证错误（例如 `No API key found for provider "zai"`）。 + 如果你引用了某个提供商 / 模型，但缺少所需的提供商 key，就会收到运行时认证错误（例如 `No API key found for provider "zai"`）。 - **添加新智能体后出现 “No API key found for provider”** + **添加新智能体后显示 No API key found for provider** - 这通常意味着**新智能体**的认证存储是空的。认证按智能体隔离， - 存储在： + 这通常表示这个**新智能体**的认证存储是空的。认证是按智能体划分的，并存储在： ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -2535,118 +2538,118 @@ x-i18n: 修复方式： - 运行 `openclaw agents add `，并在向导中配置认证。 - - 或者将主智能体 `agentDir` 中的 `auth-profiles.json` 复制到新智能体的 `agentDir` 中。 + - 或者将主智能体 `agentDir` 中的 `auth-profiles.json` 复制到新智能体的 `agentDir`。 - **不要**在多个智能体之间复用 `agentDir`；这会导致认证/会话冲突。 + **不要**在多个智能体之间复用 `agentDir`；这会导致认证 / 会话冲突。 -## 模型故障转移和“所有模型都失败了” +## 模型故障切换和 “All models failed” - - 故障转移分两个阶段进行： + + 故障切换分两个阶段进行： - 1. **同一 provider 内的认证配置文件轮换**。 + 1. 同一提供商内的**认证配置文件轮换**。 2. **模型回退**到 `agents.defaults.model.fallbacks` 中的下一个模型。 - 对失败的配置文件会应用冷却时间（指数退避），因此即使某个提供商被限速或临时失败，OpenClaw 也能继续响应。 + 对失败的配置文件会应用冷却期（指数退避），因此即使某个提供商受到速率限制或暂时失败，OpenClaw 也能继续回复。 - 限速桶不仅包含普通的 `429` 响应。OpenClaw + 速率限制桶不仅包括普通的 `429` 响应。OpenClaw 还会将诸如 `Too many concurrent requests`、 `ThrottlingException`、`concurrency limit reached`、 `workers_ai ... quota limit exceeded`、`resource exhausted` 以及周期性的 - 用量窗口限制（`weekly/monthly limit reached`）等消息视为值得故障转移的 - 限速信号。 + 用量窗口限制（`weekly/monthly limit reached`）等消息视为值得进行故障切换的 + 速率限制。 - 有些看起来像计费问题的响应并不是 `402`，而有些 HTTP `402` - 响应也仍然会留在这个临时桶中。如果提供商在 `401` 或 `403` 上返回了 - 明确的计费文本，OpenClaw 仍可将其归入 - 计费路径，但 provider 专属的文本匹配器仍然限定在其所属的 - provider 范围内（例如 OpenRouter 的 `Key limit exceeded`）。如果某条 `402` - 消息看起来像是可重试的用量窗口或 - 组织/工作区支出限制（`daily limit reached, resets tomorrow`、 + 某些看起来像计费问题的响应并不是 `402`，而某些 HTTP `402` + 响应也仍会留在该瞬时故障桶中。如果提供商在 `401` 或 `403` 上返回 + 明确的计费文本，OpenClaw 仍可以把它归入 + 计费通道，但提供商特定的文本匹配器仍会限制在其 + 所属提供商内（例如 OpenRouter 的 `Key limit exceeded`）。如果某条 `402` + 消息看起来反而像一个可重试的用量窗口，或 + 组织 / 工作区支出限制（`daily limit reached, resets tomorrow`、 `organization spending limit exceeded`），OpenClaw 会将其视为 - `rate_limit`，而不是长期的计费禁用。 + `rate_limit`，而不是长期计费禁用。 - 上下文溢出错误则不同：如 + 上下文溢出错误则不同：像 `request_too_large`、`input exceeds the maximum number of tokens`、 `input token count exceeds the maximum number of input tokens`、 `input is too long for the model` 或 `ollama error: context length - exceeded` 这类签名，会停留在压缩/重试路径中，而不是推进模型 + exceeded` 这类特征，会继续走压缩 / 重试路径，而不是推进到模型 回退。 - 通用服务器错误文本的范围被有意收窄，而不是“任何带有 - unknown/error 的内容都算”。当 provider 上下文 - 匹配时，OpenClaw 确实会将 provider 范围内的临时错误形态 - 视为值得故障转移的超时/过载信号，例如 Anthropic 的裸 `An unknown error occurred`、OpenRouter 的裸 + 通用服务器错误文本的匹配范围刻意比“任何包含 + unknown/error 的内容”更窄。OpenClaw 确实会将提供商范围内的瞬时错误形态 + 视为值得故障切换的超时 / 过载信号，例如 Anthropic 的裸 `An unknown error occurred`、OpenRouter 的裸 `Provider returned error`、停止原因错误如 `Unhandled stop reason: - error`、带有临时服务器文本的 JSON `api_error` 负载 + error`、带有瞬时服务器错误文本的 JSON `api_error` 负载 （`internal server error`、`unknown error, 520`、`upstream error`、`backend - error`），以及 provider 忙碌错误如 `ModelNotReadyException`。 + error`），以及像 `ModelNotReadyException` 这样的提供商忙碌错误，前提是提供商上下文 + 匹配。 像 `LLM request failed with an unknown - error.` 这样的通用内部回退文本则保持保守，不会单独触发模型回退。 + error.` 这样的通用内部回退文本则保持保守，不会仅凭自身触发模型回退。 - 这表示系统尝试使用认证配置文件 ID `anthropic:default`，但在预期的认证存储中找不到对应凭证。 + 这表示系统尝试使用认证配置文件 ID `anthropic:default`，但无法在预期的认证存储中找到对应凭证。 - **修复检查清单：** + **修复清单：** - - **确认认证配置文件存放位置**（新路径与遗留路径） + - **确认 auth profiles 的存放位置**（新路径与旧路径） - 当前：`~/.openclaw/agents//agent/auth-profiles.json` - - 遗留：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移） - - **确认 Gateway 网关已加载你的环境变量** - - 如果你在 shell 中设置了 `ANTHROPIC_API_KEY`，但通过 systemd/launchd 运行 Gateway 网关，它可能不会继承。请将其放入 `~/.openclaw/.env`，或启用 `env.shellEnv`。 - - **确认你编辑的是正确的智能体** - - 多智能体部署意味着可能存在多个 `auth-profiles.json` 文件。 - - **做一个模型/认证状态完整性检查** + - 旧版：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移） + - **确认 Gateway 网关 已加载你的环境变量** + - 如果你在 shell 中设置了 `ANTHROPIC_API_KEY`，但 Gateway 网关 是通过 systemd/launchd 运行的，它可能不会继承该变量。请将其放入 `~/.openclaw/.env`，或启用 `env.shellEnv`。 + - **确认你正在编辑正确的智能体** + - 多智能体设置意味着可能存在多个 `auth-profiles.json` 文件。 + - **对模型 / 认证状态做基本检查** - 使用 `openclaw models status` 查看已配置模型，以及提供商是否已认证。 - **针对 “No credentials found for profile anthropic” 的修复检查清单** + **针对 “No credentials found for profile anthropic” 的修复清单** 这表示当前运行被固定到了某个 Anthropic 认证配置文件，但 Gateway 网关 - 在其认证存储中找不到它。 + 无法在其认证存储中找到它。 - **使用 Claude CLI** - - 在 Gateway 网关主机上运行 `openclaw models auth login --provider anthropic --method cli --set-default`。 - - **如果你想改用 API 密钥** - - 将 `ANTHROPIC_API_KEY` 放到**Gateway 网关主机**上的 `~/.openclaw/.env` 中。 - - 清除任何强制使用不存在配置文件的固定顺序： + - 在 Gateway 网关 主机上运行 `openclaw models auth login --provider anthropic --method cli --set-default`。 + - **如果你想改用 API key** + - 将 `ANTHROPIC_API_KEY` 放到**Gateway 网关 主机**上的 `~/.openclaw/.env` 中。 + - 清除任何会强制使用缺失配置文件的固定顺序： ```bash openclaw models auth order clear --provider anthropic ``` - - **确认你是在 Gateway 网关主机上运行命令** - - 在远程模式下，认证配置文件存放在 Gateway 网关机器上，而不是你的笔记本电脑上。 + - **确认你是在 Gateway 网关 主机上运行命令** + - 在远程模式下，auth profiles 位于 Gateway 网关 机器上，而不是你的笔记本上。 如果你的模型配置中把 Google Gemini 作为回退项（或者你切换到了 Gemini 简写），OpenClaw 就会在模型回退时尝试它。如果你没有配置 Google 凭证，就会看到 `No API key found for provider "google"`。 - 修复方式：提供 Google 认证，或者从 `agents.defaults.model.fallbacks` / 别名中移除或避免 Google 模型，这样回退就不会路由到那里。 + 修复方法：要么提供 Google 认证，要么从 `agents.defaults.model.fallbacks` / aliases 中移除或避免使用 Google 模型，这样回退就不会路由到那里。 **LLM request rejected: thinking signature required（Google Antigravity）** 原因：会话历史中包含**没有签名的 thinking 块**（通常来自 - 已中止/部分完成的流式输出）。Google Antigravity 要求 thinking 块必须带签名。 + 已中止 / 部分流式输出）。Google Antigravity 要求 thinking 块带有签名。 - 修复方式：OpenClaw 现在会为 Google Antigravity Claude 去除无签名 thinking 块。如果问题仍然存在，请开启一个**新会话**，或为该智能体设置 `/thinking off`。 + 修复方法：OpenClaw 现在会为 Google Antigravity Claude 去除无签名的 thinking 块。如果仍然出现，请开始一个**新会话**，或为该智能体设置 `/thinking off`。 -## 认证配置文件：它们是什么，以及如何管理 +## Auth profiles：它们是什么，以及如何管理 -相关内容：[/concepts/oauth](/zh-CN/concepts/oauth)（OAuth 流程、token 存储、多账户模式） +相关内容：[/concepts/oauth](/zh-CN/concepts/oauth)（OAuth 流程、令牌存储、多账户模式） - - 认证配置文件是一个与提供商绑定的命名凭证记录（OAuth 或 API 密钥）。配置文件存放在： + + auth profile 是一个绑定到提供商的具名凭证记录（OAuth 或 API key）。profiles 位于： ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -2654,95 +2657,95 @@ x-i18n: - - OpenClaw 使用带 provider 前缀的 ID，例如： + + OpenClaw 使用带提供商前缀的 ID，例如： - - `anthropic:default`（在不存在邮箱身份时很常见） - - OAuth 身份使用 `anthropic:` - - 你自定义的 ID（例如 `anthropic:work`） + - `anthropic:default`（没有电子邮件身份时很常见） + - `anthropic:` 用于 OAuth 身份 + - 你自己选择的自定义 ID（例如 `anthropic:work`） - - 可以。配置支持配置文件的可选元数据，以及每个 provider 的顺序（`auth.order.`）。这**不会**存储 secret；它只会将 ID 映射到 provider/mode，并设置轮换顺序。 + + 可以。配置支持 profiles 的可选元数据，以及每个提供商的顺序设置（`auth.order.`）。这**不会**存储 secrets；它只会把 ID 映射到 provider/mode，并设置轮换顺序。 - 如果某个配置文件处于短期**冷却**（限速/超时/认证失败）或较长期**禁用**（计费/余额不足）状态，OpenClaw 可能会暂时跳过它。要检查这一点，请运行 `openclaw models status --json` 并查看 `auth.unusableProfiles`。调优项：`auth.cooldowns.billingBackoffHours*`。 + 如果某个 profile 处于短期**冷却**状态（速率限制 / 超时 / 认证失败）或较长期的**禁用**状态（计费 / 额度不足），OpenClaw 可能会暂时跳过它。要检查这一点，请运行 `openclaw models status --json` 并查看 `auth.unusableProfiles`。调优项：`auth.cooldowns.billingBackoffHours*`。 - 限速冷却可以按模型作用域生效。某个配置文件如果正在为一个模型冷却， - 对于同一 provider 下的兄弟模型仍可能可用； - 但计费/禁用窗口仍会阻止整个配置文件。 + 速率限制冷却可以按模型划分。某个 profile 对某个模型处于冷却状态时， + 对同一提供商下的兄弟模型仍可能可用， + 而计费 / 禁用窗口仍会阻止整个 profile。 - 你也可以通过 CLI 设置**按智能体**的顺序覆盖（存储在该智能体的 `auth-state.json` 中）： + 你还可以通过 CLI 设置**每智能体**顺序覆盖（存储在该智能体的 `auth-state.json` 中）： ```bash # 默认为已配置的默认智能体（省略 --agent） openclaw models auth order get --provider anthropic - # 将轮换锁定到单一配置文件（只尝试这个） + # 将轮换锁定到单个 profile（只尝试这一个） openclaw models auth order set --provider anthropic anthropic:default - # 或设置显式顺序（provider 内部回退） + # 或设置显式顺序（提供商内回退） openclaw models auth order set --provider anthropic anthropic:work anthropic:default # 清除覆盖（回退到 config auth.order / round-robin） openclaw models auth order clear --provider anthropic ``` - 若要指定某个智能体： + 如需指定某个特定智能体： ```bash openclaw models auth order set --provider anthropic --agent main anthropic:default ``` - 要验证实际会尝试什么，请使用： + 如需验证实际会尝试什么，请使用： ```bash openclaw models status --probe ``` - 如果某个已存储配置文件被排除在显式顺序之外，probe 会为 - 该配置文件报告 `excluded_by_auth_order`，而不是静默尝试它。 + 如果某个已存储的 profile 被排除在显式顺序之外，probe 会为该 profile 报告 + `excluded_by_auth_order`，而不是默默尝试它。 - - OpenClaw 同时支持两者： + + OpenClaw 两者都支持： - - **OAuth** 通常会利用订阅访问权限（适用时）。 - - **API 密钥** 使用按 token 计费。 + - **OAuth** 通常会利用订阅访问权限（如适用）。 + - **API keys** 使用按令牌付费的计费方式。 - 向导明确支持 Anthropic Claude CLI、OpenAI Codex OAuth 和 API 密钥。 + 向导明确支持 Anthropic Claude CLI、OpenAI Codex OAuth 和 API keys。 -## Gateway 网关：端口、“已经在运行”和远程模式 +## Gateway 网关：端口、“已在运行”和远程模式 - - `gateway.port` 控制单个复用端口，用于 WebSocket + HTTP（Control UI、hooks 等）。 + + `gateway.port` 控制单一的复用端口，用于 WebSocket + HTTP（Control UI、hooks 等）。 优先级： ``` - --port > OPENCLAW_GATEWAY_PORT > gateway.port > 默认 18789 + --port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789 ``` - - 因为 “running” 是 **supervisor** 的视角（launchd/systemd/schtasks）。RPC probe 则是 CLI 实际去连接 Gateway 网关 WebSocket 并调用 `status`。 + + 因为 “running” 是 **supervisor** 的视角（launchd/systemd/schtasks）。而 connectivity probe 表示 CLI 实际尝试连接 Gateway 网关 WebSocket 的结果。 - 使用 `openclaw gateway status`，并重点看这些行： + 使用 `openclaw gateway status`，并重点关注这些行： - `Probe target:`（探测实际使用的 URL） - `Listening:`（端口上实际绑定的内容） - - `Last gateway error:`（当进程还活着但端口没有监听时，最常见的根因） + - `Last gateway error:`（当进程活着但端口未监听时，这通常是常见根因） - - 这是因为你编辑的是一个配置文件，而服务运行的是另一个配置文件（通常是 `--profile` / `OPENCLAW_STATE_DIR` 不匹配）。 + + 你正在编辑一个配置文件，而服务运行的是另一个配置文件（通常是 `--profile` / `OPENCLAW_STATE_DIR` 不匹配）。 修复方式： @@ -2750,19 +2753,19 @@ x-i18n: openclaw gateway install --force ``` - 在你希望服务使用的同一个 `--profile` / 环境下运行该命令。 + 请在你希望服务使用的同一个 `--profile` / 环境中运行该命令。 - OpenClaw 会在启动时立即绑定 WebSocket 监听器（默认 `ws://127.0.0.1:18789`），以强制运行时锁。如果绑定因 `EADDRINUSE` 失败，就会抛出 `GatewayLockError`，表示已有另一个实例正在监听。 + OpenClaw 通过在启动时立即绑定 WebSocket 监听器来强制执行运行时锁（默认是 `ws://127.0.0.1:18789`）。如果绑定因 `EADDRINUSE` 失败，它会抛出 `GatewayLockError`，表示另一个实例已经在监听。 修复方式：停止另一个实例，释放端口，或使用 `openclaw gateway --port ` 运行。 - - 设置 `gateway.mode: "remote"`，并指向远程 WebSocket URL，可选地附带共享密钥远程凭证： + + 设置 `gateway.mode: "remote"` 并指向远程 WebSocket URL，可选再加上 shared-secret 远程凭证： ```json5 { @@ -2780,54 +2783,54 @@ x-i18n: 说明： - 只有当 `gateway.mode` 为 `local` 时，`openclaw gateway` 才会启动（除非你传入覆盖标志）。 - - macOS 应用会监视配置文件，并在这些值更改时实时切换模式。 - - `gateway.remote.token` / `.password` 只是客户端侧远程凭证；它们本身不会启用本地 Gateway 网关认证。 + - macOS 应用会监视配置文件，并在这些值发生变化时实时切换模式。 + - `gateway.remote.token` / `.password` 仅用于客户端侧远程凭证；它们本身不会启用本地 Gateway 网关 认证。 - - 你的 Gateway 网关认证路径与 UI 的认证方式不匹配。 + + 你的 Gateway 网关 认证路径与 UI 的认证方式不匹配。 - 事实（来自代码）： + 事实说明（来自代码）： - - Control UI 会将 token 保存在 `sessionStorage` 中，作用域是当前浏览器标签页会话和所选 Gateway 网关 URL，因此同标签页刷新后仍可继续工作，而不需要恢复长期的 `localStorage` token 持久化。 - - 在 `AUTH_TOKEN_MISMATCH` 时，当 Gateway 网关返回重试提示（`canRetryWithDeviceToken=true`、`recommendedNextStep=retry_with_device_token`）时，受信任客户端可以使用缓存的设备 token 尝试一次有界重试。 - - 该缓存 token 重试现在会复用与设备 token 一起存储的缓存批准 scopes。显式 `deviceToken` / 显式 `scopes` 调用方仍会保留其请求的 scope 集，而不会继承缓存 scopes。 - - 在该重试路径之外，connect 认证优先级是：显式共享 token/password 优先，然后是显式 `deviceToken`，再然后是已存储设备 token，最后是 bootstrap token。 - - Bootstrap token 的 scope 检查带有角色前缀。内置 bootstrap operator allowlist 仅满足 operator 请求；node 或其他非 operator 角色仍然需要其自身角色前缀下的 scopes。 + - Control UI 会将令牌保存在 `sessionStorage` 中，作用范围是当前浏览器标签页会话和所选 Gateway 网关 URL，因此同一标签页刷新后仍能继续使用，而无需恢复长期的 localStorage 令牌持久化。 + - 当出现 `AUTH_TOKEN_MISMATCH` 时，如果 Gateway 网关 返回重试提示（`canRetryWithDeviceToken=true`、`recommendedNextStep=retry_with_device_token`），受信任客户端可以尝试使用缓存的设备令牌进行一次有界重试。 + - 该缓存令牌重试现在会复用与设备令牌一同存储的已批准 scopes。显式 `deviceToken` / 显式 `scopes` 的调用方仍会保留它们请求的 scope 集，而不会继承缓存 scopes。 + - 在该重试路径之外，连接认证优先级依次为：显式 shared token / password，然后是显式 `deviceToken`，然后是已存储设备令牌，最后是 bootstrap 令牌。 + - Bootstrap 令牌的 scope 检查带有角色前缀。内置的 bootstrap operator allowlist 只满足 operator 请求；node 或其他非 operator 角色仍需要各自角色前缀下的 scopes。 修复方式： - - 最快：`openclaw dashboard`（会打印 + 复制控制台 URL，并尝试打开；在无头环境下会显示 SSH 提示）。 - - 如果你还没有 token：`openclaw doctor --generate-gateway-token`。 - - 如果是远程：先建立隧道：`ssh -N -L 18789:127.0.0.1:18789 user@host`，然后打开 `http://127.0.0.1:18789/`。 - - 共享密钥模式：设置 `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` 或 `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`，然后在 Control UI 设置中粘贴匹配的 secret。 - - Tailscale Serve 模式：确保已启用 `gateway.auth.allowTailscale`，并且你打开的是 Serve URL，而不是绕过 Tailscale 身份头的原始 loopback/tailnet URL。 - - trusted-proxy 模式：确保你是通过已配置的非 loopback 身份感知代理进入，而不是通过同主机 loopback 代理或原始 Gateway 网关 URL。 - - 如果一次重试后仍然不匹配，请轮换/重新批准已配对的设备 token： + - 最快方式：`openclaw dashboard`（打印并复制仪表板 URL，尝试打开；无头环境下会显示 SSH 提示）。 + - 如果你还没有令牌：`openclaw doctor --generate-gateway-token`。 + - 如果是远程环境，先建立隧道：`ssh -N -L 18789:127.0.0.1:18789 user@host`，然后打开 `http://127.0.0.1:18789/`。 + - shared-secret 模式：设置 `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` 或 `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`，然后在 Control UI 设置中粘贴匹配的 secret。 + - Tailscale Serve 模式：确认已启用 `gateway.auth.allowTailscale`，并且你打开的是 Serve URL，而不是绕过 Tailscale 身份标头的原始 loopback / tailnet URL。 + - trusted-proxy 模式：确认你是通过已配置的非 loopback 身份感知代理访问的，而不是通过同主机 loopback 代理或原始 Gateway 网关 URL。 + - 如果一次重试后仍然不匹配，请轮换 / 重新批准已配对的设备令牌： - `openclaw devices list` - `openclaw devices rotate --device --role operator` - - 如果该 rotate 调用显示被拒绝，请检查两点： - - 已配对设备会话只能轮换其**自己的**设备，除非它同时拥有 `operator.admin` + - 如果该 rotate 调用提示被拒绝，请检查两点： + - 配对设备会话只能轮换**它们自己的**设备，除非它们同时具有 `operator.admin` - 显式 `--scope` 值不能超出调用方当前的 operator scopes - - 如果仍然卡住？运行 `openclaw status --all` 并按照 [故障排除](/zh-CN/gateway/troubleshooting) 进行检查。认证详情请参见 [Dashboard](/web/dashboard)。 + - 如果仍卡住？运行 `openclaw status --all`，并参考 [故障排除](/zh-CN/gateway/troubleshooting)。认证细节请参阅 [Dashboard](/web/dashboard)。 - - `tailnet` 绑定会从你的网络接口中选择一个 Tailscale IP（100.64.0.0/10）。如果该机器没有加入 Tailscale（或接口已断开），那就没有可绑定的地址。 + + `tailnet` 绑定会从你的网络接口中选择一个 Tailscale IP（100.64.0.0/10）。如果机器没有接入 Tailscale（或接口已断开），就没有可绑定的地址。 修复方式： - - 在该主机上启动 Tailscale（使其获得一个 100.x 地址），或 + - 在该主机上启动 Tailscale（让它获得一个 100.x 地址），或者 - 切换到 `gateway.bind: "loopback"` / `"lan"`。 - 注意：`tailnet` 是显式选择。`auto` 更偏向 loopback；如果你想要仅 tailnet 绑定，请使用 `gateway.bind: "tailnet"`。 + 说明：`tailnet` 是显式模式。`auto` 会优先使用 loopback；如果你想只绑定 tailnet，请使用 `gateway.bind: "tailnet"`。 - - 通常不需要——一个 Gateway 网关就可以运行多个消息渠道和智能体。只有在你需要冗余（例如救援机器人）或强隔离时，才使用多个 Gateway 网关。 + + 通常不需要——一个 Gateway 网关 就可以运行多个消息渠道和智能体。只有在你需要冗余（例如应急机器人）或硬隔离时，才使用多个 Gateway 网关。 可以，但你必须隔离以下内容： @@ -2839,38 +2842,38 @@ x-i18n: 快速设置（推荐）： - 每个实例使用 `openclaw --profile ...`（会自动创建 `~/.openclaw-`）。 - - 在每个 profile 配置中设置唯一的 `gateway.port`（或手动运行时传入 `--port`）。 - - 安装按 profile 分离的服务：`openclaw --profile gateway install`。 + - 在每个 profile 配置中设置唯一的 `gateway.port`（或在手动运行时传入 `--port`）。 + - 安装每个 profile 对应的服务：`openclaw --profile gateway install`。 - Profiles 还会为服务名添加后缀（`ai.openclaw.`；遗留形式为 `com.openclaw.*`、`openclaw-gateway-.service`、`OpenClaw Gateway ()`）。 + Profiles 还会为服务名添加后缀（`ai.openclaw.`；旧版为 `com.openclaw.*`、`openclaw-gateway-.service`、`OpenClaw Gateway ()`）。 完整指南：[多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。 - Gateway 网关是一个**WebSocket 服务器**，它期望收到的第一条消息 - 是一个 `connect` frame。如果收到其他内容，它就会以 - **code 1008**（策略违规）关闭连接。 + Gateway 网关 是一个**WebSocket 服务器**，并且它期望收到的第一条消息 + 是一个 `connect` 帧。如果收到其他内容，它就会关闭连接， + 并返回 **code 1008**（策略违规）。 常见原因： - 你在浏览器中打开了 **HTTP** URL（`http://...`），而不是使用 WS 客户端。 - - 你使用了错误的端口或路径。 - - 某个代理或隧道剥离了认证头，或发送了非 Gateway 网关请求。 + - 你用了错误的端口或路径。 + - 某个代理或隧道剥离了认证标头，或发送了非 Gateway 网关 请求。 快速修复： - 1. 使用 WS URL：`ws://:18789`（若为 HTTPS，则使用 `wss://...`）。 + 1. 使用 WS URL：`ws://:18789`（如果是 HTTPS，则使用 `wss://...`）。 2. 不要在普通浏览器标签页中打开 WS 端口。 - 3. 如果启用了认证，请在 `connect` frame 中包含 token/password。 + 3. 如果启用了认证，请在 `connect` 帧中包含令牌 / 密码。 - 如果你使用的是 CLI 或 TUI，URL 应如下所示： + 如果你使用的是 CLI 或 TUI，URL 应该类似这样： ``` openclaw tui --url ws://:18789 --token ``` - 协议详情：[Gateway protocol](/zh-CN/gateway/protocol)。 + 协议细节：[Gateway protocol](/zh-CN/gateway/protocol)。 @@ -2887,38 +2890,38 @@ x-i18n: 你可以通过 `logging.file` 设置一个稳定路径。文件日志级别由 `logging.level` 控制。控制台详细程度由 `--verbose` 和 `logging.consoleLevel` 控制。 - 最快的日志跟踪方式： + 最快查看日志尾部的方式： ```bash openclaw logs --follow ``` - 服务/supervisor 日志（当 Gateway 网关通过 launchd/systemd 运行时）： + 服务 / supervisor 日志（当 Gateway 网关 通过 launchd/systemd 运行时）： - macOS：`$OPENCLAW_STATE_DIR/logs/gateway.log` 和 `gateway.err.log`（默认：`~/.openclaw/logs/...`；profiles 使用 `~/.openclaw-/logs/...`） - Linux：`journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager` - Windows：`schtasks /Query /TN "OpenClaw Gateway ()" /V /FO LIST` - 更多信息请参见 [故障排除](/zh-CN/gateway/troubleshooting)。 + 更多内容请参阅 [故障排除](/zh-CN/gateway/troubleshooting)。 - - 使用 Gateway 网关辅助命令： + + 使用 Gateway 网关 辅助命令： ```bash openclaw gateway status openclaw gateway restart ``` - 如果你是手动运行 Gateway 网关，`openclaw gateway --force` 可以重新夺回端口。参见 [Gateway 网关](/zh-CN/gateway)。 + 如果你是手动运行 Gateway 网关，`openclaw gateway --force` 可以回收端口。请参阅 [Gateway 网关](/zh-CN/gateway)。 - Windows 上有**两种安装模式**： + Windows 有**两种安装模式**： - **1) WSL2（推荐）：** Gateway 网关运行在 Linux 内部。 + **1）WSL2（推荐）：**Gateway 网关 运行在 Linux 内部。 打开 PowerShell，进入 WSL，然后重启： @@ -2928,13 +2931,13 @@ x-i18n: openclaw gateway restart ``` - 如果你从未安装过服务，就以前台方式启动它： + 如果你从未安装服务，就在前台启动它： ```bash openclaw gateway run ``` - **2) 原生 Windows（不推荐）：** Gateway 网关直接运行在 Windows 中。 + **2）原生 Windows（不推荐）：**Gateway 网关 直接运行在 Windows 中。 打开 PowerShell 并运行： @@ -2949,12 +2952,12 @@ x-i18n: openclaw gateway run ``` - 文档：[Windows（WSL2）](/zh-CN/platforms/windows)、[Gateway 网关服务运行手册](/zh-CN/gateway)。 + 文档：[Windows（WSL2）](/zh-CN/platforms/windows)、[Gateway 网关 服务运行手册](/zh-CN/gateway)。 - - 先做一轮快速健康检查： + + 先进行一轮快速健康检查： ```bash openclaw status @@ -2965,26 +2968,26 @@ x-i18n: 常见原因： - - 模型认证没有加载到**Gateway 网关主机**上（检查 `models status`）。 - - 渠道配对/allowlist 阻止了回复（检查渠道配置 + 日志）。 - - WebChat/Dashboard 在未使用正确 token 的情况下被打开。 + - 模型认证未在**Gateway 网关 主机**上加载（检查 `models status`）。 + - 渠道配对 / 允许列表阻止了回复（检查渠道配置 + 日志）。 + - WebChat / Dashboard 已打开，但使用的令牌不正确。 - 如果你是远程部署，请确认隧道/Tailscale 连接已建立，并且 - Gateway 网关 WebSocket 可达。 + 如果你处于远程模式，请确认隧道 / Tailscale 连接正常，并且 + Gateway WebSocket 可达。 文档：[Channels](/zh-CN/channels)、[故障排除](/zh-CN/gateway/troubleshooting)、[Remote access](/zh-CN/gateway/remote)。 - 这通常意味着 UI 丢失了 WebSocket 连接。请检查： + 这通常表示 UI 丢失了 WebSocket 连接。请检查： - 1. Gateway 网关是否在运行？`openclaw gateway status` - 2. Gateway 网关是否健康？`openclaw status` - 3. UI 是否使用了正确 token？`openclaw dashboard` - 4. 如果是远程，隧道/Tailscale 链路是否正常？ + 1. Gateway 网关 是否正在运行？`openclaw gateway status` + 2. Gateway 网关 是否健康？`openclaw status` + 3. UI 是否使用了正确的令牌？`openclaw dashboard` + 4. 如果是远程环境，隧道 / Tailscale 链路是否正常？ - 然后跟踪日志： + 然后查看日志尾部： ```bash openclaw logs --follow @@ -2994,7 +2997,7 @@ x-i18n: - + 先查看日志和渠道状态： ```bash @@ -3002,19 +3005,19 @@ x-i18n: openclaw channels logs --channel telegram ``` - 然后按错误类型处理： + 然后根据错误进行匹配： - - `BOT_COMMANDS_TOO_MUCH`：Telegram 菜单条目过多。OpenClaw 已经会裁剪到 Telegram 限制并用更少命令重试，但某些菜单项仍需要被删除。请减少插件/skill/自定义命令，或在你不需要菜单时禁用 `channels.telegram.commands.native`。 - - `TypeError: fetch failed`、`Network request for 'setMyCommands' failed!` 或类似网络错误：如果你在 VPS 上或位于代理之后，请确认允许对 `api.telegram.org` 发起出站 HTTPS，并且 DNS 正常工作。 + - `BOT_COMMANDS_TOO_MUCH`：Telegram 菜单条目过多。OpenClaw 已经会裁剪到 Telegram 限制并用更少的命令重试，但某些菜单条目仍然需要去掉。请减少插件 / skill / 自定义命令，或在不需要菜单时禁用 `channels.telegram.commands.native`。 + - `TypeError: fetch failed`、`Network request for 'setMyCommands' failed!` 或类似网络错误：如果你在 VPS 上或位于代理之后，请确认允许出站 HTTPS，并且 `api.telegram.org` 的 DNS 正常。 - 如果 Gateway 网关是远程的，请确保你查看的是 Gateway 网关主机上的日志。 + 如果 Gateway 网关 是远程的，请确认你查看的是 Gateway 网关 主机上的日志。 文档：[Telegram](/zh-CN/channels/telegram)、[渠道故障排除](/zh-CN/channels/troubleshooting)。 - - 先确认 Gateway 网关可达，并且智能体能够运行： + + 先确认 Gateway 网关 可达，并且智能体能够运行： ```bash openclaw status @@ -3022,14 +3025,14 @@ x-i18n: openclaw logs --follow ``` - 在 TUI 中，使用 `/status` 查看当前状态。如果你希望在某个聊天 - 渠道中看到回复，请确保已启用投递（`/deliver on`）。 + 在 TUI 中，使用 `/status` 查看当前状态。如果你希望回复出现在某个聊天 + 渠道中，请确认已启用投递（`/deliver on`）。 文档：[TUI](/web/tui)、[Slash commands](/zh-CN/tools/slash-commands)。 - + 如果你安装了服务： ```bash @@ -3037,38 +3040,38 @@ x-i18n: openclaw gateway start ``` - 这会停止/启动**受监督的服务**（macOS 上是 launchd，Linux 上是 systemd）。 - 当 Gateway 网关作为后台守护进程运行时，请使用这种方式。 + 这会停止 / 启动**受监管的服务**（macOS 上是 launchd，Linux 上是 systemd）。 + 当 Gateway 网关 作为后台守护进程运行时，请使用这种方式。 - 如果你是在前台运行，请用 Ctrl-C 停止，然后： + 如果你是在前台运行，请按 Ctrl-C 停止，然后： ```bash openclaw gateway run ``` - 文档：[Gateway 网关服务运行手册](/zh-CN/gateway)。 + 文档：[Gateway 网关 服务运行手册](/zh-CN/gateway)。 - + - `openclaw gateway restart`：重启**后台服务**（launchd/systemd）。 - - `openclaw gateway`：在当前终端会话中**以前台方式**运行 Gateway 网关。 + - `openclaw gateway`：在当前终端会话中**前台运行** Gateway 网关。 - 如果你已经安装了服务，请使用这些 Gateway 网关命令。只有在 + 如果你已经安装了服务，请使用 Gateway 网关 命令。只有在 你想进行一次性的前台运行时，才使用 `openclaw gateway`。 - - 使用 `--verbose` 启动 Gateway 网关，以获得更详细的控制台输出。然后检查日志文件中的渠道认证、模型路由和 RPC 错误。 + + 使用 `--verbose` 启动 Gateway 网关，以获得更详细的控制台输出。然后检查日志文件，查看渠道认证、模型路由和 RPC 错误。 ## 媒体和附件 - - 来自智能体的出站附件必须包含一行 `MEDIA:`（单独占一行）。参见 [OpenClaw assistant setup](/zh-CN/start/openclaw) 和 [Agent send](/zh-CN/tools/agent-send)。 + + 智能体发出的附件必须包含一行 `MEDIA:`（单独占一行）。请参阅 [OpenClaw assistant setup](/zh-CN/start/openclaw) 和 [Agent send](/zh-CN/tools/agent-send)。 CLI 发送方式： @@ -3076,14 +3079,14 @@ x-i18n: openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png ``` - 还要检查： + 还请检查： - - 目标渠道支持出站媒体，并且没有被 allowlist 阻止。 - - 文件大小在提供商限制之内（图片会被缩放到最大 2048px）。 - - `tools.fs.workspaceOnly=true` 会将本地路径发送限制在工作区、temp/media-store 和通过沙箱校验的文件范围内。 - - `tools.fs.workspaceOnly=false` 允许 `MEDIA:` 发送智能体本来就能读取的主机本地文件，但仅限媒体和安全文档类型（图片、音频、视频、PDF 和 Office 文档）。纯文本和类似 secret 的文件仍会被阻止。 + - 目标渠道支持出站媒体，并且没有被允许列表阻止。 + - 文件未超过提供商的大小限制（图片会被缩放到最大 2048px）。 + - `tools.fs.workspaceOnly=true` 会将本地路径发送限制在工作区、temp/media-store 和通过沙箱校验的文件内。 + - `tools.fs.workspaceOnly=false` 允许 `MEDIA:` 发送智能体已可读取的主机本地文件，但仅限媒体和安全文档类型（图片、音频、视频、PDF 和 Office 文档）。纯文本和类似 secret 的文件仍然会被阻止。 - 参见 [Images](/zh-CN/nodes/images)。 + 请参阅 [Images](/zh-CN/nodes/images)。 @@ -3091,73 +3094,73 @@ x-i18n: ## 安全和访问控制 - - 请将入站私信视为不可信输入。默认设置旨在降低风险： + + 请将入站私信视为不可信输入。默认设置的设计目标是降低风险： - - 支持私信的渠道在默认情况下采用**配对**行为： - - 未知发送者会收到配对码；机器人不会处理他们的消息。 + - 在支持私信的渠道上，默认行为是**配对**： + - 未知发送者会收到一个配对码；机器人不会处理他们的消息。 - 使用以下命令批准：`openclaw pairing approve --channel [--account ] ` - - 待处理请求上限为**每个渠道 3 个**；如果代码没有送达，请检查 `openclaw pairing list --channel [--account ]`。 - - 若要公开开放私信，必须显式选择启用（`dmPolicy: "open"` 且 allowlist 为 `"*"`）。 + - 待处理请求每个渠道最多 **3 个**；如果配对码没有送达，请检查 `openclaw pairing list --channel [--account ]` + - 公开开放私信需要显式选择加入（`dmPolicy: "open"` 且 allowlist 为 `"*"`）。 - 运行 `openclaw doctor` 可以发现有风险的私信策略。 + 运行 `openclaw doctor` 可以发现风险较高的私信策略。 - - 不是。prompt injection 关乎的是**不可信内容**，而不只是“谁能给机器人发私信”。 - 如果你的助手会读取外部内容（Web 搜索/抓取、浏览器页面、邮件、 - 文档、附件、粘贴的日志），这些内容就可能包含试图 - 劫持模型的指令。即使**你是唯一的发送者**，这种情况也可能发生。 + + 不是。提示注入针对的是**不可信内容**，而不只是“谁可以给机器人发私信”。 + 如果你的助手会读取外部内容（Web 搜索 / 获取、浏览器页面、邮件、 + 文档、附件、粘贴的日志），这些内容都可能包含试图 + 劫持模型的指令。即使**只有你自己是发送者**，也可能发生这种情况。 - 最大的风险在于启用了工具时：模型可能被诱导 - 代你泄露上下文或调用工具。可通过以下方式缩小影响范围： + 最大的风险出现在启用了工具时：模型可能被诱导去 + 窃取上下文，或代表你调用工具。可通过以下方式降低影响范围： - 使用只读或禁用工具的“阅读器”智能体来总结不可信内容 - - 对启用工具的智能体关闭 `web_search` / `web_fetch` / `browser` - - 也将解码后的文件/文本文档视为不可信：OpenResponses - `input_file` 和媒体附件提取都会将提取出的文本包装在 - 显式的外部内容边界标记中，而不是直接传递原始文件文本 - - 启用沙箱隔离并使用严格的工具 allowlist + - 对启用了工具的智能体关闭 `web_search` / `web_fetch` / `browser` + - 同样将解码后的文件 / 文档文本视为不可信：OpenResponses + `input_file` 和媒体附件提取都会将提取出的文本包裹在 + 明确的外部内容边界标记中，而不是直接传递原始文件文本 + - 使用沙箱隔离和严格的工具允许列表 - 详情参见：[Security](/zh-CN/gateway/security)。 + 详情请参阅 [Security](/zh-CN/gateway/security)。 - - 对大多数部署而言，应该有。使用单独的账号和电话号码来隔离机器人， - 可以在出问题时缩小影响范围。这也让轮换 - 凭证或撤销访问变得更容易，而不会影响你的个人账号。 + + 对大多数设置来说，是的。使用单独的账户和手机号来隔离机器人， + 可以在出问题时降低影响范围。这也使得轮换 + 凭证或撤销访问更容易，而不会影响你的个人账户。 - 从小范围开始。只授予它你实际需要的工具和账号访问权限，之后 - 再按需扩展。 + 从小规模开始。只授予它你实际需要的工具和账户访问权限，然后在确有需要时 + 再逐步扩展。 文档：[Security](/zh-CN/gateway/security)、[Pairing](/zh-CN/channels/pairing)。 - - 我们**不**建议让它完全自主处理你的个人消息。最安全的模式是： + + 我们**不建议**让它完全自主处理你的个人消息。最安全的模式是： - - 保持私信处于**配对模式**或严格的 allowlist 模式。 - - 如果你希望它代你发消息，请使用**单独的号码或账号**。 - - 让它先起草，然后在发送前**进行审批**。 + - 将私信保持在**配对模式**或严格的允许列表中。 + - 如果你想让它代表你发送消息，请使用**单独的号码或账户**。 + - 让它起草，然后在发送前**由你批准**。 - 如果你想尝试，请在专用账号上进行，并保持隔离。参见 + 如果你确实想尝试，请在专用账户上进行，并保持隔离。请参阅 [Security](/zh-CN/gateway/security)。 - - 可以，**前提是**该智能体仅用于聊天，且输入是可信的。较小档位 - 更容易受到指令劫持，因此不要将它们用于启用工具的智能体， + + 可以，**前提是**该智能体仅用于聊天，并且输入是可信的。较小档位 + 更容易受到指令劫持，因此不要将它们用于启用了工具的智能体， 或用于读取不可信内容的场景。如果你必须使用较小模型，请锁紧 - 工具，并在沙箱中运行。参见 [Security](/zh-CN/gateway/security)。 + 工具，并在沙箱中运行。请参阅 [Security](/zh-CN/gateway/security)。 - + 只有在未知发送者给机器人发消息且 - `dmPolicy: "pairing"` 已启用时，才会发送配对码。单独发送 `/start` 不会生成代码。 + `dmPolicy: "pairing"` 已启用时，才会发送配对码。单独发送 `/start` 不会生成配对码。 检查待处理请求： @@ -3165,12 +3168,12 @@ x-i18n: openclaw pairing list telegram ``` - 如果你想立即获得访问权限，请将你的发送者 id 加入 allowlist，或为该账户设置 `dmPolicy: "open"`。 + 如果你想立即获得访问权限，请将你的 sender id 加入允许列表，或为该账户设置 `dmPolicy: "open"`。 - 不会。WhatsApp 私信默认策略是**配对**。未知发送者只会收到一个配对码，他们的消息**不会被处理**。OpenClaw 只会回复它收到的聊天，或你显式触发的发送。 + 不会。WhatsApp 私信的默认策略是**配对**。未知发送者只会收到一个配对码，而且他们的消息**不会被处理**。OpenClaw 只会回复它收到的聊天，或你显式触发的发送操作。 使用以下命令批准配对： @@ -3184,18 +3187,18 @@ x-i18n: openclaw pairing list whatsapp ``` - 向导中的电话号码提示：它用于设置你的**allowlist/owner**，这样你自己的私信才会被允许。这不会用于自动发送。如果你是在自己的个人 WhatsApp 号码上运行，请使用该号码，并启用 `channels.whatsapp.selfChatMode`。 + 向导中的手机号提示用于设置你的**允许列表 / 所有者**，以便允许你自己的私信。它不会用于自动发送。如果你是在个人 WhatsApp 号码上运行，请使用该号码，并启用 `channels.whatsapp.selfChatMode`。 -## 聊天命令、中止任务，以及“它停不下来” +## 聊天命令、终止任务，以及“它就是不停” - 大多数内部消息或工具消息只会在该会话启用了 **verbose**、**trace** 或 **reasoning** 时出现。 + 大多数内部或工具消息只会在该会话启用了 **verbose**、**trace** 或 **reasoning** 时出现。 - 在你看到这些内容的聊天中修复： + 在你看到这些消息的聊天中这样修复： ``` /verbose off @@ -3204,15 +3207,15 @@ x-i18n: ``` 如果仍然很吵，请检查 Control UI 中的会话设置，并将 verbose - 设为 **inherit**。同时确认你没有使用某个在配置中将 `verboseDefault` 设为 + 设为 **inherit**。同时确认你没有使用在配置中将 `verboseDefault` 设为 `on` 的机器人配置文件。 文档：[Thinking and verbose](/zh-CN/tools/thinking)、[Security](/zh-CN/gateway/security#reasoning-verbose-output-in-groups)。 - - 将以下任意内容**作为独立消息发送**（不要加斜杠）： + + 发送以下任意内容，**作为单独的一条消息发送**（不要加斜杠）： ``` stop @@ -3236,7 +3239,7 @@ x-i18n: interrupt ``` - 这些都是中止触发词（不是 slash 命令）。 + 这些是中止触发词（不是斜杠命令）。 对于后台进程（来自 exec 工具），你可以让智能体运行： @@ -3244,17 +3247,17 @@ x-i18n: process action:kill sessionId:XXX ``` - Slash 命令概览：参见 [Slash commands](/zh-CN/tools/slash-commands)。 + 斜杠命令概览：请参阅 [Slash commands](/zh-CN/tools/slash-commands)。 - 大多数命令都必须作为**独立**消息发送，并且以 `/` 开头，但也有少数快捷方式（如 `/status`）对 allowlist 中的发送者也支持内联使用。 + 大多数命令都必须作为**单独的一条**、以 `/` 开头的消息发送，但少数快捷方式（例如 `/status`）也可以对允许列表中的发送者以内联方式生效。 - 默认情况下，OpenClaw 会阻止**跨提供商**消息发送。如果某个工具调用绑定到了 - Telegram，那么除非你显式允许，否则它不会发送到 Discord。 + OpenClaw 默认会阻止**跨提供商**消息传递。如果某次工具调用绑定到了 + Telegram，它就不会发送到 Discord，除非你显式允许。 - 为该智能体启用跨提供商消息发送： + 为该智能体启用跨提供商消息传递： ```json5 { @@ -3269,32 +3272,32 @@ x-i18n: } ``` - 编辑配置后，重启 Gateway 网关。 + 编辑配置后重启 Gateway 网关。 - - 队列模式控制新消息如何与正在进行中的运行交互。使用 `/queue` 更改模式： + + 队列模式决定了新消息如何与正在进行中的运行交互。使用 `/queue` 修改模式： - `steer` - 新消息会重定向当前任务 - - `followup` - 消息按顺序逐条运行 - - `collect` - 批量收集消息并统一回复一次（默认） - - `steer-backlog` - 先重定向当前任务，再处理积压队列 + - `followup` - 逐条处理消息 + - `collect` - 批量收集消息并回复一次（默认） + - `steer-backlog` - 先转向当前任务，然后处理积压 - `interrupt` - 中止当前运行并重新开始 - 你还可以为 followup 模式添加诸如 `debounce:2s cap:25 drop:summarize` 这样的选项。 + 你还可以为 followup 模式添加选项，例如 `debounce:2s cap:25 drop:summarize`。 -## 杂项 +## 其他 - - 在 OpenClaw 中，凭证和模型选择是分开的。设置 `ANTHROPIC_API_KEY`（或在认证配置文件中存储 Anthropic API 密钥）会启用认证，但实际默认模型取决于你在 `agents.defaults.model.primary` 中配置的内容（例如 `anthropic/claude-sonnet-4-6` 或 `anthropic/claude-opus-4-6`）。如果你看到 `No credentials found for profile "anthropic:default"`，则表示 Gateway 网关无法在当前运行智能体所对应的 `auth-profiles.json` 中找到 Anthropic 凭证。 + + 在 OpenClaw 中，凭证和模型选择是分开的。设置 `ANTHROPIC_API_KEY`（或在 auth profiles 中存储 Anthropic API key）会启用认证，但实际默认模型仍然取决于你在 `agents.defaults.model.primary` 中的配置（例如 `anthropic/claude-sonnet-4-6` 或 `anthropic/claude-opus-4-6`）。如果你看到 `No credentials found for profile "anthropic:default"`，说明 Gateway 网关 无法在当前运行智能体的预期 `auth-profiles.json` 中找到 Anthropic 凭证。 --- -还是卡住了？请到 [Discord](https://discord.com/invite/clawd) 提问，或发起一个 [GitHub discussion](https://github.com/openclaw/openclaw/discussions)。 +如果你还是卡住了，请到 [Discord](https://discord.com/invite/clawd) 提问，或创建一个 [GitHub discussion](https://github.com/openclaw/openclaw/discussions)。 diff --git a/docs/zh-CN/help/troubleshooting.md b/docs/zh-CN/help/troubleshooting.md index 91b65839a..1cea1baf1 100644 --- a/docs/zh-CN/help/troubleshooting.md +++ b/docs/zh-CN/help/troubleshooting.md @@ -2,24 +2,24 @@ read_when: - OpenClaw 无法正常工作，而你需要最快速的修复路径 - 在深入查看详细操作手册之前，你想先走一遍分诊流程 -summary: OpenClaw 的按症状分类故障排除中心 -title: 常规故障排除 +summary: OpenClaw 的按症状优先故障排除中心 +title: 常见故障排除 x-i18n: - generated_at: "2026-04-10T20:41:21Z" + generated_at: "2026-04-20T06:31:02Z" model: gpt-5.4 provider: openai - source_hash: 16b38920dbfdc8d4a79bbb5d6fab2c67c9f218a97c36bb4695310d7db9c4614a + source_hash: cc5d8c9f804084985c672c5a003ce866e8142ab99fe81abb7a0d38e22aea4b88 source_path: help/troubleshooting.md workflow: 15 --- # 故障排除 -如果你只有 2 分钟，就把这个页面当作分诊入口。 +如果你只有 2 分钟，把这个页面当作分诊入口。 ## 最初的六十秒 -按顺序运行这一组完全相同的命令： +按顺序运行下面这组精确的排查步骤： ```bash openclaw status @@ -31,15 +31,15 @@ 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 status --all` → 完整报告存在，并且可以分享。 +- `openclaw gateway probe` → 可以访问预期的 Gateway 网关目标（`Reachable: yes`）。`Capability: ...` 会告诉你探测能够证明的认证级别，而 `Read probe: limited - missing scope: operator.read` 表示诊断能力降级，不是连接失败。 +- `openclaw gateway status` → 显示 `Runtime: running`、`Connectivity probe: ok`，以及合理的 `Capability: ...` 行。如果你还需要验证读权限范围的 RPC 证明，请使用 `--require-rpc`。 - `openclaw doctor` → 没有阻塞性的配置或服务错误。 -- `openclaw channels status --probe` → 如果 Gateway 网关可访问，会返回每个账户的实时传输状态，以及诸如 `works` 或 `audit ok` 之类的探测 / 审计结果；如果 Gateway 网关不可访问，该命令会回退为仅基于配置的摘要。 -- `openclaw logs --follow` → 活动持续稳定，没有重复出现的致命错误。 +- `openclaw channels status --probe` → 当 Gateway 网关可达时，会返回每个账户的实时传输状态，以及诸如 `works` 或 `audit ok` 这样的探测/审计结果；如果 Gateway 网关不可达，该命令会回退为仅配置摘要。 +- `openclaw logs --follow` → 活动持续稳定，没有反复出现的致命错误。 ## Anthropic 长上下文 429 @@ -47,27 +47,29 @@ openclaw logs --follow `HTTP 429: rate_limit_error: Extra usage is required for long context requests`， 请前往 [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/zh-CN/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context)。 -## 本地兼容 OpenAI 的后端可直接工作，但在 OpenClaw 中失败 +## 本地 OpenAI 兼容后端直接可用，但在 OpenClaw 中失败 -如果你的本地或自托管 `/v1` 后端可以响应简短的直接 -`/v1/chat/completions` 探测，但在 `openclaw infer model run` 或正常的智能体回合中失败： +如果你的本地或自托管 `/v1` 后端可以响应小型直接 +`/v1/chat/completions` 探测，但在 `openclaw infer model run` 或正常 +智能体 回合中失败： -1. 如果错误提到 `messages[].content` 期望为字符串，请设置 +1. 如果错误提到 `messages[].content` 需要字符串，设置 `models.providers..models[].compat.requiresStringContent: true`。 -2. 如果该后端仍然只在 OpenClaw 智能体回合中失败，请设置 - `models.providers..models[].compat.supportsTools: false`，然后重试。 -3. 如果很小的直接调用仍然可用，但更大的 OpenClaw 提示词会导致后端崩溃，请将剩余问题视为上游模型 / 服务器限制，并继续查看详细操作手册： +2. 如果该后端仍然只在 OpenClaw 智能体 回合中失败，设置 + `models.providers..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 +## 插件安装失败，提示缺少 openclaw extensions -如果安装失败并显示 `package.json missing openclaw.extensions`，说明该插件包仍在使用 OpenClaw 已不再接受的旧结构。 +如果安装失败并显示 `package.json missing openclaw.extensions`，说明该插件包 +使用了 OpenClaw 已不再接受的旧结构。 -在插件包中修复： +在插件包中这样修复： 1. 在 `package.json` 中添加 `openclaw.extensions`。 2. 将入口指向已构建的运行时文件（通常是 `./dist/index.js`）。 -3. 重新发布插件，然后再次运行 `openclaw plugins install `。 +3. 重新发布该插件，然后再次运行 `openclaw plugins install `。 示例： @@ -87,22 +89,22 @@ openclaw logs --follow ```mermaid flowchart TD - A[OpenClaw 无法正常工作] --> B{首先是哪里出问题} + A[OpenClaw 无法正常工作] --> B{最先出问题的是什么} B --> C[没有回复] B --> D[仪表板或 Control UI 无法连接] B --> E[Gateway 网关无法启动或服务未运行] - B --> F[渠道已连接，但消息不流动] - B --> G[Cron 或心跳未触发或未送达] - B --> H[节点已配对，但 camera canvas screen exec 工具失败] + B --> F[渠道已连接但消息不流转] + B --> G[Cron 或心跳没有触发或没有送达] + B --> H[节点已配对，但 camera canvas screen exec 失败] B --> I[浏览器工具失败] - C --> C1[/“没有回复”部分/] - D --> D1[/“Control UI”部分/] - E --> E1[/“Gateway 网关”部分/] - F --> F1[/“渠道流转”部分/] - G --> G1[/“自动化”部分/] - H --> H1[/“节点工具”部分/] - I --> I1[/“浏览器”部分/] + C --> C1[/无回复部分/] + D --> D1[/Control UI 部分/] + E --> E1[/Gateway 网关部分/] + F --> F1[/渠道流转部分/] + G --> G1[/自动化部分/] + H --> H1[/节点工具部分/] + I --> I1[/浏览器部分/] ``` @@ -118,14 +120,15 @@ flowchart TD 正常输出应类似于： - `Runtime: running` - - `RPC probe: ok` + - `Connectivity probe: ok` + - `Capability: read-only`、`write-capable` 或 `admin-capable` - 你的渠道显示传输已连接，并且在支持的情况下，`channels status --probe` 中会显示 `works` 或 `audit ok` - - 发送方显示为已获准（或者私信策略为开放 / 允许列表） + - 发送方显示已获批准（或 私信 策略为开放/允许列表） 常见日志特征： - `drop guild message (mention required` → Discord 中的提及门控阻止了该消息。 - - `pairing request` → 发送方尚未获准，正在等待私信配对批准。 + - `pairing request` → 发送方未获批准，正在等待 私信 配对批准。 - 渠道日志中的 `blocked` / `allowlist` → 发送方、房间或群组被过滤。 详细页面： @@ -147,20 +150,21 @@ flowchart TD 正常输出应类似于： - - 在 `openclaw gateway status` 中显示 `Dashboard: http://...` - - `RPC probe: ok` + - `openclaw gateway status` 中显示 `Dashboard: http://...` + - `Connectivity probe: ok` + - `Capability: read-only`、`write-capable` 或 `admin-capable` - 日志中没有认证循环 常见日志特征： - - `device identity required` → HTTP / 非安全上下文无法完成设备认证。 - - `origin not allowed` → 浏览器 `Origin` 不在 Control UI 的 Gateway 网关目标允许范围内。 - - 带有重试提示的 `AUTH_TOKEN_MISMATCH`（`canRetryWithDeviceToken=true`）→ 可能会自动执行一次受信任的设备令牌重试。 + - `device identity required` → HTTP/非安全上下文无法完成设备认证。 + - `origin not allowed` → 浏览器 `Origin` 不被该 Control UI Gateway 网关目标允许。 + - 带有重试提示（`canRetryWithDeviceToken=true`）的 `AUTH_TOKEN_MISMATCH` → 可能会自动进行一次可信设备令牌重试。 - 该缓存令牌重试会复用与已配对设备令牌一起存储的缓存作用域集合。显式 `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 网关不可达。 + - 在异步 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 网关不可达。 详细页面： @@ -183,12 +187,13 @@ flowchart TD - `Service: ... (loaded)` - `Runtime: running` - - `RPC probe: ok` + - `Connectivity probe: ok` + - `Capability: read-only`、`write-capable` 或 `admin-capable` 常见日志特征： - `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → Gateway 网关模式为 remote，或者配置文件缺少本地模式标记，需要修复。 - - `refusing to bind gateway ... without auth` → 在没有有效 Gateway 网关认证路径的情况下绑定到非 loopback 地址（令牌 / 密码，或按配置启用的受信任代理）。 + - `refusing to bind gateway ... without auth` → 在没有有效 Gateway 网关认证路径（令牌/密码，或已配置的 trusted-proxy）的情况下拒绝绑定非 loopback 地址。 - `another gateway instance is already listening` 或 `EADDRINUSE` → 端口已被占用。 详细页面： @@ -199,7 +204,7 @@ flowchart TD - + ```bash openclaw status openclaw gateway status @@ -211,14 +216,14 @@ flowchart TD 正常输出应类似于： - 渠道传输已连接。 - - 配对 / 允许列表检查通过。 - - 在要求提及的地方，提及已被识别。 + - 配对/允许列表检查已通过。 + - 在需要时，提及已被检测到。 常见日志特征： - - `mention required` → 群组中的提及门控阻止了处理。 - - `pairing` / `pending` → 私信发送方尚未获准。 - - `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → 渠道权限令牌问题。 + - `mention required` → 群组提及门控阻止了处理。 + - `pairing` / `pending` → 私信 发送方尚未获批准。 + - `not_in_channel`、`missing_scope`、`Forbidden`、`401/403` → 渠道权限令牌问题。 详细页面： @@ -227,7 +232,7 @@ flowchart TD - + ```bash openclaw status openclaw gateway status @@ -239,17 +244,17 @@ flowchart TD 正常输出应类似于： - - `cron.status` 显示为已启用，并有下一次唤醒时间。 + - `cron.status` 显示已启用，并带有下一次唤醒时间。 - `cron runs` 显示最近的 `ok` 条目。 - - 心跳已启用，并且不在活跃时间之外。 + - 心跳已启用，且不在活跃时段之外。 常见日志特征： - `cron: scheduler disabled; jobs will not run automatically` → cron 已禁用。 - - 带有 `reason=quiet-hours` 的 `heartbeat skipped` → 当前处于配置的活跃时间之外。 - - 带有 `reason=empty-heartbeat-file` 的 `heartbeat skipped` → `HEARTBEAT.md` 存在，但只包含空白 / 仅标题的脚手架内容。 - - 带有 `reason=no-tasks-due` 的 `heartbeat skipped` → `HEARTBEAT.md` 的任务模式已启用，但当前没有任何任务间隔到期。 - - 带有 `reason=alerts-disabled` 的 `heartbeat skipped` → 所有心跳可见性都已禁用（`showOk`、`showAlerts` 和 `useIndicator` 全部关闭）。 + - 带有 `reason=quiet-hours` 的 `heartbeat skipped` → 当前不在配置的活跃时段内。 + - 带有 `reason=empty-heartbeat-file` 的 `heartbeat skipped` → `HEARTBEAT.md` 存在，但只包含空白/仅标题的骨架内容。 + - 带有 `reason=no-tasks-due` 的 `heartbeat skipped` → `HEARTBEAT.md` 任务模式已启用，但尚无任务到达间隔时间。 + - 带有 `reason=alerts-disabled` 的 `heartbeat skipped` → 所有心跳可见性均被禁用（`showOk`、`showAlerts` 和 `useIndicator` 全部关闭）。 - `requests-in-flight` → 主通道繁忙；心跳唤醒被延后。 - `unknown accountId` → 心跳投递目标账户不存在。 @@ -261,7 +266,7 @@ flowchart TD - + ```bash openclaw status openclaw gateway status @@ -272,16 +277,16 @@ flowchart TD 正常输出应类似于： - - 节点列出为已连接，并已为 `node` 角色完成配对。 - - 你调用的命令所需能力存在。 + - 节点显示为已连接，并且已按 `node` 角色完成配对。 + - 你正在调用的命令具备相应能力。 - 该工具的权限状态已授予。 常见日志特征： - - `NODE_BACKGROUND_UNAVAILABLE` → 将节点应用切换到前台。 + - `NODE_BACKGROUND_UNAVAILABLE` → 将节点应用切到前台。 - `*_PERMISSION_REQUIRED` → 操作系统权限被拒绝或缺失。 - - `SYSTEM_RUN_DENIED: approval required` → exec 批准仍在等待中。 - - `SYSTEM_RUN_DENIED: allowlist miss` → 该命令不在 exec 允许列表中。 + - `SYSTEM_RUN_DENIED: approval required` → exec 审批仍在等待中。 + - `SYSTEM_RUN_DENIED: allowlist miss` → 命令不在 exec 允许列表中。 详细页面： @@ -291,7 +296,7 @@ flowchart TD - + ```bash openclaw config get tools.exec.host openclaw config get tools.exec.security @@ -301,14 +306,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 @@ -320,14 +325,14 @@ flowchart TD 更安全的替代方案： - 如果你只是想要稳定的主机路由，只设置 `tools.exec.host=gateway`。 - - 如果你想使用主机 exec，但仍希望在允许列表未命中时进行审核，请使用 `security=allowlist` 搭配 `ask=on-miss`。 + - 如果你想使用主机 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` → 隐式或显式选择了 sandbox，但沙箱模式未开启。 详细页面： @@ -348,20 +353,20 @@ flowchart TD 正常输出应类似于： - - 浏览器状态显示 `running: true`，并且已选定浏览器 / 配置文件。 - - `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 使用了错误或超出范围的端口。 + - `browser.cdpUrl has invalid port` → 配置的 CDP URL 端口无效或超出范围。 - `No Chrome tabs found for profile="user"` → Chrome MCP 附加配置文件没有打开的本地 Chrome 标签页。 - `Remote CDP for profile "" is not reachable` → 配置的远程 CDP 端点从当前主机无法访问。 - `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加配置文件没有可用的实时 CDP 目标。 - - attach-only 或远程 CDP 配置文件上的过期 viewport / 深色模式 / locale / offline 覆盖状态 → 运行 `openclaw browser stop --browser-profile ` 以关闭当前控制会话并释放仿真状态，而无需重启 Gateway 网关。 + - attach-only 或远程 CDP 配置文件上存在过期的视口 / 深色模式 / 区域设置 / 离线覆盖状态 → 运行 `openclaw browser stop --browser-profile `，关闭活动控制会话并释放模拟状态，而无需重启 Gateway 网关。 详细页面： @@ -377,7 +382,7 @@ flowchart TD ## 相关内容 - [常见问题](/zh-CN/help/faq) — 常见问题 -- [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting) — Gateway 网关特有的问题 -- [Doctor](/zh-CN/gateway/doctor) — 自动化健康检查与修复 +- [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting) — Gateway 网关专属问题 +- [Doctor](/zh-CN/gateway/doctor) — 自动健康检查与修复 - [渠道故障排除](/zh-CN/channels/troubleshooting) — 渠道连接问题 - [自动化故障排除](/zh-CN/automation/cron-jobs#troubleshooting) — cron 和心跳问题