diff --git a/docs/zh-CN/channels/telegram.md b/docs/zh-CN/channels/telegram.md index a0628b11e..838b7d575 100644 --- a/docs/zh-CN/channels/telegram.md +++ b/docs/zh-CN/channels/telegram.md @@ -1,40 +1,40 @@ --- read_when: - - 处理 Telegram 功能或 webhook 时 -summary: Telegram 机器人支持状态、能力和配置 + - 处理 Telegram 功能或 Webhook 时 +summary: Telegram 机器人支持状态、功能和配置 title: Telegram x-i18n: - generated_at: "2026-04-05T08:19:53Z" + generated_at: "2026-04-20T04:35:04Z" model: gpt-5.4 provider: openai - source_hash: 39fbf328375fbc5d08ec2e3eed58b19ee0afa102010ecbc02e074a310ced157e + source_hash: b9903fae98bca0c345aa86d5c29015539c375442524a34d26bd28181470b8477 source_path: channels/telegram.md workflow: 15 --- # Telegram（Bot API） -状态：基于 grammY 的机器人私信 + 群组支持已可用于生产环境。长轮询是默认模式；webhook 模式为可选。 +状态：基于 grammY，适用于机器人私信 + 群组，已达到生产可用。长轮询是默认模式；Webhook 模式为可选。 - + Telegram 的默认私信策略是配对。 - + 跨渠道诊断与修复操作手册。 - + 完整的渠道配置模式和示例。 -## 快速设置 +## 快速开始 - 打开 Telegram 并与 **@BotFather** 聊天（确认用户名严格为 `@BotFather`）。 + 打开 Telegram，并与 **@BotFather** 聊天（确认用户名严格为 `@BotFather`）。 - 运行 `/newbot`，按照提示操作并保存令牌。 + 运行 `/newbot`，按照提示操作，并保存令牌。 @@ -53,8 +53,8 @@ x-i18n: } ``` - 环境变量回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账户）。 - Telegram **不**使用 `openclaw channels login telegram`；请在配置/环境变量中设置令牌，然后启动 Gateway 网关。 + 环境变量回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账号）。 + Telegram **不**使用 `openclaw channels login telegram`；请在配置/环境变量中配置令牌，然后启动 Gateway 网关。 @@ -76,35 +76,35 @@ openclaw pairing approve telegram -令牌解析顺序会识别账户上下文。实际行为中，配置值优先于环境变量回退，而 `TELEGRAM_BOT_TOKEN` 仅适用于默认账户。 +令牌解析顺序是账号感知的。实际行为中，配置值优先于环境变量回退，而 `TELEGRAM_BOT_TOKEN` 仅适用于默认账号。 ## Telegram 侧设置 - Telegram 机器人默认启用 **隐私模式**，这会限制它们接收的群组消息。 + Telegram 机器人默认启用 **隐私模式**，这会限制它们能接收到的群组消息。 - 如果机器人必须看到所有群组消息，可以选择以下任一方式： + 如果机器人必须看到所有群组消息，可以采用以下任一方式： - 通过 `/setprivacy` 关闭隐私模式，或 - 将机器人设为群组管理员。 - 切换隐私模式后，请在每个群组中移除并重新添加机器人，以便 Telegram 应用更改。 + 切换隐私模式后，请在每个群组中移除并重新添加该机器人，以便 Telegram 应用此更改。 - 管理员状态在 Telegram 群组设置中控制。 + 管理员状态由 Telegram 群组设置控制。 - 机器人拥有管理员身份后会接收所有群组消息，这对始终在线的群组行为很有用。 + 管理员机器人会接收所有群组消息，这对始终在线的群组行为很有帮助。 - + - - `/setjoingroups`：允许/拒绝加入群组 - - `/setprivacy`：控制群组可见性行为 + - `/setjoingroups` 允许/禁止加入群组 + - `/setprivacy` 控制群组可见性行为 @@ -120,23 +120,23 @@ openclaw pairing approve telegram - `open`（要求 `allowFrom` 包含 `"*"`） - `disabled` - `channels.telegram.allowFrom` 接受数值型 Telegram 用户 ID。接受并规范化 `telegram:` / `tg:` 前缀。 - 当 `dmPolicy: "allowlist"` 且 `allowFrom` 为空时，会阻止所有私信，并被配置校验拒绝。 - 新手引导接受 `@username` 输入，并将其解析为数值 ID。 - 如果你升级后，配置中仍包含 `@username` 形式的 allowlist 条目，请运行 `openclaw doctor --fix` 进行解析（尽力而为；需要 Telegram 机器人令牌）。 - 如果你之前依赖配对存储的 allowlist 文件，在 allowlist 流程中（例如 `dmPolicy: "allowlist"` 还没有显式 ID 时），`openclaw doctor --fix` 可以将这些条目恢复到 `channels.telegram.allowFrom`。 + `channels.telegram.allowFrom` 接受 Telegram 数字用户 ID。支持并会规范化 `telegram:` / `tg:` 前缀。 + `dmPolicy: "allowlist"` 且 `allowFrom` 为空时会阻止所有私信，并且会被配置校验拒绝。 + 设置流程只要求输入数字用户 ID。 + 如果你已升级且配置中包含 `@username` 形式的 allowlist 条目，请运行 `openclaw doctor --fix` 进行解析（尽力而为；需要 Telegram 机器人令牌）。 + 如果你之前依赖配对存储的 allowlist 文件，`openclaw doctor --fix` 可以在 allowlist 流程中将其中的条目恢复到 `channels.telegram.allowFrom`（例如当 `dmPolicy: "allowlist"` 还没有显式 ID 时）。 - 对于单所有者机器人，建议使用 `dmPolicy: "allowlist"` 并显式配置数值型 `allowFrom` ID，这样访问策略会稳定保存在配置中（而不是依赖先前的配对批准）。 + 对于单一所有者的机器人，推荐使用 `dmPolicy: "allowlist"` 并显式设置数字 `allowFrom` ID，以便让访问策略稳定地保存在配置中（而不是依赖之前的配对批准）。 - 常见误解：私信配对批准并不意味着“此发送者在所有地方都已获授权”。 + 常见困惑：批准私信配对并不意味着“此发送者在所有地方都被授权”。 配对只授予私信访问权限。群组发送者授权仍然来自显式配置的 allowlist。 - 如果你想要“一次授权后，私信和群组命令都能工作”，请把你的数值型 Telegram 用户 ID 放入 `channels.telegram.allowFrom`。 + 如果你希望“我只授权一次，私信和群组命令都能工作”，请将你的 Telegram 数字用户 ID 放入 `channels.telegram.allowFrom`。 ### 查找你的 Telegram 用户 ID 更安全的方法（无需第三方机器人）： - 1. 向你的机器人发送私信。 + 1. 给你的机器人发送私信。 2. 运行 `openclaw logs --follow`。 3. 读取 `from.id`。 @@ -151,30 +151,30 @@ curl "https://api.telegram.org/bot/getUpdates" - 两个控制项会同时生效： + 两个控制项会共同生效： 1. **允许哪些群组**（`channels.telegram.groups`） - 没有 `groups` 配置： - - 当 `groupPolicy: "open"` 时：任何群组都可以通过 group-id 检查 - - 当 `groupPolicy: "allowlist"`（默认）时：在你添加 `groups` 条目（或 `"*"`）之前，群组会被阻止 - - 已配置 `groups`：作为 allowlist 使用（显式 ID 或 `"*"`） + - 如果 `groupPolicy: "open"`：任意群组都可以通过群组 ID 检查 + - 如果 `groupPolicy: "allowlist"`（默认）：在你添加 `groups` 条目（或 `"*"`）之前，群组会被阻止 + - 已配置 `groups`：其行为是 allowlist（显式 ID 或 `"*"`） - 2. **允许哪些发送者在群组中使用**（`channels.telegram.groupPolicy`） + 2. **群组中允许哪些发送者**（`channels.telegram.groupPolicy`） - `open` - `allowlist`（默认） - `disabled` `groupAllowFrom` 用于群组发送者过滤。如果未设置，Telegram 会回退到 `allowFrom`。 - `groupAllowFrom` 条目应为数值型 Telegram 用户 ID（`telegram:` / `tg:` 前缀会被规范化）。 - 不要把 Telegram 群组或超级群组聊天 ID 放入 `groupAllowFrom`。负数聊天 ID 应放在 `channels.telegram.groups` 下。 - 非数值条目会在发送者授权时被忽略。 - 安全边界（`2026.2.25+`）：群组发送者授权 **不会**继承私信配对存储中的批准。 - 配对仍然仅限私信。对于群组，请设置 `groupAllowFrom` 或按群组/按话题的 `allowFrom`。 - 如果 `groupAllowFrom` 未设置，Telegram 会回退到配置中的 `allowFrom`，而不是配对存储。 - 单所有者机器人的实用模式：将你的用户 ID 设置到 `channels.telegram.allowFrom`，保持 `groupAllowFrom` 未设置，并在 `channels.telegram.groups` 下允许目标群组。 - 运行时说明：如果完全缺少 `channels.telegram`，除非显式设置了 `channels.defaults.groupPolicy`，否则运行时默认使用失败即关闭的 `groupPolicy="allowlist"`。 + `groupAllowFrom` 条目应为 Telegram 数字用户 ID（`telegram:` / `tg:` 前缀会被规范化）。 + 不要把 Telegram 群组或超级群组聊天 ID 放在 `groupAllowFrom` 中。负数聊天 ID 应放在 `channels.telegram.groups` 下。 + 非数字条目会在发送者授权时被忽略。 + 安全边界（`2026.2.25+`）：群组发送者授权 **不会**继承私信配对存储中的批准结果。 + 配对仍然只适用于私信。对于群组，请设置 `groupAllowFrom` 或每个群组/每个话题的 `allowFrom`。 + 如果未设置 `groupAllowFrom`，Telegram 会回退到配置中的 `allowFrom`，而不是配对存储。 + 对于单一所有者机器人，实用模式是：将你的用户 ID 放入 `channels.telegram.allowFrom`，保持 `groupAllowFrom` 未设置，并在 `channels.telegram.groups` 下允许目标群组。 + 运行时说明：如果 `channels.telegram` 完全缺失，运行时默认采用失败即关闭的 `groupPolicy="allowlist"`，除非显式设置了 `channels.defaults.groupPolicy`。 - 示例：允许一个特定群组中的任意成员： + 示例：允许某个特定群组中的任意成员： ```json5 { @@ -191,7 +191,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 示例：仅允许一个特定群组中的特定用户： + 示例：只允许某个特定群组中的特定用户： ```json5 { @@ -212,8 +212,8 @@ curl "https://api.telegram.org/bot/getUpdates" 常见错误：`groupAllowFrom` 不是 Telegram 群组 allowlist。 - 将 `-1001234567890` 这类负数 Telegram 群组或超级群组聊天 ID 放在 `channels.telegram.groups` 下。 - - 当你想限制允许群组中哪些人可以触发机器人时，将 `8734062810` 这类 Telegram 用户 ID 放在 `groupAllowFrom` 下。 - - 只有当你希望允许群组中的任意成员与机器人对话时，才使用 `groupAllowFrom: ["*"]`。 + - 当你想限制允许群组中哪些人可以触发机器人时，将像 `8734062810` 这样的 Telegram 用户 ID 放在 `groupAllowFrom` 下。 + - 仅当你希望允许群组中的任意成员都能与机器人对话时，才使用 `groupAllowFrom: ["*"]`。 @@ -224,7 +224,7 @@ curl "https://api.telegram.org/bot/getUpdates" 提及可以来自： - 原生 `@botusername` 提及，或 - - 以下配置中的提及模式： + - 以下位置中的提及模式： - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` @@ -233,7 +233,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `/activation always` - `/activation mention` - 这些只会更新会话状态。若要持久化，请使用配置。 + 这些只会更新会话状态。要持久化，请使用配置。 持久化配置示例： @@ -252,27 +252,27 @@ curl "https://api.telegram.org/bot/getUpdates" 获取群组聊天 ID： - 将群组消息转发给 `@userinfobot` / `@getidsbot` - - 或从 `openclaw logs --follow` 读取 `chat.id` - - 或检查 Bot API `getUpdates` + - 或从 `openclaw logs --follow` 中读取 `chat.id` + - 或查看 Bot API `getUpdates` ## 运行时行为 -- Telegram 由 Gateway 网关进程持有。 +- Telegram 由 Gateway 网关进程负责管理。 - 路由是确定性的：Telegram 入站回复会回到 Telegram（模型不会选择渠道）。 -- 入站消息会规范化为共享渠道信封格式，并附带回复元数据和媒体占位符。 +- 入站消息会规范化为共享渠道信封，并带有回复元数据和媒体占位符。 - 群组会话按群组 ID 隔离。论坛话题会追加 `:topic:` 以保持话题隔离。 - 私信消息可以携带 `message_thread_id`；OpenClaw 会使用线程感知的会话键进行路由，并为回复保留线程 ID。 -- 长轮询使用带有按聊天/按线程顺序控制的 grammY runner。整体 runner sink 并发度使用 `agents.defaults.maxConcurrent`。 +- 长轮询使用带有每聊天/每线程顺序控制的 grammY runner。整体 runner sink 并发度使用 `agents.defaults.maxConcurrent`。 - Telegram Bot API 不支持已读回执（`sendReadReceipts` 不适用）。 ## 功能参考 - OpenClaw 可以实时流式发送部分回复： + OpenClaw 可以实时流式传输部分回复： - 私聊：预览消息 + `editMessageText` - 群组/话题：预览消息 + `editMessageText` @@ -280,23 +280,23 @@ curl "https://api.telegram.org/bot/getUpdates" 要求： - `channels.telegram.streaming` 为 `off | partial | block | progress`（默认：`partial`） - - `progress` 在 Telegram 上映射为 `partial`（与跨渠道命名兼容） + - `progress` 在 Telegram 上会映射为 `partial`（与跨渠道命名兼容） - 旧版 `channels.telegram.streamMode` 和布尔型 `streaming` 值会自动映射 对于纯文本回复： - - 私信：OpenClaw 保持同一个预览消息，并在原地执行最终编辑（不会发送第二条消息） - - 群组/话题：OpenClaw 保持同一个预览消息，并在原地执行最终编辑（不会发送第二条消息） + - 私信：OpenClaw 会保留同一条预览消息，并在原位置执行最终编辑（不会发送第二条消息） + - 群组/话题：OpenClaw 会保留同一条预览消息，并在原位置执行最终编辑（不会发送第二条消息） - 对于复杂回复（例如媒体负载），OpenClaw 会回退为正常的最终投递，然后清理预览消息。 + 对于复杂回复（例如媒体负载），OpenClaw 会回退为普通最终投递，然后清理预览消息。 预览流式传输与分块流式传输是分开的。当为 Telegram 显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。 - 如果原生草稿传输不可用或被拒绝，OpenClaw 会自动回退到 `sendMessage` + `editMessageText`。 + 如果原生草稿传输不可用/被拒绝，OpenClaw 会自动回退到 `sendMessage` + `editMessageText`。 - Telegram 专属推理流： + Telegram 专用推理流： - - `/reasoning stream` 会在生成时把推理发送到实时预览中 + - `/reasoning stream` 会在生成时将推理发送到实时预览 - 最终答案发送时不包含推理文本 @@ -304,7 +304,7 @@ curl "https://api.telegram.org/bot/getUpdates" 出站文本使用 Telegram `parse_mode: "HTML"`。 - - 类 Markdown 文本会渲染为 Telegram 安全的 HTML。 + - 类 Markdown 文本会被渲染为 Telegram 安全的 HTML。 - 原始模型 HTML 会被转义，以减少 Telegram 解析失败。 - 如果 Telegram 拒绝解析后的 HTML，OpenClaw 会以纯文本重试。 @@ -313,11 +313,11 @@ curl "https://api.telegram.org/bot/getUpdates" - Telegram 命令菜单注册在启动时通过 `setMyCommands` 处理。 + Telegram 命令菜单注册会在启动时通过 `setMyCommands` 处理。 原生命令默认值： - - `commands.native: "auto"` 为 Telegram 启用原生命令 + - `commands.native: "auto"` 会为 Telegram 启用原生命令 添加自定义命令菜单项： @@ -327,7 +327,7 @@ curl "https://api.telegram.org/bot/getUpdates" telegram: { customCommands: [ { command: "backup", description: "Git 备份" }, - { command: "generate", description: "创建图像" }, + { command: "generate", description: "创建图片" }, ], }, }, @@ -336,45 +336,45 @@ curl "https://api.telegram.org/bot/getUpdates" 规则： - - 名称会被规范化（去除前导 `/`，转为小写） + - 名称会被规范化（去掉前导 `/`，转换为小写） - 有效模式：`a-z`、`0-9`、`_`，长度 `1..32` - 自定义命令不能覆盖原生命令 - 冲突/重复项会被跳过并记录日志 说明： - - 自定义命令仅是菜单项；不会自动实现行为 + - 自定义命令只是菜单项；它们不会自动实现行为 - 即使未显示在 Telegram 菜单中，插件/Skills 命令在手动输入时仍然可以工作 - 如果禁用了原生命令，内置命令会被移除。自定义/插件命令如果已配置，仍可能注册。 + 如果禁用了原生命令，内置命令会被移除。若已配置，自定义/插件命令仍可能注册。 常见设置失败： - - `setMyCommands failed` 且带有 `BOT_COMMANDS_TOO_MUCH` 表示即使裁剪后 Telegram 菜单仍然溢出；请减少插件/Skills/自定义命令，或禁用 `channels.telegram.commands.native`。 - - `setMyCommands failed` 且带有网络/fetch 错误通常表示到 `api.telegram.org` 的出站 DNS/HTTPS 被阻止。 + - `setMyCommands failed` 且出现 `BOT_COMMANDS_TOO_MUCH`，表示即使裁剪后 Telegram 菜单仍然超出限制；请减少插件/Skills/自定义命令，或禁用 `channels.telegram.commands.native`。 + - `setMyCommands failed` 且出现网络/fetch 错误，通常表示到 `api.telegram.org` 的出站 DNS/HTTPS 被阻止。 ### 设备配对命令（`device-pair` 插件） - 当安装 `device-pair` 插件后： + 安装 `device-pair` 插件后： 1. `/pair` 生成设置代码 2. 在 iOS 应用中粘贴代码 3. `/pair pending` 列出待处理请求（包括角色/作用域） 4. 批准请求： - - `/pair approve ` 进行显式批准 - - 当只有一个待处理请求时，使用 `/pair approve` - - 使用 `/pair approve latest` 批准最近一个 + - `/pair approve ` 用于显式批准 + - 当只有一个待处理请求时使用 `/pair approve` + - `/pair approve latest` 用于最近的请求 - 设置代码携带短时有效的 bootstrap 令牌。内置 bootstrap 交接会将主节点令牌保持为 `scopes: []`；任何交接出的操作员令牌仍然限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write`。Bootstrap 作用域检查带有角色前缀，因此该操作员 allowlist 只满足操作员请求；非操作员角色仍需要其自身角色前缀下的作用域。 + 设置代码携带一个短期有效的 bootstrap 令牌。内置的 bootstrap 交接会将主节点令牌保持为 `scopes: []`；任何交接出去的操作员令牌都会限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write`。Bootstrap 作用域检查带有角色前缀，因此该操作员 allowlist 只满足操作员请求；非操作员角色仍然需要其自身角色前缀下的作用域。 - 如果设备使用已更改的鉴权详情重试（例如角色/作用域/公钥），之前的待处理请求会被替代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。 + 如果设备在重试时更改了认证详情（例如角色/作用域/公钥），之前的待处理请求会被新请求取代，而新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。 - 更多详情：[配对](/channels/pairing#pair-via-telegram-recommended-for-ios)。 + 更多细节：[配对](/zh-CN/channels/pairing#pair-via-telegram-recommended-for-ios)。 - 配置内联键盘作用域： + 配置内联键盘范围： ```json5 { @@ -388,7 +388,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 按账户覆盖： + 每账号覆盖： ```json5 { @@ -406,7 +406,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 作用域： + 范围： - `off` - `dm` @@ -423,13 +423,13 @@ curl "https://api.telegram.org/bot/getUpdates" action: "send", channel: "telegram", to: "123456789", - message: "Choose an option:", + message: "请选择一个选项：", buttons: [ [ - { text: "Yes", callback_data: "yes" }, - { text: "No", callback_data: "no" }, + { text: "是", callback_data: "yes" }, + { text: "否", callback_data: "no" }, ], - [{ text: "Cancel", callback_data: "cancel" }], + [{ text: "取消", callback_data: "cancel" }], ], } ``` @@ -442,25 +442,25 @@ curl "https://api.telegram.org/bot/getUpdates" Telegram 工具动作包括： - - `sendMessage`（`to`、`content`、可选 `mediaUrl`、`replyToMessageId`、`messageThreadId`） + - `sendMessage`（`to`、`content`、可选的 `mediaUrl`、`replyToMessageId`、`messageThreadId`） - `react`（`chatId`、`messageId`、`emoji`） - `deleteMessage`（`chatId`、`messageId`） - `editMessage`（`chatId`、`messageId`、`content`） - - `createForumTopic`（`chatId`、`name`、可选 `iconColor`、`iconCustomEmojiId`） + - `createForumTopic`（`chatId`、`name`、可选的 `iconColor`、`iconCustomEmojiId`） - 渠道消息动作提供更易用的别名（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。 + 渠道消息动作提供了更易用的别名（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。 - 开关控制： + 门控控制项： - `channels.telegram.actions.sendMessage` - `channels.telegram.actions.deleteMessage` - `channels.telegram.actions.reactions` - `channels.telegram.actions.sticker`（默认：禁用） - 注意：`edit` 和 `topic-create` 当前默认启用，没有单独的 `channels.telegram.actions.*` 开关。 + 注意：`edit` 和 `topic-create` 当前默认启用，且没有单独的 `channels.telegram.actions.*` 开关。 运行时发送使用当前激活的配置/密钥快照（启动/重载时），因此动作路径不会在每次发送时临时重新解析 SecretRef。 - 移除 reaction 的语义：[/tools/reactions](/tools/reactions) + 移除反应的语义：[/tools/reactions](/zh-CN/tools/reactions) @@ -468,7 +468,7 @@ curl "https://api.telegram.org/bot/getUpdates" Telegram 支持在生成输出中使用显式回复线程标签： - `[[reply_to_current]]` 回复触发消息 - - `[[reply_to:]]` 回复特定的 Telegram 消息 ID + - `[[reply_to:]]` 回复某个特定的 Telegram 消息 ID `channels.telegram.replyToMode` 控制处理方式： @@ -476,7 +476,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `first` - `all` - 注意：`off` 会禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍会被遵循。 + 注意：`off` 会禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍会生效。 @@ -484,19 +484,19 @@ curl "https://api.telegram.org/bot/getUpdates" 论坛超级群组： - 话题会话键会追加 `:topic:` - - 回复和输入状态都以话题线程为目标 + - 回复和输入状态会定向到该话题线程 - 话题配置路径： `channels.telegram.groups..topics.` - 通用话题（`threadId=1`）特殊情况： + 常规话题（`threadId=1`）特殊情况： - 发送消息时会省略 `message_thread_id`（Telegram 会拒绝 `sendMessage(...thread_id=1)`） - - 输入动作仍会包含 `message_thread_id` + - 输入状态动作仍然包含 `message_thread_id` - 话题继承：除非显式覆盖，话题条目会继承群组设置（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。 - `agentId` 是仅限话题的字段，不会继承群组默认值。 + 话题继承：除非被覆盖，话题条目会继承群组设置（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。 + `agentId` 仅适用于话题，不会从群组默认值继承。 - **按话题智能体路由**：每个话题都可以通过在话题配置中设置 `agentId` 路由到不同的智能体。这让每个话题都有自己隔离的工作区、记忆和会话。示例： + **按话题分配智能体路由**：每个话题都可以通过在话题配置中设置 `agentId` 路由到不同的智能体。这样每个话题都有自己隔离的工作区、记忆和会话。示例： ```json5 { @@ -505,9 +505,9 @@ curl "https://api.telegram.org/bot/getUpdates" groups: { "-1001234567890": { topics: { - "1": { agentId: "main" }, // 通用话题 → main 智能体 + "1": { agentId: "main" }, // 常规话题 → main 智能体 "3": { agentId: "zu" }, // 开发话题 → zu 智能体 - "5": { agentId: "coder" } // 代码评审 → coder 智能体 + "5": { agentId: "coder" } // 代码审查 → coder 智能体 } } } @@ -516,11 +516,11 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 这样每个话题都有自己的会话键：`agent:zu:telegram:group:-1001234567890:topic:3` + 此后每个话题都有自己的会话键：`agent:zu:telegram:group:-1001234567890:topic:3` - **持久化 ACP 话题绑定**：论坛话题可以通过顶层类型化 ACP 绑定固定到 ACP harness 会话： + **持久化 ACP 话题绑定**：论坛话题可以通过顶层类型化 ACP 绑定固定 ACP harness 会话： - - `bindings[]` 中设置 `type: "acp"` 和 `match.channel: "telegram"` + - `bindings[]`，其中 `type: "acp"` 且 `match.channel: "telegram"` 示例： @@ -571,11 +571,11 @@ curl "https://api.telegram.org/bot/getUpdates" 当前这仅适用于群组和超级群组中的论坛话题。 - **从聊天中启动线程绑定的 ACP 会话**： + **从聊天中生成线程绑定的 ACP**： - - `/acp spawn --thread here|auto` 可以将当前 Telegram 话题绑定到新的 ACP 会话。 - - 后续该话题中的消息会直接路由到绑定的 ACP 会话（无需 `/acp steer`）。 - - 绑定成功后，OpenClaw 会在话题中置顶 spawn 确认消息。 + - `/acp spawn --thread here|auto` 可以将当前 Telegram 话题绑定到一个新的 ACP 会话。 + - 后续该话题中的消息会直接路由到已绑定的 ACP 会话（无需 `/acp steer`）。 + - 成功绑定后，OpenClaw 会在话题中固定显示生成确认消息。 - 需要 `channels.telegram.threadBindings.spawnAcpSessions=true`。 模板上下文包括： @@ -585,17 +585,17 @@ curl "https://api.telegram.org/bot/getUpdates" 私信线程行为： - - 带有 `message_thread_id` 的私聊会保持私信路由，但使用线程感知的会话键/回复目标。 + - 带有 `message_thread_id` 的私聊会保留私信路由，但使用线程感知的会话键/回复目标。 ### 音频消息 - Telegram 区分语音便签和音频文件。 + Telegram 会区分语音消息和音频文件。 - - 默认：按音频文件处理 - - 在智能体回复中添加标签 `[[audio_as_voice]]` 可强制按语音便签发送 + - 默认：音频文件行为 + - 在智能体回复中添加标签 `[[audio_as_voice]]` 可强制按语音消息发送 消息动作示例： @@ -611,7 +611,7 @@ curl "https://api.telegram.org/bot/getUpdates" ### 视频消息 - Telegram 区分视频文件和视频便签。 + Telegram 会区分视频文件和视频便笺。 消息动作示例： @@ -625,14 +625,14 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 视频便签不支持说明文字；提供的消息文本会单独发送。 + 视频便笺不支持说明文字；提供的消息文本会单独发送。 ### 贴纸 入站贴纸处理： - 静态 WEBP：下载并处理（占位符 ``） - - 动画 TGS：跳过 + - 动态 TGS：跳过 - 视频 WEBM：跳过 贴纸上下文字段： @@ -647,7 +647,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `~/.openclaw/telegram/sticker-cache.json` - 贴纸会尽可能只描述一次并进行缓存，以减少重复的视觉调用。 + 贴纸会在可能时描述一次并缓存，以减少重复的视觉调用。 启用贴纸动作： @@ -674,21 +674,21 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 搜索缓存贴纸： + 搜索缓存的贴纸： ```json5 { action: "sticker-search", channel: "telegram", - query: "cat waving", + query: "挥手的猫", limit: 5, } ``` - - Telegram reaction 作为 `message_reaction` 更新到达（独立于消息负载）。 + + Telegram 反应以 `message_reaction` 更新的形式到达（与消息负载分开）。 启用后，OpenClaw 会将如下系统事件加入队列： @@ -701,17 +701,17 @@ curl "https://api.telegram.org/bot/getUpdates" 说明： - - `own` 表示仅用户对机器人发送消息的 reaction（通过已发送消息缓存尽力识别）。 - - Reaction 事件仍然遵守 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权发送者会被丢弃。 - - Telegram 不在 reaction 更新中提供线程 ID。 + - `own` 表示仅用户对机器人发送消息的反应（尽力通过已发送消息缓存实现）。 + - 反应事件仍遵守 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权发送者会被丢弃。 + - Telegram 不会在反应更新中提供线程 ID。 - 非论坛群组会路由到群组聊天会话 - - 论坛群组会路由到群组通用话题会话（`:topic:1`），而不是确切来源话题 + - 论坛群组会路由到群组常规话题会话（`:topic:1`），而不是精确的来源话题 - 轮询/webhook 的 `allowed_updates` 会自动包含 `message_reaction`。 + 轮询/Webhook 的 `allowed_updates` 会自动包含 `message_reaction`。 - + `ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认 emoji。 解析顺序： @@ -719,12 +719,12 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - 智能体身份 emoji 回退（`agents.list[].identity.emoji`，否则为 `"👀"`） + - 智能体身份 emoji 回退（`agents.list[].identity.emoji`，否则为 "👀"） 说明： - - Telegram 期望的是 Unicode emoji（例如 `"👀"`）。 - - 使用 `""` 可为某个渠道或账户禁用该 reaction。 + - Telegram 需要 unicode emoji（例如 "👀"）。 + - 使用 `""` 可为某个渠道或账号禁用该反应。 @@ -750,38 +750,38 @@ curl "https://api.telegram.org/bot/getUpdates" - + 默认：长轮询。 - webhook 模式： + Webhook 模式： - 设置 `channels.telegram.webhookUrl` - - 设置 `channels.telegram.webhookSecret`（设置 webhook URL 时必需） + - 设置 `channels.telegram.webhookSecret`（设置了 webhook URL 时必填） - 可选 `channels.telegram.webhookPath`（默认 `/telegram-webhook`） - 可选 `channels.telegram.webhookHost`（默认 `127.0.0.1`） - 可选 `channels.telegram.webhookPort`（默认 `8787`） - webhook 模式下的默认本地监听绑定到 `127.0.0.1:8787`。 + Webhook 模式的默认本地监听器绑定到 `127.0.0.1:8787`。 - 如果你的公共端点不同，请在前面放置反向代理，并让 `webhookUrl` 指向公共 URL。 - 当你明确需要外部入口时，请设置 `webhookHost`（例如 `0.0.0.0`）。 + 如果你的公共端点不同，请在前面放置一个反向代理，并将 `webhookUrl` 指向公共 URL。 + 如果你确实需要外部入口，请设置 `webhookHost`（例如 `0.0.0.0`）。 - `channels.telegram.textChunkLimit` 默认值为 4000。 - - `channels.telegram.chunkMode="newline"` 会优先在段落边界（空行）处分割，再按长度拆分。 + - `channels.telegram.chunkMode="newline"` 会在按长度切分前优先按段落边界（空行）切分。 - `channels.telegram.mediaMaxMb`（默认 100）限制 Telegram 入站和出站媒体大小。 - - `channels.telegram.timeoutSeconds` 覆盖 Telegram API 客户端超时（若未设置，则使用 grammY 默认值）。 + - `channels.telegram.timeoutSeconds` 会覆盖 Telegram API 客户端超时时间（如果未设置，则使用 grammY 默认值）。 - 群组上下文历史使用 `channels.telegram.historyLimit` 或 `messages.groupChat.historyLimit`（默认 50）；`0` 表示禁用。 - - reply/quote/forward 的补充上下文当前会按接收内容原样传递。 - - Telegram allowlist 主要用于限制谁可以触发智能体，而不是完整的补充上下文脱敏边界。 + - 回复/引用/转发的补充上下文当前会按接收时的内容直接传递。 + - Telegram allowlist 主要限制的是谁可以触发智能体，而不是一个完整的补充上下文脱敏边界。 - 私信历史控制： - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - `channels.telegram.retry` 配置适用于 Telegram 发送辅助函数（CLI/工具/动作）中的可恢复出站 API 错误。 + - `channels.telegram.retry` 配置适用于 Telegram 发送辅助功能（CLI/工具/动作）中的可恢复出站 API 错误。 - CLI 发送目标可以是数值聊天 ID 或用户名： + CLI 发送目标可以是数字聊天 ID 或用户名： ```bash openclaw message send --channel telegram --target 123456789 --message "hi" @@ -798,7 +798,7 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-duration-seconds 300 --poll-public ``` - Telegram 专属投票标志： + Telegram 专用投票标志： - `--poll-duration-seconds`（5-600） - `--poll-anonymous` @@ -807,10 +807,10 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ Telegram 发送还支持： - - `--buttons`：当 `channels.telegram.capabilities.inlineButtons` 允许时，用于内联键盘 - - `--force-document`：将出站图像和 GIF 作为文档发送，而不是压缩照片或动画媒体上传 + - `--buttons`，用于在 `channels.telegram.capabilities.inlineButtons` 允许时使用内联键盘 + - `--force-document`，将出站图片和 GIF 作为文档发送，而不是作为压缩照片或动画媒体上传 - 动作开关： + 动作门控： - `channels.telegram.actions.sendMessage=false` 会禁用出站 Telegram 消息，包括投票 - `channels.telegram.actions.poll=false` 会禁用 Telegram 投票创建，同时保留常规发送功能 @@ -818,58 +818,59 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ - Telegram 支持在批准者私信中进行 exec 批准，并且可以选择在来源聊天或话题中发布批准提示。 + Telegram 支持在批准者私信中进行 exec 批准，也可以选择在原始聊天或话题中发布批准提示。 配置路径： - `channels.telegram.execApprovals.enabled` - - `channels.telegram.execApprovals.approvers`（可选；如果可能，会回退到从 `allowFrom` 和直接 `defaultTo` 推断出的数值所有者 ID） + - `channels.telegram.execApprovals.approvers`（可选；在可能的情况下，会回退到从 `allowFrom` 和直接 `defaultTo` 推断出的数字所有者 ID） - `channels.telegram.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`） - `agentFilter`、`sessionFilter` - 批准者必须是数值型 Telegram 用户 ID。当 `enabled` 未设置或为 `"auto"`，且至少能解析出一个批准者时，Telegram 会自动启用原生 exec 批准；批准者可来自 `execApprovals.approvers`，也可来自账户的数值所有者配置（`allowFrom` 和私信 `defaultTo`）。如需明确禁用 Telegram 作为原生批准客户端，请设置 `enabled: false`。否则，批准请求会回退到其他已配置的批准路由或 exec 批准回退策略。 + 批准者必须是数字 Telegram 用户 ID。当 `enabled` 未设置或为 `"auto"`，且至少能解析出一个批准者时，Telegram 会自动启用原生 exec 批准；这些批准者可以来自 `execApprovals.approvers`，也可以来自账号的数字所有者配置（`allowFrom` 和私信 `defaultTo`）。设置 `enabled: false` 可显式禁用 Telegram 作为原生批准客户端。否则，批准请求会回退到其他已配置的批准路径或 exec 批准回退策略。 - Telegram 也会渲染其他聊天渠道使用的共享批准按钮。原生 Telegram 适配器主要增加批准者私信路由、渠道/话题扇出，以及投递前的输入提示。 - 当这些按钮存在时，它们就是主要的批准 UX；只有在工具结果表明聊天批准不可用，或手动批准是唯一途径时，OpenClaw + Telegram 还会渲染其他聊天渠道使用的共享批准按钮。原生 Telegram 适配器主要增加了批准者私信路由、渠道/话题扇出，以及投递前的输入提示。 + 当这些按钮存在时，它们是主要的批准 UX；只有当工具结果表明 + 聊天批准不可用，或者手动批准是唯一途径时，OpenClaw 才应包含手动 `/approve` 命令。 投递规则： - - `target: "dm"` 仅向已解析的批准者私信发送批准提示 - - `target: "channel"` 将提示发回来源 Telegram 聊天/话题 - - `target: "both"` 同时发送到批准者私信和来源聊天/话题 + - `target: "dm"` 只会将批准提示发送到已解析的批准者私信 + - `target: "channel"` 会将提示发送回原始 Telegram 聊天/话题 + - `target: "both"` 会同时发送到批准者私信和原始聊天/话题 - 只有已解析的批准者才能批准或拒绝。非批准者不能使用 `/approve`，也不能使用 Telegram 批准按钮。 + 只有已解析的批准者可以批准或拒绝。非批准者不能使用 `/approve`，也不能使用 Telegram 批准按钮。 批准解析行为： - - 带有 `plugin:` 前缀的批准 ID 总是通过插件批准进行解析。 + - 以 `plugin:` 为前缀的 ID 总是通过插件批准进行解析。 - 其他批准 ID 会先尝试 `exec.approval.resolve`。 - - 如果 Telegram 也被授权用于插件批准，且 Gateway 网关表示 - exec 批准未知/已过期，Telegram 会通过 - `plugin.approval.resolve` 再重试一次。 - - 真实的 exec 批准拒绝/错误不会悄悄回退到插件 + - 如果 Telegram 也被授权用于插件批准，并且 Gateway 网关返回 + exec 批准未知/已过期，Telegram 会再通过 + `plugin.approval.resolve` 重试一次。 + - 真正的 exec 批准拒绝/错误不会静默回退到插件 批准解析。 - 渠道投递会在聊天中显示命令文本，因此仅应在可信群组/话题中启用 `channel` 或 `both`。当提示落在论坛话题中时，OpenClaw 会为批准提示和批准后的后续消息都保留该话题。Exec 批准默认在 30 分钟后过期。 + 渠道投递会在聊天中显示命令文本，因此仅应在受信任的群组/话题中启用 `channel` 或 `both`。当提示落在论坛话题中时，OpenClaw 会为批准提示和批准后的后续消息都保留该话题。exec 批准默认会在 30 分钟后过期。 - 内联批准按钮还依赖于 `channels.telegram.capabilities.inlineButtons` 允许目标表面（`dm`、`group` 或 `all`）。 + 内联批准按钮还依赖 `channels.telegram.capabilities.inlineButtons` 允许目标范围（`dm`、`group` 或 `all`）。 - 相关文档：[Exec 批准](/tools/exec-approvals) + 相关文档：[Exec 批准](/zh-CN/tools/exec-approvals) ## 错误回复控制 -当智能体遇到投递或提供商错误时，Telegram 可以回复错误文本，也可以抑制错误文本。两个配置键控制此行为： +当智能体遇到投递或提供商错误时，Telegram 可以选择回复错误文本，或将其抑制。两个配置键控制此行为： | Key | Values | Default | Description | | ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- | -| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` 向聊天发送友好的错误消息。`silent` 完全抑制错误回复。 | -| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | 同一聊天两次错误回复之间的最短时间。防止故障期间错误刷屏。 | +| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` 会向聊天发送一条友好的错误消息。`silent` 会完全抑制错误回复。 | +| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | 同一聊天两次错误回复之间的最短时间。可防止在故障期间出现错误刷屏。 | -支持按账户、按群组和按话题覆盖（继承方式与其他 Telegram 配置键相同）。 +支持按账号、按群组和按话题覆盖（继承方式与其他 Telegram 配置键相同）。 ```json5 { @@ -879,7 +880,7 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ errorCooldownMs: 120000, groups: { "-1001234567890": { - errorPolicy: "silent", // 在此群组中抑制错误 + errorPolicy: "silent", // 在该群组中抑制错误 }, }, }, @@ -890,40 +891,40 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ ## 故障排除 - + - 如果 `requireMention=false`，Telegram 隐私模式必须允许完整可见性。 - BotFather：`/setprivacy` -> Disable - 然后将机器人从群组中移除并重新添加 - - 当配置期望未提及的群组消息时，`openclaw channels status` 会发出警告。 - - `openclaw channels status --probe` 可以检查显式数值群组 ID；无法对通配符 `"*"` 探测成员关系。 + - 当配置预期接收未提及的群组消息时，`openclaw channels status` 会发出警告。 + - `openclaw channels status --probe` 可以检查显式数字群组 ID；无法对通配符 `"*"` 执行成员资格探测。 - 快速会话测试：`/activation always`。 - - 当存在 `channels.telegram.groups` 时，群组必须已列出（或包含 `"*"`） - - 验证机器人是否已加入群组 - - 查看日志：使用 `openclaw logs --follow` 检查跳过原因 + - 当 `channels.telegram.groups` 存在时，必须列出该群组（或包含 `"*"`） + - 验证机器人是否已加入该群组 + - 查看日志：`openclaw logs --follow` 以获取跳过原因 - + - - 授权你的发送者身份（配对和/或数值型 `allowFrom`） - - 即使群组策略为 `open`，命令授权仍然适用 - - `setMyCommands failed` 且带有 `BOT_COMMANDS_TOO_MUCH` 表示原生菜单条目过多；请减少插件/Skills/自定义命令，或禁用原生菜单 - - `setMyCommands failed` 且带有网络/fetch 错误通常表示无法通过 DNS/HTTPS 访问 `api.telegram.org` + - 授权你的发送者身份（配对和/或数字 `allowFrom`） + - 即使群组策略是 `open`，命令授权仍然适用 + - `setMyCommands failed` 且出现 `BOT_COMMANDS_TOO_MUCH` 表示原生命令菜单项过多；请减少插件/Skills/自定义命令，或禁用原生菜单 + - `setMyCommands failed` 且出现网络/fetch 错误，通常表示到 `api.telegram.org` 的 DNS/HTTPS 连通性有问题 - - Node 22+ + 自定义 fetch/proxy 如果 AbortSignal 类型不匹配，可能触发立即中止行为。 + - Node 22+ + 自定义 fetch/proxy 在 AbortSignal 类型不匹配时可能触发立即中止行为。 - 某些主机会优先将 `api.telegram.org` 解析为 IPv6；损坏的 IPv6 出站连接可能导致 Telegram API 间歇性失败。 - 如果日志包含 `TypeError: fetch failed` 或 `Network request for 'getUpdates' failed!`，OpenClaw 现在会将这些作为可恢复网络错误进行重试。 - - 在出站/TLS 不稳定的 VPS 主机上，可通过 `channels.telegram.proxy` 路由 Telegram API 调用： + - 在出站连接/TLS 不稳定的 VPS 主机上，请通过 `channels.telegram.proxy` 转发 Telegram API 调用： ```yaml channels: @@ -932,7 +933,7 @@ channels: ``` - Node 22+ 默认使用 `autoSelectFamily=true`（WSL2 除外）和 `dnsResultOrder=ipv4first`。 - - 如果你的主机是 WSL2，或者明确在仅 IPv4 行为下运行更稳定，请强制选择地址族： + - 如果你的主机是 WSL2，或者明确在仅 IPv4 行为下运行更好，请强制设置地址族选择： ```yaml channels: @@ -941,11 +942,11 @@ channels: autoSelectFamily: false ``` - - RFC 2544 基准测试地址段应答（`198.18.0.0/15`）默认已 - 被允许用于 Telegram 媒体下载。如果受信任的 fake-IP 或 + - RFC 2544 基准测试地址范围（`198.18.0.0/15`）默认已被允许 + 用于 Telegram 媒体下载。如果受信任的 fake-IP 或 透明代理在媒体下载期间将 `api.telegram.org` 重写为其他 私有/内部/特殊用途地址，你可以选择启用 - Telegram 专属绕过： + Telegram 专用绕过： ```yaml channels: @@ -954,25 +955,25 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - 同样的可选启用项也可按账户设置在 + - 同样的可选启用项也可按账号设置在 `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`。 - 如果你的代理将 Telegram 媒体主机解析到 `198.18.x.x`，请先保持 - 危险标志关闭。Telegram 媒体默认已经允许 RFC 2544 - 基准测试地址段。 + 该危险标志关闭。Telegram 媒体默认已经允许 RFC 2544 + 基准测试地址范围。 `channels.telegram.network.dangerouslyAllowPrivateNetwork` 会削弱 Telegram - 媒体 SSRF 防护。仅应在受信任、由操作者控制的代理 + 媒体 SSRF 防护。仅应在受信任的、由操作员控制的代理 环境中使用，例如 Clash、Mihomo 或 Surge 的 fake-IP 路由， - 且它们会在 RFC 2544 基准测试地址段之外合成私有或特殊用途应答时。 - 对于普通公共互联网 Telegram 访问，请保持关闭。 + 且它们会在 RFC 2544 基准测试地址范围之外合成私有或特殊用途地址时。 + 对于正常的公共互联网 Telegram 访问，请保持关闭。 - 环境变量覆盖（临时）： - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` - - 验证 DNS 应答： + - 验证 DNS 解析结果： ```bash dig +short api.telegram.org A @@ -982,79 +983,79 @@ dig +short api.telegram.org AAAA -更多帮助：[渠道故障排除](/channels/troubleshooting)。 +更多帮助：[渠道故障排除](/zh-CN/channels/troubleshooting)。 -## Telegram 配置参考指针 +## Telegram 配置参考指引 主要参考： - `channels.telegram.enabled`：启用/禁用渠道启动。 - `channels.telegram.botToken`：机器人令牌（BotFather）。 -- `channels.telegram.tokenFile`：从常规文件路径读取令牌。不允许符号链接。 +- `channels.telegram.tokenFile`：从常规文件路径读取令牌。不接受符号链接。 - `channels.telegram.dmPolicy`：`pairing | allowlist | open | disabled`（默认：pairing）。 -- `channels.telegram.allowFrom`：私信 allowlist（数值型 Telegram 用户 ID）。`allowlist` 要求至少一个发送者 ID。`open` 要求 `"*"`。`openclaw doctor --fix` 可以将旧版 `@username` 条目解析为 ID，也可以在 allowlist 迁移流程中从配对存储文件恢复 allowlist 条目。 -- `channels.telegram.actions.poll`：启用或禁用 Telegram 投票创建（默认：启用；仍要求 `sendMessage`）。 +- `channels.telegram.allowFrom`：私信 allowlist（Telegram 数字用户 ID）。`allowlist` 需要至少一个发送者 ID。`open` 需要 `"*"`。`openclaw doctor --fix` 可以将旧版 `@username` 条目解析为 ID，也可以在 allowlist 迁移流程中从配对存储文件恢复 allowlist 条目。 +- `channels.telegram.actions.poll`：启用或禁用 Telegram 投票创建（默认：启用；仍然需要 `sendMessage`）。 - `channels.telegram.defaultTo`：当未提供显式 `--reply-to` 时，CLI `--deliver` 使用的默认 Telegram 目标。 - `channels.telegram.groupPolicy`：`open | allowlist | disabled`（默认：allowlist）。 -- `channels.telegram.groupAllowFrom`：群组发送者 allowlist（数值型 Telegram 用户 ID）。`openclaw doctor --fix` 可以将旧版 `@username` 条目解析为 ID。非数值条目会在鉴权时被忽略。群组鉴权不使用私信配对存储回退（`2026.2.25+`）。 -- 多账户优先级： - - 当配置了两个或更多账户 ID 时，请设置 `channels.telegram.defaultAccount`（或包含 `channels.telegram.accounts.default`）以显式指定默认路由。 - - 如果两者都未设置，OpenClaw 会回退到第一个规范化后的账户 ID，且 `openclaw doctor` 会发出警告。 - - `channels.telegram.accounts.default.allowFrom` 和 `channels.telegram.accounts.default.groupAllowFrom` 仅适用于 `default` 账户。 - - 当账户级值未设置时，命名账户会继承 `channels.telegram.allowFrom` 和 `channels.telegram.groupAllowFrom`。 - - 命名账户不会继承 `channels.telegram.accounts.default.allowFrom` / `groupAllowFrom`。 -- `channels.telegram.groups`：按群组的默认值 + allowlist（使用 `"*"` 作为全局默认值）。 - - `channels.telegram.groups..groupPolicy`：按群组覆盖 groupPolicy（`open | allowlist | disabled`）。 +- `channels.telegram.groupAllowFrom`：群组发送者 allowlist（Telegram 数字用户 ID）。`openclaw doctor --fix` 可以将旧版 `@username` 条目解析为 ID。非数字条目在认证时会被忽略。群组认证不会使用私信配对存储回退（`2026.2.25+`）。 +- 多账号优先级： + - 当配置了两个或更多账号 ID 时，设置 `channels.telegram.defaultAccount`（或包含 `channels.telegram.accounts.default`）以显式指定默认路由。 + - 如果两者都未设置，OpenClaw 会回退到第一个规范化账号 ID，并由 `openclaw doctor` 发出警告。 + - `channels.telegram.accounts.default.allowFrom` 和 `channels.telegram.accounts.default.groupAllowFrom` 仅适用于 `default` 账号。 + - 当账号级值未设置时，命名账号会继承 `channels.telegram.allowFrom` 和 `channels.telegram.groupAllowFrom`。 + - 命名账号不会继承 `channels.telegram.accounts.default.allowFrom` / `groupAllowFrom`。 +- `channels.telegram.groups`：每群组默认值 + allowlist（使用 `"*"` 作为全局默认值）。 + - `channels.telegram.groups..groupPolicy`：`groupPolicy` 的每群组覆盖（`open | allowlist | disabled`）。 - `channels.telegram.groups..requireMention`：提及门控默认值。 - - `channels.telegram.groups..skills`：Skills 过滤器（省略 = 所有 Skills，空数组 = 无）。 - - `channels.telegram.groups..allowFrom`：按群组覆盖发送者 allowlist。 + - `channels.telegram.groups..skills`：Skills 过滤器（省略 = 所有 Skills，空值 = 无）。 + - `channels.telegram.groups..allowFrom`：每群组发送者 allowlist 覆盖。 - `channels.telegram.groups..systemPrompt`：群组的额外系统提示词。 - - `channels.telegram.groups..enabled`：当为 `false` 时禁用该群组。 - - `channels.telegram.groups..topics..*`：按话题覆盖（群组字段 + 仅话题字段 `agentId`）。 - - `channels.telegram.groups..topics..agentId`：将此话题路由到特定智能体（覆盖群组级和绑定路由）。 -- `channels.telegram.groups..topics..groupPolicy`：按话题覆盖 groupPolicy（`open | allowlist | disabled`）。 -- `channels.telegram.groups..topics..requireMention`：按话题覆盖提及门控。 -- 顶层 `bindings[]` 中使用 `type: "acp"`，并在 `match.peer.id` 中使用规范话题 ID `chatId:topic:topicId`：持久化 ACP 话题绑定字段（参见 [ACP Agents](/tools/acp-agents#channel-specific-settings)）。 + - `channels.telegram.groups..enabled`：为 `false` 时禁用该群组。 + - `channels.telegram.groups..topics..*`：每话题覆盖（群组字段 + 仅话题字段 `agentId`）。 + - `channels.telegram.groups..topics..agentId`：将该话题路由到特定智能体（覆盖群组级和绑定路由）。 +- `channels.telegram.groups..topics..groupPolicy`：`groupPolicy` 的每话题覆盖（`open | allowlist | disabled`）。 +- `channels.telegram.groups..topics..requireMention`：每话题提及门控覆盖。 +- 顶层 `bindings[]` 中 `type: "acp"` 且在 `match.peer.id` 中使用规范话题 ID `chatId:topic:topicId`：持久化 ACP 话题绑定字段（见 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)）。 - `channels.telegram.direct..topics..agentId`：将私信话题路由到特定智能体（行为与论坛话题相同）。 -- `channels.telegram.execApprovals.enabled`：为此账户启用 Telegram 作为基于聊天的 exec 批准客户端。 -- `channels.telegram.execApprovals.approvers`：允许批准或拒绝 exec 请求的 Telegram 用户 ID。当 `channels.telegram.allowFrom` 或直接 `channels.telegram.defaultTo` 已标识所有者时，此项可选。 -- `channels.telegram.execApprovals.target`：`dm | channel | both`（默认：`dm`）。当存在来源话题时，`channel` 和 `both` 会保留该 Telegram 话题。 -- `channels.telegram.execApprovals.agentFilter`：可选的智能体 ID 过滤器，用于转发批准提示。 -- `channels.telegram.execApprovals.sessionFilter`：可选的会话键过滤器（子串或正则），用于转发批准提示。 -- `channels.telegram.accounts..execApprovals`：按账户覆盖 Telegram exec 批准路由和批准者授权。 +- `channels.telegram.execApprovals.enabled`：为此账号启用 Telegram 作为基于聊天的 exec 批准客户端。 +- `channels.telegram.execApprovals.approvers`：允许批准或拒绝 exec 请求的 Telegram 用户 ID。当 `channels.telegram.allowFrom` 或直接的 `channels.telegram.defaultTo` 已经标识出所有者时，此项可选。 +- `channels.telegram.execApprovals.target`：`dm | channel | both`（默认：`dm`）。`channel` 和 `both` 在存在时会保留原始 Telegram 话题。 +- `channels.telegram.execApprovals.agentFilter`：转发批准提示的可选智能体 ID 过滤器。 +- `channels.telegram.execApprovals.sessionFilter`：转发批准提示的可选会话键过滤器（子串或正则）。 +- `channels.telegram.accounts..execApprovals`：Telegram exec 批准路由和批准者授权的每账号覆盖。 - `channels.telegram.capabilities.inlineButtons`：`off | dm | group | all | allowlist`（默认：allowlist）。 -- `channels.telegram.accounts..capabilities.inlineButtons`：按账户覆盖。 +- `channels.telegram.accounts..capabilities.inlineButtons`：每账号覆盖。 - `channels.telegram.commands.nativeSkills`：启用/禁用 Telegram 原生 Skills 命令。 - `channels.telegram.replyToMode`：`off | first | all`（默认：`off`）。 -- `channels.telegram.textChunkLimit`：出站分块大小（字符数）。 -- `channels.telegram.chunkMode`：`length`（默认）或 `newline`，会先按空行（段落边界）分割，再进行长度分块。 +- `channels.telegram.textChunkLimit`：出站分块大小（字符）。 +- `channels.telegram.chunkMode`：`length`（默认）或 `newline`，表示在按长度分块前先按空行（段落边界）切分。 - `channels.telegram.linkPreview`：切换出站消息的链接预览（默认：true）。 -- `channels.telegram.streaming`：`off | partial | block | progress`（实时流式预览；默认：`partial`；`progress` 映射为 `partial`；`block` 是旧版预览模式兼容值）。Telegram 预览流式传输使用单条预览消息，并在原地编辑。 -- `channels.telegram.mediaMaxMb`：Telegram 入站/出站媒体大小上限（MB，默认：100）。 -- `channels.telegram.retry`：Telegram 发送辅助函数（CLI/工具/动作）在可恢复出站 API 错误上的重试策略（尝试次数、`minDelayMs`、`maxDelayMs`、抖动）。 -- `channels.telegram.network.autoSelectFamily`：覆盖 Node autoSelectFamily（true=启用，false=禁用）。在 Node 22+ 上默认启用，WSL2 默认禁用。 -- `channels.telegram.network.dnsResultOrder`：覆盖 DNS 结果顺序（`ipv4first` 或 `verbatim`）。在 Node 22+ 上默认使用 `ipv4first`。 -- `channels.telegram.network.dangerouslyAllowPrivateNetwork`：针对受信任 fake-IP 或透明代理环境的危险性可选启用项；当 Telegram 媒体下载将 `api.telegram.org` 解析到默认 RFC 2544 基准地址段许可范围之外的私有/内部/特殊用途地址时可使用。 +- `channels.telegram.streaming`：`off | partial | block | progress`（实时流式预览；默认：`partial`；`progress` 映射为 `partial`；`block` 是旧版预览模式兼容值）。Telegram 预览流式传输使用一条会原地编辑的预览消息。 +- `channels.telegram.mediaMaxMb`：Telegram 入站/出站媒体上限（MB，默认：100）。 +- `channels.telegram.retry`：Telegram 发送辅助功能（CLI/工具/动作）在可恢复的出站 API 错误时的重试策略（attempts、minDelayMs、maxDelayMs、jitter）。 +- `channels.telegram.network.autoSelectFamily`：覆盖 Node 的 autoSelectFamily（true = 启用，false = 禁用）。在 Node 22+ 上默认启用，WSL2 默认禁用。 +- `channels.telegram.network.dnsResultOrder`：覆盖 DNS 结果顺序（`ipv4first` 或 `verbatim`）。在 Node 22+ 上默认是 `ipv4first`。 +- `channels.telegram.network.dangerouslyAllowPrivateNetwork`：用于受信任 fake-IP 或透明代理环境的危险可选启用项；在这些环境中，Telegram 媒体下载会将 `api.telegram.org` 解析到默认 RFC 2544 基准范围允许之外的私有/内部/特殊用途地址。 - `channels.telegram.proxy`：Bot API 调用的代理 URL（SOCKS/HTTP）。 -- `channels.telegram.webhookUrl`：启用 webhook 模式（要求 `channels.telegram.webhookSecret`）。 -- `channels.telegram.webhookSecret`：webhook 密钥（设置 webhookUrl 时必需）。 -- `channels.telegram.webhookPath`：本地 webhook 路径（默认 `/telegram-webhook`）。 -- `channels.telegram.webhookHost`：本地 webhook 绑定主机（默认 `127.0.0.1`）。 -- `channels.telegram.webhookPort`：本地 webhook 绑定端口（默认 `8787`）。 -- `channels.telegram.actions.reactions`：控制 Telegram 工具 reaction。 +- `channels.telegram.webhookUrl`：启用 Webhook 模式（需要 `channels.telegram.webhookSecret`）。 +- `channels.telegram.webhookSecret`：Webhook 密钥（设置了 webhookUrl 时必填）。 +- `channels.telegram.webhookPath`：本地 Webhook 路径（默认 `/telegram-webhook`）。 +- `channels.telegram.webhookHost`：本地 Webhook 绑定主机（默认 `127.0.0.1`）。 +- `channels.telegram.webhookPort`：本地 Webhook 绑定端口（默认 `8787`）。 +- `channels.telegram.actions.reactions`：控制 Telegram 工具反应。 - `channels.telegram.actions.sendMessage`：控制 Telegram 工具消息发送。 - `channels.telegram.actions.deleteMessage`：控制 Telegram 工具消息删除。 - `channels.telegram.actions.sticker`：控制 Telegram 贴纸动作——发送和搜索（默认：false）。 -- `channels.telegram.reactionNotifications`：`off | own | all` —— 控制哪些 reaction 会触发系统事件（默认：未设置时为 `own`）。 -- `channels.telegram.reactionLevel`：`off | ack | minimal | extensive` —— 控制智能体的 reaction 能力（默认：未设置时为 `minimal`）。 -- `channels.telegram.errorPolicy`：`reply | silent` —— 控制错误回复行为（默认：`reply`）。支持按账户/群组/话题覆盖。 -- `channels.telegram.errorCooldownMs`：同一聊天两次错误回复之间的最短毫秒数（默认：`60000`）。防止故障期间错误刷屏。 +- `channels.telegram.reactionNotifications`：`off | own | all` —— 控制哪些反应会触发系统事件（未设置时默认：`own`）。 +- `channels.telegram.reactionLevel`：`off | ack | minimal | extensive` —— 控制智能体的反应能力（未设置时默认：`minimal`）。 +- `channels.telegram.errorPolicy`：`reply | silent` —— 控制错误回复行为（默认：`reply`）。支持按账号/群组/话题覆盖。 +- `channels.telegram.errorCooldownMs`：对同一聊天发送错误回复的最小间隔毫秒数（默认：`60000`）。可防止在故障期间出现错误刷屏。 -- [配置参考 - Telegram](/gateway/configuration-reference#telegram) +- [配置参考 - Telegram](/zh-CN/gateway/configuration-reference#telegram) -Telegram 专属高信号字段： +Telegram 特有的高信号字段： -- 启动/鉴权：`enabled`、`botToken`、`tokenFile`、`accounts.*`（`tokenFile` 必须指向常规文件；不允许符号链接） +- 启动/认证：`enabled`、`botToken`、`tokenFile`、`accounts.*`（`tokenFile` 必须指向常规文件；不接受符号链接） - 访问控制：`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups`、`groups.*.topics.*`、顶层 `bindings[]`（`type: "acp"`） - exec 批准：`execApprovals`、`accounts.*.execApprovals` - 命令/菜单：`commands.native`、`commands.nativeSkills`、`customCommands` @@ -1062,17 +1063,17 @@ Telegram 专属高信号字段： - 流式传输：`streaming`（预览）、`blockStreaming` - 格式化/投递：`textChunkLimit`、`chunkMode`、`linkPreview`、`responsePrefix` - 媒体/网络：`mediaMaxMb`、`timeoutSeconds`、`retry`、`network.autoSelectFamily`、`network.dangerouslyAllowPrivateNetwork`、`proxy` -- webhook：`webhookUrl`、`webhookSecret`、`webhookPath`、`webhookHost` +- Webhook：`webhookUrl`、`webhookSecret`、`webhookPath`、`webhookHost` - 动作/能力：`capabilities.inlineButtons`、`actions.sendMessage|editMessage|deleteMessage|reactions|sticker` -- reactions：`reactionNotifications`、`reactionLevel` +- 反应：`reactionNotifications`、`reactionLevel` - 错误：`errorPolicy`、`errorCooldownMs` - 写入/历史：`configWrites`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` ## 相关内容 -- [配对](/channels/pairing) -- [群组](/channels/groups) -- [安全](/gateway/security) -- [渠道路由](/channels/channel-routing) -- [多智能体路由](/concepts/multi-agent) -- [故障排除](/channels/troubleshooting) +- [配对](/zh-CN/channels/pairing) +- [群组](/zh-CN/channels/groups) +- [安全](/zh-CN/gateway/security) +- [渠道路由](/zh-CN/channels/channel-routing) +- [多智能体路由](/zh-CN/concepts/multi-agent) +- [故障排除](/zh-CN/channels/troubleshooting) diff --git a/docs/zh-CN/help/faq.md b/docs/zh-CN/help/faq.md index b5888c64b..15ba6a742 100644 --- a/docs/zh-CN/help/faq.md +++ b/docs/zh-CN/help/faq.md @@ -1,39 +1,39 @@ --- read_when: - 回答常见的设置、安装、新手引导或运行时支持问题 - - 在进行更深入的调试之前，对用户报告的问题进行初步分诊 -summary: 有关 OpenClaw 设置、配置和使用的常见问题 + - 在进行更深入的调试之前，对用户报告的问题进行初步分类和排查 +summary: 关于 OpenClaw 设置、配置和使用的常见问题 title: 常见问题 x-i18n: - generated_at: "2026-04-19T10:22:57Z" + generated_at: "2026-04-20T04:35:02Z" model: gpt-5.4 provider: openai - source_hash: de5a3b612607fc86c883466ff803b82466415644b7211d1c176f87e07641bb97 + source_hash: 6bdb17fc4d8c61a36f3a9fc3ca4a20f723cfa6c9bbbc92f963d6e313181f3451 source_path: help/faq.md workflow: 15 --- # 常见问题 -针对真实世界部署场景的快速解答，以及更深入的故障排除（本地开发、VPS、多智能体、OAuth/API 密钥、模型故障切换）。如需运行时诊断，请参阅 [故障排除](/zh-CN/gateway/troubleshooting)。如需完整的配置参考，请参阅 [配置](/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. **跟踪最新日志** @@ -58,13 +58,13 @@ x-i18n: openclaw logs --follow ``` - 如果 RPC 不可用，则改用： + 如果 RPC 不可用，则退回到： ```bash tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" ``` - 文件日志与服务日志是分开的；请参阅 [日志](/zh-CN/logging) 和 [故障排除](/zh-CN/gateway/troubleshooting)。 + 文件日志与服务日志是分开的；参见 [Logging](/zh-CN/logging) 和 [故障排除](/zh-CN/gateway/troubleshooting)。 6. **运行 Doctor（修复）** @@ -72,48 +72,47 @@ 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 + 配置路径 ``` - 向正在运行的 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 @@ -123,44 +122,44 @@ 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`。 - 快速调试循环：[如果出了问题，先看最初的六十秒](#如果出了问题先看最初的六十秒)。 - 安装文档：[安装](/zh-CN/install)、[安装器标志](/zh-CN/install/installer)、[更新](/zh-CN/install/updating)。 + 快速调试循环：[如果出了问题，最初的六十秒](#如果出了问题最初的六十秒)。 + 安装文档：[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)、[自动化与任务](/zh-CN/automation)。 + 文档：[Heartbeat](/zh-CN/gateway/heartbeat)、[Automation & Tasks](/zh-CN/automation)。 - 仓库推荐从源码运行并使用新手引导： + 仓库推荐从源码运行，并使用新手引导： ```bash curl -fsSL https://openclaw.ai/install.sh | bash openclaw onboard --install-daemon ``` - 向导也可以自动构建 UI 资源。完成新手引导后，你通常会在 **18789** 端口上运行 Gateway 网关。 + 向导也可以自动构建 UI 资源。完成新手引导后，你通常会在 **18789** 端口运行 Gateway 网关。 - 从源码开始（贡献者 / 开发者）： + 从源码开始（贡献者/开发者）： ```bash git clone https://github.com/openclaw/openclaw.git @@ -171,90 +170,90 @@ x-i18n: openclaw onboard ``` - 如果你还没有全局安装，可以通过 `pnpm openclaw onboard` 运行它。 + 如果你还没有全局安装，请通过 `pnpm openclaw onboard` 运行。 - - 向导会在新手引导结束后立刻用一个干净的（不带令牌的）仪表板 URL 打开你的浏览器，并且也会在摘要中打印该链接。保持这个标签页打开；如果没有自动启动，就在同一台机器上复制 / 粘贴打印出来的 URL。 + + 向导会在新手引导完成后立即用浏览器打开一个干净的（不带 token 的）控制台 URL，并且也会在摘要中打印该链接。请保持该标签页打开；如果没有自动启动，请在同一台机器上复制/粘贴打印出的 URL。 - - **Localhost（同一台机器）：** + + **localhost（同一台机器）：** - 打开 `http://127.0.0.1:18789/`。 - - 如果它要求 shared-secret 认证，请把已配置的令牌或密码粘贴到 Control UI 设置中。 - - 令牌来源：`gateway.auth.token`（或 `OPENCLAW_GATEWAY_TOKEN`）。 + - 如果它要求共享密钥认证，请将已配置的 token 或密码粘贴到 Control UI 设置中。 + - token 来源：`gateway.auth.token`（或 `OPENCLAW_GATEWAY_TOKEN`）。 - 密码来源：`gateway.auth.password`（或 `OPENCLAW_GATEWAY_PASSWORD`）。 - - 如果还没有配置 shared secret，可通过 `openclaw doctor --generate-gateway-token` 生成一个令牌。 + - 如果尚未配置共享密钥，可使用 `openclaw doctor --generate-gateway-token` 生成 token。 **不在 localhost：** - - **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 认证尝试，会在 failed-auth limiter 记录之前先被串行化，因此第二次错误重试可能已经显示 `retry later`。 - - **Tailnet bind**：运行 `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 认证在隧道上仍然适用；如果有提示，请粘贴已配置的令牌或密码。 + - **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 或密码。 - 有关 bind 模式和认证细节，请参阅 [仪表板](/web/dashboard) 和 [Web 界面](/web)。 + 有关绑定模式和认证详情，请参阅 [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` 会通过共享路径工作。 + - 如果某个受支持的原生渠道可以安全推断审批人，那么当 `channels..execApprovals.enabled` 未设置或为 `"auto"` 时，OpenClaw 现在会自动启用“优先私信”的原生审批。 + - 当原生审批卡片/按钮可用时，该原生 UI 是主要路径；只有在工具结果表明聊天审批不可用，或者手动审批是唯一方式时，智能体才应包含手动 `/approve` 命令。 + - 只有当提示还必须转发到其他聊天或专门的运维房间时，才使用 `approvals.exec`。 + - 只有当你明确希望将审批提示回发到原始房间/话题中时，才使用 `channels..execApprovals.target: "channel"` 或 `"both"`。 + - 插件审批则是另外一套：默认使用同一聊天中的 `/approve`，可选 `approvals.plugin` 转发，并且只有部分原生渠道会在此基础上保留插件审批原生处理。 - 简短来说：转发用于路由，原生客户端配置用于更丰富的渠道专属 UX。 - 请参阅 [Exec 审批](/zh-CN/tools/exec-approvals)。 + 简而言之：转发用于路由，原生客户端配置用于更丰富的渠道专属 UX。 + 参见 [Exec Approvals](/zh-CN/tools/exec-approvals)。 - 需要 Node **>= 22**。推荐使用 `pnpm`。不推荐将 Bun 用于 Gateway 网关。 + 需要 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 网关，而你可以在笔记本电脑 / 手机上配对 **节点**， - 用于本地屏幕 / 摄像头 / canvas 或命令执行。请参阅 [Nodes](/zh-CN/nodes)。 + 提示：一个小型 Pi/VPS 可以托管 Gateway 网关，而你可以在笔记本电脑/手机上配对 **nodes**， + 用于本地屏幕/摄像头/canvas 或命令执行。参见 [Nodes](/zh-CN/nodes)。 - - 简短来说：可以运行，但要预期会有一些棘手边缘情况。 + + 简短回答：可以运行，但要预期会遇到一些粗糙边角。 - - 使用 **64 位** 操作系统，并保持 Node >= 22。 - - 优先使用**可修改的（git）安装方式**，这样你可以查看日志并快速更新。 - - 先不要启用渠道 / Skills，然后逐个添加。 - - 如果你遇到奇怪的二进制问题，通常是 **ARM 兼容性** 问题。 + - 使用 **64 位**操作系统，并保持 Node >= 22。 + - 优先选择**可修改的（git）安装**，这样你可以查看日志并快速更新。 + - 先不要启用渠道/Skills，然后逐个添加。 + - 如果你遇到奇怪的二进制问题，通常都是 **ARM 兼容性** 问题。 - 文档：[Linux](/zh-CN/platforms/linux)、[安装](/zh-CN/install)。 + 文档：[Linux](/zh-CN/platforms/linux)、[Install](/zh-CN/install)。 - - 这个界面依赖于 Gateway 网关 可达且已完成认证。TUI 也会在首次 hatch 时自动发送 - “Wake up, my friend!”。如果你看到这行文字却**没有回复**， - 且令牌仍然是 0，那么智能体根本没有运行。 + + 该界面依赖 Gateway 网关可达且已认证。TUI 还会在首次 hatch 时自动发送 + “Wake up, my friend!”。如果你看到这一行但**没有回复**， + 并且 token 仍为 0，说明智能体根本没有运行。 1. 重启 Gateway 网关： @@ -276,63 +275,63 @@ x-i18n: openclaw doctor ``` - 如果 Gateway 网关 是远程的，请确保隧道 / Tailscale 连接已建立，并且 UI - 指向的是正确的 Gateway 网关。请参阅 [远程访问](/zh-CN/gateway/remote)。 + 如果 Gateway 网关是远程的，请确保隧道/Tailscale 连接已建立，并且 UI + 指向了正确的 Gateway 网关。参见 [Remote access](/zh-CN/gateway/remote)。 - - 可以。复制**状态目录**和**工作区**，然后运行一次 Doctor。这样 - 就能让你的机器人“完全保持原样”（memory、会话历史、认证以及渠道 + + 可以。复制**状态目录**和**工作区**，然后运行一次 Doctor。这会 + 让你的机器人“完全保持不变”（记忆、会话历史、认证以及渠道 状态），前提是你复制了**这两个**位置： 1. 在新机器上安装 OpenClaw。 2. 从旧机器复制 `$OPENCLAW_STATE_DIR`（默认：`~/.openclaw`）。 3. 复制你的工作区（默认：`~/.openclaw/workspace`）。 - 4. 运行 `openclaw doctor` 并重启 Gateway 网关 服务。 + 4. 运行 `openclaw doctor` 并重启 Gateway 网关服务。 - 这会保留配置、认证配置文件、WhatsApp 凭据、会话和 memory。如果你处于 - 远程模式，请记住会话存储和工作区归 Gateway 网关 主机所有。 + 这会保留配置、认证配置文件、WhatsApp 凭据、会话和记忆。如果你处于 + 远程模式，请记住会话存储和工作区归 Gateway 网关主机所有。 - **重要：** 如果你只是把工作区提交 / 推送到 GitHub，你备份的将是 - **memory + bootstrap 文件**，但**不包括**会话历史或认证。那些内容位于 + **重要：** 如果你只是将工作区提交/推送到 GitHub，你备份的是 + **记忆 + 引导文件**，但**不会**备份会话历史或认证信息。那些内容保存在 `~/.openclaw/` 下（例如 `~/.openclaw/agents//sessions/`）。 - 相关内容：[迁移](/zh-CN/install/migrating)、[磁盘上的文件位置](#where-things-live-on-disk)、 - [智能体工作区](/zh-CN/concepts/agent-workspace)、[Doctor](/zh-CN/gateway/doctor)、 - [远程模式](/zh-CN/gateway/remote)。 + 相关内容：[Migrating](/zh-CN/install/migrating)、[磁盘上的文件位置](#where-things-live-on-disk)、 + [Agent workspace](/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**，则下一个带日期的 + 最新条目在最上方。如果最上面的部分标记为 **Unreleased**，那么下一个带日期的 部分就是最新发布的版本。条目按 **Highlights**、**Changes** 和 - **Fixes** 分组（需要时还会有 docs / 其他部分）。 + **Fixes** 分组（在需要时还会有 docs/其他部分）。 - 某些 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 上有镜像： + 如果你仍然无法访问该站点，文档在 GitHub 上也有镜像： [https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs) - **Stable** 和 **beta** 是 **npm dist-tags**，不是独立的代码线： + **Stable** 和 **beta** 是 **npm dist-tag**，不是独立的代码线： - `latest` = stable - `beta` = 用于测试的早期构建 - 通常，稳定版本会先发布到 **beta**，然后通过一个明确的 - 提升步骤把同一个版本移动到 `latest`。维护者在需要时也可以 - 直接发布到 `latest`。这就是为什么 beta 和 stable 在提升之后可以 + 通常，一个稳定版本会先发布到 **beta**，然后通过一个显式的 + 提升步骤把同一个版本移动到 `latest`。维护者也可以在必要时 + 直接发布到 `latest`。这就是为什么 beta 和 stable 在提升后可能 指向**同一个版本**。 查看变更内容： @@ -343,10 +342,10 @@ x-i18n: - **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 @@ -356,14 +355,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) - 更多细节：[开发渠道](/zh-CN/install/development-channels) 和 [安装器标志](/zh-CN/install/installer)。 + 更多细节：[Development channels](/zh-CN/install/development-channels) 和 [Installer flags](/zh-CN/install/installer)。 - + 有两种方式： 1. **Dev 渠道（git 检出）：** @@ -372,17 +371,17 @@ x-i18n: openclaw update --channel dev ``` - 这会切换到 `main` 分支，并从源码更新。 + 这会切换到 `main` 分支并从源码更新。 - 2. **可修改安装（从安装站点）：** + 2. **可修改安装（通过安装站点）：** ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - 这样你会得到一个可本地编辑的仓库，然后可以通过 git 更新。 + 这会给你一个可在本地编辑的仓库，然后你可以通过 git 更新。 - 如果你更喜欢手动使用一个干净的克隆，请使用： + 如果你更喜欢手动进行干净克隆，请使用： ```bash git clone https://github.com/openclaw/openclaw.git @@ -391,8 +390,8 @@ x-i18n: pnpm build ``` - 文档：[更新](/cli/update)、[开发渠道](/zh-CN/install/development-channels)、 - [安装](/zh-CN/install)。 + 文档：[Update](/cli/update)、[Development channels](/zh-CN/install/development-channels)、 + [Install](/zh-CN/install)。 @@ -400,15 +399,15 @@ x-i18n: 大致参考： - **安装：** 2-5 分钟 - - **新手引导：** 5-15 分钟，取决于你配置了多少渠道 / 模型 + - **新手引导：** 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 @@ -429,27 +428,27 @@ x-i18n: Windows（PowerShell）等效方式： ```powershell - # install.ps1 目前还没有专门的 -Verbose 标志。 + # install.ps1 目前还没有专用的 -Verbose 标志。 Set-PSDebug -Trace 1 & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard Set-PSDebug -Trace 0 ``` - 更多选项：[安装器标志](/zh-CN/install/installer)。 + 更多选项：[Installer flags](/zh-CN/install/installer)。 - + 两个常见的 Windows 问题： **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 中。 + - 你的 npm 全局 bin 目录不在 PATH 中。 - 检查路径： ```powershell @@ -459,7 +458,7 @@ x-i18n: - 将该目录添加到你的用户 PATH 中（Windows 上不需要 `\bin` 后缀；在大多数系统上它是 `%AppData%\npm`）。 - 更新 PATH 后，关闭并重新打开 PowerShell。 - 如果你想要最顺畅的 Windows 设置体验，请使用 **WSL2**，而不是原生 Windows。 + 如果你想获得最顺畅的 Windows 设置体验，请使用 **WSL2** 而不是原生 Windows。 文档：[Windows](/zh-CN/platforms/windows)。 @@ -469,8 +468,8 @@ x-i18n: 症状： - - `system.run` / `exec` 输出中的中文显示为乱码 - - 同一个命令在另一个终端配置中看起来正常 + - `system.run`/`exec` 输出中的中文显示为乱码 + - 同一条命令在另一个终端配置中显示正常 PowerShell 中的快速解决方法： @@ -481,27 +480,27 @@ 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 ``` - 更多细节：[安装](/zh-CN/install) 和 [安装器标志](/zh-CN/install/installer)。 + 更多细节：[Install](/zh-CN/install) 和 [Installer flags](/zh-CN/install/installer)。 @@ -510,43 +509,43 @@ x-i18n: - Linux 快速路径 + 服务安装：[Linux](/zh-CN/platforms/linux)。 - 完整演练：[入门指南](/zh-CN/start/getting-started)。 - - 安装器 + 更新：[安装与更新](/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 网关 远程访问](/zh-CN/gateway/remote)。 + 远程访问：[Gateway remote](/zh-CN/gateway/remote)。 - - 我们维护了一个**托管中心**，涵盖常见提供商。选择一个并按照指南操作： + + 我们提供了一个**托管中心**，汇总常见提供商。请选择一个并按照指南操作： - - [VPS 托管](/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）从笔记本电脑/手机访问它。你的状态 + 工作区 + 都保存在服务器上，因此请将主机视为事实来源并做好备份。 - 你可以将**节点**（Mac / iOS / Android / 无头设备）配对到该云端 Gateway 网关，以便访问 - 本地屏幕 / 摄像头 / canvas，或在你的笔记本电脑上运行命令，同时保持 - Gateway 网关 在云端。 + 你可以将 **nodes**（Mac/iOS/Android/headless）配对到这个云端 Gateway 网关， + 以访问本地屏幕/摄像头/canvas，或者在保留 + Gateway 网关位于云端的同时，在你的笔记本电脑上运行命令。 - 中心页：[平台](/zh-CN/platforms)。远程访问：[Gateway 网关 远程访问](/zh-CN/gateway/remote)。 - 节点：[Nodes](/zh-CN/nodes)、[Nodes CLI](/cli/nodes)。 + 中心：[Platforms](/zh-CN/platforms)。远程访问：[Gateway remote](/zh-CN/gateway/remote)。 + Nodes：[Nodes](/zh-CN/nodes)、[Nodes CLI](/cli/nodes)。 - + 简短回答：**可以，但不推荐**。更新流程可能会重启 - Gateway 网关（这会断开当前会话），可能需要一个干净的 git 检出，并且 - 可能会要求确认。更安全的做法是：由操作员在 shell 中运行更新。 + Gateway 网关（这会中断当前活跃会话），可能需要一个干净的 git 检出，并且 + 可能会提示确认。更安全的做法是：由操作人员在 shell 中执行更新。 使用 CLI： @@ -558,56 +557,56 @@ x-i18n: openclaw update --no-restart ``` - 如果你必须通过智能体自动化： + 如果你必须从智能体自动化执行： ```bash openclaw update --yes --no-restart openclaw gateway restart ``` - 文档：[更新](/cli/update)、[更新中](/zh-CN/install/updating)。 + 文档：[Update](/cli/update)、[Updating](/zh-CN/install/updating)。 `openclaw onboard` 是推荐的设置路径。在**本地模式**下，它会引导你完成： - - **模型 / 认证设置**（提供商 OAuth、API 密钥、Anthropic setup-token，以及 LM Studio 等本地模型选项） - - **工作区**位置 + bootstrap 文件 - - **Gateway 网关 设置**（bind / port / auth / tailscale） + - **模型/认证设置**（提供商 OAuth、API 密钥、Anthropic setup-token，以及 LM Studio 等本地模型选项） + - **工作区**位置 + 引导文件 + - **Gateway 网关设置**（绑定/端口/认证/tailscale） - **渠道**（WhatsApp、Telegram、Discord、Mattermost、Signal、iMessage，以及像 QQ Bot 这样的内置渠道插件） - - **守护进程安装**（macOS 上为 LaunchAgent；Linux / WSL2 上为 systemd 用户单元） - - **健康检查** 和 **Skills** 选择 + - **守护进程安装**（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 密钥**：普通 Anthropic API 计费 + - **Anthropic API key**：普通的 Anthropic API 计费 - **OpenClaw 中的 Claude CLI / Claude 订阅认证**：Anthropic 员工 - 告诉我们这种用法再次被允许，OpenClaw 正将 `claude -p` - 的使用视为该集成的受认可用法，除非 Anthropic 发布新的 + 告诉我们这种用法再次被允许，OpenClaw 目前将 `claude -p` + 的用法视为该集成下被认可的方式，除非 Anthropic 发布新的 政策 - 对于长期运行的 Gateway 网关 主机，Anthropic API 密钥仍然是更 - 可预测的设置方式。OpenAI Codex OAuth 明确支持用于 OpenClaw 这类外部 + 对于长期运行的 Gateway 网关主机，Anthropic API 密钥仍然是更 + 可预测的配置方式。OpenAI Codex OAuth 明确支持像 OpenClaw 这样的外部 工具。 - OpenClaw 还支持其他托管的订阅式选项，包括 + OpenClaw 还支持其他托管式订阅选项，包括 **Qwen Cloud Coding Plan**、**MiniMax Coding Plan** 和 **Z.AI / GLM Coding Plan**。 文档：[Anthropic](/zh-CN/providers/anthropic)、[OpenAI](/zh-CN/providers/openai)、 [Qwen Cloud](/zh-CN/providers/qwen)、 [MiniMax](/zh-CN/providers/minimax)、[GLM Models](/zh-CN/providers/glm)、 - [本地模型](/zh-CN/gateway/local-models)、[模型](/zh-CN/concepts/models)。 + [Local models](/zh-CN/gateway/local-models)、[Models](/zh-CN/concepts/models)。 @@ -615,8 +614,8 @@ x-i18n: 可以。 Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此 - 除非 Anthropic 发布新的政策，否则 OpenClaw 会将 Claude 订阅认证和 `claude -p` 的使用视为该集成中受认可的 - 用法。如果你想要最可预测的服务端部署方式，请改用 Anthropic API 密钥。 + 除非 Anthropic 发布新的政策，否则 OpenClaw 会将 Claude 订阅认证和 `claude -p` 的使用视为 + 此集成下被认可的方式。如果你想要最可预测的服务器端部署方式，请改用 Anthropic API 密钥。 @@ -624,137 +623,136 @@ x-i18n: 支持。 Anthropic 员工告诉我们，这种用法再次被允许，因此除非 Anthropic 发布新的政策，否则 OpenClaw 会将 - Claude CLI 复用和 `claude -p` 的使用视为该集成中受认可的 - 用法。 + Claude CLI 复用和 `claude -p` 的使用视为此集成下被认可的方式。 - Anthropic setup-token 仍然作为受支持的 OpenClaw 令牌路径可用，但 OpenClaw 现在在可用时更倾向于使用 Claude CLI 复用和 `claude -p`。 + Anthropic setup-token 仍然是受支持的 OpenClaw token 路径，但 OpenClaw 现在在可用时更倾向于使用 Claude CLI 复用和 `claude -p`。 对于生产环境或多用户工作负载，Anthropic API 密钥认证仍然是 - 更安全、更可预测的选择。如果你想了解 OpenClaw 中其他托管的订阅式 + 更安全、更可预测的选择。如果你想在 OpenClaw 中使用其他订阅式托管 选项，请参阅 [OpenAI](/zh-CN/providers/openai)、[Qwen / Model - Cloud](/zh-CN/providers/qwen)、[MiniMax](/zh-CN/providers/minimax) 以及 [GLM + Cloud](/zh-CN/providers/qwen)、[MiniMax](/zh-CN/providers/minimax) 和 [GLM Models](/zh-CN/providers/glm)。 - -这意味着你当前时间窗口内的 **Anthropic 配额 / 速率限制** 已经耗尽。如果你 -使用 **Claude CLI**，请等待时间窗口重置或升级你的套餐。如果你 -使用的是 **Anthropic API 密钥**，请检查 Anthropic Console -中的使用量 / 计费情况，并在需要时提高限制。 + +这表示你当前窗口中的 **Anthropic 配额/速率限制** 已用尽。如果你 +使用 **Claude CLI**，请等待窗口重置或升级你的套餐。如果你 +使用的是 **Anthropic API key**，请检查 Anthropic Console +中的用量/计费情况，并根据需要提高限制。 - 如果消息具体是： - `Extra usage is required for long context requests`，这表示请求正在尝试使用 + 如果消息明确是： + `Extra usage is required for long context requests`，说明请求正在尝试使用 Anthropic 的 1M 上下文 beta（`context1m: true`）。这只有在你的 - 凭据符合长上下文计费资格时才有效（API 密钥计费，或 - 启用了 Extra Usage 的 OpenClaw Claude 登录路径）。 + 凭证具备长上下文计费资格时才可用（API 密钥计费，或启用了 Extra Usage 的 + OpenClaw Claude 登录路径）。 - 提示：设置一个**回退模型**，这样当某个提供商受到速率限制时，OpenClaw 仍然可以继续回复。 - 请参阅 [模型](/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) 和 [模型提供商](/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`。请参阅 [模型提供商](/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 将这两种路径分开处理： + + OpenClaw 将这两条路径分开处理： - - `openai-codex/gpt-5.4` = ChatGPT / Codex OAuth + - `openai-codex/gpt-5.4` = ChatGPT/Codex OAuth - `openai/gpt-5.4` = 直接 OpenAI Platform API - 在 OpenClaw 中，ChatGPT / Codex 登录连接的是 `openai-codex/*` 路径， + 在 OpenClaw 中，ChatGPT/Codex 登录接入的是 `openai-codex/*` 路径， 而不是直接的 `openai/*` 路径。如果你想在 OpenClaw 中使用直接 API 路径，请设置 `OPENAI_API_KEY`（或等效的 OpenAI 提供商配置）。 - 如果你想在 OpenClaw 中使用 ChatGPT / Codex 登录，请使用 `openai-codex/*`。 + 如果你想在 OpenClaw 中使用 ChatGPT/Codex 登录，请使用 `openai-codex/*`。 - - `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 密钥的 `openai/*`。 支持。OpenClaw 完全支持 **OpenAI Code（Codex）订阅 OAuth**。 - OpenAI 明确允许在 OpenClaw 这样的外部工具 / 工作流中 - 使用订阅 OAuth。新手引导也可以为你运行 OAuth 流程。 + OpenAI 明确允许在像 OpenClaw 这样的外部工具/工作流中 + 使用订阅 OAuth。新手引导可以为你运行 OAuth 流程。 - 请参阅 [OAuth](/zh-CN/concepts/oauth)、[模型提供商](/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 令牌存储在 Gateway 网关 主机上的认证配置文件中。详情请参阅：[模型提供商](/zh-CN/concepts/model-providers)。 + 这会将 OAuth token 存储在 Gateway 网关主机上的认证配置文件中。详情参见：[Model providers](/zh-CN/concepts/model-providers)。 - 通常不适合。OpenClaw 需要大上下文 + 强安全性；小模型会截断并泄露内容。如果你必须使用，请在本地运行你能承载的**最大**模型构建（LM Studio），并参阅 [/gateway/local-models](/zh-CN/gateway/local-models)。更小 / 量化后的模型会增加 prompt injection 风险——请参阅 [安全](/zh-CN/gateway/security)。 + 通常不适合。OpenClaw 需要大上下文 + 强安全性；小显存卡上的模型会截断并泄漏。如果你必须这样做，请在本地运行你能使用的**最大**模型构建（LM Studio），并参见 [/gateway/local-models](/zh-CN/gateway/local-models)。更小/量化的模型会增加 prompt injection 风险——参见 [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 远程模式](/zh-CN/platforms/mac/remote)。 + 文档：[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 或其他地方。 + 任何 Mac 都可以。对于 iMessage，请**使用 [BlueBubbles](/zh-CN/channels/bluebubbles)**（推荐）——BlueBubbles 服务器运行在 macOS 上，而 Gateway 网关可以运行在 Linux 或其他地方。 常见部署方式： - - 在 Linux / VPS 上运行 Gateway 网关，并在任意已登录 Messages 的 Mac 上运行 BlueBubbles 服务器。 + - 在 Linux/VPS 上运行 Gateway 网关，并在任何已登录 Messages 的 Mac 上运行 BlueBubbles 服务器。 - 如果你想要最简单的单机部署，也可以把所有内容都运行在这台 Mac 上。 文档：[BlueBubbles](/zh-CN/channels/bluebubbles)、[Nodes](/zh-CN/nodes)、 - [Mac 远程模式](/zh-CN/platforms/mac/remote)。 + [Mac remote mode](/zh-CN/platforms/mac/remote)。 可以。**Mac mini 可以运行 Gateway 网关**，而你的 MacBook Pro 可以作为 - **节点**（配套设备）连接。节点不运行 Gateway 网关——它们提供额外的 - 能力，例如该设备上的屏幕 / 摄像头 / canvas 和 `system.run`。 + **节点**（配套设备）进行连接。节点不运行 Gateway 网关——它们提供额外的 + 能力，例如该设备上的 screen/camera/canvas 和 `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)。 @@ -762,46 +760,45 @@ x-i18n: - **不推荐**使用 Bun。我们观察到运行时 bug，尤其是在 WhatsApp 和 Telegram 上。 - 对于稳定的 Gateway 网关，请使用 **Node**。 + **不推荐**使用 Bun。我们观察到运行时 bug，尤其是在 WhatsApp 和 Telegram 方面。 + 如需稳定的 Gateway 网关，请使用 **Node**。 - 如果你仍然想尝试 Bun，请在非生产环境的 Gateway 网关 上使用， - 并且不要启用 WhatsApp / Telegram。 + 如果你仍想尝试 Bun，请只在非生产 Gateway 网关上进行， + 并且不要启用 WhatsApp/Telegram。 - - `channels.telegram.allowFrom` 是**真人发送者的 Telegram 用户 ID**（数字）。 - 它不是机器人用户名。 + + `channels.telegram.allowFrom` 填的是**人工发送者的 Telegram 用户 ID**（数字）。它不是机器人用户名。 - 新手引导接受 `@username` 输入，并会将其解析为数字 ID，但 OpenClaw 的授权只使用数字 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 账号范围内是全局的。请参阅 [多智能体路由](/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)。 - - 可以。使用多智能体路由：为每个智能体设置各自的默认模型，然后将入站路由（提供商账户或特定 peer）绑定到各自的智能体。示例配置见 [多智能体路由](/zh-CN/concepts/multi-agent)。另请参阅 [模型](/zh-CN/concepts/models) 和 [配置](/zh-CN/gateway/configuration)。 + + 可以。使用多智能体路由：为每个智能体配置各自的默认模型，然后将入站路由（提供商账户或特定 peers）绑定到对应智能体。示例配置见 [Multi-Agent Routing](/zh-CN/concepts/multi-agent)。另请参阅 [Models](/zh-CN/concepts/models) 和 [Configuration](/zh-CN/gateway/configuration)。 - 可以。Homebrew 支持 Linux（Linuxbrew）。快速设置如下： + 可以。Homebrew 支持 Linux（Linuxbrew）。快速设置： ```bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" @@ -810,23 +807,23 @@ x-i18n: brew install ``` - 如果你通过 systemd 运行 OpenClaw，请确保服务的 PATH 包含 `/home/linuxbrew/.linuxbrew/bin`（或你的 brew 前缀），这样在非登录 shell 中也能解析 `brew` 安装的工具。 - 最近的构建也会在 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 安装，没有仓库，最适合“只想直接运行”。 - 更新来自 npm dist-tags。 + + - **可修改的（git）安装：** 完整源码检出，可编辑，最适合贡献者。 + 你可以在本地运行构建，并修改代码/文档。 + - **npm install：** 全局 CLI 安装，不包含仓库，最适合“只想跑起来”。 + 更新来自 npm dist-tag。 - 文档：[入门指南](/zh-CN/start/getting-started)、[更新中](/zh-CN/install/updating)。 + 文档：[入门指南](/zh-CN/start/getting-started)、[Updating](/zh-CN/install/updating)。 - - 可以。安装另一种形式后，运行 Doctor，让 Gateway 网关 服务指向新的入口点。 + + 可以。安装另一种方式后，运行 Doctor，让 Gateway 网关服务指向新的入口点。 这**不会删除你的数据**——它只会更改 OpenClaw 的代码安装方式。你的状态 （`~/.openclaw`）和工作区（`~/.openclaw/workspace`）都会保持不变。 @@ -849,153 +846,153 @@ x-i18n: openclaw gateway restart ``` - Doctor 会检测 Gateway 网关 服务入口点不匹配，并提供重写服务配置以匹配当前安装的选项（在自动化中使用 `--repair`）。 + Doctor 会检测 Gateway 网关服务入口点不匹配的问题，并提供将服务配置重写为与当前安装一致的选项（在自动化中使用 `--repair`）。 - 备份提示：请参阅 [备份策略](#where-things-live-on-disk)。 + 备份提示：参见 [备份策略](#where-things-live-on-disk)。 - - 简短回答：**如果你想要 24/7 的可靠性，就使用 VPS**。如果你想要 - 最低的使用门槛，并且可以接受休眠 / 重启，那就在本地运行。 + + 简短回答：**如果你想要 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 网关 放在专用主机上，再将你的笔记本电脑作为**节点**配对，以提供本地屏幕 / 摄像头 / exec 工具。请参阅 [Nodes](/zh-CN/nodes)。 - 如需安全指南，请阅读 [安全](/zh-CN/gateway/security)。 + 如果你想兼顾两者，请将 Gateway 网关放在专用主机上运行，并将你的笔记本电脑配对为一个**节点**，用于本地 screen/camera/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 安装路径在这些系统上测试最充分。 + 操作系统：使用 **Ubuntu LTS**（或任何现代 Debian/Ubuntu）。Linux 安装路径在这些系统上测试最充分。 - 文档：[Linux](/zh-CN/platforms/linux)、[VPS 托管](/zh-CN/vps)。 + 文档：[Linux](/zh-CN/platforms/linux)、[VPS hosting](/zh-CN/vps)。 - - 可以。将虚拟机视为 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 托管](/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)。 -## 什么是 OpenClaw？ +## OpenClaw 是什么？ - 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 的一个封装”。它是一个**本地优先的控制平面**，让你能够在**自己的硬件上** - 运行一个功能强大的助手，并通过你已经在使用的聊天应用访问它，同时具备 - 有状态会话、memory 和工具——无需把你的工作流控制权交给托管式 + OpenClaw 不只是“Claude 的封装”。它是一个**local-first 控制平面**，让你能够在**自己的硬件上** + 运行一个强大的助手，并通过你已经使用的聊天应用访问它，同时具备 + 有状态会话、记忆和工具——而不必把你的工作流控制权交给托管式 SaaS。 亮点： - - **你的设备，你的数据：** 在任何你想要的地方运行 Gateway 网关（Mac、Linux、VPS），并将 + - **你的设备，你的数据：** 你可以在任何地方运行 Gateway 网关（Mac、Linux、VPS），并让 工作区 + 会话历史保留在本地。 - - **真实渠道，而不是 Web 沙箱：** WhatsApp / Telegram / Slack / Discord / Signal / iMessage 等， - 以及受支持平台上的移动语音和 Canvas。 - - **模型无关：** 使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，并支持按智能体进行路由 - 和故障切换。 - - **纯本地选项：** 运行本地模型，这样**所有数据都可以保留在你的设备上**，如果你愿意的话。 + - **真实渠道，而不是网页沙箱：** WhatsApp/Telegram/Slack/Discord/Signal/iMessage 等， + 并且在受支持的平台上还支持移动语音和 Canvas。 + - **模型无关：** 使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，并支持按智能体路由 + 和故障转移。 + - **纯本地选项：** 如果你愿意，可以运行本地模型，让**所有数据都保留在你的设备上**。 - **多智能体路由：** 按渠道、账户或任务拆分不同智能体，每个都有自己的 工作区和默认设置。 - - **开源且可修改：** 可检查、可扩展、可自托管，不受供应商锁定。 + - **开源且可修改：** 可检查、可扩展、可自托管，无供应商锁定。 - 文档：[Gateway 网关](/zh-CN/gateway)、[渠道](/zh-CN/channels)、[多智能体](/zh-CN/concepts/multi-agent)、 + 文档：[Gateway 网关](/zh-CN/gateway)、[渠道](/zh-CN/channels)、[Multi-agent](/zh-CN/concepts/multi-agent)、 [Memory](/zh-CN/concepts/memory)。 - - 很适合作为第一个项目的事情： + + 很好的起步项目包括： - - 构建一个网站（WordPress、Shopify，或一个简单的静态站点）。 + - 搭建一个网站（WordPress、Shopify 或简单的静态站点）。 - 制作一个移动应用原型（大纲、界面、API 方案）。 - 整理文件和文件夹（清理、命名、打标签）。 - - 连接 Gmail，并自动生成摘要或后续跟进。 + - 连接 Gmail，并自动化摘要或后续跟进。 - 它可以处理大型任务，但最适合的方式是把任务拆分成多个阶段， - 并使用子智能体来并行处理。 + 它可以处理大型任务，但当你把任务拆成多个阶段，并 + 使用子智能体并行工作时，效果通常最好。 - - 日常中最常见的收获通常包括： + + 日常收益通常体现在这些方面： - - **个人简报：** 汇总你关心的收件箱、日历和新闻。 - - **研究与起草：** 快速研究、摘要，以及电子邮件或文档的初稿。 - - **提醒和跟进：** 由 cron 或 Heartbeat 驱动的提醒和清单。 - - **浏览器自动化：** 填表、采集数据，以及重复性的网页任务。 - - **跨设备协作：** 从手机发送任务，让 Gateway 网关 在服务器上执行，然后在聊天中返回结果。 + - **个人简报：** 总结你关心的收件箱、日历和新闻。 + - **研究与起草：** 快速研究、摘要，以及邮件或文档的初稿。 + - **提醒和后续跟进：** 由 cron 或 Heartbeat 驱动的提醒和清单。 + - **浏览器自动化：** 填表、采集数据、重复执行网页任务。 + - **跨设备协同：** 从手机发起任务，让 Gateway 网关在服务器上执行，再把结果返回到聊天中。 - - 可以用于**研究、资格筛选和起草**。它可以扫描网站、建立候选名单、 - 总结潜在客户信息，并撰写外联文案或广告文案草稿。 + + 对于**研究、筛选和起草**，可以。它可以扫描网站、建立候选名单、 + 总结潜在客户，并撰写外联文案或广告文案草稿。 - 对于**外联或广告投放**，请始终保留人工参与。避免垃圾信息，遵守当地法律和 + 对于**外联或广告投放**，请保留人工参与。避免垃圾信息，遵守当地法律和 平台政策，并在发送前审核所有内容。最安全的模式是让 - OpenClaw 起草，再由你审批。 + OpenClaw 起草，由你审批。 - 文档：[安全](/zh-CN/gateway/security)。 + 文档：[Security](/zh-CN/gateway/security)。 - - OpenClaw 是一个**个人助手**和协作协调层，不是 IDE 替代品。对于仓库中的最快直接编码循环， - 请使用 Claude Code 或 Codex。使用 OpenClaw 则是在你 - 需要持久 memory、跨设备访问和工具编排的时候。 + + OpenClaw 是一个**个人助手**和协同层，而不是 IDE 替代品。对于仓库中的 + 最高效直接编码循环，请使用 Claude Code 或 Codex。当你 + 需要持久记忆、跨设备访问和工具编排时，请使用 OpenClaw。 优势： - - **跨会话的持久 memory + 工作区** + - **跨会话的持久记忆 + 工作区** - **多平台访问**（WhatsApp、Telegram、TUI、WebChat） - **工具编排**（浏览器、文件、调度、hooks） - - **始终在线的 Gateway 网关**（运行在 VPS 上，可随时随地交互） - - 用于本地浏览器 / 屏幕 / 摄像头 / exec 的 **节点** + - **始终在线的 Gateway 网关**（可运行在 VPS 上，随时随地交互） + - 用于本地 browser/screen/camera/exec 的 **Nodes** - 展示页：[https://openclaw.ai/showcase](https://openclaw.ai/showcase) + 展示：[https://openclaw.ai/showcase](https://openclaw.ai/showcase) @@ -1003,69 +1000,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 作业：** 隔离作业可以为每个作业设置 `model` 覆盖。 + - **Cron jobs：** 隔离作业可以为每个作业设置 `model` 覆盖。 - **子智能体：** 将任务路由到具有不同默认模型的独立智能体。 - - **按需切换：** 使用 `/model` 可随时切换当前会话的模型。 + - **按需切换：** 使用 `/model` 随时切换当前会话模型。 - 请参阅 [Cron 作业](/zh-CN/automation/cron-jobs)、[多智能体路由](/zh-CN/concepts/multi-agent) 和 [斜杠命令](/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 网关当前正在做什么（以及它是否繁忙）。 - 令牌提示：长任务和子智能体都会消耗令牌。如果你在意成本，请通过 `agents.defaults.subagents.model` 为子智能体设置一个 - 更便宜的模型。 + token 提示：长任务和子智能体都会消耗 token。如果你关心成本，请通过 `agents.defaults.subagents.model` + 为子智能体设置一个更便宜的模型。 - 文档：[子智能体](/zh-CN/tools/subagents)、[后台任务](/zh-CN/automation/tasks)。 + 文档：[Sub-agents](/zh-CN/tools/subagents)、[Background Tasks](/zh-CN/automation/tasks)。 - - 使用线程绑定。你可以将 Discord 线程绑定到子智能体或会话目标，这样该线程中的后续消息就会持续留在已绑定的会话上。 + + 使用线程绑定。你可以把 Discord 线程绑定到某个子智能体或会话目标，这样该线程中的后续消息就会始终停留在这个已绑定的会话上。 基本流程： - - 使用 `sessions_spawn` 并设置 `thread: true` 启动（可选再加 `mode: "session"` 以支持持久后续跟进）。 - - 或者手动使用 `/focus ` 进行绑定。 + - 使用 `sessions_spawn` 并设置 `thread: true` 启动（也可选 `mode: "session"` 以支持持久后续交互）。 + - 或者通过 `/focus ` 手动绑定。 - 使用 `/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`。 - - 在生成时自动绑定：设置 `channels.discord.threadBindings.spawnSubagentSessions: true`。 + - 在 spawn 时自动绑定：设置 `channels.discord.threadBindings.spawnSubagentSessions: true`。 - 文档：[子智能体](/zh-CN/tools/subagents)、[Discord](/zh-CN/channels/discord)、[配置参考](/zh-CN/gateway/configuration-reference)、[斜杠命令](/zh-CN/tools/slash-commands)。 + 文档：[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`），这样直接投递仍然可能成功。 - - 如果既没有绑定路由，也没有可用的存储路由，直接投递可能失败，结果会回退为排队的会话投递，而不是立即发到聊天中。 - - 无效或过期的目标仍可能导致回退到队列，或者最终投递失败。 - - 如果子任务最后一条可见的助手回复恰好是静默令牌 `NO_REPLY` / `no_reply`，或恰好是 `ANNOUNCE_SKIP`，OpenClaw 会有意抑制通知，而不是发布先前已过时的进度。 - - 如果子任务在只进行了工具调用后超时，通知可能会将其折叠为简短的部分进度摘要，而不是重放原始工具输出。 + - 当存在绑定线程或会话路由时，完成模式的子智能体投递会优先使用它。 + - 如果完成来源只携带一个渠道，OpenClaw 会回退到请求方会话中存储的路由（`lastChannel` / `lastTo` / `lastAccountId`），以便直接投递仍然可以成功。 + - 如果既没有绑定路由，也没有可用的存储路由，直接投递可能会失败，结果会回退为排队的会话投递，而不是立即发到聊天中。 + - 无效或陈旧的目标仍然可能导致回退到队列，或最终投递失败。 + - 如果子智能体最后一个可见的助手回复恰好是静默 token `NO_REPLY` / `no_reply`，或恰好是 `ANNOUNCE_SKIP`，OpenClaw 会有意抑制公告，而不是发送更早的陈旧进度。 + - 如果子智能体在仅进行了工具调用之后超时，公告可能会将其压缩为一段简短的部分进度摘要，而不是回放原始工具输出。 调试： @@ -1073,18 +1070,18 @@ x-i18n: openclaw tasks show ``` - 文档：[子智能体](/zh-CN/tools/subagents)、[后台任务](/zh-CN/automation/tasks)、[会话工具](/zh-CN/concepts/session-tool)。 + 文档：[Sub-agents](/zh-CN/tools/subagents)、[Background Tasks](/zh-CN/automation/tasks)、[Session Tools](/zh-CN/concepts/session-tool)。 - - Cron 在 Gateway 网关 进程内部运行。如果 Gateway 网关 没有持续运行， + + Cron 在 Gateway 网关进程内运行。如果 Gateway 网关没有持续运行， 定时作业就不会执行。 检查清单： - - 确认 cron 已启用（`cron.enabled`），且未设置 `OPENCLAW_SKIP_CRON`。 - - 检查 Gateway 网关 是否在 24/7 持续运行（没有休眠 / 重启）。 + - 确认 cron 已启用（`cron.enabled`），并且没有设置 `OPENCLAW_SKIP_CRON`。 + - 检查 Gateway 网关是否在 24/7 持续运行（没有睡眠/重启）。 - 验证作业的时区设置（`--tz` 与主机时区）。 调试： @@ -1094,22 +1091,22 @@ x-i18n: openclaw cron runs --id --limit 50 ``` - 文档：[Cron 作业](/zh-CN/automation/cron-jobs)、[自动化与任务](/zh-CN/automation)。 + 文档：[Cron jobs](/zh-CN/automation/cron-jobs)、[Automation & Tasks](/zh-CN/automation)。 先检查投递模式： - - `--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 作业，运行器负责最终投递。系统期望 - 智能体返回一个纯文本摘要，供运行器发送。`--no-deliver` 会将 - 该结果保留在内部；它并不会改为让智能体直接通过 - message 工具发送。 + 对于隔离的 cron 作业，最终投递由运行器负责。期望智能体 + 返回一段纯文本摘要，供运行器发送。`--no-deliver` 会让 + 该结果保持内部状态；它不会让智能体改为通过 + message 工具直接发送。 调试： @@ -1118,26 +1115,26 @@ x-i18n: openclaw tasks show ``` - 文档：[Cron 作业](/zh-CN/automation/cron-jobs)、[后台任务](/zh-CN/automation/tasks)。 + 文档：[Cron jobs](/zh-CN/automation/cron-jobs)、[Background Tasks](/zh-CN/automation/tasks)。 - + 这通常是实时模型切换路径，而不是重复调度。 - 隔离的 cron 在当前运行抛出 `LiveSessionModelSwitchError` 时， - 可以持久化运行时模型切换并重试。重试会保留已切换的 - provider / model；如果切换还携带了新的认证配置覆盖，cron - 也会在重试前将其持久化。 + 隔离的 cron 在活动运行抛出 `LiveSessionModelSwitchError` 时， + 可以持久化一次运行时模型切换并重试。重试会保留已切换的 + provider/model；如果切换还携带了新的认证配置文件覆盖，cron + 也会在重试前一并持久化。 相关选择规则： - - 如果适用，Gmail hook 模型覆盖优先级最高。 + - 当适用时，Gmail hook 模型覆盖优先级最高。 - 然后是每个作业的 `model`。 - 然后是任何已存储的 cron 会话模型覆盖。 - - 最后才是常规的智能体 / 默认模型选择。 + - 最后是常规的智能体/默认模型选择。 - 重试循环是有上限的。在初始尝试加上 2 次切换重试之后， + 重试循环是有边界的。初始尝试加上 2 次切换重试之后， cron 会中止，而不是无限循环。 调试： @@ -1147,12 +1144,12 @@ x-i18n: openclaw tasks show ``` - 文档：[Cron 作业](/zh-CN/automation/cron-jobs)、[cron CLI](/cli/cron)。 + 文档：[Cron jobs](/zh-CN/automation/cron-jobs)、[cron CLI](/cli/cron)。 - 使用原生 `openclaw skills` 命令，或将 Skills 放入你的工作区。macOS 的 Skills UI 在 Linux 上不可用。 + 使用原生 `openclaw skills` 命令，或直接把 Skills 放进你的工作区。macOS 的 Skills UI 在 Linux 上不可用。 可在 [https://clawhub.ai](https://clawhub.ai) 浏览 Skills。 ```bash @@ -1166,42 +1163,41 @@ x-i18n: openclaw skills check ``` - 原生 `openclaw skills install` 会写入当前工作区的 `skills/` - 目录。只有当你想发布或同步你自己的 Skills 时，才需要单独安装 `clawhub` CLI。 - 对于跨智能体共享安装，请将 skill 放在 - `~/.openclaw/skills` 下；如果你想限制哪些智能体可以看到它， - 请使用 `agents.defaults.skills` 或 - `agents.list[].skills`。 + 原生 `openclaw skills install` 会写入当前活动工作区的 `skills/` + 目录。只有当你想发布或 + 同步你自己的 Skills 时，才需要单独安装 `clawhub` CLI。对于跨智能体共享安装，请把 skill 放到 + `~/.openclaw/skills` 下，并使用 `agents.defaults.skills` 或 + `agents.list[].skills` 来缩小可见范围（如果需要）。 - 可以。使用 Gateway 网关 调度器： + 可以。使用 Gateway 网关调度器： - - **Cron 作业**：用于定时或重复任务（重启后仍会保留）。 - - **Heartbeat**：用于“主会话”的定期检查。 - - **隔离作业**：用于会发布摘要或投递到聊天中的自治智能体。 + - **Cron jobs**：用于定时或周期性任务（重启后仍会保留）。 + - **Heartbeat**：用于“主会话”的周期性检查。 + - **隔离作业**：用于自主智能体，可发布摘要或投递到聊天。 - 文档：[Cron 作业](/zh-CN/automation/cron-jobs)、[自动化与任务](/zh-CN/automation)、 + 文档：[Cron jobs](/zh-CN/automation/cron-jobs)、[Automation & Tasks](/zh-CN/automation)、 [Heartbeat](/zh-CN/gateway/heartbeat)。 - 不能直接运行。macOS Skills 受 `metadata.openclaw.os` 和所需二进制文件控制，而且只有当它们在 **Gateway 网关 主机**上符合条件时，Skills 才会出现在系统提示中。在 Linux 上，`darwin` 专属的 Skills（如 `apple-notes`、`apple-reminders`、`things-mac`）不会加载，除非你覆盖这些限制条件。 + 不能直接运行。macOS Skills 受 `metadata.openclaw.os` 和所需二进制文件的限制，且只有在 **Gateway 网关主机** 上满足条件时，这些 Skills 才会出现在 system prompt 中。在 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 会正常加载。 + **方案 A - 在 Mac 上运行 Gateway 网关（最简单）。** + 在 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” 会将该命令加入允许列表。 + **方案 B - 使用 macOS 节点（无需 SSH）。** + 在 Linux 上运行 Gateway 网关，配对一个 macOS 节点（菜单栏应用），并在 Mac 上将 **Node Run Commands** 设置为 “Always Ask” 或 “Always Allow”。当节点上存在所需二进制文件时，OpenClaw 可以将仅限 macOS 的 Skills 视为可用。智能体会通过 `nodes` 工具运行这些 Skills。如果你选择 “Always Ask”，在提示中批准 “Always Allow” 会将该命令加入允许列表。 - **选项 C - 通过 SSH 代理 macOS 二进制文件（高级）。** - 将 Gateway 网关 保持运行在 Linux 上，但让所需的 CLI 二进制文件解析为在 Mac 上运行的 SSH 包装器。然后覆盖该 skill，使其允许 Linux，从而保持其符合条件。 + **方案 C - 通过 SSH 代理 macOS 二进制文件（高级）。** + 让 Gateway 网关继续运行在 Linux 上，但将所需 CLI 二进制文件解析为在 Mac 上执行的 SSH 包装器。然后覆盖该 skill，使其允许 Linux，从而保持可用。 - 1. 为该二进制文件创建一个 SSH 包装器（示例：Apple Notes 的 `memo`）： + 1. 为该二进制文件创建 SSH 包装器（示例：Apple Notes 的 `memo`）： ```bash #!/usr/bin/env bash @@ -1220,24 +1216,24 @@ x-i18n: --- ``` - 4. 启动一个新会话，以便刷新 Skills 快照。 + 4. 启动一个新会话，以刷新 Skills 快照。 目前没有内置。 - 可选方式： + 可选方案： - - **自定义 skill / 插件：** 最适合可靠的 API 访问（Notion / HeyGen 都有 API）。 - - **浏览器自动化：** 无需写代码即可使用，但速度较慢，也更脆弱。 + - **自定义 skill / 插件：** 最适合稳定的 API 访问（Notion/HeyGen 都有 API）。 + - **浏览器自动化：** 无需写代码即可使用，但速度更慢，也更脆弱。 如果你想为每个客户保留上下文（代理机构工作流），一种简单模式是： - 每个客户一个 Notion 页面（上下文 + 偏好 + 当前工作）。 - - 在会话开始时让智能体获取该页面。 + - 让智能体在会话开始时获取该页面。 - 如果你想要原生集成，请提交功能请求，或构建一个 + 如果你想要原生集成，可以提交功能请求，或构建一个 面向这些 API 的 skill。 安装 Skills： @@ -1247,130 +1243,131 @@ 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` 当前的限制： + 当前 `existing-session` / `user` 的限制： - - 操作是基于 ref 驱动的，而不是基于 CSS 选择器驱动的 - - 上传需要 `ref` / `inputRef`，而且目前一次只支持一个文件 + - 操作基于 ref，而不是基于 CSS 选择器 + - 上传需要 `ref` / `inputRef`，且目前一次只支持一个文件 - `responsebody`、PDF 导出、下载拦截和批量操作仍然需要托管浏览器或原始 CDP 配置文件 -## 沙箱隔离和 memory +## 沙箱隔离和记忆 - - 有。请参阅 [沙箱隔离](/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` 让缓存得以保留。 + - 持久化 `/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) - 关键配置参考：[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) 和 [沙箱 vs 工具策略 vs 提权](/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 的 memory 就是智能体工作区中的 Markdown 文件： + + OpenClaw 的记忆本质上就是智能体工作区中的 Markdown 文件： - - `memory/YYYY-MM-DD.md` 中的每日日志 - - `MEMORY.md` 中整理过的长期笔记（仅主 / 私密会话） + - `memory/YYYY-MM-DD.md` 中的每日笔记 + - `MEMORY.md` 中整理过的长期笔记（仅主会话/私密会话） - OpenClaw 还会运行一个**静默的预压缩 memory flush**，提醒模型 - 在自动压缩前写入持久笔记。这只会在工作区 - 可写时运行（只读沙箱会跳过）。请参阅 [Memory](/zh-CN/concepts/memory)。 + OpenClaw 还会运行一个**静默的预压缩记忆刷新**，以提醒模型 + 在自动压缩之前写入持久笔记。只有在工作区 + 可写时才会运行这一过程（只读沙箱会跳过）。参见 [Memory](/zh-CN/concepts/memory)。 - - 让机器人**把这个事实写入 memory**。长期笔记应写入 `MEMORY.md`， - 短期上下文则写入 `memory/YYYY-MM-DD.md`。 + + 让机器人**把这个事实写入记忆**。长期笔记应写入 `MEMORY.md`， + 短期上下文则放入 `memory/YYYY-MM-DD.md`。 - 这仍然是我们正在改进的领域。提醒模型存储记忆会有帮助； - 它会知道该怎么做。如果它还是总忘记，请确认 Gateway 网关 每次运行时都在使用同一个 - 工作区。 + 这仍然是我们正在持续改进的领域。提醒模型存储记忆会有帮助； + 它知道该怎么做。如果它仍然总是遗忘，请确认 Gateway 网关每次运行时 + 使用的是同一个工作区。 - 文档：[Memory](/zh-CN/concepts/memory)、[智能体工作区](/zh-CN/concepts/agent-workspace)。 + 文档：[Memory](/zh-CN/concepts/memory)、[Agent workspace](/zh-CN/concepts/agent-workspace)。 - - memory 文件保存在磁盘上，除非你删除它们，否则会一直存在。限制来自你的 - 存储空间，而不是模型。**会话上下文**仍然受模型 - 上下文窗口限制，因此长对话可能会被压缩或截断。这就是为什么会有 - memory 搜索——它只会将相关部分重新拉回上下文。 + + 记忆文件保存在磁盘上，除非你删除它们，否则会一直存在。限制来自你的 + 存储空间，而不是模型。**会话上下文** + 仍受模型上下文窗口限制，因此长对话可能会被压缩或截断。这就是为什么 + 需要记忆搜索——它只会将相关部分重新拉回上下文。 - 文档：[Memory](/zh-CN/concepts/memory)、[上下文](/zh-CN/concepts/context)。 + 文档：[Memory](/zh-CN/concepts/memory)、[Context](/zh-CN/concepts/context)。 - - 只有在你使用 **OpenAI embeddings** 时才需要。Codex OAuth 仅覆盖聊天 / 补全， - **不**授予 embeddings 访问权限，因此**使用 Codex 登录（OAuth 或 - Codex CLI 登录）** 并不能帮助启用语义 memory 搜索。OpenAI embeddings + + 只有当你使用 **OpenAI embeddings** 时才需要。Codex OAuth 仅涵盖聊天/补全， + **不会**授予 embeddings 访问权限，因此**使用 Codex 登录（OAuth 或 + Codex CLI 登录）** 对语义记忆搜索没有帮助。OpenAI embeddings 仍然需要真实的 API 密钥（`OPENAI_API_KEY` 或 `models.providers.openai.apiKey`）。 - 如果你没有显式设置提供商，OpenClaw 会在它 - 能解析到 API 密钥时自动选择一个提供商（认证配置文件、`models.providers.*.apiKey` 或环境变量）。 - 如果能解析到 OpenAI 密钥，它会优先选择 OpenAI；否则如果能解析到 Gemini 密钥， - 则选择 Gemini；然后是 Voyage，再然后是 Mistral。如果没有可用的远程密钥， - memory 搜索会保持禁用状态，直到你完成配置。如果你已配置且存在本地模型路径，OpenClaw + 如果你没有显式设置提供商，OpenClaw 会在能够解析 API 密钥时 + 自动选择提供商（认证配置文件、`models.providers.*.apiKey` 或环境变量）。 + 如果能够解析到 OpenAI 密钥，它会优先选择 OpenAI；否则如果能解析到 Gemini 密钥， + 就选择 Gemini；再之后是 Voyage，然后是 Mistral。如果没有可用的远程密钥，记忆 + 搜索会保持禁用状态，直到你完成配置。如果你配置了本地模型路径 + 且该路径存在，OpenClaw 会优先选择 `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** embeddings - 模型——设置细节请参阅 [Memory](/zh-CN/concepts/memory)。 + `memorySearch.remote.apiKey`）。我们支持 **OpenAI、Gemini、Voyage、Mistral、Ollama 或 local** embedding + 模型——有关设置详情，请参见 [Memory](/zh-CN/concepts/memory)。 @@ -1379,51 +1376,51 @@ x-i18n: - 不会——**OpenClaw 的状态是本地的**，但**外部服务仍然能看到你发送给它们的内容**。 + 不会——**OpenClaw 的状态在本地**，但**外部服务仍然会看到你发给它们的内容**。 - - **默认保存在本地：** 会话、memory 文件、配置和工作区都位于 Gateway 网关 主机上 + - **默认本地：** 会话、记忆文件、配置和工作区都位于 Gateway 网关主机上 （`~/.openclaw` + 你的工作区目录）。 - - **因需求而远程：** 你发送给模型提供商（Anthropic / OpenAI / 等）的消息会发送到 - 它们的 API，而聊天平台（WhatsApp / Telegram / Slack / 等）会将消息数据存储在它们的 - 服务器上。 - - **由你控制数据范围：** 使用本地模型可以让提示保留在你的机器上，但渠道 + - **出于必要而远程：** 你发送给模型提供商（Anthropic/OpenAI 等）的消息会发送到 + 它们的 API，而聊天平台（WhatsApp/Telegram/Slack 等）会在它们的 + 服务器上存储消息数据。 + - **足迹由你控制：** 使用本地模型可以让提示内容保留在你的机器上，但渠道 流量仍然会经过该渠道的服务器。 - 相关内容：[智能体工作区](/zh-CN/concepts/agent-workspace)、[Memory](/zh-CN/concepts/memory)。 + 相关内容：[Agent workspace](/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 导入（首次使用时复制到认证配置文件中） | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | 认证配置文件（OAuth、API 密钥，以及可选的 `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 + sessions） | + | `$OPENCLAW_STATE_DIR/agents/` | 每个智能体的状态（agentDir + 会话） | | `$OPENCLAW_STATE_DIR/agents//sessions/` | 对话历史与状态（按智能体） | | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | 会话元数据（按智能体） | - 旧版单智能体路径：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移）。 + 遗留的单智能体路径：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移）。 - 你的**工作区**（AGENTS.md、memory 文件、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`）， + - **工作区（每个智能体）**：`AGENTS.md`、`SOUL.md`、`IDENTITY.md`、`USER.md`、 + `MEMORY.md`（如果没有 `MEMORY.md`，则使用遗留回退 `memory.md`）， `memory/YYYY-MM-DD.md`，以及可选的 `HEARTBEAT.md`。 - - **状态目录（`~/.openclaw`）：** 配置、渠道 / 提供商状态、认证配置文件、会话、日志， + - **状态目录（`~/.openclaw`）**：配置、渠道/提供商状态、认证配置文件、会话、日志， 以及共享 Skills（`~/.openclaw/skills`）。 - 默认工作区为 `~/.openclaw/workspace`，可通过以下方式配置： + 默认工作区是 `~/.openclaw/workspace`，可通过以下方式配置： ```json5 { @@ -1431,42 +1428,42 @@ x-i18n: } ``` - 如果机器人在重启后“遗忘”了内容，请确认 Gateway 网关 每次启动时都在使用同一个 - 工作区（并记住：远程模式使用的是**Gateway 网关 主机** - 的工作区，而不是你的本地笔记本电脑）。 + 如果机器人在重启后“遗忘”了内容，请确认 Gateway 网关每次启动时 + 使用的是同一个工作区（并记住：远程模式使用的是**Gateway 网关主机的** + 工作区，而不是你的本地笔记本电脑）。 - 提示：如果你希望某种行为或偏好长期保留，请让机器人**将其写入 - AGENTS.md 或 MEMORY.md**，而不是依赖聊天历史。 + 提示：如果你想保留某种持久行为或偏好，请让机器人**把它写入 + AGENTS.md 或 MEMORY.md**，而不要依赖聊天历史。 - 请参阅 [智能体工作区](/zh-CN/concepts/agent-workspace) 和 [Memory](/zh-CN/concepts/memory)。 + 参见 [Agent workspace](/zh-CN/concepts/agent-workspace) 和 [Memory](/zh-CN/concepts/memory)。 - 将你的**智能体工作区**放在一个**私有** git 仓库中，并备份到某个 - 私有位置（例如 GitHub 私有仓库）。这样可以保存 memory + AGENTS / SOUL / USER - 文件，并让你之后能够恢复助手的“思维”。 + 把你的**智能体工作区**放进一个**私有** git 仓库，并将其备份到某个 + 私密位置（例如 GitHub 私有仓库）。这样可以保存记忆 + AGENTS/SOUL/USER + 文件，并让你之后恢复助手的“思维”。 - **不要**提交 `~/.openclaw` 下的任何内容（凭据、会话、令牌或加密 secret 负载）。 + **不要**提交 `~/.openclaw` 下的任何内容（凭证、会话、token 或加密的 secret 负载）。 如果你需要完整恢复，请分别备份工作区和状态目录 （参见上面的迁移问题）。 - 文档：[智能体工作区](/zh-CN/concepts/agent-workspace)。 + 文档：[Agent workspace](/zh-CN/concepts/agent-workspace)。 - 请参阅专门指南：[卸载](/zh-CN/install/uninstall)。 + 请参阅专门指南：[Uninstall](/zh-CN/install/uninstall)。 - 可以。工作区是**默认 cwd** 和 memory 锚点，而不是硬性沙箱。 - 相对路径会在工作区内解析，但绝对路径可以访问主机上的其他 + 可以。工作区是**默认 cwd** 和记忆锚点，而不是硬性沙箱。 + 相对路径会解析到工作区内，但绝对路径仍然可以访问主机上的其他 位置，除非启用了沙箱隔离。如果你需要隔离，请使用 - [`agents.defaults.sandbox`](/zh-CN/gateway/sandboxing) 或按智能体设置沙箱。如果你 - 希望某个仓库成为默认工作目录，请将该智能体的 - `workspace` 指向仓库根目录。OpenClaw 仓库只是源代码；除非你明确希望智能体在其中工作，否则请将 - 工作区与其分开。 + [`agents.defaults.sandbox`](/zh-CN/gateway/sandboxing) 或每个智能体的沙箱设置。如果你 + 想让某个仓库成为默认工作目录，请将该智能体的 + `workspace` 指向仓库根目录。OpenClaw 仓库本身只是源码；除非你明确希望智能体在其中工作，否则请保持 + 工作区与其分离。 示例（将仓库作为默认 cwd）： @@ -1483,14 +1480,14 @@ x-i18n: - 会话状态归**Gateway 网关 主机**所有。如果你处于远程模式，你关心的会话存储位于远程机器上，而不是你的本地笔记本电脑。请参阅 [会话管理](/zh-CN/concepts/session)。 + 会话状态归**Gateway 网关主机**所有。如果你处于远程模式，那么你关心的会话存储位于远程机器上，而不是你的本地笔记本电脑。参见 [会话管理](/zh-CN/concepts/session)。 ## 配置基础 - + OpenClaw 会从 `$OPENCLAW_CONFIG_PATH` 读取可选的 **JSON5** 配置（默认：`~/.openclaw/openclaw.json`）： ``` @@ -1501,11 +1498,11 @@ x-i18n: - - 非 loopback bind **需要有效的 gateway 认证路径**。实际来说，这意味着： + + 非 loopback 绑定**需要有效的 Gateway 网关认证路径**。实际来说，这意味着： - - shared-secret 认证：令牌或密码 - - 位于正确配置的非 loopback 身份感知反向代理之后的 `gateway.auth.mode: "trusted-proxy"` + - 共享密钥认证：token 或密码 + - `gateway.auth.mode: "trusted-proxy"`，并位于正确配置的非 loopback 身份感知反向代理之后 ```json5 { @@ -1521,26 +1518,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 显式配置但无法解析，解析会以默认拒绝方式失败（不会用远程回退来掩盖）。 - - shared-secret 的 Control UI 部署通过 `connect.params.auth.token` 或 `connect.params.auth.password` 进行认证（存储在 app / UI 设置中）。像 Tailscale Serve 或 `trusted-proxy` 这样的带身份模式则改用请求头。避免将 shared secret 放在 URL 中。 - - 使用 `gateway.auth.mode: "trusted-proxy"` 时，同主机上的 loopback 反向代理**仍然不能**满足 trusted-proxy 认证。trusted proxy 必须是一个已配置的非 loopback 来源。 + - 如果 `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 来源。 - - OpenClaw 默认会强制执行 gateway 认证，包括 loopback。在正常默认路径下，这意味着令牌认证：如果没有显式配置认证路径，gateway 启动时会解析为令牌模式并自动生成一个令牌，保存到 `gateway.auth.token`，因此**本地 WS 客户端也必须认证**。这样可以阻止其他本地进程调用 Gateway 网关。 + + OpenClaw 默认强制执行 Gateway 网关认证，包括 loopback。在常规默认路径下，这意味着 token 认证：如果没有配置显式认证路径，Gateway 网关启动时会解析为 token 模式，并自动生成一个 token，保存到 `gateway.auth.token`，因此**本地 WS 客户端也必须认证**。这样可以阻止其他本地进程调用 Gateway 网关。 - 如果你更喜欢其他认证路径，可以显式选择密码模式（或者，对于非 loopback 的身份感知反向代理，可选择 `trusted-proxy`）。如果你**确实**想开放 loopback，请在配置中显式设置 `gateway.auth.mode: "none"`。Doctor 可以随时为你生成令牌：`openclaw doctor --generate-gateway-token`。 + 如果你更喜欢其他认证方式，可以显式选择密码模式（或者对于非 loopback 身份感知反向代理，选择 `trusted-proxy`）。如果你**确实**想开放 loopback，请在配置中显式设置 `gateway.auth.mode: "none"`。Doctor 可以随时为你生成 token：`openclaw doctor --generate-gateway-token`。 - - Gateway 网关 会监视配置并支持热重载： + + Gateway 网关会监视配置并支持热重载： - - `gateway.reload.mode: "hybrid"`（默认）：安全变更热应用，关键变更则重启 + - `gateway.reload.mode: "hybrid"`（默认）：安全更改热应用，关键更改则重启 - 也支持 `hot`、`restart`、`off` @@ -1558,21 +1555,21 @@ x-i18n: } ``` - - `off`：隐藏标语文本，但保留横幅标题 / 版本行。 + - `off`：隐藏标语文本，但保留横幅标题/版本行。 - `default`：每次都使用 `All your chats, one OpenClaw.`。 - - `random`：轮换有趣 / 季节性标语（默认行为）。 - - 如果你希望完全不显示横幅，请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 + - `random`：轮换显示有趣/季节性的标语（默认行为）。 + - 如果你想完全不显示横幅，请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 - + `web_fetch` 无需 API 密钥即可使用。`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 密钥。 + - Ollama Web 搜索不需要密钥，但它会使用你配置的 Ollama 主机，并要求执行 `ollama signin`。 + - DuckDuckGo 不需要密钥，但它是一个非官方的基于 HTML 的集成。 + - SearXNG 不需要密钥/可自托管；请配置 `SEARXNG_BASE_URL` 或 `plugins.entries.searxng.config.webSearch.baseUrl`。 **推荐方式：** 运行 `openclaw configure --section web` 并选择一个提供商。 环境变量替代方案： @@ -1617,54 +1614,54 @@ x-i18n: } ``` - 提供商专属的 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 抓取回退配置位于 `plugins.entries.firecrawl.config.webFetch.*` 下。 说明： - - 如果你使用允许列表，请添加 `web_search` / `web_fetch` / `x_search` 或 `group:web`。 - - `web_fetch` 默认启用（除非显式禁用）。 - - 如果省略 `tools.web.fetch.provider`，OpenClaw 会从可用凭据中自动检测第一个已就绪的抓取回退提供商。目前内置提供商是 Firecrawl。 + - 如果你使用 allowlist，请加入 `web_search`/`web_fetch`/`x_search` 或 `group:web`。 + - `web_fetch` 默认启用（除非被显式禁用）。 + - 如果省略 `tools.web.fetch.provider`，OpenClaw 会从可用凭证中自动检测第一个可用的抓取回退提供商。目前内置提供商是 Firecrawl。 - 守护进程会从 `~/.openclaw/.env`（或服务环境）读取环境变量。 - 文档：[Web 工具](/zh-CN/tools/web)。 + 文档：[Web tools](/zh-CN/tools/web)。 - + `config.apply` 会替换**整个配置**。如果你发送的是部分对象，其他所有内容 都会被移除。 - 恢复方法： + 恢复方式： - 从备份恢复（git 或复制过的 `~/.openclaw/openclaw.json`）。 - - 如果没有备份，请重新运行 `openclaw doctor` 并重新配置渠道 / 模型。 - - 如果这是意料之外的行为，请提交 bug，并附上你最近可用的配置或任何备份。 - - 本地编码智能体通常可以根据日志或历史记录重建一个可工作的配置。 + - 如果没有备份，请重新运行 `openclaw doctor`，并重新配置渠道/模型。 + - 如果这不符合预期，请提交 bug，并附上你最后一次可用的配置或任何备份。 + - 本地编码智能体通常可以根据日志或历史重建一个可工作的配置。 - 避免方法： + 避免方式： - - 对于小改动，请使用 `openclaw config set`。 - - 对于交互式编辑，请使用 `openclaw configure`。 - - 当你不确定准确路径或字段结构时，先使用 `config.schema.lookup`；它会返回一个浅层 schema 节点以及其直接子项摘要，便于逐步深入。 - - 对于部分 RPC 编辑，请使用 `config.patch`；只在需要完整替换配置时才使用 `config.apply`。 - - 如果你在智能体运行中使用仅限 owner 的 `gateway` 工具，它仍然会拒绝对 `tools.exec.ask` / `tools.exec.security` 的写入（包括会被规范化到同一受保护 exec 路径的旧版 `tools.bash.*` 别名）。 + - 小改动请使用 `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.*` 别名）。 - 文档：[配置](/cli/config)、[配置向导](/cli/configure)、[Doctor](/zh-CN/gateway/doctor)。 + 文档：[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`）。 + - **智能体（工作器）：** 用于特殊角色的独立“大脑”/工作区（例如 “Hetzner 运维”、“个人数据”）。 + - **子智能体：** 当你需要并行处理时，从主智能体启动后台工作。 + - **TUI：** 连接到 Gateway 网关并切换智能体/会话。 - 文档：[Nodes](/zh-CN/nodes)、[远程访问](/zh-CN/gateway/remote)、[多智能体路由](/zh-CN/concepts/multi-agent)、[子智能体](/zh-CN/tools/subagents)、[TUI](/web/tui)。 + 文档：[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)。 @@ -1682,126 +1679,124 @@ 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 网关 运行智能体， + + Telegram 消息由**Gateway 网关**处理。Gateway 网关运行智能体， 只有在需要节点工具时，才会通过 **Gateway WebSocket** 调用节点： Telegram → Gateway 网关 → 智能体 → `node.*` → 节点 → Gateway 网关 → Telegram - 节点不会看到入站提供商流量；它们只会接收节点 RPC 调用。 + 节点看不到入站提供商流量；它们只会接收节点 RPC 调用。 - - 简短回答：**把你的电脑配对为一个节点**。Gateway 网关 运行在别处，但它可以 - 通过 Gateway WebSocket 调用你本地机器上的 `node.*` 工具（屏幕、摄像头、系统）。 + + 简短回答：**将你的电脑配对为一个节点**。Gateway 网关运行在别处，但它可以 + 通过 Gateway WebSocket 调用你本地机器上的 `node.*` 工具（screen、camera、system）。 - 典型部署： + 典型部署方式： - 1. 在始终在线的主机（VPS / 家庭服务器）上运行 Gateway 网关。 - 2. 将 Gateway 网关 主机和你的电脑加入同一个 tailnet。 - 3. 确保 Gateway WS 可访问（tailnet bind 或 SSH 隧道）。 + 1. 在始终在线的主机（VPS/家用服务器）上运行 Gateway 网关。 + 2. 将 Gateway 网关主机和你的电脑放到同一个 tailnet 中。 + 3. 确保 Gateway 网关 WS 可达（tailnet 绑定或 SSH 隧道）。 4. 在本地打开 macOS 应用，并以**通过 SSH 远程连接**模式（或直接 tailnet） 连接，这样它就可以注册为一个节点。 - 5. 在 Gateway 网关 上批准该节点： + 5. 在 Gateway 网关上批准该节点： ```bash openclaw devices list openclaw devices approve ``` - 不需要额外的 TCP bridge；节点通过 Gateway WebSocket 连接。 + 不需要单独的 TCP bridge；节点通过 Gateway WebSocket 连接。 - 安全提醒：配对 macOS 节点意味着允许在该机器上执行 `system.run`。只 - 配对你信任的设备，并查看 [安全](/zh-CN/gateway/security)。 + 安全提醒：配对一个 macOS 节点意味着允许在那台机器上执行 `system.run`。只 + 配对你信任的设备，并阅读 [Security](/zh-CN/gateway/security)。 - 文档：[Nodes](/zh-CN/nodes)、[Gateway 网关 协议](/zh-CN/gateway/protocol)、[macOS 远程模式](/zh-CN/platforms/mac/remote)、[安全](/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)。 先检查基础项： - - Gateway 网关 正在运行：`openclaw gateway status` - - Gateway 网关 健康状态：`openclaw status` + - Gateway 网关是否在运行：`openclaw gateway status` + - Gateway 网关健康状态：`openclaw status` - 渠道健康状态：`openclaw channels status` 然后验证认证和路由： - 如果你使用 Tailscale Serve，请确保 `gateway.auth.allowTailscale` 设置正确。 - - 如果你通过 SSH 隧道连接，请确认本地隧道已建立并指向正确端口。 - - 确认你的允许列表（私信或群组）包含你的账号。 + - 如果你通过 SSH 隧道连接，请确认本地隧道已建立，并且指向了正确的端口。 + - 确认你的 allowlist（私信或群组）包含你的账户。 - 文档：[Tailscale](/zh-CN/gateway/tailscale)、[远程访问](/zh-CN/gateway/remote)、[渠道](/zh-CN/channels)。 + 文档：[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 - 通过 SSH / Tailscale 指向那个远程 Gateway 网关 - （参见 [远程访问](/zh-CN/gateway/remote)）。 + **CLI bridge（通用）：** 运行一个脚本，通过 + `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，或“不要回复机器人消息”的规则）。 - 文档：[远程访问](/zh-CN/gateway/remote)、[智能体 CLI](/cli/agent)、[智能体发送](/zh-CN/tools/agent-send)。 + 文档：[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` 受该笔记本电脑上的节点允许列表 / 审批控制。 - - **更多设备工具。** 节点除 `system.run` 外，还暴露 `canvas`、`camera` 和 `screen`。 - - **本地浏览器自动化。** 将 Gateway 网关 保持在 VPS 上，但通过笔记本电脑上的节点主机在本地运行 Chrome，或通过 Chrome MCP 连接主机上的本地 Chrome。 + - **无需入站 SSH。** 节点会主动向 Gateway WebSocket 发起连接，并使用设备配对。 + - **更安全的执行控制。** `system.run` 在该笔记本电脑上受节点 allowlist/审批控制。 + - **更多设备工具。** 节点除了 `system.run` 外，还暴露 `canvas`、`camera` 和 `screen`。 + - **本地浏览器自动化。** 保持 Gateway 网关在 VPS 上运行，但通过笔记本电脑上的节点主机在本地运行 Chrome，或通过 Chrome MCP 连接到主机上的本地 Chrome。 SSH 适合临时 shell 访问，但对于持续性的智能体工作流和 设备自动化，节点更简单。 @@ -1810,23 +1805,23 @@ x-i18n: - - 不会。每台主机通常只应运行**一个 Gateway 网关**，除非你有意运行隔离的配置文件（参见 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)）。节点是连接到 - Gateway 网关 的外设（iOS / Android 节点，或菜单栏应用中的 macOS“节点模式”）。对于无头节点 - 主机和 CLI 控制，请参阅 [节点主机 CLI](/cli/node)。 + + 不会。每台主机通常只应运行**一个 Gateway 网关**，除非你有意运行隔离配置文件（参见 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)）。节点是连接到 + Gateway 网关的外设（iOS/Android 节点，或菜单栏应用中的 macOS “节点模式”）。对于无头节点 + 主机和 CLI 控制，请参见 [Node host CLI](/cli/node)。 对 `gateway`、`discovery` 和 `canvasHost` 的更改需要完整重启。 - + 有。 - - `config.schema.lookup`：在写入前检查一个配置子树，包括其浅层 schema 节点、匹配到的 UI 提示和直接子项摘要 - - `config.get`：获取当前快照 + 哈希 - - `config.patch`：安全的部分更新（大多数 RPC 编辑的首选）；在可能时热重载，需要时重启 - - `config.apply`：验证并替换完整配置；在可能时热重载，需要时重启 - - 仅限 owner 的 `gateway` 运行时工具仍然拒绝重写 `tools.exec.ask` / `tools.exec.security`；旧版 `tools.bash.*` 别名会被规范化到相同的受保护 exec 路径 + - `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 路径 @@ -1842,59 +1837,59 @@ x-i18n: - + 最小步骤： - 1. **在 VPS 上安装并登录** + 1. **在 VPS 上安装 + 登录** ```bash curl -fsSL https://tailscale.com/install.sh | sh sudo tailscale up ``` - 2. **在你的 Mac 上安装并登录** - - 使用 Tailscale 应用并登录到同一个 tailnet。 + 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： + 如果你想在不使用 SSH 的情况下使用 Control UI，请在 VPS 上使用 Tailscale Serve： ```bash 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 openclaw devices approve ``` - 文档：[Gateway 网关 协议](/zh-CN/gateway/protocol)、[设备发现](/zh-CN/gateway/discovery)、[macOS 远程模式](/zh-CN/platforms/mac/remote)。 + 文档：[Gateway protocol](/zh-CN/gateway/protocol)、[设备发现](/zh-CN/gateway/discovery)、[macOS remote mode](/zh-CN/platforms/mac/remote)。 - - 如果你只需要在第二台笔记本电脑上使用**本地工具**（屏幕 / 摄像头 / exec），那就把它添加为 - 一个**节点**。这样可以保留单个 Gateway 网关，并避免重复配置。本地节点工具 - 目前仅支持 macOS，但我们计划将其扩展到其他操作系统。 + + 如果你只需要在第二台笔记本电脑上使用**本地工具**（screen/camera/exec），那就把它添加为一个 + **节点**。这样可以保持单一 Gateway 网关，避免重复配置。本地节点工具 + 目前仅支持 macOS，但我们计划扩展到其他操作系统。 - 只有在你需要**硬隔离**或两个完全独立的机器人时，才需要安装第二个 Gateway 网关。 + 只有在你需要**强隔离**或两个完全独立的机器人时，才安装第二个 Gateway 网关。 文档：[Nodes](/zh-CN/nodes)、[Nodes CLI](/cli/nodes)、[多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。 @@ -1905,14 +1900,14 @@ x-i18n: - OpenClaw 会从父进程（shell、launchd / systemd、CI 等）读取环境变量，另外还会加载： + OpenClaw 会从父进程（shell、launchd/systemd、CI 等）读取环境变量，并额外加载： - 当前工作目录中的 `.env` - - `~/.openclaw/.env` 中的全局回退 `.env`（也就是 `$OPENCLAW_STATE_DIR/.env`） + - `~/.openclaw/.env`（即 `$OPENCLAW_STATE_DIR/.env`）中的全局回退 `.env` - 两个 `.env` 文件都不会覆盖现有环境变量。 + 这两个 `.env` 文件都不会覆盖现有环境变量。 - 你也可以在配置中定义内联环境变量（仅在进程环境中缺失时应用）： + 你也可以在配置中定义内联环境变量（仅在进程环境中缺失时才应用）： ```json5 { @@ -1923,15 +1918,15 @@ x-i18n: } ``` - 完整优先级和来源请参阅 [/environment](/zh-CN/help/environment)。 + 完整优先级和来源请参见 [/environment](/zh-CN/help/environment)。 - - 两个常见修复方法： + + 两种常见修复方式： - 1. 将缺失的键放入 `~/.openclaw/.env`，这样即使服务没有继承你的 shell 环境，它们也会被读取。 - 2. 启用 shell 导入（可选的便捷功能）： + 1. 将缺失的 key 放到 `~/.openclaw/.env` 中，这样即使服务没有继承你的 shell 环境，它们也会被读取。 + 2. 启用 shell 导入（自选便利功能）： ```json5 { @@ -1944,36 +1939,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 不会 + 自动加载你的登录 shell。 - 如果 Gateway 网关 作为服务运行（launchd / systemd），它不会继承你的 shell - 环境。可以通过以下任一方式修复： + 如果 Gateway 网关作为服务运行（launchd/systemd），它不会继承你的 shell + 环境。可通过以下任一方式修复： - 1. 将令牌放入 `~/.openclaw/.env`： + 1. 将 token 放到 `~/.openclaw/.env` 中： ``` COPILOT_GITHUB_TOKEN=... ``` 2. 或启用 shell 导入（`env.shellEnv.enabled: true`）。 - 3. 或将它添加到你的配置 `env` 块中（仅在缺失时应用）。 + 3. 或将其添加到配置的 `env` 块中（仅在缺失时应用）。 - 然后重启 Gateway 网关 并重新检查： + 然后重启 Gateway 网关并重新检查： ```bash openclaw models status ``` - Copilot 令牌会从 `COPILOT_GITHUB_TOKEN` 读取（也支持 `GH_TOKEN` / `GITHUB_TOKEN`）。 - 请参阅 [/concepts/model-providers](/zh-CN/concepts/model-providers) 和 [/environment](/zh-CN/help/environment)。 + Copilot token 会从 `COPILOT_GITHUB_TOKEN` 读取（也支持 `GH_TOKEN` / `GITHUB_TOKEN`）。 + 参见 [/concepts/model-providers](/zh-CN/concepts/model-providers) 和 [/environment](/zh-CN/help/environment)。 @@ -1982,14 +1977,14 @@ x-i18n: - 发送 `/new` 或 `/reset` 作为单独消息。请参阅 [会话管理](/zh-CN/concepts/session)。 + 发送 `/new` 或 `/reset` 作为独立消息即可。参见 [会话管理](/zh-CN/concepts/session)。 - - 会话可以在 `session.idleMinutes` 之后过期，但这**默认是禁用的**（默认值为 **0**）。 - 将其设置为正值即可启用空闲过期。启用后，在空闲期结束后的**下一条** + + 会话可以在 `session.idleMinutes` 之后过期，但默认**禁用**（默认值为 **0**）。 + 将其设为正值即可启用空闲过期。启用后，空闲期结束后的**下一条** 消息会为该聊天键启动一个新的会话 ID。 - 这不会删除转录内容——它只是开始一个新会话。 + 这不会删除对话记录——只是启动一个新会话。 ```json5 { @@ -2001,30 +1996,29 @@ x-i18n: - - 可以，通过**多智能体路由**和**子智能体**实现。你可以创建一个协调者 - 智能体，以及多个具有各自工作区和模型的工作智能体。 + + 可以，通过**多智能体路由**和**子智能体**实现。你可以创建一个协调型 + 智能体和若干个拥有各自工作区与模型的工作智能体。 - 不过，这更适合作为一种**有趣的实验**来看待。它会消耗大量令牌，而且通常 - 不如使用一个机器人配合多个独立会话高效。我们设想的典型模式是 - 你只与一个机器人对话，并用不同会话来进行并行工作。这个 - 机器人也可以在需要时生成子智能体。 + 不过，最好把这视为一个**有趣的实验**。它会消耗大量 token，而且通常 + 不如使用一个机器人配合多个独立会话高效。我们设想的典型模型是：你与一个机器人对话， + 同时用不同会话处理并行工作。这个机器人也可以在需要时启动子智能体。 - 文档：[多智能体路由](/zh-CN/concepts/multi-agent)、[子智能体](/zh-CN/tools/subagents)、[智能体 CLI](/cli/agents)。 + 文档：[多智能体路由](/zh-CN/concepts/multi-agent)、[Sub-agents](/zh-CN/tools/subagents)、[Agents CLI](/cli/agents)。 - + 会话上下文受模型窗口限制。长聊天、大量工具输出或许多 文件都可能触发压缩或截断。 有帮助的做法： - 让机器人总结当前状态并写入文件。 - - 在长任务前使用 `/compact`，切换主题时使用 `/new`。 + - 在长任务前使用 `/compact`，切换话题时使用 `/new`。 - 将重要上下文保存在工作区中，并让机器人重新读取。 - - 对长任务或并行工作使用子智能体，这样主聊天会保持更小。 - - 如果这种情况经常发生，选择具有更大上下文窗口的模型。 + - 对于长时间或并行工作，使用子智能体，这样主聊天会保持更小。 + - 如果这种情况经常发生，请选择上下文窗口更大的模型。 @@ -2035,7 +2029,7 @@ x-i18n: openclaw reset ``` - 非交互式完全重置： + 非交互式完整重置： ```bash openclaw reset --scope full --yes --non-interactive @@ -2049,57 +2043,57 @@ x-i18n: 说明： - - 如果新手引导检测到已有配置，也会提供**重置**选项。请参阅 [设置向导（CLI）](/zh-CN/start/wizard)。 - - 如果你使用了配置文件（`--profile` / `OPENCLAW_PROFILE`），请分别重置每个状态目录（默认是 `~/.openclaw-`）。 - - 开发环境重置：`openclaw gateway --dev --reset`（仅限开发环境；会清除开发配置 + 凭据 + 会话 + 工作区）。 + - 如果检测到现有配置，新手引导也会提供**重置**选项。参见 [设置向导（CLI）](/zh-CN/start/wizard)。 + - 如果你使用了配置文件（`--profile` / `OPENCLAW_PROFILE`），请重置每个状态目录（默认是 `~/.openclaw-`）。 + - 开发环境重置：`openclaw gateway --dev --reset`（仅限开发环境；会清除开发配置 + 凭证 + 会话 + 工作区）。 - + 使用以下任一方式： - - **压缩**（保留对话，但总结较早的轮次）： + - **压缩**（保留对话，但总结较早轮次）： ``` /compact ``` - 或使用 `/compact ` 来指导摘要方式。 + 或使用 `/compact ` 来引导摘要内容。 - - **重置**（为相同聊天键创建新的会话 ID）： + - **重置**（为同一个聊天键生成新的会话 ID）： ``` /new /reset ``` - 如果问题持续发生： + 如果这种情况持续发生： - - 启用或调整**会话修剪**（`agents.defaults.contextPruning`）以裁剪旧工具输出。 - - 使用具有更大上下文窗口的模型。 + - 启用或调整**会话修剪**（`agents.defaults.contextPruning`），以裁剪旧的工具输出。 + - 使用上下文窗口更大的模型。 - 文档：[压缩](/zh-CN/concepts/compaction)、[会话修剪](/zh-CN/concepts/session-pruning)、[会话管理](/zh-CN/concepts/session)。 + 文档：[Compaction](/zh-CN/concepts/compaction)、[Session pruning](/zh-CN/concepts/session-pruning)、[会话管理](/zh-CN/concepts/session)。 - 这是一个提供商验证错误：模型输出了一个缺少必需 - `input` 的 `tool_use` 块。通常意味着会话历史已过期或损坏（常见于长线程 - 或工具 / schema 变更之后）。 + 这是提供商校验错误：模型输出了一个缺少必需 + `input` 的 `tool_use` 块。通常意味着会话历史陈旧或已损坏（常见于长线程 + 或工具/schema 变更之后）。 - 修复方法：使用 `/new`（单独一条消息）开始一个新会话。 + 修复方式：使用 `/new`（独立消息）开启一个全新会话。 - Heartbeat 默认每 **30m** 运行一次（使用 OAuth 认证时为 **1h**）。你可以调整或禁用它们： + Heartbeat 默认每 **30 分钟**运行一次（使用 OAuth 认证时为 **1 小时**）。可调整或禁用： ```json5 { agents: { defaults: { heartbeat: { - every: "2h", // 或 "0m" 以禁用 + every: "2h", // 或设为 "0m" 以禁用 }, }, }, @@ -2107,18 +2101,18 @@ x-i18n: ``` 如果 `HEARTBEAT.md` 存在但实际上为空（只有空行和 markdown - 标题，例如 `# Heading`），OpenClaw 会跳过 Heartbeat 运行以节省 API 调用。 - 如果文件不存在，Heartbeat 仍会运行，并由模型决定该做什么。 + 标题，如 `# 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 { @@ -2134,7 +2128,7 @@ x-i18n: - 方式 1（最快）：跟踪日志，然后在群组中发送一条测试消息： + 方式 1（最快）：跟踪日志，然后在群里发送一条测试消息： ```bash openclaw logs --follow --json @@ -2143,61 +2137,61 @@ x-i18n: 查找以 `@g.us` 结尾的 `chatId`（或 `from`），例如： `1234567890-1234567890@g.us`。 - 方式 2（如果已经配置 / 加入允许列表）：从配置中列出群组： + 方式 2（如果已经配置/加入 allowlist）：从配置中列出群组： ```bash openclaw directory groups list --channel whatsapp ``` - 文档：[WhatsApp](/zh-CN/channels/whatsapp)、[Directory](/cli/directory)、[日志](/cli/logs)。 + 文档：[WhatsApp](/zh-CN/channels/whatsapp)、[Directory](/cli/directory)、[Logs](/cli/logs)。 - + 两个常见原因： - - 提及门控已开启（默认）。你必须 `@提及` 机器人（或匹配 `mentionPatterns`）。 - - 你配置了 `channels.whatsapp.groups`，但没有包含 `"*"`，且该群组不在允许列表中。 + - 提及触发已开启（默认）。你必须 @ 提及机器人（或匹配 `mentionPatterns`）。 + - 你配置了 `channels.whatsapp.groups`，但没有包含 `"*"`，且该群组不在 allowlist 中。 - 请参阅 [群组](/zh-CN/channels/groups) 和 [群组消息](/zh-CN/channels/group-messages)。 + 参见 [Groups](/zh-CN/channels/groups) 和 [Group messages](/zh-CN/channels/group-messages)。 - - 直接聊天默认会折叠到主会话。群组 / 渠道有各自独立的会话键，而 Telegram 话题 / Discord 线程则是独立会话。请参阅 [群组](/zh-CN/channels/groups) 和 [群组消息](/zh-CN/channels/group-messages)。 + + 直接聊天默认会收敛到主会话。群组/渠道有各自独立的会话键，而 Telegram 话题 / Discord 线程也都是独立会话。参见 [Groups](/zh-CN/channels/groups) 和 [Group messages](/zh-CN/channels/group-messages)。 - 没有硬性限制。几十个（甚至几百个）都没问题，但要注意： + 没有硬性限制。几十个（甚至上百个）都没问题，但请注意： - - **磁盘增长：** 会话 + 转录内容位于 `~/.openclaw/agents//sessions/` 下。 - - **令牌成本：** 更多智能体意味着更多并发模型使用。 - - **运维开销：** 按智能体划分的认证配置文件、工作区和渠道路由。 + - **磁盘增长：** 会话 + 转录内容保存在 `~/.openclaw/agents//sessions/` 下。 + - **token 成本：** 智能体越多，意味着并发模型使用越多。 + - **运维开销：** 每个智能体都有各自的认证配置文件、工作区和渠道路由。 提示： - - 为每个智能体保留一个**活跃**工作区（`agents.defaults.workspace`）。 - - 如果磁盘增长，修剪旧会话（删除 JSONL 或存储条目）。 - - 使用 `openclaw doctor` 检查游离工作区和配置文件不匹配问题。 + - 每个智能体保持一个**活动**工作区（`agents.defaults.workspace`）。 + - 如果磁盘增长，清理旧会话（删除 JSONL 或存储条目）。 + - 使用 `openclaw doctor` 发现零散工作区和配置文件不匹配问题。 - - 可以。使用**多智能体路由**来运行多个隔离的智能体，并按 - 渠道 / 账户 / peer 路由入站消息。Slack 作为渠道受支持，并且可以绑定到特定智能体。 + + 可以。使用**多智能体路由**来运行多个相互隔离的智能体，并按 + 渠道/账户/peer 路由入站消息。Slack 作为渠道受支持，也可以绑定到特定智能体。 - 浏览器访问能力很强，但并不等于“能做任何人类能做的事”——反机器人机制、CAPTCHA 和 MFA - 仍然可能阻止自动化。若想获得最可靠的浏览器控制，请在主机上使用本地 Chrome MCP， + 浏览器访问能力很强，但并不等于“能做人类能做的任何事”——反机器人机制、CAPTCHA 和 MFA + 仍然可能阻止自动化。若要获得最可靠的浏览器控制，请在主机上使用本地 Chrome MCP， 或在实际运行浏览器的机器上使用 CDP。 - 最佳实践部署： + 最佳实践部署方式： - - 始终在线的 Gateway 网关 主机（VPS / Mac mini）。 + - 始终在线的 Gateway 网关主机（VPS/Mac mini）。 - 每个角色一个智能体（bindings）。 - 将 Slack 渠道绑定到这些智能体。 - - 需要时通过 Chrome MCP 或节点使用本地浏览器。 + - 在需要时通过 Chrome MCP 或节点使用本地浏览器。 - 文档：[多智能体路由](/zh-CN/concepts/multi-agent)、[Slack](/zh-CN/channels/slack)、 + 文档：[Multi-Agent Routing](/zh-CN/concepts/multi-agent)、[Slack](/zh-CN/channels/slack)、 [Browser](/zh-CN/tools/browser)、[Nodes](/zh-CN/nodes)。 @@ -2207,90 +2201,91 @@ x-i18n: - OpenClaw 的默认模型就是你设置在以下位置的模型： + OpenClaw 的默认模型就是你设置在以下位置的内容： ``` agents.defaults.model.primary ``` - 模型以 `provider/model` 的形式引用（示例：`openai/gpt-5.4`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该精确模型 id 唯一匹配的已配置提供商，最后才会退回到已配置的默认提供商这一已弃用的兼容路径。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider / model，而不是暴露一个陈旧的、已移除提供商默认值。不过，你仍然应该**显式**设置 `provider/model`。 + 模型以 `provider/model` 的形式引用（例如：`openai/gpt-5.4`）。如果你省略了 provider，OpenClaw 会先尝试别名，然后尝试与该精确模型 id 匹配的唯一已配置 provider，最后才会退回到已配置的默认 provider，这是一条已弃用的兼容路径。如果该 provider 不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider/model，而不是暴露一个陈旧的、已移除 provider 的默认值。你仍然应该**显式**设置 `provider/model`。 - - **推荐默认值：** 使用你提供商栈中可用的最强最新一代模型。 - **对于启用了工具或处理不可信输入的智能体：** 优先考虑模型强度，而不是成本。 - **对于常规 / 低风险聊天：** 使用更便宜的回退模型，并按智能体角色进行路由。 + + **推荐默认值：** 使用你的提供商栈中可用的最强、最新一代模型。 + **对于启用工具或处理不可信输入的智能体：** 优先考虑模型能力，而不是成本。 + **对于日常/低风险聊天：** 使用更便宜的回退模型，并按智能体角色进行路由。 - MiniMax 有单独文档：[MiniMax](/zh-CN/providers/minimax) 和 - [本地模型](/zh-CN/gateway/local-models)。 + MiniMax 有自己的文档：[MiniMax](/zh-CN/providers/minimax) 和 + [Local models](/zh-CN/gateway/local-models)。 - 经验法则：对于高风险工作，使用**你负担得起的最佳模型**；对于日常 - 聊天或摘要，则使用更便宜的模型。你可以按智能体路由模型，并使用子智能体来 - 并行处理长任务（每个子智能体都会消耗令牌）。请参阅 [模型](/zh-CN/concepts/models) 和 - [子智能体](/zh-CN/tools/subagents)。 + 经验法则：对于高风险工作，使用你**负担得起的最佳模型**；而对于日常聊天或摘要， + 使用更便宜的模型。你可以按智能体路由模型，并使用子智能体来 + 并行处理长任务（每个子智能体都会消耗 token）。参见 [Models](/zh-CN/concepts/models) 和 + [Sub-agents](/zh-CN/tools/subagents)。 - 强烈警告：较弱 / 过度量化的模型更容易受到 prompt - injection 和不安全行为影响。请参阅 [安全](/zh-CN/gateway/security)。 + 强烈警告：较弱/过度量化的模型更容易受到 prompt + injection 和不安全行为的影响。参见 [Security](/zh-CN/gateway/security)。 - 更多背景：[模型](/zh-CN/concepts/models)。 + 更多背景信息：[Models](/zh-CN/concepts/models)。 - 使用**模型命令**，或只编辑**模型**字段。避免完整替换配置。 + 使用**模型命令**，或只编辑**模型**字段。避免整份配置替换。 - 安全选项： + 安全方式： - 在聊天中使用 `/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` 进行修复。 - 文档：[模型](/zh-CN/concepts/models)、[配置向导](/cli/configure)、[配置](/cli/config)、[Doctor](/zh-CN/gateway/doctor)。 + 文档：[Models](/zh-CN/concepts/models)、[Configure](/cli/configure)、[Config](/cli/config)、[Doctor](/zh-CN/gateway/doctor)。 - 可以。Ollama 是使用本地模型最简单的路径。 + 可以。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` 这样的云模型不需要本地拉取 - - 若要手动切换，请使用 `openclaw models list` 和 `openclaw models set ollama/` + - 像 `kimi-k2.5:cloud` 这样的云模型不需要本地 pull + - 如需手动切换，请使用 `openclaw models list` 和 `openclaw models set ollama/` 安全说明：较小或高度量化的模型更容易受到 prompt - injection 影响。对于任何可使用工具的机器人，我们强烈建议使用**大模型**。 - 如果你仍然想使用小模型，请启用沙箱隔离和严格的工具允许列表。 + injection 影响。对于任何可以使用工具的机器人，我们强烈推荐使用**大模型**。 + 如果你仍想使用小模型，请启用沙箱隔离和严格的工具 allowlist。 - 文档：[Ollama](/zh-CN/providers/ollama)、[本地模型](/zh-CN/gateway/local-models)、 - [模型提供商](/zh-CN/concepts/model-providers)、[安全](/zh-CN/gateway/security)、 + 文档：[Ollama](/zh-CN/providers/ollama)、[Local models](/zh-CN/gateway/local-models)、 + [Model providers](/zh-CN/concepts/model-providers)、[Security](/zh-CN/gateway/security)、 [沙箱隔离](/zh-CN/gateway/sandboxing)。 - - 这些部署可能彼此不同，并且会随时间变化；没有固定的提供商推荐。 - - 请在每个 gateway 上使用 `openclaw models status` 检查当前运行时设置。 - - 对于安全敏感 / 启用了工具的智能体，请使用当前可用的最强最新一代模型。 + - 这些部署可能不同，而且会随时间变化；没有固定的提供商推荐。 + - 使用 `openclaw models status` 检查每个 Gateway 网关上的当前运行时设置。 + - 对于安全敏感/启用工具的智能体，请使用当前可用的最强最新一代模型。 - 将 `/model` 命令作为单独消息发送： + 将 `/model` 命令作为独立消息发送： ``` /model sonnet @@ -2302,9 +2297,9 @@ x-i18n: /model gemini-flash-lite ``` - 这些是内置别名。自定义别名可通过 `agents.defaults.models` 添加。 + 这些是内置别名。你也可以通过 `agents.defaults.models` 添加自定义别名。 - 你可以通过 `/model`、`/model list` 或 `/model status` 列出可用模型。 + 你可以使用 `/model`、`/model list` 或 `/model status` 列出可用模型。 `/model`（以及 `/model list`）会显示一个紧凑的编号选择器。按编号选择： @@ -2312,46 +2307,46 @@ x-i18n: /model 3 ``` - 你还可以为提供商强制指定某个认证配置文件（按会话）： + 你还可以为 provider 强制指定某个认证配置文件（按会话）： ``` /model opus@anthropic:default /model opus@anthropic:work ``` - 提示：`/model status` 会显示当前处于活动状态的智能体、正在使用的 `auth-profiles.json` 文件，以及接下来将尝试哪个认证配置文件。 - 如果可用，它还会显示已配置的提供商端点（`baseUrl`）和 API 模式（`api`）。 + 提示：`/model status` 会显示当前激活的是哪个智能体、正在使用哪个 `auth-profiles.json` 文件，以及接下来将尝试哪个认证配置文件。 + 如果可用，它还会显示已配置的 provider 端点（`baseUrl`）和 API 模式（`api`）。 - **如何取消通过 @profile 设置的固定配置文件？** + **如何取消用 `@profile` 设置的固定配置文件？** - 重新运行 `/model`，**不要**带上 `@profile` 后缀： + 重新运行 `/model`，**不要**带 `@profile` 后缀： ``` /model anthropic/claude-opus-4-6 ``` - 如果你想回到默认值，可以从 `/model` 中选择它（或发送 `/model `）。 + 如果你想恢复默认值，请从 `/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`，编码时使用 `/model openai-codex/gpt-5.4` 配合 Codex OAuth。 + - **默认值 + 切换：** 将 `agents.defaults.model.primary` 设为 `openai/gpt-5.4`，然后在编码时切换到 `openai-codex/gpt-5.4`（反过来也可以）。 + - **子智能体：** 将编码任务路由到默认模型不同的子智能体。 - 请参阅 [模型](/zh-CN/concepts/models) 和 [斜杠命令](/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`，请在那里设置相同标志。 + - **每模型默认值：** 将 `agents.defaults.models["openai/gpt-5.4"].params.fastMode` 设为 `true`。 + - **Codex OAuth 也一样：** 如果你也使用 `openai-codex/gpt-5.4`，也在那边设置相同标志。 示例： @@ -2378,38 +2373,37 @@ x-i18n: 对于 OpenAI，快速模式会映射为受支持原生 Responses 请求中的 `service_tier = "priority"`。会话级 `/fast` 覆盖优先于配置默认值。 - 请参阅 [思考与快速模式](/zh-CN/tools/thinking) 和 [OpenAI 快速模式](/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` 和任何 - 会话覆盖的**允许列表**。选择不在该列表中的模型会返回： + + 如果设置了 `agents.defaults.models`，它就会成为 `/model` 以及任何 + 会话覆盖的**allowlist**。选择不在列表中的模型会返回： ``` Model "provider/model" is not allowed. Use /model to list available models. ``` - 该错误会**取代**正常回复返回。修复方法：将模型添加到 - `agents.defaults.models`，移除允许列表，或从 `/model list` 中选择一个模型。 + 该错误会**替代**正常回复返回。修复方式：将该模型加入 + `agents.defaults.models`，移除 allowlist，或从 `/model list` 中选择一个模型。 - 这意味着**提供商未配置**（未找到 MiniMax 提供商配置或 - 认证配置文件），因此无法解析该模型。 + 这意味着**provider 未配置**（未找到 MiniMax provider 配置或认证 + 配置文件），因此无法解析该模型。 - 修复清单： + 修复检查清单： - 1. 升级到当前版本的 OpenClaw（或直接从源码 `main` 运行），然后重启 gateway。 - 2. 确保已配置 MiniMax（通过向导或 JSON），或者 MiniMax 认证 - 存在于环境变量 / 认证配置文件中，以便注入匹配的提供商 + 1. 升级到当前的 OpenClaw 版本（或从源码 `main` 运行），然后重启 Gateway 网关。 + 2. 确保已配置 MiniMax（通过向导或 JSON），或者在环境变量/认证配置文件中 + 存在 MiniMax 认证，以便注入匹配的 provider （`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 密钥方式使用 `minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed`， + OAuth 方式使用 `minimax-portal/MiniMax-M2.7` / `minimax-portal/MiniMax-M2.7-highspeed`。 4. 运行： @@ -2417,17 +2411,17 @@ x-i18n: openclaw models list ``` - 并从列表中选择（或在聊天中使用 `/model list`）。 + 然后从列表中选择（或在聊天中使用 `/model list`）。 - 请参阅 [MiniMax](/zh-CN/providers/minimax) 和 [模型](/zh-CN/concepts/models)。 + 参见 [MiniMax](/zh-CN/providers/minimax) 和 [Models](/zh-CN/concepts/models)。 - - 可以。将 **MiniMax 设为默认值**，并在需要时**按会话**切换模型。 - 回退机制适用于**错误**，而不是“难任务”，所以请使用 `/model` 或单独的智能体。 + + 可以。将**MiniMax 设为默认**，并在需要时**按会话**切换模型。 + 回退是为**错误**准备的，不是为“高难度任务”准备的，因此请使用 `/model` 或单独的智能体。 - **选项 A：按会话切换** + **方案 A：按会话切换** ```json5 { @@ -2450,18 +2444,18 @@ x-i18n: /model gpt ``` - **选项 B：单独的智能体** + **方案 B：分成不同智能体** - 智能体 A 默认：MiniMax - 智能体 B 默认：OpenAI - - 按智能体路由，或使用 `/agent` 切换 + - 按智能体路由，或使用 `/agent` 进行切换 - 文档：[模型](/zh-CN/concepts/models)、[多智能体路由](/zh-CN/concepts/multi-agent)、[MiniMax](/zh-CN/providers/minimax)、[OpenAI](/zh-CN/providers/openai)。 + 文档：[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` @@ -2476,7 +2470,7 @@ x-i18n: - + 别名来自 `agents.defaults.models..alias`。示例： ```json5 @@ -2494,12 +2488,12 @@ x-i18n: } ``` - 然后 `/model sonnet`（或在支持时使用 `/`）就会解析到对应的模型 ID。 + 然后 `/model sonnet`（或在支持时使用 `/`）就会解析为该模型 ID。 - - OpenRouter（按令牌计费；模型很多）： + + OpenRouter（按 token 计费；模型众多）： ```json5 { @@ -2527,11 +2521,11 @@ x-i18n: } ``` - 如果你引用了某个 provider / model，但缺少所需的提供商密钥，你会看到运行时认证错误（例如 `No API key found for provider "zai"`）。 + 如果你引用了某个 provider/model，但缺少所需的 provider key，就会收到运行时认证错误（例如 `No API key found for provider "zai"`）。 - **添加新智能体后提示 No API key found for provider** + **添加新智能体后出现 “No API key found for provider”** - 这通常意味着**新智能体**的认证存储是空的。认证是按智能体区分的， + 这通常意味着**新智能体**的认证存储是空的。认证按智能体隔离， 存储在： ``` @@ -2541,117 +2535,118 @@ x-i18n: 修复方式： - 运行 `openclaw agents add `，并在向导中配置认证。 - - 或者把主智能体 `agentDir` 中的 `auth-profiles.json` 复制到新智能体的 `agentDir` 中。 + - 或者将主智能体 `agentDir` 中的 `auth-profiles.json` 复制到新智能体的 `agentDir` 中。 - **不要**在多个智能体之间复用 `agentDir`；这会导致认证 / 会话冲突。 + **不要**在多个智能体之间复用 `agentDir`；这会导致认证/会话冲突。 -## 模型故障切换和 “All models failed” +## 模型故障转移和“所有模型都失败了” - - 故障切换分为两个阶段： + + 故障转移分两个阶段进行： - 1. **同一提供商内的认证配置文件轮换**。 + 1. **同一 provider 内的认证配置文件轮换**。 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`）视为值得故障切换的 - 速率限制。 + `workers_ai ... quota limit exceeded`、`resource exhausted` 以及周期性的 + 用量窗口限制（`weekly/monthly limit reached`）等消息视为值得故障转移的 + 限速信号。 有些看起来像计费问题的响应并不是 `402`，而有些 HTTP `402` - 响应也会留在那个瞬时错误桶里。如果某个提供商在 `401` 或 `403` - 上返回明确的计费文本，OpenClaw 仍然可以把它归入 - 计费通道，但提供商专属的文本匹配器仍然只作用于 - 拥有它们的提供商（例如 OpenRouter 的 `Key limit exceeded`）。如果某条 `402` - 消息看起来更像是可重试的使用窗口或 - 组织 / 工作区花费限制（`daily limit reached, resets tomorrow`、 + 响应也仍然会留在这个临时桶中。如果提供商在 `401` 或 `403` 上返回了 + 明确的计费文本，OpenClaw 仍可将其归入 + 计费路径，但 provider 专属的文本匹配器仍然限定在其所属的 + provider 范围内（例如 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 的内容” - 更窄。OpenClaw 确实会在提供商上下文匹配时，将提供商专属的瞬时错误形态 - 视为值得故障切换的超时 / 过载信号，例如 Anthropic 的裸 `An unknown error occurred`、OpenRouter 的裸 + 通用服务器错误文本的范围被有意收窄，而不是“任何带有 + unknown/error 的内容都算”。当 provider 上下文 + 匹配时，OpenClaw 确实会将 provider 范围内的临时错误形态 + 视为值得故障转移的超时/过载信号，例如 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`），以及提供商繁忙错误如 `ModelNotReadyException`。 - 而像 `LLM request failed with an unknown - error.` 这样的通用内部回退文本则保持保守，不会仅凭自身触发模型回退。 + error`），以及 provider 忙碌错误如 `ModelNotReadyException`。 + 像 `LLM request failed with an unknown + error.` 这样的通用内部回退文本则保持保守，不会单独触发模型回退。 - 这意味着系统尝试使用认证配置文件 ID `anthropic:default`，但无法在预期的认证存储中找到它的凭据。 + 这表示系统尝试使用认证配置文件 ID `anthropic:default`，但在预期的认证存储中找不到对应凭证。 - **修复清单：** + **修复检查清单：** - - **确认认证配置文件存放位置**（新版路径与旧版路径） + - **确认认证配置文件存放位置**（新路径与遗留路径） - 当前：`~/.openclaw/agents//agent/auth-profiles.json` - - 旧版：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移） - - **确认 Gateway 网关 已加载你的环境变量** - - 如果你在 shell 中设置了 `ANTHROPIC_API_KEY`，但通过 systemd / launchd 运行 Gateway 网关，它可能不会继承该变量。请把它放到 `~/.openclaw/.env` 中，或启用 `env.shellEnv`。 - - **确保你编辑的是正确的智能体** + - 遗留：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移） + - **确认 Gateway 网关已加载你的环境变量** + - 如果你在 shell 中设置了 `ANTHROPIC_API_KEY`，但通过 systemd/launchd 运行 Gateway 网关，它可能不会继承。请将其放入 `~/.openclaw/.env`，或启用 `env.shellEnv`。 + - **确认你编辑的是正确的智能体** - 多智能体部署意味着可能存在多个 `auth-profiles.json` 文件。 - - **检查模型 / 认证状态** - - 使用 `openclaw models status` 查看已配置的模型以及提供商是否已认证。 + - **做一个模型/认证状态完整性检查** + - 使用 `openclaw models status` 查看已配置模型，以及提供商是否已认证。 - **“No credentials found for profile anthropic” 的修复清单** + **针对 “No credentials found for profile anthropic” 的修复检查清单** - 这意味着当前运行被固定到某个 Anthropic 认证配置文件，但 Gateway 网关 - 无法在其认证存储中找到它。 + 这表示当前运行被固定到了某个 Anthropic 认证配置文件，但 Gateway 网关 + 在其认证存储中找不到它。 - **使用 Claude CLI** - - 在 Gateway 网关 主机上运行 `openclaw models auth login --provider anthropic --method cli --set-default`。 + - 在 Gateway 网关主机上运行 `openclaw models auth login --provider anthropic --method cli --set-default`。 - **如果你想改用 API 密钥** - - 在**Gateway 网关 主机**上的 `~/.openclaw/.env` 中设置 `ANTHROPIC_API_KEY`。 - - 清除任何强制使用缺失配置文件的固定顺序： + - 将 `ANTHROPIC_API_KEY` 放到**Gateway 网关主机**上的 `~/.openclaw/.env` 中。 + - 清除任何强制使用不存在配置文件的固定顺序： ```bash openclaw models auth order clear --provider anthropic ``` - - **确认你是在 Gateway 网关 主机上运行命令** - - 在远程模式下，认证配置文件位于 gateway 机器上，而不是你的笔记本电脑上。 + - **确认你是在 Gateway 网关主机上运行命令** + - 在远程模式下，认证配置文件存放在 Gateway 网关机器上，而不是你的笔记本电脑上。 - - 如果你的模型配置中把 Google Gemini 设为了回退项（或者你切换到了 Gemini 简写），OpenClaw 就会在模型回退时尝试它。如果你没有配置 Google 凭据，就会看到 `No API key found for provider "google"`。 + + 如果你的模型配置中把 Google Gemini 作为回退项（或者你切换到了 Gemini 简写），OpenClaw 就会在模型回退时尝试它。如果你没有配置 Google 凭证，就会看到 `No API key found for provider "google"`。 - 修复方法：要么提供 Google 认证，要么从 `agents.defaults.model.fallbacks` / 别名中移除 / 避免 Google 模型，这样回退就不会路由到那里。 + 修复方式：提供 Google 认证，或者从 `agents.defaults.model.fallbacks` / 别名中移除或避免 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`。 ## 认证配置文件：它们是什么，以及如何管理 -相关内容：[/concepts/oauth](/zh-CN/concepts/oauth)（OAuth 流程、令牌存储、多账户模式） +相关内容：[/concepts/oauth](/zh-CN/concepts/oauth)（OAuth 流程、token 存储、多账户模式） - 认证配置文件是与某个提供商关联的命名凭据记录（OAuth 或 API 密钥）。配置文件保存在： + 认证配置文件是一个与提供商绑定的命名凭证记录（OAuth 或 API 密钥）。配置文件存放在： ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -2660,40 +2655,40 @@ x-i18n: - OpenClaw 使用带提供商前缀的 ID，例如： + OpenClaw 使用带 provider 前缀的 ID，例如： - - `anthropic:default`（没有 email 身份时很常见） - - `anthropic:` 用于 OAuth 身份 + - `anthropic:default`（在不存在邮箱身份时很常见） + - OAuth 身份使用 `anthropic:` - 你自定义的 ID（例如 `anthropic:work`） - 可以。配置支持可选的配置文件元数据，以及按提供商划分的顺序（`auth.order.`）。这**不会**存储 secret；它只会把 ID 映射到 provider / mode，并设置轮换顺序。 + 可以。配置支持配置文件的可选元数据，以及每个 provider 的顺序（`auth.order.`）。这**不会**存储 secret；它只会将 ID 映射到 provider/mode，并设置轮换顺序。 - 如果某个配置文件处于短暂的**冷却**状态（速率限制 / 超时 / 认证失败）或较长的**禁用**状态（计费 / 额度不足），OpenClaw 可能会暂时跳过它。要检查这一点，请运行 `openclaw models status --json` 并查看 `auth.unusableProfiles`。调优项：`auth.cooldowns.billingBackoffHours*`。 + 如果某个配置文件处于短期**冷却**（限速/超时/认证失败）或较长期**禁用**（计费/余额不足）状态，OpenClaw 可能会暂时跳过它。要检查这一点，请运行 `openclaw models status --json` 并查看 `auth.unusableProfiles`。调优项：`auth.cooldowns.billingBackoffHours*`。 - 速率限制冷却可以是模型级别的。某个配置文件在一个模型上处于冷却状态时， - 在同一提供商下的兄弟模型上仍可能可用， - 而计费 / 禁用窗口仍会阻止整个配置文件。 + 限速冷却可以按模型作用域生效。某个配置文件如果正在为一个模型冷却， + 对于同一 provider 下的兄弟模型仍可能可用； + 但计费/禁用窗口仍会阻止整个配置文件。 - 你还可以通过 CLI 设置**按智能体**的顺序覆盖（存储在该智能体的 `auth-state.json` 中）： + 你也可以通过 CLI 设置**按智能体**的顺序覆盖（存储在该智能体的 `auth-state.json` 中）： ```bash # 默认为已配置的默认智能体（省略 --agent） openclaw models auth order get --provider anthropic - # 将轮换固定为单个配置文件（只尝试这个） + # 将轮换锁定到单一配置文件（只尝试这个） 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 @@ -2705,27 +2700,27 @@ x-i18n: openclaw models status --probe ``` - 如果显式顺序中省略了某个已存储配置文件，probe 会为该配置文件报告 - `excluded_by_auth_order`，而不是悄悄尝试它。 + 如果某个已存储配置文件被排除在显式顺序之外，probe 会为 + 该配置文件报告 `excluded_by_auth_order`，而不是静默尝试它。 - OpenClaw 两者都支持： + OpenClaw 同时支持两者： - - **OAuth** 通常会利用订阅访问权限（在适用时）。 - - **API 密钥** 使用按令牌计费。 + - **OAuth** 通常会利用订阅访问权限（适用时）。 + - **API 密钥** 使用按 token 计费。 向导明确支持 Anthropic Claude CLI、OpenAI Codex OAuth 和 API 密钥。 -## Gateway 网关：端口、“already running”和远程模式 +## Gateway 网关：端口、“已经在运行”和远程模式 - - `gateway.port` 控制单一复用端口，用于 WebSocket + HTTP（Control UI、hooks 等）。 + + `gateway.port` 控制单个复用端口，用于 WebSocket + HTTP（Control UI、hooks 等）。 优先级： @@ -2735,39 +2730,39 @@ x-i18n: - - 因为 “running” 是 **supervisor** 的视角（launchd / systemd / schtasks）。而 RPC probe 则是 CLI 实际连接到 gateway WebSocket 并调用 `status` 的结果。 + + 因为 “running” 是 **supervisor** 的视角（launchd/systemd/schtasks）。RPC probe 则是 CLI 实际去连接 Gateway 网关 WebSocket 并调用 `status`。 - 使用 `openclaw gateway status`，并重点查看以下几行： + 使用 `openclaw gateway status`，并重点看这些行： - `Probe target:`（探测实际使用的 URL） - `Listening:`（端口上实际绑定的内容） - - `Last gateway error:`（当进程还活着但端口没有监听时，常见的根因） + - `Last gateway error:`（当进程还活着但端口没有监听时，最常见的根因） - - 你编辑的是一个配置文件，而服务运行的是另一个配置文件（通常是 `--profile` / `OPENCLAW_STATE_DIR` 不匹配）。 + + 这是因为你编辑的是一个配置文件，而服务运行的是另一个配置文件（通常是 `--profile` / `OPENCLAW_STATE_DIR` 不匹配）。 - 修复方法： + 修复方式： ```bash 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 ` 运行。 + 修复方式：停止另一个实例，释放端口，或使用 `openclaw gateway --port ` 运行。 - - 设置 `gateway.mode: "remote"`，并指向远程 WebSocket URL，可选附带 shared-secret 远程凭据： + + 设置 `gateway.mode: "remote"`，并指向远程 WebSocket URL，可选地附带共享密钥远程凭证： ```json5 { @@ -2784,55 +2779,55 @@ x-i18n: 说明： - - 只有在 `gateway.mode` 为 `local` 时，`openclaw gateway` 才会启动（或者你传入覆盖标志）。 - - macOS 应用会监视配置文件，并在这些值变更时实时切换模式。 - - `gateway.remote.token` / `.password` 只是客户端侧的远程凭据；它们本身不会启用本地 gateway 认证。 + - 只有当 `gateway.mode` 为 `local` 时，`openclaw gateway` 才会启动（除非你传入覆盖标志）。 + - macOS 应用会监视配置文件，并在这些值更改时实时切换模式。 + - `gateway.remote.token` / `.password` 只是客户端侧远程凭证；它们本身不会启用本地 Gateway 网关认证。 - 你的 gateway 认证路径与 UI 使用的认证方法不匹配。 + 你的 Gateway 网关认证路径与 UI 的认证方式不匹配。 事实（来自代码）： - - Control UI 会将令牌保存在当前浏览器标签页会话和所选 gateway URL 对应的 `sessionStorage` 中，因此同一标签页刷新后仍然可以继续工作，而无需恢复长期的 `localStorage` 令牌持久化。 - - 在 `AUTH_TOKEN_MISMATCH` 时，当 gateway 返回重试提示（`canRetryWithDeviceToken=true`、`recommendedNextStep=retry_with_device_token`）时，受信任客户端可以使用缓存的设备令牌执行一次有界重试。 - - 该缓存令牌重试现在会复用与设备令牌一同存储的已批准作用域。显式 `deviceToken` / 显式 `scopes` 调用者仍会保留自己请求的作用域集合，而不是继承缓存作用域。 - - 在该重试路径之外，连接认证优先级依次为：显式 shared token / password，然后是显式 `deviceToken`，然后是已存储的设备令牌，最后是 bootstrap 令牌。 - - Bootstrap 令牌作用域检查采用角色前缀。内置的 bootstrap operator 允许列表只满足 operator 请求；节点或其他非 operator 角色仍然需要其自身角色前缀下的作用域。 + - 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。 - 修复方法： + 修复方式： - - 最快方式：`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`，然后把对应 secret 粘贴到 Control UI 设置中。 - - Tailscale Serve 模式：确保已启用 `gateway.auth.allowTailscale`，并且你打开的是 Serve URL，而不是绕过 Tailscale 身份头的原始 loopback / tailnet URL。 - - Trusted-proxy 模式：确保你是通过已配置的非 loopback 身份感知代理访问，而不是通过同主机 loopback 代理或原始 gateway URL。 - - 如果一次重试后仍然不匹配，请轮换 / 重新批准已配对设备令牌： + - 最快：`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 devices list` - `openclaw devices rotate --device --role operator` - - 如果该轮换命令提示被拒绝，请检查两点： - - 已配对设备会话只能轮换它们**自己的**设备，除非它们还具有 `operator.admin` - - 显式 `--scope` 值不能超过调用者当前的 operator 作用域 - - 还是卡住？运行 `openclaw status --all`，并按照 [故障排除](/zh-CN/gateway/troubleshooting) 操作。认证细节请参阅 [仪表板](/web/dashboard)。 + - 如果该 rotate 调用显示被拒绝，请检查两点： + - 已配对设备会话只能轮换其**自己的**设备，除非它同时拥有 `operator.admin` + - 显式 `--scope` 值不能超出调用方当前的 operator scopes + - 如果仍然卡住？运行 `openclaw status --all` 并按照 [故障排除](/zh-CN/gateway/troubleshooting) 进行检查。认证详情请参见 [Dashboard](/web/dashboard)。 - - `tailnet` bind 会从你的网络接口中选择一个 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 网关。 可以，但你必须隔离以下内容： @@ -2844,38 +2839,38 @@ x-i18n: 快速设置（推荐）： - 每个实例使用 `openclaw --profile ...`（会自动创建 `~/.openclaw-`）。 - - 在每个配置文件中设置唯一的 `gateway.port`（或在手动运行时传入 `--port`）。 - - 安装按配置文件区分的服务：`openclaw --profile gateway install`。 + - 在每个 profile 配置中设置唯一的 `gateway.port`（或手动运行时传入 `--port`）。 + - 安装按 profile 分离的服务：`openclaw --profile gateway install`。 - 配置文件还会为服务名添加后缀（`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。如果收到其他内容，它会以 + Gateway 网关是一个**WebSocket 服务器**，它期望收到的第一条消息 + 是一个 `connect` frame。如果收到其他内容，它就会以 **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` frame 中包含 token/password。 - 如果你使用的是 CLI 或 TUI，URL 应该类似： + 如果你使用的是 CLI 或 TUI，URL 应如下所示： ``` openclaw tui --url ws://:18789 --token ``` - 协议细节：[Gateway 网关 协议](/zh-CN/gateway/protocol)。 + 协议详情：[Gateway protocol](/zh-CN/gateway/protocol)。 @@ -2890,40 +2885,40 @@ x-i18n: /tmp/openclaw/openclaw-YYYY-MM-DD.log ``` - 你可以通过 `logging.file` 设置稳定路径。文件日志级别由 `logging.level` 控制。控制台详细程度由 `--verbose` 和 `logging.consoleLevel` 控制。 + 你可以通过 `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/...`；配置文件使用 `~/.openclaw-/logs/...`） + - 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，然后重启： @@ -2933,13 +2928,13 @@ x-i18n: openclaw gateway restart ``` - 如果你从未安装服务，就在前台启动它： + 如果你从未安装过服务，就以前台方式启动它： ```bash openclaw gateway run ``` - **2) 原生 Windows（不推荐）：** Gateway 网关 直接在 Windows 中运行。 + **2) 原生 Windows（不推荐）：** Gateway 网关直接运行在 Windows 中。 打开 PowerShell 并运行： @@ -2954,12 +2949,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 @@ -2970,36 +2965,36 @@ x-i18n: 常见原因： - - **Gateway 网关 主机**上没有加载模型认证（检查 `models status`）。 - - 渠道配对 / 允许列表阻止了回复（检查渠道配置 + 日志）。 - - WebChat / 仪表板打开时没有使用正确的令牌。 + - 模型认证没有加载到**Gateway 网关主机**上（检查 `models status`）。 + - 渠道配对/allowlist 阻止了回复（检查渠道配置 + 日志）。 + - WebChat/Dashboard 在未使用正确 token 的情况下被打开。 - 如果你处于远程环境，请确认隧道 / Tailscale 连接已建立，并且 - Gateway WebSocket 可达。 + 如果你是远程部署，请确认隧道/Tailscale 连接已建立，并且 + Gateway 网关 WebSocket 可达。 - 文档：[渠道](/zh-CN/channels)、[故障排除](/zh-CN/gateway/troubleshooting)、[远程访问](/zh-CN/gateway/remote)。 + 文档：[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 是否使用了正确的令牌？`openclaw dashboard` - 4. 如果是远程环境，隧道 / Tailscale 链路是否已建立？ + 1. Gateway 网关是否在运行？`openclaw gateway status` + 2. Gateway 网关是否健康？`openclaw status` + 3. UI 是否使用了正确 token？`openclaw dashboard` + 4. 如果是远程，隧道/Tailscale 链路是否正常？ - 然后查看日志尾部： + 然后跟踪日志： ```bash openclaw logs --follow ``` - 文档：[仪表板](/web/dashboard)、[远程访问](/zh-CN/gateway/remote)、[故障排除](/zh-CN/gateway/troubleshooting)。 + 文档：[Dashboard](/web/dashboard)、[Remote access](/zh-CN/gateway/remote)、[故障排除](/zh-CN/gateway/troubleshooting)。 - + 先查看日志和渠道状态： ```bash @@ -3007,19 +3002,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 上或使用代理，请确认允许出站 HTTPS，并且 `api.telegram.org` 的 DNS 正常工作。 + - `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 正常工作。 - 如果 Gateway 网关 是远程的，请确保你查看的是 Gateway 网关 主机上的日志。 + 如果 Gateway 网关是远程的，请确保你查看的是 Gateway 网关主机上的日志。 文档：[Telegram](/zh-CN/channels/telegram)、[渠道故障排除](/zh-CN/channels/troubleshooting)。 - - 先确认 Gateway 网关 可达，并且智能体可以运行： + + 先确认 Gateway 网关可达，并且智能体能够运行： ```bash openclaw status @@ -3027,14 +3022,14 @@ x-i18n: openclaw logs --follow ``` - 在 TUI 中，使用 `/status` 查看当前状态。如果你希望在聊天 - 渠道中收到回复，请确保已启用投递（`/deliver on`）。 + 在 TUI 中，使用 `/status` 查看当前状态。如果你希望在某个聊天 + 渠道中看到回复，请确保已启用投递（`/deliver on`）。 - 文档：[TUI](/web/tui)、[斜杠命令](/zh-CN/tools/slash-commands)。 + 文档：[TUI](/web/tui)、[Slash commands](/zh-CN/tools/slash-commands)。 - + 如果你安装了服务： ```bash @@ -3042,29 +3037,29 @@ 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 restart`：重启**后台服务**（launchd/systemd）。 + - `openclaw gateway`：在当前终端会话中**以前台方式**运行 Gateway 网关。 - 如果你安装了服务，请使用 gateway 命令。当你 - 想进行一次性的前台运行时，请使用 `openclaw gateway`。 + 如果你已经安装了服务，请使用这些 Gateway 网关命令。只有在 + 你想进行一次性的前台运行时，才使用 `openclaw gateway`。 - + 使用 `--verbose` 启动 Gateway 网关，以获得更详细的控制台输出。然后检查日志文件中的渠道认证、模型路由和 RPC 错误。 @@ -3072,23 +3067,23 @@ x-i18n: ## 媒体和附件 - - 来自智能体的出站附件必须包含一行 `MEDIA:`（单独成行）。请参阅 [OpenClaw 助手设置](/zh-CN/start/openclaw) 和 [智能体发送](/zh-CN/tools/agent-send)。 + + 来自智能体的出站附件必须包含一行 `MEDIA:`（单独占一行）。参见 [OpenClaw assistant setup](/zh-CN/start/openclaw) 和 [Agent send](/zh-CN/tools/agent-send)。 - CLI 发送： + CLI 发送方式： ```bash openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png ``` - 还请检查： + 还要检查： - - 目标渠道支持出站媒体，并且未被允许列表阻止。 - - 文件在提供商的大小限制内（图片会被调整到最大 2048px）。 - - `tools.fs.workspaceOnly=true` 会让本地路径发送仅限于工作区、temp / media-store 和经过沙箱校验的文件。 - - `tools.fs.workspaceOnly=false` 允许 `MEDIA:` 发送智能体已能读取的主机本地文件，但仅限媒体和安全文档类型（图片、音频、视频、PDF 和 Office 文档）。纯文本和类似 secret 的文件仍会被阻止。 + - 目标渠道支持出站媒体，并且没有被 allowlist 阻止。 + - 文件大小在提供商限制之内（图片会被缩放到最大 2048px）。 + - `tools.fs.workspaceOnly=true` 会将本地路径发送限制在工作区、temp/media-store 和通过沙箱校验的文件范围内。 + - `tools.fs.workspaceOnly=false` 允许 `MEDIA:` 发送智能体本来就能读取的主机本地文件，但仅限媒体和安全文档类型（图片、音频、视频、PDF 和 Office 文档）。纯文本和类似 secret 的文件仍会被阻止。 - 请参阅 [图片](/zh-CN/nodes/images)。 + 参见 [Images](/zh-CN/nodes/images)。 @@ -3097,72 +3092,72 @@ x-i18n: - 请将入站私信视为不受信任的输入。默认设置旨在降低风险： + 请将入站私信视为不可信输入。默认设置旨在降低风险： - - 支持私信的渠道在默认情况下使用**配对**行为： - - 未知发送者会收到一个配对码；机器人不会处理他们的消息。 + - 支持私信的渠道在默认情况下采用**配对**行为： + - 未知发送者会收到配对码；机器人不会处理他们的消息。 - 使用以下命令批准：`openclaw pairing approve --channel [--account ] ` - - 待处理请求每个渠道最多 **3 个**；如果没有收到代码，请检查 `openclaw pairing list --channel [--account ]`。 - - 公开开放私信需要显式选择加入（`dmPolicy: "open"` 和允许列表 `"*"`）。 + - 待处理请求上限为**每个渠道 3 个**；如果代码没有送达，请检查 `openclaw pairing list --channel [--account ]`。 + - 若要公开开放私信，必须显式选择启用（`dmPolicy: "open"` 且 allowlist 为 `"*"`）。 - 运行 `openclaw doctor` 以识别有风险的私信策略。 + 运行 `openclaw doctor` 可以发现有风险的私信策略。 - 不是。prompt injection 关乎的是**不受信任的内容**，而不仅仅是谁能给机器人发私信。 - 如果你的助手会读取外部内容（web 搜索 / 抓取、浏览器页面、电子邮件、 + 不是。prompt injection 关乎的是**不可信内容**，而不只是“谁能给机器人发私信”。 + 如果你的助手会读取外部内容（Web 搜索/抓取、浏览器页面、邮件、 文档、附件、粘贴的日志），这些内容就可能包含试图 - 劫持模型的指令。即使**你是唯一的发送者**，这也可能发生。 + 劫持模型的指令。即使**你是唯一的发送者**，这种情况也可能发生。 - 最大的风险出现在启用工具时：模型可能会被诱导去 - 泄露上下文或代表你调用工具。降低影响范围的方法包括： + 最大的风险在于启用了工具时：模型可能被诱导 + 代你泄露上下文或调用工具。可通过以下方式缩小影响范围： - - 使用只读或禁用工具的“阅读器”智能体来总结不受信任的内容 - - 对启用了工具的智能体关闭 `web_search` / `web_fetch` / `browser` - - 同样将解码后的文件 / 文档文本视为不受信任：OpenResponses + - 使用只读或禁用工具的“阅读器”智能体来总结不可信内容 + - 对启用工具的智能体关闭 `web_search` / `web_fetch` / `browser` + - 也将解码后的文件/文本文档视为不可信：OpenResponses `input_file` 和媒体附件提取都会将提取出的文本包装在 - 明确的外部内容边界标记中，而不是直接传递原始文件文本 - - 使用沙箱隔离和严格的工具允许列表 + 显式的外部内容边界标记中，而不是直接传递原始文件文本 + - 启用沙箱隔离并使用严格的工具 allowlist - 详情请参阅 [安全](/zh-CN/gateway/security)。 + 详情参见：[Security](/zh-CN/gateway/security)。 - 对于大多数部署来说，是的。用单独的账户和电话号码来隔离机器人 - 能在出问题时缩小影响范围。这也让你更容易轮换 - 凭据或撤销访问，而不影响你的个人账户。 + 对大多数部署而言，应该有。使用单独的账号和电话号码来隔离机器人， + 可以在出问题时缩小影响范围。这也让轮换 + 凭证或撤销访问变得更容易，而不会影响你的个人账号。 - 从小处开始。只授予你实际需要的工具和账户访问权限，必要时 - 再逐步扩大。 + 从小范围开始。只授予它你实际需要的工具和账号访问权限，之后 + 再按需扩展。 - 文档：[安全](/zh-CN/gateway/security)、[配对](/zh-CN/channels/pairing)。 + 文档：[Security](/zh-CN/gateway/security)、[Pairing](/zh-CN/channels/pairing)。 - + 我们**不**建议让它完全自主处理你的个人消息。最安全的模式是： - - 将私信保持为**配对模式**或严格的允许列表。 - - 如果你希望它代表你发消息，请使用**单独的号码或账户**。 - - 让它起草，然后在发送前**进行审批**。 + - 保持私信处于**配对模式**或严格的 allowlist 模式。 + - 如果你希望它代你发消息，请使用**单独的号码或账号**。 + - 让它先起草，然后在发送前**进行审批**。 - 如果你想尝试，请在专用账户上进行，并保持隔离。请参阅 - [安全](/zh-CN/gateway/security)。 + 如果你想尝试，请在专用账号上进行，并保持隔离。参见 + [Security](/zh-CN/gateway/security)。 - - 可以，**前提是**该智能体只用于聊天，且输入是可信的。更小档位的模型 - 更容易受到指令劫持，因此不要将它们用于启用了工具的智能体 - 或读取不受信任内容的场景。如果你必须使用更小的模型，请收紧 - 工具权限，并在沙箱中运行。请参阅 [安全](/zh-CN/gateway/security)。 + + 可以，**前提是**该智能体仅用于聊天，且输入是可信的。较小档位 + 更容易受到指令劫持，因此不要将它们用于启用工具的智能体， + 或用于读取不可信内容的场景。如果你必须使用较小模型，请锁紧 + 工具，并在沙箱中运行。参见 [Security](/zh-CN/gateway/security)。 - - 只有在未知发送者给机器人发送消息，且 - `dmPolicy: "pairing"` 已启用时，才会发送配对码。单独的 `/start` 不会生成代码。 + + 只有在未知发送者给机器人发消息且 + `dmPolicy: "pairing"` 已启用时，才会发送配对码。单独发送 `/start` 不会生成代码。 检查待处理请求： @@ -3170,12 +3165,12 @@ x-i18n: openclaw pairing list telegram ``` - 如果你想立即获得访问权限，请将你的发送者 id 加入允许列表，或为该账户设置 `dmPolicy: "open"`。 + 如果你想立即获得访问权限，请将你的发送者 id 加入 allowlist，或为该账户设置 `dmPolicy: "open"`。 - - 不会。WhatsApp 私信的默认策略是**配对**。未知发送者只会收到一个配对码，而且他们的消息**不会被处理**。OpenClaw 只会回复它收到的聊天，或你明确触发的发送。 + + 不会。WhatsApp 私信默认策略是**配对**。未知发送者只会收到一个配对码，他们的消息**不会被处理**。OpenClaw 只会回复它收到的聊天，或你显式触发的发送。 使用以下命令批准配对： @@ -3189,19 +3184,18 @@ x-i18n: openclaw pairing list whatsapp ``` - 向导中的电话号码提示用于设置你的**允许列表 / 所有者**，以便允许你自己的私信。它不会用于自动发送。如果你运行在自己的 WhatsApp 号码上，请使用该号码并启用 `channels.whatsapp.selfChatMode`。 + 向导中的电话号码提示：它用于设置你的**allowlist/owner**，这样你自己的私信才会被允许。这不会用于自动发送。如果你是在自己的个人 WhatsApp 号码上运行，请使用该号码，并启用 `channels.whatsapp.selfChatMode`。 -## 聊天命令、中止任务和“它停不下来” +## 聊天命令、中止任务，以及“它停不下来” - 大多数内部消息或工具消息只有在该会话启用了 **verbose**、**trace** 或 **reasoning** 时 - 才会出现。 + 大多数内部消息或工具消息只会在该会话启用了 **verbose**、**trace** 或 **reasoning** 时出现。 - 在你看到这些消息的聊天中修复： + 在你看到这些内容的聊天中修复： ``` /verbose off @@ -3210,15 +3204,15 @@ x-i18n: ``` 如果仍然很吵，请检查 Control UI 中的会话设置，并将 verbose - 设为 **inherit**。同时确认你没有在配置中使用将 `verboseDefault` 设为 + 设为 **inherit**。同时确认你没有使用某个在配置中将 `verboseDefault` 设为 `on` 的机器人配置文件。 - 文档：[思考和 verbose](/zh-CN/tools/thinking)、[安全](/zh-CN/gateway/security#reasoning-verbose-output-in-groups)。 + 文档：[Thinking and verbose](/zh-CN/tools/thinking)、[Security](/zh-CN/gateway/security#reasoning-verbose-output-in-groups)。 - - 发送以下任一内容，且**必须作为单独消息发送**（不要带斜杠）： + + 将以下任意内容**作为独立消息发送**（不要加斜杠）： ``` stop @@ -3242,7 +3236,7 @@ x-i18n: interrupt ``` - 这些都是中止触发词（不是斜杠命令）。 + 这些都是中止触发词（不是 slash 命令）。 对于后台进程（来自 exec 工具），你可以让智能体运行： @@ -3250,15 +3244,15 @@ x-i18n: process action:kill sessionId:XXX ``` - 斜杠命令概览：请参阅 [斜杠命令](/zh-CN/tools/slash-commands)。 + Slash 命令概览：参见 [Slash commands](/zh-CN/tools/slash-commands)。 - 大多数命令都必须作为一个**以 `/` 开头的单独消息**发送，但少数快捷方式（如 `/status`）对允许列表中的发送者也支持内联使用。 + 大多数命令都必须作为**独立**消息发送，并且以 `/` 开头，但也有少数快捷方式（如 `/status`）对 allowlist 中的发送者也支持内联使用。 - OpenClaw 默认会阻止**跨提供商**消息发送。如果某个工具调用绑定 - 到 Telegram，它就不会发送到 Discord，除非你显式允许。 + 默认情况下，OpenClaw 会阻止**跨提供商**消息发送。如果某个工具调用绑定到了 + Telegram，那么除非你显式允许，否则它不会发送到 Discord。 为该智能体启用跨提供商消息发送： @@ -3275,20 +3269,20 @@ x-i18n: } ``` - 编辑配置后，重启 gateway。 + 编辑配置后，重启 Gateway 网关。 - + 队列模式控制新消息如何与正在进行中的运行交互。使用 `/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` 这样的选项。 @@ -3296,11 +3290,11 @@ x-i18n: ## 杂项 - - 在 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`（或在认证配置文件中存储 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 凭证。 --- -如果还是卡住了？请到 [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)。