From 9d59081832cb5e370d55bb2254ea8281fd2f55d0 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Thu, 23 Apr 2026 19:33:28 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/automation/cron-jobs.md | 203 +- docs/zh-CN/channels/slack.md | 430 ++-- docs/zh-CN/cli/config.md | 112 +- docs/zh-CN/cli/infer.md | 74 +- docs/zh-CN/concepts/model-providers.md | 286 ++- docs/zh-CN/concepts/models.md | 146 +- docs/zh-CN/concepts/qa-e2e-automation.md | 144 +- docs/zh-CN/gateway/cli-backends.md | 152 +- docs/zh-CN/gateway/configuration-examples.md | 60 +- docs/zh-CN/gateway/configuration-reference.md | 1668 ++++++------- docs/zh-CN/gateway/configuration.md | 300 ++- docs/zh-CN/gateway/openai-http-api.md | 158 +- .../sandbox-vs-tool-policy-vs-elevated.md | 93 +- docs/zh-CN/help/faq.md | 2088 +++++++++-------- docs/zh-CN/help/testing.md | 953 ++++---- docs/zh-CN/install/fly.md | 186 +- docs/zh-CN/nodes/media-understanding.md | 162 +- docs/zh-CN/plugins/codex-harness.md | 247 +- docs/zh-CN/plugins/manifest.md | 369 +-- docs/zh-CN/plugins/sdk-agent-harness.md | 138 +- docs/zh-CN/providers/kilocode.md | 61 +- docs/zh-CN/providers/openai.md | 333 +-- docs/zh-CN/providers/opencode.md | 62 +- docs/zh-CN/providers/vercel-ai-gateway.md | 50 +- docs/zh-CN/refactor/qa.md | 278 +-- docs/zh-CN/reference/wizard.md | 208 +- docs/zh-CN/start/wizard-cli-automation.md | 47 +- docs/zh-CN/start/wizard-cli-reference.md | 231 +- docs/zh-CN/tools/acp-agents.md | 467 ++-- docs/zh-CN/tools/exec.md | 188 +- docs/zh-CN/tools/llm-task.md | 37 +- docs/zh-CN/tools/multi-agent-sandbox-tools.md | 113 +- docs/zh-CN/tools/slash-commands.md | 300 +-- 33 files changed, 5180 insertions(+), 5164 deletions(-) diff --git a/docs/zh-CN/automation/cron-jobs.md b/docs/zh-CN/automation/cron-jobs.md index 6fd623460..a81d7b386 100644 --- a/docs/zh-CN/automation/cron-jobs.md +++ b/docs/zh-CN/automation/cron-jobs.md @@ -1,27 +1,27 @@ --- read_when: - - 调度后台任务或唤醒操作 - - 将外部触发器（webhook、Gmail）接入 OpenClaw + - 调度后台作业或唤醒任务 + - 将外部触发器（webhooks、Gmail）接入 OpenClaw - 为计划任务决定使用 heartbeat 还是 cron -summary: 用于 Gateway 网关调度器的计划任务、webhook 和 Gmail PubSub 触发器 +summary: 用于 Gateway 网关调度器的计划任务、webhooks 和 Gmail PubSub 触发器 title: 计划任务 x-i18n: - generated_at: "2026-04-23T07:03:26Z" + generated_at: "2026-04-23T19:23:49Z" model: gpt-5.4 provider: openai - source_hash: c9565b73efc151c991ee6a1029c887c35d8673736913ddc5cdcfae09a4652f86 + source_hash: 023e8a73e028d0b5a466e9d933b8033604ba1066641cf29c8415ba9e5ac12447 source_path: automation/cron-jobs.md workflow: 15 --- # 计划任务（Cron） -Cron 是 Gateway 网关内置的调度器。它会持久化任务，在正确的时间唤醒智能体，并可将输出回传到聊天渠道或 webhook 端点。 +Cron 是 Gateway 网关内置的调度器。它会持久化作业，在正确的时间唤醒智能体，并且可以将输出回传到聊天渠道或 webhook 端点。 ## 快速开始 ```bash -# 添加一个一次性提醒 +# 添加一次性提醒 openclaw cron add \ --name "Reminder" \ --at "2026-02-01T16:00:00Z" \ @@ -30,7 +30,7 @@ openclaw cron add \ --wake now \ --delete-after-run -# 查看你的任务 +# 检查你的作业 openclaw cron list openclaw cron show @@ -40,98 +40,99 @@ openclaw cron runs --id ## Cron 的工作方式 -- Cron 在 **Gateway 网关** 进程**内部**运行（不在模型内部）。 -- 任务定义持久化保存在 `~/.openclaw/cron/jobs.json`，因此重启不会丢失调度计划。 -- 运行时执行状态保存在旁边的 `~/.openclaw/cron/jobs-state.json` 中。如果你用 git 跟踪 cron 定义，请跟踪 `jobs.json`，并将 `jobs-state.json` 加入 `.gitignore`。 -- 拆分之后，旧版 OpenClaw 可以读取 `jobs.json`，但可能会将任务视为全新任务，因为运行时字段现在位于 `jobs-state.json` 中。 +- Cron **运行在 Gateway 网关进程内部**（而不是运行在模型内部）。 +- 作业定义会持久化到 `~/.openclaw/cron/jobs.json`，因此重启不会丢失调度计划。 +- 运行时执行状态会持久化到旁边的 `~/.openclaw/cron/jobs-state.json`。如果你用 git 跟踪 cron 定义，请跟踪 `jobs.json`，并将 `jobs-state.json` 加入 `.gitignore`。 +- 在拆分之后，旧版本的 OpenClaw 仍然可以读取 `jobs.json`，但可能会将作业视为全新作业，因为运行时字段现在存放在 `jobs-state.json` 中。 - 所有 cron 执行都会创建[后台任务](/zh-CN/automation/tasks)记录。 -- 一次性任务（`--at`）默认在成功后自动删除。 -- 独立 cron 运行会在运行完成时尽力关闭其 `cron:` 会话所跟踪的浏览器标签页/进程，这样分离的浏览器自动化就不会留下孤儿进程。 -- 独立 cron 运行还会防止过时的确认回复。如果第一个结果只是中间状态更新（如 `on it`、`pulling everything together` 以及类似提示），并且没有任何后代子智能体运行仍负责最终答案，OpenClaw 会在投递前再次提示一次，以获取实际结果。 +- 一次性作业（`--at`）默认会在成功后自动删除。 +- 独立的 cron 运行会在执行完成后尽力关闭其 `cron:` 会话所跟踪的浏览器标签页/进程，因此分离式浏览器自动化不会留下孤儿进程。 +- 独立的 cron 运行还会防止过期的确认回复。如果第一个结果只是中间状态更新（例如 `on it`、`pulling everything together` 以及类似提示），并且没有任何后代子智能体运行仍负责给出最终答案，OpenClaw 会在投递前再提示一次以获取实际结果。 -Cron 的任务协调由运行时负责：只要 cron 运行时仍将该任务跟踪为正在运行，对应的活动 cron 任务就会保持存活，即使仍存在旧的子会话行记录也是如此。一旦运行时不再拥有该任务，且 5 分钟宽限期到期，维护流程就可以将该任务标记为 `lost`。 +Cron 的任务协调由运行时负责：只要 cron 运行时仍将该作业标记为正在运行，对应的活动 cron 任务就会保持存活，即使旧的子会话记录仍然存在也是如此。 +一旦运行时不再拥有该作业，并且 5 分钟宽限窗口到期，维护流程就可以将该任务标记为 `lost`。 ## 调度类型 -| 类型 | CLI 标志 | 描述 | -| ------- | -------- | --------------------------------------------------- | -| `at` | `--at` | 一次性时间戳（ISO 8601 或类似 `20m` 的相对时间） | -| `every` | `--every`| 固定间隔 | -| `cron` | `--cron` | 5 字段或 6 字段的 cron 表达式，可选搭配 `--tz` 使用 | +| 类型 | CLI 标志 | 说明 | +| ------- | -------- | -------------------------------------------------- | +| `at` | `--at` | 一次性时间戳（ISO 8601 或类似 `20m` 的相对时间） | +| `every` | `--every`| 固定间隔 | +| `cron` | `--cron` | 5 字段或 6 字段的 cron 表达式，可选配 `--tz` | 不带时区的时间戳会被视为 UTC。添加 `--tz America/New_York` 可按本地墙上时钟时间进行调度。 -循环的整点表达式会自动错开最多 5 分钟，以减少负载尖峰。使用 `--exact` 可强制精确时间，或使用 `--stagger 30s` 指定明确的错开窗口。 +每小时整点的循环表达式会自动错峰最多 5 分钟，以减少负载尖峰。使用 `--exact` 可强制精确时间，或使用 `--stagger 30s` 指定显式错峰窗口。 -### 月中的某天与星期几使用 OR 逻辑 +### day-of-month 和 day-of-week 使用 OR 逻辑 -Cron 表达式由 [croner](https://github.com/Hexagon/croner) 解析。当“月中的某天”和“星期几”字段都不是通配符时，croner 会在**任一**字段匹配时触发，而不是两个都匹配时才触发。这是标准的 Vixie cron 行为。 +Cron 表达式由 [croner](https://github.com/Hexagon/croner) 解析。当 day-of-month 和 day-of-week 字段都不是通配符时，croner 会在**任一**字段匹配时触发，而不是要求两者都匹配。这是标准的 Vixie cron 行为。 ``` -# 预期："每月 15 日上午 9 点，且仅当这一天是周一" -# 实际："每个 15 日上午 9 点，以及每个周一上午 9 点" +# 预期："15 号上午 9 点，但前提是这一天是周一" +# 实际："每个 15 号上午 9 点，外加每个周一上午 9 点" 0 9 15 * 1 ``` -这样每月会触发约 5–6 次，而不是 0–1 次。OpenClaw 在这里使用 Croner 默认的 OR 行为。若要同时要求两个条件都满足，请使用 Croner 的 `+` 星期几修饰符（`0 9 15 * +1`），或仅按一个字段调度，再在任务的提示词或命令中对另一个条件进行判断。 +这会导致它每月触发约 5–6 次，而不是每月 0–1 次。OpenClaw 在这里使用 Croner 默认的 OR 行为。若要同时要求两个条件都成立，请使用 Croner 的 `+` day-of-week 修饰符（`0 9 15 * +1`），或者只按一个字段调度，并在作业的提示词或命令中对另一个条件进行判断。 ## 执行方式 -| 方式 | `--session` 值 | 运行位置 | 最适合 | -| --------------- | ------------------- | ------------------------ | ----------------------------- | -| 主会话 | `main` | 下一次 heartbeat 轮次 | 提醒、系统事件 | -| 独立 | `isolated` | 专用 `cron:` | 报告、后台杂务 | -| 当前会话 | `current` | 绑定到创建时的会话 | 依赖上下文的循环工作 | -| 自定义会话 | `session:custom-id` | 持久化命名会话 | 基于历史逐步推进的工作流 | +| 方式 | `--session` 值 | 运行位置 | 最适合 | +| -------------- | ------------------ | ------------------------ | -------------------------- | +| 主会话 | `main` | 下一次 heartbeat 轮次 | 提醒、系统事件 | +| 独立 | `isolated` | 专用 `cron:` | 报告、后台杂务 | +| 当前会话 | `current` | 在创建时绑定 | 感知上下文的循环工作 | +| 自定义会话 | `session:custom-id`| 持久化命名会话 | 基于历史逐步累积的工作流 | -**主会话**任务会入队一个系统事件，并可选择唤醒 heartbeat（`--wake now` 或 `--wake next-heartbeat`）。**独立**任务会在一个全新会话中运行专用的智能体轮次。**自定义会话**（`session:xxx`）会在多次运行之间保留上下文，从而支持诸如基于前一天摘要继续推进的每日站会等工作流。 +**主会话**作业会排入一个系统事件，并可选择唤醒 heartbeat（`--wake now` 或 `--wake next-heartbeat`）。**独立**作业会使用一个全新的专用会话运行一次独立的智能体轮次。**自定义会话**（`session:xxx`）会在多次运行之间保留上下文，从而支持例如基于先前摘要持续累积的每日日报工作流。 -对于独立任务，运行时拆除现在包含了该 cron 会话的尽力式浏览器清理。清理失败会被忽略，以确保实际的 cron 结果仍然优先。 +对于独立作业，运行时拆除现在包含针对该 cron 会话的尽力浏览器清理。清理失败会被忽略，因此实际的 cron 结果仍然优先。 -独立 cron 运行还会通过共享的运行时清理路径，释放为该任务创建的所有内置 MCP 运行时实例。这与主会话和自定义会话的 MCP 客户端拆除方式一致，因此独立 cron 任务不会在多次运行之间泄漏 stdio 子进程或长期存活的 MCP 连接。 +独立的 cron 运行还会通过共享的运行时清理路径，释放为该作业创建的所有内置 MCP 运行时实例。这与主会话和自定义会话的 MCP 客户端拆除方式保持一致，因此独立的 cron 作业不会在多次运行之间泄漏 stdio 子进程或长期存在的 MCP 连接。 -当独立 cron 运行编排子智能体时，投递逻辑也会优先使用最终的后代输出，而不是过时的父级中间文本。如果后代仍在运行，OpenClaw 会抑制该父级的部分更新，而不是直接播报它。 +当独立的 cron 运行编排子智能体时，投递也会优先使用最终后代输出，而不是过期的父级中间文本。如果后代仍在运行，OpenClaw 会抑制该不完整的父级更新，而不是将其宣告出去。 -### 独立任务的负载选项 +### 独立作业的负载选项 -- `--message`：提示文本（独立任务必填） +- `--message`：提示文本（独立模式必需） - `--model` / `--thinking`：模型和思考级别覆盖 - `--light-context`：跳过工作区引导文件注入 -- `--tools exec,read`：限制任务可使用的工具 +- `--tools exec,read`：限制作业可使用的工具 -`--model` 会为该任务使用所选的允许模型。如果请求的模型不被允许，cron 会记录一条警告，并回退到该任务的智能体/默认模型选择。已配置的回退链仍然适用，但如果只是普通的模型覆盖，且没有显式的逐任务回退列表，就不再把智能体主模型作为隐藏的额外重试目标附加进去。 +`--model` 会为该作业使用所选的允许模型。如果请求的模型不被允许，cron 会记录一条警告，并回退到该作业的智能体/默认模型选择。已配置的回退链仍然会生效，但仅指定模型覆盖、且没有显式的按作业回退列表时，不会再把智能体主模型作为隐藏的额外重试目标附加进去。 -独立任务的模型选择优先级如下： +独立作业的模型选择优先级如下： 1. Gmail hook 模型覆盖（当运行来自 Gmail 且该覆盖被允许时） -2. 每个任务负载中的 `model` +2. 按作业负载中的 `model` 3. 已存储的 cron 会话模型覆盖 4. 智能体/默认模型选择 -快速模式也会遵循解析后的 live 选择。如果所选模型配置包含 `params.fastMode`，独立 cron 默认就会使用该设置。已存储的会话 `fastMode` 覆盖在两个方向上都仍然优先生效。 +快速模式也会遵循解析后的实时选择。如果所选模型配置包含 `params.fastMode`，独立 cron 默认会使用它。已存储的会话 `fastMode` 覆盖仍然会在任一方向上优先于配置。 -如果独立运行遇到 live 模型切换交接，cron 会使用切换后的 provider/模型重试，并在重试前持久化该 live 选择。如果切换同时携带新的凭证配置文件，cron 也会持久化该凭证配置文件覆盖。重试次数是有限的：在初始尝试加上 2 次切换重试之后，cron 会中止，而不是无限循环。 +如果独立运行遇到实时模型切换交接，cron 会使用切换后的提供商/模型重试，并在重试前持久化该实时选择。当切换同时携带新的 auth profile 时，cron 也会持久化该 auth profile 覆盖。重试是有边界的：在初始尝试再加 2 次切换重试之后，cron 会中止，而不是无限循环。 -## 投递与输出 +## 投递和输出 -| 模式 | 行为说明 | -| ---------- | ------------------------------------------------------------- | -| `announce` | 如果智能体未发送，则回退投递最终文本到目标 | -| `webhook` | 将完成事件负载以 POST 方式发送到某个 URL | -| `none` | 运行器不执行回退投递 | +| 模式 | 行为说明 | +| ---------- | ------------------------------------------------------------ | +| `announce` | 如果智能体未主动发送，则回退并将最终文本投递到目标 | +| `webhook` | 将完成事件负载以 POST 方式发送到某个 URL | +| `none` | 运行器不执行任何回退投递 | -使用 `--announce --channel telegram --to "-1001234567890"` 可投递到渠道。对于 Telegram 论坛话题，请使用 `-1001234567890:topic:123`。Slack/Discord/Mattermost 目标应使用显式前缀（`channel:`、`user:`）。 +使用 `--announce --channel telegram --to "-1001234567890"` 可投递到渠道。对于 Telegram forum topics，请使用 `-1001234567890:topic:123`。Slack/Discord/Mattermost 目标应使用显式前缀（`channel:`、`user:`）。 -对于独立任务，聊天投递是共享的。如果聊天路由可用，智能体即使在任务使用 `--no-deliver` 时也可以使用 `message` 工具。如果智能体发送到了已配置/当前目标，OpenClaw 就会跳过回退 announce。否则，`announce`、`webhook` 和 `none` 只控制运行器在智能体轮次结束后如何处理最终回复。 +对于独立作业，聊天投递是共享的。如果存在可用的聊天路由，即使作业使用了 `--no-deliver`，智能体也可以使用 `message` 工具。如果智能体发送到了已配置/当前目标，OpenClaw 会跳过回退 announce。否则，`announce`、`webhook` 和 `none` 只控制运行器在智能体轮次结束后如何处理最终回复。 失败通知遵循单独的目标路径： -- `cron.failureDestination` 设置失败通知的全局默认值。 -- `job.delivery.failureDestination` 可按任务覆盖该设置。 -- 如果两者都未设置，而该任务本身已通过 `announce` 投递，则失败通知现在会回退到该主 announce 目标。 -- `delivery.failureDestination` 仅在 `sessionTarget="isolated"` 的任务上受支持，除非主投递模式是 `webhook`。 +- `cron.failureDestination` 为失败通知设置全局默认值。 +- `job.delivery.failureDestination` 按作业覆盖该设置。 +- 如果两者都未设置，并且作业本身已通过 `announce` 投递，失败通知现在会回退到该主 announce 目标。 +- `delivery.failureDestination` 仅在 `sessionTarget="isolated"` 的作业上受支持，除非主投递模式是 `webhook`。 ## CLI 示例 @@ -146,7 +147,7 @@ openclaw cron add \ --wake now ``` -带投递的循环独立任务： +带投递的循环独立作业： ```bash openclaw cron add \ @@ -160,7 +161,7 @@ openclaw cron add \ --to "channel:C1234567890" ``` -带模型和思考覆盖的独立任务： +带模型和思考覆盖的独立作业： ```bash openclaw cron add \ @@ -176,7 +177,7 @@ openclaw cron add \ ## Webhooks -Gateway 网关可以暴露 HTTP webhook 端点，用于外部触发器。在配置中启用： +Gateway 网关可以暴露 HTTP webhook 端点以接收外部触发器。在配置中启用： ```json5 { @@ -199,7 +200,7 @@ Gateway 网关可以暴露 HTTP webhook 端点，用于外部触发器。在配 ### POST /hooks/wake -为主会话入队一个系统事件： +为主会话排入一个系统事件： ```bash curl -X POST http://127.0.0.1:18789/hooks/wake \ @@ -208,35 +209,35 @@ curl -X POST http://127.0.0.1:18789/hooks/wake \ -d '{"text":"New email received","mode":"now"}' ``` -- `text`（必填）：事件描述 +- `text`（必需）：事件描述 - `mode`（可选）：`now`（默认）或 `next-heartbeat` ### POST /hooks/agent -运行一个独立的智能体轮次： +运行一次独立的智能体轮次： ```bash curl -X POST http://127.0.0.1:18789/hooks/agent \ -H 'Authorization: Bearer SECRET' \ -H 'Content-Type: application/json' \ - -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4-mini"}' + -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.5"}' ``` -字段：`message`（必填）、`name`、`agentId`、`wakeMode`、`deliver`、`channel`、`to`、`model`、`thinking`、`timeoutSeconds`。 +字段：`message`（必需）、`name`、`agentId`、`wakeMode`、`deliver`、`channel`、`to`、`model`、`thinking`、`timeoutSeconds`。 -### 映射 hook（POST /hooks/\） +### 映射 hooks（POST /hooks/\） -自定义 hook 名称会通过配置中的 `hooks.mappings` 解析。映射可以通过模板或代码转换，将任意负载转换为 `wake` 或 `agent` 动作。 +自定义 hook 名称会通过配置中的 `hooks.mappings` 进行解析。映射可以使用模板或代码转换，将任意负载转换为 `wake` 或 `agent` 动作。 ### 安全性 -- 将 hook 端点放在 loopback、tailnet 或受信任的反向代理之后。 +- 将 hook 端点保留在 loopback、tailnet 或受信任的反向代理之后。 - 使用专用的 hook token；不要复用 gateway 身份验证 token。 -- 将 `hooks.path` 放在专用子路径下；`/` 会被拒绝。 +- 将 `hooks.path` 保持在专用子路径下；`/` 会被拒绝。 - 设置 `hooks.allowedAgentIds` 以限制显式 `agentId` 路由。 - 除非你确实需要由调用方选择会话，否则请保持 `hooks.allowRequestSessionKey=false`。 -- 如果你启用了 `hooks.allowRequestSessionKey`，也要同时设置 `hooks.allowedSessionKeyPrefixes`，以约束允许的会话键形态。 -- 默认情况下，hook 负载会被安全边界包装。 +- 如果你启用了 `hooks.allowRequestSessionKey`，还应设置 `hooks.allowedSessionKeyPrefixes` 以约束允许的会话键形状。 +- 默认情况下，hook 负载会被安全边界包裹。 ## Gmail PubSub 集成 @@ -250,11 +251,11 @@ curl -X POST http://127.0.0.1:18789/hooks/agent \ openclaw webhooks gmail setup --account openclaw@gmail.com ``` -这会写入 `hooks.gmail` 配置，启用 Gmail 预设，并使用 Tailscale Funnel 作为推送端点。 +这会写入 `hooks.gmail` 配置，启用 Gmail 预设，并为 push 端点使用 Tailscale Funnel。 ### Gateway 网关自动启动 -当 `hooks.enabled=true` 且设置了 `hooks.gmail.account` 时，Gateway 网关会在启动时启动 `gog gmail watch serve`，并自动续订 watch。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可选择退出此行为。 +当 `hooks.enabled=true` 且设置了 `hooks.gmail.account` 时，Gateway 网关会在启动时运行 `gog gmail watch serve` 并自动续订 watch。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可选择退出。 ### 手动一次性设置 @@ -266,7 +267,7 @@ gcloud config set project gcloud services enable gmail.googleapis.com pubsub.googleapis.com ``` -2. 创建主题并授予 Gmail 推送权限： +2. 创建 topic 并授予 Gmail push 访问权限： ```bash gcloud pubsub topics create gog-gmail-watch @@ -297,19 +298,19 @@ gog gmail watch start \ } ``` -## 管理任务 +## 管理作业 ```bash -# 列出所有任务 +# 列出所有作业 openclaw cron list -# 显示单个任务，包括解析后的投递路由 +# 显示单个作业，包括解析后的投递路由 openclaw cron show -# 编辑任务 +# 编辑作业 openclaw cron edit --message "Updated prompt" --model "opus" -# 立即强制运行任务 +# 立即强制运行作业 openclaw cron run # 仅在到期时运行 @@ -318,7 +319,7 @@ openclaw cron run --due # 查看运行历史 openclaw cron runs --id --limit 50 -# 删除任务 +# 删除作业 openclaw cron remove # 智能体选择（多智能体设置） @@ -328,10 +329,10 @@ openclaw cron edit --clear-agent 模型覆盖说明： -- `openclaw cron add|edit --model ...` 会更改任务所选的模型。 -- 如果该模型被允许，独立智能体运行将使用这个精确的 provider/模型。 -- 如果不被允许，cron 会发出警告，并回退到任务的智能体/默认模型选择。 -- 已配置的回退链仍然适用，但普通的 `--model` 覆盖如果没有显式的逐任务回退列表，就不再静默回落到智能体主模型作为额外的重试目标。 +- `openclaw cron add|edit --model ...` 会更改作业选定的模型。 +- 如果该模型被允许，那个确切的 provider/model 会传递给独立智能体运行。 +- 如果它不被允许，cron 会发出警告，并回退到该作业的智能体/默认模型选择。 +- 已配置的回退链仍然会生效，但单独的 `--model` 覆盖在没有显式按作业回退列表时，不会再悄悄回退到智能体主模型作为额外重试目标。 ## 配置 @@ -353,19 +354,19 @@ openclaw cron edit --clear-agent } ``` -运行时状态 sidecar 由 `cron.store` 推导而来：像 `~/clawd/cron/jobs.json` 这样的 `.json` 存储会使用 `~/clawd/cron/jobs-state.json`，而没有 `.json` 后缀的存储路径则会追加 `-state.json`。 +运行时状态 sidecar 由 `cron.store` 派生：像 `~/clawd/cron/jobs.json` 这样的 `.json` 存储会使用 `~/clawd/cron/jobs-state.json`，而没有 `.json` 后缀的存储路径则会追加 `-state.json`。 禁用 cron：`cron.enabled: false` 或 `OPENCLAW_SKIP_CRON=1`。 -**一次性任务重试**：瞬时错误（速率限制、过载、网络、服务器错误）最多重试 3 次，并使用指数退避。永久性错误会立即禁用。 +**一次性重试**：暂时性错误（速率限制、过载、网络、服务器错误）最多重试 3 次，并采用指数退避。永久性错误会立即禁用。 -**循环任务重试**：重试之间使用指数退避（30 秒到 60 分钟）。下一次成功运行后会重置退避状态。 +**循环重试**：重试之间采用指数退避（30 秒到 60 分钟）。在下一次成功运行后，退避会重置。 **维护**：`cron.sessionRetention`（默认 `24h`）会清理独立运行的会话条目。`cron.runLog.maxBytes` / `cron.runLog.keepLines` 会自动清理运行日志文件。 ## 故障排除 -### 命令排查顺序 +### 命令梯 ```bash openclaw status @@ -378,30 +379,30 @@ openclaw logs --follow openclaw doctor ``` -### Cron 未触发 +### Cron 没有触发 - 检查 `cron.enabled` 和 `OPENCLAW_SKIP_CRON` 环境变量。 -- 确认 Gateway 网关正在持续运行。 -- 对于 `cron` 调度，请核对时区（`--tz`）与主机时区是否一致。 -- 运行输出中的 `reason: not-due` 表示你通过 `openclaw cron run --due` 检查了手动运行，但该任务尚未到期。 +- 确认 Gateway 网关持续处于运行状态。 +- 对于 `cron` 调度，验证时区（`--tz`）与主机时区是否一致。 +- 运行输出中的 `reason: not-due` 表示使用 `openclaw cron run --due` 检查了手动运行，但该作业尚未到期。 ### Cron 已触发但没有投递 -- 投递模式为 `none` 表示不应期待运行器执行回退发送。如果聊天路由可用，智能体仍可通过 `message` 工具直接发送。 -- 投递目标缺失/无效（`channel`/`to`）表示已跳过出站发送。 +- 投递模式 `none` 表示不应期待运行器执行回退发送。当有可用聊天路由时，智能体仍然可以通过 `message` 工具直接发送。 +- 投递目标缺失/无效（`channel`/`to`）意味着出站发送已被跳过。 - 渠道身份验证错误（`unauthorized`、`Forbidden`）表示投递被凭证阻止。 -- 如果独立运行只返回静默 token（`NO_REPLY` / `no_reply`），OpenClaw 会抑制直接的出站投递，也会抑制回退的排队摘要路径，因此不会有任何内容发回聊天。 -- 如果智能体应自行向用户发送消息，请检查该任务是否具有可用路由（带有先前聊天记录的 `channel: "last"`，或显式的渠道/目标）。 +- 如果独立运行只返回静默 token（`NO_REPLY` / `no_reply`），OpenClaw 会抑制直接出站投递，也会抑制回退排队摘要路径，因此不会向聊天回发任何内容。 +- 如果应该由智能体自行给用户发消息，请检查该作业是否有可用路由（带有先前聊天记录的 `channel: "last"`，或显式渠道/目标）。 ### 时区注意事项 -- 不带 `--tz` 的 cron 会使用 Gateway 网关主机时区。 +- 不带 `--tz` 的 cron 使用 gateway 主机时区。 - 不带时区的 `at` 调度会被视为 UTC。 - Heartbeat 的 `activeHours` 使用已配置的时区解析。 ## 相关内容 -- [自动化与任务](/zh-CN/automation) — 一览所有自动化机制 -- [后台任务](/zh-CN/automation/tasks) — cron 执行的任务账本 -- [Heartbeat](/zh-CN/gateway/heartbeat) — 周期性的主会话轮次 -- [时区](/zh-CN/concepts/timezone) — 时区配置 +- [Automation & Tasks](/zh-CN/automation) —— 所有自动化机制总览 +- [Background Tasks](/zh-CN/automation/tasks) —— cron 执行的任务账本 +- [Heartbeat](/zh-CN/gateway/heartbeat) —— 周期性的主会话轮次 +- [Timezone](/zh-CN/concepts/timezone) —— 时区配置 diff --git a/docs/zh-CN/channels/slack.md b/docs/zh-CN/channels/slack.md index 549f82faa..7531c1de0 100644 --- a/docs/zh-CN/channels/slack.md +++ b/docs/zh-CN/channels/slack.md @@ -1,20 +1,18 @@ --- read_when: - - 设置 Slack 或调试 Slack 的 socket/HTTP 模式 + - 设置 Slack 或调试 Slack socket/HTTP 模式 summary: Slack 设置与运行时行为（Socket Mode + HTTP 请求 URL） title: Slack x-i18n: - generated_at: "2026-04-23T15:05:04Z" + generated_at: "2026-04-23T19:23:48Z" model: gpt-5.4 provider: openai - source_hash: 19d87dfc1fd655c3849fd66053826f6d054b9d3150e6321f7f7252ab8409edb8 + source_hash: 530514e9da8ff611eada0bbdd6d274c2c21c5d14cac55346641389fec065c0b4 source_path: channels/slack.md workflow: 15 --- -# Slack - -状态：可通过 Slack 应用集成在私信和渠道中投入生产使用。默认模式为 Socket Mode；也支持 HTTP 请求 URL。 +通过 Slack 应用集成即可为私信和渠道提供生产可用支持。默认模式为 Socket Mode；也支持 HTTP 请求 URL。 @@ -24,7 +22,7 @@ x-i18n: 原生命令行为和命令目录。 - 跨渠道诊断和修复操作手册。 + 跨渠道诊断与修复操作手册。 @@ -38,8 +36,8 @@ x-i18n: - 选择 **from a manifest**，并为你的应用选择一个工作区 - 粘贴下方的[示例清单](#manifest-and-scope-checklist)，然后继续创建 - - 生成一个具有 `connections:write` 权限的 **App-Level Token**（`xapp-...`） - - 安装应用并复制显示出的 **Bot Token**（`xoxb-...`） + - 生成带有 `connections:write` 权限的 **App-Level Token**（`xapp-...`） + - 安装应用，并复制显示的 **Bot Token**（`xoxb-...`） @@ -83,9 +81,9 @@ openclaw gateway 在 Slack 应用设置中，点击 **[Create New App](https://api.slack.com/apps/new)** 按钮： - 选择 **from a manifest**，并为你的应用选择一个工作区 - - 粘贴[示例清单](#manifest-and-scope-checklist)，并在创建前更新这些 URL - - 保存用于请求验证的 **Signing Secret** - - 安装应用并复制显示出的 **Bot Token**（`xoxb-...`） + - 粘贴[示例清单](#manifest-and-scope-checklist)，并在创建前更新 URL + - 保存用于请求校验的 **Signing Secret** + - 安装应用，并复制显示的 **Bot Token**（`xoxb-...`） @@ -106,9 +104,9 @@ openclaw gateway ``` - 为多账户 HTTP 使用唯一的 webhook 路径 + 对多账户 HTTP 使用唯一的 webhook 路径 - 为每个账户提供不同的 `webhookPath`（默认是 `/slack/events`），以免注册发生冲突。 + 为每个账户分配不同的 `webhookPath`（默认是 `/slack/events`），这样注册就不会冲突。 @@ -125,9 +123,9 @@ openclaw gateway -## 清单与作用域检查清单 +## 清单和 scope 检查清单 -Slack 应用的基础清单在 Socket Mode 和 HTTP 请求 URL 中相同。只有 `settings` 代码块（以及 slash command 的 `url`）不同。 +基础 Slack 应用清单在 Socket Mode 和 HTTP 请求 URL 中相同。只有 `settings` 块（以及斜杠命令的 `url`）不同。 基础清单（Socket Mode 默认）： @@ -201,7 +199,7 @@ Slack 应用的基础清单在 Socket Mode 和 HTTP 请求 URL 中相同。只 } ``` -对于 **HTTP 请求 URL 模式**，请将 `settings` 替换为 HTTP 变体，并为每个 slash command 添加 `url`。需要公开 URL： +对于 **HTTP 请求 URL 模式**，请将 `settings` 替换为 HTTP 变体，并为每个斜杠命令添加 `url`。需要公共 URL： ```json { @@ -233,17 +231,17 @@ Slack 应用的基础清单在 Socket Mode 和 HTTP 请求 URL 中相同。只 ### 其他清单设置 -展示可扩展上述默认值的不同功能。 +展示可扩展上述默认设置的不同功能。 - 可以使用多个[原生斜杠命令](#commands-and-slash-behavior)，而不是单个已配置命令，但有一些细节需要注意： + 可以使用多个[原生斜杠命令](#commands-and-slash-behavior)来替代单个已配置命令，但有一些细节需要注意： - 使用 `/agentstatus` 而不是 `/status`，因为 `/status` 命令已被保留。 - - 同时可用的斜杠命令不能超过 25 个。 + - 同时最多只能提供 25 个斜杠命令。 - 将你现有的 `features.slash_commands` 部分替换为[可用命令](/zh-CN/tools/slash-commands#command-list)的一个子集： + 请将你现有的 `features.slash_commands` 部分替换为[可用命令](/zh-CN/tools/slash-commands#command-list)中的一个子集： @@ -363,140 +361,22 @@ Slack 应用的基础清单在 Socket Mode 和 HTTP 请求 URL 中相同。只 + 使用与上方 Socket Mode 相同的 `slash_commands` 列表，并为每一项添加 `"url": "https://gateway-host.example.com/slack/events"`。示例： ```json "slash_commands": [ { "command": "/new", - "description": "开始新会话", + "description": "Start a new session", "usage_hint": "[model]", "url": "https://gateway-host.example.com/slack/events" }, - { - "command": "/reset", - "description": "重置当前会话", - "url": "https://gateway-host.example.com/slack/events" - }, - { - "command": "/compact", - "description": "压缩会话上下文", - "usage_hint": "[instructions]", - "url": "https://gateway-host.example.com/slack/events" - }, - { - "command": "/stop", - "description": "停止当前运行", - "url": "https://gateway-host.example.com/slack/events" - }, - { - "command": "/session", - "description": "管理线程绑定过期时间", - "usage_hint": "idle 或 max-age ", - "url": "https://gateway-host.example.com/slack/events" - }, - { - "command": "/think", - "description": "设置思考级别", - "usage_hint": "", - "url": "https://gateway-host.example.com/slack/events" - }, - { - "command": "/verbose", - "description": "切换详细输出", - "usage_hint": "on|off|full", - "url": "https://gateway-host.example.com/slack/events" - }, - { - "command": "/fast", - "description": "显示或设置快速模式", - "usage_hint": "[status|on|off]", - "url": "https://gateway-host.example.com/slack/events" - }, - { - "command": "/reasoning", - "description": "切换推理可见性", - "usage_hint": "[on|off|stream]", - "url": "https://gateway-host.example.com/slack/events" - }, - { - "command": "/elevated", - "description": "切换提升模式", - "usage_hint": "[on|off|ask|full]", - "url": "https://gateway-host.example.com/slack/events" - }, - { - "command": "/exec", - "description": "显示或设置 exec 默认值", - "usage_hint": "host= security= ask= node=", - "url": "https://gateway-host.example.com/slack/events" - }, - { - "command": "/model", - "description": "显示或设置模型", - "usage_hint": "[name|#|status]", - "url": "https://gateway-host.example.com/slack/events" - }, - { - "command": "/models", - "description": "列出提供商，或列出某个提供商的模型", - "usage_hint": "[provider] [page] [limit=|size=|all]", - "url": "https://gateway-host.example.com/slack/events" - }, { "command": "/help", - "description": "显示简短帮助摘要", - "url": "https://gateway-host.example.com/slack/events" - }, - { - "command": "/commands", - "description": "显示生成的命令目录", - "url": "https://gateway-host.example.com/slack/events" - }, - { - "command": "/tools", - "description": "显示当前智能体此刻可使用的内容", - "usage_hint": "[compact|verbose]", - "url": "https://gateway-host.example.com/slack/events" - }, - { - "command": "/agentstatus", - "description": "显示运行时状态，包括可用时的提供商使用量/配额", - "url": "https://gateway-host.example.com/slack/events" - }, - { - "command": "/tasks", - "description": "列出当前会话中活跃/最近的后台任务", - "url": "https://gateway-host.example.com/slack/events" - }, - { - "command": "/context", - "description": "说明上下文是如何组装的", - "usage_hint": "[list|detail|json]", - "url": "https://gateway-host.example.com/slack/events" - }, - { - "command": "/whoami", - "description": "显示你的发送者身份", - "url": "https://gateway-host.example.com/slack/events" - }, - { - "command": "/skill", - "description": "按名称运行 skill", - "usage_hint": " [input]", - "url": "https://gateway-host.example.com/slack/events" - }, - { - "command": "/btw", - "description": "在不更改会话上下文的情况下提出一个旁支问题", - "usage_hint": "", - "url": "https://gateway-host.example.com/slack/events" - }, - { - "command": "/usage", - "description": "控制 usage 页脚或显示成本摘要", - "usage_hint": "off|tokens|full|cost", + "description": "Show the short help summary", "url": "https://gateway-host.example.com/slack/events" } + // ...为每个命令重复添加相同的 `url` 值 ] ``` @@ -504,14 +384,14 @@ Slack 应用的基础清单在 Socket Mode 和 HTTP 请求 URL 中相同。只 - - 如果你希望发出的消息使用当前智能体身份（自定义用户名和图标），而不是默认的 Slack 应用身份，请添加 `chat:write.customize` bot scope。 + + 如果你希望出站消息使用当前智能体身份（自定义用户名和图标），而不是默认的 Slack 应用身份，请添加 `chat:write.customize` bot scope。 - 如果你使用 emoji 图标，Slack 要求采用 `:emoji_name:` 语法。 + 如果你使用表情符号图标，Slack 要求使用 `:emoji_name:` 语法。 - - 如果你配置了 `channels.slack.userToken`，典型的读取作用域包括： + + 如果你配置了 `channels.slack.userToken`，常见的读取 scope 包括： - `channels:history`、`groups:history`、`im:history`、`mpim:history` - `channels:read`、`groups:read`、`im:read`、`mpim:read` @@ -524,41 +404,41 @@ Slack 应用的基础清单在 Socket Mode 和 HTTP 请求 URL 中相同。只 -## 令牌模型 +## Token 模型 - Socket Mode 需要 `botToken` + `appToken`。 - HTTP 模式需要 `botToken` + `signingSecret`。 - `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文字符串或 SecretRef 对象。 -- 配置中的令牌会覆盖环境变量回退。 +- 配置中的 token 会覆盖环境变量回退值。 - `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` 环境变量回退仅适用于默认账户。 -- `userToken`（`xoxp-...`）仅支持通过配置提供（无环境变量回退），并且默认是只读行为（`userTokenReadOnly: true`）。 +- `userToken`（`xoxp-...`）仅支持通过配置提供（无环境变量回退），且默认是只读行为（`userTokenReadOnly: true`）。 状态快照行为： -- Slack 账户检查会跟踪每个凭证对应的 `*Source` 和 `*Status` 字段（`botToken`、`appToken`、`signingSecret`、`userToken`）。 -- 状态可以是 `available`、`configured_unavailable` 或 `missing`。 -- `configured_unavailable` 表示该账户通过 SecretRef 或其他非内联密钥来源进行了配置，但当前命令/运行时路径无法解析出实际值。 -- 在 HTTP 模式下，会包含 `signingSecretStatus`；在 Socket Mode 下，所需的一对状态字段是 `botTokenStatus` + `appTokenStatus`。 +- Slack 账户检查会按凭证跟踪各自的 `*Source` 和 `*Status` 字段（`botToken`、`appToken`、`signingSecret`、`userToken`）。 +- 状态值可以是 `available`、`configured_unavailable` 或 `missing`。 +- `configured_unavailable` 表示账户通过 SecretRef 或其他非内联 secret 来源完成了配置，但当前命令/运行时路径无法解析出实际值。 +- 在 HTTP 模式下，会包含 `signingSecretStatus`；在 Socket Mode 下，所需组合是 `botTokenStatus` + `appTokenStatus`。 -对于 actions/目录读取，如果配置了用户令牌，则可以优先使用它。对于写入，仍优先使用 bot 令牌；仅当 `userTokenReadOnly: false` 且 bot 令牌不可用时，才允许使用用户令牌写入。 +对于操作/目录读取，如果配置了 user token，则可以优先使用它。对于写入，仍然优先使用 bot token；只有在 `userTokenReadOnly: false` 且 bot token 不可用时，才允许使用 user-token 写入。 -## Actions 和门控 +## 操作与门控 -Slack actions 由 `channels.slack.actions.*` 控制。 +Slack 操作由 `channels.slack.actions.*` 控制。 -当前 Slack 工具中可用的 action 分组： +当前 Slack 工具中的可用操作组： -| Group | Default | +| 组 | 默认值 | | ---------- | ------- | -| messages | enabled | -| reactions | enabled | -| pins | enabled | -| memberInfo | enabled | -| emojiList | enabled | +| messages | 已启用 | +| reactions | 已启用 | +| pins | 已启用 | +| memberInfo | 已启用 | +| emojiList | 已启用 | -当前 Slack 消息 actions 包括 `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info` 和 `emoji-list`。 +当前 Slack 消息操作包括 `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info` 和 `emoji-list`。 ## 访问控制与路由 @@ -577,12 +457,12 @@ Slack actions 由 `channels.slack.actions.*` 控制。 - `channels.slack.allowFrom`（推荐） - `dm.allowFrom`（旧版） - `dm.groupEnabled`（群组私信默认 false） - - `dm.groupChannels`（可选的 MPIM allowlist） + - `dm.groupChannels`（可选 MPIM allowlist） 多账户优先级： - `channels.slack.accounts.default.allowFrom` 仅适用于 `default` 账户。 - - 当命名账户自己的 `allowFrom` 未设置时，会继承 `channels.slack.allowFrom`。 + - 当命名账户自身未设置 `allowFrom` 时，会继承 `channels.slack.allowFrom`。 - 命名账户不会继承 `channels.slack.accounts.default.allowFrom`。 在私信中进行配对时，使用 `openclaw pairing approve slack `。 @@ -598,26 +478,26 @@ Slack actions 由 `channels.slack.actions.*` 控制。 渠道 allowlist 位于 `channels.slack.channels` 下，并且应使用稳定的渠道 ID。 - 运行时说明：如果 `channels.slack` 完全缺失（仅环境变量设置），运行时会回退到 `groupPolicy="allowlist"` 并记录一条警告（即使设置了 `channels.defaults.groupPolicy` 也是如此）。 + 运行时说明：如果 `channels.slack` 完全缺失（仅环境变量设置），运行时会回退为 `groupPolicy="allowlist"` 并记录一条警告（即使设置了 `channels.defaults.groupPolicy` 也是如此）。 名称/ID 解析： - - 当令牌访问权限允许时，渠道 allowlist 条目和私信 allowlist 条目会在启动时解析 - - 无法解析的渠道名称条目会按配置保留，但默认会在路由中被忽略 - - 入站授权和渠道路由默认采用 ID 优先；直接用户名/slug 匹配需要 `channels.slack.dangerouslyAllowNameMatching: true` + - 渠道 allowlist 条目和私信 allowlist 条目会在启动时、在 token 访问权限允许的情况下进行解析 + - 无法解析的渠道名称条目会按配置保留，但默认不会参与路由 + - 入站授权和渠道路由默认优先按 ID 处理；直接用户名/slug 匹配需要 `channels.slack.dangerouslyAllowNameMatching: true` - - 渠道消息默认受提及门控。 + + 默认情况下，渠道消息受 mention 门控控制。 - 提及来源： + mention 来源： - 显式应用提及（`<@botId>`） - - 提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） - - 隐式回复给 bot 的线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用） + - mention 正则模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） + - 隐式回复机器人线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用） - 每渠道控制（`channels.slack.channels.`；名称仅通过启动解析或 `dangerouslyAllowNameMatching` 支持）： + 每渠道控制（`channels.slack.channels.`；名称仅通过启动时解析或 `dangerouslyAllowNameMatching` 支持）： - `requireMention` - `users`（allowlist） @@ -626,37 +506,37 @@ Slack actions 由 `channels.slack.actions.*` 控制。 - `systemPrompt` - `tools`、`toolsBySender` - `toolsBySender` 键格式：`id:`、`e164:`、`username:`、`name:` 或 `"*"` 通配符 - （旧版无前缀键仍仅映射到 `id:`） + （旧版无前缀键仍然只映射到 `id:`） -## 线程、会话和回复标签 +## 线程、会话与回复标签 - 私信路由为 `direct`；渠道路由为 `channel`；MPIM 路由为 `group`。 - 使用默认 `session.dmScope=main` 时，Slack 私信会折叠到智能体主会话。 - 渠道会话：`agent::slack:channel:`。 -- 在线程回复适用时，可以创建带线程会话后缀的回复（`:thread:`）。 +- 在线程回复适用时，可以创建带线程会话后缀（`:thread:`）的会话。 - `channels.slack.thread.historyScope` 默认为 `thread`；`thread.inheritParent` 默认为 `false`。 -- `channels.slack.thread.initialHistoryLimit` 控制新线程会话开始时抓取多少现有线程消息（默认 `20`；设为 `0` 可禁用）。 -- `channels.slack.thread.requireExplicitMention`（默认 `false`）：当设为 `true` 时，会抑制隐式线程提及，因此 bot 即使已经参与了线程，也只会响应线程中的显式 `@bot` 提及。若不启用此项，在 bot 已参与的线程中进行回复时会绕过 `requireMention` 门控。 +- `channels.slack.thread.initialHistoryLimit` 控制新线程会话启动时要抓取多少条现有线程消息（默认 `20`；设为 `0` 可禁用）。 +- `channels.slack.thread.requireExplicitMention`（默认 `false`）：设为 `true` 时，会抑制隐式线程提及，因此机器人即使已经参与该线程，也只会响应线程内显式的 `@bot` 提及。不启用此项时，在机器人已参与的线程中的回复会绕过 `requireMention` 门控。 回复线程控制： - `channels.slack.replyToMode`：`off|first|all|batched`（默认 `off`） -- `channels.slack.replyToModeByChatType`：按 `direct|group|channel` 分别设置 -- 私聊的旧版回退：`channels.slack.dm.replyToMode` +- `channels.slack.replyToModeByChatType`：按 `direct|group|channel` +- 直聊旧版回退：`channels.slack.dm.replyToMode` 支持手动回复标签： - `[[reply_to_current]]` - `[[reply_to:]]` -注意：`replyToMode="off"` 会禁用 Slack 中**所有**回复线程行为，包括显式 `[[reply_to_*]]` 标签。这与 Telegram 不同；在 Telegram 中，即使在 `"off"` 模式下，显式标签仍会被遵循——Slack 线程会将消息隐藏在渠道视图之外，而 Telegram 回复仍以内联形式可见。 +注意：`replyToMode="off"` 会禁用 Slack 中**所有**回复线程功能，包括显式 `[[reply_to_*]]` 标签。这与 Telegram 不同，在 Telegram 中，即使在 `"off"` 模式下，显式标签仍会生效——Slack 线程会把消息隐藏在渠道中，而 Telegram 回复仍以内联形式可见。 ## Ack reactions -`ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认 emoji。 +`ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认表情。 解析顺序： @@ -668,7 +548,7 @@ Slack actions 由 `channels.slack.actions.*` 控制。 说明： - Slack 期望使用短代码（例如 `"eyes"`）。 -- 使用 `""` 可为 Slack 账户或全局禁用该 reaction。 +- 使用 `""` 可为某个 Slack 账户或全局禁用该 reaction。 ## 文本流式传输 @@ -676,18 +556,18 @@ Slack actions 由 `channels.slack.actions.*` 控制。 - `off`：禁用实时预览流式传输。 - `partial`（默认）：用最新的部分输出替换预览文本。 -- `block`：追加分块的预览更新。 -- `progress`：在生成期间显示进度状态文本，然后发送最终文本。 +- `block`：追加分块预览更新。 +- `progress`：生成期间显示进度状态文本，然后发送最终文本。 - `streaming.preview.toolProgress`：当草稿预览启用时，将工具/进度更新路由到同一条被编辑的预览消息中（默认：`true`）。设为 `false` 可保留单独的工具/进度消息。 -`channels.slack.streaming.nativeTransport` 控制当 `channels.slack.streaming.mode` 为 `partial` 时 Slack 原生文本流式传输的行为（默认：`true`）。 +当 `channels.slack.streaming.mode` 为 `partial` 时，`channels.slack.streaming.nativeTransport` 控制 Slack 原生文本流式传输（默认：`true`）。 -- 必须有可用的回复线程，Slack 原生文本流式传输和 Slack assistant 线程状态才会显示。线程选择仍遵循 `replyToMode`。 +- 必须有可用的回复线程，才能显示原生文本流式传输和 Slack assistant 线程状态。线程选择仍遵循 `replyToMode`。 - 当原生流式传输不可用时，渠道和群聊根消息仍可使用普通草稿预览。 -- 顶层 Slack 私信默认保持非线程模式，因此不会显示线程样式的预览；如果你希望在那里看到可见进度，请使用线程回复或 `typingReaction`。 +- 顶层 Slack 私信默认保持非线程状态，因此不会显示线程式预览；如果你希望在那里看到可见进度，请使用线程回复或 `typingReaction`。 - 媒体和非文本负载会回退到普通投递。 -- 媒体/错误类最终消息会取消待处理的预览编辑；符合条件的文本/块最终消息仅会在能够原地编辑预览时刷新。 -- 如果流式传输在回复中途失败，OpenClaw 会对剩余负载回退为普通投递。 +- 媒体/错误最终消息会取消待处理的预览编辑；符合条件的文本/块最终消息只有在可以原地编辑预览时才会刷新。 +- 如果流式传输在回复过程中失败，OpenClaw 会对剩余负载回退到普通投递。 使用草稿预览而不是 Slack 原生文本流式传输： @@ -704,15 +584,15 @@ Slack actions 由 `channels.slack.actions.*` 控制。 } ``` -旧版键名： +旧版键： - `channels.slack.streamMode`（`replace | status_final | append`）会自动迁移到 `channels.slack.streaming.mode`。 -- 布尔型 `channels.slack.streaming` 会自动迁移到 `channels.slack.streaming.mode` 和 `channels.slack.streaming.nativeTransport`。 +- 布尔值 `channels.slack.streaming` 会自动迁移到 `channels.slack.streaming.mode` 和 `channels.slack.streaming.nativeTransport`。 - 旧版 `channels.slack.nativeStreaming` 会自动迁移到 `channels.slack.streaming.nativeTransport`。 ## Typing reaction 回退 -`typingReaction` 会在 OpenClaw 处理回复期间为入站 Slack 消息添加一个临时 reaction，并在运行结束后将其移除。这在线程回复之外尤其有用，因为线程回复会使用默认的“正在输入...”状态指示器。 +`typingReaction` 会在 OpenClaw 处理回复期间，给入站 Slack 消息添加一个临时 reaction，并在运行结束时移除它。这在非线程回复场景中特别有用，因为线程回复会使用默认的 “is typing...” 状态指示器。 解析顺序： @@ -722,39 +602,39 @@ Slack actions 由 `channels.slack.actions.*` 控制。 说明： - Slack 期望使用短代码（例如 `"hourglass_flowing_sand"`）。 -- 该 reaction 属于尽力而为，回复完成或失败路径结束后会自动尝试清理。 +- 该 reaction 采用尽力而为方式，回复完成或失败路径结束后会自动尝试清理。 ## 媒体、分块与投递 - Slack 文件附件会从 Slack 托管的私有 URL 下载（基于令牌认证的请求流程），并在抓取成功且大小限制允许时写入媒体存储。 + Slack 文件附件会从 Slack 托管的私有 URL 下载（基于 token 认证的请求流程），并在抓取成功且大小限制允许时写入媒体存储。 - 运行时入站大小上限默认是 `20MB`，除非通过 `channels.slack.mediaMaxMb` 覆盖。 + 运行时入站大小上限默认为 `20MB`，除非被 `channels.slack.mediaMaxMb` 覆盖。 - + - 文本分块使用 `channels.slack.textChunkLimit`（默认 4000） - `channels.slack.chunkMode="newline"` 启用按段落优先拆分 - 文件发送使用 Slack 上传 API，并可包含线程回复（`thread_ts`） - - 配置了 `channels.slack.mediaMaxMb` 时，出站媒体上限遵循该值；否则渠道发送使用媒体流水线中的 MIME 类型默认值 + - 出站媒体上限在配置了 `channels.slack.mediaMaxMb` 时遵循该值；否则渠道发送使用媒体管道中的 MIME 类型默认值 推荐的显式目标： - - 私信使用 `user:` - - 渠道使用 `channel:` + - 私信用 `user:` + - 渠道用 `channel:` - 向用户目标发送时，Slack 私信会通过 Slack conversation API 打开。 + 当向用户目标发送时，Slack 私信会通过 Slack 会话 API 打开。 -## 命令与 slash 行为 +## 命令与斜杠行为 -Slack 中的 slash command 可以表现为单个已配置命令，或多个原生命令。配置 `channels.slack.slashCommand` 可更改命令默认值： +斜杠命令在 Slack 中会显示为单个已配置命令或多个原生命令。配置 `channels.slack.slashCommand` 可更改命令默认值： - `enabled: false` - `name: "openclaw"` @@ -765,30 +645,30 @@ Slack 中的 slash command 可以表现为单个已配置命令，或多个原 /openclaw /help ``` -原生命令需要你在 Slack 应用中配置[其他清单设置](#additional-manifest-settings)，并通过 `channels.slack.commands.native: true` 或全局配置中的 `commands.native: true` 启用。 +原生命令需要在你的 Slack 应用中进行[其他清单设置](#additional-manifest-settings)，并通过 `channels.slack.commands.native: true` 或全局配置中的 `commands.native: true` 启用。 -- 对于 Slack，原生命令自动模式默认是 **off**，因此 `commands.native: "auto"` 不会启用 Slack 原生命令。 +- 对 Slack 而言，原生命令自动模式默认**关闭**，因此 `commands.native: "auto"` 不会启用 Slack 原生命令。 ```txt /help ``` -原生参数菜单使用自适应渲染策略，在分发所选选项值之前会先显示确认模态框： +原生参数菜单使用自适应渲染策略，会在分发所选选项值之前显示确认模态框： - 最多 5 个选项：按钮块 - 6-100 个选项：静态选择菜单 -- 超过 100 个选项：当可用 interactivity 选项处理器时，使用带异步选项过滤的外部选择 -- 超出 Slack 限制时：已编码的选项值会回退为按钮 +- 超过 100 个选项：如果可用 interactivity 选项处理器，则使用带异步选项过滤的外部选择 +- 超出 Slack 限制：编码后的选项值会回退为按钮 ```txt /think ``` -slash 会话使用类似 `agent::slack:slash:` 的隔离键，但仍会通过 `CommandTargetSessionKey` 将命令执行路由到目标对话会话。 +斜杠会话使用类似 `agent::slack:slash:` 的隔离键，但仍会通过 `CommandTargetSessionKey` 将命令执行路由到目标对话会话。 ## 交互式回复 -Slack 可以渲染由智能体编写的交互式回复控件，但此功能默认禁用。 +Slack 可以渲染由智能体编写的交互式回复控件，但此功能默认关闭。 全局启用： @@ -804,7 +684,7 @@ Slack 可以渲染由智能体编写的交互式回复控件，但此功能默 } ``` -或仅为某个 Slack 账户启用： +或者仅为一个 Slack 账户启用： ```json5 { @@ -822,39 +702,39 @@ Slack 可以渲染由智能体编写的交互式回复控件，但此功能默 } ``` -启用后，智能体可以发出仅适用于 Slack 的回复指令： +启用后，智能体可以输出仅限 Slack 的回复指令： - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` -这些指令会编译为 Slack Block Kit，并将点击或选择通过现有的 Slack 交互事件路径路由回来。 +这些指令会编译为 Slack Block Kit，并将点击或选择通过现有 Slack 交互事件路径路由回来。 说明： -- 这是 Slack 专用 UI。其他渠道不会将 Slack Block Kit 指令转换为自己的按钮系统。 -- 交互回调值是 OpenClaw 生成的不透明令牌，而不是智能体编写的原始值。 -- 如果生成的交互块会超出 Slack Block Kit 限制，OpenClaw 会回退为原始文本回复，而不是发送无效的 blocks 负载。 +- 这是 Slack 特有的 UI。其他渠道不会将 Slack Block Kit 指令转换为它们自己的按钮系统。 +- 交互式回调值是 OpenClaw 生成的不透明 token，不是智能体原始编写的值。 +- 如果生成的交互块会超出 Slack Block Kit 限制，OpenClaw 会回退到原始文本回复，而不是发送无效的块负载。 -## Slack 中的 exec 审批 +## Slack 中的 Exec 审批 Slack 可以作为原生审批客户端，使用交互式按钮和交互，而不是回退到 Web UI 或终端。 - Exec 审批使用 `channels.slack.execApprovals.*` 进行原生私信/渠道路由。 -- 如果请求已经落在 Slack 中且审批 ID 类型为 `plugin:`，插件审批仍可通过同一套 Slack 原生按钮界面完成。 -- 审批人授权仍会被强制执行：只有被识别为审批人的用户才能通过 Slack 批准或拒绝请求。 +- 当请求已经到达 Slack 且审批 ID 类型为 `plugin:` 时，插件审批仍可通过同一个 Slack 原生按钮界面进行处理。 +- 审批人授权仍然会被强制执行：只有被识别为审批人的用户才能通过 Slack 批准或拒绝请求。 -这使用与其他渠道相同的共享审批按钮界面。当你的 Slack 应用设置中启用了 `interactivity` 时，审批提示会直接以 Block Kit 按钮形式渲染在对话中。 +这使用与其他渠道相同的共享审批按钮界面。当你的 Slack 应用设置中启用了 `interactivity` 时，审批提示会直接在对话中渲染为 Block Kit 按钮。 当这些按钮存在时，它们就是主要的审批 UX；只有当工具结果表明聊天审批不可用，或手动审批是唯一途径时，OpenClaw 才应包含手动 `/approve` 命令。 配置路径： - `channels.slack.execApprovals.enabled` -- `channels.slack.execApprovals.approvers`（可选；尽可能回退到 `commands.ownerAllowFrom`） +- `channels.slack.execApprovals.approvers`（可选；在可能时回退到 `commands.ownerAllowFrom`） - `channels.slack.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`） - `agentFilter`、`sessionFilter` -当 `enabled` 未设置或为 `"auto"`，且至少解析出一名审批人时，Slack 会自动启用原生 exec 审批。将 `enabled: false` 设为显式禁用 Slack 作为原生审批客户端。 +当 `enabled` 未设置或为 `"auto"`，且至少解析出一个审批人时，Slack 会自动启用原生 exec 审批。将 `enabled: false` 设为显式禁用 Slack 作为原生审批客户端。 将 `enabled: true` 设为在审批人可解析时强制启用原生审批。 在没有显式 Slack exec 审批配置时的默认行为： @@ -867,7 +747,7 @@ Slack 可以作为原生审批客户端，使用交互式按钮和交互，而 } ``` -只有当你想覆盖审批人、添加过滤器或选择将消息投递到来源聊天时，才需要显式 Slack 原生配置： +只有在你想覆盖审批人、添加过滤器，或选择加入源聊天投递时，才需要显式 Slack 原生配置： ```json5 { @@ -883,42 +763,43 @@ Slack 可以作为原生审批客户端，使用交互式按钮和交互，而 } ``` -共享 `approvals.exec` 转发是独立的。仅当 exec 审批提示还必须路由到其他聊天或显式带外目标时才使用它。共享 `approvals.plugin` 转发也是独立的；当这些请求已落在 Slack 中时，Slack 原生按钮仍可处理插件审批。 +共享 `approvals.exec` 转发是独立的。仅当 exec 审批提示还必须路由到其他聊天或显式带外目标时才使用它。共享 `approvals.plugin` 转发也是独立的；当这些请求已经到达 Slack 时，Slack 原生按钮仍然可以处理插件审批。 -同聊天中的 `/approve` 也适用于已经支持命令的 Slack 渠道和私信。完整的审批转发模型请参见[Exec approvals](/zh-CN/tools/exec-approvals)。 +同一聊天中的 `/approve` 在已经支持命令的 Slack 渠道和私信中也可用。完整的审批转发模型请参见 [Exec approvals](/zh-CN/tools/exec-approvals)。 ## 事件与运行行为 - 消息编辑/删除/线程广播会映射为系统事件。 - reaction 添加/移除事件会映射为系统事件。 - 成员加入/离开、渠道创建/重命名，以及 pin 添加/移除事件会映射为系统事件。 -- 当启用了 `configWrites` 时，`channel_id_changed` 可以迁移渠道配置键。 -- 渠道 topic/purpose 元数据被视为不受信任的上下文，并可注入到路由上下文中。 -- 在线程发起者和初始线程历史上下文植入过程中，会在适用时按已配置的发送者 allowlist 进行过滤。 -- Block action 和模态交互会发出结构化的 `Slack interaction: ...` 系统事件，并携带丰富的负载字段： - - block action：选中值、标签、选择器值，以及 `workflow_*` 元数据 - - 模态 `view_submission` 和 `view_closed` 事件，带有已路由的渠道元数据和表单输入 +- 当启用 `configWrites` 时，`channel_id_changed` 可以迁移渠道配置键。 +- 渠道 topic/purpose 元数据被视为不可信上下文，并可注入路由上下文。 +- 在线程发起者和初始线程历史上下文播种中，当适用时会根据已配置的发送者 allowlist 进行过滤。 +- 块操作和模态交互会发出结构化的 `Slack interaction: ...` 系统事件，并带有丰富的负载字段： + - 块操作：所选值、标签、选择器值以及 `workflow_*` 元数据 + - 模态 `view_submission` 和 `view_closed` 事件，带有路由后的渠道元数据和表单输入 -## 配置参考指引 +## 配置参考 -主要参考： +主参考： [配置参考 - Slack](/zh-CN/gateway/configuration-reference#slack)。 -- [配置参考 - Slack](/zh-CN/gateway/configuration-reference#slack) + - 高信号 Slack 字段： - - 模式/认证：`mode`、`botToken`、`appToken`、`signingSecret`、`webhookPath`、`accounts.*` - - 私信访问：`dm.enabled`、`dmPolicy`、`allowFrom`（旧版：`dm.policy`、`dm.allowFrom`）、`dm.groupEnabled`、`dm.groupChannels` - - 兼容性开关：`dangerouslyAllowNameMatching`（紧急兜底；除非确有需要，否则保持关闭） - - 渠道访问：`groupPolicy`、`channels.*`、`channels.*.users`、`channels.*.requireMention` - - 线程/历史：`replyToMode`、`replyToModeByChatType`、`thread.*`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` - - 投递：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`streaming`、`streaming.nativeTransport`、`streaming.preview.toolProgress` - - 运维/功能：`configWrites`、`commands.native`、`slashCommand.*`、`actions.*`、`userToken`、`userTokenReadOnly` +- mode/auth：`mode`、`botToken`、`appToken`、`signingSecret`、`webhookPath`、`accounts.*` +- 私信访问：`dm.enabled`、`dmPolicy`、`allowFrom`（旧版：`dm.policy`、`dm.allowFrom`）、`dm.groupEnabled`、`dm.groupChannels` +- 兼容性开关：`dangerouslyAllowNameMatching`（紧急兜底开关；除非必要否则保持关闭） +- 渠道访问：`groupPolicy`、`channels.*`、`channels.*.users`、`channels.*.requireMention` +- 线程/历史记录：`replyToMode`、`replyToModeByChatType`、`thread.*`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit` +- 投递：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`streaming`、`streaming.nativeTransport`、`streaming.preview.toolProgress` +- 运维/功能：`configWrites`、`commands.native`、`slashCommand.*`、`actions.*`、`userToken`、`userTokenReadOnly` + + ## 故障排除 - 按顺序检查： + 请按顺序检查： - `groupPolicy` - 渠道 allowlist（`channels.slack.channels`） @@ -948,47 +829,58 @@ openclaw pairing list slack - - 验证 bot + app 令牌，以及 Slack 应用设置中是否启用了 Socket Mode。 + + 验证 bot token、app token 以及 Slack 应用设置中的 Socket Mode 是否已启用。 如果 `openclaw channels status --probe --json` 显示 `botTokenStatus` 或 - `appTokenStatus: "configured_unavailable"`，则说明 Slack 账户 - 已完成配置，但当前运行时无法解析由 SecretRef 支持的 - 实际值。 + `appTokenStatus: "configured_unavailable"`，说明 Slack 账户已完成配置， + 但当前运行时无法解析由 SecretRef 支持的实际值。 - + 验证： - signing secret - webhook 路径 - - Slack 请求 URL（Events + Interactivity + Slash Commands） + - Slack Request URL（Events + Interactivity + Slash Commands） - 每个 HTTP 账户使用唯一的 `webhookPath` 如果账户快照中出现 `signingSecretStatus: "configured_unavailable"`， - 则说明该 HTTP 账户已完成配置，但当前运行时无法 - 解析由 SecretRef 支持的 signing secret 实际值。 + 说明 HTTP 账户已完成配置，但当前运行时无法解析由 SecretRef 支持的 signing secret。 - - 验证你是否本意要使用： + + 确认你原本想使用的是： - - 原生命令模式（`channels.slack.commands.native: true`），并确保已在 Slack 中注册匹配的 slash command - - 或单个 slash command 模式（`channels.slack.slashCommand.enabled: true`） + - 原生命令模式（`channels.slack.commands.native: true`），并且在 Slack 中注册了匹配的斜杠命令 + - 或单斜杠命令模式（`channels.slack.slashCommand.enabled: true`） - 还要检查 `commands.useAccessGroups` 以及渠道/用户 allowlist。 + 同时检查 `commands.useAccessGroups` 以及渠道/用户 allowlist。 ## 相关内容 -- [配对](/zh-CN/channels/pairing) -- [群组](/zh-CN/channels/groups) -- [安全性](/zh-CN/gateway/security) -- [渠道路由](/zh-CN/channels/channel-routing) -- [故障排除](/zh-CN/channels/troubleshooting) -- [配置](/zh-CN/gateway/configuration) -- [斜杠命令](/zh-CN/tools/slash-commands) + + + 将 Slack 用户与 Gateway 网关配对。 + + + 渠道和群组私信行为。 + + + 将入站消息路由到智能体。 + + + 威胁模型与加固。 + + + 配置布局与优先级。 + + + 命令目录与行为。 + + diff --git a/docs/zh-CN/cli/config.md b/docs/zh-CN/cli/config.md index 530781213..209e9bbcd 100644 --- a/docs/zh-CN/cli/config.md +++ b/docs/zh-CN/cli/config.md @@ -4,23 +4,23 @@ read_when: summary: '`openclaw config` 的 CLI 参考（get/set/unset/file/schema/validate）' title: 配置 x-i18n: - generated_at: "2026-04-23T18:44:46Z" + generated_at: "2026-04-23T19:23:47Z" model: gpt-5.4 provider: openai - source_hash: c3b08d4f288cb00021509817e8552370bcf326b0f70b49abf8c26d6508801aab + source_hash: ec16221cc977eb2108c4310eab6b49e74220de50425ab12201cf97d275ab5a65 source_path: cli/config.md workflow: 15 --- # `openclaw config` -用于在 `openclaw.json` 中进行非交互式编辑的配置辅助命令：按路径获取/设置/取消设置/输出文件/输出 schema/验证值，并打印当前生效的配置文件。不带子命令运行时，会打开配置向导（与 `openclaw configure` 相同）。 +用于在 `openclaw.json` 中进行非交互式编辑的配置辅助工具：按路径获取/设置/取消设置/file/schema/validate 值，并打印当前生效的配置文件。不带子命令运行时，会打开配置向导（与 `openclaw configure` 相同）。 根选项： - `--section
`：当你在不带子命令的情况下运行 `openclaw config` 时，可重复使用的引导式设置分区过滤器 -支持的引导式分区： +支持的引导分区： - `workspace` - `model` @@ -43,7 +43,7 @@ openclaw config get browser.executablePath openclaw config set browser.executablePath "/usr/bin/google-chrome" openclaw config set agents.defaults.heartbeat.every "2h" openclaw config set agents.list[0].tools.exec.node "node-id-or-name" -openclaw config set agents.defaults.models '{"openai-codex/gpt-5.4":{}}' --strict-json --merge +openclaw config set agents.defaults.models '{"openai-codex/gpt-5.5":{}}' --strict-json --merge openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN openclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode json openclaw config unset plugins.entries.brave.config.webSearch.apiKey @@ -54,26 +54,26 @@ openclaw config validate --json ### `config schema` -将为 `openclaw.json` 生成的 JSON schema 以 JSON 形式输出到 stdout。 +将为 `openclaw.json` 生成的 JSON schema 以 JSON 形式打印到 stdout。 -其包含内容： +它包含： -- 当前根配置 schema，以及一个用于编辑器工具的根 `$schema` 字符串字段 +- 当前的根配置 schema，以及一个用于编辑器工具的根 `$schema` 字符串字段 - Control UI 使用的字段 `title` 和 `description` 文档元数据 -- 嵌套对象、通配符（`*`）和数组项（`[]`）节点，在存在匹配字段文档时会继承相同的 `title` / `description` 元数据 -- `anyOf` / `oneOf` / `allOf` 分支在存在匹配字段文档时也会继承相同的文档元数据 -- 在可加载运行时清单时，尽力提供实时的 plugin 和渠道 schema 元数据 -- 即使当前配置无效，也会提供一个干净的后备 schema +- 当存在匹配的字段文档时，嵌套对象、通配符（`*`）和数组项（`[]`）节点会继承相同的 `title` / `description` 元数据 +- 当存在匹配的字段文档时，`anyOf` / `oneOf` / `allOf` 分支也会继承相同的文档元数据 +- 当可以加载运行时清单时，尽力提供实时的插件 + 渠道 schema 元数据 +- 即使当前配置无效，也会提供一个干净的回退 schema 相关运行时 RPC： -- `config.schema.lookup` 会返回一个标准化后的配置路径，以及一个浅层 schema 节点（`title`、`description`、`type`、`enum`、`const`、常见边界）、匹配的 UI 提示元数据和直接子项摘要。可用于 Control UI 或自定义客户端中按路径范围逐层查看。 +- `config.schema.lookup` 返回一个标准化的配置路径，其中包含一个浅层 schema 节点（`title`、`description`、`type`、`enum`、`const`、常见边界）、匹配到的 UI 提示元数据以及直接子项摘要。可将其用于 Control UI 或自定义客户端中的路径范围钻取。 ```bash openclaw config schema ``` -如果你想用其他工具检查或验证它，可以将其导入文件： +当你想用其他工具检查或验证它时，可将其输出到文件： ```bash openclaw config schema > openclaw.schema.json @@ -97,7 +97,7 @@ openclaw config set agents.list[1].tools.exec.node "node-id-or-name" ## 值 -值会尽可能按 JSON5 解析；否则会被视为字符串。使用 `--strict-json` 可强制要求进行 JSON5 解析。`--json` 仍然作为旧别名受支持。 +值会尽可能按 JSON5 解析；否则会被视为字符串。使用 `--strict-json` 可强制要求进行 JSON5 解析。`--json` 仍作为旧版别名受支持。 ```bash openclaw config set agents.defaults.heartbeat.every "0m" @@ -105,18 +105,18 @@ openclaw config set gateway.port 19001 --strict-json openclaw config set channels.whatsapp.groups '["*"]' --strict-json ``` -`config get --json` 会将原始值以 JSON 形式输出，而不是输出终端格式化文本。 +`config get --json` 会将原始值作为 JSON 打印，而不是终端格式化文本。 -默认情况下，对象赋值会替换目标路径。对于常用于保存用户添加条目的受保护映射/列表路径，例如 `agents.defaults.models`、`models.providers`、`models.providers..models`、`plugins.entries` 和 `auth.profiles`，如果替换操作会删除现有条目，则会被拒绝，除非你传入 `--replace`。 +默认情况下，对象赋值会替换目标路径。对那些通常保存用户添加条目的受保护映射/列表路径，例如 `agents.defaults.models`、`models.providers`、`models.providers..models`、`plugins.entries` 和 `auth.profiles`，如果替换会删除现有条目，则会拒绝执行，除非你传入 `--replace`。 -向这些映射中添加条目时，请使用 `--merge`： +向这些映射添加条目时，请使用 `--merge`： ```bash -openclaw config set agents.defaults.models '{"openai-codex/gpt-5.4":{}}' --strict-json --merge +openclaw config set agents.defaults.models '{"openai-codex/gpt-5.5":{}}' --strict-json --merge openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge ``` -仅当你明确希望所提供的值成为完整目标值时，才使用 `--replace`。 +仅当你明确希望提供的值成为完整目标值时，才使用 `--replace`。 ## `config set` 模式 @@ -164,12 +164,12 @@ openclaw config set --batch-file ./config-set.batch.json --dry-run 策略说明： -- 在不支持运行时可变更的表面上，SecretRef 赋值会被拒绝（例如 `hooks.token`、`commands.ownerDisplaySecret`、Discord 线程绑定 webhook token，以及 WhatsApp creds JSON）。参见 [SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface)。 +- 在不受支持的运行时可变表面上，SecretRef 赋值会被拒绝（例如 `hooks.token`、`commands.ownerDisplaySecret`、Discord 线程绑定 webhook token，以及 WhatsApp creds JSON）。参见 [SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface)。 -批处理解析始终将批处理负载（`--batch-json`/`--batch-file`）视为唯一真实来源。 +批处理解析始终将批处理载荷（`--batch-json`/`--batch-file`）作为事实来源。 `--strict-json` / `--json` 不会改变批处理解析行为。 -JSON 路径/值模式对 SecretRef 和提供商也同样受支持： +JSON 路径/值模式对 SecretRefs 和提供商都仍受支持： ```bash openclaw config set channels.discord.token \ @@ -190,7 +190,7 @@ openclaw config set secrets.providers.vaultfile \ - `--provider-source ` - `--provider-timeout-ms `（`file`、`exec`） -Env 提供商（`--provider-source env`）： +环境提供商（`--provider-source env`）： - `--provider-allowlist `（可重复） @@ -214,7 +214,7 @@ Exec 提供商（`--provider-source exec`）： - `--provider-allow-insecure-path` - `--provider-allow-symlink-command` -加固后的 exec 提供商示例： +加固的 Exec 提供商示例： ```bash openclaw config set secrets.providers.vault \ @@ -228,9 +228,9 @@ openclaw config set secrets.providers.vault \ --provider-timeout-ms 5000 ``` -## Dry run +## 试运行 -使用 `--dry-run` 在不写入 `openclaw.json` 的情况下验证更改。 +使用 `--dry-run` 可在不写入 `openclaw.json` 的情况下验证更改。 ```bash openclaw config set channels.discord.token \ @@ -254,25 +254,25 @@ openclaw config set channels.discord.token \ --allow-exec ``` -Dry-run 行为： +试运行行为： -- 构建器模式：对已更改的 ref/提供商运行 SecretRef 可解析性检查。 +- 构建器模式：对已更改的 refs/providers 运行 SecretRef 可解析性检查。 - JSON 模式（`--strict-json`、`--json` 或批处理模式）：运行 schema 验证以及 SecretRef 可解析性检查。 -- 对已知不受支持的 SecretRef 目标表面也会运行策略验证。 -- 策略检查会评估更改后的完整配置，因此写入父对象（例如将 `hooks` 设置为对象）不能绕过不受支持表面的验证。 -- 为避免命令副作用，dry-run 期间默认会跳过 Exec SecretRef 检查。 -- 若要启用 exec SecretRef 检查，请在 `--dry-run` 时同时使用 `--allow-exec`（这可能会执行提供商命令）。 -- `--allow-exec` 仅可用于 dry-run；如果未配合 `--dry-run` 使用则会报错。 +- 对已知不受支持的 SecretRef 目标表面，也会运行策略验证。 +- 策略检查会评估变更后的完整配置，因此写入父对象（例如将 `hooks` 设置为对象）无法绕过不受支持表面的验证。 +- 为避免命令副作用，试运行期间默认会跳过 Exec SecretRef 检查。 +- 使用 `--allow-exec` 搭配 `--dry-run` 可选择启用 Exec SecretRef 检查（这可能会执行提供商命令）。 +- `--allow-exec` 仅适用于试运行；如果未搭配 `--dry-run` 使用则会报错。 -`--dry-run --json` 会输出机器可读报告： +`--dry-run --json` 会打印机器可读的报告： -- `ok`：dry-run 是否通过 +- `ok`：试运行是否通过 - `operations`：已评估的赋值数量 - `checks`：是否运行了 schema/可解析性检查 -- `checks.resolvabilityComplete`：可解析性检查是否完整运行完毕（当跳过 exec refs 时为 false） -- `refsChecked`：dry-run 期间实际已解析的 ref 数量 -- `skippedExecRefs`：因未设置 `--allow-exec` 而跳过的 exec ref 数量 -- `errors`：当 `ok=false` 时的结构化 schema/可解析性失败信息 +- `checks.resolvabilityComplete`：可解析性检查是否完整执行（当跳过 exec refs 时为 false） +- `refsChecked`：试运行期间实际解析的 ref 数量 +- `skippedExecRefs`：由于未设置 `--allow-exec` 而跳过的 exec ref 数量 +- `errors`：当 `ok=false` 时，结构化的 schema/可解析性失败信息 ### JSON 输出结构 @@ -293,7 +293,7 @@ Dry-run 行为： { kind: "schema" | "resolvability", message: string, - ref?: string, // 出现可解析性错误时存在 + ref?: string, // 对于可解析性错误时存在 }, ], } @@ -342,20 +342,20 @@ Dry-run 行为： } ``` -如果 dry-run 失败： +如果试运行失败： -- `config schema validation failed`：更改后的配置结构无效；请修正路径/值或提供商/ref 对象结构。 +- `config schema validation failed`：你变更后的配置结构无效；请修复路径/值或 provider/ref 对象结构。 - `Config policy validation failed: unsupported SecretRef usage`：请将该凭证移回明文/字符串输入，并仅在受支持的表面上使用 SecretRefs。 -- `SecretRef assignment(s) could not be resolved`：当前引用的提供商/ref 无法解析（缺少环境变量、文件指针无效、exec 提供商失败，或提供商/来源不匹配）。 -- `Dry run note: skipped exec SecretRef resolvability check(s)`：dry-run 跳过了 exec refs；如果你需要验证 exec 可解析性，请使用 `--allow-exec` 重新运行。 -- 对于批处理模式，请修复失败的条目，然后在写入前重新运行 `--dry-run`。 +- `SecretRef assignment(s) could not be resolved`：被引用的 provider/ref 当前无法解析（缺少环境变量、文件指针无效、exec 提供商失败，或 provider/source 不匹配）。 +- `Dry run note: skipped exec SecretRef resolvability check(s)`：试运行跳过了 exec refs；如果你需要验证 exec 可解析性，请使用 `--allow-exec` 重新运行。 +- 对于批处理模式，请修复失败条目，并在写入前重新运行 `--dry-run`。 ## 写入安全 -`openclaw config set` 和其他由 OpenClaw 管理的配置写入器，会在提交到磁盘前验证完整的更改后配置。如果新负载未通过 schema 验证，或看起来像是破坏性的覆盖，当前生效的配置将保持不变，被拒绝的负载会保存到其旁边，命名为 `openclaw.json.rejected.*`。 -当前生效的配置路径必须是常规文件。不支持通过符号链接形式的 `openclaw.json` 布局进行写入；请改用 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。 +`openclaw config set` 和其他由 OpenClaw 管理的配置写入器，在将完整的变更后配置提交到磁盘前，会先进行验证。如果新载荷未通过 schema 验证，或看起来像是破坏性覆盖，则当前生效的配置会保持不变，而被拒绝的载荷会保存在其旁边，命名为 `openclaw.json.rejected.*`。 +生效配置路径必须是常规文件。写入不支持使用符号链接形式的 `openclaw.json` 布局；请改用 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。 -对于小范围编辑，优先使用 CLI 写入： +小型编辑建议优先使用 CLI 写入： ```bash openclaw config set gateway.reload.mode hybrid --dry-run @@ -363,7 +363,7 @@ openclaw config set gateway.reload.mode hybrid openclaw config validate ``` -如果写入被拒绝，请检查已保存的负载并修正完整配置结构： +如果写入被拒绝，请检查保存的载荷并修复完整配置结构： ```bash CONFIG="$(openclaw config file)" @@ -371,7 +371,7 @@ ls -lt "$CONFIG".rejected.* 2>/dev/null | head openclaw config validate ``` -仍然允许直接使用编辑器写入，但正在运行的 Gateway 网关 会在这些更改通过验证之前将其视为不可信。无效的直接编辑可能会在启动或热重载期间，从“最后一次已知正常”的备份中恢复。参见 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。 +仍然允许直接使用编辑器写入，但正在运行的 Gateway 网关会在这些更改通过验证前将其视为不受信任。无效的直接编辑可在启动或热重载期间从最后一次已知正常的备份中恢复。参见 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。 ## 子命令 @@ -379,7 +379,7 @@ openclaw config validate 编辑后请重启 Gateway 网关。 -## 验证 +## validate 在不启动 Gateway 网关的情况下，根据当前生效的 schema 验证当前配置。 @@ -388,9 +388,9 @@ openclaw config validate openclaw config validate --json ``` -当 `openclaw config validate` 通过后，你可以使用本地 TUI，让一个内嵌智能体在同一终端中，在你验证每一项更改时，对照文档比较当前生效配置： +当 `openclaw config validate` 通过后，你可以使用本地 TUI，让一个内嵌智能体在你从同一个终端验证每项更改时，将当前生效的配置与文档进行对比： -如果验证已经失败，请先从 `openclaw configure` 或 `openclaw doctor --fix` 开始。`openclaw chat` 不会绕过无效配置保护机制。 +如果当前验证已经失败，请先使用 `openclaw configure` 或 `openclaw doctor --fix`。`openclaw chat` 不会绕过无效配置保护。 ```bash openclaw chat @@ -407,7 +407,7 @@ openclaw chat 典型修复流程： -- 让智能体将你当前的配置与相关文档页面进行比较，并建议最小修复方案。 +- 让智能体将你当前的配置与相关文档页面进行对比，并建议最小化修复方案。 - 使用 `openclaw config set` 或 `openclaw configure` 应用有针对性的编辑。 - 每次更改后重新运行 `openclaw config validate`。 -- 如果验证通过但运行时仍然不健康，请运行 `openclaw doctor` 或 `openclaw doctor --fix` 以获取迁移和修复帮助。 +- 如果验证通过但运行时仍不健康，请运行 `openclaw doctor` 或 `openclaw doctor --fix` 以获取迁移和修复帮助。 diff --git a/docs/zh-CN/cli/infer.md b/docs/zh-CN/cli/infer.md index a82874a78..a192b3798 100644 --- a/docs/zh-CN/cli/infer.md +++ b/docs/zh-CN/cli/infer.md @@ -2,40 +2,40 @@ read_when: - 添加或修改 `openclaw infer` 命令 - 设计稳定的无头能力自动化 -summary: 面向由提供商支持的模型、图像、音频、TTS、视频、网页和嵌入工作流的推理优先 CLI +summary: 面向由提供商支持的模型、图像、音频、TTS、视频、网页和嵌入工作流的 infer-first CLI title: 推理 CLI x-i18n: - generated_at: "2026-04-23T06:17:43Z" + generated_at: "2026-04-23T19:23:49Z" model: gpt-5.4 provider: openai - source_hash: e57d2438d0da24e1ed880bbacd244ede4af56beba4ac1baa3f2a1e393e641c9c + source_hash: a80407deae51d7443244f6bb45b2a197aca7aec838f6526b3755fa4109ae7e81 source_path: cli/infer.md workflow: 15 --- # 推理 CLI -`openclaw infer` 是由提供商支持的推理工作流的规范无头界面。 +`openclaw infer` 是用于由提供商支持的推理工作流的规范无头界面。 -它刻意暴露的是能力族，而不是原始 Gateway 网关 RPC 名称，也不是原始智能体工具 id。 +它有意公开的是能力家族，而不是原始 Gateway 网关 RPC 名称，也不是原始智能体工具 id。 -## 将 infer 变成一个 skill +## 将 infer 变成一个技能 -把下面内容复制并粘贴给一个智能体： +将以下内容复制并粘贴给一个智能体： ```text Read https://docs.openclaw.ai/cli/infer, then create a skill that routes my common workflows to `openclaw infer`. Focus on model runs, image generation, video generation, audio transcription, TTS, web search, and embeddings. ``` -一个良好的基于 infer 的 skill 应该： +一个好的基于 infer 的技能应当： - 将常见用户意图映射到正确的 infer 子命令 - 为其覆盖的工作流包含一些规范的 infer 示例 - 在示例和建议中优先使用 `openclaw infer ...` -- 避免在 skill 正文中重新记录整个 infer 界面 +- 避免在技能正文中重新记录整个 infer 界面 -典型的面向 infer 的 skill 覆盖范围： +典型的面向 infer 的技能覆盖范围： - `openclaw infer model run` - `openclaw infer image generate` @@ -46,15 +46,15 @@ Focus on model runs, image generation, video generation, audio transcription, TT ## 为什么使用 infer -`openclaw infer` 为 OpenClaw 中由提供商支持的推理任务提供了一套统一的 CLI。 +`openclaw infer` 为 OpenClaw 中由提供商支持的推理任务提供了一个统一的 CLI。 优点： -- 使用 OpenClaw 中已经配置好的提供商和模型，而不是为每个后端分别接入一次性封装。 -- 将模型、图像、音频转录、TTS、视频、网页和嵌入工作流统一到一个命令树下。 -- 为脚本、自动化和智能体驱动的工作流提供稳定的 `--json` 输出结构。 +- 使用已经在 OpenClaw 中配置好的提供商和模型，而不是为每个后端单独编写一次性封装。 +- 将模型、图像、音频转录、TTS、视频、网页和嵌入工作流统一在一个命令树下。 +- 为脚本、自动化和智能体驱动的工作流使用稳定的 `--json` 输出结构。 - 当任务本质上是“运行推理”时，优先使用 OpenClaw 的第一方界面。 -- 大多数 infer 命令都可以使用常规本地路径，而不要求 Gateway 网关参与。 +- 对于大多数 infer 命令，使用常规本地路径而无需依赖 Gateway 网关。 ## 命令树 @@ -112,46 +112,46 @@ Focus on model runs, image generation, video generation, audio transcription, TT 下表将常见推理任务映射到对应的 infer 命令。 | 任务 | 命令 | 说明 | -| ---- | ---- | ---- | -| 运行文本 / 模型提示 | `openclaw infer model run --prompt "..." --json` | 默认使用常规本地路径 | -| 生成图像 | `openclaw infer image generate --prompt "..." --json` | 如果从现有文件开始，使用 `image edit` | +| ----------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------- | +| 运行文本/模型提示词 | `openclaw infer model run --prompt "..." --json` | 默认使用常规本地路径 | +| 生成图像 | `openclaw infer image generate --prompt "..." --json` | 从现有文件开始时请使用 `image edit` | | 描述图像文件 | `openclaw infer image describe --file ./image.png --json` | `--model` 必须是支持图像的 `` | | 转录音频 | `openclaw infer audio transcribe --file ./memo.m4a --json` | `--model` 必须是 `` | | 合成语音 | `openclaw infer tts convert --text "..." --output ./speech.mp3 --json` | `tts status` 面向 Gateway 网关 | | 生成视频 | `openclaw infer video generate --prompt "..." --json` | | | 描述视频文件 | `openclaw infer video describe --file ./clip.mp4 --json` | `--model` 必须是 `` | | 搜索网页 | `openclaw infer web search --query "..." --json` | | -| 获取网页内容 | `openclaw infer web fetch --url https://example.com --json` | | +| 获取网页 | `openclaw infer web fetch --url https://example.com --json` | | | 创建嵌入 | `openclaw infer embedding create --text "..." --json` | | ## 行为 - `openclaw infer ...` 是这些工作流的主要 CLI 界面。 -- 当输出将被另一个命令或脚本消费时，请使用 `--json`。 -- 当需要特定后端时，使用 `--provider` 或 `--model provider/model`。 +- 当输出会被其他命令或脚本消费时，请使用 `--json`。 +- 当需要特定后端时，请使用 `--provider` 或 `--model provider/model`。 - 对于 `image describe`、`audio transcribe` 和 `video describe`，`--model` 必须使用 `` 形式。 -- 对于 `image describe`，显式指定 `--model` 会直接运行该提供商 / 模型。该模型必须在模型目录或提供商配置中具备图像能力。 -- 无状态执行命令默认走本地路径。 -- 由 Gateway 网关管理状态的命令默认走 Gateway 网关路径。 -- 常规本地路径不要求 Gateway 网关正在运行。 +- 对于 `image describe`，显式指定 `--model` 会直接运行该提供商/模型。该模型必须在模型目录或提供商配置中具备图像能力。 +- 无状态执行命令默认走本地。 +- 由 Gateway 网关管理状态的命令默认走 Gateway 网关。 +- 常规本地路径不要求 Gateway 网关处于运行状态。 ## Model -使用 `model` 进行由提供商支持的文本推理，以及模型 / 提供商检查。 +使用 `model` 进行由提供商支持的文本推理，以及模型/提供商检查。 ```bash openclaw infer model run --prompt "Reply with exactly: smoke-ok" --json openclaw infer model run --prompt "Summarize this changelog entry" --provider openai --json openclaw infer model providers --json -openclaw infer model inspect --name gpt-5.4 --json +openclaw infer model inspect --name gpt-5.5 --json ``` 说明： -- `model run` 会复用智能体运行时，因此提供商 / 模型覆盖的行为与常规智能体执行一致。 +- `model run` 会复用智能体运行时，因此提供商/模型覆盖行为与常规智能体执行一致。 - `model auth login`、`model auth logout` 和 `model auth status` 用于管理已保存的提供商认证状态。 -## 图像 +## Image 使用 `image` 进行生成、编辑和描述。 @@ -165,11 +165,11 @@ openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --j 说明： -- 当从现有输入文件开始时，使用 `image edit`。 +- 从现有输入文件开始时，请使用 `image edit`。 - 对于 `image describe`，`--model` 必须是支持图像的 ``。 -- 对于本地 Ollama 视觉模型，请先拉取模型，并将 `OLLAMA_API_KEY` 设置为任意占位值，例如 `ollama-local`。参见 [Ollama](/zh-CN/providers/ollama#vision-and-image-description)。 +- 对于本地 Ollama 视觉模型，请先拉取模型，并将 `OLLAMA_API_KEY` 设为任意占位值，例如 `ollama-local`。参见 [Ollama](/zh-CN/providers/ollama#vision-and-image-description)。 -## 音频 +## Audio 使用 `audio` 进行文件转录。 @@ -200,7 +200,7 @@ openclaw infer tts status --json - `tts status` 默认走 Gateway 网关，因为它反映的是由 Gateway 网关管理的 TTS 状态。 - 使用 `tts providers`、`tts voices` 和 `tts set-provider` 来检查和配置 TTS 行为。 -## 视频 +## Video 使用 `video` 进行生成和描述。 @@ -215,7 +215,7 @@ openclaw infer video describe --file ./clip.mp4 --model openai/gpt-4.1-mini --js - 对于 `video describe`，`--model` 必须是 ``。 -## 网页 +## Web 使用 `web` 进行搜索和抓取工作流。 @@ -228,9 +228,9 @@ openclaw infer web providers --json 说明： -- 使用 `web providers` 检查可用、已配置和已选定的提供商。 +- 使用 `web providers` 来检查可用、已配置和已选定的提供商。 -## 嵌入 +## Embedding 使用 `embedding` 进行向量创建和嵌入提供商检查。 @@ -242,7 +242,7 @@ openclaw infer embedding providers --json ## JSON 输出 -Infer 命令会在共享封装结构下统一 JSON 输出： +Infer 命令会在共享封装下规范化 JSON 输出： ```json { diff --git a/docs/zh-CN/concepts/model-providers.md b/docs/zh-CN/concepts/model-providers.md index d24782efd..cb79d461b 100644 --- a/docs/zh-CN/concepts/model-providers.md +++ b/docs/zh-CN/concepts/model-providers.md @@ -1,96 +1,94 @@ --- read_when: - - 你需要一份按提供商逐项整理的模型设置参考文档 + - 你需要一份按提供商划分的模型设置参考资料 - 你想要模型提供商的示例配置或 CLI 新手引导命令 summary: 模型提供商概览，包含示例配置 + CLI 流程 title: 模型提供商 x-i18n: - generated_at: "2026-04-23T16:30:10Z" + generated_at: "2026-04-23T19:23:50Z" model: gpt-5.4 provider: openai - source_hash: 29fcf755be64658ed7ff2489ec3fa828f6bb848a63646f341529a3d3f332c12b + source_hash: bdbb8deae102c8e55d4535ddb14b8eadb999c123cb6d188ebe563971bed762fc source_path: concepts/model-providers.md workflow: 15 --- # 模型提供商 -本页介绍的是 **LLM/模型提供商**（不是像 WhatsApp/Telegram 这样的聊天渠道）。 -关于模型选择规则，参见 [/concepts/models](/zh-CN/concepts/models)。 +本页介绍 **LLM / 模型提供商**（而不是像 WhatsApp / Telegram 这样的聊天渠道）。 +有关模型选择规则，请参见 [/concepts/models](/zh-CN/concepts/models)。 ## 快速规则 -- 模型引用使用 `provider/model`（示例：`opencode/claude-opus-4-6`）。 -- 设置后，`agents.defaults.models` 会作为允许列表使用。 +- 模型引用使用 `provider/model`（例如：`opencode/claude-opus-4-6`）。 +- 设置后，`agents.defaults.models` 会作为允许列表。 - CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set `。 -- `models.providers.*.models[].contextWindow` 是模型原生元数据；`contextTokens` 是运行时实际生效的上限。 -- 回退规则、冷却探测和会话覆盖持久化：参见 [模型故障转移](/zh-CN/concepts/model-failover)。 -- 内置的 `codex` 与 Codex 智能体 harness 配对使用 —— 对于由 Codex 管理的登录、发现、原生线程恢复和 app-server 执行，请使用 `codex/gpt-*`。普通的 `openai/gpt-*` 使用 OpenAI 提供商和常规传输。对于仅 Codex 的部署，可通过 `agents.defaults.embeddedHarness.fallback: "none"` 禁用自动的 PI 回退 —— 参见 [Codex harness](/zh-CN/plugins/codex-harness)。 +- `models.providers.*.models[].contextWindow` 是模型原生元数据；`contextTokens` 是运行时生效的上限。 +- 回退规则、冷却探测和会话覆盖持久化：参见 [模型故障切换](/zh-CN/concepts/model-failover)。 +- 内置的 `codex` 与 Codex 智能体 harness 配套使用 —— 使用 `codex/gpt-*` 可获得由 Codex 管理的登录、发现、原生线程恢复和应用服务器执行。普通的 `openai/gpt-*` 使用 OpenAI 提供商和常规传输。对于仅使用 Codex 的部署，可通过 `agents.defaults.embeddedHarness.fallback: "none"` 禁用自动 PI 回退 —— 参见 [Codex harness](/zh-CN/plugins/codex-harness)。 -## 由插件负责的提供商行为 +## 由插件拥有的提供商行为 -大多数提供商特定逻辑都位于提供商插件中（`registerProvider(...)`），而 OpenClaw 保持通用推理循环。插件负责新手引导、模型目录、身份验证环境变量映射、传输/配置规范化、工具模式清理、故障转移分类、OAuth 刷新、用量上报、thinking/reasoning 配置文件等内容。 +大多数提供商特定逻辑都位于提供商插件中（`registerProvider(...)`），而 OpenClaw 保留通用推理循环。插件负责新手引导、模型目录、认证环境变量映射、传输 / 配置标准化、工具模式清理、故障切换分类、OAuth 刷新、使用情况报告、thinking / reasoning 配置文件等。 -提供商 SDK 钩子与内置插件示例的完整列表见 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)。如果某个提供商需要完全自定义的请求执行器，则属于另一种更深层的扩展接口。 +Provider SDK hook 的完整列表以及内置插件示例位于 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)。如果某个提供商需要完全自定义的请求执行器，则属于另一个更深层的扩展接口。 -提供商运行时 `capabilities` 是共享运行器元数据（提供商家族、transcript/tooling 特性、传输/缓存提示）。它不同于[公开能力模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是插件注册了什么能力（文本推理、语音等）。 +提供商运行时 `capabilities` 是共享的运行器元数据（提供商系列、转录 / 工具特性、传输 / 缓存提示）。它与[公开能力模型](/zh-CN/plugins/architecture#public-capability-model)不同，后者描述的是插件注册了什么（文本推理、语音等）。 ## API 密钥轮换 -- 支持为选定提供商进行通用密钥轮换。 +- 支持为选定提供商进行通用提供商轮换。 - 通过以下方式配置多个密钥： - - `OPENCLAW_LIVE__KEY`（单个实时覆盖，优先级最高） + - `OPENCLAW_LIVE__KEY`（单个实时覆盖，最高优先级） - `_API_KEYS`（逗号或分号分隔的列表） - `_API_KEY`（主密钥） - `_API_KEY_*`（编号列表，例如 `_API_KEY_1`） -- 对于 Google 提供商，还会将 `GOOGLE_API_KEY` 作为回退项。 -- 密钥选择顺序会保留优先级并去重。 -- 仅在收到速率限制响应时，请求才会使用下一个密钥重试（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性用量限制消息）。 +- 对于 Google 提供商，还会将 `GOOGLE_API_KEY` 作为回退项包含在内。 +- 密钥选择顺序会保留优先级，并对值去重。 +- 仅在遇到速率限制响应时，才会使用下一个密钥重试请求（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性使用上限消息）。 - 非速率限制失败会立即失败；不会尝试密钥轮换。 - 当所有候选密钥都失败时，将返回最后一次尝试的最终错误。 ## 内置提供商（pi-ai 目录） -OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** -`models.providers` 配置；只需设置身份验证并选择模型即可。 +OpenClaw 自带 pi‑ai 目录。这些提供商**不需要** +`models.providers` 配置；只需设置认证信息并选择模型。 ### OpenAI - 提供商：`openai` -- 身份验证：`OPENAI_API_KEY` +- 认证：`OPENAI_API_KEY` - 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单个覆盖） -- 示例模型：`openai/gpt-5.4`、`openai/gpt-5.4-pro` +- 示例模型：`openai/gpt-5.5`、`openai/gpt-5.5-pro` - CLI：`openclaw onboard --auth-choice openai-api-key` - 默认传输为 `auto`（优先 WebSocket，回退到 SSE） - 可按模型通过 `agents.defaults.models["openai/"].params.transport` 覆盖（`"sse"`、`"websocket"` 或 `"auto"`） -- OpenAI Responses WebSocket 预热默认启用，通过 `params.openaiWsWarmup` 控制（`true`/`false`） +- OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup` 启用（`true` / `false`） - 可通过 `agents.defaults.models["openai/"].params.serviceTier` 启用 OpenAI 优先级处理 -- `/fast` 和 `params.fastMode` 会将直接的 `openai/*` Responses 请求映射到 `api.openai.com` 上的 `service_tier=priority` -- 当你需要显式层级而不是共享的 `/fast` 开关时，请使用 `params.serviceTier` -- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、 - `User-Agent`）仅应用于发往 `api.openai.com` 的原生 OpenAI 流量，不应用于通用 OpenAI 兼容代理 -- 原生 OpenAI 路由还会保留 Responses 的 `store`、prompt-cache 提示以及 - OpenAI reasoning 兼容负载整形；代理路由则不会 -- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意屏蔽，因为实时 OpenAI API 会拒绝它；Spark 被视为仅限 Codex +- `/fast` 和 `params.fastMode` 会将直接的 `openai/*` Responses 请求映射为发往 `api.openai.com` 的 `service_tier=priority` +- 当你想使用显式层级而不是共享的 `/fast` 开关时，请使用 `params.serviceTier` +- 隐藏的 OpenClaw 归因头（`originator`、`version`、`User-Agent`）仅适用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用的 OpenAI 兼容代理 +- 原生 OpenAI 路由还会保留 Responses `store`、prompt-cache 提示以及 OpenAI reasoning 兼容载荷整形；代理路由不会 +- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意隐藏，因为实时 OpenAI API 会拒绝它；Spark 被视为仅供 Codex 使用 ```json5 { - agents: { defaults: { model: { primary: "openai/gpt-5.4" } } }, + agents: { defaults: { model: { primary: "openai/gpt-5.5" } } }, } ``` ### Anthropic - 提供商：`anthropic` -- 身份验证：`ANTHROPIC_API_KEY` +- 认证：`ANTHROPIC_API_KEY` - 可选轮换：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_KEY`（单个覆盖） - 示例模型：`anthropic/claude-opus-4-6` - CLI：`openclaw onboard --auth-choice apiKey` -- 直接的公共 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API 密钥和 OAuth 身份验证流量；OpenClaw 会将其映射到 Anthropic 的 `service_tier`（`auto` 与 `standard_only`） -- Anthropic 说明：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 会将 Claude CLI 复用和 `claude -p` 用法视为此集成的受支持方式。 -- Anthropic setup-token 仍然作为受支持的 OpenClaw token 路径提供，但 OpenClaw 现在在可用时更优先选择 Claude CLI 复用和 `claude -p`。 +- 直接面向公开 Anthropic 的请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API 密钥认证和 OAuth 认证流量；OpenClaw 会将其映射为 Anthropic `service_tier`（`auto` 与 `standard_only`） +- Anthropic 说明：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 使用再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 会将 Claude CLI 复用和 `claude -p` 用法视为该集成的获准方式。 +- Anthropic setup-token 仍然作为受支持的 OpenClaw token 路径保留可用，但现在 OpenClaw 在可用时更倾向于 Claude CLI 复用和 `claude -p`。 ```json5 { @@ -101,23 +99,21 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** ### OpenAI Code（Codex） - 提供商：`openai-codex` -- 身份验证：OAuth（ChatGPT） -- 示例模型：`openai-codex/gpt-5.4` +- 认证：OAuth（ChatGPT） +- 示例模型：`openai-codex/gpt-5.5` - CLI：`openclaw onboard --auth-choice openai-codex` 或 `openclaw models auth login --provider openai-codex` - 默认传输为 `auto`（优先 WebSocket，回退到 SSE） - 可按模型通过 `agents.defaults.models["openai-codex/"].params.transport` 覆盖（`"sse"`、`"websocket"` 或 `"auto"`） -- `params.serviceTier` 也会在原生 Codex Responses 请求（`chatgpt.com/backend-api`）上转发 -- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、 - `User-Agent`）仅附加到发往 - `chatgpt.com/backend-api` 的原生 Codex 流量，不附加到通用 OpenAI 兼容代理 -- 它与直接的 `openai/*` 共享相同的 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射为 `service_tier=priority` +- `params.serviceTier` 也会在原生 Codex Responses 请求（`chatgpt.com/backend-api`）中透传 +- 隐藏的 OpenClaw 归因头（`originator`、`version`、`User-Agent`）仅附加在发往 `chatgpt.com/backend-api` 的原生 Codex 流量上，不适用于通用的 OpenAI 兼容代理 +- 与直接的 `openai/*` 共用同一个 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射为 `service_tier=priority` - 当 Codex OAuth 目录公开 `openai-codex/gpt-5.3-codex-spark` 时，它仍然可用；取决于 entitlement -- `openai-codex/gpt-5.4` 保持原生 `contextWindow = 1050000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限 -- 策略说明：OpenAI Codex OAuth 明确支持用于 OpenClaw 这类外部工具/工作流。 +- `openai-codex/gpt-5.5` 保留原生 `contextWindow = 1000000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限 +- 政策说明：OpenAI Codex OAuth 明确支持 OpenClaw 这类外部工具 / 工作流 ```json5 { - agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } }, + agents: { defaults: { model: { primary: "openai-codex/gpt-5.5" } } }, } ``` @@ -126,7 +122,7 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** models: { providers: { "openai-codex": { - models: [{ id: "gpt-5.4", contextTokens: 160000 }], + models: [{ id: "gpt-5.5", contextTokens: 160000 }], }, }, }, @@ -135,13 +131,13 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** ### 其他订阅式托管选项 -- [Qwen Cloud](/zh-CN/providers/qwen)：Qwen Cloud 提供商接口，以及阿里云 DashScope 和 Coding Plan 端点映射 +- [Qwen Cloud](/zh-CN/providers/qwen)：Qwen Cloud 提供商接口，以及 Alibaba DashScope 和 Coding Plan 端点映射 - [MiniMax](/zh-CN/providers/minimax)：MiniMax Coding Plan OAuth 或 API 密钥访问 - [GLM Models](/zh-CN/providers/glm)：Z.AI Coding Plan 或通用 API 端点 ### OpenCode -- 身份验证：`OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`） +- 认证：`OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`） - Zen 运行时提供商：`opencode` - Go 运行时提供商：`opencode-go` - 示例模型：`opencode/claude-opus-4-6`、`opencode-go/kimi-k2.5` @@ -156,20 +152,20 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** ### Google Gemini（API 密钥） - 提供商：`google` -- 身份验证：`GEMINI_API_KEY` -- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退项，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖） +- 认证：`GEMINI_API_KEY` +- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖） - 示例模型：`google/gemini-3.1-pro-preview`、`google/gemini-3-flash-preview` -- 兼容性：旧版 OpenClaw 配置中的 `google/gemini-3.1-flash-preview` 会被规范化为 `google/gemini-3-flash-preview` +- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被标准化为 `google/gemini-3-flash-preview` - CLI：`openclaw onboard --auth-choice gemini-api-key` -- 直接的 Gemini 运行还接受 `agents.defaults.models["google/"].params.cachedContent` +- 直接 Gemini 运行还接受 `agents.defaults.models["google/"].params.cachedContent` （或旧版 `cached_content`），以转发提供商原生的 - `cachedContents/...` 句柄；Gemini 缓存命中会以 OpenClaw `cacheRead` 的形式体现 + `cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead` ### Google Vertex 和 Gemini CLI - 提供商：`google-vertex`、`google-gemini-cli` -- 身份验证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程 -- 注意：OpenClaw 中的 Gemini CLI OAuth 是非官方集成。有用户报告称，使用第三方客户端后，Google 账号可能受到限制。若你选择继续，请先查看 Google 条款，并使用非关键账号。 +- 认证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程 +- 注意：OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，在使用第三方客户端后，他们的 Google 账号受到限制。若你选择继续，请查看 Google 条款并使用非关键账号。 - Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。 - 先安装 Gemini CLI： - `brew install gemini-cli` @@ -178,54 +174,54 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** - 登录：`openclaw models auth login --provider google-gemini-cli --set-default` - 默认模型：`google-gemini-cli/gemini-3-flash-preview` - 注意：你**不需要**将 client id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会将 - token 存储在 Gateway 网关主机上的身份验证配置文件中。 + token 存储在 Gateway 网关主机上的 auth profile 中。 - 如果登录后请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`。 - - Gemini CLI 的 JSON 回复从 `response` 中解析；用量则回退到 - `stats`，其中 `stats.cached` 会被规范化为 OpenClaw `cacheRead`。 + - Gemini CLI JSON 回复会从 `response` 解析；使用情况会回退到 + `stats`，其中 `stats.cached` 会被标准化为 OpenClaw `cacheRead`。 ### Z.AI（GLM） - 提供商：`zai` -- 身份验证：`ZAI_API_KEY` +- 认证：`ZAI_API_KEY` - 示例模型：`zai/glm-5.1` - CLI：`openclaw onboard --auth-choice zai-api-key` - - 别名：`z.ai/*` 和 `z-ai/*` 会规范化为 `zai/*` + - 别名：`z.ai/*` 和 `z-ai/*` 会标准化为 `zai/*` - `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制使用特定接口 ### Vercel AI Gateway - 提供商：`vercel-ai-gateway` -- 身份验证：`AI_GATEWAY_API_KEY` +- 认证：`AI_GATEWAY_API_KEY` - 示例模型：`vercel-ai-gateway/anthropic/claude-opus-4.6`、 `vercel-ai-gateway/moonshotai/kimi-k2.6` - CLI：`openclaw onboard --auth-choice ai-gateway-api-key` -### Kilo Gateway 网关 +### Kilo Gateway - 提供商：`kilocode` -- 身份验证：`KILOCODE_API_KEY` +- 认证：`KILOCODE_API_KEY` - 示例模型：`kilocode/kilo/auto` - CLI：`openclaw onboard --auth-choice kilocode-api-key` - 基础 URL：`https://api.kilo.ai/api/gateway/` - 静态回退目录内置 `kilocode/kilo/auto`；实时 - `https://api.kilo.ai/api/gateway/models` 发现可进一步扩展运行时 + `https://api.kilo.ai/api/gateway/models` 发现可以进一步扩展运行时 目录。 -- `kilocode/kilo/auto` 背后的精确上游路由由 Kilo Gateway 网关负责， - 并非 OpenClaw 中硬编码。 +- `kilocode/kilo/auto` 背后的具体上游路由由 Kilo Gateway + 负责，而不是在 OpenClaw 中硬编码。 -设置详情参见 [/providers/kilocode](/zh-CN/providers/kilocode)。 +有关设置详情，请参见 [/providers/kilocode](/zh-CN/providers/kilocode)。 ### 其他内置提供商插件 -| 提供商 | Id | 身份验证环境变量 | 示例模型 | +| 提供商 | Id | 认证环境变量 | 示例模型 | | ----------------------- | -------------------------------- | ------------------------------------------------------------ | ----------------------------------------------- | -| BytePlus（国际版） | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` | +| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` | | Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` | -| Cloudflare AI Gateway 网关 | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — | +| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — | | GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — | | Groq | `groq` | `GROQ_API_KEY` | — | | Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` | -| Kilo Gateway 网关 | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` | +| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` | | Kimi Coding | `kimi` | `KIMI_API_KEY` 或 `KIMICODE_API_KEY` | `kimi/kimi-code` | | MiniMax | `minimax` / `minimax-portal` | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN` | `minimax/MiniMax-M2.7` | | Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` | @@ -237,39 +233,40 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** | StepFun | `stepfun` / `stepfun-plan` | `STEPFUN_API_KEY` | `stepfun/step-3.5-flash` | | Together | `together` | `TOGETHER_API_KEY` | `together/moonshotai/Kimi-K2.5` | | Venice | `venice` | `VENICE_API_KEY` | — | -| Vercel AI Gateway 网关 | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` | +| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` | | Volcano Engine（Doubao） | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` | | xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` | | Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` | -值得注意的特性： +值得了解的特性： -- **OpenRouter** 仅在已验证的 `openrouter.ai` 路由上应用其 app-attribution 请求头和 Anthropic `cache_control` 标记。作为代理风格的 OpenAI 兼容路径，它会跳过仅限原生 OpenAI 的整形（`serviceTier`、Responses `store`、prompt-cache 提示、OpenAI reasoning 兼容性）。基于 Gemini 的引用仅保留代理 Gemini 的 thought-signature 清理。 -- **Kilo Gateway 网关** 中基于 Gemini 的引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理 reasoning 的引用会跳过代理 reasoning 注入。 -- **MiniMax** 的 API 密钥新手引导会写入显式的 M2.7 模型定义，并设置 `input: ["text", "image"]`；在该配置具体化之前，内置目录会将聊天引用保持为仅文本。 +- **OpenRouter** 仅在已验证的 `openrouter.ai` 路由上应用其应用归因头和 Anthropic `cache_control` 标记。作为代理式 OpenAI 兼容路径，它会跳过仅适用于原生 OpenAI 的整形（`serviceTier`、Responses `store`、prompt-cache 提示、OpenAI reasoning 兼容处理）。基于 Gemini 的引用仅保留代理 Gemini thought-signature 清理。 +- **Kilo Gateway** 基于 Gemini 的引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理 reasoning 的引用会跳过代理 reasoning 注入。 +- **MiniMax** API 密钥新手引导会写入显式的 M2.7 模型定义，并设置 `input: ["text", "image"]`；在该配置具体化之前，内置目录会将聊天引用保持为仅文本。 - **xAI** 使用 xAI Responses 路径。`/fast` 或 `params.fastMode: true` 会将 `grok-3`、`grok-3-mini`、`grok-4` 和 `grok-4-0709` 重写为其 `*-fast` 变体。`tool_stream` 默认开启；可通过 `agents.defaults.models["xai/"].params.tool_stream=false` 禁用。 -- **Cerebras** 的 GLM 模型使用 `zai-glm-4.7` / `zai-glm-4.6`；OpenAI 兼容的基础 URL 为 `https://api.cerebras.ai/v1`。 +- **Cerebras** GLM 模型使用 `zai-glm-4.7` / `zai-glm-4.6`；OpenAI 兼容基础 URL 为 `https://api.cerebras.ai/v1`。 -## 通过 `models.providers` 配置的提供商（自定义/基础 URL） +## 通过 `models.providers` 使用的提供商（自定义 / 基础 URL） -使用 `models.providers`（或 `models.json`）来添加**自定义**提供商或 -OpenAI/Anthropic 兼容代理。 +使用 `models.providers`（或 `models.json`）添加**自定义**提供商或 +OpenAI / Anthropic 兼容代理。 -下方许多内置提供商插件已经发布了默认目录。 -仅当你想覆盖默认基础 URL、请求头或模型列表时， +下面的许多内置提供商插件已经发布了默认目录。 +只有当你想覆盖默认基础 URL、headers 或模型列表时， 才需要使用显式的 `models.providers.` 条目。 ### Moonshot AI（Kimi） -Moonshot 作为内置提供商插件提供。默认情况下请使用内置提供商， -仅当你需要覆盖基础 URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目： +Moonshot 以内置提供商插件形式提供。默认情况下请使用内置提供商， +只有在你需要覆盖基础 URL 或模型元数据时， +才添加显式的 `models.providers.moonshot` 条目： - 提供商：`moonshot` -- 身份验证：`MOONSHOT_API_KEY` +- 认证：`MOONSHOT_API_KEY` - 示例模型：`moonshot/kimi-k2.6` - CLI：`openclaw onboard --auth-choice moonshot-api-key` 或 `openclaw onboard --auth-choice moonshot-api-key-cn` -Kimi K2 模型 ID： +Kimi K2 模型 Id： [//]: # "moonshot-kimi-k2-model-refs:start" @@ -305,7 +302,7 @@ Kimi K2 模型 ID： Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点： - 提供商：`kimi` -- 身份验证：`KIMI_API_KEY` +- 认证：`KIMI_API_KEY` - 示例模型：`kimi/kimi-code` ```json5 @@ -317,14 +314,14 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点： } ``` -旧版 `kimi/k2p5` 仍然接受为兼容模型 ID。 +旧版 `kimi/k2p5` 仍然作为兼容性模型 id 被接受。 ### Volcano Engine（Doubao） Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访问。 -- 提供商：`volcengine`（编码方案：`volcengine-plan`） -- 身份验证：`VOLCANO_ENGINE_API_KEY` +- 提供商：`volcengine`（编码版：`volcengine-plan`） +- 认证：`VOLCANO_ENGINE_API_KEY` - 示例模型：`volcengine-plan/ark-code-latest` - CLI：`openclaw onboard --auth-choice volcengine-api-key` @@ -337,12 +334,12 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访 ``` 新手引导默认使用编码接口，但通用 `volcengine/*` -目录也会同时注册。 +目录会同时注册。 -在新手引导/配置的模型选择器中，Volcengine 身份验证选项会优先显示 +在新手引导 / 配置的模型选择器中，Volcengine 认证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 行。如果这些模型尚未加载， -OpenClaw 会回退到未筛选的目录，而不是显示空的 -按提供商范围筛选的选择器。 +OpenClaw 会回退到未过滤的目录，而不是显示空的 +提供商范围选择器。 可用模型： @@ -364,8 +361,8 @@ OpenClaw 会回退到未筛选的目录，而不是显示空的 BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力。 -- 提供商：`byteplus`（编码方案：`byteplus-plan`） -- 身份验证：`BYTEPLUS_API_KEY` +- 提供商：`byteplus`（编码版：`byteplus-plan`） +- 认证：`BYTEPLUS_API_KEY` - 示例模型：`byteplus-plan/ark-code-latest` - CLI：`openclaw onboard --auth-choice byteplus-api-key` @@ -378,12 +375,12 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力 ``` 新手引导默认使用编码接口，但通用 `byteplus/*` -目录也会同时注册。 +目录会同时注册。 -在新手引导/配置的模型选择器中，BytePlus（国际版）身份验证选项会优先显示 +在新手引导 / 配置的模型选择器中，BytePlus（国际版） 认证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 行。如果这些模型尚未加载， -OpenClaw 会回退到未筛选的目录，而不是显示空的 -按提供商范围筛选的选择器。 +OpenClaw 会回退到未过滤的目录，而不是显示空的 +提供商范围选择器。 可用模型： @@ -404,7 +401,7 @@ OpenClaw 会回退到未筛选的目录，而不是显示空的 Synthetic 通过 `synthetic` 提供商提供 Anthropic 兼容模型： - 提供商：`synthetic` -- 身份验证：`SYNTHETIC_API_KEY` +- 认证：`SYNTHETIC_API_KEY` - 示例模型：`synthetic/hf:MiniMaxAI/MiniMax-M2.5` - CLI：`openclaw onboard --auth-choice synthetic-api-key` @@ -429,37 +426,37 @@ Synthetic 通过 `synthetic` 提供商提供 Anthropic 兼容模型： ### MiniMax -MiniMax 通过 `models.providers` 进行配置，因为它使用自定义端点： +MiniMax 通过 `models.providers` 配置，因为它使用自定义端点： - MiniMax OAuth（Global）：`--auth-choice minimax-global-oauth` - MiniMax OAuth（CN）：`--auth-choice minimax-cn-oauth` - MiniMax API 密钥（Global）：`--auth-choice minimax-global-api` - MiniMax API 密钥（CN）：`--auth-choice minimax-cn-api` -- 身份验证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 +- 认证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY` -设置详情、模型选项和配置片段请参见 [/providers/minimax](/zh-CN/providers/minimax)。 +有关设置详情、模型选项和配置片段，请参见 [/providers/minimax](/zh-CN/providers/minimax)。 在 MiniMax 的 Anthropic 兼容流式传输路径上，OpenClaw 默认禁用 thinking， -除非你显式启用它；而 `/fast on` 会将 +除非你显式设置它，并且 `/fast on` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 -由插件负责的能力拆分： +由插件拥有的能力拆分： -- 文本/聊天默认保持在 `minimax/MiniMax-M2.7` -- 图像生成为 `minimax/image-01` 或 `minimax-portal/image-01` -- 图像理解在两个 MiniMax 身份验证路径上都由插件负责，使用 `MiniMax-VL-01` +- 文本 / 聊天默认使用 `minimax/MiniMax-M2.7` +- 图像生成使用 `minimax/image-01` 或 `minimax-portal/image-01` +- 图像理解在两个 MiniMax 认证路径上都使用由插件拥有的 `MiniMax-VL-01` - Web 搜索保持使用提供商 id `minimax` ### LM Studio -LM Studio 作为内置提供商插件提供，并使用原生 API： +LM Studio 以内置提供商插件形式提供，并使用原生 API： - 提供商：`lmstudio` -- 身份验证：`LM_API_TOKEN` +- 认证：`LM_API_TOKEN` - 默认推理基础 URL：`http://localhost:1234/v1` -然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）： +然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 Id）： ```json5 { @@ -471,14 +468,14 @@ LM Studio 作为内置提供商插件提供，并使用原生 API： OpenClaw 使用 LM Studio 原生的 `/api/v1/models` 和 `/api/v1/models/load` 进行发现 + 自动加载，默认使用 `/v1/chat/completions` 进行推理。 -设置与故障排除请参见 [/providers/lmstudio](/zh-CN/providers/lmstudio)。 +有关设置和故障排除，请参见 [/providers/lmstudio](/zh-CN/providers/lmstudio)。 ### Ollama -Ollama 作为内置提供商插件提供，并使用 Ollama 的原生 API： +Ollama 以内置提供商插件形式提供，并使用 Ollama 的原生 API： - 提供商：`ollama` -- 身份验证：无需（本地服务器） +- 认证：无需（本地服务器） - 示例模型：`ollama/llama3.3` - 安装：[https://ollama.com/download](https://ollama.com/download) @@ -496,26 +493,27 @@ ollama pull llama3.3 ``` 当你通过 -`OLLAMA_API_KEY` 选择启用时，Ollama 会在本地 `http://127.0.0.1:11434` 被检测到， -并且内置提供商插件会将 Ollama 直接添加到 -`openclaw onboard` 和模型选择器中。有关新手引导、云端/本地模式及自定义配置，参见 [/providers/ollama](/zh-CN/providers/ollama)。 +`OLLAMA_API_KEY` 选择启用时，系统会在本地 `http://127.0.0.1:11434` 检测 Ollama， +而内置提供商插件会将 Ollama 直接添加到 +`openclaw onboard` 和模型选择器中。有关新手引导、云端 / 本地模式及自定义配置， +请参见 [/providers/ollama](/zh-CN/providers/ollama)。 ### vLLM -vLLM 作为内置提供商插件提供，用于本地/自托管的 OpenAI 兼容 +vLLM 以内置提供商插件形式提供，用于本地 / 自托管的 OpenAI 兼容 服务器： - 提供商：`vllm` -- 身份验证：可选（取决于你的服务器） +- 认证：可选（取决于你的服务器） - 默认基础 URL：`http://127.0.0.1:8000/v1` -要在本地选择启用自动发现（如果你的服务器不强制要求身份验证，任意值都可用）： +要选择启用本地自动发现（如果你的服务器不强制要求认证，任意值都可以）： ```bash export VLLM_API_KEY="vllm-local" ``` -然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）： +然后设置一个模型（替换为 `/v1/models` 返回的某个 Id）： ```json5 { @@ -529,21 +527,21 @@ export VLLM_API_KEY="vllm-local" ### SGLang -SGLang 作为内置提供商插件提供，用于快速自托管的 +SGLang 以内置提供商插件形式提供，用于快速的自托管 OpenAI 兼容服务器： - 提供商：`sglang` -- 身份验证：可选（取决于你的服务器） +- 认证：可选（取决于你的服务器） - 默认基础 URL：`http://127.0.0.1:30000/v1` -要在本地选择启用自动发现（如果你的服务器不 -强制要求身份验证，任意值都可用）： +要选择启用本地自动发现（如果你的服务器不 +强制要求认证，任意值都可以）： ```bash export SGLANG_API_KEY="sglang-local" ``` -然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）： +然后设置一个模型（替换为 `/v1/models` 返回的某个 Id）： ```json5 { @@ -564,7 +562,7 @@ export SGLANG_API_KEY="sglang-local" agents: { defaults: { model: { primary: "lmstudio/my-local-model" }, - models: { "lmstudio/my-local-model": { alias: "本地" } }, + models: { "lmstudio/my-local-model": { alias: "Local" } }, }, }, models: { @@ -576,7 +574,7 @@ export SGLANG_API_KEY="sglang-local" models: [ { id: "my-local-model", - name: "本地模型", + name: "Local Model", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, @@ -590,23 +588,23 @@ export SGLANG_API_KEY="sglang-local" } ``` -说明： +注意： -- 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选项。 - 省略时，OpenClaw 默认值为： +- 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选的。 + 省略时，OpenClaw 默认使用： - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` -- 建议：设置与你的代理/模型限制相匹配的显式值。 -- 对于非原生端点上的 `api: "openai-completions"`（任何非空 `baseUrl` 且其 host 不是 `api.openai.com`），OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。 -- 代理风格的 OpenAI 兼容路由也会跳过仅限原生 OpenAI 的请求 - 整形：没有 `service_tier`，没有 Responses `store`，没有 prompt-cache 提示，没有 - OpenAI reasoning 兼容负载整形，也没有隐藏的 OpenClaw 归因 - 请求头。 -- 如果 `baseUrl` 为空/省略，OpenClaw 会保留默认 OpenAI 行为（会解析到 `api.openai.com`）。 -- 出于安全考虑，即使显式设置了 `compat.supportsDeveloperRole: true`，在非原生 `openai-completions` 端点上仍会被覆盖。 +- 建议：设置与你的代理 / 模型限制匹配的显式值。 +- 对于非原生端点上的 `api: "openai-completions"`（任何主机不是 `api.openai.com` 的非空 `baseUrl`），OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。 +- 代理式 OpenAI 兼容路由也会跳过仅适用于原生 OpenAI 的请求 + 整形：不使用 `service_tier`，不使用 Responses `store`，不使用 prompt-cache 提示，不使用 + OpenAI reasoning 兼容载荷整形，也不附加隐藏的 OpenClaw 归因 + 头。 +- 如果 `baseUrl` 为空 / 省略，OpenClaw 会保留默认的 OpenAI 行为（会解析到 `api.openai.com`）。 +- 出于安全考虑，即使显式设置 `compat.supportsDeveloperRole: true`，在非原生 `openai-completions` 端点上仍会被覆盖。 ## CLI 示例 @@ -616,11 +614,11 @@ openclaw models set opencode/claude-opus-4-6 openclaw models list ``` -另请参见：[/gateway/configuration](/zh-CN/gateway/configuration) 获取完整配置示例。 +另请参见：[/gateway/configuration](/zh-CN/gateway/configuration)，获取完整配置示例。 ## 相关内容 - [模型](/zh-CN/concepts/models) — 模型配置和别名 -- [模型故障转移](/zh-CN/concepts/model-failover) — 回退链和重试行为 +- [模型故障切换](/zh-CN/concepts/model-failover) — 回退链和重试行为 - [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) — 模型配置键 -- [提供商](/zh-CN/providers) — 按提供商分类的设置指南 +- [提供商](/zh-CN/providers) — 按提供商划分的设置指南 diff --git a/docs/zh-CN/concepts/models.md b/docs/zh-CN/concepts/models.md index 21e736599..18c4a62c4 100644 --- a/docs/zh-CN/concepts/models.md +++ b/docs/zh-CN/concepts/models.md @@ -1,23 +1,23 @@ --- read_when: - - 添加或修改模型 CLI（`models list`/`set`/`scan`/`aliases`/`fallbacks`） + - 添加或修改模型 CLI（`models list/set/scan/aliases/fallbacks`） - 更改模型回退行为或选择 UX - 更新模型扫描探测项（工具/图像） summary: 模型 CLI：列表、设置、别名、回退、扫描、状态 title: 模型 CLI x-i18n: - generated_at: "2026-04-23T06:24:04Z" + generated_at: "2026-04-23T19:23:49Z" model: gpt-5.4 provider: openai - source_hash: 46916d9600a4e4aebdb026aa42df39149d8b6d438a8a7e85a61053dfc8f76dcc + source_hash: 45ee320df8d49171261cd0a5d42e1c0c39d7ea77d16fd7895ef15b1195d81fb4 source_path: concepts/models.md workflow: 15 --- # 模型 CLI -有关凭证配置轮换、冷却时间，以及它们如何与回退机制交互，请参见 [/concepts/model-failover](/zh-CN/concepts/model-failover)。 -提供商快速概览 + 示例：[/concepts/model-providers](/zh-CN/concepts/model-providers)。 +关于凭证配置轮换、冷却时间以及它们如何与回退机制交互，请参阅 [/concepts/model-failover](/zh-CN/concepts/model-failover)。 +提供商快速概览与示例：[/concepts/model-providers](/zh-CN/concepts/model-providers)。 ## 模型选择的工作方式 @@ -25,23 +25,23 @@ OpenClaw 按以下顺序选择模型： 1. **主模型**（`agents.defaults.model.primary` 或 `agents.defaults.model`）。 2. `agents.defaults.model.fallbacks` 中的**回退模型**（按顺序）。 -3. **提供商凭证故障转移**会在单个提供商内部发生，然后才会移动到下一个模型。 +3. **提供商凭证回退**会在同一提供商内部发生，然后才会切换到下一个模型。 相关项： -- `agents.defaults.models` 是 OpenClaw 可使用模型的允许列表/目录（包含别名）。 -- `agents.defaults.imageModel` **仅在**主模型无法接收图像时使用。 -- `agents.defaults.pdfModel` 由 `pdf` 工具使用。如果省略，该工具会回退到 `agents.defaults.imageModel`，然后回退到解析后的会话/默认模型。 -- `agents.defaults.imageGenerationModel` 用于共享图像生成功能。如果省略，`image_generate` 仍可推断出一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API 密钥。 -- `agents.defaults.musicGenerationModel` 用于共享音乐生成功能。如果省略，`music_generate` 仍可推断出一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API 密钥。 -- `agents.defaults.videoGenerationModel` 用于共享视频生成功能。如果省略，`video_generate` 仍可推断出一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API 密钥。 -- 每个智能体的默认值可通过 `agents.list[].model` 加绑定来覆盖 `agents.defaults.model`（参见 [/concepts/multi-agent](/zh-CN/concepts/multi-agent)）。 +- `agents.defaults.models` 是 OpenClaw 可使用模型的允许列表/目录（以及别名）。 +- `agents.defaults.imageModel` **仅在**主模型无法接受图像时使用。 +- `agents.defaults.pdfModel` 由 `pdf` 工具使用。如果省略，该工具会回退到 `agents.defaults.imageModel`，然后回退到已解析的会话/默认模型。 +- `agents.defaults.imageGenerationModel` 用于共享的图像生成能力。如果省略，`image_generate` 仍可推断出一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API 密钥。 +- `agents.defaults.musicGenerationModel` 用于共享的音乐生成能力。如果省略，`music_generate` 仍可推断出一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API 密钥。 +- `agents.defaults.videoGenerationModel` 用于共享的视频生成能力。如果省略，`video_generate` 仍可推断出一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API 密钥。 +- 每个智能体的默认值可通过 `agents.list[].model` 加上绑定覆盖 `agents.defaults.model`（参见 [/concepts/multi-agent](/zh-CN/concepts/multi-agent)）。 ## 快速模型策略 -- 将你的主模型设置为你可用的、最新一代中最强的模型。 -- 对成本/延迟敏感的任务和风险较低的聊天，使用回退模型。 -- 对启用了工具的智能体或不受信任的输入，避免使用较旧/较弱的模型层级。 +- 将你的主模型设置为你可用的、能力最强的最新一代模型。 +- 对于成本/延迟敏感的任务和风险较低的聊天，使用回退模型。 +- 对于启用了工具的智能体或不受信任的输入，避免使用较旧/较弱的模型层级。 ## 新手引导（推荐） @@ -51,7 +51,7 @@ OpenClaw 按以下顺序选择模型： openclaw onboard ``` -它可以为常见提供商设置模型 + 凭证，包括 **OpenAI Code (Codex) subscription**（OAuth）和 **Anthropic**（API 密钥或 Claude CLI）。 +它可以为常见提供商设置模型和凭证，包括 **OpenAI Code (Codex) subscription**（OAuth）和 **Anthropic**（API 密钥或 Claude CLI）。 ## 配置键名（概览） @@ -63,38 +63,38 @@ openclaw onboard - `agents.defaults.models`（允许列表 + 别名 + 提供商参数） - `models.providers`（写入 `models.json` 的自定义提供商） -模型引用会被规范化为小写。像 `z.ai/*` 这样的提供商别名会规范化为 `zai/*`。 +模型引用会被规范化为小写。像 `z.ai/*` 这样的提供商别名会被规范化为 `zai/*`。 提供商配置示例（包括 OpenCode）位于 [/providers/opencode](/zh-CN/providers/opencode)。 ### 安全地编辑允许列表 -手动更新 `agents.defaults.models` 时，请使用追加式写入： +手动更新 `agents.defaults.models` 时，请使用增量写入： ```bash -openclaw config set agents.defaults.models '{"openai-codex/gpt-5.4":{}}' --strict-json --merge +openclaw config set agents.defaults.models '{"openai-codex/gpt-5.5":{}}' --strict-json --merge ``` -`openclaw config set` 会保护模型/提供商映射，防止意外覆盖。当对 `agents.defaults.models`、`models.providers` 或 `models.providers..models` 执行普通对象赋值且会移除现有条目时，此操作会被拒绝。对于追加式更改，请使用 `--merge`；仅当提供的值应成为完整目标值时，才使用 `--replace`。 +`openclaw config set` 会保护模型/提供商映射，防止被意外覆盖。对 `agents.defaults.models`、`models.providers` 或 `models.providers..models` 进行普通对象赋值时，如果会移除现有条目，就会被拒绝。新增变更请使用 `--merge`；仅当提供的值应成为完整目标值时，才使用 `--replace`。 -交互式提供商设置和 `openclaw configure --section model` 也会将提供商作用域内的选择合并到现有允许列表中，因此添加 Codex、Ollama 或其他提供商时，不会丢弃无关的模型条目。 +交互式提供商设置和 `openclaw configure --section model` 也会将按提供商划分的选择合并到现有允许列表中，因此添加 Codex、Ollama 或其他提供商时，不会丢失无关的模型条目。 ## “Model is not allowed”（以及为什么回复会停止） -如果设置了 `agents.defaults.models`，它就会成为 `/model` 和会话覆盖的**允许列表**。当用户选择了不在该允许列表中的模型时，OpenClaw 会返回： +如果设置了 `agents.defaults.models`，它就会成为 `/model` 和会话覆盖的**允许列表**。当用户选择的模型不在该允许列表中时，OpenClaw 会返回： ``` Model "provider/model" is not allowed. Use /model to list available models. ``` -这发生在生成正常回复**之前**，因此消息会让人感觉像是“没有响应”。修复方式如下： +这会在生成正常回复**之前**发生，因此这条消息可能让人感觉它“没有响应”。解决方法是以下任一项： - 将该模型添加到 `agents.defaults.models`，或 -- 清空允许列表（删除 `agents.defaults.models`），或 +- 清除允许列表（移除 `agents.defaults.models`），或 - 从 `/model list` 中选择一个模型。 -允许列表配置示例： +允许列表示例配置： ```json5 { @@ -110,36 +110,36 @@ Model "provider/model" is not allowed. Use /model to list available models. ## 在聊天中切换模型（`/model`） -你可以在不重启的情况下为当前会话切换模型： +你可以在不重启的情况下切换当前会话的模型： -```text +``` /model /model list /model 3 -/model openai/gpt-5.4 +/model openai/gpt-5.5 /model status ``` 说明： - `/model`（以及 `/model list`）是一个紧凑的编号选择器（模型家族 + 可用提供商）。 -- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单，以及一个提交步骤。 -- `/models add` 默认可用，可通过 `commands.modelsWrite=false` 禁用。 -- 启用后，`/models add ` 是最快路径；单独输入 `/models add` 会在支持时启动一个按提供商优先的引导流程。 -- 执行 `/models add` 后，新模型无需重启 Gateway 网关，就会在 `/models` 和 `/model` 中可用。 -- `/model <#>` 会从该选择器中进行选择。 +- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉框，以及一个提交步骤。 +- 默认提供 `/models add`，可通过 `commands.modelsWrite=false` 禁用。 +- 启用后，`/models add ` 是最快路径；而不带参数的 `/models add` 会在支持的情况下启动“先选提供商”的引导流程。 +- 执行 `/models add` 后，新模型无需重启 Gateway 网关，即可在 `/models` 和 `/model` 中使用。 +- `/model <#>` 会从该选择器中选取。 - `/model` 会立即持久化新的会话选择。 -- 如果智能体处于空闲状态，下一次运行会立即使用新模型。 -- 如果某次运行已经处于活动状态，OpenClaw 会将实时切换标记为待处理，并仅在一个干净的重试点重启并切换到新模型。 -- 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到后续的重试机会或下一次用户回合。 -- `/model status` 是详细视图（凭证候选项，以及在已配置时显示提供商端点 `baseUrl` + `api` 模式）。 -- 模型引用通过在**第一个** `/` 处分割来解析。输入 `/model ` 时请使用 `provider/model`。 -- 如果模型 ID 本身包含 `/`（OpenRouter 风格），你必须包含提供商前缀（示例：`/model openrouter/moonshotai/kimi-k2`）。 -- 如果你省略了提供商，OpenClaw 会按以下顺序解析输入： +- 如果智能体空闲，下一次运行会立即使用新模型。 +- 如果某次运行已经在进行中，OpenClaw 会将实时切换标记为待处理，并只会在一个干净的重试点重启到新模型。 +- 如果工具活动或回复输出已经开始，待处理的切换可能会一直排队到稍后的重试机会，或直到下一轮用户输入。 +- `/model status` 是详细视图（凭证候选项，以及在已配置时显示提供商端点 `baseUrl` 和 `api` 模式）。 +- 模型引用通过按**第一个** `/` 分割来解析。输入 `/model ` 时，请使用 `provider/model`。 +- 如果模型 ID 本身包含 `/`（例如 OpenRouter 风格），你必须包含提供商前缀（示例：`/model openrouter/moonshotai/kimi-k2`）。 +- 如果你省略提供商，OpenClaw 会按以下顺序解析输入： 1. 别名匹配 - 2. 对该确切未加前缀模型 ID 的唯一已配置提供商匹配 - 3. 已弃用的回退：使用已配置的默认提供商 - 如果该提供商不再公开已配置的默认模型，OpenClaw 会改为回退到第一个已配置的提供商/模型，以避免暴露一个陈旧、已移除提供商的默认值。 + 2. 对该精确无前缀模型 ID 的唯一已配置提供商匹配 + 3. 已弃用的回退：回退到已配置的默认提供商 + 如果该提供商不再提供已配置的默认模型，OpenClaw 会改为回退到第一个已配置的提供商/模型，以避免暴露过时的、已移除提供商默认值。 完整命令行为/配置： [Slash commands](/zh-CN/tools/slash-commands)。 @@ -186,18 +186,18 @@ openclaw models image-fallbacks clear - `--plain`：每行一个模型 - `--json`：机器可读输出 -`--all` 会在配置凭证之前包含内置的、由提供商拥有的静态目录行，因此仅发现视图也可以显示那些在你添加匹配提供商凭证之前不可用的模型。 +`--all` 会在配置凭证之前，先包含由内置提供商拥有的静态目录行，因此仅用于发现的视图也可以显示那些在你添加匹配提供商凭证之前不可用的模型。 ### `models status` -显示解析后的主模型、回退模型、图像模型，以及已配置提供商的凭证概览。它还会显示在凭证存储中找到的配置文件的 OAuth 到期状态（默认在 24 小时内到期时警告）。`--plain` 仅打印解析后的主模型。 -OAuth 状态始终会显示（并包含在 `--json` 输出中）。如果已配置的提供商没有凭证，`models status` 会打印一个 **Missing auth** 部分。 -JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的实际凭证，包括基于环境变量的凭证）。`auth.oauth` 仅表示凭证存储中的配置文件健康状态；仅通过环境变量提供凭证的提供商不会出现在其中。 -对自动化使用 `--check`（缺失/过期时退出码为 `1`，即将过期时为 `2`）。 -使用 `--probe` 进行实时凭证检查；探测行可能来自凭证配置文件、环境变量凭证或 `models.json`。 -如果显式的 `auth.order.` 省略了某个已存储配置文件，则探测会报告 `excluded_by_auth_order`，而不是尝试它。如果凭证存在，但无法为该提供商解析出可探测的模型，则探测会报告 `status: no_model`。 +显示已解析的主模型、回退模型、图像模型，以及已配置提供商的凭证概览。它还会显示认证存储中凭证配置的 OAuth 过期状态（默认会在 24 小时内过期时发出警告）。`--plain` 仅打印已解析的主模型。 +OAuth 状态始终会显示（并包含在 `--json` 输出中）。如果某个已配置的提供商没有凭证，`models status` 会打印一个 **Missing auth** 部分。 +JSON 包含 `auth.oauth`（警告窗口 + 配置）和 `auth.providers`（每个提供商的有效凭证，包括基于环境变量的凭证）。`auth.oauth` 仅表示认证存储中配置的健康状态；仅使用环境变量的提供商不会出现在其中。 +对自动化场景使用 `--check`（缺失/已过期时退出码为 `1`，即将过期时为 `2`）。 +对实时凭证检查使用 `--probe`；探测行可能来自凭证配置、环境变量凭证或 `models.json`。 +如果显式的 `auth.order.` 省略了某个已存储配置，探测会报告 `excluded_by_auth_order`，而不是尝试它。如果存在凭证，但无法为该提供商解析出可探测的模型，探测会报告 `status: no_model`。 -凭证选择取决于提供商/账户。对于始终在线的 Gateway 网关主机，API 密钥通常是最可预测的；也支持复用 Claude CLI 以及现有的 Anthropic OAuth/token 配置文件。 +凭证选择取决于提供商/账户。对于始终在线的 Gateway 网关主机，API 密钥通常是最可预测的；同时也支持复用 Claude CLI 以及现有的 Anthropic OAuth/token 配置。 示例（Claude CLI）： @@ -208,20 +208,20 @@ openclaw models status ## 扫描（OpenRouter 免费模型） -`openclaw models scan` 会检查 OpenRouter 的**免费模型目录**，并可选择探测模型的工具和图像支持。 +`openclaw models scan` 会检查 OpenRouter 的**免费模型目录**，并可选择探测模型是否支持工具和图像。 关键标志： - `--no-probe`：跳过实时探测（仅元数据） - `--min-params `：最小参数规模（十亿） -- `--max-age-days `：跳过较旧模型 +- `--max-age-days `：跳过较旧的模型 - `--provider `：提供商前缀过滤 - `--max-candidates `：回退列表大小 -- `--set-default`：将 `agents.defaults.model.primary` 设置为第一个选择项 -- `--set-image`：将 `agents.defaults.imageModel.primary` 设置为第一个图像选择项 +- `--set-default`：将 `agents.defaults.model.primary` 设置为第一个选中的项 +- `--set-image`：将 `agents.defaults.imageModel.primary` 设置为第一个图像选中的项 -探测需要 OpenRouter API 密钥（来自凭证配置文件或 -`OPENROUTER_API_KEY`）。如果没有密钥，请使用 `--no-probe` 仅列出候选项。 +探测需要 OpenRouter API 密钥（来自凭证配置或 `OPENROUTER_API_KEY`）。 +如果没有密钥，请使用 `--no-probe` 仅列出候选项。 扫描结果按以下规则排序： @@ -233,33 +233,33 @@ openclaw models status 输入 - OpenRouter `/models` 列表（过滤 `:free`） -- 需要来自凭证配置文件或 `OPENROUTER_API_KEY` 的 OpenRouter API 密钥（参见 [/environment](/zh-CN/help/environment)） +- 需要来自凭证配置或 `OPENROUTER_API_KEY` 的 OpenRouter API 密钥（参见 [/environment](/zh-CN/help/environment)） - 可选过滤器：`--max-age-days`、`--min-params`、`--provider`、`--max-candidates` - 探测控制：`--timeout`、`--concurrency` -在 TTY 中运行时，你可以交互式选择回退模型。在非交互模式下，传入 `--yes` 以接受默认值。 +在 TTY 中运行时，你可以以交互方式选择回退模型。在非交互模式下，传入 `--yes` 以接受默认值。 ## 模型注册表（`models.json`） -`models.providers` 中的自定义提供商会写入智能体目录下的 `models.json`（默认 `~/.openclaw/agents//agent/models.json`）。默认情况下会合并该文件，除非将 `models.mode` 设置为 `replace`。 +`models.providers` 中的自定义提供商会被写入智能体目录下的 `models.json`（默认路径为 `~/.openclaw/agents//agent/models.json`）。除非将 `models.mode` 设置为 `replace`，否则默认会合并此文件。 匹配提供商 ID 的合并模式优先级： - 智能体 `models.json` 中已存在的非空 `baseUrl` 优先。 -- 智能体 `models.json` 中非空的 `apiKey` 仅在该提供商在当前配置/凭证配置文件上下文中**不**受 SecretRef 管理时优先。 -- 受 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化已解析的密钥。 -- 受 SecretRef 管理的提供商 header 值会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）。 +- 智能体 `models.json` 中的非空 `apiKey` 仅在该提供商在当前配置/凭证配置上下文中**不是**由 SecretRef 管理时优先。 +- 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化已解析的密钥。 +- 由 SecretRef 管理的提供商请求头值会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）。 - 空的或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 - 其他提供商字段会从配置和规范化后的目录数据中刷新。 -标记持久化以源为权威：OpenClaw 会根据当前源配置快照（预解析），而不是根据运行时已解析的密钥值来写入标记。 -只要 OpenClaw 重新生成 `models.json`，这条规则就适用，包括像 `openclaw agent` 这样的命令驱动路径。 +标记持久化以源为准：OpenClaw 从当前活动源配置快照（解析前）写入标记，而不是从运行时已解析的密钥值写入。 +这适用于 OpenClaw 重新生成 `models.json` 的所有情况，包括诸如 `openclaw agent` 这样的命令驱动路径。 -## 相关 +## 相关内容 -- [模型提供商](/zh-CN/concepts/model-providers) — 提供商路由和凭证 -- [模型故障转移](/zh-CN/concepts/model-failover) — 回退链 -- [图像生成](/zh-CN/tools/image-generation) — 图像模型配置 -- [音乐生成](/zh-CN/tools/music-generation) — 音乐模型配置 -- [视频生成](/zh-CN/tools/video-generation) — 视频模型配置 -- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) — 模型配置键名 +- [模型提供商](/zh-CN/concepts/model-providers) —— 提供商路由和凭证 +- [模型回退](/zh-CN/concepts/model-failover) —— 回退链 +- [图像生成](/zh-CN/tools/image-generation) —— 图像模型配置 +- [音乐生成](/zh-CN/tools/music-generation) —— 音乐模型配置 +- [视频生成](/zh-CN/tools/video-generation) —— 视频模型配置 +- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) —— 模型配置键名 diff --git a/docs/zh-CN/concepts/qa-e2e-automation.md b/docs/zh-CN/concepts/qa-e2e-automation.md index a805d04d0..8bb3cd5e8 100644 --- a/docs/zh-CN/concepts/qa-e2e-automation.md +++ b/docs/zh-CN/concepts/qa-e2e-automation.md @@ -2,42 +2,42 @@ read_when: - 扩展 qa-lab 或 qa-channel - 添加由仓库支持的 QA 场景 - - 围绕 Gateway 网关仪表板构建更高拟真度的 QA 自动化 -summary: qa-lab、qa-channel、种子场景和协议报告的私有 QA 自动化形态 + - 围绕 Gateway 网关仪表板构建更高真实性的 QA 自动化 +summary: 面向 qa-lab、qa-channel、种子场景和协议报告的私有 QA 自动化形态 title: QA 端到端自动化 x-i18n: - generated_at: "2026-04-23T09:05:04Z" + generated_at: "2026-04-23T19:23:50Z" model: gpt-5.4 provider: openai - source_hash: a967a74d2e70b042e9443c5ec954902b820d2e5a22cbecd9be74af13b9085553 + source_hash: baecad15e244cb927cac6489eb9f59531a8f56dd0ea7d47bd4dad463984cc9f3 source_path: concepts/qa-e2e-automation.md workflow: 15 --- # QA 端到端自动化 -私有 QA 栈旨在以比单个单元测试更贴近真实、具备渠道形态的方式来验证 OpenClaw。 +私有 QA 栈旨在以比单个单元测试更贴近真实、更加符合渠道形态的方式来验证 OpenClaw。 -当前组成部分： +当前包含的组成部分： -- `extensions/qa-channel`：合成消息渠道，包含私信、渠道、线程、表情回应、编辑和删除等交互面。 +- `extensions/qa-channel`：合成消息渠道，提供私信、渠道、线程、反应、编辑和删除等表面能力。 - `extensions/qa-lab`：调试器 UI 和 QA 总线，用于观察转录内容、注入入站消息，以及导出 Markdown 报告。 - `qa/`：由仓库支持的启动任务种子资源和基线 QA 场景。 -当前 QA 操作流程是一个双栏 QA 站点： +当前的 QA 操作流程是一个双窗格 QA 站点： -- 左侧：带有智能体的 Gateway 网关仪表板（控制 UI）。 -- 右侧：QA Lab，显示类似 Slack 的转录和场景计划。 +- 左侧：带有智能体的 Gateway 网关仪表板（Control UI）。 +- 右侧：QA Lab，显示类似 Slack 的转录内容和场景计划。 -运行方式： +使用以下命令运行： ```bash pnpm qa:lab:up ``` -这会构建 QA 站点、启动基于 Docker 的 gateway 测试通道，并暴露 QA Lab 页面，供操作员或自动化循环向智能体下达 QA 任务、观察真实渠道行为，并记录哪些内容成功了、失败了，或仍然受阻。 +这会构建 QA 站点，启动由 Docker 支持的 Gateway 网关通道，并暴露 QA Lab 页面，操作员或自动化循环可以在其中给智能体分配一个 QA 任务、观察真实渠道行为，并记录哪些内容有效、哪些失败了，或哪些仍然受阻。 -如果你想更快迭代 QA Lab UI，而不必每次都重建 Docker 镜像，可以使用绑定挂载的 QA Lab bundle 启动该栈： +如果你想在不每次都重建 Docker 镜像的情况下更快迭代 QA Lab UI，请使用绑定挂载的 QA Lab bundle 启动此栈： ```bash pnpm openclaw qa docker-build-image @@ -46,48 +46,48 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` 会让 Docker 服务保持在预构建镜像上运行，并将 `extensions/qa-lab/web/dist` 绑定挂载到 `qa-lab` 容器中。`qa:lab:watch` 会在变更时重建该 bundle，当 QA Lab 资源哈希发生变化时，浏览器会自动重新加载。 +`qa:lab:up:fast` 会让 Docker 服务保持在一个预构建镜像上，并将 `extensions/qa-lab/web/dist` 绑定挂载到 `qa-lab` 容器中。`qa:lab:watch` 会在变更时重建该 bundle，当 QA Lab 资源哈希变化时，浏览器会自动重新加载。 -若要运行一个基于真实传输层的 Matrix 冒烟测试通道，请执行： +若要运行一个传输层真实的 Matrix 冒烟通道，请执行： ```bash pnpm openclaw qa matrix ``` -该通道会在 Docker 中配置一个一次性的 Tuwunel homeserver，注册临时的驱动、SUT 和观察者用户，创建一个私有房间，然后在 QA gateway 子进程中运行真实的 Matrix 插件。实时传输通道会将子进程配置限定在被测试的传输协议上，因此 Matrix 会在子进程配置中不包含 `qa-channel` 的情况下运行。它会将结构化报告产物以及合并后的 stdout/stderr 日志写入所选的 Matrix QA 输出目录。若还要捕获外层 `scripts/run-node.mjs` 的构建/启动输出，请将 `OPENCLAW_RUN_NODE_OUTPUT_LOG=` 设置为仓库本地日志文件。 +该通道会在 Docker 中配置一个一次性的 Tuwunel homeserver，注册临时的 driver、SUT 和 observer 用户，创建一个私有房间，然后在一个 QA Gateway 网关子进程中运行真实的 Matrix 插件。实时传输通道会将子进程配置限制在被测传输协议范围内，因此 Matrix 会在子进程配置中不包含 `qa-channel` 的情况下运行。它会将结构化报告产物以及合并后的 stdout/stderr 日志写入所选的 Matrix QA 输出目录。若还要捕获外层 `scripts/run-node.mjs` 的构建/启动器输出，请将 `OPENCLAW_RUN_NODE_OUTPUT_LOG=` 设置为一个位于仓库内的日志文件。 -若要运行一个基于真实传输层的 Telegram 冒烟测试通道，请执行： +若要运行一个传输层真实的 Telegram 冒烟通道，请执行： ```bash pnpm openclaw qa telegram ``` -该通道会使用一个真实的私有 Telegram 群组，而不是配置一次性服务器。它要求提供 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` 和 `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`，并要求两个不同的 bot 位于同一个私有群组中。SUT bot 必须具有 Telegram 用户名；如果两个 bot 都在 `@BotFather` 中启用了 Bot-to-Bot Communication Mode，则 bot 对 bot 的观察效果最佳。 -当任一场景失败时，该命令会以非零状态退出。如果你想保留产物但不以失败退出码结束，请使用 `--allow-failures`。 -Telegram 报告和摘要还会包含每次回复的 RTT，从驱动消息发送请求开始，到观察到 SUT 回复为止，金丝雀场景也包括在内。 +该通道会面向一个真实的私有 Telegram 群组，而不是配置一个一次性服务器。它需要 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` 和 `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`，并且要求同一个私有群组中有两个不同的机器人。SUT 机器人必须具有一个 Telegram 用户名，并且当两个机器人都在 `@BotFather` 中启用了 Bot-to-Bot Communication Mode 时，机器人之间的观察效果最佳。 +当任一场景失败时，该命令会以非零状态退出。如果你想保留产物但不希望退出码失败，请使用 `--allow-failures`。 +Telegram 报告和摘要包含每次回复的 RTT，从 driver 消息发送请求到观测到的 SUT 回复进行计时，从 canary 开始。 -实时传输通道现在共享一个更小的契约，而不是各自设计自己的场景列表结构： +实时传输通道现在共享一个更小的统一契约，而不是各自发明自己的场景列表形态： -`qa-channel` 仍然是更广泛的合成产品行为套件，不属于实时传输覆盖矩阵的一部分。 +`qa-channel` 仍然是覆盖面广泛的合成产品行为套件，不属于实时传输覆盖矩阵的一部分。 -| 通道 | 金丝雀 | 提及门控 | 白名单拦截 | 顶层回复 | 重启恢复 | 线程后续回复 | 线程隔离 | 表情回应观察 | 帮助命令 | -| ---- | ------ | -------- | ---------- | -------- | -------- | ------------ | -------- | ------------ | -------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| 通道 | Canary | 提及门控 | 允许列表阻止 | 顶层回复 | 重启恢复 | 线程后续跟进 | 线程隔离 | 反应观察 | 帮助命令 | +| ---- | ------ | -------- | ------------ | -------- | -------- | ------------ | -------- | -------- | -------- | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | -这样可以让 `qa-channel` 继续作为广泛的产品行为套件，而 Matrix、Telegram 以及未来的实时传输协议共享一份显式的传输契约检查清单。 +这使 `qa-channel` 继续作为覆盖面广泛的产品行为套件，而 Matrix、Telegram 以及未来的实时传输协议则共享一份明确的传输契约检查清单。 -若要运行一个一次性的 Linux VM 通道，而不将 Docker 纳入 QA 路径，请执行： +若要运行一个无需将 Docker 引入 QA 路径的一次性 Linux VM 通道，请执行： ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -这会启动一个全新的 Multipass guest，在 guest 内安装依赖、构建 OpenClaw、运行 `qa suite`，然后将常规 QA 报告和摘要复制回主机上的 `.artifacts/qa-e2e/...`。 -它会复用与主机上 `qa suite` 相同的场景选择行为。 -主机和 Multipass 的 suite 运行默认都会并行执行多个选中的场景，并使用隔离的 gateway worker。`qa-channel` 默认并发度为 4，但不会超过所选场景数量。使用 `--concurrency ` 可调整 worker 数量，或使用 `--concurrency 1` 进行串行执行。 -当任一场景失败时，该命令会以非零状态退出。如果你想保留产物但不以失败退出码结束，请使用 `--allow-failures`。 -实时运行会转发适合 guest 使用的受支持 QA 认证输入：基于环境变量的提供商密钥、QA 实时提供商配置路径，以及存在时的 `CODEX_HOME`。请将 `--output-dir` 保持在仓库根目录下，以便 guest 可以通过挂载的工作区写回内容。 +这会启动一个全新的 Multipass guest，在 guest 中安装依赖、构建 OpenClaw、运行 `qa suite`，然后将常规 QA 报告和摘要复制回宿主机上的 `.artifacts/qa-e2e/...`。 +它会复用与宿主机上 `qa suite` 相同的场景选择行为。 +宿主机和 Multipass 套件运行默认都会以多个隔离的 Gateway 网关工作进程并行执行多个被选中的场景。`qa-channel` 默认并发数为 4，并受所选场景数量限制。使用 `--concurrency ` 可调整工作进程数量，或使用 `--concurrency 1` 进行串行执行。 +当任一场景失败时，该命令会以非零状态退出。如果你想保留产物但不希望退出码失败，请使用 `--allow-failures`。 +实时运行会转发适合 guest 使用的受支持 QA 凭证输入：基于 env 的提供商密钥、QA 实时 provider 配置路径，以及存在时的 `CODEX_HOME`。请将 `--output-dir` 保持在仓库根目录下，以便 guest 能通过挂载的工作区回写内容。 ## 由仓库支持的种子资源 @@ -96,70 +96,72 @@ pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline - `qa/scenarios/index.md` - `qa/scenarios//*.md` -这些文件有意保存在 git 中，以便 QA 计划对人类和智能体都可见。 +这些内容特意保存在 git 中，以便 QA 计划对人类和智能体都可见。 -`qa-lab` 应保持为一个通用 Markdown 运行器。每个场景 Markdown 文件都是一次测试运行的事实来源，并应定义： +`qa-lab` 应保持为一个通用的 Markdown 运行器。每个场景 Markdown 文件都是一次测试运行的事实来源，并且应定义以下内容： - 场景元数据 -- 可选的分类、能力、通道和风险元数据 -- 文档和代码引用 +- 可选的 category、capability、lane 和 risk 元数据 +- docs 和 code 引用 - 可选的插件要求 - 可选的 Gateway 网关配置补丁 - 可执行的 `qa-flow` -支撑 `qa-flow` 的可复用运行时表面可以保持通用且跨领域。例如，Markdown 场景可以组合传输侧辅助工具与浏览器侧辅助工具，通过 Gateway 网关 `browser.request` 接缝驱动嵌入式控制 UI，而无需添加特例运行器。 +支撑 `qa-flow` 的可复用运行时表面允许保持通用和跨领域。例如，Markdown 场景可以将传输侧辅助工具与浏览器侧辅助工具结合起来，通过 Gateway 网关 `browser.request` 接缝驱动嵌入式 Control UI，而无需添加特殊情况运行器。 -场景文件应按产品能力分组，而不是按源码树文件夹分组。即使文件移动，也要保持场景 ID 稳定；使用 `docsRefs` 和 `codeRefs` 来实现实现层面的可追溯性。 +场景文件应按产品能力分组，而不是按源代码树文件夹分组。文件移动时请保持场景 ID 稳定；使用 `docsRefs` 和 `codeRefs` 进行实现可追溯性标注。 -基线列表应足够广泛，以覆盖： +基线列表应保持足够广泛，以覆盖： - 私信和渠道聊天 - 线程行为 -- 消息动作生命周期 +- 消息操作生命周期 - cron 回调 - 记忆召回 - 模型切换 - 子智能体交接 -- 读取仓库和读取文档 +- 仓库读取和文档读取 - 一个小型构建任务，例如 Lobster Invaders -## 提供商 mock 通道 +## provider 模拟通道 -`qa suite` 具有两个本地提供商 mock 通道： +`qa suite` 有两个本地 provider 模拟通道： -- `mock-openai` 是具备场景感知能力的 OpenClaw mock。它仍然是由仓库支持的 QA 和一致性验证的默认确定性 mock 通道。 -- `aimock` 会启动一个由 AIMock 支持的提供商服务器，用于实验性协议、夹具、录制/回放和混沌测试覆盖。它是增量补充，不会替代 `mock-openai` 场景分发器。 +- `mock-openai` 是具备场景感知能力的 OpenClaw 模拟器。它仍然是由仓库支持的 QA 和一致性门禁的默认确定性模拟通道。 +- `aimock` 会启动一个由 AIMock 支持的 provider 服务器，用于实验性协议、夹具、录制/回放和混沌覆盖。它是附加能力，不会替代 `mock-openai` 场景分发器。 -提供商通道实现位于 `extensions/qa-lab/src/providers/` 下。每个提供商都负责自己的默认值、本地服务器启动、gateway 模型配置、auth-profile 暂存需求，以及 live/mock 能力标志。共享 suite 和 gateway 代码应通过提供商注册表进行路由，而不是根据提供商名称分支。 +provider 通道实现位于 `extensions/qa-lab/src/providers/` 下。 +每个 provider 负责自己的默认值、本地服务器启动、Gateway 网关模型配置、auth profile 暂存需求，以及实时/模拟能力标记。共享的 suite 和 Gateway 网关代码应通过 provider 注册表进行路由，而不是根据 provider 名称分支。 ## 传输适配器 -`qa-lab` 为 Markdown QA 场景提供一个通用传输接缝。 -`qa-channel` 是该接缝上的第一个适配器，但设计目标更广：未来无论是真实渠道还是合成渠道，都应接入同一个 suite 运行器，而不是新增特定于传输协议的 QA 运行器。 +`qa-lab` 拥有一个用于 Markdown QA 场景的通用传输接缝。 +`qa-channel` 是该接缝上的第一个适配器，但设计目标更广：未来的真实或合成渠道应接入同一个 suite 运行器，而不是添加一个特定于传输协议的 QA 运行器。 -在架构层面，划分如下： +从架构层面看，拆分如下： -- `qa-lab` 负责通用场景执行、worker 并发、产物写入和报告生成。 -- 传输适配器负责 gateway 配置、就绪性、入站和出站观察、传输动作以及标准化的传输状态。 -- `qa/scenarios/` 下的 Markdown 场景文件定义测试运行；`qa-lab` 提供执行它们的可复用运行时表面。 +- `qa-lab` 负责通用场景执行、工作进程并发、产物写入和报告。 +- 传输适配器负责 Gateway 网关配置、就绪状态、入站和出站观察、传输动作以及标准化的传输状态。 +- `qa/scenarios/` 下的 Markdown 场景文件定义测试运行；`qa-lab` 提供执行这些场景的可复用运行时表面。 -面向维护者的新渠道适配器接入指南位于 [测试](/zh-CN/help/testing#adding-a-channel-to-qa)。 +面向维护者的新渠道适配器接入指南位于 +[测试](/zh-CN/help/testing#adding-a-channel-to-qa)。 ## 报告 -`qa-lab` 会根据观察到的总线时间线导出 Markdown 协议报告。 +`qa-lab` 会基于观测到的总线时间线导出一份 Markdown 协议报告。 该报告应回答： -- 哪些内容成功了 -- 哪些内容失败了 +- 哪些内容有效 +- 哪些内容失败 - 哪些内容仍然受阻 -- 值得补充哪些后续场景 +- 值得添加哪些后续场景 -对于角色和风格检查，可让同一场景在多个实时模型引用上运行，并输出一份经评审的 Markdown 报告： +对于角色和风格检查，请在多个实时模型引用上运行同一个场景，并写出一份经评审的 Markdown 报告： ```bash pnpm openclaw qa character-eval \ - --model openai/gpt-5.4,thinking=xhigh \ + --model openai/gpt-5.5,thinking=xhigh \ --model openai/gpt-5.2,thinking=xhigh \ --model openai/gpt-5,thinking=xhigh \ --model anthropic/claude-opus-4-6,thinking=high \ @@ -167,20 +169,26 @@ pnpm openclaw qa character-eval \ --model zai/glm-5.1,thinking=high \ --model moonshot/kimi-k2.5,thinking=high \ --model google/gemini-3.1-pro-preview,thinking=high \ - --judge-model openai/gpt-5.4,thinking=xhigh,fast \ + --judge-model openai/gpt-5.5,thinking=xhigh,fast \ --judge-model anthropic/claude-opus-4-6,thinking=high \ --blind-judge-models \ --concurrency 16 \ --judge-concurrency 16 ``` -该命令运行的是本地 QA gateway 子进程，而不是 Docker。角色评估场景应通过 `SOUL.md` 设置 persona，然后运行普通用户轮次，例如聊天、工作区帮助和小型文件任务。候选模型不应被告知自己正在接受评估。该命令会保留每份完整转录、记录基础运行统计信息，然后让评审模型以 fast 模式和 `xhigh` 推理来按自然度、氛围和幽默感对这些运行进行排序。 -在比较不同提供商时，请使用 `--blind-judge-models`：评审提示仍会收到每份转录和运行状态，但候选引用会被替换为 `candidate-01` 之类的中性标签；在解析完成后，报告会将排序结果映射回真实引用。 -候选运行默认使用 `high` thinking，而支持的 OpenAI 模型默认使用 `xhigh`。你可以用 `--model provider/model,thinking=` 为特定候选单独覆盖。`--thinking ` 仍可设置全局后备值，而旧的 `--model-thinking ` 形式也会为了兼容性而保留。 -OpenAI 候选引用默认使用 fast 模式，以便在提供商支持时使用优先处理。若某个候选或评审需要覆盖，请内联添加 `,fast`、`,no-fast` 或 `,fast=false`。只有当你想为所有候选模型强制启用 fast 模式时，才传递 `--fast`。报告中会记录候选和评审的耗时，以供基准分析，但评审提示会明确说明不要根据速度进行排序。 -候选和评审模型运行的默认并发度都是 16。如果提供商限制或本地 gateway 压力导致运行噪声过大，请降低 `--concurrency` 或 `--judge-concurrency`。 -当未传递候选 `--model` 时，角色评估默认使用 `openai/gpt-5.4`、`openai/gpt-5.2`、`openai/gpt-5`、`anthropic/claude-opus-4-6`、`anthropic/claude-sonnet-4-6`、`zai/glm-5.1`、`moonshot/kimi-k2.5` 和 `google/gemini-3.1-pro-preview`。 -当未传递 `--judge-model` 时，评审默认使用 `openai/gpt-5.4,thinking=xhigh,fast` 和 `anthropic/claude-opus-4-6,thinking=high`。 +该命令运行的是本地 QA Gateway 网关子进程，而不是 Docker。角色评估场景应通过 `SOUL.md` 设置 persona，然后运行普通用户轮次，例如聊天、工作区帮助和小型文件任务。候选模型不应被告知自己正在接受评估。该命令会保留每一份完整转录，记录基本运行统计信息，然后以快速模式和 `xhigh` 推理让评审模型按自然度、氛围和幽默感对这些运行进行排序。 +在比较不同 provider 时，请使用 `--blind-judge-models`：评审提示仍会获得每份转录和运行状态，但候选引用会被替换为诸如 `candidate-01` 之类的中性标签；报告会在解析后将排名映射回真实引用。 +候选运行默认使用 `high` thinking，对于支持它的 OpenAI 模型则使用 `xhigh`。可通过 `--model provider/model,thinking=` 内联覆盖某个特定候选项。`--thinking ` 仍会设置全局后备值，而较旧的 `--model-thinking ` 形式也会为兼容性保留。 +OpenAI 候选引用默认使用快速模式，以便在 provider 支持时使用优先处理。若单个候选项或评审项需要覆盖，请内联添加 `,fast`、`,no-fast` 或 `,fast=false`。仅当你希望对每个候选模型都强制启用快速模式时，才传入 `--fast`。候选和评审时长都会记录在报告中用于基准分析，但评审提示会明确说明不要按速度排序。 +候选模型和评审模型运行的默认并发数都是 16。当 provider 限制或本地 Gateway 网关压力使运行噪声过大时，请降低 `--concurrency` 或 `--judge-concurrency`。 +当未传入候选 `--model` 时，角色评估默认使用 +`openai/gpt-5.5`、`openai/gpt-5.2`、`openai/gpt-5`、`anthropic/claude-opus-4-6`、 +`anthropic/claude-sonnet-4-6`、`zai/glm-5.1`、 +`moonshot/kimi-k2.5` 和 +`google/gemini-3.1-pro-preview`。 +当未传入 `--judge-model` 时，评审默认使用 +`openai/gpt-5.5,thinking=xhigh,fast` 和 +`anthropic/claude-opus-4-6,thinking=high`。 ## 相关文档 diff --git a/docs/zh-CN/gateway/cli-backends.md b/docs/zh-CN/gateway/cli-backends.md index 3d4151fca..383c137bc 100644 --- a/docs/zh-CN/gateway/cli-backends.md +++ b/docs/zh-CN/gateway/cli-backends.md @@ -1,41 +1,41 @@ --- read_when: - - 当 API 提供商失败时，你希望有一个可靠的回退方案 + - 当 API 提供商失效时，你希望有一个可靠的回退方案 - 你正在运行 Codex CLI 或其他本地 AI CLI，并希望复用它们 - - 你想了解用于 CLI 后端工具访问的 MCP loopback 桥接机制 -summary: CLI 后端：本地 AI CLI 回退机制，可选 MCP 工具桥接 + - 你想了解用于 CLI 后端工具访问的 MCP loopback 桥接器 +summary: CLI 后端：带可选 MCP 工具桥接的本地 AI CLI 回退方案 title: CLI 后端 x-i18n: - generated_at: "2026-04-23T14:54:03Z" + generated_at: "2026-04-23T19:23:51Z" model: gpt-5.4 provider: openai - source_hash: ff7458d18b8a5b716930579241177917fd3edffcf7f6e211c7d570cf76519316 + source_hash: 3709769c7fd88be1c455001d77472848f1b65a8aac499c6c35b063c4faa1cbfb source_path: gateway/cli-backends.md workflow: 15 --- # CLI 后端（回退运行时） -当 API 提供商不可用、触发速率限制或暂时行为异常时，OpenClaw 可以运行**本地 AI CLI**作为**纯文本回退**。这项设计刻意保持保守： +当 API 提供商不可用、遭遇速率限制或暂时行为异常时，OpenClaw 可以运行**本地 AI CLI** 作为**纯文本回退方案**。这一设计刻意保持保守： -- **OpenClaw 工具不会被直接注入**，但带有 `bundleMcp: true` 的后端可以通过 loopback MCP 桥接接收 Gateway 网关工具。 -- 对支持该能力的 CLI 提供 **JSONL 流式传输**。 -- **支持会话**（因此后续轮次可以保持连贯）。 +- **不会直接注入 OpenClaw 工具**，但设置了 `bundleMcp: true` 的后端可以通过 loopback MCP 桥接接收 Gateway 网关工具。 +- 为支持的 CLI 提供 **JSONL 流式传输**。 +- **支持会话**（因此后续轮次能够保持连贯）。 - 如果 CLI 接受图片路径，**图片也可以透传**。 -这被设计为一种**安全兜底机制**，而不是主路径。当你想要“不依赖外部 API 也始终可用”的文本响应时，可以使用它。 +它的定位是一个**安全兜底机制**，而不是主要路径。当你希望获得“不管怎样都能工作”的文本回复，而不依赖外部 API 时，可以使用它。 -如果你需要具备 ACP 会话控制、后台任务、线程/对话绑定以及持久化外部编码会话的完整 harness 运行时，请改用 [ACP Agents](/zh-CN/tools/acp-agents)。CLI 后端不是 ACP。 +如果你需要带有 ACP 会话控制、后台任务、线程/对话绑定以及持久化外部编码会话的完整 harness 运行时，请改用 [ACP Agents](/zh-CN/tools/acp-agents)。CLI 后端不是 ACP。 ## 面向初学者的快速开始 -你可以**无需任何配置**使用 Codex CLI（内置的 OpenAI 插件会注册一个默认后端）： +你可以**无需任何配置**使用 Codex CLI（内置 OpenAI 插件会注册一个默认后端）： ```bash -openclaw agent --message "hi" --model codex-cli/gpt-5.4 +openclaw agent --message "hi" --model codex-cli/gpt-5.5 ``` -如果你的 Gateway 网关运行在 launchd/systemd 下且 `PATH` 很精简，只需添加命令路径： +如果你的 Gateway 网关运行在 launchd/systemd 下且 PATH 很精简，只需添加命令路径： ```json5 { @@ -51,13 +51,13 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4 } ``` -就是这样。除了 CLI 自身之外，不需要密钥，也不需要额外的认证配置。 +就是这样。除了 CLI 本身所需的配置外，不需要密钥，也不需要额外的认证配置。 -如果你在 Gateway 网关主机上把某个内置 CLI 后端用作**主要消息提供商**，当你的配置在模型引用中或在 `agents.defaults.cliBackends` 下显式引用该后端时，OpenClaw 现在会自动加载其所属的内置插件。 +如果你将某个内置 CLI 后端作为 Gateway 网关主机上的**主要消息提供商**使用，当你的配置在模型引用或 `agents.defaults.cliBackends` 下显式引用该后端时，OpenClaw 现在会自动加载其所属的内置插件。 -## 将它用作回退 +## 将其用作回退方案 -将 CLI 后端加入你的回退列表，这样它只会在主模型失败时运行： +将 CLI 后端添加到你的回退列表中，这样它只会在主模型失败时运行： ```json5 { @@ -65,11 +65,11 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4 defaults: { model: { primary: "anthropic/claude-opus-4-6", - fallbacks: ["codex-cli/gpt-5.4"], + fallbacks: ["codex-cli/gpt-5.5"], }, models: { "anthropic/claude-opus-4-6": { alias: "Opus" }, - "codex-cli/gpt-5.4": {}, + "codex-cli/gpt-5.5": {}, }, }, }, @@ -78,8 +78,8 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4 说明： -- 如果你使用 `agents.defaults.models`（允许列表），也必须把你的 CLI 后端模型包含进去。 -- 如果主提供商失败（认证、速率限制、超时），OpenClaw 会接着尝试 CLI 后端。 +- 如果你使用 `agents.defaults.models`（允许列表），你也必须在其中包含 CLI 后端模型。 +- 如果主提供商失败（认证、速率限制、超时），OpenClaw 接下来会尝试 CLI 后端。 ## 配置概览 @@ -89,8 +89,8 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4 agents.defaults.cliBackends ``` -每个条目都以一个**提供商 id** 为键（例如 `codex-cli`、`my-cli`）。 -这个提供商 id 会成为你的模型引用左侧部分： +每个条目都以**提供商 id** 作为键（例如 `codex-cli`、`my-cli`）。 +该提供商 id 会成为你的模型引用左侧部分： ``` / @@ -120,7 +120,7 @@ agents.defaults.cliBackends sessionMode: "existing", sessionIdFields: ["session_id", "conversation_id"], systemPromptArg: "--system", - // 对于 Codex 风格的 CLI，也可以改为指向一个提示文件： + // 对于 Codex 风格的 CLI，也可以改为指向提示词文件： // systemPromptFileConfigArg: "-c", // systemPromptFileConfigKey: "model_instructions_file", systemPromptWhen: "first", @@ -138,21 +138,22 @@ agents.defaults.cliBackends 1. 根据提供商前缀（`codex-cli/...`）**选择后端**。 2. 使用相同的 OpenClaw 提示词和工作区上下文**构建系统提示词**。 -3. 使用会话 id（如果支持）**执行 CLI**，以保持历史一致。 +3. 使用会话 id（如果支持）**执行 CLI**，从而保持历史一致。 内置的 `claude-cli` 后端会为每个 OpenClaw 会话保持一个 Claude stdio 进程存活，并通过 stream-json stdin 发送后续轮次。 4. **解析输出**（JSON 或纯文本）并返回最终文本。 -5. 按后端**持久化会话 id**，以便后续轮次复用同一个 CLI 会话。 +5. 按后端**持久化会话 id**，这样后续轮次可以复用同一个 CLI 会话。 -内置的 Anthropic `claude-cli` 后端现已再次受支持。Anthropic 员工告诉我们，再次允许 OpenClaw 风格的 Claude CLI 用法，因此除非 Anthropic 发布新的策略，否则 OpenClaw 会将这种用于该集成的 `claude -p` 用法视为已获认可。 +内置的 Anthropic `claude-cli` 后端现已再次受支持。Anthropic 工作人员告诉我们，再次允许 OpenClaw 风格的 Claude CLI 用法，因此除非 Anthropic 发布新的政策，否则 OpenClaw 将 `claude -p` 用法视为该集成的已认可方式。 内置的 OpenAI `codex-cli` 后端会通过 Codex 的 `model_instructions_file` 配置覆盖项（`-c -model_instructions_file="..."`）传递 OpenClaw 的系统提示词。Codex 并未提供 Claude 风格的 `--append-system-prompt` 标志，因此 OpenClaw 会为每个新的 Codex CLI 会话将组装后的提示词写入临时文件。 +model_instructions_file="..."`）传递 OpenClaw 的系统提示词。Codex 不提供类似 Claude 的 +`--append-system-prompt` 标志，因此 OpenClaw 会为每个新的 Codex CLI 会话将组装后的提示词写入临时文件。 -内置的 Anthropic `claude-cli` 后端以两种方式接收 OpenClaw Skills 快照：一种是追加系统提示词中的精简 OpenClaw Skills 目录，另一种是通过 `--plugin-dir` 传入的临时 Claude Code 插件。该插件只包含对当前智能体/会话有资格使用的 Skills，因此 Claude Code 的原生 skill 解析器看到的过滤后集合，与 OpenClaw 原本会在提示词中公布的集合相同。Skills 的 env/API 密钥覆盖仍然由 OpenClaw 应用于本次运行的子进程环境。 +内置的 Anthropic `claude-cli` 后端会通过两种方式接收 OpenClaw 的 Skills 快照：其一是附加系统提示词中的精简 OpenClaw Skills 目录，其二是通过 `--plugin-dir` 传入的临时 Claude Code 插件。该插件只包含对该智能体/会话符合条件的 Skills，因此 Claude Code 的原生 Skills 解析器看到的就是与 OpenClaw 原本会在提示词中公布的同一组过滤结果。对于运行过程中的 Skill 环境变量/API 密钥覆盖，仍由 OpenClaw 应用到子进程环境中。 -在 OpenClaw 能使用内置 `claude-cli` 后端之前，Claude Code 本身必须已经在同一主机上完成登录： +在 OpenClaw 能使用内置 `claude-cli` 后端之前，Claude Code 本身必须已经在同一台主机上登录： ```bash claude auth login @@ -160,27 +161,28 @@ claude auth status --text openclaw models auth login --provider anthropic --method cli --set-default ``` -只有当 `claude` 二进制文件不在 `PATH` 上时，才使用 `agents.defaults.cliBackends.claude-cli.command`。 +只有当 `claude` 二进制文件不在 `PATH` 中时，才需要使用 `agents.defaults.cliBackends.claude-cli.command`。 ## 会话 -- 如果 CLI 支持会话，设置 `sessionArg`（例如 `--session-id`）或 - `sessionArgs`（占位符 `{sessionId}`），用于需要将该 id 插入多个标志的情况。 +- 如果 CLI 支持会话，请设置 `sessionArg`（例如 `--session-id`）或 + `sessionArgs`（占位符为 `{sessionId}`），适用于需要将 ID 插入多个标志的情况。 - 如果 CLI 使用带有不同标志的**恢复子命令**，请设置 - `resumeArgs`（恢复时替换 `args`），并可选设置 `resumeOutput` - （用于非 JSON 恢复）。 + `resumeArgs`（恢复时替换 `args`），并可选择设置 `resumeOutput` + （用于非 JSON 的恢复输出）。 - `sessionMode`： - `always`：始终发送会话 id（如果未存储则生成新的 UUID）。 - - `existing`：只有先前已存储时才发送会话 id。 + - `existing`：只有之前已存储会话 id 时才发送。 - `none`：永不发送会话 id。 -- `claude-cli` 默认使用 `liveSession: "claude-stdio"`、`output: "jsonl"` 和 `input: "stdin"`，因此只要进程仍然活跃，后续轮次就会复用这个活动中的 Claude 进程。现在默认就是 warm stdio，包括那些省略传输字段的自定义配置。如果 Gateway 网关重启，或空闲进程退出，OpenClaw 会从已存储的 Claude 会话 id 恢复。在恢复前，已存储的会话 id 会先与现有且可读的项目转录记录进行校验，因此虚假的绑定会以 `reason=transcript-missing` 被清除，而不是在 `--resume` 下悄悄启动一个新的 Claude CLI 会话。 -- 已存储的 CLI 会话属于提供商拥有的连续性。隐式的每日会话重置不会切断它们；`/reset` 和显式的 `session.reset` 策略仍然会切断。 +- `claude-cli` 默认使用 `liveSession: "claude-stdio"`、`output: "jsonl"`， + 以及 `input: "stdin"`，这样在 Claude 进程仍处于活动状态时，后续轮次就能复用该实时 Claude 进程。现在默认就是预热的 stdio，包括那些省略传输字段的自定义配置。如果 Gateway 网关重启或空闲进程退出，OpenClaw 会从已存储的 Claude 会话 id 恢复。已存储的会话 id 会先针对现有且可读取的项目转录记录进行验证，之后才会恢复，因此虚假的绑定会以 `reason=transcript-missing` 被清除，而不是在 `--resume` 下悄悄启动一个全新的 Claude CLI 会话。 +- 已存储的 CLI 会话属于提供商连续性的一部分。隐式的每日会话重置不会切断它们；但 `/reset` 和显式的 `session.reset` 策略仍然会切断。 序列化说明： -- `serialize: true` 会保持同一 lane 中的运行顺序。 -- 大多数 CLI 会在一个提供商 lane 上串行化。 -- 当所选认证身份发生变化时，OpenClaw 会放弃复用已存储的 CLI 会话，包括认证配置文件 id 变化、静态 API 密钥变化、静态令牌变化，或当 CLI 暴露该信息时 OAuth 账户身份变化。OAuth 访问令牌和刷新令牌轮换不会切断已存储的 CLI 会话。如果某个 CLI 没有暴露稳定的 OAuth 账户 id，OpenClaw 会让该 CLI 自行决定恢复权限。 +- `serialize: true` 会保持同一执行通道中的运行按顺序进行。 +- 大多数 CLI 都会在一个提供商通道上串行执行。 +- 当所选认证身份发生变化时，OpenClaw 会放弃复用已存储的 CLI 会话，这包括认证配置文件 id、静态 API 密钥、静态令牌，或 CLI 暴露出的 OAuth 账户身份发生变化。OAuth 访问令牌和刷新令牌轮换不会切断已存储的 CLI 会话。如果某个 CLI 没有暴露稳定的 OAuth 账户 id，OpenClaw 会让该 CLI 自行强制执行恢复权限。 ## 图片（透传） @@ -191,24 +193,24 @@ imageArg: "--image", imageMode: "repeat" ``` -OpenClaw 会将 base64 图片写入临时文件。如果设置了 `imageArg`，这些路径会作为 CLI 参数传入。如果缺少 `imageArg`，OpenClaw 会把文件路径追加到提示词中（路径注入）；对于那些能从普通路径自动加载本地文件的 CLI，这已经足够。 +OpenClaw 会将 base64 图片写入临时文件。如果设置了 `imageArg`，这些路径会作为 CLI 参数传入。如果缺少 `imageArg`，OpenClaw 会将文件路径附加到提示词中（路径注入），这对于那些能够从普通路径自动加载本地文件的 CLI 已经足够。 ## 输入 / 输出 -- `output: "json"`（默认）会尝试解析 JSON 并提取文本与会话 id。 +- `output: "json"`（默认）会尝试解析 JSON 并提取文本和会话 id。 - 对于 Gemini CLI 的 JSON 输出，当 `usage` 缺失或为空时，OpenClaw 会从 `response` 读取回复文本，并从 `stats` 读取用量。 -- `output: "jsonl"` 会解析 JSONL 流（例如 Codex CLI `--json`），并提取最终智能体消息以及存在时的会话标识符。 +- `output: "jsonl"` 会解析 JSONL 流（例如 Codex CLI `--json`），并提取最终智能体消息以及其中存在的会话标识符。 - `output: "text"` 会将 stdout 视为最终响应。 输入模式： -- `input: "arg"`（默认）会将提示词作为最后一个 CLI 参数传递。 +- `input: "arg"`（默认）会将提示词作为最后一个 CLI 参数传入。 - `input: "stdin"` 会通过 stdin 发送提示词。 - 如果提示词很长且设置了 `maxPromptArgChars`，则会改用 stdin。 -## 默认值（插件拥有） +## 默认值（插件所属） -内置的 OpenAI 插件也为 `codex-cli` 注册了一个默认值： +内置的 OpenAI 插件也为 `codex-cli` 注册了一个默认配置： - `command: "codex"` - `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]` @@ -219,7 +221,7 @@ OpenClaw 会将 base64 图片写入临时文件。如果设置了 `imageArg`， - `imageArg: "--image"` - `sessionMode: "existing"` -内置的 Google 插件也为 `google-gemini-cli` 注册了一个默认值： +内置的 Google 插件也为 `google-gemini-cli` 注册了一个默认配置： - `command: "gemini"` - `args: ["--output-format", "json", "--prompt", "{prompt}"]` @@ -230,30 +232,30 @@ OpenClaw 会将 base64 图片写入临时文件。如果设置了 `imageArg`， - `sessionMode: "existing"` - `sessionIdFields: ["session_id", "sessionId"]` -前提条件：本地 Gemini CLI 必须已安装，并且可通过 `PATH` 中的 +前提条件：本地 Gemini CLI 必须已经安装，并且可在 `PATH` 中作为 `gemini` 使用（`brew install gemini-cli` 或 `npm install -g @google/gemini-cli`）。 Gemini CLI JSON 说明： - 回复文本从 JSON 的 `response` 字段读取。 -- 当 `usage` 缺失或为空时，用量会回退到 `stats`。 -- `stats.cached` 会被规范化为 OpenClaw `cacheRead`。 -- 如果 `stats.input` 缺失，OpenClaw 会通过 +- 当 `usage` 不存在或为空时，用量会回退到 `stats`。 +- `stats.cached` 会被规范化为 OpenClaw 的 `cacheRead`。 +- 如果缺少 `stats.input`，OpenClaw 会根据 `stats.input_tokens - stats.cached` 推导输入 token 数。 -只有在需要时才覆盖这些默认值（常见情况：使用绝对 `command` 路径）。 +仅在必要时覆盖（常见情况：使用绝对 `command` 路径）。 -## 插件拥有的默认值 +## 插件所属默认值 -CLI 后端默认值现在属于插件表面的一部分： +CLI 后端默认值现在已成为插件表面的一部分： -- 插件使用 `api.registerCliBackend(...)` 注册它们。 +- 插件通过 `api.registerCliBackend(...)` 注册它们。 - 后端 `id` 会成为模型引用中的提供商前缀。 -- 用户在 `agents.defaults.cliBackends.` 中的配置仍然会覆盖插件默认值。 -- 后端特定的配置清理仍由插件通过可选的 `normalizeConfig` hook 负责。 +- 位于 `agents.defaults.cliBackends.` 下的用户配置仍会覆盖插件默认值。 +- 通过可选的 `normalizeConfig` 钩子，后端特定的配置清理逻辑仍归插件所有。 -需要微小提示词/消息兼容性 shim 的插件，可以声明双向文本转换，而无需替换某个提供商或 CLI 后端： +需要细小提示词/消息兼容性垫片的插件，可以声明双向文本转换，而无需替换提供商或 CLI 后端： ```typescript api.registerTextTransforms({ @@ -270,43 +272,45 @@ api.registerTextTransforms({ }); ``` -`input` 会重写传给 CLI 的系统提示词和用户提示词。`output` 会在 OpenClaw 处理其自身控制标记和渠道投递之前，重写流式传输的 assistant 增量以及解析后的最终文本。 +`input` 会重写传递给 CLI 的系统提示词和用户提示词。`output` +会在 OpenClaw 处理其自身控制标记和渠道投递之前，重写流式传输的助手增量内容以及解析后的最终文本。 -对于输出 Claude Code stream-json 兼容 JSONL 的 CLI，请在该后端配置上设置 +对于输出与 Claude Code stream-json 兼容的 JSONL 的 CLI，请在该后端配置上设置 `jsonlDialect: "claude-stream-json"`。 ## Bundle MCP 覆盖层 -CLI 后端**不会**直接接收 OpenClaw 工具调用，但后端可以通过设置 `bundleMcp: true` 选择加入一个生成的 MCP 配置覆盖层。 +CLI 后端**不会**直接接收 OpenClaw 工具调用，但后端可以通过设置 `bundleMcp: true` 选择启用生成的 MCP 配置覆盖层。 当前内置行为： -- `claude-cli`：生成严格的 MCP 配置文件 +- `claude-cli`：生成严格 MCP 配置文件 - `codex-cli`：为 `mcp_servers` 提供内联配置覆盖 - `google-gemini-cli`：生成 Gemini 系统设置文件 启用 bundle MCP 后，OpenClaw 会： -- 启动一个 loopback HTTP MCP 服务器，向 CLI 进程暴露 Gateway 网关工具 +- 启动一个 loopback HTTP MCP 服务器，将 Gateway 网关工具暴露给 CLI 进程 - 使用每会话令牌（`OPENCLAW_MCP_TOKEN`）对桥接进行认证 -- 将工具访问范围限定在当前会话、账户和渠道上下文中 +- 将工具访问范围限定在当前会话、账户和渠道上下文内 - 为当前工作区加载已启用的 bundle-MCP 服务器 -- 将它们与现有的后端 MCP 配置/设置结构合并 -- 使用所属扩展中由后端拥有的集成模式重写启动配置 +- 将它们与任何现有的后端 MCP 配置/设置结构合并 +- 使用所属扩展定义的集成模式重写启动配置 -如果没有启用任何 MCP 服务器，当某个后端选择加入 bundle MCP 时，OpenClaw 仍会注入严格配置，以确保后台运行保持隔离。 +如果没有启用任何 MCP 服务器，当某个后端选择启用 bundle MCP 时，OpenClaw 仍会注入严格配置，以便后台运行保持隔离。 ## 限制 -- **没有直接的 OpenClaw 工具调用。** OpenClaw 不会将工具调用注入到 CLI 后端协议中。后端只有在选择加入 `bundleMcp: true` 时，才会看到 Gateway 网关工具。 -- **流式传输是后端特定的。** 有些后端会流式输出 JSONL；另一些则会缓冲到退出时才输出。 +- **没有直接的 OpenClaw 工具调用。** OpenClaw 不会将工具调用注入到 + CLI 后端协议中。只有当后端选择启用 `bundleMcp: true` 时，它们才会看到 Gateway 网关工具。 +- **流式传输是后端特定的。** 有些后端会流式输出 JSONL；另一些则会缓冲直到退出。 - **结构化输出** 取决于 CLI 的 JSON 格式。 -- **Codex CLI 会话** 通过文本输出恢复（不是 JSONL），其结构化程度低于初始的 `--json` 运行。不过 OpenClaw 会话本身仍可正常工作。 +- **Codex CLI 会话** 通过文本输出恢复（不是 JSONL），因此其结构化程度低于初始的 `--json` 运行。不过 OpenClaw 会话仍会正常工作。 ## 故障排除 - **找不到 CLI**：将 `command` 设置为完整路径。 - **模型名称错误**：使用 `modelAliases` 将 `provider/model` 映射到 CLI 模型。 -- **没有会话连续性**：确保已设置 `sessionArg`，并且 `sessionMode` 不是 - `none`（Codex CLI 当前无法使用 JSON 输出进行恢复）。 +- **没有会话连续性**：确保已设置 `sessionArg`，且 `sessionMode` 不是 + `none`（Codex CLI 目前无法使用 JSON 输出进行恢复）。 - **图片被忽略**：设置 `imageArg`（并确认 CLI 支持文件路径）。 diff --git a/docs/zh-CN/gateway/configuration-examples.md b/docs/zh-CN/gateway/configuration-examples.md index b1f0423e0..68b8f803c 100644 --- a/docs/zh-CN/gateway/configuration-examples.md +++ b/docs/zh-CN/gateway/configuration-examples.md @@ -3,24 +3,24 @@ read_when: - 学习如何配置 OpenClaw - 查找配置示例 - 首次设置 OpenClaw -summary: 适用于常见 OpenClaw 设置、与 schema 精确对齐的配置示例 +summary: 适用于常见 OpenClaw 设置的符合 schema 的准确配置示例 title: 配置示例 x-i18n: - generated_at: "2026-04-05T08:23:29Z" + generated_at: "2026-04-23T19:24:17Z" model: gpt-5.4 provider: openai - source_hash: 1c85643b02285cefa2aaa9dd7c1e3abebb505bc8b415b5153b5899efc3ade0f7 + source_hash: 9b5f280003776000a24ab6f9174fcd85f3b159e58c9f22923c6c6ab9143682fb source_path: gateway/configuration-examples.md workflow: 15 --- # 配置示例 -以下示例与当前配置 schema 保持一致。完整参考和各字段说明，请参见[Configuration](/gateway/configuration)。 +以下示例与当前配置 schema 保持一致。若需完整参考和逐字段说明，请参见 [Configuration](/zh-CN/gateway/configuration)。 ## 快速开始 -### 绝对最小配置 +### 最小配置 ```json5 { @@ -29,9 +29,9 @@ x-i18n: } ``` -保存到 `~/.openclaw/openclaw.json`，然后你就可以用这个号码给机器人发送私信。 +保存到 `~/.openclaw/openclaw.json`，然后你就可以从该号码向机器人发送私信。 -### 推荐入门配置 +### 推荐起步配置 ```json5 { @@ -55,7 +55,7 @@ x-i18n: ## 扩展示例（主要选项） -> JSON5 允许你使用注释和尾随逗号。普通 JSON 也可以。 +> JSON5 允许使用注释和尾随逗号。普通 JSON 也可以。 ```json5 { @@ -71,7 +71,7 @@ x-i18n: }, }, - // Auth 配置文件元数据（秘密存储在 auth-profiles.json 中） + // 认证配置档元数据（密钥存放在 auth-profiles.json 中） auth: { profiles: { "anthropic:default": { provider: "anthropic", mode: "api_key" }, @@ -141,7 +141,7 @@ x-i18n: maxBytes: 20971520, models: [ { provider: "openai", model: "gpt-4o-mini-transcribe" }, - // 可选 CLI 回退（Whisper 二进制）： + // 可选的 CLI 回退（Whisper 二进制）： // { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] } ], timeoutSeconds: 120, @@ -243,7 +243,7 @@ x-i18n: userTimezone: "America/Chicago", model: { primary: "anthropic/claude-sonnet-4-6", - fallbacks: ["anthropic/claude-opus-4-6", "openai/gpt-5.4"], + fallbacks: ["anthropic/claude-opus-4-6", "openai/gpt-5.5"], }, imageModel: { primary: "openrouter/anthropic/claude-sonnet-4-6", @@ -251,9 +251,9 @@ x-i18n: models: { "anthropic/claude-opus-4-6": { alias: "opus" }, "anthropic/claude-sonnet-4-6": { alias: "sonnet" }, - "openai/gpt-5.4": { alias: "gpt" }, + "openai/gpt-5.5": { alias: "gpt" }, }, - skills: ["github", "weather"], // 会被未设置 list[].skills 的智能体继承 + skills: ["github", "weather"], // 被未设置 list[].skills 的智能体继承 thinkingDefault: "low", verboseDefault: "off", elevatedDefault: "on", @@ -293,7 +293,7 @@ x-i18n: }, sandbox: { mode: "non-main", - scope: "session", // 相较于旧版 perSession: true，更推荐 + scope: "session", // 优先于旧版 perSession: true workspaceRoot: "~/.openclaw/sandboxes", docker: { image: "openclaw-sandbox:bookworm-slim", @@ -313,14 +313,14 @@ x-i18n: id: "main", default: true, // 继承 defaults.skills -> github, weather - thinkingDefault: "high", // 按智能体覆盖 thinking - reasoningDefault: "on", // 按智能体设置 reasoning 可见性 - fastModeDefault: false, // 按智能体设置快速模式 + thinkingDefault: "high", // 每个智能体的 thinking 覆盖 + reasoningDefault: "on", // 每个智能体的推理可见性 + fastModeDefault: false, // 每个智能体的快速模式 }, { id: "quick", skills: [], // 这个智能体不使用任何 Skills - fastModeDefault: true, // 这个智能体始终快速运行 + fastModeDefault: true, // 这个智能体始终以快速模式运行 thinkingDefault: "off", }, ], @@ -374,7 +374,7 @@ x-i18n: }, }, - // Cron 任务 + // Cron 作业 cron: { enabled: true, store: "~/.openclaw/cron/cron.json", @@ -468,7 +468,7 @@ x-i18n: ## 常见模式 -### 共享 Skill 基线与单项覆盖 +### 共享 Skills 基线并覆盖一个智能体 ```json5 { @@ -486,8 +486,8 @@ x-i18n: ``` - `agents.defaults.skills` 是共享基线。 -- `agents.list[].skills` 会为单个智能体替换这套基线。 -- 如果某个智能体不应看到任何 Skills，请使用 `skills: []`。 +- `agents.list[].skills` 会替换某个智能体的这份基线。 +- 当某个智能体不应看到任何 Skills 时，请使用 `skills: []`。 ### 多平台设置 @@ -512,7 +512,7 @@ x-i18n: ### 安全私信模式（共享收件箱 / 多用户私信） -如果有多个人可以给你的机器人发私信（`allowFrom` 中有多个条目、为多个人批准了 pairing，或 `dmPolicy: "open"`），请启用**安全私信模式**，这样不同发送者的私信默认不会共享同一个上下文： +如果有多个人可以向你的机器人发送私信（`allowFrom` 中有多个条目、为多个人批准了配对，或使用 `dmPolicy: "open"`），请启用 **安全私信模式**，这样不同发送者发来的私信默认不会共享同一个上下文： ```json5 { @@ -536,10 +536,10 @@ x-i18n: } ``` -对于 Discord/Slack/Google Chat/Microsoft Teams/Mattermost/IRC，默认优先按发送者 ID 进行授权。 -只有在你明确接受这种风险的情况下，才启用各渠道中的 `dangerouslyAllowNameMatching: true`，以允许直接使用可变的名称/邮箱/昵称进行匹配。 +对于 Discord/Slack/Google Chat/Microsoft Teams/Mattermost/IRC，发送者授权默认优先基于 ID。 +只有在你明确接受该风险时，才通过各渠道的 `dangerouslyAllowNameMatching: true` 启用基于可变名称/邮箱/昵称的直接匹配。 -### Anthropic API key + MiniMax 回退 +### Anthropic API 密钥 + MiniMax 回退 ```json5 { @@ -598,7 +598,7 @@ x-i18n: } ``` -### 仅本地模型 +### 仅使用本地模型 ```json5 { @@ -633,6 +633,6 @@ x-i18n: ## 提示 - 如果你设置了 `dmPolicy: "open"`，对应的 `allowFrom` 列表必须包含 `"*"`。 -- provider ID 的格式各不相同（电话号码、用户 ID、渠道 ID）。请参阅 provider 文档确认格式。 -- 之后可以再添加的可选部分：`web`、`browser`、`ui`、`discovery`、`canvasHost`、`talk`、`signal`、`imessage`。 -- 更深入的设置说明请参见 [Providers](/providers) 和 [故障排除](/gateway/troubleshooting)。 +- 提供商 ID 各不相同（电话号码、用户 ID、渠道 ID）。请查阅提供商文档以确认格式。 +- 之后可以添加的可选部分包括：`web`、`browser`、`ui`、`discovery`、`canvasHost`、`talk`、`signal`、`imessage`。 +- 更深入的设置说明请参见 [Providers](/zh-CN/providers) 和 [故障排除](/zh-CN/gateway/troubleshooting)。 diff --git a/docs/zh-CN/gateway/configuration-reference.md b/docs/zh-CN/gateway/configuration-reference.md index aa342a7b6..94c9af7df 100644 --- a/docs/zh-CN/gateway/configuration-reference.md +++ b/docs/zh-CN/gateway/configuration-reference.md @@ -2,69 +2,69 @@ read_when: - 你需要精确到字段级别的配置语义或默认值 - 你正在验证渠道、模型、Gateway 网关或工具配置块 -summary: Gateway 网关 配置参考，涵盖 OpenClaw 核心键名、默认值，以及指向专门子系统参考的链接 +summary: 面向 OpenClaw 核心键、默认值以及专用子系统参考链接的 Gateway 网关配置参考 title: 配置参考 x-i18n: - generated_at: "2026-04-23T18:44:56Z" + generated_at: "2026-04-23T19:24:43Z" model: gpt-5.4 provider: openai - source_hash: 87b651be76f9a40969f42f2e6a7ca1b47135877dcb00a6165e1ab0a0feb977fe + source_hash: 2ed93c1439fd26f548a48b2813922bdd7b2344551376eefd7cdde616327b7ca8 source_path: gateway/configuration-reference.md workflow: 15 --- # 配置参考 -`~/.openclaw/openclaw.json` 的核心配置参考。若需面向任务的概览，请参阅 [配置](/zh-CN/gateway/configuration)。 +`~/.openclaw/openclaw.json` 的核心配置参考。若要查看面向任务的概览，请参见 [配置](/zh-CN/gateway/configuration)。 -本页介绍 OpenClaw 的主要配置表面，并在某个子系统有更深入的独立参考时提供对应链接。它**不会**尝试在单页内嵌每个渠道/插件自有的命令目录，或每个深层 memory/QMD 细粒度参数。 +本页涵盖 OpenClaw 的主要配置表面，并在某个子系统拥有自己更深入的参考文档时提供相应链接。它**不会**尝试在单个页面中内联列出每个由渠道 / 插件拥有的命令目录，或每个深层内存 / QMD 调节项。 -代码中的真实依据： +代码事实来源： -- `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置/插件/渠道元数据 -- `config.schema.lookup` 会返回单个按路径限定的 schema 节点，供深入查看工具使用 -- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面验证配置文档基线哈希 +- `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置 / 插件 / 渠道元数据 +- `config.schema.lookup` 会返回一个按路径作用域限定的 schema 节点，供钻取工具使用 +- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面，验证配置文档基线哈希 -专门的深度参考： +专用的深度参考文档： -- [Memory 配置参考](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 Dreaming 配置 +- [内存配置参考](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 Dreaming 配置 - [斜杠命令](/zh-CN/tools/slash-commands)，适用于当前内置 + 内置插件命令目录 -- 对应渠道/插件页面，适用于渠道特定的命令表面 +- 对应渠道 / 插件页面，适用于特定渠道的命令表面 -配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的——省略时，OpenClaw 会使用安全的默认值。 +配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段均为可选 —— OpenClaw 在省略时会使用安全默认值。 --- ## 渠道 -只要某个渠道的配置段存在，该渠道就会自动启动（除非设置了 `enabled: false`）。 +当每个渠道的配置节存在时，它都会自动启动（除非设置了 `enabled: false`）。 ### 私信和群组访问 所有渠道都支持私信策略和群组策略： -| 私信策略 | 行为 | -| ------------------- | ---- | -| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 | -| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对允许存储中的发送者） | -| `open` | 允许所有传入私信（要求 `allowFrom: ["*"]`） | -| `disabled` | 忽略所有传入私信 | +| 私信策略 | 行为 | +| ------------------- | ------------------------------------------------ | +| `pairing`（默认） | 未知发送者会收到一次性配对码；所有者必须批准 | +| `allowlist` | 仅允许 `allowFrom` 中的发送者（或已配对允许存储） | +| `open` | 允许所有传入私信（要求 `allowFrom: ["*"]`） | +| `disabled` | 忽略所有传入私信 | -| 群组策略 | 行为 | -| --------------------- | ---- | -| `allowlist`（默认） | 仅允许匹配已配置允许列表的群组 | -| `open` | 绕过群组允许列表（仍会应用提及门控） | -| `disabled` | 阻止所有群组/房间消息 | +| 群组策略 | 行为 | +| --------------------- | ------------------------------------------------ | +| `allowlist`（默认） | 仅允许与已配置允许列表匹配的群组 | +| `open` | 绕过群组允许列表（但仍会应用提及门控） | +| `disabled` | 阻止所有群组 / 房间消息 | -`channels.defaults.groupPolicy` 用于在某个提供商的 `groupPolicy` 未设置时指定默认值。 -配对码会在 1 小时后过期。待处理的私信配对请求每个渠道最多 **3 个**。 -如果某个提供商配置块完全缺失（即不存在 `channels.`），运行时群组策略会回退为 `allowlist`（失败即关闭），并在启动时发出警告。 +`channels.defaults.groupPolicy` 会在某个提供商的 `groupPolicy` 未设置时作为默认值。 +配对码会在 1 小时后过期。待处理的私信配对请求每个渠道上限为 **3 个**。 +如果某个提供商配置块完全缺失（`channels.` 不存在），运行时群组策略会回退为 `allowlist`（默认拒绝），并在启动时发出警告。 ### 渠道模型覆盖 -使用 `channels.modelByChannel` 可将特定渠道 ID 固定到某个模型。值接受 `provider/model` 或已配置的模型别名。当某个会话尚未有模型覆盖时（例如通过 `/model` 设置），将应用该渠道映射。 +使用 `channels.modelByChannel` 可将特定渠道 ID 固定到某个模型。值支持 `provider/model` 或已配置的模型别名。当会话尚未具有模型覆盖时（例如通过 `/model` 设置），才会应用该渠道映射。 ```json5 { @@ -85,9 +85,9 @@ x-i18n: } ``` -### 渠道默认值和心跳 +### 渠道默认值与心跳 -使用 `channels.defaults` 为各提供商设置共享的群组策略和心跳行为： +使用 `channels.defaults` 为各提供商共享群组策略和心跳行为： ```json5 { @@ -105,15 +105,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`：当提供商级别的 `groupPolicy` 未设置时使用的回退群组策略。 -- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用/线程/历史上下文）、`allowlist`（仅包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用/回复上下文）。按渠道覆盖：`channels..contextVisibility`。 +- `channels.defaults.groupPolicy`：当提供商级别的 `groupPolicy` 未设置时的回退群组策略。 +- `channels.defaults.contextVisibility`：所有渠道的默认补充上下文可见性模式。取值：`all`（默认，包含所有引用 / 线程 / 历史上下文）、`allowlist`（只包含来自允许列表发送者的上下文）、`allowlist_quote`（与 allowlist 相同，但保留显式引用 / 回复上下文）。每渠道覆盖：`channels..contextVisibility`。 - `channels.defaults.heartbeat.showOk`：在心跳输出中包含健康渠道状态。 -- `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级/错误状态。 +- `channels.defaults.heartbeat.showAlerts`：在心跳输出中包含降级 / 错误状态。 - `channels.defaults.heartbeat.useIndicator`：以紧凑的指示器样式渲染心跳输出。 ### WhatsApp -WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在已关联的会话时，它会自动启动。 +WhatsApp 通过 Gateway 网关的 Web 渠道（Baileys Web）运行。当存在已链接会话时会自动启动。 ```json5 { @@ -124,7 +124,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // blue ticks (false in self-chat mode) + sendReadReceipts: true, // 蓝色对勾（在自聊模式下为 false） groups: { "*": { requireMention: true }, }, @@ -164,10 +164,10 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 } ``` -- 出站命令默认使用账户 `default`；如果不存在，则使用第一个已配置的账户 ID（按排序顺序）。 -- 可选的 `channels.whatsapp.defaultAccount` 可在其匹配某个已配置账户 ID 时，覆盖该回退默认账户选择。 -- 旧版单账户 Baileys 凭证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 -- 按账户覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 +- 出站命令默认使用账户 `default`（如果存在）；否则使用第一个已配置的账户 ID（按排序结果）。 +- 可选的 `channels.whatsapp.defaultAccount` 会在其匹配某个已配置账户 ID 时，覆盖该回退默认账户选择。 +- 旧版单账户 Baileys 认证目录会由 `openclaw doctor` 迁移到 `whatsapp/default`。 +- 每账户覆盖：`channels.whatsapp.accounts..sendReadReceipts`、`channels.whatsapp.accounts..dmPolicy`、`channels.whatsapp.accounts..allowFrom`。 @@ -202,7 +202,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits) + streaming: "partial", // off | partial | block | progress (默认：off；请显式启用，以避免预览编辑速率限制) actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -225,12 +225,12 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 } ``` -- Bot token：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅允许常规文件；拒绝符号链接），默认账户还可回退为 `TELEGRAM_BOT_TOKEN`。 -- 可选的 `channels.telegram.defaultAccount` 可在其匹配某个已配置账户 ID 时覆盖默认账户选择。 -- 在多账户设置中（2 个及以上账户 ID），请设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；若该项缺失或无效，`openclaw doctor` 会发出警告。 +- 机器人令牌：`channels.telegram.botToken` 或 `channels.telegram.tokenFile`（仅限常规文件；拒绝符号链接），默认账户还可回退为 `TELEGRAM_BOT_TOKEN`。 +- 可选的 `channels.telegram.defaultAccount` 会在其匹配某个已配置账户 ID 时，覆盖默认账户选择。 +- 在多账户配置（2 个及以上账户 ID）中，请设置显式默认值（`channels.telegram.defaultAccount` 或 `channels.telegram.accounts.default`）以避免回退路由；若缺失或无效，`openclaw doctor` 会发出警告。 - `configWrites: false` 会阻止由 Telegram 发起的配置写入（超级群组 ID 迁移、`/config set|unset`）。 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目用于配置论坛话题的持久 ACP 绑定（在 `match.peer.id` 中使用规范形式 `chatId:topic:topicId`）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中统一说明。 -- Telegram 流式预览使用 `sendMessage` + `editMessageText`（在私聊和群聊中均可使用）。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目可为论坛话题配置持久 ACP 绑定（在 `match.peer.id` 中使用规范的 `chatId:topic:topicId`）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享说明。 +- Telegram 流式预览使用 `sendMessage` + `editMessageText`（可用于私聊和群聊）。 - 重试策略：参见 [重试策略](/zh-CN/concepts/retry)。 ### Discord @@ -286,7 +286,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress (progress maps to partial on Discord) + streaming: "off", // off | partial | block | progress（在 Discord 上，progress 会映射为 partial） maxLinesPerMessage: 17, ui: { components: { @@ -297,7 +297,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true }) + spawnSubagentSessions: false, // 对 `sessions_spawn({ thread: true })` 的显式启用 }, voice: { enabled: true, @@ -333,34 +333,34 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 } ``` -- Token：`channels.discord.token`，默认账户还可回退为 `DISCORD_BOT_TOKEN`。 -- 直接出站调用如果显式提供了 Discord `token`，该次调用会使用该 token；账户重试/策略设置仍来自活动运行时快照中选定的账户。 -- 可选的 `channels.discord.defaultAccount` 可在其匹配某个已配置账户 ID 时覆盖默认账户选择。 -- 使用 `user:`（私信）或 `channel:`（guild 渠道）作为投递目标；裸数字 ID 会被拒绝。 -- Guild slug 使用小写并将空格替换为 `-`；渠道键使用 slug 化后的名称（不含 `#`）。优先使用 guild ID。 -- 默认会忽略机器人发送的消息。`allowBots: true` 可启用它们；使用 `allowBots: "mentions"` 则只接受提及该机器人的机器人消息（机器人自己的消息仍会被过滤）。 +- 令牌：`channels.discord.token`，默认账户还可回退为 `DISCORD_BOT_TOKEN`。 +- 直接出站调用若显式提供了 Discord `token`，该调用会使用该令牌；账户重试 / 策略设置仍来自活动运行时快照中选定的账户。 +- 可选的 `channels.discord.defaultAccount` 会在其匹配某个已配置账户 ID 时，覆盖默认账户选择。 +- 传递目标请使用 `user:`（私信）或 `channel:`（服务器渠道）；裸数字 ID 会被拒绝。 +- 服务器 slug 使用小写，并将空格替换为 `-`；渠道键使用 slug 化后的名称（不带 `#`）。优先使用服务器 ID。 +- 默认会忽略由机器人撰写的消息。`allowBots: true` 会启用它们；使用 `allowBots: "mentions"` 则只接受提及该机器人的机器人消息（机器人自己的消息仍会被过滤）。 - `channels.discord.guilds..ignoreOtherMentions`（以及渠道级覆盖）会丢弃提及了其他用户或角色但未提及机器人的消息（不包括 @everyone/@here）。 -- `maxLinesPerMessage`（默认 17）会拆分行数过多的消息，即使其长度未超过 2000 个字符。 +- `maxLinesPerMessage`（默认 17）会拆分过高的消息，即使其未超过 2000 个字符。 - `channels.discord.threadBindings` 控制 Discord 线程绑定路由： - - `enabled`：Discord 对线程绑定会话功能的覆盖（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定投递/路由） - - `idleHours`：Discord 对按不活动时间自动取消焦点的小时数覆盖（`0` 表示禁用） - - `maxAgeHours`：Discord 对硬性最大存续时间的小时数覆盖（`0` 表示禁用） - - `spawnSubagentSessions`：为 `sessions_spawn({ thread: true })` 自动创建/绑定线程启用的显式开关 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目用于为渠道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用渠道/线程 ID）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中统一说明。 -- `channels.discord.ui.components.accentColor` 用于设置 Discord components v2 容器的强调色。 + - `enabled`：线程绑定会话功能的 Discord 覆盖（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`，以及绑定传递 / 路由） + - `idleHours`：按小时计算的不活跃自动取消焦点的 Discord 覆盖（`0` 表示禁用） + - `maxAgeHours`：按小时计算的硬性最大存续时间的 Discord 覆盖（`0` 表示禁用） + - `spawnSubagentSessions`：用于 `sessions_spawn({ thread: true })` 自动创建 / 绑定线程的显式启用开关 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目可为渠道和线程配置持久 ACP 绑定（在 `match.peer.id` 中使用 channel/thread id）。字段语义在 [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings) 中共享说明。 +- `channels.discord.ui.components.accentColor` 为 Discord components v2 容器设置强调色。 - `channels.discord.voice` 启用 Discord 语音频道对话，以及可选的自动加入 + TTS 覆盖。 -- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会透传给 `@discordjs/voice` 的 DAVE 选项（默认分别为 `true` 和 `24`）。 -- 此外，OpenClaw 还会在重复解密失败后通过离开/重新加入语音会话来尝试恢复语音接收。 -- `channels.discord.streaming` 是规范的流式模式键。旧版 `streamMode` 和布尔值 `streaming` 会自动迁移。 -- `channels.discord.autoPresence` 会将运行时可用性映射到机器人在线状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖。 -- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称/tag 匹配（紧急兼容模式）。 -- `channels.discord.execApprovals`：Discord 原生 exec 审批投递与审批人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，将启用 exec 审批。 +- `channels.discord.voice.daveEncryption` 和 `channels.discord.voice.decryptionFailureTolerance` 会直通传递给 `@discordjs/voice` 的 DAVE 选项（默认分别为 `true` 和 `24`）。 +- OpenClaw 还会在重复解密失败后，通过离开 / 重新加入语音会话来尝试恢复语音接收。 +- `channels.discord.streaming` 是规范的流式模式键。旧版 `streamMode` 和布尔型 `streaming` 值会被自动迁移。 +- `channels.discord.autoPresence` 会将运行时可用性映射为机器人在线状态（healthy => online，degraded => idle，exhausted => dnd），并允许可选的状态文本覆盖。 +- `channels.discord.dangerouslyAllowNameMatching` 会重新启用可变名称 / 标签匹配（紧急兼容模式）。 +- `channels.discord.execApprovals`：Discord 原生 exec 审批传递与审批人授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，exec 审批会激活。 - `approvers`：允许批准 exec 请求的 Discord 用户 ID。省略时回退到 `commands.ownerAllowFrom`。 - - `agentFilter`：可选的智能体 ID 允许列表。省略时转发所有智能体的审批请求。 - - `sessionFilter`：可选的会话键模式（子串或正则）。 - - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批人的私信，`"channel"` 发送到发起渠道，`"both"` 同时发送到两者。当 target 包含 `"channel"` 时，按钮仅对已解析出的审批人可用。 - - `cleanupAfterResolve`：设为 `true` 时，在审批、拒绝或超时后删除审批私信。 + - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批请求。 + - `sessionFilter`：可选的会话键模式（子串或正则表达式）。 + - `target`：发送审批提示的位置。`"dm"`（默认）发送到审批人的私信，`"channel"` 发送到发起渠道，`"both"` 同时发送到两者。当目标包含 `"channel"` 时，按钮仅可由已解析出的审批人使用。 + - `cleanupAfterResolve`：为 `true` 时，在批准、拒绝或超时后删除审批私信。 **反应通知模式：** `off`（无）、`own`（机器人的消息，默认）、`all`（所有消息）、`allowlist`（来自 `guilds..users` 的所有消息）。 @@ -393,11 +393,11 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 } ``` -- 服务账户 JSON：可内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 +- 服务账户 JSON：支持内联（`serviceAccount`）或基于文件（`serviceAccountFile`）。 - 也支持服务账户 SecretRef（`serviceAccountRef`）。 - 环境变量回退：`GOOGLE_CHAT_SERVICE_ACCOUNT` 或 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`。 -- 使用 `spaces/` 或 `users/` 作为投递目标。 -- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体匹配（紧急兼容模式）。 +- 传递目标请使用 `spaces/` 或 `users/`。 +- `channels.googlechat.dangerouslyAllowNameMatching` 会重新启用可变邮箱主体匹配（紧急兼容模式）。 ### Slack @@ -449,7 +449,7 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 chunkMode: "length", streaming: { mode: "partial", // off | partial | block | progress - nativeTransport: true, // use Slack native streaming API when mode=partial + nativeTransport: true, // 当 mode=partial 时使用 Slack 原生流式传输 API }, mediaMaxMb: 20, execApprovals: { @@ -464,34 +464,38 @@ WhatsApp 通过 Gateway 网关的 web 渠道（Baileys Web）运行。当存在 } ``` -- **Socket mode** 需要同时提供 `botToken` 和 `appToken`（默认账户的环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 -- **HTTP mode** 需要 `botToken` 加上 `signingSecret`（位于根级别或按账户设置）。 -- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文字符串或 SecretRef 对象。 -- Slack 账户快照会暴露按凭证区分的来源/状态字段，例如 `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP mode 下的 `signingSecretStatus`。`configured_unavailable` 表示该账户通过 SecretRef 进行配置，但当前命令/运行时路径无法解析该 secret 值。 +- **Socket 模式** 需要同时提供 `botToken` 和 `appToken`（默认账户的环境变量回退为 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`）。 +- **HTTP 模式** 需要 `botToken` 加 `signingSecret`（在根级或每账户级别）。 +- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文 + 字符串或 SecretRef 对象。 +- Slack 账户快照会暴露按凭证划分的来源 / 状态字段，例如 + `botTokenSource`、`botTokenStatus`、`appTokenStatus`，以及在 HTTP 模式下的 + `signingSecretStatus`。`configured_unavailable` 表示该账户通过 SecretRef + 进行了配置，但当前命令 / 运行时路径无法解析出该 secret 值。 - `configWrites: false` 会阻止由 Slack 发起的配置写入。 -- 可选的 `channels.slack.defaultAccount` 可在其匹配某个已配置账户 ID 时覆盖默认账户选择。 -- `channels.slack.streaming.mode` 是规范的 Slack 流式模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输。旧版 `streamMode`、布尔值 `streaming` 和 `nativeStreaming` 会自动迁移。 -- 使用 `user:`（私信）或 `channel:` 作为投递目标。 +- 可选的 `channels.slack.defaultAccount` 会在其匹配某个已配置账户 ID 时，覆盖默认账户选择。 +- `channels.slack.streaming.mode` 是规范的 Slack 流式模式键。`channels.slack.streaming.nativeTransport` 控制 Slack 的原生流式传输机制。旧版 `streamMode`、布尔型 `streaming` 和 `nativeStreaming` 值会被自动迁移。 +- 传递目标请使用 `user:`（私信）或 `channel:`。 **反应通知模式：** `off`、`own`（默认）、`all`、`allowlist`（来自 `reactionAllowlist`）。 -**线程会话隔离：** `thread.historyScope` 可设为按线程（默认）或按渠道共享。`thread.inheritParent` 会将父渠道转录复制到新线程中。 +**线程会话隔离：** `thread.historyScope` 可设为按线程隔离（默认）或在整个渠道内共享。`thread.inheritParent` 会将父渠道的对话记录复制到新线程中。 -- Slack 原生流式传输加上 Slack 助手风格的 “is typing...” 线程状态需要一个回复线程目标。顶层私信默认保持非线程状态，因此会使用 `typingReaction` 或常规投递，而不是线程样式预览。 -- `typingReaction` 会在回复运行期间向传入的 Slack 消息添加一个临时反应，并在完成后移除。请使用 Slack emoji 简码，例如 `"hourglass_flowing_sand"`。 -- `channels.slack.execApprovals`：Slack 原生 exec 审批投递与审批人授权。与 Discord 使用相同 schema：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 +- Slack 原生流式传输加上 Slack 助手风格的“正在输入...”线程状态需要一个回复线程目标。顶层私信默认保持非线程，因此它们会使用 `typingReaction` 或普通传递，而不是线程式预览。 +- `typingReaction` 会在回复运行期间为传入的 Slack 消息添加一个临时反应，并在完成后移除。请使用 Slack emoji 简码，例如 `"hourglass_flowing_sand"`。 +- `channels.slack.execApprovals`：Slack 原生 exec 审批传递与审批人授权。其 schema 与 Discord 相同：`enabled`（`true`/`false`/`"auto"`）、`approvers`（Slack 用户 ID）、`agentFilter`、`sessionFilter` 和 `target`（`"dm"`、`"channel"` 或 `"both"`）。 -| 操作组 | 默认值 | 说明 | -| ------------ | ------- | ---------------------- | -| reactions | 已启用 | 添加反应 + 列出反应 | -| messages | 已启用 | 读取/发送/编辑/删除 | -| pins | 已启用 | 置顶/取消置顶/列出 | -| memberInfo | 已启用 | 成员信息 | -| emojiList | 已启用 | 自定义 emoji 列表 | +| 操作组 | 默认 | 说明 | +| ---------- | ------ | -------------------- | +| reactions | 已启用 | 添加反应 + 列出反应 | +| messages | 已启用 | 读取 / 发送 / 编辑 / 删除 | +| pins | 已启用 | 固定 / 取消固定 / 列出 | +| memberInfo | 已启用 | 成员信息 | +| emojiList | 已启用 | 自定义 emoji 列表 | ### Mattermost -Mattermost 作为插件发布：`openclaw plugins install @openclaw/mattermost`。 +Mattermost 以插件形式提供：`openclaw plugins install @openclaw/mattermost`。 ```json5 { @@ -508,10 +512,10 @@ Mattermost 作为插件发布：`openclaw plugins install @openclaw/mattermost` "team-channel-id": { requireMention: false }, }, commands: { - native: true, // opt-in + native: true, // 显式启用 nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // Optional explicit URL for reverse-proxy/public deployments + // 面向反向代理 / 公网部署的可选显式 URL callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -521,19 +525,21 @@ Mattermost 作为插件发布：`openclaw plugins install @openclaw/mattermost` } ``` -聊天模式：`oncall`（在 @ 提及时响应，默认）、`onmessage`（每条消息都响应）、`onchar`（以触发前缀开头的消息）。 +聊天模式：`oncall`（在收到 @ 提及时响应，默认）、`onmessage`（每条消息都响应）、`onchar`（以触发前缀开头的消息）。 启用 Mattermost 原生命令时： - `commands.callbackPath` 必须是路径（例如 `/api/channels/mattermost/command`），不能是完整 URL。 -- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器能够访问。 -- 原生斜杠回调使用 Mattermost 在斜杠命令注册期间返回的每命令 token 进行身份验证。如果注册失败或没有激活任何命令，OpenClaw 会拒绝回调并返回 `Unauthorized: invalid command token.`。 -- 对于私有/tailnet/内部回调主机，Mattermost 可能要求 `ServiceSettings.AllowedUntrustedInternalConnections` 包含回调主机/域名。 - 请使用主机/域名值，而不是完整 URL。 +- `commands.callbackUrl` 必须解析到 OpenClaw Gateway 网关端点，并且 Mattermost 服务器可以访问到它。 +- 原生斜杠回调通过 Mattermost 在斜杠命令注册期间返回的每命令令牌进行认证。如果注册失败或没有激活任何命令，OpenClaw 会以 + `Unauthorized: invalid command token.` 拒绝回调。 +- 对于私有 / tailnet / 内部回调主机，Mattermost 可能要求 + `ServiceSettings.AllowedUntrustedInternalConnections` 包含该回调主机 / 域名。 + 请使用主机 / 域名值，而不是完整 URL。 - `channels.mattermost.configWrites`：允许或拒绝由 Mattermost 发起的配置写入。 -- `channels.mattermost.requireMention`：在渠道中回复前要求 `@mention`。 +- `channels.mattermost.requireMention`：在渠道中回复前要求有 `@mention`。 - `channels.mattermost.groups..requireMention`：按渠道覆盖提及门控（`"*"` 作为默认值）。 -- 可选的 `channels.mattermost.defaultAccount` 可在其匹配某个已配置账户 ID 时覆盖默认账户选择。 +- 可选的 `channels.mattermost.defaultAccount` 会在其匹配某个已配置账户 ID 时，覆盖默认账户选择。 ### Signal @@ -542,7 +548,7 @@ Mattermost 作为插件发布：`openclaw plugins install @openclaw/mattermost` channels: { signal: { enabled: true, - account: "+15555550123", // optional account binding + account: "+15555550123", // 可选的账户绑定 dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -558,11 +564,11 @@ Mattermost 作为插件发布：`openclaw plugins install @openclaw/mattermost` - `channels.signal.account`：将渠道启动固定到特定的 Signal 账户身份。 - `channels.signal.configWrites`：允许或拒绝由 Signal 发起的配置写入。 -- 可选的 `channels.signal.defaultAccount` 可在其匹配某个已配置账户 ID 时覆盖默认账户选择。 +- 可选的 `channels.signal.defaultAccount` 会在其匹配某个已配置账户 ID 时，覆盖默认账户选择。 ### BlueBubbles -BlueBubbles 是推荐的 iMessage 方案（基于插件，在 `channels.bluebubbles` 下配置）。 +BlueBubbles 是推荐的 iMessage 路径（由插件支持，在 `channels.bluebubbles` 下配置）。 ```json5 { @@ -570,17 +576,17 @@ BlueBubbles 是推荐的 iMessage 方案（基于插件，在 `channels.bluebubb bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl, password, webhookPath, group controls, and advanced actions: - // see /channels/bluebubbles + // serverUrl、password、webhookPath、群组控制和高级操作： + // 参见 /channels/bluebubbles }, }, } ``` - 此处涵盖的核心键路径：`channels.bluebubbles`、`channels.bluebubbles.dmPolicy`。 -- 可选的 `channels.bluebubbles.defaultAccount` 可在其匹配某个已配置账户 ID 时覆盖默认账户选择。 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目可以将 BlueBubbles 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或目标字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 -- 完整的 BlueBubbles 渠道配置记录于 [BlueBubbles](/zh-CN/channels/bluebubbles)。 +- 可选的 `channels.bluebubbles.defaultAccount` 会在其匹配某个已配置账户 ID 时，覆盖默认账户选择。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目可以将 BlueBubbles 会话绑定到持久 ACP 会话。在 `match.peer.id` 中使用 BlueBubbles handle 或 target 字符串（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- 完整的 BlueBubbles 渠道配置记录在 [BlueBubbles](/zh-CN/channels/bluebubbles) 中。 ### iMessage @@ -608,17 +614,17 @@ OpenClaw 会生成 `imsg rpc`（通过 stdio 的 JSON-RPC）。不需要守护 } ``` -- 可选的 `channels.imessage.defaultAccount` 可在其匹配某个已配置账户 ID 时覆盖默认账户选择。 +- 可选的 `channels.imessage.defaultAccount` 会在其匹配某个已配置账户 ID 时，覆盖默认账户选择。 -- 需要对 Messages 数据库授予 Full Disk Access。 +- 需要对 Messages DB 拥有完全磁盘访问权限。 - 优先使用 `chat_id:` 目标。使用 `imsg chats --limit 20` 列出聊天。 -- `cliPath` 可以指向 SSH 包装器；设置 `remoteHost`（`host` 或 `user@host`）以通过 SCP 获取附件。 +- `cliPath` 可以指向 SSH 包装脚本；设置 `remoteHost`（`host` 或 `user@host`）以通过 SCP 获取附件。 - `attachmentRoots` 和 `remoteAttachmentRoots` 会限制传入附件路径（默认：`/Users/*/Library/Messages/Attachments`）。 -- SCP 使用严格主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 +- SCP 使用严格的主机密钥检查，因此请确保中继主机密钥已存在于 `~/.ssh/known_hosts` 中。 - `channels.imessage.configWrites`：允许或拒绝由 iMessage 发起的配置写入。 -- 顶层 `bindings[]` 中 `type: "acp"` 的条目可以将 iMessage 对话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 +- 顶层 `bindings[]` 中 `type: "acp"` 的条目可以将 iMessage 会话绑定到持久 ACP 会话。在 `match.peer.id` 中使用规范化的 handle 或显式聊天目标（`chat_id:*`、`chat_guid:*`、`chat_identifier:*`）。共享字段语义： [ACP Agents](/zh-CN/tools/acp-agents#channel-specific-settings)。 - + ```bash #!/usr/bin/env bash @@ -629,7 +635,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix 基于插件，并在 `channels.matrix` 下配置。 +Matrix 由插件支持，并在 `channels.matrix` 下配置。 ```json5 { @@ -659,25 +665,25 @@ Matrix 基于插件，并在 `channels.matrix` 下配置。 } ``` -- Token 身份验证使用 `accessToken`；密码身份验证使用 `userId` + `password`。 -- `channels.matrix.proxy` 会通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。命名账户可以用 `channels.matrix.accounts..proxy` 覆盖它。 -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有/内部 homeserver。`proxy` 与此网络显式启用项是彼此独立的控制项。 -- `channels.matrix.defaultAccount` 用于在多账户设置中选择首选账户。 +- 令牌认证使用 `accessToken`；密码认证使用 `userId` + `password`。 +- `channels.matrix.proxy` 会通过显式 HTTP(S) 代理转发 Matrix HTTP 流量。具名账户可以通过 `channels.matrix.accounts..proxy` 覆盖它。 +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` 允许私有 / 内部 homeserver。`proxy` 与该网络显式启用是彼此独立的控制项。 +- `channels.matrix.defaultAccount` 会在多账户配置中选择首选账户。 - `channels.matrix.autoJoin` 默认为 `off`，因此受邀房间和新的私信式邀请会被忽略，直到你设置 `autoJoin: "allowlist"` 并配合 `autoJoinAllowlist`，或设置 `autoJoin: "always"`。 -- `channels.matrix.execApprovals`：Matrix 原生 exec 审批投递与审批人授权。 - - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，将启用 exec 审批。 +- `channels.matrix.execApprovals`：Matrix 原生 exec 审批传递与审批人授权。 + - `enabled`：`true`、`false` 或 `"auto"`（默认）。在自动模式下，当可以从 `approvers` 或 `commands.ownerAllowFrom` 解析出审批人时，exec 审批会激活。 - `approvers`：允许批准 exec 请求的 Matrix 用户 ID（例如 `@owner:example.org`）。 - - `agentFilter`：可选的智能体 ID 允许列表。省略时转发所有智能体的审批请求。 - - `sessionFilter`：可选的会话键模式（子串或正则）。 + - `agentFilter`：可选的智能体 ID 允许列表。省略则转发所有智能体的审批请求。 + - `sessionFilter`：可选的会话键模式（子串或正则表达式）。 - `target`：发送审批提示的位置。`"dm"`（默认）、`"channel"`（发起房间）或 `"both"`。 - - 按账户覆盖：`channels.matrix.accounts..execApprovals`。 -- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何归组为会话：`per-user`（默认）按路由对端共享，`per-room` 则隔离每个私信房间。 + - 每账户覆盖：`channels.matrix.accounts..execApprovals`。 +- `channels.matrix.dm.sessionScope` 控制 Matrix 私信如何归入会话：`per-user`（默认）按路由对端共享，而 `per-room` 会隔离每个私信房间。 - Matrix 状态探测和实时目录查找使用与运行时流量相同的代理策略。 -- 完整的 Matrix 配置、目标规则和设置示例记录于 [Matrix](/zh-CN/channels/matrix)。 +- 完整的 Matrix 配置、目标规则和设置示例记录在 [Matrix](/zh-CN/channels/matrix) 中。 ### Microsoft Teams -Microsoft Teams 基于插件，并在 `channels.msteams` 下配置。 +Microsoft Teams 由插件支持，并在 `channels.msteams` 下配置。 ```json5 { @@ -685,19 +691,19 @@ Microsoft Teams 基于插件，并在 `channels.msteams` 下配置。 msteams: { enabled: true, configWrites: true, - // appId, appPassword, tenantId, webhook, team/channel policies: - // see /channels/msteams + // appId、appPassword、tenantId、webhook、团队 / 渠道策略： + // 参见 /channels/msteams }, }, } ``` - 此处涵盖的核心键路径：`channels.msteams`、`channels.msteams.configWrites`。 -- 完整的 Teams 配置（凭证、webhook、私信/群组策略、按团队/按渠道覆盖）记录于 [Microsoft Teams](/zh-CN/channels/msteams)。 +- 完整的 Teams 配置（凭证、webhook、私信 / 群组策略、按团队 / 按渠道覆盖）记录在 [Microsoft Teams](/zh-CN/channels/msteams) 中。 ### IRC -IRC 基于插件，并在 `channels.irc` 下配置。 +IRC 由插件支持，并在 `channels.irc` 下配置。 ```json5 { @@ -719,12 +725,12 @@ IRC 基于插件，并在 `channels.irc` 下配置。 ``` - 此处涵盖的核心键路径：`channels.irc`、`channels.irc.dmPolicy`、`channels.irc.configWrites`、`channels.irc.nickserv.*`。 -- 可选的 `channels.irc.defaultAccount` 可在其匹配某个已配置账户 ID 时覆盖默认账户选择。 -- 完整的 IRC 渠道配置（host/port/TLS/channels/allowlists/提及门控）记录于 [IRC](/zh-CN/channels/irc)。 +- 可选的 `channels.irc.defaultAccount` 会在其匹配某个已配置账户 ID 时，覆盖默认账户选择。 +- 完整的 IRC 渠道配置（host/port/TLS/channels/allowlists/mention gating）记录在 [IRC](/zh-CN/channels/irc) 中。 ### 多账户（所有渠道） -为每个渠道运行多个账户（每个账户都有自己的 `accountId`）： +在每个渠道中运行多个账户（每个账户都有自己的 `accountId`）： ```json5 { @@ -746,17 +752,17 @@ IRC 基于插件，并在 `channels.irc` 下配置。 ``` - 省略 `accountId` 时使用 `default`（CLI + 路由）。 -- 环境变量 token 仅适用于 **default** 账户。 -- 基础渠道设置适用于所有账户，除非按账户覆盖。 -- 使用 `bindings[].match.accountId` 可将每个账户路由到不同的智能体。 -- 如果你通过 `openclaw channels add`（或渠道新手引导）添加非默认账户，而当前仍使用单账户顶层渠道配置，OpenClaw 会先将按账户范围的顶层单账户值提升到该渠道的账户映射中，以便原始账户继续工作。大多数渠道会将它们移动到 `channels..accounts.default`；Matrix 则可以保留现有匹配的命名/默认目标。 -- 现有的仅渠道级绑定（无 `accountId`）会继续匹配默认账户；按账户范围的绑定仍然是可选的。 -- `openclaw doctor --fix` 也会通过将按账户范围的顶层单账户值移动到为该渠道选定的提升后账户中来修复混合形态。大多数渠道使用 `accounts.default`；Matrix 则可以保留现有匹配的命名/默认目标。 +- 环境变量令牌仅适用于 **default** 账户。 +- 基础渠道设置适用于所有账户，除非在每账户级别进行覆盖。 +- 使用 `bindings[].match.accountId` 将每个账户路由到不同的智能体。 +- 如果你通过 `openclaw channels add`（或渠道新手引导）添加一个非默认账户，而当前仍使用单账户顶层渠道配置，OpenClaw 会先将账户作用域的顶层单账户值提升到渠道账户映射中，这样原始账户仍可继续工作。大多数渠道会将这些值移动到 `channels..accounts.default`；Matrix 则可以改为保留现有的匹配具名 / 默认目标。 +- 现有仅渠道级绑定（没有 `accountId`）会继续匹配默认账户；账户作用域绑定仍然是可选的。 +- `openclaw doctor --fix` 也会通过将账户作用域的顶层单账户值移动到该渠道所选的提升后账户中来修复混合形态。大多数渠道使用 `accounts.default`；Matrix 则可以改为保留现有的匹配具名 / 默认目标。 -### 其他渠道插件 +### 其他插件渠道 -许多渠道插件配置为 `channels.`，并在各自专门的渠道页面中记录（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 -请参阅完整的渠道索引：[渠道](/zh-CN/channels)。 +许多插件渠道配置为 `channels.`，并记录在它们各自的专用渠道页面中（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。 +请参见完整渠道索引：[Channels](/zh-CN/channels)。 ### 群聊提及门控 @@ -766,7 +772,7 @@ IRC 基于插件，并在 `channels.irc` 下配置。 - **元数据提及**：平台原生 @ 提及。在 WhatsApp 自聊模式中会被忽略。 - **文本模式**：位于 `agents.list[].groupChat.mentionPatterns` 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。 -- 仅当可以检测提及时（原生提及或至少一个模式）才会执行提及门控。 +- 仅在能够检测提及的情况下（原生提及或至少一个模式）才会强制执行提及门控。 ```json5 { @@ -779,9 +785,9 @@ IRC 基于插件，并在 `channels.irc` 下配置。 } ``` -`messages.groupChat.historyLimit` 设置全局默认值。渠道可通过 `channels..historyLimit`（或按账户）覆盖。设为 `0` 可禁用。 +`messages.groupChat.historyLimit` 设置全局默认值。渠道可以通过 `channels..historyLimit`（或每账户级别）覆盖它。设为 `0` 可禁用。 -#### 私信历史限制 +#### 私信历史记录限制 ```json5 { @@ -796,13 +802,13 @@ IRC 基于插件，并在 `channels.irc` 下配置。 } ``` -解析顺序：按私信覆盖 → 提供商默认值 → 不限制（全部保留）。 +解析顺序：按私信覆盖 → 提供商默认值 → 不限制（保留全部）。 支持：`telegram`、`whatsapp`、`discord`、`slack`、`signal`、`imessage`、`msteams`。 #### 自聊模式 -将你自己的号码加入 `allowFrom` 以启用自聊模式（忽略原生 @ 提及，仅响应文本模式）： +将你自己的号码包含在 `allowFrom` 中，以启用自聊模式（忽略原生 @ 提及，仅响应文本模式）： ```json5 { @@ -823,21 +829,21 @@ IRC 基于插件，并在 `channels.irc` 下配置。 } ``` -### 命令（聊天命令处理） +### Commands（聊天命令处理） ```json5 { commands: { - native: "auto", // register native commands when supported - nativeSkills: "auto", // register native skill commands when supported - text: true, // parse /commands in chat messages - bash: false, // allow ! (alias: /bash) + native: "auto", // 在支持时注册原生命令 + nativeSkills: "auto", // 在支持时注册原生 Skills 命令 + text: true, // 解析聊天消息中的 /commands + bash: false, // 允许 !（别名：/bash） bashForegroundMs: 2000, - config: false, // allow /config - mcp: false, // allow /mcp - plugins: false, // allow /plugins - debug: false, // allow /debug - restart: true, // allow /restart + gateway restart tool + config: false, // 允许 /config + mcp: false, // 允许 /mcp + plugins: false, // 允许 /plugins + debug: false, // 允许 /debug + restart: true, // 允许 /restart + gateway restart 工具 ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -852,32 +858,32 @@ IRC 基于插件，并在 `channels.irc` 下配置。 -- 此块用于配置命令表面。关于当前内置 + 内置插件命令目录，请参阅 [斜杠命令](/zh-CN/tools/slash-commands)。 -- 本页是**配置键参考**，不是完整命令目录。像 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、device-pair `/pair`、memory `/dreaming`、phone-control `/phone` 和 Talk `/voice` 这类由渠道/插件拥有的命令，记录于它们各自的渠道/插件页面以及 [斜杠命令](/zh-CN/tools/slash-commands)。 -- 文本命令必须是以前导 `/` 开头的**独立**消息。 -- `native: "auto"` 会为 Discord/Telegram 打开原生命令，对 Slack 保持关闭。 -- `nativeSkills: "auto"` 会为 Discord/Telegram 打开原生 Skills 命令，对 Slack 保持关闭。 +- 此块用于配置命令表面。当前内置 + 内置插件命令目录请参见 [斜杠命令](/zh-CN/tools/slash-commands)。 +- 本页是**配置键参考**，不是完整命令目录。由渠道 / 插件拥有的命令，例如 QQ Bot `/bot-ping` `/bot-help` `/bot-logs`、LINE `/card`、设备配对 `/pair`、内存 `/dreaming`、手机控制 `/phone` 和 Talk `/voice`，记录在对应的渠道 / 插件页面以及 [斜杠命令](/zh-CN/tools/slash-commands) 中。 +- 文本命令必须是带有前导 `/` 的**独立**消息。 +- `native: "auto"` 会为 Discord / Telegram 打开原生命令，对 Slack 则保持关闭。 +- `nativeSkills: "auto"` 会为 Discord / Telegram 打开原生 Skills 命令，对 Slack 则保持关闭。 - 按渠道覆盖：`channels.discord.commands.native`（布尔值或 `"auto"`）。`false` 会清除先前已注册的命令。 - 使用 `channels..commands.nativeSkills` 按渠道覆盖原生 Skills 命令注册。 - `channels.telegram.customCommands` 会添加额外的 Telegram 机器人菜单项。 -- `bash: true` 会为主机 shell 启用 `! `。要求 `tools.elevated.enabled` 已启用，且发送者位于 `tools.elevated.allowFrom.` 中。 -- `config: true` 会启用 `/config`（读取/写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化的 `/config set|unset` 写入还要求 `operator.admin`；只读的 `/config show` 对普通写入作用域的 operator 客户端仍然可用。 +- `bash: true` 会为主机 shell 启用 `! `。要求 `tools.elevated.enabled` 已开启，且发送者在 `tools.elevated.allowFrom.` 中。 +- `config: true` 会启用 `/config`（读取 / 写入 `openclaw.json`）。对于 Gateway 网关 `chat.send` 客户端，持久化的 `/config set|unset` 写入还要求 `operator.admin`；只读的 `/config show` 对普通写作用域 operator 客户端仍然可用。 - `mcp: true` 会为 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置启用 `/mcp`。 -- `plugins: true` 会启用 `/plugins`，用于插件发现、安装和启用/禁用控制。 -- `channels..configWrites` 按渠道控制配置变更（默认：true）。 +- `plugins: true` 会为插件发现、安装以及启用 / 禁用控制启用 `/plugins`。 +- `channels..configWrites` 用于按渠道控制配置变更（默认：true）。 - 对于多账户渠道，`channels..accounts..configWrites` 也会控制以该账户为目标的写入（例如 `/allowlist --config --account ` 或 `/config set channels..accounts....`）。 -- `restart: false` 会禁用 `/restart` 和 Gateway 网关重启动作工具。默认值：`true`。 -- `ownerAllowFrom` 是用于仅限 owner 命令/工具的显式 owner 允许列表。它与 `allowFrom` 分开。 -- `ownerDisplay: "hash"` 会在系统提示中对 owner ID 进行哈希。设置 `ownerDisplaySecret` 可控制哈希行为。 -- `allowFrom` 按提供商生效。设置后，它将成为**唯一**的授权来源（渠道允许列表/配对和 `useAccessGroups` 都会被忽略）。 -- `useAccessGroups: false` 会在未设置 `allowFrom` 时允许命令绕过访问组策略。 +- `restart: false` 会禁用 `/restart` 和 gateway restart 工具操作。默认值：`true`。 +- `ownerAllowFrom` 是仅限 owner 的命令 / 工具所用的显式 owner 允许列表。它与 `allowFrom` 分开。 +- `ownerDisplay: "hash"` 会在系统提示中对 owner id 进行哈希。设置 `ownerDisplaySecret` 可控制哈希。 +- `allowFrom` 是按提供商配置的。设置后，它将成为**唯一**的授权来源（渠道允许列表 / 配对和 `useAccessGroups` 都会被忽略）。 +- `useAccessGroups: false` 会在未设置 `allowFrom` 时，让命令绕过访问组策略。 - 命令文档映射： - 内置 + 内置插件目录：[斜杠命令](/zh-CN/tools/slash-commands) - - 渠道特定命令表面：[渠道](/zh-CN/channels) + - 渠道特定命令表面：[Channels](/zh-CN/channels) - QQ Bot 命令：[QQ Bot](/zh-CN/channels/qqbot) - - 配对命令：[配对](/zh-CN/channels/pairing) + - 配对命令：[Pairing](/zh-CN/channels/pairing) - LINE 卡片命令：[LINE](/zh-CN/channels/line) - - memory Dreaming：[Dreaming](/zh-CN/concepts/dreaming) + - 内存 Dreaming：[Dreaming](/zh-CN/concepts/dreaming) @@ -897,7 +903,7 @@ IRC 基于插件，并在 `channels.irc` 下配置。 ### `agents.defaults.repoRoot` -可选的仓库根目录，会显示在系统提示的 Runtime 行中。如果未设置，OpenClaw 会从工作区开始向上遍历自动检测。 +可选的仓库根目录，会显示在系统提示的 Runtime 行中。若未设置，OpenClaw 会从工作区开始向上遍历并自动检测。 ```json5 { @@ -907,29 +913,32 @@ IRC 基于插件，并在 `channels.irc` 下配置。 ### `agents.defaults.skills` -为未设置 `agents.list[].skills` 的智能体提供可选的默认 Skills 允许列表。 +适用于未设置 +`agents.list[].skills` +的智能体的可选默认 Skills 允许列表。 ```json5 { agents: { defaults: { skills: ["github", "weather"] }, list: [ - { id: "writer" }, // inherits github, weather - { id: "docs", skills: ["docs-search"] }, // replaces defaults - { id: "locked-down", skills: [] }, // no skills + { id: "writer" }, // 继承 github、weather + { id: "docs", skills: ["docs-search"] }, // 替换默认值 + { id: "locked-down", skills: [] }, // 无 Skills ], }, } ``` -- 省略 `agents.defaults.skills` 可使 Skills 默认不受限制。 +- 省略 `agents.defaults.skills` 可使默认 Skills 不受限制。 - 省略 `agents.list[].skills` 可继承默认值。 -- 设置 `agents.list[].skills: []` 表示不使用任何 Skills。 -- 非空的 `agents.list[].skills` 列表是该智能体的最终集合；它不会与默认值合并。 +- 设置 `agents.list[].skills: []` 表示没有 Skills。 +- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合； + 它不会与默认值合并。 ### `agents.defaults.skipBootstrap` -禁用工作区 bootstrap 文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）的自动创建。 +禁用自动创建工作区 bootstrap 文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。 ```json5 { @@ -939,9 +948,9 @@ IRC 基于插件，并在 `channels.irc` 下配置。 ### `agents.defaults.contextInjection` -控制何时将工作区 bootstrap 文件注入系统提示。默认值：`"always"`。 +控制何时将工作区 bootstrap 文件注入到系统提示中。默认值：`"always"`。 -- `"continuation-skip"`：安全续接轮次（在助手完成回复之后）会跳过工作区 bootstrap 的重新注入，从而减小提示大小。心跳运行和压缩后重试仍会重建上下文。 +- `"continuation-skip"`：安全续接轮次（在 assistant 完成响应之后）会跳过工作区 bootstrap 的重新注入，从而缩小提示大小。Heartbeat 运行和压缩后重试仍会重建上下文。 ```json5 { @@ -961,7 +970,7 @@ IRC 基于插件，并在 `channels.irc` 下配置。 ### `agents.defaults.bootstrapTotalMaxChars` -跨所有工作区 bootstrap 文件注入的最大总字符数。默认值：`60000`。 +所有工作区 bootstrap 文件合计可注入的最大字符数。默认值：`60000`。 ```json5 { @@ -971,11 +980,12 @@ IRC 基于插件，并在 `channels.irc` 下配置。 ### `agents.defaults.bootstrapPromptTruncationWarning` -控制 bootstrap 上下文被截断时，对智能体可见的警告文本。默认值：`"once"`。 +控制在 bootstrap 上下文被截断时，向智能体显示的警告文本。 +默认值：`"once"`。 -- `"off"`：绝不向系统提示注入警告文本。 -- `"once"`：每个唯一的截断签名仅注入一次警告（推荐）。 -- `"always"`：只要存在截断，就在每次运行时注入警告。 +- `"off"`：绝不将警告文本注入系统提示。 +- `"once"`：每个唯一的截断签名只注入一次警告（推荐）。 +- `"always"`：只要存在截断，就在每次运行时都注入警告。 ```json5 { @@ -985,7 +995,7 @@ IRC 基于插件，并在 `channels.irc` 下配置。 ### 上下文预算归属映射 -OpenClaw 拥有多个高容量提示/上下文预算，这些预算会按子系统有意拆分，而不是全部流经一个通用旋钮。 +OpenClaw 拥有多个高容量提示 / 上下文预算，并且它们被有意按子系统拆分，而不是全部通过一个通用调节项流转。 - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`： @@ -994,20 +1004,21 @@ OpenClaw 拥有多个高容量提示/上下文预算，这些预算会按子系 一次性的 `/new` 和 `/reset` 启动前导内容，包括最近的每日 `memory/*.md` 文件。 - `skills.limits.*`： - 注入系统提示中的紧凑 Skills 列表。 + 注入到系统提示中的紧凑 Skills 列表。 - `agents.defaults.contextLimits.*`： - 有界的运行时摘录和运行时拥有的注入块。 + 有界运行时摘录和由运行时拥有的注入块。 - `memory.qmd.limits.*`： - 已索引 memory 搜索片段和注入大小控制。 + 已索引内存搜索片段和注入大小控制。 -仅当某个智能体需要不同预算时，才使用匹配的按智能体覆盖： +仅当某个智能体需要不同预算时，才使用对应的按智能体覆盖： - `agents.list[].skillsLimits.maxSkillsPromptChars` - `agents.list[].contextLimits.*` #### `agents.defaults.startupContext` -控制在裸 `/new` 和 `/reset` 运行时注入的首轮启动前导内容。 +控制在纯 `/new` 和 `/reset` +运行时注入的首次轮次启动前导内容。 ```json5 { @@ -1028,7 +1039,7 @@ OpenClaw 拥有多个高容量提示/上下文预算，这些预算会按子系 #### `agents.defaults.contextLimits` -用于有界运行时上下文表面的共享默认值。 +有界运行时上下文表面的共享默认值。 ```json5 { @@ -1045,14 +1056,19 @@ OpenClaw 拥有多个高容量提示/上下文预算，这些预算会按子系 } ``` -- `memoryGetMaxChars`：`memory_get` 摘录在添加截断元数据和续接通知之前的默认上限。 -- `memoryGetDefaultLines`：省略 `lines` 时，`memory_get` 的默认行窗口。 -- `toolResultMaxChars`：用于持久化结果和溢出恢复的实时工具结果上限。 -- `postCompactionMaxChars`：压缩后刷新注入期间使用的 `AGENTS.md` 摘录上限。 +- `memoryGetMaxChars`：在添加截断元数据 + 和续接提示之前，`memory_get` 摘录的默认上限。 +- `memoryGetDefaultLines`：在省略 `lines` 时， + `memory_get` 的默认行窗口。 +- `toolResultMaxChars`：用于持久化结果和 + 溢出恢复的实时工具结果上限。 +- `postCompactionMaxChars`：用于压缩后刷新注入期间 + 的 AGENTS.md 摘录上限。 #### `agents.list[].contextLimits` -对共享 `contextLimits` 旋钮的按智能体覆盖。省略的字段将继承自 `agents.defaults.contextLimits`。 +共享 `contextLimits` 调节项的按智能体覆盖。省略的字段会继承 +`agents.defaults.contextLimits`。 ```json5 { @@ -1078,7 +1094,8 @@ OpenClaw 拥有多个高容量提示/上下文预算，这些预算会按子系 #### `skills.limits.maxSkillsPromptChars` -注入系统提示中的紧凑 Skills 列表的全局上限。这不会影响按需读取 `SKILL.md` 文件。 +注入到系统提示中的紧凑 Skills 列表的全局上限。此项 +不会影响按需读取 `SKILL.md` 文件。 ```json5 { @@ -1092,7 +1109,7 @@ OpenClaw 拥有多个高容量提示/上下文预算，这些预算会按子系 #### `agents.list[].skillsLimits.maxSkillsPromptChars` -对 Skills 提示预算的按智能体覆盖。 +Skills 提示预算的按智能体覆盖。 ```json5 { @@ -1111,10 +1128,10 @@ OpenClaw 拥有多个高容量提示/上下文预算，这些预算会按子系 ### `agents.defaults.imageMaxDimensionPx` -在调用提供商之前，转录/工具图像块中图像最长边的最大像素尺寸。 +在调用提供商之前，转录 / 工具图像块中图像最长边的最大像素尺寸。 默认值：`1200`。 -较低的值通常会减少视觉 token 使用量，以及以截图为主的运行中的请求负载大小。 +对于大量截图的运行，较低的值通常会减少视觉 token 使用量和请求负载大小。 较高的值则会保留更多视觉细节。 ```json5 @@ -1125,7 +1142,7 @@ OpenClaw 拥有多个高容量提示/上下文预算，这些预算会按子系 ### `agents.defaults.userTimezone` -用于系统提示上下文的时区（不影响消息时间戳）。未设置时回退到主机时区。 +系统提示上下文所用时区（不是消息时间戳）。会回退到主机时区。 ```json5 { @@ -1135,7 +1152,7 @@ OpenClaw 拥有多个高容量提示/上下文预算，这些预算会按子系 ### `agents.defaults.timeFormat` -系统提示中的时间格式。默认值：`auto`（操作系统偏好）。 +系统提示中的时间格式。默认值：`auto`（OS 偏好）。 ```json5 { @@ -1173,9 +1190,9 @@ OpenClaw 拥有多个高容量提示/上下文预算，这些预算会按子系 primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // global default provider params + params: { cacheRetention: "long" }, // 全局默认提供商参数 embeddedHarness: { - runtime: "auto", // auto | pi | registered harness id, e.g. codex + runtime: "auto", // auto | pi | 已注册的 harness id，例如 codex fallback: "pi", // pi | none }, pdfMaxBytesMb: 10, @@ -1192,57 +1209,57 @@ OpenClaw 拥有多个高容量提示/上下文预算，这些预算会按子系 } ``` -- `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 +- `model`：既接受字符串（`"provider/model"`），也接受对象（`{ primary, fallbacks }`）。 - 字符串形式仅设置主模型。 - - 对象形式设置主模型以及有序的故障转移模型。 -- `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 对象形式设置主模型以及有序故障转移模型。 +- `imageModel`：既接受字符串（`"provider/model"`），也接受对象（`{ primary, fallbacks }`）。 - 由 `image` 工具路径用作其视觉模型配置。 - - 当所选/默认模型无法接受图像输入时，也用作回退路由。 -- `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 由共享图像生成能力以及未来任何生成图像的工具/插件表面使用。 - - 典型值：`google/gemini-3.1-flash-image-preview`（用于原生 Gemini 图像生成）、`fal/fal-ai/flux/dev`（用于 fal），或 `openai/gpt-image-2`（用于 OpenAI Images）。 - - 如果你直接选择某个提供商/模型，也要配置匹配的提供商身份验证/API key（例如 `google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 使用 `OPENAI_API_KEY`，`fal/*` 使用 `FAL_KEY`）。 - - 如果省略，`image_generate` 仍可推断出一个由身份验证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。 -- `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 由共享音乐生成能力和内置 `music_generate` 工具使用。 + - 当已选 / 默认模型无法接受图像输入时，也会用作回退路由。 +- `imageGenerationModel`：既接受字符串（`"provider/model"`），也接受对象（`{ primary, fallbacks }`）。 + - 供共享图像生成能力以及任何未来生成图像的工具 / 插件表面使用。 + - 典型值：`google/gemini-3.1-flash-image-preview`（原生 Gemini 图像生成）、`fal/fal-ai/flux/dev`（fal）或 `openai/gpt-image-2`（OpenAI Images）。 + - 如果你直接选择某个 provider/model，也请配置匹配的提供商认证 / API key（例如，`google/*` 对应 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/*` 对应 `OPENAI_API_KEY`，`fal/*` 对应 `FAL_KEY`）。 + - 如果省略，`image_generate` 仍可推断出一个具备认证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的图像生成提供商。 +- `musicGenerationModel`：既接受字符串（`"provider/model"`），也接受对象（`{ primary, fallbacks }`）。 + - 供共享音乐生成能力和内置 `music_generate` 工具使用。 - 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。 - - 如果省略，`music_generate` 仍可推断出一个由身份验证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。 - - 如果你直接选择某个提供商/模型，也要配置匹配的提供商身份验证/API key。 -- `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - - 由共享视频生成能力和内置 `video_generate` 工具使用。 + - 如果省略，`music_generate` 仍可推断出一个具备认证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的音乐生成提供商。 + - 如果你直接选择某个 provider/model，也请配置匹配的提供商认证 / API key。 +- `videoGenerationModel`：既接受字符串（`"provider/model"`），也接受对象（`{ primary, fallbacks }`）。 + - 供共享视频生成能力和内置 `video_generate` 工具使用。 - 典型值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。 - - 如果省略，`video_generate` 仍可推断出一个由身份验证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。 - - 如果你直接选择某个提供商/模型，也要配置匹配的提供商身份验证/API key。 - - 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 -- `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 + - 如果省略，`video_generate` 仍可推断出一个具备认证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的视频生成提供商。 + - 如果你直接选择某个 provider/model，也请配置匹配的提供商认证 / API key。 + - 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。 +- `pdfModel`：既接受字符串（`"provider/model"`），也接受对象（`{ primary, fallbacks }`）。 - 由 `pdf` 工具用于模型路由。 - - 如果省略，PDF 工具会先回退到 `imageModel`，再回退到已解析的会话/默认模型。 -- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具使用的默认 PDF 大小限制。 -- `pdfMaxPages`：`pdf` 工具在提取回退模式中考虑的默认最大页数。 -- `verboseDefault`：智能体的默认 verbose 级别。取值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。 -- `elevatedDefault`：智能体的默认 elevated-output 级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 -- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.4`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该精确模型 ID 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此建议优先使用显式 `provider/model`）。如果该提供商不再提供已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露一个陈旧的、已移除提供商默认值。 -- `models`：为 `/model` 配置的模型目录和允许列表。每个条目都可以包含 `alias`（快捷方式）和 `params`（提供商特定，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 - - 安全编辑：使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加条目。`config set` 会拒绝替换那些会移除现有允许列表条目的操作，除非你传入 `--replace`。 - - 按提供商范围的配置/新手引导流程会将所选提供商模型合并到该映射中，并保留已配置的无关提供商。 -- `params`：应用于所有模型的全局默认提供商参数。在 `agents.defaults.params` 设置（例如 `{ cacheRetention: "long" }`）。 -- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后再由 `agents.list[].params`（匹配的智能体 ID）按键覆盖。详情请参阅 [Prompt Caching](/zh-CN/reference/prompt-caching)。 -- `embeddedHarness`：默认的底层嵌入式智能体运行时策略。使用 `runtime: "auto"` 让已注册的插件 harness 认领受支持的模型，使用 `runtime: "pi"` 强制使用内置 Pi harness，或使用已注册的 harness ID，例如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动 Pi 回退。 -- 会变更这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及回退 add/remove 命令）会保存规范的对象形式，并尽可能保留现有回退列表。 -- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话仍然串行）。默认值：4。 + - 如果省略，PDF 工具会回退到 `imageModel`，然后再回退到已解析的会话 / 默认模型。 +- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb`，这是 `pdf` 工具的默认 PDF 大小限制。 +- `pdfMaxPages`：`pdf` 工具在提取回退模式下考虑的默认最大页数。 +- `verboseDefault`：智能体的默认详细级别。取值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。 +- `elevatedDefault`：智能体的默认 elevated 输出级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。 +- `model.primary`：格式为 `provider/model`（例如 `openai/gpt-5.5`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试对该精确模型 id 的唯一已配置提供商匹配，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此请优先使用显式 `provider/model`）。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider/model，而不是继续暴露一个已过时、已移除提供商的默认值。 +- `models`：为 `/model` 配置的模型目录和允许列表。每个条目都可以包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`）。 + - 安全编辑：使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加条目。除非你传入 `--replace`，否则 `config set` 会拒绝会移除现有允许列表条目的替换操作。 + - 按提供商范围的配置 / 新手引导流程会将所选提供商模型合并到此映射中，并保留其他已配置提供商不受影响。 +- `params`：应用于所有模型的全局默认提供商参数。设置位置为 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。 +- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配的智能体 id）再按键覆盖。详见 [Prompt Caching](/zh-CN/reference/prompt-caching)。 +- `embeddedHarness`：默认的底层嵌入式智能体运行时策略。使用 `runtime: "auto"` 让已注册的插件 harness 认领受支持的模型，使用 `runtime: "pi"` 强制使用内置 PI harness，或者指定已注册 harness id，例如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动 PI 回退。 +- 会变更这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及 fallback add/remove 命令）会保存规范对象形式，并尽可能保留现有的回退列表。 +- `maxConcurrent`：跨会话并行运行的最大智能体数（每个会话本身仍串行）。默认值：4。 ### `agents.defaults.embeddedHarness` -`embeddedHarness` 控制由哪个底层执行器运行嵌入式智能体轮次。 -大多数部署应保持默认值 `{ runtime: "auto", fallback: "pi" }`。 -当受信任的插件提供原生 harness 时使用它，例如内置的 +`embeddedHarness` 控制哪个底层执行器运行嵌入式智能体轮次。 +大多数部署应保留默认值 `{ runtime: "auto", fallback: "pi" }`。 +当受信任的插件提供原生 harness 时，可使用此项，例如内置的 Codex app-server harness。 ```json5 { agents: { defaults: { - model: "codex/gpt-5.4", + model: "codex/gpt-5.5", embeddedHarness: { runtime: "codex", fallback: "none", @@ -1252,35 +1269,35 @@ Codex app-server harness。 } ``` -- `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness ID。内置的 Codex 插件会注册 `codex`。 -- `fallback`：`"pi"` 或 `"none"`。当未选择任何插件 harness 时，`"pi"` 会保留内置 Pi harness 作为兼容性回退。`"none"` 则会让缺失或不受支持的插件 harness 选择直接失败，而不是悄悄使用 Pi。所选插件 harness 的失败始终会直接暴露。 -- 环境变量覆盖：`OPENCLAW_AGENT_RUNTIME=` 会覆盖 `runtime`；`OPENCLAW_AGENT_HARNESS_FALLBACK=none` 会为该进程禁用 Pi 回退。 -- 对于仅 Codex 的部署，设置 `model: "codex/gpt-5.4"`、`embeddedHarness.runtime: "codex"` 和 `embeddedHarness.fallback: "none"`。 -- 第一次嵌入式运行后，harness 选择会按会话 ID 固定。配置/环境变量变更只影响新的或已重置的会话，不影响现有转录。具有转录历史但没有已记录固定值的旧会话会被视为固定到 Pi。`/status` 会在 `Fast` 旁显示非 Pi 的 harness ID，例如 `codex`。 -- 这只控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用它们各自的提供商/模型设置。 +- `runtime`：`"auto"`、`"pi"` 或某个已注册的插件 harness id。内置 Codex 插件会注册 `codex`。 +- `fallback`：`"pi"` 或 `"none"`。当未选择任何插件 harness 时，`"pi"` 会保留内置 PI harness 作为兼容性回退。`"none"` 则会让缺失或不受支持的插件 harness 选择直接失败，而不是静默使用 PI。已选中的插件 harness 失败始终会直接暴露。 +- 环境变量覆盖：`OPENCLAW_AGENT_RUNTIME=` 会覆盖 `runtime`；`OPENCLAW_AGENT_HARNESS_FALLBACK=none` 会为该进程禁用 PI 回退。 +- 对于仅 Codex 的部署，请设置 `model: "codex/gpt-5.5"`、`embeddedHarness.runtime: "codex"` 和 `embeddedHarness.fallback: "none"`。 +- 在首次嵌入式运行后，harness 选择会按会话 id 固定。配置 / 环境变量变更会影响新的或已重置的会话，不会影响现有对话记录。带有对话历史但没有记录固定项的旧会话会被视为已固定到 PI。`/status` 会在 `Fast` 旁显示非 PI 的 harness id，例如 `codex`。 +- 这仅控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用它们各自的提供商 / 模型设置。 **内置别名简写**（仅当模型位于 `agents.defaults.models` 中时适用）： -| 别名 | 模型 | -| ------------------- | ---- | -| `opus` | `anthropic/claude-opus-4-6` | -| `sonnet` | `anthropic/claude-sonnet-4-6` | -| `gpt` | `openai/gpt-5.4` | -| `gpt-mini` | `openai/gpt-5.4-mini` | -| `gpt-nano` | `openai/gpt-5.4-nano` | -| `gemini` | `google/gemini-3.1-pro-preview` | -| `gemini-flash` | `google/gemini-3-flash-preview` | +| 别名 | 模型 | +| ------------------- | -------------------------------------- | +| `opus` | `anthropic/claude-opus-4-6` | +| `sonnet` | `anthropic/claude-sonnet-4-6` | +| `gpt` | `openai/gpt-5.5` | +| `gpt-mini` | `openai/gpt-5.4-mini` | +| `gpt-nano` | `openai/gpt-5.4-nano` | +| `gemini` | `google/gemini-3.1-pro-preview` | +| `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -你配置的别名始终优先于默认值。 +你自己配置的别名始终优先于默认值。 Z.AI GLM-4.x 模型会自动启用 thinking 模式，除非你设置 `--thinking off`，或自行定义 `agents.defaults.models["zai/"].params.thinking`。 -Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设为 `false` 可禁用它。 +Z.AI 模型默认启用 `tool_stream` 用于工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设为 `false` 可禁用它。 Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 `adaptive` thinking。 ### `agents.defaults.cliBackends` -用于纯文本回退运行（无工具调用）的可选 CLI 后端。在 API 提供商失败时可作为备份。 +适用于纯文本回退运行（无工具调用）的可选 CLI 后端。在 API 提供商失败时，可作为备份。 ```json5 { @@ -1308,13 +1325,13 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- CLI 后端以文本优先；工具始终禁用。 +- CLI 后端以文本为先；工具始终被禁用。 - 设置了 `sessionArg` 时支持会话。 -- 当 `imageArg` 接受文件路径时，支持图像透传。 +- 当 `imageArg` 接受文件路径时，支持图像直通。 ### `agents.defaults.systemPromptOverride` -用固定字符串替换完整的 OpenClaw 组装系统提示。可在默认级别设置（`agents.defaults.systemPromptOverride`），也可按智能体设置（`agents.list[].systemPromptOverride`）。按智能体值优先；空值或仅空白的值会被忽略。适用于受控提示实验。 +用固定字符串替换整个由 OpenClaw 组装的系统提示。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体级别（`agents.list[].systemPromptOverride`）设置。按智能体的值优先；空值或仅包含空白字符的值会被忽略。适用于受控的提示实验。 ```json5 { @@ -1328,7 +1345,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 ### `agents.defaults.promptOverlays` -按模型家族应用、与提供商无关的提示覆盖。GPT-5 家族模型 ID 会跨提供商接收共享行为契约；`personality` 仅控制友好的交互风格层。 +按模型家族应用的、与提供商无关的提示叠加层。GPT-5 家族模型 id 会跨提供商接收共享行为契约；`personality` 仅控制友好交互风格这一层。 ```json5 { @@ -1344,29 +1361,29 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `"friendly"`（默认）和 `"on"` 会启用友好的交互风格层。 -- `"off"` 仅禁用友好层；带标签的 GPT-5 行为契约仍保持启用。 -- 当此共享设置未设置时，仍会读取旧版 `plugins.entries.openai.config.personality`。 +- `"friendly"`（默认）和 `"on"` 会启用友好交互风格层。 +- `"off"` 只会禁用友好层；带标签的 GPT-5 行为契约仍保持启用。 +- 当该共享设置未设置时，仍会读取旧版 `plugins.entries.openai.config.personality`。 ### `agents.defaults.heartbeat` -定期心跳运行。 +周期性 Heartbeat 运行。 ```json5 { agents: { defaults: { heartbeat: { - every: "30m", // 0m disables + every: "30m", // 0m 表示禁用 model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt - lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files - isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) + includeSystemPromptSection: true, // 默认：true；false 会从系统提示中省略 Heartbeat 部分 + lightContext: false, // 默认：false；true 仅保留工作区 bootstrap 文件中的 HEARTBEAT.md + isolatedSession: false, // 默认：false；true 会在新会话中运行每次 Heartbeat（无对话历史） session: "main", to: "+15555550123", - directPolicy: "allow", // allow (default) | block - target: "none", // default: none | options: last | whatsapp | telegram | discord | ... + directPolicy: "allow", // allow（默认）| block + target: "none", // 默认：none | 可选值：last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -1377,15 +1394,15 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 身份验证）或 `1h`（OAuth 身份验证）。设为 `0m` 可禁用。 +- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。 - `includeSystemPromptSection`：设为 false 时，会从系统提示中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入 bootstrap 上下文。默认值：`true`。 -- `suppressToolErrorWarnings`：设为 true 时，会在 heartbeat 运行期间抑制工具错误警告负载。 -- `timeoutSeconds`：heartbeat 智能体轮次在被中止前允许的最长秒数。留空则使用 `agents.defaults.timeoutSeconds`。 -- `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 会抑制直接目标投递，并发出 `reason=dm-blocked`。 -- `lightContext`：设为 true 时，heartbeat 运行会使用轻量 bootstrap 上下文，并仅保留工作区 bootstrap 文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：设为 true 时，每次 heartbeat 都会在一个全新会话中运行，不带任何先前对话历史。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次 heartbeat 的 token 成本从约 100K 降低到约 2-5K token。 -- 按智能体设置：使用 `agents.list[].heartbeat`。当任一智能体定义了 `heartbeat` 时，**只有这些智能体**会运行 heartbeat。 -- Heartbeat 会运行完整的智能体轮次——更短的间隔会消耗更多 token。 +- `suppressToolErrorWarnings`：设为 true 时，会在 Heartbeat 运行期间抑制工具错误警告载荷。 +- `timeoutSeconds`：Heartbeat 智能体轮次在被中止前允许的最长秒数。若不设置，则使用 `agents.defaults.timeoutSeconds`。 +- `directPolicy`：直接 / 私信传递策略。`allow`（默认）允许直接目标传递。`block` 会抑制直接目标传递，并发出 `reason=dm-blocked`。 +- `lightContext`：设为 true 时，Heartbeat 运行会使用轻量 bootstrap 上下文，并且仅保留工作区 bootstrap 文件中的 `HEARTBEAT.md`。 +- `isolatedSession`：设为 true 时，每次 Heartbeat 都会在一个全新会话中运行，没有任何先前的对话历史。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次 Heartbeat 的 token 成本从约 100K 降低到约 2–5K token。 +- 按智能体设置：使用 `agents.list[].heartbeat`。当任意智能体定义了 `heartbeat` 时，**只有这些智能体**会运行 Heartbeat。 +- Heartbeat 会运行完整的智能体轮次 —— 间隔越短，消耗的 token 越多。 ### `agents.defaults.compaction` @@ -1395,14 +1412,14 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // id of a registered compaction provider plugin (optional) + provider: "my-provider", // 已注册压缩提供商插件的 id（可选） timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom - postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection - model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override - notifyUser: true, // send brief notices when compaction starts and completes (default: false) + identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // 当 identifierPolicy=custom 时使用 + postCompactionSections: ["Session Startup", "Red Lines"], // [] 表示禁用重新注入 + model: "openrouter/anthropic/claude-sonnet-4-6", // 仅用于压缩的可选模型覆盖 + notifyUser: true, // 在压缩开始和完成时发送简短通知给用户（默认：false） memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -1415,19 +1432,19 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- `mode`：`default` 或 `safeguard`（用于长历史记录的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `provider`：已注册 compaction 提供商插件的 ID。设置后，将调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。失败时会回退到内置实现。设置提供商会强制使用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。 -- `timeoutSeconds`：OpenClaw 在中止前允许单次 compaction 操作运行的最大秒数。默认值：`900`。 -- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预置内置的不透明标识符保留指引。 -- `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留说明文本。 -- `postCompactionSections`：compaction 后重新注入的可选 `AGENTS.md` H2/H3 章节名。默认值为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。未设置或显式设为该默认对时，也会接受较旧的 `Every Session`/`Safety` 标题作为旧版回退。 -- `model`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。当主会话应保持一个模型，但 compaction 摘要应使用另一个模型时使用；未设置时，compaction 使用会话的主模型。 -- `notifyUser`：设为 `true` 时，会在 compaction 开始和完成时向用户发送简短通知（例如 “正在压缩上下文...” 和 “上下文压缩完成”）。默认禁用，以保持 compaction 静默。 -- `memoryFlush`：自动 compaction 前的静默智能体轮次，用于存储持久 memory。工作区为只读时会跳过。 +- `mode`：`default` 或 `safeguard`（对长历史进行分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `provider`：已注册压缩提供商插件的 id。设置后，会调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。失败时会回退到内置实现。设置提供商会强制 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。 +- `timeoutSeconds`：OpenClaw 在中止单次压缩操作前允许的最长秒数。默认值：`900`。 +- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在压缩摘要前附加内置的不透明标识符保留指导。 +- `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。 +- `postCompactionSections`：压缩后重新注入的可选 AGENTS.md H2/H3 节名。默认值为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。若未设置，或显式设置为该默认对，则还会接受旧版 `Every Session` / `Safety` 标题作为兼容回退。 +- `model`：仅用于压缩摘要的可选 `provider/model-id` 覆盖。当主会话应保留一个模型，而压缩摘要应使用另一个模型时使用；若未设置，压缩会使用会话的主模型。 +- `notifyUser`：设为 `true` 时，会在压缩开始和完成时向用户发送简短通知（例如“Compacting context...”和“Compaction complete”）。默认禁用，以保持压缩静默。 +- `memoryFlush`：在自动压缩前进行一次静默的智能体轮次，用于存储持久记忆。当工作区为只读时会跳过。 ### `agents.defaults.contextPruning` -在发送给 LLM 之前，从内存上下文中修剪**旧的工具结果**。**不会**修改磁盘上的会话历史。 +在发送给 LLM 之前，从内存上下文中清理**旧的工具结果**。**不会**修改磁盘上的会话历史。 ```json5 { @@ -1435,7 +1452,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // duration (ms/s/m/h), default unit: minutes + ttl: "1h", // 时长（ms/s/m/h），默认单位：分钟 keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, @@ -1449,21 +1466,21 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` - + -- `mode: "cache-ttl"` 会启用修剪过程。 -- `ttl` 控制多久之后才能再次运行修剪（自上次缓存触碰后）。 -- 修剪会先对过大的工具结果进行软截断，如仍有需要，再对更旧的工具结果执行硬清除。 +- `mode: "cache-ttl"` 会启用清理过程。 +- `ttl` 控制下次允许再次运行清理的频率（在上次缓存触碰之后）。 +- 清理会先对超大的工具结果执行软裁剪，如仍有需要，再对较旧的工具结果执行硬清除。 -**软截断** 会保留开头和结尾，并在中间插入 `...`。 +**软裁剪**会保留开头 + 结尾，并在中间插入 `...`。 -**硬清除** 会将整个工具结果替换为占位符。 +**硬清除**会用占位符替换整个工具结果。 -注意： +说明： -- 图像块永远不会被截断/清除。 -- 比例按字符计算（近似），不是精确 token 计数。 -- 如果 assistant 消息少于 `keepLastAssistants` 条，则跳过修剪。 +- 图像块永远不会被裁剪 / 清除。 +- 比例是基于字符数的（近似），不是精确 token 数。 +- 如果 assistant 消息少于 `keepLastAssistants` 条，则会跳过清理。 @@ -1479,19 +1496,19 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 blockStreamingBreak: "text_end", // text_end | message_end blockStreamingChunk: { minChars: 800, maxChars: 1200 }, blockStreamingCoalesce: { idleMs: 1000 }, - humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs) + humanDelay: { mode: "natural" }, // off | natural | custom（使用 minMs/maxMs） }, }, } ``` - 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。 -- 渠道级覆盖：`channels..blockStreamingCoalesce`（以及按账户的变体）。Signal/Slack/Discord/Google Chat 默认为 `minChars: 1500`。 -- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。按智能体覆盖：`agents.list[].humanDelay`。 +- 渠道覆盖：`channels..blockStreamingCoalesce`（以及每账户变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 +- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500 ms。按智能体覆盖：`agents.list[].humanDelay`。 -行为和分块细节请参见 [流式传输](/zh-CN/concepts/streaming)。 +行为和分块细节请参见 [Streaming](/zh-CN/concepts/streaming)。 -### 输入指示器 +### 输入中指示器 ```json5 { @@ -1504,10 +1521,10 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 } ``` -- 默认值：私聊/提及使用 `instant`，未被提及的群聊使用 `message`。 +- 默认值：在私聊 / 被提及时为 `instant`，在未被提及的群聊中为 `message`。 - 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 -请参见 [输入指示器](/zh-CN/concepts/typing-indicators)。 +参见 [Typing Indicators](/zh-CN/concepts/typing-indicators)。 @@ -1559,7 +1576,7 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // SecretRefs / inline contents also supported: + // 也支持 SecretRef / 内联内容： // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -1616,44 +1633,44 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 - `ssh`：通用 SSH 支持的远程运行时 - `openshell`：OpenShell 运行时 -选择 `backend: "openshell"` 时，运行时特定设置会移动到 +当选择 `backend: "openshell"` 时，运行时特定设置会移动到 `plugins.entries.openshell.config`。 **SSH 后端配置：** -- `target`：格式为 `user@host[:port]` 的 SSH 目标 +- `target`：`user@host[:port]` 形式的 SSH 目标 - `command`：SSH 客户端命令（默认：`ssh`） -- `workspaceRoot`：用于按作用域工作区的远程绝对根目录 +- `workspaceRoot`：用于每个 scope 工作区的远程绝对根目录 - `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件 - `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其实体化为临时文件 -- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关 +- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略调节项 -**SSH 身份验证优先级：** +**SSH 认证优先级：** - `identityData` 优先于 `identityFile` - `certificateData` 优先于 `certificateFile` - `knownHostsData` 优先于 `knownHostsFile` -- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前，从活动 secrets 运行时快照中解析 +- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前，从当前活动的 secrets 运行时快照中解析 **SSH 后端行为：** -- 在创建或重建后，仅初始化远程工作区一次 -- 随后保持远程 SSH 工作区为规范副本 +- 在创建或重建后会为远程工作区执行一次初始化 +- 然后保持远程 SSH 工作区为规范状态 - 通过 SSH 路由 `exec`、文件工具和媒体路径 - 不会自动将远程更改同步回主机 - 不支持沙箱浏览器容器 **工作区访问：** -- `none`：位于 `~/.openclaw/sandboxes` 下的按作用域沙箱工作区 +- `none`：每个 scope 一个沙箱工作区，位于 `~/.openclaw/sandboxes` - `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent` - `rw`：智能体工作区以读写方式挂载到 `/workspace` -**作用域：** +**Scope：** -- `session`：按会话分配容器 + 工作区 -- `agent`：每个智能体一个容器 + 工作区（默认） -- `shared`：共享容器和工作区（无跨会话隔离） +- `session`：每会话一个容器 + 工作区 +- `agent`：每智能体一个容器 + 工作区（默认） +- `shared`：共享容器和工作区（没有跨会话隔离） **OpenShell 插件配置：** @@ -1668,10 +1685,10 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", - gateway: "lab", // optional - gatewayEndpoint: "https://lab.example", // optional - policy: "strict", // optional OpenShell policy id - providers: ["openai"], // optional + gateway: "lab", // 可选 + gatewayEndpoint: "https://lab.example", // 可选 + policy: "strict", // 可选的 OpenShell policy id + providers: ["openai"], // 可选 autoProviders: true, timeoutSeconds: 120, }, @@ -1683,30 +1700,30 @@ Anthropic Claude 4.6 模型在未设置显式 thinking 级别时，默认使用 **OpenShell 模式：** -- `mirror`：在执行前从本地播种到远程，在执行后同步回本地；本地工作区保持为规范副本 -- `remote`：在创建沙箱时将本地播种到远程一次，之后保持远程工作区为规范副本 +- `mirror`：在 exec 前将远程端与本地同步播种，exec 后再同步回本地；本地工作区保持为规范副本 +- `remote`：在创建沙箱时仅对远程端播种一次，之后保持远程工作区为规范副本 -在 `remote` 模式下，种子步骤之后，在 OpenClaw 之外进行的主机本地编辑不会自动同步到沙箱中。 -传输方式是通过 SSH 进入 OpenShell 沙箱，但该插件拥有沙箱生命周期以及可选的镜像同步。 +在 `remote` 模式下，播种步骤之后，在 OpenClaw 之外对主机本地所做的编辑不会自动同步到沙箱中。 +传输层是通过 SSH 连接到 OpenShell 沙箱，但插件负责沙箱生命周期以及可选的镜像同步。 **`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。 -**容器默认使用 `network: "none"`**——如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。 -默认会阻止 `"host"`。默认也会阻止 `"container:"`，除非你显式设置 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急模式）。 +**容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请设为 `"bridge"`（或自定义 bridge 网络）。 +`"host"` 会被阻止。`"container:"` 默认也会被阻止，除非你显式设置 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急破窗模式）。 -**传入附件** 会被暂存到活动工作区中的 `media/inbound/*`。 +**传入附件** 会被暂存到当前活动工作区中的 `media/inbound/*`。 **`docker.binds`** 会挂载额外的主机目录；全局和按智能体的 binds 会合并。 -**沙箱隔离浏览器**（`sandbox.browser.enabled`）：运行在容器中的 Chromium + CDP。noVNC URL 会注入系统提示中。不需要在 `openclaw.json` 中启用 `browser.enabled`。 -noVNC 观察者访问默认使用 VNC 身份验证，OpenClaw 会发出一个短期有效的 token URL（而不是在共享 URL 中暴露密码）。 +**沙箱隔离浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。系统提示中会注入 noVNC URL。不需要在 `openclaw.json` 中启用 `browser.enabled`。 +noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短期有效的令牌 URL（而不是在共享 URL 中暴露密码）。 -- `allowHostControl: false`（默认）会阻止沙箱隔离会话以主机浏览器为目标。 -- `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。只有当你明确希望使用全局 bridge 连接时，才设置为 `bridge`。 -- `cdpSourceRange` 可选，用于在容器边界将 CDP 入口限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。 -- `sandbox.browser.binds` 仅将额外的主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。 -- 启动默认值定义于 `scripts/sandbox-browser-entrypoint.sh`，并针对容器主机进行了调优： +- `allowHostControl: false`（默认）会阻止沙箱隔离会话将目标指向主机浏览器。 +- `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。只有当你明确想要全局 bridge 连通性时才设为 `bridge`。 +- `cdpSourceRange` 可选择在容器边界将 CDP 入站限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。 +- `sandbox.browser.binds` 仅会将额外主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。 +- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机进行了调优： - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1725,16 +1742,16 @@ noVNC 观察者访问默认使用 VNC 身份验证，OpenClaw 会发出一个短 - `--metrics-recording-only` - `--disable-extensions`（默认启用） - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` - 默认启用；如果 WebGL/3D 使用场景需要它们，可通过 + 默认启用；如果 WebGL / 3D 使用场景需要它们，可通过 `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用这些标志。 - - 如果你的工作流依赖扩展，可通过 - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 重新启用扩展。 + - 如果你的工作流 + 依赖扩展，`OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会重新启用扩展。 - `--renderer-process-limit=2` 可通过 - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 修改；设为 `0` 将使用 Chromium 的 - 默认进程限制。 + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=` 更改；设为 `0` 可使用 Chromium 的 + 默认进程上限。 - 当启用 `noSandbox` 时，还会附加 `--no-sandbox` 和 `--disable-setuid-sandbox`。 - - 这些默认值是容器镜像基线；如需更改容器默认值，请使用带有自定义 - 入口点的自定义浏览器镜像。 + - 这些默认值是容器镜像基线；如需更改容器默认行为，请使用带自定义 + entrypoint 的自定义浏览器镜像。 @@ -1743,8 +1760,8 @@ noVNC 观察者访问默认使用 VNC 身份验证，OpenClaw 会发出一个短 构建镜像： ```bash -scripts/sandbox-setup.sh # main sandbox image -scripts/sandbox-browser-setup.sh # optional browser image +scripts/sandbox-setup.sh # 主沙箱镜像 +scripts/sandbox-browser-setup.sh # 可选浏览器镜像 ``` ### `agents.list`（按智能体覆盖） @@ -1759,13 +1776,13 @@ scripts/sandbox-browser-setup.sh # optional browser image name: "Main Agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", - model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } - thinkingDefault: "high", // per-agent thinking level override - reasoningDefault: "on", // per-agent reasoning visibility override - fastModeDefault: false, // per-agent fast mode override + model: "anthropic/claude-opus-4-6", // 或 { primary, fallbacks } + thinkingDefault: "high", // 按智能体覆盖的默认 thinking 级别 + reasoningDefault: "on", // 按智能体覆盖的默认 reasoning 可见性 + fastModeDefault: false, // 按智能体覆盖的默认 fast mode embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // overrides matching defaults.models params by key - skills: ["docs-search"], // replaces agents.defaults.skills when set + params: { cacheRetention: "none" }, // 按键覆盖匹配的 defaults.models params + skills: ["docs-search"], // 设置后会替换 agents.defaults.skills identity: { name: "Samantha", theme: "helpful sloth", @@ -1796,27 +1813,27 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `id`：稳定的智能体 ID（必填）。 -- `default`：当设置了多个时，以第一个为准（会记录警告）。如果一个都没设置，则列表中的第一个条目为默认值。 -- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 同时覆盖两者（`[]` 会禁用全局回退）。只覆盖 `primary` 的 cron 作业仍会继承默认回退，除非你设置 `fallbacks: []`。 -- `params`：按智能体的流参数，会合并到 `agents.defaults.models` 中选定模型条目之上。用于像 `cacheRetention`、`temperature` 或 `maxTokens` 这类按智能体覆盖，而无需复制整个模型目录。 -- `skills`：可选的按智能体 Skills 允许列表。若省略，则在已设置时继承 `agents.defaults.skills`；显式列表会替换默认值而不是合并，`[]` 表示不使用任何 Skills。 -- `thinkingDefault`：可选的按智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当未设置按消息或按会话覆盖时，会覆盖该智能体的 `agents.defaults.thinkingDefault`。 -- `reasoningDefault`：可选的按智能体默认 reasoning 可见性（`on | off | stream`）。当未设置按消息或按会话 reasoning 覆盖时生效。 -- `fastModeDefault`：可选的按智能体默认快速模式（`true | false`）。当未设置按消息或按会话快速模式覆盖时生效。 -- `embeddedHarness`：可选的按智能体底层 harness 策略覆盖。使用 `{ runtime: "codex", fallback: "none" }` 可让某个智能体仅使用 Codex，而其他智能体保留默认的 Pi 回退。 -- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 并设置 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 +- `id`：稳定的智能体 id（必需）。 +- `default`：如果设置了多个，以第一个为准（会记录警告）。如果一个都未设置，则列表中的第一个条目为默认值。 +- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 会同时覆盖两者（`[]` 会禁用全局 fallbacks）。只覆盖 `primary` 的 cron 作业仍会继承默认 fallbacks，除非你设置 `fallbacks: []`。 +- `params`：按智能体的流参数，会合并到 `agents.defaults.models` 中选定模型条目之上。用它来做按智能体的覆盖，例如 `cacheRetention`、`temperature` 或 `maxTokens`，而无需复制整个模型目录。 +- `skills`：可选的按智能体 Skills 允许列表。若省略，则当 `agents.defaults.skills` 已设置时，该智能体会继承它；显式列表会替换默认值而不是合并，`[]` 表示没有 Skills。 +- `thinkingDefault`：可选的按智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当未设置按消息或按会话覆盖时，它会覆盖该智能体的 `agents.defaults.thinkingDefault`。 +- `reasoningDefault`：可选的按智能体默认 reasoning 可见性（`on | off | stream`）。当未设置按消息或按会话的 reasoning 覆盖时适用。 +- `fastModeDefault`：可选的按智能体默认 fast mode（`true | false`）。当未设置按消息或按会话的 fast mode 覆盖时适用。 +- `embeddedHarness`：可选的按智能体底层 harness 策略覆盖。使用 `{ runtime: "codex", fallback: "none" }` 可让某个智能体仅使用 Codex，而其他智能体仍保留默认 PI 回退。 +- `runtime`：可选的按智能体运行时描述符。当该智能体应默认使用 ACP harness 会话时，请使用 `type: "acp"` 和 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。 - `identity.avatar`：工作区相对路径、`http(s)` URL 或 `data:` URI。 -- `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name`/`emoji`。 -- `subagents.allowAgents`：`sessions_spawn` 的智能体 ID 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 -- 沙箱继承保护：如果请求方会话处于沙箱隔离中，`sessions_spawn` 会拒绝那些将以非沙箱方式运行的目标。 -- `subagents.requireAgentId`：设为 true 时，会阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置；默认：false）。 +- `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name` / `emoji`。 +- `subagents.allowAgents`：`sessions_spawn` 的智能体 id 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 +- 沙箱继承保护：如果请求方会话处于沙箱隔离状态，`sessions_spawn` 会拒绝那些会以非沙箱模式运行的目标。 +- `subagents.requireAgentId`：设为 true 时，会阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式 profile 选择；默认：false）。 --- ## 多智能体路由 -在一个 Gateway 网关内运行多个隔离的智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。 +在一个 Gateway 网关中运行多个隔离的智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。 ```json5 { @@ -1835,11 +1852,11 @@ scripts/sandbox-browser-setup.sh # optional browser image ### 绑定匹配字段 -- `type`（可选）：普通路由使用 `route`（缺失时默认是 route），持久 ACP 会话绑定使用 `acp` -- `match.channel`（必填） +- `type`（可选）：普通路由用 `route`（缺失时默认为 route），持久 ACP 会话绑定用 `acp` +- `match.channel`（必需） - `match.accountId`（可选；`*` = 任意账户；省略 = 默认账户） - `match.peer`（可选；`{ kind: direct|group|channel, id }`） -- `match.guildId` / `match.teamId`（可选；渠道特定） +- `match.guildId` / `match.teamId`（可选；特定渠道使用） - `acp`（可选；仅用于 `type: "acp"`）：`{ mode, label, cwd, backend }` **确定性匹配顺序：** @@ -1847,17 +1864,17 @@ scripts/sandbox-browser-setup.sh # optional browser image 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId`（精确，无 peer/guild/team） -5. `match.accountId: "*"`（渠道级） +4. `match.accountId`（精确匹配，无 peer/guild/team） +5. `match.accountId: "*"`（整个渠道范围） 6. 默认智能体 -在每一层中，第一个匹配的 `bindings` 条目获胜。 +在每一层级内，第一个匹配的 `bindings` 条目获胜。 对于 `type: "acp"` 条目，OpenClaw 会按精确会话身份（`match.channel` + account + `match.peer.id`）解析，不使用上述 route 绑定层级顺序。 ### 按智能体访问配置 - + ```json5 { @@ -1976,22 +1993,22 @@ scripts/sandbox-browser-setup.sh # optional browser image }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) + parentForkMaxTokens: 100000, // 超过此 token 数时跳过父线程 fork（0 表示禁用） maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // duration or false - maxDiskBytes: "500mb", // optional hard budget - highWaterBytes: "400mb", // optional cleanup target + resetArchiveRetention: "30d", // 时长或 false + maxDiskBytes: "500mb", // 可选硬预算 + highWaterBytes: "400mb", // 可选清理目标 }, threadBindings: { enabled: true, - idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) - maxAgeHours: 0, // default hard max age in hours (`0` disables) + idleHours: 24, // 默认按小时计算的不活跃自动取消焦点（`0` 表示禁用） + maxAgeHours: 0, // 默认按小时计算的硬性最大存续时间（`0` 表示禁用） }, - mainKey: "main", // legacy (runtime always uses "main") + mainKey: "main", // 旧版字段（运行时始终使用 "main"） agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -2004,34 +2021,34 @@ scripts/sandbox-browser-setup.sh # optional browser image - **`scope`**：群聊上下文的基础会话分组策略。 - - `per-sender`（默认）：在同一渠道上下文中，每个发送者获得独立会话。 - - `global`：渠道上下文中的所有参与者共享一个会话（仅在确实需要共享上下文时使用）。 + - `per-sender`（默认）：在某个渠道上下文中，每个发送者都拥有独立会话。 + - `global`：某个渠道上下文中的所有参与者共享同一个会话（仅在确实需要共享上下文时使用）。 - **`dmScope`**：私信的分组方式。 - `main`：所有私信共享主会话。 - - `per-peer`：按发送者 ID 跨渠道隔离。 + - `per-peer`：按发送者 id 跨渠道隔离。 - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。 - `per-account-channel-peer`：按账户 + 渠道 + 发送者隔离（推荐用于多账户）。 -- **`identityLinks`**：将规范 ID 映射到带提供商前缀的对端，用于跨渠道共享会话。 -- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。若两者都已配置，则以先到期者为准。 -- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 仍接受为 `direct` 的别名。 -- **`parentForkMaxTokens`**：创建分叉线程会话时，父会话允许的最大 `totalTokens`（默认 `100000`）。 - - 如果父会话的 `totalTokens` 高于该值，OpenClaw 会启动一个新的线程会话，而不是继承父级转录历史。 - - 设为 `0` 可禁用此保护，并始终允许父级分叉。 -- **`mainKey`**：旧版字段。运行时始终对主私聊分桶使用 `"main"`。 -- **`agentToAgent.maxPingPongTurns`**：智能体到智能体交换期间的最大往返回复轮数（整数，范围：`0`–`5`）。`0` 会禁用往返链式交互。 -- **`sendPolicy`**：可按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。首个 deny 优先。 +- **`identityLinks`**：将规范 id 映射到带提供商前缀的对端，以实现跨渠道会话共享。 +- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。当两者都已配置时，以先到期者为准。 +- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名。 +- **`parentForkMaxTokens`**：创建 fork 线程会话时，允许父会话 `totalTokens` 的最大值（默认 `100000`）。 + - 如果父会话 `totalTokens` 超过此值，OpenClaw 会启动一个新的线程会话，而不是继承父对话记录历史。 + - 设为 `0` 可禁用此保护，并始终允许父会话 fork。 +- **`mainKey`**：旧版字段。运行时始终对主私聊桶使用 `"main"`。 +- **`agentToAgent.maxPingPongTurns`**：智能体之间交换期间来回回复的最大轮数（整数，范围：`0`–`5`）。`0` 会禁用 ping-pong 链式往返。 +- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 生效。 - **`maintenance`**：会话存储清理 + 保留控制。 - - `mode`：`warn` 仅发出警告；`enforce` 会执行清理。 - - `pruneAfter`：陈旧条目的年龄截止值（默认 `30d`）。 + - `mode`：`warn` 仅发出警告；`enforce` 会实际执行清理。 + - `pruneAfter`：过期条目的年龄截止值（默认 `30d`）。 - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。 - - `rotateBytes`：当 `sessions.json` 超过该大小时轮转（默认 `10mb`）。 - - `resetArchiveRetention`：`*.reset.` 转录归档的保留期限。默认与 `pruneAfter` 相同；设为 `false` 可禁用。 - - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先移除最旧的产物/会话。 + - `rotateBytes`：当 `sessions.json` 超过此大小时轮转（默认 `10mb`）。 + - `resetArchiveRetention`：`*.reset.` 对话记录归档的保留时长。默认等于 `pruneAfter`；设为 `false` 可禁用。 + - `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先删除最旧的产物 / 会话。 - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - - `idleHours`：默认按不活动时间自动取消焦点的小时数（`0` 表示禁用；提供商可覆盖） - - `maxAgeHours`：默认硬性最大存续时间的小时数（`0` 表示禁用；提供商可覆盖） + - `idleHours`：默认按小时计算的不活跃自动取消焦点（`0` 表示禁用；提供商可覆盖） + - `maxAgeHours`：默认按小时计算的硬性最大存续时间（`0` 表示禁用；提供商可覆盖） @@ -2042,7 +2059,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ```json5 { messages: { - responsePrefix: "🦞", // or "auto" + responsePrefix: "🦞", // 或 "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -2057,7 +2074,7 @@ scripts/sandbox-browser-setup.sh # optional browser image }, }, inbound: { - debounceMs: 2000, // 0 disables + debounceMs: 2000, // 0 表示禁用 byChannel: { whatsapp: 5000, slack: 1500, @@ -2067,21 +2084,21 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -### 回复前缀 +### 响应前缀 -按渠道/账户覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 +按渠道 / 账户覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 解析顺序（越具体越优先）：账户 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生为 `[{identity.name}]`。 **模板变量：** -| 变量 | 说明 | 示例 | -| ----------------- | ---------------------- | --------------------------- | -| `{model}` | 短模型名称 | `claude-opus-4-6` | -| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | -| `{provider}` | 提供商名称 | `anthropic` | -| `{thinkingLevel}` | 当前 thinking 级别 | `high`, `low`, `off` | -| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | +| 变量 | 说明 | 示例 | +| ----------------- | ------------------ | --------------------------- | +| `{model}` | 简短模型名称 | `claude-opus-4-6` | +| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | +| `{provider}` | 提供商名称 | `anthropic` | +| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off` | +| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） | 变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。 @@ -2090,17 +2107,17 @@ scripts/sandbox-browser-setup.sh # optional browser image - 默认使用活动智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。 - 按渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。 - 解析顺序：账户 → 渠道 → `messages.ackReaction` → identity 回退。 -- 作用范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。 +- 范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。 - `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上回复后移除确认反应。 - `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。 - 在 Slack 和 Discord 上，未设置时，只要确认反应处于活动状态，就会保持状态反应启用。 - 在 Telegram 上，需要显式将其设为 `true` 才会启用生命周期状态反应。 + 在 Slack 和 Discord 上，未设置时只要确认反应处于活动状态，就会保持状态反应启用。 + 在 Telegram 上，需要显式设为 `true` 才会启用生命周期状态反应。 -### 传入去抖 +### 传入防抖 -将来自同一发送者的快速纯文本消息批处理为单个智能体轮次。媒体/附件会立即刷新。控制命令会绕过去抖。 +将同一发送者快速发送的纯文本消息合并为一次智能体轮次。媒体 / 附件会立即冲刷。控制命令会绕过防抖。 -### TTS（text-to-speech） +### TTS（文本转语音） ```json5 { @@ -2141,18 +2158,18 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可覆盖本地偏好，`/tts status` 会显示实际生效状态。 -- `summaryModel` 会覆盖用于自动摘要的 `agents.defaults.model.primary`。 +- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可覆盖本地偏好，`/tts status` 会显示生效状态。 +- `summaryModel` 会覆盖自动摘要所用的 `agents.defaults.model.primary`。 - `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需显式启用）。 - API key 会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。 -- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置，然后是 `OPENAI_TTS_BASE_URL`，最后是 `https://api.openai.com/v1`。 -- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为 OpenAI-compatible TTS 服务器，并放宽模型/voice 验证。 +- `openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置，其次是 `OPENAI_TTS_BASE_URL`，最后是 `https://api.openai.com/v1`。 +- 当 `openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为 OpenAI 兼容的 TTS 服务器，并放宽模型 / 语音校验。 --- ## Talk -Talk 模式（macOS/iOS/Android）的默认值。 +Talk 模式的默认值（macOS/iOS/Android）。 ```json5 { @@ -2177,50 +2194,50 @@ Talk 模式（macOS/iOS/Android）的默认值。 ``` - 当配置了多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的某个键。 -- 旧版平铺 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，会自动迁移到 `talk.providers.`。 +- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，并会自动迁移到 `talk.providers.`。 - Voice ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 - `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。 -- 仅当未配置 Talk API key 时，才会使用 `ELEVENLABS_API_KEY` 回退。 -- `providers.*.voiceAliases` 允许 Talk 指令使用易记名称。 -- `silenceTimeoutMs` 控制 Talk 模式在用户静默后等待多久才发送转录。未设置时会保留平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 +- 只有在未配置 Talk API key 时，才会应用 `ELEVENLABS_API_KEY` 回退。 +- `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。 +- `silenceTimeoutMs` 控制 Talk 模式在用户静默后等待多久才发送转录内容。未设置时会保留平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。 --- ## 工具 -### 工具配置 +### 工具配置文件 -`tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置基础允许列表： +`tools.profile` 会在 `tools.allow` / `tools.deny` 之前设置基础允许列表： -本地新手引导在未设置时，会将新的本地配置默认设为 `tools.profile: "coding"`（已有显式配置会保留）。 +本地新手引导在未设置时，会将新的本地配置默认设为 `tools.profile: "coding"`（已有的显式 profile 会被保留）。 -| 配置 | 包含 | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | 仅 `session_status` | -| `coding` | `group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image`、`image_generate`、`video_generate` | -| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` | -| `full` | 无限制（与未设置相同） | +| 配置文件 | 包含内容 | +| ---------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `minimal` | 仅 `session_status` | +| `coding` | `group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image`、`image_generate`、`video_generate` | +| `messaging` | `group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status` | +| `full` | 无限制（等同于未设置） | ### 工具组 -| 组 | 工具 | -| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） | -| `group:fs` | `read`、`write`、`edit`、`apply_patch` | -| `group:sessions` | `sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`sessions_yield`、`subagents`、`session_status` | -| `group:memory` | `memory_search`、`memory_get` | -| `group:web` | `web_search`、`x_search`、`web_fetch` | -| `group:ui` | `browser`、`canvas` | -| `group:automation` | `cron`、`gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`、`image_generate`、`video_generate`、`tts` | -| `group:openclaw` | 所有内置工具（不包括提供商插件） | +| 组 | 工具 | +| ------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| `group:runtime` | `exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） | +| `group:fs` | `read`、`write`、`edit`、`apply_patch` | +| `group:sessions` | `sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`sessions_yield`、`subagents`、`session_status` | +| `group:memory` | `memory_search`、`memory_get` | +| `group:web` | `web_search`、`x_search`、`web_fetch` | +| `group:ui` | `browser`、`canvas` | +| `group:automation` | `cron`、`gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`、`image_generate`、`video_generate`、`tts` | +| `group:openclaw` | 所有内置工具（不包括提供商插件） | ### `tools.allow` / `tools.deny` -全局工具允许/拒绝策略（deny 优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱隔离关闭时也会应用。 +全局工具允许 / 拒绝策略（拒绝优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱已关闭，也会生效。 ```json5 { @@ -2230,7 +2247,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.byProvider` -进一步限制特定提供商或模型的工具。顺序：基础配置 → 提供商配置 → allow/deny。 +进一步限制特定提供商或模型可用的工具。顺序：基础 profile → 提供商 profile → allow/deny。 ```json5 { @@ -2238,7 +2255,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 profile: "coding", byProvider: { "google-antigravity": { profile: "minimal" }, - "openai/gpt-5.4": { allow: ["group:fs", "sessions_list"] }, + "openai/gpt-5.5": { allow: ["group:fs", "sessions_list"] }, }, }, } @@ -2263,8 +2280,8 @@ Talk 模式（macOS/iOS/Android）的默认值。 ``` - 按智能体覆盖（`agents.list[].tools.elevated`）只能进一步收紧限制。 -- `/elevated on|off|ask|full` 会按会话保存状态；内联指令仅对单条消息生效。 -- Elevated `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认为 `gateway`，或者当 exec 目标为 `node` 时使用 `node`）。 +- `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅作用于单条消息。 +- elevated `exec` 会绕过沙箱隔离，并使用已配置的逃逸路径（默认是 `gateway`，若 exec 目标为 `node` 则使用 `node`）。 ### `tools.exec` @@ -2279,7 +2296,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 notifyOnExitEmptySuccess: false, applyPatch: { enabled: false, - allowModels: ["gpt-5.4"], + allowModels: ["gpt-5.5"], }, }, }, @@ -2288,8 +2305,8 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.loopDetection` -工具循环安全检查默认**禁用**。设置 `enabled: true` 以启用检测。 -设置可在全局 `tools.loopDetection` 中定义，并可在 `agents.list[].tools.loopDetection` 中按智能体覆盖。 +工具循环安全检查默认**关闭**。设置 `enabled: true` 可启用检测。 +这些设置可以在全局 `tools.loopDetection` 中定义，并在按智能体的 `agents.list[].tools.loopDetection` 中覆盖。 ```json5 { @@ -2310,14 +2327,14 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -- `historySize`：用于循环分析而保留的最大工具调用历史。 -- `warningThreshold`：用于发出警告的重复无进展模式阈值。 -- `criticalThreshold`：用于阻止严重循环的更高重复阈值。 -- `globalCircuitBreakerThreshold`：用于任何无进展运行的硬停止阈值。 -- `detectors.genericRepeat`：对重复调用相同工具/相同参数发出警告。 -- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告/阻止。 -- `detectors.pingPong`：对交替出现的无进展成对模式发出警告/阻止。 -- 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，验证将失败。 +- `historySize`：用于循环分析的最大工具调用历史保留数。 +- `warningThreshold`：触发警告的重复无进展模式阈值。 +- `criticalThreshold`：触发阻断严重循环的更高重复阈值。 +- `globalCircuitBreakerThreshold`：任意无进展运行的硬停止阈值。 +- `detectors.genericRepeat`：对重复的同工具 / 同参数调用发出警告。 +- `detectors.knownPollNoProgress`：对已知轮询工具（`process.poll`、`command_status` 等）的无进展情况发出警告 / 阻断。 +- `detectors.pingPong`：对交替出现的无进展成对模式发出警告 / 阻断。 +- 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，验证会失败。 ### `tools.web` @@ -2327,14 +2344,14 @@ Talk 模式（macOS/iOS/Android）的默认值。 web: { search: { enabled: true, - apiKey: "brave_api_key", // or BRAVE_API_KEY env + apiKey: "brave_api_key", // 或 BRAVE_API_KEY 环境变量 maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, - provider: "firecrawl", // optional; omit for auto-detect + provider: "firecrawl", // 可选；省略则自动检测 maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2351,7 +2368,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.media` -配置传入媒体理解（图像/音频/视频）： +配置传入媒体理解（图像 / 音频 / 视频）： ```json5 { @@ -2359,7 +2376,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: send finished async music/video directly to the channel + directSend: false, // 显式启用：将已完成的异步音乐 / 视频直接发送到渠道 }, audio: { enabled: true, @@ -2387,9 +2404,9 @@ Talk 模式（macOS/iOS/Android）的默认值。 **提供商条目**（`type: "provider"` 或省略）： -- `provider`：API 提供商 ID（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） -- `model`：模型 ID 覆盖 -- `profile` / `preferredProfile`：`auth-profiles.json` 配置选择 +- `provider`：API 提供商 id（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） +- `model`：模型 id 覆盖 +- `profile` / `preferredProfile`：`auth-profiles.json` 配置文件选择 **CLI 条目**（`type: "cli"`）： @@ -2402,13 +2419,13 @@ Talk 模式（macOS/iOS/Android）的默认值。 - `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：按条目覆盖。 - 失败时会回退到下一个条目。 -提供商身份验证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 +提供商认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 **异步完成字段：** -- `asyncCompletion.directSend`：设为 `true` 时，已完成的异步 `music_generate` - 和 `video_generate` 任务会优先尝试直接投递到渠道。默认值：`false` - （旧版请求方会话唤醒/模型投递路径）。 +- `asyncCompletion.directSend`：当为 `true` 时，已完成的异步 `music_generate` + 和 `video_generate` 任务会优先尝试直接传递到渠道。默认值：`false` + （旧版请求方会话唤醒 / 模型传递路径）。 @@ -2427,7 +2444,7 @@ Talk 模式（macOS/iOS/Android）的默认值。 ### `tools.sessions` -控制会话工具（`sessions_list`、`sessions_history`、`sessions_send`）可定位哪些会话。 +控制会话工具（`sessions_list`、`sessions_history`、`sessions_send`）可以将哪些会话作为目标。 默认值：`tree`（当前会话 + 由其生成的会话，例如子智能体）。 @@ -2442,13 +2459,13 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -注意： +说明： - `self`：仅当前会话键。 - `tree`：当前会话 + 由当前会话生成的会话（子智能体）。 -- `agent`：属于当前智能体 ID 的任意会话（如果你在相同智能体 ID 下运行按发送者隔离的会话，也可能包含其他用户）。 -- `all`：任意会话。跨智能体定位仍要求 `tools.agentToAgent`。 -- 沙箱钳制：当当前会话处于沙箱隔离中，且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 +- `agent`：属于当前智能体 id 的任意会话（如果你在同一个智能体 id 下运行按发送者隔离的会话，也可能包含其他用户）。 +- `all`：任意会话。跨智能体定向仍需要 `tools.agentToAgent`。 +- 沙箱钳制：当当前会话处于沙箱隔离状态且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 ### `tools.sessions_spawn` @@ -2459,47 +2476,47 @@ Talk 模式（macOS/iOS/Android）的默认值。 tools: { sessions_spawn: { attachments: { - enabled: false, // opt-in: set true to allow inline file attachments - maxTotalBytes: 5242880, // 5 MB total across all files + enabled: false, // 显式启用：设为 true 以允许内联文件附件 + maxTotalBytes: 5242880, // 所有文件总计 5 MB maxFiles: 50, - maxFileBytes: 1048576, // 1 MB per file - retainOnSessionKeep: false, // keep attachments when cleanup="keep" + maxFileBytes: 1048576, // 每个文件 1 MB + retainOnSessionKeep: false, // 当 cleanup="keep" 时保留附件 }, }, }, } ``` -注意： +说明： -- 仅 `runtime: "subagent"` 支持附件。ACP 运行时会拒绝它们。 -- 文件会被实体化到子工作区中的 `.openclaw/attachments//`，并附带一个 `.manifest.json`。 -- 附件内容会自动从转录持久化中脱敏。 -- Base64 输入会使用严格的字母表/填充检查，以及解码前大小保护进行验证。 -- 目录权限为 `0700`，文件权限为 `0600`。 -- 清理由 `cleanup` 策略控制：`delete` 总是移除附件；仅当 `retainOnSessionKeep: true` 时，`keep` 才会保留它们。 +- 附件仅支持 `runtime: "subagent"`。ACP 运行时会拒绝它们。 +- 文件会实体化到子工作区中的 `.openclaw/attachments//`，并附带一个 `.manifest.json`。 +- 附件内容会自动从对话记录持久化中脱敏。 +- Base64 输入会使用严格的字母表 / 填充检查，以及解码前大小保护进行验证。 +- 文件权限：目录为 `0700`，文件为 `0600`。 +- 清理由 `cleanup` 策略控制：`delete` 总是会移除附件；只有在 `retainOnSessionKeep: true` 时，`keep` 才会保留附件。 ### `tools.experimental` -实验性内置工具标志。默认关闭，除非严格智能体式 GPT-5 自动启用规则生效。 +实验性内置工具标志。默认关闭，除非严格智能体 GPT-5 自动启用规则生效。 ```json5 { tools: { experimental: { - planTool: true, // enable experimental update_plan + planTool: true, // 启用实验性的 update_plan }, }, } ``` -注意： +说明： - `planTool`：为非平凡的多步骤工作跟踪启用结构化 `update_plan` 工具。 -- 默认值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或按智能体覆盖）在 OpenAI 或 OpenAI Codex GPT-5 家族运行中被设置为 `"strict-agentic"`。设为 `true` 可在该范围之外强制启用该工具，设为 `false` 则即使在 strict-agentic GPT-5 运行中也保持关闭。 -- 启用后，系统提示还会添加使用指南，使模型仅在实质性工作中使用它，并且始终最多只保留一个 `in_progress` 步骤。 +- 默认值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或按智能体覆盖）对某个 OpenAI 或 OpenAI Codex GPT-5 家族运行设置为 `"strict-agentic"`。设为 `true` 可在该范围之外强制开启该工具，设为 `false` 则即使在 strict-agentic GPT-5 运行中也保持关闭。 +- 启用后，系统提示还会添加使用说明，以便模型仅在实质性工作中使用它，并且最多只保持一个 `in_progress` 步骤。 ### `agents.defaults.subagents` @@ -2519,21 +2536,21 @@ Talk 模式（macOS/iOS/Android）的默认值。 } ``` -- `model`：生成的子智能体的默认模型。如果省略，子智能体会继承调用方模型。 -- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 目标智能体 ID 的默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。 -- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 的默认超时秒数。`0` 表示无超时。 +- `model`：生成的子智能体的默认模型。如果省略，子智能体会继承调用方的模型。 +- `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 默认可选的目标智能体 id 允许列表（`["*"]` = 任意；默认：仅同一智能体）。 +- `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 使用的默认超时（秒）。`0` 表示无超时。 - 按子智能体工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 --- ## 自定义提供商和 base URL -OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义提供商。 +OpenClaw 使用内置模型目录。可通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义提供商。 ```json5 { models: { - mode: "merge", // merge (default) | replace + mode: "merge", // merge（默认）| replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -2557,49 +2574,49 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -- 使用 `authHeader: true` + `headers` 以满足自定义身份验证需求。 -- 使用 `OPENCLAW_AGENT_DIR`（或旧版环境变量别名 `PI_CODING_AGENT_DIR`）覆盖智能体配置根目录。 -- 对于匹配的提供商 ID，合并优先级如下： +- 对于自定义认证需求，请使用 `authHeader: true` + `headers`。 +- 使用 `OPENCLAW_AGENT_DIR` 覆盖智能体配置根目录（或使用旧版环境变量别名 `PI_CODING_AGENT_DIR`）。 +- 对于匹配的 provider ID，合并优先级如下： - 非空的智能体 `models.json` `baseUrl` 值优先。 - - 非空的智能体 `apiKey` 值仅在该提供商在当前配置/auth-profile 上下文中不是 SecretRef 管理时优先。 - - 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化已解析的 secret。 - - 由 SecretRef 管理的提供商 header 值会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）。 - - 空的或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 - - 匹配模型的 `contextWindow`/`maxTokens` 会在显式配置值与隐式目录值之间取更高者。 - - 匹配模型的 `contextTokens` 会在存在时保留显式运行时上限；当你想限制有效上下文而不改变模型原生元数据时，请使用它。 - - 当你希望配置完全重写 `models.json` 时，使用 `models.mode: "replace"`。 - - 标记持久化以源为准：标记写入自活动源配置快照（解析前），而不是已解析的运行时 secret 值。 + - 非空的智能体 `apiKey` 值仅在当前 config/auth-profile 上下文中该提供商**不是** SecretRef 管理时优先。 + - 由 SecretRef 管理的提供商 `apiKey` 值会根据来源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件 / exec 引用使用 `secretref-managed`），而不是持久化已解析的 secrets。 + - 由 SecretRef 管理的提供商 header 值会根据来源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件 / exec 引用使用 `secretref-managed`）。 + - 空的或缺失的智能体 `apiKey` / `baseUrl` 会回退到配置中的 `models.providers`。 + - 匹配模型的 `contextWindow` / `maxTokens` 会在显式配置值与隐式目录值之间取较高者。 + - 匹配模型的 `contextTokens` 会在存在显式运行时上限时保留它；当你想限制有效上下文而不更改模型原生元数据时请使用它。 + - 如果你希望配置完全重写 `models.json`，请使用 `models.mode: "replace"`。 + - 标记持久化是来源权威的：标记来自活动来源配置快照（解析前）写入，而不是来自已解析的运行时 secret 值。 ### 提供商字段详情 - `models.mode`：提供商目录行为（`merge` 或 `replace`）。 -- `models.providers`：按提供商 ID 键控的自定义提供商映射。 - - 安全编辑：使用 `openclaw config set models.providers. '' --strict-json --merge` 或 `openclaw config set models.providers..models '' --strict-json --merge` 进行追加更新。除非你传入 `--replace`，否则 `config set` 会拒绝破坏性替换。 +- `models.providers`：以 provider id 为键的自定义提供商映射。 + - 安全编辑：使用 `openclaw config set models.providers. '' --strict-json --merge` 或 `openclaw config set models.providers..models '' --strict-json --merge` 进行增量更新。除非传入 `--replace`，否则 `config set` 会拒绝破坏性替换。 - `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。 -- `models.providers.*.apiKey`：提供商凭证（优先使用 SecretRef/环境变量替换）。 -- `models.providers.*.auth`：身份验证策略（`api-key`、`token`、`oauth`、`aws-sdk`）。 -- `models.providers.*.injectNumCtxForOpenAICompat`：对于 Ollama + `openai-completions`，向请求注入 `options.num_ctx`（默认：`true`）。 +- `models.providers.*.apiKey`：提供商凭证（优先使用 SecretRef / 环境变量替换）。 +- `models.providers.*.auth`：认证策略（`api-key`、`token`、`oauth`、`aws-sdk`）。 +- `models.providers.*.injectNumCtxForOpenAICompat`：对于 Ollama + `openai-completions`，将 `options.num_ctx` 注入请求中（默认：`true`）。 - `models.providers.*.authHeader`：在需要时强制通过 `Authorization` header 传输凭证。 - `models.providers.*.baseUrl`：上游 API base URL。 -- `models.providers.*.headers`：用于代理/租户路由的额外静态 headers。 +- `models.providers.*.headers`：用于代理 / 租户路由的额外静态 headers。 - `models.providers.*.request`：模型提供商 HTTP 请求的传输覆盖。 - - `request.headers`：额外 headers（与提供商默认值合并）。值接受 SecretRef。 - - `request.auth`：身份验证策略覆盖。模式：`"provider-default"`（使用提供商内置身份验证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value` 和可选 `prefix`）。 - - `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（配合 `url`）。两种模式都接受可选的 `tls` 子对象。 - - `request.tls`：直连时的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（全部接受 SecretRef）、`serverName`、`insecureSkipVerify`。 - - `request.allowPrivateNetwork`：设为 `true` 时，当 DNS 将 `baseUrl` 解析为私有、CGNAT 或类似范围时，允许通过提供商 HTTP 抓取保护访问 HTTPS（这是面向受信任自托管 OpenAI-compatible 端点的 operator 显式启用项）。WebSocket 对 headers/TLS 使用相同的 `request`，但不使用该抓取 SSRF 门控。默认值 `false`。 + - `request.headers`：额外 headers（与提供商默认值合并）。值支持 SecretRef。 + - `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用提供商内置认证）、`"authorization-bearer"`（配合 `token`）、`"header"`（配合 `headerName`、`value`，以及可选的 `prefix`）。 + - `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY` / `HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（配合 `url`）。两种模式都接受可选的 `tls` 子对象。 + - `request.tls`：直连时的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（都支持 SecretRef）、`serverName`、`insecureSkipVerify`。 + - `request.allowPrivateNetwork`：设为 `true` 时，当 DNS 将 `baseUrl` 解析到私有、CGNAT 或类似范围时，允许通过提供商 HTTP 抓取保护访问 HTTPS（这是面向受信任自托管 OpenAI 兼容端点的 operator 显式启用项）。WebSocket 对 headers/TLS 也使用相同的 `request`，但不使用该抓取 SSRF 门控。默认值 `false`。 - `models.providers.*.models`：显式提供商模型目录条目。 - `models.providers.*.models.*.contextWindow`：模型原生上下文窗口元数据。 -- `models.providers.*.models.*.contextTokens`：可选的运行时上下文上限。当你希望有效上下文预算小于模型原生 `contextWindow` 时使用它。 -- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且非空、非原生的 `baseUrl`（主机不是 `api.openai.com`），OpenClaw 会在运行时强制将其设为 `false`。空的/省略的 `baseUrl` 会保留默认 OpenAI 行为。 -- `models.providers.*.models.*.compat.requiresStringContent`：针对仅支持字符串的 OpenAI-compatible chat 端点的可选兼容性提示。设为 `true` 时，OpenClaw 会在发送请求前将纯文本 `messages[].content` 数组展平为普通字符串。 -- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根。 -- `plugins.entries.amazon-bedrock.config.discovery.enabled`：开启/关闭隐式发现。 +- `models.providers.*.models.*.contextTokens`：可选运行时上下文上限。当你希望有效上下文预算小于模型原生 `contextWindow` 时，请使用它。 +- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选兼容性提示。对于 `api: "openai-completions"` 且存在非空、非原生的 `baseUrl`（主机不是 `api.openai.com`），OpenClaw 会在运行时强制将其设为 `false`。空的 / 省略的 `baseUrl` 会保留默认 OpenAI 行为。 +- `models.providers.*.models.*.compat.requiresStringContent`：面向仅支持字符串的 OpenAI 兼容聊天端点的可选兼容性提示。当为 `true` 时，OpenClaw 会在发送请求前，将纯文本 `messages[].content` 数组压平成普通字符串。 +- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根节点。 +- `plugins.entries.amazon-bedrock.config.discovery.enabled`：打开 / 关闭隐式发现。 - `plugins.entries.amazon-bedrock.config.discovery.region`：用于发现的 AWS 区域。 -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：用于定向发现的可选提供商 ID 过滤器。 +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：可选的提供商 id 过滤器，用于定向发现。 - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`：发现刷新的轮询间隔。 -- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：发现到的模型使用的回退上下文窗口。 -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：发现到的模型使用的回退最大输出 token 数。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：已发现模型的回退上下文窗口。 +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：已发现模型的回退最大输出 token 数。 ### 提供商示例 @@ -2637,7 +2654,7 @@ OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~ } ``` -Cerebras 使用 `cerebras/zai-glm-4.7`；Z.AI 直连使用 `zai/glm-4.7`。 +Cerebras 请使用 `cerebras/zai-glm-4.7`；Z.AI 直连请使用 `zai/glm-4.7`。 @@ -2674,7 +2691,7 @@ Cerebras 使用 `cerebras/zai-glm-4.7`；Z.AI 直连使用 `zai/glm-4.7`。 设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 都是可接受的别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。 - 通用端点：`https://api.z.ai/api/paas/v4` -- Coding 端点（默认）：`https://api.z.ai/api/coding/paas/v4` +- 编码端点（默认）：`https://api.z.ai/api/coding/paas/v4` - 对于通用端点，请定义一个带 base URL 覆盖的自定义提供商。 @@ -2714,11 +2731,11 @@ Cerebras 使用 `cerebras/zai-glm-4.7`；Z.AI 直连使用 `zai/glm-4.7`。 } ``` -中国端点使用：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。 +中国区端点请使用：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。 原生 Moonshot 端点会在共享的 `openai-completions` 传输上声明流式使用兼容性，而 OpenClaw 会根据端点能力 -而不仅仅是内置提供商 ID 来处理这一点。 +而不仅仅是内置提供商 id 来识别这一点。 @@ -2736,11 +2753,11 @@ Cerebras 使用 `cerebras/zai-glm-4.7`；Z.AI 直连使用 `zai/glm-4.7`。 } ``` -与 Anthropic-compatible 兼容，属于内置提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 +内置的 Anthropic 兼容提供商。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 - + ```json5 { @@ -2775,7 +2792,7 @@ Cerebras 使用 `cerebras/zai-glm-4.7`；Z.AI 直连使用 `zai/glm-4.7`。 } ``` -Base URL 不应包含 `/v1`（Anthropic 客户端会自行附加）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。 +Base URL 不应包含 `/v1`（Anthropic 客户端会自行追加它）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。 @@ -2819,8 +2836,8 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行附加）。快捷方 `openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。 模型目录默认仅包含 M2.7。 -在 Anthropic-compatible 流式路径上，除非你显式自行设置 `thinking`， -否则 OpenClaw 默认会禁用 MiniMax thinking。`/fast on` 或 +在 Anthropic 兼容的流式路径上，除非你显式设置 `thinking`，否则 OpenClaw +默认会禁用 MiniMax thinking。`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 @@ -2828,7 +2845,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行附加）。快捷方 -请参阅 [本地模型](/zh-CN/gateway/local-models)。简而言之：在严肃硬件上通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。 +参见 [本地模型](/zh-CN/gateway/local-models)。简而言之：在性能充足的硬件上，通过 LM Studio Responses API 运行大型本地模型；同时保留已合并的托管模型作为回退。 @@ -2849,7 +2866,7 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行附加）。快捷方 }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // 或明文字符串 env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2859,13 +2876,14 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行附加）。快捷方 } ``` -- `allowBundled`：仅适用于内置 Skills 的可选允许列表（不影响托管/工作区 Skills）。 +- `allowBundled`：仅适用于内置 Skills 的可选允许列表（托管 / 工作区 Skills 不受影响）。 - `load.extraDirs`：额外的共享 Skills 根目录（优先级最低）。 -- `install.preferBrew`：设为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器，然后才回退到其他安装器类型。 +- `install.preferBrew`：为 true 时，如果 + `brew` 可用，则优先使用 Homebrew 安装器，然后才回退到其他安装器类型。 - `install.nodeManager`：用于 `metadata.openclaw.install` - 规范的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 -- `entries..enabled: false`：即使某个 Skill 已内置/已安装，也会禁用它。 -- `entries..apiKey`：为声明了主环境变量的 Skills 提供的便捷字段（明文字符串或 SecretRef 对象）。 + 规范的 node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。 +- `entries..enabled: false`：即使某个技能已内置 / 已安装，也会将其禁用。 +- `entries..apiKey`：为声明了主环境变量的技能提供的便捷字段（明文字符串或 SecretRef 对象）。 --- @@ -2894,42 +2912,42 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行附加）。快捷方 ``` - 从 `~/.openclaw/extensions`、`/.openclaw/extensions` 以及 `plugins.load.paths` 加载。 -- 设备发现接受原生 OpenClaw 插件，以及兼容的 Codex bundles 和 Claude bundles，包括无 manifest 的 Claude 默认布局 bundles。 -- **配置变更需要重启 Gateway 网关。** +- 设备发现接受原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。 +- **配置更改需要重启 Gateway 网关。** - `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。 -- `plugins.entries..apiKey`：插件级 API key 便捷字段（插件支持时）。 +- `plugins.entries..apiKey`：插件级 API key 便捷字段（在插件支持时）。 - `plugins.entries..env`：插件作用域环境变量映射。 -- `plugins.entries..hooks.allowPromptInjection`：设为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hooks，以及受支持的 bundle 提供的 hook 目录。 -- `plugins.entries..subagent.allowModelOverride`：显式信任该插件可为后台子智能体运行请求按次 `provider` 和 `model` 覆盖。 -- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖可使用的规范 `provider/model` 目标的可选允许列表。仅当你确实希望允许任意模型时，才使用 `"*"`。 -- `plugins.entries..config`：插件定义的配置对象（当可用时，会由原生 OpenClaw 插件 schema 验证）。 -- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web 抓取提供商设置。 - - `apiKey`：Firecrawl API key（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。 +- `plugins.entries..hooks.allowPromptInjection`：当为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会变更提示的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件 hooks 以及受支持的、由 bundle 提供的 hook 目录。 +- `plugins.entries..subagent.allowModelOverride`：显式信任此插件，让它可以为后台子智能体运行请求按次的 `provider` 和 `model` 覆盖。 +- `plugins.entries..subagent.allowedModels`：受信任子智能体覆盖可使用的规范 `provider/model` 目标可选允许列表。仅当你明确希望允许任意模型时才使用 `"*"`。 +- `plugins.entries..config`：插件定义的配置对象（若可用，则会由原生 OpenClaw 插件 schema 验证）。 +- `plugins.entries.firecrawl.config.webFetch`：Firecrawl Web 抓取提供商设置。 + - `apiKey`：Firecrawl API key（支持 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。 - `baseUrl`：Firecrawl API base URL（默认：`https://api.firecrawl.dev`）。 - - `onlyMainContent`：仅提取页面主要内容（默认：`true`）。 - - `maxAgeMs`：最大缓存年龄（毫秒）（默认：`172800000` / 2 天）。 + - `onlyMainContent`：仅提取页面主体内容（默认：`true`）。 + - `maxAgeMs`：缓存最大年龄（毫秒）（默认：`172800000` / 2 天）。 - `timeoutSeconds`：抓取请求超时秒数（默认：`60`）。 -- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web 搜索）设置。 +- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok Web 搜索）设置。 - `enabled`：启用 X Search 提供商。 - `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。 -- `plugins.entries.memory-core.config.dreaming`：memory Dreaming 设置。阶段和阈值请参见 [Dreaming](/zh-CN/concepts/dreaming)。 +- `plugins.entries.memory-core.config.dreaming`：内存 Dreaming 设置。阶段和阈值请参见 [Dreaming](/zh-CN/concepts/dreaming)。 - `enabled`：Dreaming 主开关（默认 `false`）。 - `frequency`：每次完整 Dreaming 扫描的 cron 频率（默认 `"0 3 * * *"`）。 - 阶段策略和阈值属于实现细节（不是面向用户的配置键）。 -- 完整的 memory 配置位于 [Memory 配置参考](/zh-CN/reference/memory-config)： +- 完整的内存配置位于 [内存配置参考](/zh-CN/reference/memory-config)： - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- 已启用的 Claude bundle 插件也可以从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为净化后的智能体设置应用，而不是原始 OpenClaw 配置补丁。 -- `plugins.slots.memory`：选择活动 memory 插件 ID，或使用 `"none"` 禁用 memory 插件。 -- `plugins.slots.contextEngine`：选择活动上下文引擎插件 ID；默认值为 `"legacy"`，除非你安装并选择了其他引擎。 +- 已启用的 Claude bundle 插件也可以从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将这些值作为经过净化的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。 +- `plugins.slots.memory`：选择活动的 memory 插件 id，或设为 `"none"` 以禁用内存插件。 +- `plugins.slots.contextEngine`：选择活动的上下文引擎插件 id；默认值为 `"legacy"`，除非你安装并选择了其他引擎。 - `plugins.installs`：由 CLI 管理的安装元数据，供 `openclaw plugins update` 使用。 - 包括 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。 - - 将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。 + - 请将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。 -请参见 [插件](/zh-CN/tools/plugin)。 +参见 [插件](/zh-CN/tools/plugin)。 --- @@ -2942,8 +2960,8 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行附加）。快捷方 evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access - // allowPrivateNetwork: true, // legacy alias + // dangerouslyAllowPrivateNetwork: true, // 仅在信任私有网络访问时显式启用 + // allowPrivateNetwork: true, // 旧版别名 // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, @@ -2970,29 +2988,29 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行附加）。快捷方 ``` - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。 -- 未设置时，`ssrfPolicy.dangerouslyAllowPrivateNetwork` 为禁用状态，因此浏览器导航默认保持严格模式。 -- 仅当你明确信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 -- 在严格模式下，远程 CDP 配置端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间同样受私有网络阻止规则约束。 +- 未设置时，`ssrfPolicy.dangerouslyAllowPrivateNetwork` 为禁用状态，因此默认会对浏览器导航保持严格限制。 +- 仅当你有意信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。 +- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性 / 设备发现检查期间也会受到相同的私有网络阻止。 - `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 -- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 添加显式例外。 -- 远程配置为仅附加模式（禁用 start/stop/reset）。 +- 在严格模式下，请使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 作为显式例外。 +- 远程配置文件为仅附加模式（禁用 start/stop/reset）。 - `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。 - 如果你希望 OpenClaw 发现 `/json/version`，请使用 HTTP(S)； - 当提供商直接给出 DevTools WebSocket URL 时，请使用 WS(S)。 -- `existing-session` 配置使用 Chrome MCP 而不是 CDP，并且可以附加到 - 所选主机上，或通过已连接的浏览器节点附加。 -- `existing-session` 配置可以设置 `userDataDir`，以定位特定的 - 基于 Chromium 的浏览器配置，例如 Brave 或 Edge。 -- `existing-session` 配置保留当前的 Chrome MCP 路由限制： - 使用 snapshot/ref 驱动的操作而不是 CSS 选择器定位、单文件上传 + 当你希望 OpenClaw 发现 `/json/version` 时，请使用 HTTP(S)； + 当你的提供商直接给出 DevTools WebSocket URL 时，请使用 WS(S)。 +- `existing-session` 配置文件使用 Chrome MCP 而不是 CDP，并且可以附加到 + 选定主机上，或通过已连接的浏览器节点进行附加。 +- `existing-session` 配置文件可以设置 `userDataDir`，以定位特定的 + Chromium 系浏览器配置文件，例如 Brave 或 Edge。 +- `existing-session` 配置文件保持当前的 Chrome MCP 路由限制： + 使用 snapshot/ref 驱动的操作而不是 CSS 选择器定向、单文件上传 hooks、不支持对话框超时覆盖、不支持 `wait --load networkidle`，以及不支持 `responsebody`、PDF 导出、下载拦截或批量操作。 -- 本地托管的 `openclaw` 配置会自动分配 `cdpPort` 和 `cdpUrl`；仅在 - 远程 CDP 场景下才需要显式设置 `cdpUrl`。 -- 自动检测顺序：默认浏览器（若为基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。 -- Control 服务：仅 loopback（端口由 `gateway.port` 派生，默认 `18791`）。 -- `extraArgs` 会将额外启动标志附加到本地 Chromium 启动参数中（例如 - `--disable-gpu`、窗口尺寸，或调试标志）。 +- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；只有 + 远程 CDP 才需要显式设置 `cdpUrl`。 +- 自动检测顺序：若默认浏览器为 Chromium 系则优先使用默认浏览器 → Chrome → Brave → Edge → Chromium → Chrome Canary。 +- 控制服务：仅限 local loopback（端口派生自 `gateway.port`，默认 `18791`）。 +- `extraArgs` 会为本地 Chromium 启动追加额外启动标志（例如 + `--disable-gpu`、窗口大小设置或调试标志）。 --- @@ -3004,13 +3022,13 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行附加）。快捷方 seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji, short text, image URL, or data URI + avatar: "CB", // emoji、短文本、图像 URL 或 data URI }, }, } ``` -- `seamColor`：原生应用 UI 外框的强调色（Talk 模式气泡着色等）。 +- `seamColor`：原生应用 UI 外壳的强调色（Talk 模式气泡着色等）。 - `assistant`：Control UI 身份覆盖。会回退到活动智能体身份。 --- @@ -3026,8 +3044,8 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行附加）。快捷方 auth: { mode: "token", // none | token | password | trusted-proxy token: "your-token", - // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth + // password: "your-password", // 或 OPENCLAW_GATEWAY_PASSWORD + // trustedProxy: { userHeader: "x-forwarded-user" }, // 用于 mode=trusted-proxy；参见 /gateway/trusted-proxy-auth allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -3045,9 +3063,9 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行附加）。快捷方 basePath: "/openclaw", // root: "dist/control-ui", // embedSandbox: "scripts", // strict | scripts | trusted - // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs - // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI - // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode + // allowExternalEmbedUrls: false, // 危险：允许绝对外部 http(s) 嵌入 URL + // allowedOrigins: ["https://control.example.com"], // 非 local loopback Control UI 必需 + // dangerouslyAllowHostHeaderOriginFallback: false, // 危险的 Host-header origin 回退模式 // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -3058,12 +3076,12 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行附加）。快捷方 // password: "your-password", }, trustedProxies: ["10.0.0.1"], - // Optional. Default false. + // 可选。默认 false。 allowRealIpFallback: false, tools: { - // Additional /tools/invoke HTTP denies + // 额外的 /tools/invoke HTTP 拒绝列表 deny: ["browser"], - // Remove tools from the default HTTP deny list + // 从默认 HTTP 拒绝列表中移除工具 allow: ["gateway"], }, push: { @@ -3081,63 +3099,63 @@ Base URL 不应包含 `/v1`（Anthropic 客户端会自行附加）。快捷方 - `mode`：`local`（运行 gateway）或 `remote`（连接到远程 gateway）。除非为 `local`，否则 Gateway 网关会拒绝启动。 -- `port`：WS + HTTP 共用的单一多路复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 +- `port`：用于 WS + HTTP 的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。 - `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。 -- **旧版 bind 别名**：在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 -- **Docker 注意事项**：默认的 `loopback` 绑定会在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 gateway 不可达。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 并配合 `customBindHost: "0.0.0.0"`）以监听所有接口。 -- **身份验证**：默认必需。非 loopback 绑定要求 gateway 身份验证。实际中这意味着共享 token/password，或使用带 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成 token。 -- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式将 `gateway.auth.mode` 设为 `token` 或 `password`。当两者都已配置且未设置 mode 时，启动及服务安装/修复流程都会失败。 -- `gateway.auth.mode: "none"`：显式无身份验证模式。仅用于受信任的本地 local loopback 设置；新手引导提示中不会提供该选项。 -- `gateway.auth.mode: "trusted-proxy"`：将身份验证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份头（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求**非 loopback** 的代理来源；同主机的 loopback 反向代理不满足 trusted-proxy 身份验证要求。 -- `gateway.auth.allowTailscale`：设为 `true` 时，Tailscale Serve 身份头可以满足 Control UI/WebSocket 身份验证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 头身份验证；它们仍遵循 gateway 的普通 HTTP 身份验证模式。此无 token 流程假设 gateway 主机是受信任的。当 `tailscale.mode = "serve"` 时，默认值为 `true`。 -- `gateway.auth.rateLimit`：可选的身份验证失败限流器。按客户端 IP 和身份验证作用域生效（共享 secret 和设备 token 会独立跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。 - - 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败尝试会在写入失败记录之前串行化。因此，来自同一客户端的并发错误尝试，可能会在第二个请求时触发限流器，而不是两个请求都像普通不匹配那样同时通过。 - - `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；如果你有意也希望对 localhost 流量进行限流（例如测试设置或严格代理部署），请设为 `false`。 -- 来自浏览器源的 WS 身份验证尝试始终会启用限流，并禁用 loopback 豁免（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。 +- **旧版 bind 别名**：请在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。 +- **Docker 说明**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 gateway 不可访问。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 并配合 `customBindHost: "0.0.0.0"`）以监听所有接口。 +- **认证**：默认必需。非 loopback 绑定要求 gateway 认证。实践中，这意味着共享 token/password，或使用带有 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成 token。 +- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请显式设置 `gateway.auth.mode` 为 `token` 或 `password`。如果两者都已配置但未设置 mode，启动以及服务安装 / 修复流程都会失败。 +- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的本地 local loopback 设置；新手引导提示中不会主动提供此选项。 +- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份 headers（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求**非 loopback** 的代理来源；同主机的 loopback 反向代理不能满足 trusted-proxy 认证要求。 +- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份 headers 可以满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale header 认证；它们仍遵循 gateway 的正常 HTTP 认证模式。当 `tailscale.mode = "serve"` 时，默认值为 `true`。这种无 token 流程假定 gateway 主机是受信任的。 +- `gateway.auth.rateLimit`：可选的认证失败限制器。按客户端 IP 和认证作用域分别应用（共享 secret 和设备 token 会独立跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。 + - 在异步 Tailscale Serve Control UI 路径上，对于相同 `{scope, clientIp}` 的失败尝试，会在写入失败记录之前进行串行化处理。因此，同一客户端并发发起的错误尝试，可能会在第二个请求上触发限制器，而不是两个都以普通不匹配的形式同时通过。 + - `gateway.auth.rateLimit.exemptLoopback` 默认值为 `true`；如果你有意也想对 localhost 流量进行速率限制（例如测试环境或严格代理部署），请设为 `false`。 +- 来自浏览器源的 WS 认证尝试始终会启用节流，并禁用 loopback 例外（作为对基于浏览器的 localhost 暴力破解的纵深防御）。 - 在 loopback 上，这些来自浏览器源的锁定会按规范化后的 `Origin` - 值隔离，因此来自某个 localhost origin 的重复失败不会自动 + 值分别隔离，因此来自一个 localhost origin 的重复失败不会自动 锁定另一个 origin。 -- `tailscale.mode`：`serve`（仅 tailnet，loopback 绑定）或 `funnel`（公开，需要身份验证）。 -- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器来源允许列表。当预期浏览器客户端来自非 loopback 来源时，这是必需的。 -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host-header 来源策略的部署启用 Host-header 来源回退。 -- `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须为 `ws://` 或 `wss://`。 -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧紧急覆盖，允许对受信任私有网络 IP 使用明文 `ws://`；默认仍仅允许 loopback 使用明文。 -- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身并不配置 gateway 身份验证。 -- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 构建在将基于 relay 的注册发布到 gateway 后，用于外部 APNs relay 的基础 HTTPS URL。此 URL 必须与编译进 iOS 构建中的 relay URL 匹配。 +- `tailscale.mode`：`serve`（仅 tailnet，loopback 绑定）或 `funnel`（公网，需要认证）。 +- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器 origin 允许列表。当预期浏览器客户端来自非 loopback origin 时为必需。 +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，允许使用 Host-header origin 回退，适用于有意依赖 Host-header origin 策略的部署。 +- `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。 +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端侧紧急破窗覆盖，允许对受信任私有网络 IP 使用明文 `ws://`；默认仍仅允许对 loopback 使用明文。 +- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 gateway 认证。 +- `gateway.push.apns.relay.baseUrl`：官方 / TestFlight iOS 构建在向 gateway 发布基于 relay 的注册后，供外部 APNs relay 使用的基础 HTTPS URL。此 URL 必须与编译进 iOS 构建中的 relay URL 一致。 - `gateway.push.apns.relay.timeoutMs`：gateway 到 relay 的发送超时（毫秒）。默认值为 `10000`。 -- 基于 relay 的注册会委托给特定的 gateway 身份。配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并将一个按注册范围的发送授权转发给 gateway。另一个 gateway 无法复用该已存储注册。 -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：对上述 relay 配置的临时环境变量覆盖。 -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅用于开发环境的逃生口，用于 loopback HTTP relay URL。生产 relay URL 应保持为 HTTPS。 +- 基于 relay 的注册会委托给特定的 gateway 身份。配对的 iOS 应用会获取 `gateway.identity.get`，将该身份包含在 relay 注册中，并向 gateway 转发一个作用域限定在该注册上的发送授权。另一个 gateway 无法复用该已存储注册。 +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：上述 relay 配置的临时环境变量覆盖。 +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅用于开发环境的逃生舱，允许使用 loopback HTTP relay URL。生产 relay URL 应保持为 HTTPS。 - `gateway.channelHealthCheckMinutes`：渠道健康监控间隔（分钟）。设为 `0` 可全局禁用健康监控重启。默认值：`5`。 -- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 -- `gateway.channelMaxRestartsPerHour`：每个渠道/账户在滚动一小时内的最大健康监控重启次数。默认值：`10`。 -- `channels..healthMonitor.enabled`：在保留全局监控启用的情况下，按渠道退出健康监控重启。 +- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值（分钟）。请保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。 +- `gateway.channelMaxRestartsPerHour`：滚动一小时内每个渠道 / 账户允许的最大健康监控重启次数。默认值：`10`。 +- `channels..healthMonitor.enabled`：在保持全局监控启用的同时，按渠道选择退出健康监控重启。 - `channels..accounts..healthMonitor.enabled`：多账户渠道的按账户覆盖。设置后，其优先级高于渠道级覆盖。 -- 仅当 `gateway.auth.*` 未设置时，本地 gateway 调用路径才可将 `gateway.remote.*` 用作回退。 -- 如果 `gateway.auth.token` / `gateway.auth.password` 是通过 SecretRef 显式配置且未解析，则解析会失败即关闭（不会由远程回退来掩盖）。 -- `trustedProxies`：终止 TLS 或注入转发客户端头的反向代理 IP。只列出你控制的代理。loopback 条目仍适用于同主机代理/本地检测设置（例如 Tailscale Serve 或本地反向代理），但它们**不会**让 loopback 请求符合 `gateway.auth.mode: "trusted-proxy"` 的资格。 -- `allowRealIpFallback`：设为 `true` 时，如果缺少 `X-Forwarded-For`，gateway 会接受 `X-Real-IP`。默认 `false`，以保持失败即关闭行为。 -- `gateway.tools.deny`：为 HTTP `POST /tools/invoke` 额外阻止的工具名（会扩展默认拒绝列表）。 +- 本地 gateway 调用路径仅会在 `gateway.auth.*` 未设置时，才使用 `gateway.remote.*` 作为回退。 +- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 但未解析成功，解析会以默认拒绝方式失败（不会使用远程回退进行掩盖）。 +- `trustedProxies`：用于终止 TLS 或注入转发客户端 headers 的反向代理 IP。只列出你控制的代理。loopback 条目对于同主机代理 / 本地检测设置（例如 Tailscale Serve 或本地反向代理）仍然有效，但它们**不会**使 loopback 请求符合 `gateway.auth.mode: "trusted-proxy"` 的资格。 +- `allowRealIpFallback`：为 `true` 时，当缺少 `X-Forwarded-For` 时，gateway 会接受 `X-Real-IP`。默认值为 `false`，以保持默认拒绝行为。 +- `gateway.tools.deny`：针对 HTTP `POST /tools/invoke` 的额外被阻止工具名（扩展默认拒绝列表）。 - `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名。 -### OpenAI-compatible 端点 +### OpenAI 兼容端点 -- Chat Completions：默认禁用。使用 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。 +- Chat Completions：默认禁用。通过 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。 - Responses API：`gateway.http.endpoints.responses.enabled`。 - Responses URL 输入加固： - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - 空允许列表会被视为未设置；使用 `gateway.http.endpoints.responses.files.allowUrl=false` - 和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 来禁用 URL 抓取。 -- 可选的响应加固 header： - - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS 来源设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） + 空允许列表会被视为未设置；若要禁用 URL 抓取，请使用 `gateway.http.endpoints.responses.files.allowUrl=false` + 和 / 或 `gateway.http.endpoints.responses.images.allowUrl=false`。 +- 可选响应加固 header： + - `gateway.http.securityHeaders.strictTransportSecurity`（仅在你控制的 HTTPS origin 上设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)） ### 多实例隔离 -在同一主机上运行多个 Gateway 网关时，请使用不同的端口和状态目录： +在一台主机上运行多个 gateway，并为其分配唯一端口和状态目录： ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -3147,7 +3165,7 @@ openclaw gateway --port 19001 便捷标志：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`）、`--profile `（使用 `~/.openclaw-`）。 -请参见 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。 +参见 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。 ### `gateway.tls` @@ -3166,10 +3184,10 @@ openclaw gateway --port 19001 ``` - `enabled`：在 gateway 监听器处启用 TLS 终止（HTTPS/WSS）（默认：`false`）。 -- `autoGenerate`：当未配置显式文件时，自动生成本地自签名证书/密钥对；仅适用于本地/开发用途。 +- `autoGenerate`：当未配置显式文件时，自动生成本地自签名 cert/key 对；仅用于本地 / 开发环境。 - `certPath`：TLS 证书文件的文件系统路径。 -- `keyPath`：TLS 私钥文件的文件系统路径；应限制权限。 -- `caPath`：用于客户端验证或自定义信任链的可选 CA bundle 路径。 +- `keyPath`：TLS 私钥文件的文件系统路径；请限制其权限。 +- `caPath`：可选的 CA bundle 路径，用于客户端验证或自定义信任链。 ### `gateway.reload` @@ -3185,13 +3203,13 @@ openclaw gateway --port 19001 } ``` -- `mode`：控制如何在运行时应用配置编辑。 +- `mode`：控制配置编辑在运行时如何应用。 - `"off"`：忽略实时编辑；更改需要显式重启。 - `"restart"`：配置变更时始终重启 gateway 进程。 - - `"hot"`：在进程内应用更改而不重启。 - - `"hybrid"`（默认）：先尝试热重载；如有需要则回退为重启。 -- `debounceMs`：应用配置更改前的去抖窗口（毫秒）（非负整数）。 -- `deferralTimeoutMs`：在强制重启前等待进行中操作完成的最大毫秒数（默认：`300000` = 5 分钟）。 + - `"hot"`：在进程内应用更改，无需重启。 + - `"hybrid"`（默认）：先尝试热重载；如有需要则回退到重启。 +- `debounceMs`：应用配置更改前的防抖窗口（毫秒）（非负整数）。 +- `deferralTimeoutMs`：在强制重启前等待正在进行中的操作完成的最长时间（毫秒）（默认：`300000` = 5 分钟）。 --- @@ -3228,47 +3246,47 @@ openclaw gateway --port 19001 } ``` -身份验证：`Authorization: Bearer ` 或 `x-openclaw-token: `。 +认证方式：`Authorization: Bearer ` 或 `x-openclaw-token: `。 查询字符串中的 hook token 会被拒绝。 -验证和安全注意事项： +验证与安全说明： -- `hooks.enabled=true` 要求提供非空的 `hooks.token`。 -- `hooks.token` 必须与 `gateway.auth.token` **不同**；复用 Gateway 网关 token 会被拒绝。 +- `hooks.enabled=true` 要求 `hooks.token` 为非空。 +- `hooks.token` 必须与 `gateway.auth.token` **不同**；重复使用 Gateway 网关 token 会被拒绝。 - `hooks.path` 不能是 `/`；请使用专用子路径，例如 `/hooks`。 -- 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 -- 如果某个映射或 preset 使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要该显式启用项。 +- 如果 `hooks.allowRequestSessionKey=true`，请限制 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。 +- 如果某个 mapping 或 preset 使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态 mapping 键不需要该显式启用项。 **端点：** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - 仅当 `hooks.allowRequestSessionKey=true`（默认：`false`）时，才接受请求负载中的 `sessionKey`。 + - 仅当 `hooks.allowRequestSessionKey=true`（默认：`false`）时，才接受请求载荷中的 `sessionKey`。 - `POST /hooks/` → 通过 `hooks.mappings` 解析 - - 模板渲染后的映射 `sessionKey` 值会被视为外部提供，因此同样要求 `hooks.allowRequestSessionKey=true`。 + - 模板渲染后的 mapping `sessionKey` 值会被视为外部提供，因此也要求 `hooks.allowRequestSessionKey=true`。 - + -- `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 -- `match.source` 匹配通用路径中的某个负载字段。 -- `{{messages[0].subject}}` 之类的模板会从负载中读取。 -- `transform` 可以指向一个返回 hook 动作的 JS/TS 模块。 - - `transform.module` 必须是相对路径，并且保持在 `hooks.transformsDir` 内（绝对路径和路径遍历会被拒绝）。 +- `match.path` 会匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。 +- `match.source` 会匹配通用路径中的某个载荷字段。 +- 像 `{{messages[0].subject}}` 这样的模板会从载荷中读取。 +- `transform` 可以指向一个返回 hook action 的 JS/TS 模块。 + - `transform.module` 必须是相对路径，并保持在 `hooks.transformsDir` 内（绝对路径和路径穿越都会被拒绝）。 - `agentId` 会路由到特定智能体；未知 ID 会回退到默认值。 - `allowedAgentIds`：限制显式路由（`*` 或省略 = 全部允许，`[]` = 全部拒绝）。 -- `defaultSessionKey`：对未显式提供 `sessionKey` 的 hook 智能体运行，可选的固定会话键。 -- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方以及模板驱动的映射会话键设置 `sessionKey`（默认：`false`）。 -- `allowedSessionKeyPrefixes`：对显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任意映射或 preset 使用模板化 `sessionKey` 时，它就变为必需项。 -- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认为 `last`。 -- `model` 会覆盖此次 hook 运行的 LLM（如果设置了模型目录，则该模型必须被允许）。 +- `defaultSessionKey`：可选的固定会话键，用于没有显式 `sessionKey` 的 hook 智能体运行。 +- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方以及模板驱动的 mapping 会话键设置 `sessionKey`（默认：`false`）。 +- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + mapping）的可选前缀允许列表，例如 `["hook:"]`。当任意 mapping 或 preset 使用模板化的 `sessionKey` 时，它就成为必填项。 +- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认是 `last`。 +- `model` 会覆盖此次 hook 运行所用的 LLM（如果设置了模型目录，则该模型必须被允许）。 ### Gmail 集成 - 内置 Gmail preset 使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。 -- 如果你保留这种按消息路由方式，请设置 `hooks.allowRequestSessionKey: true`，并约束 `hooks.allowedSessionKeyPrefixes` 以匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。 -- 如果你需要 `hooks.allowRequestSessionKey: false`，请用静态 `sessionKey` 覆盖 preset，而不是使用模板化默认值。 +- 如果你保留这种按消息路由方式，请设置 `hooks.allowRequestSessionKey: true`，并将 `hooks.allowedSessionKeyPrefixes` 限制为匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。 +- 如果你需要 `hooks.allowRequestSessionKey: false`，请使用静态 `sessionKey` 覆盖该 preset，而不是使用模板化默认值。 ```json5 { @@ -3292,7 +3310,7 @@ openclaw gateway --port 19001 ``` - 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用。 -- 不要在 Gateway 网关旁边再单独运行一个 `gog gmail watch serve`。 +- 不要在 Gateway 网关旁边单独运行另一个 `gog gmail watch serve`。 --- @@ -3303,23 +3321,23 @@ openclaw gateway --port 19001 canvasHost: { root: "~/.openclaw/workspace/canvas", liveReload: true, - // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1 + // enabled: false, // 或 OPENCLAW_SKIP_CANVAS_HOST=1 }, } ``` -- 在 Gateway 网关端口下，通过 HTTP 提供可由智能体编辑的 HTML/CSS/JS 和 A2UI： +- 通过 Gateway 网关端口下的 HTTP 提供可由智能体编辑的 HTML/CSS/JS 和 A2UI： - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - 仅限本地：保持 `gateway.bind: "loopback"`（默认）。 -- 非 loopback 绑定：canvas 路由与其他 Gateway 网关 HTTP 表面一样，都需要 Gateway 网关身份验证（token/password/trusted-proxy）。 -- 节点 WebView 通常不会发送身份验证头；当某个节点完成配对并连接后，Gateway 网关会为 canvas/A2UI 访问通告按节点作用域的能力 URL。 -- 能力 URL 绑定到活动节点 WS 会话，并且会很快过期。不使用基于 IP 的回退。 +- 非 loopback 绑定：canvas 路由与其他 Gateway 网关 HTTP 表面一样，也需要 Gateway 网关认证（token/password/trusted-proxy）。 +- 节点 WebView 通常不会发送认证 headers；当某个节点已配对并连接后，Gateway 网关会为 canvas/A2UI 访问公布节点作用域的能力 URL。 +- 能力 URL 绑定到当前活动的节点 WS 会话，并且很快过期。不使用基于 IP 的回退。 - 会向所提供的 HTML 中注入 live-reload 客户端。 -- 空目录时会自动创建起始 `index.html`。 -- 还会在 `/__openclaw__/a2ui/` 提供 A2UI。 -- 变更需要重启 gateway。 -- 对于大型目录或 `EMFILE` 错误，请禁用 live reload。 +- 当目录为空时，会自动创建初始 `index.html`。 +- 也会在 `/__openclaw__/a2ui/` 提供 A2UI。 +- 更改需要重启 gateway。 +- 对于大型目录或出现 `EMFILE` 错误时，请禁用 live reload。 --- @@ -3341,7 +3359,7 @@ openclaw gateway --port 19001 - `full`：包含 `cliPath` + `sshPort`。 - 主机名默认为 `openclaw`。可通过 `OPENCLAW_MDNS_HOSTNAME` 覆盖。 -### 广域网（DNS-SD） +### 广域（DNS-SD） ```json5 { @@ -3351,7 +3369,7 @@ openclaw gateway --port 19001 } ``` -会在 `~/.openclaw/dns/` 下写入一个单播 DNS-SD 区域。对于跨网络设备发现，请配合 DNS 服务器（推荐 CoreDNS）+ Tailscale 拆分 DNS。 +会在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。对于跨网络设备发现，请将其与 DNS 服务器（推荐 CoreDNS）+ Tailscale 分流 DNS 搭配使用。 设置：`openclaw dns setup --apply`。 @@ -3376,14 +3394,14 @@ openclaw gateway --port 19001 } ``` -- 内联环境变量仅在进程环境缺少该键时才会生效。 -- `.env` 文件：当前工作目录的 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 +- 仅当进程环境中缺少该键时，才会应用内联环境变量。 +- `.env` 文件：当前工作目录 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。 - `shellEnv`：从你的登录 shell 配置文件中导入缺失的预期键名。 - 完整优先级请参见 [环境变量](/zh-CN/help/environment)。 ### 环境变量替换 -可在任意配置字符串中通过 `${VAR_NAME}` 引用环境变量： +可在任意配置字符串中使用 `${VAR_NAME}` 引用环境变量： ```json5 { @@ -3394,19 +3412,19 @@ openclaw gateway --port 19001 ``` - 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。 -- 缺失/为空的变量会在加载配置时抛出错误。 -- 使用 `$${VAR}` 转义为字面量 `${VAR}`。 +- 缺失 / 为空的变量会在加载配置时抛出错误。 +- 使用 `$${VAR}` 可转义为字面量 `${VAR}`。 - 适用于 `$include`。 --- ## Secrets -SecretRef 是追加式的：明文值仍然可用。 +SecretRef 是增量式的：明文值仍然可用。 ### `SecretRef` -使用以下对象形态之一： +使用一种对象形态： ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -3416,23 +3434,23 @@ SecretRef 是追加式的：明文值仍然可用。 - `provider` 模式：`^[a-z][a-z0-9_-]{0,63}$` - `source: "env"` 的 id 模式：`^[A-Z][A-Z0-9_]{0,127}$` -- `source: "file"` 的 id：绝对 JSON 指针（例如 `"/providers/openai/apiKey"`） +- `source: "file"` 的 id：绝对 JSON pointer（例如 `"/providers/openai/apiKey"`） - `source: "exec"` 的 id 模式：`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `source: "exec"` 的 id 不得包含 `.` 或 `..` 这样的以斜杠分隔的路径段（例如 `a/../b` 会被拒绝） +- `source: "exec"` 的 id 不得包含以 `/` 分隔的 `.` 或 `..` 路径段（例如 `a/../b` 会被拒绝） ### 支持的凭证表面 -- 规范矩阵：[SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface) +- 规范矩阵：[SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface) - `secrets apply` 以受支持的 `openclaw.json` 凭证路径为目标。 -- `auth-profiles.json` 引用也包含在运行时解析和审计覆盖范围中。 +- `auth-profiles.json` refs 也包含在运行时解析和审计覆盖范围内。 -### Secret providers 配置 +### Secret 提供商配置 ```json5 { secrets: { providers: { - default: { source: "env" }, // optional explicit env provider + default: { source: "env" }, // 可选的显式 env 提供商 filemain: { source: "file", path: "~/.openclaw/secrets.json", @@ -3454,20 +3472,20 @@ SecretRef 是追加式的：明文值仍然可用。 } ``` -注意： +说明： -- `file` provider 支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。 -- 当 Windows ACL 验证不可用时，file 和 exec provider 路径会失败即关闭。仅对无法验证但受信任的路径设置 `allowInsecurePath: true`。 -- `exec` provider 要求使用绝对 `command` 路径，并通过 stdin/stdout 使用协议负载。 -- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时验证其解析后的目标路径。 -- 如果配置了 `trustedDirs`，受信任目录检查会应用到解析后的目标路径。 -- 默认情况下，`exec` 子进程环境是最小化的；请使用 `passEnv` 显式传递所需变量。 +- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。 +- 当无法验证 Windows ACL 时，文件和 exec 提供商路径会以默认拒绝方式失败。仅对无法验证但你信任的路径设置 `allowInsecurePath: true`。 +- `exec` 提供商要求 `command` 为绝对路径，并通过 stdin/stdout 使用协议载荷。 +- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可在验证解析后的目标路径时允许符号链接路径。 +- 如果配置了 `trustedDirs`，则受信任目录检查会应用到解析后的目标路径。 +- `exec` 子进程环境默认是最小化的；请使用 `passEnv` 显式传递所需变量。 - Secret refs 会在激活时解析到内存快照中，之后请求路径只读取该快照。 -- 激活期间会应用活动表面过滤：已启用表面上的未解析引用会导致启动/重载失败，而非活动表面会被跳过并附带诊断信息。 +- 激活期间会应用活动表面过滤：已启用表面上的未解析 refs 会导致启动 / 重载失败，而非活动表面会被跳过并记录诊断信息。 --- -## Auth 存储 +## 认证存储 ```json5 { @@ -3486,11 +3504,11 @@ SecretRef 是追加式的：明文值仍然可用。 ``` - 按智能体的配置文件存储在 `/auth-profiles.json`。 -- `auth-profiles.json` 支持静态凭证模式下的值级引用（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 +- `auth-profiles.json` 支持静态凭证模式的值级 refs（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。 - OAuth 模式配置文件（`auth.profiles..mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。 -- 静态运行时凭证来自内存中已解析的快照；发现旧版静态 `auth.json` 条目时会进行清理。 +- 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会将其清除。 - 旧版 OAuth 会从 `~/.openclaw/credentials/oauth.json` 导入。 -- 请参见 [OAuth](/zh-CN/concepts/oauth)。 +- 参见 [OAuth](/zh-CN/concepts/oauth)。 - Secrets 运行时行为以及 `audit/configure/apply` 工具：参见 [Secrets Management](/zh-CN/gateway/secrets)。 ### `auth.cooldowns` @@ -3514,19 +3532,19 @@ SecretRef 是追加式的：明文值仍然可用。 ``` - `billingBackoffHours`：当某个配置文件因真实的 - 计费/额度不足错误而失败时，使用的基础退避小时数（默认：`5`）。即使在 `401`/`403` 响应中， - 明确的计费文本仍可能归入这里，但提供商特定的文本 - 匹配器仍然仅限于拥有它们的提供商（例如 OpenRouter 的 + 计费 / 余额不足错误而失败时使用的基础退避时间（小时）（默认：`5`）。显式计费文本 + 即使出现在 `401` / `403` 响应中，仍可能落入这里，但提供商特定文本 + 匹配器仍限定在拥有它们的提供商范围内（例如 OpenRouter 的 `Key limit exceeded`）。可重试的 HTTP `402` 用量窗口或 - organization/workspace 支出限制消息则仍归入 `rate_limit` 路径。 -- `billingBackoffHoursByProvider`：可选的按提供商计费退避小时覆盖。 + organization/workspace 消费上限消息则仍会进入 `rate_limit` 路径。 +- `billingBackoffHoursByProvider`：可选的按提供商计费退避小时数覆盖。 - `billingMaxHours`：计费退避指数增长的小时上限（默认：`24`）。 -- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避分钟数（默认：`10`）。 +- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避时间（分钟）（默认：`10`）。 - `authPermanentMaxMinutes`：`auth_permanent` 退避增长的分钟上限（默认：`60`）。 -- `failureWindowHours`：用于退避计数器的滚动窗口小时数（默认：`24`）。 -- `overloadedProfileRotations`：对于 overloaded 错误，在切换到模型回退前，允许的同一提供商 auth-profile 最大轮换次数（默认：`1`）。像 `ModelNotReadyException` 这样的提供商繁忙形态会归入这里。 -- `overloadedBackoffMs`：重试 overloaded 提供商/profile 轮换前的固定延迟（默认：`0`）。 -- `rateLimitedProfileRotations`：对于速率限制错误，在切换到模型回退前，允许的同一提供商 auth-profile 最大轮换次数（默认：`1`）。该速率限制桶包括诸如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted` 等提供商形态文本。 +- `failureWindowHours`：用于退避计数器的滚动时间窗口（小时）（默认：`24`）。 +- `overloadedProfileRotations`：对于 overloaded 错误，在切换到模型回退前，允许的同提供商 auth-profile 轮换最大次数（默认：`1`）。例如 `ModelNotReadyException` 之类的提供商繁忙形态会归入此类。 +- `overloadedBackoffMs`：在重试 overloaded 提供商 / 配置文件轮换前的固定延迟（毫秒）（默认：`0`）。 +- `rateLimitedProfileRotations`：对于 rate-limit 错误，在切换到模型回退前，允许的同提供商 auth-profile 轮换最大次数（默认：`1`）。该 rate-limit 桶包括带有提供商形态的文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。 --- @@ -3546,9 +3564,9 @@ SecretRef 是追加式的：明文值仍然可用。 ``` - 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。 -- 设置 `logging.file` 以使用固定路径。 +- 设置 `logging.file` 可使用稳定路径。 - 使用 `--verbose` 时，`consoleLevel` 会提升到 `debug`。 -- `maxFileBytes`：在抑制写入前允许的最大日志文件大小（字节）（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 +- `maxFileBytes`：在抑制写入之前，日志文件允许的最大字节数（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。 --- @@ -3585,20 +3603,20 @@ SecretRef 是追加式的：明文值仍然可用。 } ``` -- `enabled`：instrumentation 输出的主开关（默认：`true`）。 +- `enabled`：仪表输出的主开关（默认：`true`）。 - `flags`：用于启用定向日志输出的标志字符串数组（支持 `"telegram.*"` 或 `"*"` 之类的通配符）。 -- `stuckSessionWarnMs`：当会话保持在 processing 状态时，用于发出卡住会话警告的年龄阈值（毫秒）。 +- `stuckSessionWarnMs`：当会话持续处于 processing 状态时，用于发出卡住会话警告的年龄阈值（毫秒）。 - `otel.enabled`：启用 OpenTelemetry 导出管线（默认：`false`）。 - `otel.endpoint`：用于 OTel 导出的 collector URL。 - `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。 -- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据头。 -- `otel.serviceName`：资源属性中的服务名称。 -- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 log 导出。 -- `otel.sampleRate`：trace 采样率，范围 `0`–`1`。 -- `otel.flushIntervalMs`：定期刷新 telemetry 的间隔（毫秒）。 +- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据 headers。 +- `otel.serviceName`：资源属性使用的服务名称。 +- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 logs 导出。 +- `otel.sampleRate`：trace 采样率 `0`–`1`。 +- `otel.flushIntervalMs`：定期刷新遥测的间隔（毫秒）。 - `cacheTrace.enabled`：记录嵌入式运行的缓存跟踪快照（默认：`false`）。 - `cacheTrace.filePath`：缓存跟踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。 -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出中包含哪些内容（默认全为 `true`）。 +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出中包含哪些内容（默认均为：`true`）。 --- @@ -3620,12 +3638,12 @@ SecretRef 是追加式的：明文值仍然可用。 } ``` -- `channel`：npm/git 安装的发布渠道——`"stable"`、`"beta"` 或 `"dev"`。 -- `checkOnStart`：gateway 启动时检查 npm 更新（默认：`true`）。 +- `channel`：npm/git 安装使用的发布渠道 —— `"stable"`、`"beta"` 或 `"dev"`。 +- `checkOnStart`：在 gateway 启动时检查 npm 更新（默认：`true`）。 - `auto.enabled`：为包安装启用后台自动更新（默认：`false`）。 -- `auto.stableDelayHours`：stable 渠道自动应用前的最短延迟小时数（默认：`6`；最大：`168`）。 -- `auto.stableJitterHours`：stable 渠道额外的滚动分布窗口小时数（默认：`12`；最大：`168`）。 -- `auto.betaCheckIntervalHours`：beta 渠道检查运行的间隔小时数（默认：`1`；最大：`24`）。 +- `auto.stableDelayHours`：稳定渠道自动应用前的最小延迟（小时）（默认：`6`；最大：`168`）。 +- `auto.stableJitterHours`：稳定渠道发布扩散窗口的额外小时数（默认：`12`；最大：`168`）。 +- `auto.betaCheckIntervalHours`：beta 渠道检查运行的频率（小时）（默认：`1`；最大：`24`）。 --- @@ -3659,21 +3677,21 @@ SecretRef 是追加式的：明文值仍然可用。 ``` - `enabled`：全局 ACP 功能开关（默认：`false`）。 -- `dispatch.enabled`：ACP 会话轮次分发的独立开关（默认：`true`）。设为 `false` 可在阻止执行的同时保留 ACP 命令可用。 -- `backend`：默认 ACP 运行时后端 ID（必须匹配某个已注册的 ACP 运行时插件）。 -- `defaultAgent`：当生成时未指定显式目标时，所使用的回退 ACP 目标智能体 ID。 -- `allowedAgents`：允许用于 ACP 运行时会话的智能体 ID 允许列表；为空表示无额外限制。 -- `maxConcurrentSessions`：最多同时活动的 ACP 会话数。 -- `stream.coalesceIdleMs`：流式文本的空闲合并刷新窗口（毫秒）。 -- `stream.maxChunkChars`：在拆分流式块投影前允许的最大块大小。 -- `stream.repeatSuppression`：按轮次抑制重复的状态/工具行（默认：`true`）。 -- `stream.deliveryMode`：`"live"` 递增式流出；`"final_only"` 缓冲到轮次终结事件后再输出。 +- `dispatch.enabled`：ACP 会话轮次分发的独立开关（默认：`true`）。设为 `false` 可在保留 ACP 命令可用的同时阻止执行。 +- `backend`：默认 ACP 运行时后端 id（必须匹配已注册的 ACP 运行时插件）。 +- `defaultAgent`：当生成未指定显式目标时，ACP 回退使用的目标智能体 id。 +- `allowedAgents`：ACP 运行时会话允许使用的智能体 id 允许列表；空值表示没有额外限制。 +- `maxConcurrentSessions`：同时处于活动状态的 ACP 会话最大数。 +- `stream.coalesceIdleMs`：流式文本的空闲冲刷窗口（毫秒）。 +- `stream.maxChunkChars`：在拆分流式分块投影前允许的最大块大小。 +- `stream.repeatSuppression`：每轮抑制重复的状态 / 工具行（默认：`true`）。 +- `stream.deliveryMode`：`"live"` 增量流式传输；`"final_only"` 则缓冲到轮次终止事件后再输出。 - `stream.hiddenBoundarySeparator`：隐藏工具事件后、可见文本前的分隔符（默认：`"paragraph"`）。 -- `stream.maxOutputChars`：每个 ACP 轮次投影的最大助手输出字符数。 -- `stream.maxSessionUpdateChars`：投影的 ACP 状态/更新行允许的最大字符数。 -- `stream.tagVisibility`：记录标签名称到布尔可见性覆盖的映射，用于流式事件。 -- `runtime.ttlMinutes`：ACP 会话工作进程在变为可清理前的空闲 TTL（分钟）。 -- `runtime.installCommand`：在引导 ACP 运行时环境时运行的可选安装命令。 +- `stream.maxOutputChars`：每次 ACP 轮次投影的 assistant 输出最大字符数。 +- `stream.maxSessionUpdateChars`：投影 ACP 状态 / 更新行的最大字符数。 +- `stream.tagVisibility`：针对流式事件的 tag 名称到布尔可见性覆盖的记录。 +- `runtime.ttlMinutes`：ACP 会话 worker 在符合清理条件前的空闲 TTL（分钟）。 +- `runtime.installCommand`：引导 ACP 运行时环境时可选执行的安装命令。 --- @@ -3690,10 +3708,10 @@ SecretRef 是追加式的：明文值仍然可用。 ``` - `cli.banner.taglineMode` 控制 banner 标语样式： - - `"random"`（默认）：轮换的有趣/节日标语。 - - `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。 - - `"off"`：不显示标语文本（仍显示 banner 标题/版本）。 -- 如需隐藏整个 banner（而不仅是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 + - `"random"`（默认）：轮换显示有趣 / 季节性标语。 + - `"default"`：固定中性标语（`All your chats, one OpenClaw.`）。 + - `"off"`：不显示标语文本（仍会显示 banner 标题 / 版本）。 +- 若要隐藏整个 banner（而不仅仅是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 --- @@ -3717,13 +3735,13 @@ SecretRef 是追加式的：明文值仍然可用。 ## 身份 -请参阅 [智能体默认值](#agent-defaults) 下 `agents.list` 的身份字段。 +参见 [智能体默认值](#agent-defaults) 下 `agents.list` 的身份字段。 --- ## Bridge protocol（旧版节点，历史参考）（旧版，已移除） -当前构建不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前，验证会失败；`openclaw doctor --fix` 可剥离未知键）。 +当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前验证会失败；`openclaw doctor --fix` 可移除未知键）。 @@ -3752,22 +3770,22 @@ SecretRef 是追加式的：明文值仍然可用。 cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs - webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth - sessionRetention: "24h", // duration string or false + webhook: "https://example.invalid/legacy", // 已弃用，用于已保存 notify:true 作业的回退 + webhookToken: "replace-with-dedicated-token", // 可选的出站 webhook 认证 bearer token + sessionRetention: "24h", // 时长字符串或 false runLog: { - maxBytes: "2mb", // default 2_000_000 bytes - keepLines: 2000, // default 2000 + maxBytes: "2mb", // 默认 2_000_000 字节 + keepLines: 2000, // 默认 2000 }, }, } ``` -- `sessionRetention`：从 `sessions.json` 中修剪前，保留已完成隔离 cron 运行会话的时长。也控制已归档已删除 cron 转录的清理。默认值：`24h`；设为 `false` 可禁用。 -- `runLog.maxBytes`：每个运行日志文件（`cron/runs/.jsonl`）在修剪前允许的最大大小。默认值：`2_000_000` 字节。 -- `runLog.keepLines`：触发运行日志修剪时保留的最新行数。默认值：`2000`。 -- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；若省略，则不发送身份验证头。 -- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于仍保留 `notify: true` 的已存储作业。 +- `sessionRetention`：已完成的隔离 cron 运行会话在从 `sessions.json` 中修剪前保留多久。也控制已归档、已删除的 cron 对话记录的清理。默认：`24h`；设为 `false` 可禁用。 +- `runLog.maxBytes`：每个运行日志文件（`cron/runs/.jsonl`）在修剪前允许的最大大小。默认：`2_000_000` 字节。 +- `runLog.keepLines`：触发运行日志修剪时保留的最新行数。默认：`2000`。 +- `webhookToken`：用于 cron webhook POST 传递（`delivery.mode = "webhook"`）的 bearer token；若省略则不会发送认证 header。 +- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于仍带有 `notify: true` 的已存储作业。 ### `cron.retry` @@ -3783,11 +3801,11 @@ SecretRef 是追加式的：明文值仍然可用。 } ``` -- `maxAttempts`：对于瞬时错误，单次作业允许的最大重试次数（默认：`3`；范围：`0`–`10`）。 -- `backoffMs`：每次重试尝试使用的退避延迟数组（毫秒）（默认：`[30000, 60000, 300000]`；1–10 个条目）。 -- `retryOn`：触发重试的错误类型——`"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略则会重试所有瞬时类型。 +- `maxAttempts`：一次性作业在瞬态错误下的最大重试次数（默认：`3`；范围：`0`–`10`）。 +- `backoffMs`：每次重试尝试的退避延迟数组（毫秒）（默认：`[30000, 60000, 300000]`；1–10 个条目）。 +- `retryOn`：触发重试的错误类型 —— `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略则会对所有瞬态类型重试。 -仅适用于单次 cron 作业。周期性作业使用单独的失败处理。 +仅适用于一次性 cron 作业。周期性作业使用单独的失败处理机制。 ### `cron.failureAlert` @@ -3805,11 +3823,11 @@ SecretRef 是追加式的：明文值仍然可用。 } ``` -- `enabled`：为 cron 作业启用失败告警（默认：`false`）。 -- `after`：在触发告警前的连续失败次数（正整数，最小值：`1`）。 -- `cooldownMs`：同一作业重复告警之间的最小毫秒间隔（非负整数）。 -- `mode`：投递模式——`"announce"` 通过渠道消息发送；`"webhook"` 向已配置 webhook 发起 POST。 -- `accountId`：用于限定告警投递范围的可选账户或渠道 ID。 +- `enabled`：启用 cron 作业失败告警（默认：`false`）。 +- `after`：触发告警前允许的连续失败次数（正整数，最小值：`1`）。 +- `cooldownMs`：同一作业重复告警之间的最小间隔（毫秒）（非负整数）。 +- `mode`：传递模式 —— `"announce"` 通过渠道消息发送；`"webhook"` 则向已配置 webhook 发起 POST。 +- `accountId`：用于限定告警传递范围的可选账户或渠道 id。 ### `cron.failureDestination` @@ -3826,16 +3844,16 @@ SecretRef 是追加式的：明文值仍然可用。 } ``` -- 所有作业共享的 cron 失败通知默认目标。 -- `mode`：`"announce"` 或 `"webhook"`；当存在足够目标数据时，默认是 `"announce"`。 -- `channel`：announce 投递的渠道覆盖。`"last"` 会复用最近已知的投递渠道。 -- `to`：显式的 announce 目标或 webhook URL。webhook 模式下必需。 -- `accountId`：投递时的可选账户覆盖。 +- 所有作业共用的 cron 失败通知默认目标。 +- `mode`：`"announce"` 或 `"webhook"`；当存在足够目标数据时，默认值为 `"announce"`。 +- `channel`：announce 传递的渠道覆盖。`"last"` 会复用上次已知的传递渠道。 +- `to`：显式的 announce 目标或 webhook URL。webhook 模式下为必填。 +- `accountId`：可选的传递账户覆盖。 - 按作业的 `delivery.failureDestination` 会覆盖该全局默认值。 -- 当全局和按作业失败目标都未设置时，那些原本已通过 `announce` 投递的作业在失败时会回退到其主 announce 目标。 +- 当全局和按作业失败目标都未设置时，已经通过 `announce` 进行主传递的作业会在失败时回退到其主 announce 目标。 - `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 的作业，除非该作业的主 `delivery.mode` 为 `"webhook"`。 -请参见 [Cron 作业](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为 [后台任务](/zh-CN/automation/tasks) 跟踪。 +参见 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为 [后台任务](/zh-CN/automation/tasks) 跟踪。 --- @@ -3843,34 +3861,34 @@ SecretRef 是追加式的：明文值仍然可用。 在 `tools.media.models[].args` 中展开的模板占位符： -| 变量 | 说明 | -| ------------------ | ------------------------------------------------- | -| `{{Body}}` | 完整传入消息正文 | -| `{{RawBody}}` | 原始正文（无历史/发送者包装） | -| `{{BodyStripped}}` | 去除群组提及后的正文 | -| `{{From}}` | 发送者标识符 | -| `{{To}}` | 目标标识符 | -| `{{MessageSid}}` | 渠道消息 ID | -| `{{SessionId}}` | 当前会话 UUID | -| `{{IsNewSession}}` | 新建会话时为 `"true"` | -| `{{MediaUrl}}` | 传入媒体伪 URL | -| `{{MediaPath}}` | 本地媒体路径 | -| `{{MediaType}}` | 媒体类型（image/audio/document/…） | -| `{{Transcript}}` | 音频转录 | -| `{{Prompt}}` | CLI 条目的已解析媒体提示 | -| `{{MaxChars}}` | CLI 条目的已解析最大输出字符数 | -| `{{ChatType}}` | `"direct"` 或 `"group"` | -| `{{GroupSubject}}` | 群组主题（尽力而为） | -| `{{GroupMembers}}` | 群组成员预览（尽力而为） | -| `{{SenderName}}` | 发送者显示名称（尽力而为） | -| `{{SenderE164}}` | 发送者电话号码（尽力而为） | +| 变量 | 说明 | +| ------------------ | ------------------------------------- | +| `{{Body}}` | 完整传入消息正文 | +| `{{RawBody}}` | 原始正文（不含历史 / 发送者包装） | +| `{{BodyStripped}}` | 去除群组提及后的正文 | +| `{{From}}` | 发送者标识符 | +| `{{To}}` | 目标标识符 | +| `{{MessageSid}}` | 渠道消息 id | +| `{{SessionId}}` | 当前会话 UUID | +| `{{IsNewSession}}` | 新建会话时为 `"true"` | +| `{{MediaUrl}}` | 传入媒体伪 URL | +| `{{MediaPath}}` | 本地媒体路径 | +| `{{MediaType}}` | 媒体类型（image/audio/document/…） | +| `{{Transcript}}` | 音频转录 | +| `{{Prompt}}` | CLI 条目解析后的媒体提示 | +| `{{MaxChars}}` | CLI 条目解析后的最大输出字符数 | +| `{{ChatType}}` | `"direct"` 或 `"group"` | +| `{{GroupSubject}}` | 群组主题（尽力而为） | +| `{{GroupMembers}}` | 群组成员预览（尽力而为） | +| `{{SenderName}}` | 发送者显示名称（尽力而为） | +| `{{SenderE164}}` | 发送者电话号码（尽力而为） | | `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） | --- -## 配置包含（`$include`） +## 配置 include（`$include`） -将配置拆分为多个文件： +将配置拆分到多个文件中： ```json5 // ~/.openclaw/openclaw.json @@ -3885,14 +3903,14 @@ SecretRef 是追加式的：明文值仍然可用。 **合并行为：** -- 单文件：替换其所在的包含对象。 +- 单文件：替换其所在的容器对象。 - 文件数组：按顺序深度合并（后者覆盖前者）。 -- 同级键：会在 includes 之后合并（覆盖包含进来的值）。 -- 嵌套 includes：最多 10 层。 -- 路径：相对于发起包含的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）之内。绝对路径/`../` 形式仅在最终仍解析到该边界内时才允许。 -- 当 OpenClaw 自有写入仅更改由单文件 include 支持的某一个顶层部分时，会透传写入到该被包含文件。例如，`plugins install` 会更新 `plugins: { $include: "./plugins.json5" }` 中的 `plugins.json5`，并保持 `openclaw.json` 不变。 -- 根级 includes、include 数组，以及带有同级覆盖的 includes 对 OpenClaw 自有写入来说是只读的；这些写入会失败即关闭，而不是将配置拍平。 -- 错误：对缺失文件、解析错误和循环 includes 提供清晰消息。 +- 同级键：在 includes 之后合并（覆盖已 include 的值）。 +- 嵌套 include：最多 10 层。 +- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。绝对路径 / `../` 形式只有在最终仍解析到该边界内部时才允许。 +- 仅变更某一个由单文件 include 支持的顶层区段的 OpenClaw 自有写入，会直接写回该 include 文件。例如，`plugins install` 会在 `plugins: { $include: "./plugins.json5" }` 的情况下更新 `plugins.json5` 中的内容，而保留 `openclaw.json` 不变。 +- 根级 include、include 数组以及带同级覆盖的 include 对于 OpenClaw 自有写入都是只读的；这些写入会以默认拒绝方式失败，而不是将配置扁平化。 +- 错误：对于缺失文件、解析错误和循环 include，会提供清晰的错误消息。 --- diff --git a/docs/zh-CN/gateway/configuration.md b/docs/zh-CN/gateway/configuration.md index 10d7c093a..522c082ec 100644 --- a/docs/zh-CN/gateway/configuration.md +++ b/docs/zh-CN/gateway/configuration.md @@ -3,35 +3,32 @@ read_when: - 首次设置 OpenClaw - 查找常见配置模式 - 导航到特定配置部分 -summary: 配置概览：常见任务、快速设置，以及指向完整参考的链接 +summary: 配置概览：常见任务、快速设置与完整参考链接 title: 配置 x-i18n: - generated_at: "2026-04-23T08:25:19Z" + generated_at: "2026-04-23T19:24:37Z" model: gpt-5.4 provider: openai - source_hash: d76b40c25f98de791e0d8012b2bc5b80e3e38dde99bb9105539e800ddac3f362 + source_hash: e21161b8b05cf2963d935646bc9b8fe3e3de514cefee71c837566a4090538df2 source_path: gateway/configuration.md workflow: 15 --- # 配置 -OpenClaw 会从 `~/.openclaw/openclaw.json` 读取一个可选的 **JSON5** 配置。 -当前使用的配置路径必须是一个常规文件。对于 OpenClaw 自身发起的写入操作， -不支持使用符号链接形式的 `openclaw.json` 布局；原子写入可能会替换该路径， -而不是保留符号链接。如果你将配置保存在默认状态目录之外，请将 -`OPENCLAW_CONFIG_PATH` 直接指向真实文件。 +OpenClaw 会从 `~/.openclaw/openclaw.json` 读取可选的 **JSON5** 配置。 +当前使用的配置路径必须是一个常规文件。对于由 OpenClaw 执行写入的场景，不支持使用符号链接的 `openclaw.json` 布局；原子写入可能会替换该路径，而不是保留符号链接。如果你将配置保存在默认状态目录之外，请将 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。 -如果文件缺失，OpenClaw 会使用安全的默认值。添加配置的常见原因包括： +如果该文件不存在，OpenClaw 会使用安全的默认值。常见的添加配置原因包括： -- 连接渠道并控制谁可以向机器人发送消息 -- 设置模型、工具、沙箱隔离或自动化功能（cron、hooks） +- 连接渠道并控制谁可以给机器人发消息 +- 设置模型、工具、沙箱隔离或自动化（cron、hooks） - 调整会话、媒体、网络或 UI -有关所有可用字段，请参阅[完整参考](/zh-CN/gateway/configuration-reference)。 +所有可用字段请参阅[完整参考](/zh-CN/gateway/configuration-reference)。 -**刚接触配置？** 可以从 `openclaw onboard` 开始进行交互式设置，或者查看 [Configuration Examples](/zh-CN/gateway/configuration-examples) 指南，获取可直接复制粘贴的完整配置。 +**刚开始接触配置？** 请先使用 `openclaw onboard` 进行交互式设置，或查看[配置示例](/zh-CN/gateway/configuration-examples)指南，获取可直接复制粘贴的完整配置。 ## 最小配置 @@ -49,7 +46,7 @@ OpenClaw 会从 `~/.openclaw/openclaw.json` 读取一个可选的 ```bash - openclaw onboard # 完整的新手引导流程 + openclaw onboard # 完整新手引导流程 openclaw configure # 配置向导 ``` @@ -61,50 +58,42 @@ OpenClaw 会从 `~/.openclaw/openclaw.json` 读取一个可选的 - 打开 [http://127.0.0.1:18789](http://127.0.0.1:18789)，然后使用 **配置** 选项卡。 - 控制 UI 会根据当前配置 schema 渲染表单，其中包括字段 - `title` / `description` 文档元数据，以及在可用情况下的插件和渠道 schema， - 同时还提供一个 **Raw JSON** 编辑器作为兜底入口。对于下钻式 - UI 和其他工具，Gateway 网关 还提供了 `config.schema.lookup`，用于 - 获取单个路径范围内的 schema 节点及其直接子节点摘要。 + 打开 [http://127.0.0.1:18789](http://127.0.0.1:18789) 并使用 **配置** 标签页。 + Control UI 会根据实时配置 schema 渲染表单，包括字段 `title` / `description` 文档元数据，以及在可用时的插件和渠道 schema，并提供一个 **Raw JSON** 编辑器作为兜底方式。对于下钻式 UI 和其他工具，Gateway 网关还暴露了 `config.schema.lookup`，用于获取单个路径范围的 schema 节点及其直接子节点摘要。 - 直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关 会监视该文件并自动应用更改（参见[热重载](#config-hot-reload)）。 + 直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关会监视该文件并自动应用更改（见[热重载](#config-hot-reload)）。 ## 严格校验 -OpenClaw 只接受与 schema 完全匹配的配置。未知键名、格式错误的类型或无效值都会导致 Gateway 网关 **拒绝启动**。唯一的根级例外是 `$schema`（字符串），这样编辑器就可以附加 JSON Schema 元数据。 +OpenClaw 只接受完全符合 schema 的配置。未知键名、格式错误的类型或无效值都会导致 Gateway 网关**拒绝启动**。唯一的根级例外是 `$schema`（字符串），这样编辑器就可以附加 JSON Schema 元数据。 -`openclaw config schema` 会打印供控制 UI -和校验使用的规范 JSON Schema。`config.schema.lookup` 会获取单个路径范围内的节点及其 -子节点摘要，用于下钻式工具。字段 `title`/`description` 文档元数据 -会传递到嵌套对象、通配符（`*`）、数组项（`[]`）以及 `anyOf`/ -`oneOf`/`allOf` 分支中。当清单注册表加载后，运行时插件和渠道 schema 也会合并进来。 +`openclaw config schema` 会打印 Control UI 和校验所使用的规范 JSON Schema。 +`config.schema.lookup` 会获取单个路径范围节点及其子节点摘要，用于下钻式工具。 +字段 `title`/`description` 文档元数据会延续到嵌套对象、通配符（`*`）、数组项（`[]`）以及 `anyOf`/`oneOf`/`allOf` 分支中。 +加载清单注册表后，运行时插件和渠道 schema 也会合并进来。 当校验失败时： -- Gateway 网关 不会启动 +- Gateway 网关不会启动 - 只有诊断命令可用（`openclaw doctor`、`openclaw logs`、`openclaw health`、`openclaw status`） - 运行 `openclaw doctor` 查看具体问题 -- 运行 `openclaw doctor --fix`（或 `--yes`）以应用修复 +- 运行 `openclaw doctor --fix`（或 `--yes`）应用修复 -Gateway 网关 在每次成功启动后都会保留一份受信任的“上次已知正常”副本。 -如果之后 `openclaw.json` 未通过校验（或缺少 `gateway.mode`、体积明显缩小， -或前面意外插入了一行日志），OpenClaw 会将损坏的文件保留为 -`.clobbered.*`，恢复“上次已知正常”副本，并记录恢复原因。 -下一次智能体回合也会收到一条系统事件警告，这样主智能体就不会盲目重写已恢复的配置。 -当候选配置中包含诸如 `***` 之类已脱敏的密钥占位符时， -将其提升为“上次已知正常”副本的操作会被跳过。 +每次成功启动后，Gateway 网关都会保留一份可信的“最后一次已知正常”副本。 +如果之后 `openclaw.json` 校验失败（或丢失 `gateway.mode`、体积显著缩小，或前面意外插入了一行日志），OpenClaw 会将损坏的文件保留为 `.clobbered.*`，恢复“最后一次已知正常”副本，并记录恢复原因。 +下一次智能体轮次也会收到一条系统事件警告，这样主智能体就不会盲目重写已恢复的配置。 +如果候选配置中包含诸如 `***` 之类已脱敏的密钥占位符，则不会将其提升为“最后一次已知正常”。 ## 常见任务 - 每个渠道在 `channels.` 下都有自己的配置部分。设置步骤请参见对应的专用渠道页面： + 每个渠道在 `channels.` 下都有自己的配置部分。设置步骤请参阅相应的专属渠道页面： - [WhatsApp](/zh-CN/channels/whatsapp) — `channels.whatsapp` - [Telegram](/zh-CN/channels/telegram) — `channels.telegram` @@ -117,7 +106,7 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次 - [iMessage](/zh-CN/channels/imessage) — `channels.imessage` - [Mattermost](/zh-CN/channels/mattermost) — `channels.mattermost` - 所有渠道都共享相同的私信策略模式： + 所有渠道共享相同的私信策略模式： ```json5 { @@ -126,7 +115,7 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次 enabled: true, botToken: "123:abc", dmPolicy: "pairing", // pairing | allowlist | open | disabled - allowFrom: ["tg:123"], // only for allowlist/open + allowFrom: ["tg:123"], // 仅用于 allowlist/open }, }, } @@ -135,7 +124,7 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次 - 设置主模型和可选的后备模型： + 设置主模型和可选回退模型： ```json5 { @@ -143,42 +132,42 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次 defaults: { model: { primary: "anthropic/claude-sonnet-4-6", - fallbacks: ["openai/gpt-5.4"], + fallbacks: ["openai/gpt-5.5"], }, models: { "anthropic/claude-sonnet-4-6": { alias: "Sonnet" }, - "openai/gpt-5.4": { alias: "GPT" }, + "openai/gpt-5.5": { alias: "GPT" }, }, }, }, } ``` - - `agents.defaults.models` 定义模型目录，并充当 `/model` 的允许列表。 - - 使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加允许列表条目，而不会移除现有模型。会删除条目的普通替换操作将被拒绝，除非你传入 `--replace`。 + - `agents.defaults.models` 定义模型目录，并作为 `/model` 的允许列表。 + - 使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 可在不移除现有模型的情况下添加允许列表条目。会移除条目的普通替换操作会被拒绝，除非你传入 `--replace`。 - 模型引用使用 `provider/model` 格式（例如 `anthropic/claude-opus-4-6`）。 - - `agents.defaults.imageMaxDimensionPx` 控制对话记录/工具图像的缩放上限（默认 `1200`）；在截图较多的运行中，较低的值通常能减少视觉 token 的使用量。 - - 在聊天中切换模型，请参见 [Models CLI](/zh-CN/concepts/models)；关于凭证轮换和后备行为，请参见 [Model Failover](/zh-CN/concepts/model-failover)。 - - 对于自定义/自托管提供商，请参见参考文档中的 [Custom providers](/zh-CN/gateway/configuration-reference#custom-providers-and-base-urls)。 + - `agents.defaults.imageMaxDimensionPx` 控制转录/工具图像的缩放下限（默认 `1200`）；较低的值通常会在截图较多的运行中减少视觉 token 使用量。 + - 在聊天中切换模型请参阅[模型 CLI](/zh-CN/concepts/models)，关于凭证轮换和回退行为请参阅[模型回退](/zh-CN/concepts/model-failover)。 + - 对于自定义/自托管提供商，请参阅参考中的[自定义提供商](/zh-CN/gateway/configuration-reference#custom-providers-and-base-urls)。 - - 私信访问通过每个渠道的 `dmPolicy` 进行控制： + + 私信访问通过每个渠道的 `dmPolicy` 控制： - `"pairing"`（默认）：未知发送者会收到一次性配对码以供批准 - `"allowlist"`：仅允许 `allowFrom` 中的发送者（或已配对的允许存储） - - `"open"`：允许所有入站私信（需要 `allowFrom: ["*"]`） + - `"open"`：允许所有传入私信（要求 `allowFrom: ["*"]`） - `"disabled"`：忽略所有私信 - 对于群组，请使用 `groupPolicy` + `groupAllowFrom` 或渠道专用的允许列表。 + 对于群组，请使用 `groupPolicy` + `groupAllowFrom` 或渠道特定允许列表。 - 有关每个渠道的详细信息，请参见[完整参考](/zh-CN/gateway/configuration-reference#dm-and-group-access)。 + 每个渠道的详细信息请参阅[完整参考](/zh-CN/gateway/configuration-reference#dm-and-group-access)。 - 群组消息默认 **需要提及**。可按智能体配置模式： + 群组消息默认**要求提及**。可按智能体配置模式： ```json5 { @@ -201,14 +190,13 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次 ``` - **元数据提及**：原生 @ 提及（WhatsApp 点按提及、Telegram @bot 等） - - **文本模式**：`mentionPatterns` 中的安全正则表达式模式 - - 有关每个渠道的覆盖规则和自聊模式，请参见[完整参考](/zh-CN/gateway/configuration-reference#group-chat-mention-gating)。 + - **文本模式**：`mentionPatterns` 中的安全正则模式 + - 每个渠道的覆盖和自聊模式请参阅[完整参考](/zh-CN/gateway/configuration-reference#group-chat-mention-gating)。 - 使用 `agents.defaults.skills` 作为共享基线，然后通过 - `agents.list[].skills` 覆盖特定智能体： + 使用 `agents.defaults.skills` 作为共享基线，然后通过 `agents.list[].skills` 覆盖特定智能体： ```json5 { @@ -219,22 +207,21 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次 list: [ { id: "writer" }, // 继承 github、weather { id: "docs", skills: ["docs-search"] }, // 替换默认值 - { id: "locked-down", skills: [] }, // 无 Skills + { id: "locked-down", skills: [] }, // 不启用 Skills ], }, } ``` - - 省略 `agents.defaults.skills` 可使默认 Skills 不受限制。 - - 省略 `agents.list[].skills` 将继承默认值。 - - 设置 `agents.list[].skills: []` 表示不启用 Skills。 - - 请参见 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 和 - [配置参考](/zh-CN/gateway/configuration-reference#agents-defaults-skills)。 + - 省略 `agents.defaults.skills` 表示默认不限制 Skills。 + - 省略 `agents.list[].skills` 表示继承默认值。 + - 将 `agents.list[].skills` 设为 `[]` 表示不启用 Skills。 + - 参阅 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 以及[配置参考](/zh-CN/gateway/configuration-reference#agents-defaults-skills)。 - - 控制 Gateway 网关 对看起来已停滞的渠道执行重启的激进程度： + + 控制 Gateway 网关对看似卡住的渠道执行重启的激进程度： ```json5 { @@ -256,20 +243,20 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次 } ``` - - 设置 `gateway.channelHealthCheckMinutes: 0` 可全局禁用健康监控重启。 + - 将 `gateway.channelHealthCheckMinutes: 0` 设为 0 可全局禁用健康监控重启。 - `channelStaleEventThresholdMinutes` 应大于或等于检查间隔。 - - 使用 `channels..healthMonitor.enabled` 或 `channels..accounts..healthMonitor.enabled`，可对单个渠道或账户禁用自动重启，而无需禁用全局监控。 - - 关于运维调试，请参见[健康检查](/zh-CN/gateway/health)；有关所有字段，请参见[完整参考](/zh-CN/gateway/configuration-reference#gateway)。 + - 使用 `channels..healthMonitor.enabled` 或 `channels..accounts..healthMonitor.enabled`，可为单个渠道或账号禁用自动重启，而不必关闭全局监控。 + - 运行调试请参阅[健康检查](/zh-CN/gateway/health)，所有字段请参阅[完整参考](/zh-CN/gateway/configuration-reference#gateway)。 - 会话控制对话的连续性和隔离性： + 会话控制对话连续性和隔离性： ```json5 { session: { - dmScope: "per-channel-peer", // recommended for multi-user + dmScope: "per-channel-peer", // 推荐用于多用户 threadBindings: { enabled: true, idleHours: 24, @@ -286,8 +273,8 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次 - `dmScope`：`main`（共享）| `per-peer` | `per-channel-peer` | `per-account-channel-peer` - `threadBindings`：线程绑定会话路由的全局默认值（Discord 支持 `/focus`、`/unfocus`、`/agents`、`/session idle` 和 `/session max-age`）。 - - 关于作用域、身份关联和发送策略，请参见[会话管理](/zh-CN/concepts/session)。 - - 有关所有字段，请参见[完整参考](/zh-CN/gateway/configuration-reference#session)。 + - 作用域、身份关联和发送策略请参阅[会话管理](/zh-CN/concepts/session)。 + - 所有字段请参阅[完整参考](/zh-CN/gateway/configuration-reference#session)。 @@ -309,14 +296,14 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次 先构建镜像：`scripts/sandbox-setup.sh` - 完整指南请参见[沙箱隔离](/zh-CN/gateway/sandboxing)，所有选项请参见[完整参考](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox)。 + 完整指南请参阅[沙箱隔离](/zh-CN/gateway/sandboxing)，所有选项请参阅[完整参考](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox)。 基于 relay 的推送在 `openclaw.json` 中配置。 - 在 Gateway 网关 配置中设置： + 在 Gateway 网关配置中设置： ```json5 { @@ -340,37 +327,37 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次 openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com ``` - 这会执行以下操作： + 作用如下： - - 允许 Gateway 网关 通过外部 relay 发送 `push.test`、唤醒提示和重连唤醒。 - - 使用由已配对 iOS 应用转发的、限定注册范围的发送授权。Gateway 网关 不需要部署范围的 relay token。 - - 将每个基于 relay 的注册绑定到 iOS 应用配对时所连接的 Gateway 网关 身份，因此其他 Gateway 网关 无法复用已存储的注册信息。 - - 本地/手动构建的 iOS 版本仍使用直接 APNs。基于 relay 的发送仅适用于通过 relay 注册的官方分发构建版本。 - - 必须与官方/TestFlight iOS 构建中内置的 relay base URL 匹配，这样注册和发送流量才会到达同一个 relay 部署。 + - 让 Gateway 网关能够通过外部 relay 发送 `push.test`、唤醒提示和重连唤醒。 + - 使用由已配对 iOS 应用转发的、基于注册范围的发送授权。Gateway 网关不需要部署范围的 relay token。 + - 将每个基于 relay 的注册绑定到 iOS 应用所配对的 Gateway 网关身份，因此其他 Gateway 网关无法复用已存储的注册信息。 + - 对本地/手动构建的 iOS 版本继续使用直接 APNs。基于 relay 的发送仅适用于通过 relay 注册的官方分发版本。 + - 必须与官方/TestFlight iOS 构建中内置的 relay 基础 URL 匹配，这样注册和发送流量才会到达同一个 relay 部署。 端到端流程： - 1. 安装一个使用相同 relay base URL 编译的官方/TestFlight iOS 构建版本。 - 2. 在 Gateway 网关 上配置 `gateway.push.apns.relay.baseUrl`。 - 3. 将 iOS 应用与 Gateway 网关 配对，并让节点会话和操作员会话都建立连接。 - 4. iOS 应用获取 Gateway 网关 身份，使用 App Attest 和应用收据向 relay 注册，然后将基于 relay 的 `push.apns.register` 负载发布到已配对的 Gateway 网关。 - 5. Gateway 网关 存储 relay 句柄和发送授权，然后将它们用于 `push.test`、唤醒提示和重连唤醒。 + 1. 安装一个使用相同 relay 基础 URL 编译的官方/TestFlight iOS 构建。 + 2. 在 Gateway 网关上配置 `gateway.push.apns.relay.baseUrl`。 + 3. 将 iOS 应用与 Gateway 网关配对，并让节点会话与操作员会话都建立连接。 + 4. iOS 应用获取 Gateway 网关身份，使用 App Attest 和应用收据向 relay 注册，然后将基于 relay 的 `push.apns.register` 负载发布到已配对的 Gateway 网关。 + 5. Gateway 网关存储 relay 句柄和发送授权，然后将它们用于 `push.test`、唤醒提示和重连唤醒。 - 运行说明： + 运维说明： - - 如果你将 iOS 应用切换到另一个 Gateway 网关，请重新连接应用，以便它发布绑定到该 Gateway 网关 的新 relay 注册信息。 - - 如果你发布了一个指向不同 relay 部署的新 iOS 构建版本，应用会刷新其缓存的 relay 注册信息，而不是复用旧的 relay 来源。 + - 如果你将 iOS 应用切换到另一个 Gateway 网关，请重新连接该应用，以便它发布一个绑定到新 Gateway 网关的 relay 注册。 + - 如果你发布了一个指向不同 relay 部署的新 iOS 构建，应用会刷新其缓存的 relay 注册，而不是复用旧的 relay 来源。 兼容性说明： - `OPENCLAW_APNS_RELAY_BASE_URL` 和 `OPENCLAW_APNS_RELAY_TIMEOUT_MS` 仍可作为临时环境变量覆盖项使用。 - - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍然只是一个仅限 local loopback 的开发逃生口；不要在配置中持久保存 HTTP relay URL。 + - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍然只是一个仅限 loopback 的开发逃生口；不要在配置中持久化 HTTP relay URL。 - 有关端到端流程，请参见 [iOS App](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)；有关 relay 安全模型，请参见 [Authentication and trust flow](/zh-CN/platforms/ios#authentication-and-trust-flow)。 + 端到端流程请参阅 [iOS App](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)，relay 安全模型请参阅[认证与信任流程](/zh-CN/platforms/ios#authentication-and-trust-flow)。 - + ```json5 { agents: { @@ -384,10 +371,10 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次 } ``` - - `every`：时长字符串（`30m`、`2h`）。设置为 `0m` 可禁用。 + - `every`：时长字符串（`30m`、`2h`）。设为 `0m` 可禁用。 - `target`：`last` | `none` | ``（例如 `discord`、`matrix`、`telegram` 或 `whatsapp`） - - `directPolicy`：对于私信式心跳目标，可设为 `allow`（默认）或 `block` - - 完整指南请参见 [Heartbeat](/zh-CN/gateway/heartbeat)。 + - `directPolicy`：用于私信类 heartbeat 目标时，可设为 `allow`（默认）或 `block` + - 完整指南请参阅 [Heartbeat](/zh-CN/gateway/heartbeat)。 @@ -406,14 +393,14 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次 } ``` - - `sessionRetention`：从 `sessions.json` 中清理已完成的隔离运行会话（默认 `24h`；设置为 `false` 可禁用）。 + - `sessionRetention`：从 `sessions.json` 中清理已完成的隔离运行会话（默认 `24h`；设为 `false` 可禁用）。 - `runLog`：按大小和保留行数清理 `cron/runs/.jsonl`。 - - 功能概览和 CLI 示例请参见 [Cron jobs](/zh-CN/automation/cron-jobs)。 + - 功能概览和 CLI 示例请参阅 [Cron jobs](/zh-CN/automation/cron-jobs)。 - - 在 Gateway 网关 上启用 HTTP webhook 端点： + + 在 Gateway 网关上启用 HTTP webhook 端点： ```json5 { @@ -437,20 +424,20 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次 ``` 安全说明： - - 将所有 hook/webhook 负载内容都视为不可信输入。 + - 将所有 hook/webhook 负载内容都视为不受信任的输入。 - 使用专用的 `hooks.token`；不要复用共享的 Gateway 网关 token。 - - Hook 身份验证仅支持请求头（`Authorization: Bearer ...` 或 `x-openclaw-token`）；查询字符串 token 会被拒绝。 - - `hooks.path` 不能为 `/`；请将 webhook 入口保留在专用子路径下，例如 `/hooks`。 - - 保持不安全内容绕过标志为禁用状态（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`），除非你是在进行严格限定范围的调试。 - - 如果你启用了 `hooks.allowRequestSessionKey`，也要同时设置 `hooks.allowedSessionKeyPrefixes`，以限制调用方可选的会话键。 - - 对于由 hook 驱动的智能体，优先使用强大的现代模型层级和严格的工具策略（例如仅消息传递，并在可能时启用沙箱隔离）。 + - Hook 认证仅支持请求头（`Authorization: Bearer ...` 或 `x-openclaw-token`）；查询字符串中的 token 会被拒绝。 + - `hooks.path` 不能是 `/`；请将 webhook 入口放在专用子路径下，例如 `/hooks`。 + - 除非进行严格限定范围的调试，否则请保持不安全内容绕过标志为禁用状态（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`）。 + - 如果你启用了 `hooks.allowRequestSessionKey`，也请设置 `hooks.allowedSessionKeyPrefixes`，以限制调用方可选的会话键名范围。 + - 对于由 hook 驱动的智能体，请优先使用强大的现代模型层级和严格的工具策略（例如仅限消息传递，并尽可能启用沙箱隔离）。 - 有关所有映射选项和 Gmail 集成，请参见[完整参考](/zh-CN/gateway/configuration-reference#hooks)。 + 所有映射选项和 Gmail 集成请参阅[完整参考](/zh-CN/gateway/configuration-reference#hooks)。 - 运行多个相互隔离的智能体，并为其分配独立的工作区和会话： + 运行多个相互隔离的智能体，并为其使用单独的工作区和会话： ```json5 { @@ -467,12 +454,12 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次 } ``` - 绑定规则和每个智能体的访问配置文件，请参见 [Multi-Agent](/zh-CN/concepts/multi-agent) 和[完整参考](/zh-CN/gateway/configuration-reference#multi-agent-routing)。 + 绑定规则和每个智能体的访问配置请参阅[多智能体](/zh-CN/concepts/multi-agent)和[完整参考](/zh-CN/gateway/configuration-reference#multi-agent-routing)。 - 使用 `$include` 来组织大型配置： + 使用 `$include` 组织大型配置： ```json5 // ~/.openclaw/openclaw.json @@ -485,17 +472,13 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次 } ``` - - **单个文件**：替换所在对象 + - **单个文件**：替换包含它的对象 - **文件数组**：按顺序深度合并（后者优先） - - **同级键**：在 include 之后再合并（覆盖引入的值） + - **同级键名**：在 include 之后合并（覆盖被包含的值） - **嵌套 include**：支持，最多 10 层 - **相对路径**：相对于包含它的文件解析 - - **由 OpenClaw 发起的写入**：当一次写入只更改一个由单文件 include - 支撑的顶层部分时，例如 `plugins: { $include: "./plugins.json5" }`， - OpenClaw 会更新该被引入文件，并保持 `openclaw.json` 不变 - - **不支持透传写入**：对于根级 include、include 数组以及带有 - 同级覆盖的 include，OpenClaw 发起的写入会以封闭失败方式终止，而不是 - 将配置拍平 + - **OpenClaw 自有写入**：当一次写入只更改一个由单文件 include 支持的顶层部分时，例如 `plugins: { $include: "./plugins.json5" }`，OpenClaw 会更新该被包含文件，并保持 `openclaw.json` 不变 + - **不支持的透传写入**：根级 include、include 数组，以及带有同级覆盖的 include，对于 OpenClaw 自有写入会以“失败即关闭”的方式处理，而不是将配置展平 - **错误处理**：对缺失文件、解析错误和循环 include 提供清晰错误信息 @@ -503,27 +486,20 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次 ## 配置热重载 -Gateway 网关 会监视 `~/.openclaw/openclaw.json` 并自动应用更改 —— 对于大多数设置，无需手动重启。 +Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改——对于大多数设置，无需手动重启。 -直接编辑文件会在通过校验前被视为不可信。监视器会等待 -编辑器的临时写入/重命名抖动稳定下来，读取最终文件，并通过恢复 -“上次已知正常”配置来拒绝无效的外部编辑。由 OpenClaw 发起的 -配置写入在落盘前也会经过相同的 schema 校验；具有破坏性的覆盖行为，例如 -删除 `gateway.mode` 或将文件缩小到原来的一半以下，会被拒绝， -并保存为 `.rejected.*` 以供检查。 +直接编辑文件会在通过校验前被视为不受信任。监视器会等待编辑器临时写入/重命名抖动稳定下来，读取最终文件，并通过恢复“最后一次已知正常”配置来拒绝无效的外部编辑。OpenClaw 自有的配置写入也会在写入前经过相同的 schema 关卡；诸如删除 `gateway.mode` 或将文件缩小到原来一半以下之类的破坏性覆盖会被拒绝，并保存为 `.rejected.*` 以供检查。 如果你在日志中看到 `Config auto-restored from last-known-good` 或 -`config reload restored last-known-good config`，请检查 `openclaw.json` 旁边对应的 -`.clobbered.*` 文件，修复被拒绝的负载，然后运行 -`openclaw config validate`。恢复检查清单请参见[Gateway 网关 故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。 +`config reload restored last-known-good config`，请检查 `openclaw.json` 旁边对应的 `.clobbered.*` 文件，修复被拒绝的负载，然后运行 `openclaw config validate`。恢复检查清单请参阅 [Gateway 故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。 ### 重载模式 | 模式 | 行为 | | ---------------------- | --------------------------------------------------------------------------------------- | | **`hybrid`**（默认） | 立即热应用安全更改。对关键更改自动重启。 | -| **`hot`** | 仅热应用安全更改。当需要重启时记录警告 —— 由你手动处理。 | -| **`restart`** | 对任何配置更改都重启 Gateway 网关，无论是否安全。 | +| **`hot`** | 仅热应用安全更改。当需要重启时记录警告——由你自行处理。 | +| **`restart`** | 任何配置更改都会重启 Gateway 网关，无论是否安全。 | | **`off`** | 禁用文件监视。更改会在下一次手动重启时生效。 | ```json5 @@ -534,64 +510,54 @@ Gateway 网关 会监视 `~/.openclaw/openclaw.json` 并自动应用更改 — } ``` -### 哪些可以热应用，哪些需要重启 +### 哪些可热应用，哪些需要重启 大多数字段都可以无停机热应用。在 `hybrid` 模式下，需要重启的更改会自动处理。 | 类别 | 字段 | 需要重启？ | | ------------------- | ----------------------------------------------------------------- | --------------- | -| 渠道 | `channels.*`、`web`（WhatsApp）—— 所有内置和插件渠道 | 否 | -| 智能体和模型 | `agent`、`agents`、`models`、`routing` | 否 | +| 渠道 | `channels.*`、`web`（WhatsApp）——所有内置和插件渠道 | 否 | +| 智能体与模型 | `agent`、`agents`、`models`、`routing` | 否 | | 自动化 | `hooks`、`cron`、`agent.heartbeat` | 否 | -| 会话和消息 | `session`、`messages` | 否 | -| 工具和媒体 | `tools`、`browser`、`skills`、`audio`、`talk` | 否 | -| UI 和其他 | `ui`、`logging`、`identity`、`bindings` | 否 | -| Gateway 网关 服务器 | `gateway.*`（port、bind、auth、tailscale、TLS、HTTP） | **是** | +| 会话与消息 | `session`、`messages` | 否 | +| 工具与媒体 | `tools`、`browser`、`skills`、`audio`、`talk` | 否 | +| UI 与其他 | `ui`、`logging`、`identity`、`bindings` | 否 | +| Gateway 网关服务器 | `gateway.*`（port、bind、auth、Tailscale、TLS、HTTP） | **是** | | 基础设施 | `discovery`、`canvasHost`、`plugins` | **是** | -`gateway.reload` 和 `gateway.remote` 是例外 —— 更改它们**不会**触发重启。 +`gateway.reload` 和 `gateway.remote` 是例外——更改它们**不会**触发重启。 ### 重载规划 -当你编辑一个通过 `$include` 引用的源文件时，OpenClaw 会基于 -源文件编写时的布局来规划重载，而不是基于拍平后的内存视图。 -这样即使某个单独的顶层部分位于其自己的被引入文件中，例如 -`plugins: { $include: "./plugins.json5" }`，热重载决策（热应用还是重启）也能保持可预测。 -如果源布局存在歧义，重载规划会以封闭失败方式终止。 +当你编辑一个通过 `$include` 引用的源文件时，OpenClaw 会根据源作者编写的布局来规划重载，而不是根据展平后的内存视图。即使某个顶层部分单独存在于一个被包含文件中，例如 `plugins: { $include: "./plugins.json5" }`，这也能让热重载决策（热应用还是重启）保持可预测。如果源布局存在歧义，重载规划会以“失败即关闭”的方式处理。 -## 配置 RPC（程序化更新） +## 配置 RPC（编程式更新） 对于通过 Gateway 网关 API 写入配置的工具，推荐使用以下流程： -- 使用 `config.schema.lookup` 检查一个子树（浅层 schema 节点 + 子节点 - 摘要） -- 使用 `config.get` 获取当前快照及其 `hash` -- 使用 `config.patch` 进行部分更新（JSON merge patch：对象合并，`null` - 表示删除，数组整体替换） -- 仅当你确实打算替换整个配置时，才使用 `config.apply` -- 使用 `update.run` 显式执行自更新并重启 +- 使用 `config.schema.lookup` 检查一个子树（浅层 schema 节点 + 子节点摘要） +- 使用 `config.get` 获取当前快照和 `hash` +- 使用 `config.patch` 执行部分更新（JSON merge patch：对象合并，`null` 删除，数组替换） +- 仅在你打算替换整个配置时使用 `config.apply` +- 使用 `update.run` 执行显式自更新并重启 -控制平面写入（`config.apply`、`config.patch`、`update.run`） -按每个 `deviceId+clientIp` 限流为每 60 秒 3 次请求。 -重启请求会被合并，然后在两次重启周期之间强制执行 30 秒冷却时间。 +控制平面写入（`config.apply`、`config.patch`、`update.run`）按每个 `deviceId+clientIp` 限制为每 60 秒 3 次请求。重启请求会被合并处理，并在两次重启周期之间强制执行 30 秒冷却时间。 部分 patch 示例： ```bash -openclaw gateway call config.get --params '{}' # capture payload.hash +openclaw gateway call config.get --params '{}' # 捕获 payload.hash openclaw gateway call config.patch --params '{ "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }", "baseHash": "" }' ``` -`config.apply` 和 `config.patch` 都接受 `raw`、`baseHash`、`sessionKey`、 -`note` 和 `restartDelayMs`。当配置已存在时，这两种方法都要求提供 -`baseHash`。 +`config.apply` 和 `config.patch` 都接受 `raw`、`baseHash`、`sessionKey`、`note` 和 `restartDelayMs`。如果配置已存在，这两种方法都要求提供 `baseHash`。 ## 环境变量 @@ -611,8 +577,8 @@ OpenClaw 会从父进程读取环境变量，此外还包括： } ``` - - 如果启用，并且预期键名尚未设置，OpenClaw 会运行你的登录 shell，并且只导入缺失的键名： + + 如果启用，且预期键名未设置，OpenClaw 会运行你的登录 shell，并只导入缺失的键名： ```json5 { @@ -622,11 +588,11 @@ OpenClaw 会从父进程读取环境变量，此外还包括： } ``` -对应的环境变量：`OPENCLAW_LOAD_SHELL_ENV=1` +环境变量等价写法：`OPENCLAW_LOAD_SHELL_ENV=1` - 可在任意配置字符串值中使用 `${VAR_NAME}` 引用环境变量： + 在任意配置字符串值中使用 `${VAR_NAME}` 引用环境变量： ```json5 { @@ -638,9 +604,9 @@ OpenClaw 会从父进程读取环境变量，此外还包括： 规则： - 仅匹配大写名称：`[A-Z_][A-Z0-9_]*` -- 缺失或为空的变量会在加载时报错 +- 缺失或为空的变量会在加载时抛出错误 - 使用 `$${VAR}` 转义以输出字面量 -- 在 `$include` 文件中同样有效 +- 在 `$include` 文件中同样适用 - 内联替换：`"${BASE}/v1"` → `"https://api.example.com/v1"` @@ -678,16 +644,16 @@ OpenClaw 会从父进程读取环境变量，此外还包括： } ``` -有关 SecretRef 的详细信息（包括用于 `env`/`file`/`exec` 的 `secrets.providers`），请参见[Secrets Management](/zh-CN/gateway/secrets)。 -支持的凭证路径列在 [SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface) 中。 +有关 SecretRef 的详细信息（包括用于 `env`/`file`/`exec` 的 `secrets.providers`），请参阅[密钥管理](/zh-CN/gateway/secrets)。 +支持的凭证路径列于 [SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface)。 -有关完整的优先级和来源，请参见[环境](/zh-CN/help/environment)。 +完整优先级和来源请参阅[环境变量](/zh-CN/help/environment)。 ## 完整参考 -有关完整的逐字段参考，请参见 **[配置参考](/zh-CN/gateway/configuration-reference)**。 +完整的逐字段参考请参阅 **[配置参考](/zh-CN/gateway/configuration-reference)**。 --- -_相关内容：[Configuration Examples](/zh-CN/gateway/configuration-examples) · [配置参考](/zh-CN/gateway/configuration-reference) · [Doctor](/zh-CN/gateway/doctor)_ +_相关内容：[配置示例](/zh-CN/gateway/configuration-examples) · [配置参考](/zh-CN/gateway/configuration-reference) · [Doctor](/zh-CN/gateway/doctor)_ diff --git a/docs/zh-CN/gateway/openai-http-api.md b/docs/zh-CN/gateway/openai-http-api.md index 611dbdbd7..6b5eda4ac 100644 --- a/docs/zh-CN/gateway/openai-http-api.md +++ b/docs/zh-CN/gateway/openai-http-api.md @@ -1,110 +1,108 @@ --- read_when: - - 集成那些期望使用 OpenAI Chat Completions 的工具 -summary: 从 Gateway 网关暴露 OpenAI 兼容的 `/v1/chat/completions` HTTP 端点 + - 集成那些需要 OpenAI Chat Completions 的工具 +summary: 从 Gateway 网关公开一个兼容 OpenAI 的 `/v1/chat/completions` HTTP 端点 title: OpenAI Chat Completions x-i18n: - generated_at: "2026-04-05T08:24:20Z" + generated_at: "2026-04-23T19:24:38Z" model: gpt-5.4 provider: openai - source_hash: c374b2f32ce693a8c752e2b0a2532c5f0299ed280f9a0e97b1a9d73bcec37b95 + source_hash: 36f09a82d96bbbc78ba325572dda1524857a534629398582a0bfc007f427b61c source_path: gateway/openai-http-api.md workflow: 15 --- # OpenAI Chat Completions（HTTP） -OpenClaw 的 Gateway 网关可以提供一个小型的 OpenAI 兼容 Chat Completions 端点。 +OpenClaw 的 Gateway 网关可以提供一个小型的、兼容 OpenAI 的 Chat Completions 端点。 该端点**默认禁用**。请先在配置中启用它。 - `POST /v1/chat/completions` - 与 Gateway 网关相同的端口（WS + HTTP 复用）：`http://:/v1/chat/completions` -当启用 Gateway 网关的 OpenAI 兼容 HTTP 表面时，它还会提供： +当启用 Gateway 网关兼容 OpenAI 的 HTTP 接口后，它还会提供： - `GET /v1/models` - `GET /v1/models/{id}` - `POST /v1/embeddings` - `POST /v1/responses` -在底层，请求会作为普通的 Gateway 网关智能体运行来执行（与 `openclaw agent` 使用同一条代码路径），因此路由/权限/配置与你的 Gateway 网关保持一致。 +在底层，请求会作为一次普通的 Gateway 智能体运行来执行（与 `openclaw agent` 使用相同代码路径），因此路由/权限/配置都与你的 Gateway 网关保持一致。 -## 认证 +## 身份验证 -使用 Gateway 网关认证配置。 +使用 Gateway 网关的身份验证配置。 -常见的 HTTP 认证路径： +常见的 HTTP 身份验证路径： -- 共享密钥认证（`gateway.auth.mode="token"` 或 `"password"`）： +- 共享密钥身份验证（`gateway.auth.mode="token"` 或 `"password"`）： `Authorization: Bearer ` -- 受信任的带身份 HTTP 认证（`gateway.auth.mode="trusted-proxy"`）： - 通过已配置的身份感知代理进行路由，并让它注入所需的身份头 -- 私有入口开放认证（`gateway.auth.mode="none"`）： - 不需要认证头 +- 受信任的携带身份信息的 HTTP 身份验证（`gateway.auth.mode="trusted-proxy"`）： + 通过已配置的身份感知代理进行路由，并让它注入所需的身份标头 +- 私有入口开放身份验证（`gateway.auth.mode="none"`）： + 不需要身份验证标头 -注意事项： +说明： - 当 `gateway.auth.mode="token"` 时，使用 `gateway.auth.token`（或 `OPENCLAW_GATEWAY_TOKEN`）。 - 当 `gateway.auth.mode="password"` 时，使用 `gateway.auth.password`（或 `OPENCLAW_GATEWAY_PASSWORD`）。 -- 当 `gateway.auth.mode="trusted-proxy"` 时，HTTP 请求必须来自 - 已配置的非 loopback 受信任代理源；同主机上的 loopback 代理 - 不满足此模式。 -- 如果配置了 `gateway.auth.rateLimit` 且认证失败次数过多，端点会返回 `429`，并带有 `Retry-After`。 +- 当 `gateway.auth.mode="trusted-proxy"` 时，HTTP 请求必须来自已配置的非 loopback 受信任代理来源；同主机 loopback 代理不满足该模式要求。 +- 如果已配置 `gateway.auth.rateLimit` 且身份验证失败次数过多，端点会返回 `429` 并附带 `Retry-After`。 ## 安全边界（重要） -请将该端点视为此 Gateway 网关实例的**完整操作员访问**表面。 +请将此端点视为该 Gateway 网关实例的**完整操作员访问**接口。 -- 这里的 HTTP bearer 认证不是狭义的按用户划分作用域模型。 -- 对此端点有效的 Gateway 网关 token/password 应被视为所有者/操作员凭证。 -- 请求会经过与受信任操作员操作相同的控制平面智能体路径。 -- 此端点上不存在单独的非所有者/按用户划分的工具边界；一旦调用方通过了这里的 Gateway 网关认证，OpenClaw 就会将该调用方视为此 Gateway 网关的受信任操作员。 -- 对于共享密钥认证模式（`token` 和 `password`），即使调用方发送了更窄的 `x-openclaw-scopes` 头，端点也会恢复正常的完整操作员默认值。 -- 受信任的带身份 HTTP 模式（例如 trusted proxy 认证或私有入口上的 `gateway.auth.mode="none"`）在提供 `x-openclaw-scopes` 时会遵从它，否则会回退到正常的操作员默认作用域集。 -- 如果目标智能体策略允许敏感工具，此端点就可以使用它们。 -- 请仅在 loopback/tailnet/私有入口上保留此端点；不要将其直接暴露到公共互联网。 +- 这里的 HTTP bearer 身份验证不是一个狭义的按用户划分的作用域模型。 +- 该端点的有效 Gateway 网关 token/password 应被视为所有者/操作员凭证。 +- 请求会通过与受信任操作员操作相同的控制平面智能体路径运行。 +- 此端点上没有单独的非所有者/按用户划分的工具边界；一旦调用方通过了这里的 Gateway 网关身份验证，OpenClaw 就会将该调用方视为此 Gateway 网关的受信任操作员。 +- 对于共享密钥身份验证模式（`token` 和 `password`），即使调用方发送了更窄的 `x-openclaw-scopes` 标头，该端点也会恢复正常的完整操作员默认设置。 +- 对于受信任的携带身份信息的 HTTP 模式（例如 trusted proxy 身份验证或 `gateway.auth.mode="none"`），存在 `x-openclaw-scopes` 时会遵循它，否则会回退到正常的操作员默认作用域集合。 +- 如果目标智能体策略允许敏感工具，此端点也可以使用它们。 +- 请仅在 loopback/tailnet/私有入口上使用此端点；不要将其直接暴露到公共互联网。 -认证矩阵： +身份验证矩阵： - `gateway.auth.mode="token"` 或 `"password"` + `Authorization: Bearer ...` - - 证明持有共享的 Gateway 网关操作员密钥 + - 证明持有共享 Gateway 网关操作员密钥 - 忽略更窄的 `x-openclaw-scopes` - - 恢复完整的默认操作员作用域集： - `operator.admin`、`operator.approvals`、`operator.pairing`、 - `operator.read`、`operator.talk.secrets`、`operator.write` - - 将此端点上的聊天回合视为所有者发送者回合 -- 受信任的带身份 HTTP 模式（例如 trusted proxy 认证，或私有入口上的 `gateway.auth.mode="none"`） - - 认证某个外层受信任身份或部署边界 - - 在头存在时遵从 `x-openclaw-scopes` - - 在头缺失时回退到正常的操作员默认作用域集 - - 只有当调用方显式缩窄作用域且省略 `operator.admin` 时，才会失去所有者语义 + - 恢复完整的默认操作员作用域集合： + `operator.admin`, `operator.approvals`, `operator.pairing`, + `operator.read`, `operator.talk.secrets`, `operator.write` + - 将该端点上的聊天轮次视为所有者发送者轮次 +- 受信任的携带身份信息的 HTTP 模式（例如 trusted proxy 身份验证，或私有入口上的 `gateway.auth.mode="none"`） + - 对某种外层受信任身份或部署边界进行身份验证 + - 当标头存在时遵循 `x-openclaw-scopes` + - 当标头缺失时回退到正常的操作员默认作用域集合 + - 仅当调用方显式收窄作用域并省略 `operator.admin` 时，才会失去所有者语义 -请参阅 [Security](/gateway/security) 和 [Remote access](/gateway/remote)。 +参见 [安全性](/zh-CN/gateway/security) 和 [远程访问](/zh-CN/gateway/remote)。 -## 以智能体为先的模型契约 +## 智能体优先的模型契约 -OpenClaw 将 OpenAI `model` 字段视为**智能体目标**，而不是原始提供商模型 ID。 +OpenClaw 将 OpenAI `model` 字段视为**智能体目标**，而不是原始提供商模型 id。 - `model: "openclaw"` 会路由到已配置的默认智能体。 - `model: "openclaw/default"` 也会路由到已配置的默认智能体。 -- `model: "openclaw/"` 会路由到某个特定智能体。 +- `model: "openclaw/"` 会路由到特定智能体。 -可选请求头： +可选请求标头： -- `x-openclaw-model: ` 会为所选智能体覆盖后端模型。 -- `x-openclaw-agent-id: ` 仍作为兼容性覆盖受支持。 +- `x-openclaw-model: ` 会覆盖所选智能体的后端模型。 +- `x-openclaw-agent-id: ` 仍作为兼容性覆盖项受支持。 - `x-openclaw-session-key: ` 可完全控制会话路由。 -- `x-openclaw-message-channel: ` 可为具备渠道感知的提示词和策略设置合成入站渠道上下文。 +- `x-openclaw-message-channel: ` 会为感知渠道的提示词和策略设置合成入口渠道上下文。 -仍然接受的兼容性别名： +仍然接受的兼容别名： - `model: "openclaw:"` - `model: "agent:"` -## 启用该端点 +## 启用端点 -将 `gateway.http.endpoints.chatCompletions.enabled` 设为 `true`： +将 `gateway.http.endpoints.chatCompletions.enabled` 设置为 `true`： ```json5 { @@ -118,9 +116,9 @@ OpenClaw 将 OpenAI `model` 字段视为**智能体目标**，而不是原始提 } ``` -## 禁用该端点 +## 禁用端点 -将 `gateway.http.endpoints.chatCompletions.enabled` 设为 `false`： +将 `gateway.http.endpoints.chatCompletions.enabled` 设置为 `false`： ```json5 { @@ -136,57 +134,57 @@ OpenClaw 将 OpenAI `model` 字段视为**智能体目标**，而不是原始提 ## 会话行为 -默认情况下，该端点对每个请求都是**无状态**的（每次调用都会生成一个新的会话键）。 +默认情况下，此端点对每个请求都是**无状态的**（每次调用都会生成一个新的会话键）。 -如果请求中包含 OpenAI `user` 字符串，Gateway 网关会从中派生一个稳定的会话键，因此重复调用可以共享同一个智能体会话。 +如果请求包含 OpenAI `user` 字符串，Gateway 网关会基于它派生出一个稳定的会话键，因此重复调用可以共享同一个智能体会话。 -## 为什么这个表面很重要 +## 为什么这个接口很重要 -这是对自托管前端和工具最有杠杆作用的一组兼容接口： +这是对自托管前端和工具最有价值的一组兼容接口： -- 大多数 Open WebUI、LobeChat 和 LibreChat 部署都期望 `/v1/models`。 -- 许多 RAG 系统都期望 `/v1/embeddings`。 -- 现有的 OpenAI 聊天客户端通常可以从 `/v1/chat/completions` 开始。 -- 更偏向智能体原生的客户端则越来越倾向于 `/v1/responses`。 +- 大多数 Open WebUI、LobeChat 和 LibreChat 配置都需要 `/v1/models`。 +- 许多 RAG 系统需要 `/v1/embeddings`。 +- 现有的 OpenAI 聊天客户端通常可以从 `/v1/chat/completions` 开始接入。 +- 更偏向智能体原生的客户端则越来越倾向于使用 `/v1/responses`。 -## 模型列表和智能体路由 +## 模型列表与智能体路由 一个 OpenClaw 智能体目标列表。 - 返回的 ID 为 `openclaw`、`openclaw/default` 以及 `openclaw/` 条目。 + 返回的 id 包括 `openclaw`、`openclaw/default` 和 `openclaw/` 条目。 直接将它们用作 OpenAI `model` 值即可。 它列出的是顶层智能体目标，不是后端提供商模型，也不是子智能体。 - 子智能体仍然是内部执行拓扑的一部分。它们不会显示为伪模型。 + 子智能体仍然属于内部执行拓扑。它们不会作为伪模型出现。 `openclaw/default` 是已配置默认智能体的稳定别名。 - 这意味着即使不同环境中的真实默认智能体 ID 发生变化，客户端也可以继续使用同一个可预测的 ID。 + 这意味着即使不同环境中的真实默认智能体 id 发生变化，客户端仍可持续使用同一个可预测 id。 使用 `x-openclaw-model`。 示例： - `x-openclaw-model: openai/gpt-5.4` - `x-openclaw-model: gpt-5.4` + `x-openclaw-model: openai/gpt-5.5` + `x-openclaw-model: gpt-5.5` - 如果省略它，所选智能体会使用其正常配置的模型选择运行。 + 如果省略它，所选智能体会按其正常配置的模型选择运行。 - `/v1/embeddings` 使用相同的智能体目标 `model` ID。 + `/v1/embeddings` 使用相同的智能体目标 `model` id。 使用 `model: "openclaw/default"` 或 `model: "openclaw/"`。 - 当你需要特定 embedding 模型时，请通过 `x-openclaw-model` 发送。 - 如果没有该头，请求会传递到所选智能体的正常 embedding 设置。 + 当你需要特定的嵌入模型时，请在 `x-openclaw-model` 中发送它。 + 如果没有该标头，请求会透传到所选智能体的常规嵌入配置。 @@ -201,18 +199,18 @@ OpenClaw 将 OpenAI `model` 字段视为**智能体目标**，而不是原始提 ## Open WebUI 快速设置 -对于基本的 Open WebUI 连接： +进行基本的 Open WebUI 连接时： - 基础 URL：`http://127.0.0.1:18789/v1` - macOS 上 Docker 的基础 URL：`http://host.docker.internal:18789/v1` -- API key：你的 Gateway 网关 bearer token +- API 密钥：你的 Gateway 网关 bearer token - 模型：`openclaw/default` 预期行为： - `GET /v1/models` 应列出 `openclaw/default` -- Open WebUI 应使用 `openclaw/default` 作为聊天模型 ID -- 如果你希望该智能体使用特定的后端提供商/模型，请设置该智能体正常的默认模型，或发送 `x-openclaw-model` +- Open WebUI 应使用 `openclaw/default` 作为聊天模型 id +- 如果你想为该智能体指定特定后端提供商/模型，请设置该智能体的常规默认模型，或发送 `x-openclaw-model` 快速冒烟测试： @@ -221,7 +219,7 @@ curl -sS http://127.0.0.1:18789/v1/models \ -H 'Authorization: Bearer YOUR_TOKEN' ``` -如果该请求返回 `openclaw/default`，大多数 Open WebUI 部署就可以使用相同的基础 URL 和 token 连接。 +如果返回了 `openclaw/default`，大多数 Open WebUI 配置都可以使用相同的基础 URL 和 token 进行连接。 ## 示例 @@ -243,7 +241,7 @@ curl -sS http://127.0.0.1:18789/v1/chat/completions \ curl -N http://127.0.0.1:18789/v1/chat/completions \ -H 'Authorization: Bearer YOUR_TOKEN' \ -H 'Content-Type: application/json' \ - -H 'x-openclaw-model: openai/gpt-5.4' \ + -H 'x-openclaw-model: openai/gpt-5.5' \ -d '{ "model": "openclaw/research", "stream": true, @@ -278,9 +276,9 @@ curl -sS http://127.0.0.1:18789/v1/embeddings \ }' ``` -注意事项： +说明： - `/v1/models` 返回的是 OpenClaw 智能体目标，而不是原始提供商目录。 -- `openclaw/default` 始终存在，因此一个稳定 ID 就可跨环境使用。 -- 后端提供商/模型覆盖应放在 `x-openclaw-model` 中，而不是 OpenAI `model` 字段中。 +- `openclaw/default` 始终存在，因此同一个稳定 id 可在不同环境中使用。 +- 后端提供商/模型覆盖项应放在 `x-openclaw-model` 中，而不是 OpenAI `model` 字段中。 - `/v1/embeddings` 支持将 `input` 作为字符串或字符串数组。 diff --git a/docs/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated.md b/docs/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated.md index 5639ced14..0de2faf14 100644 --- a/docs/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated.md +++ b/docs/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated.md @@ -1,28 +1,28 @@ --- read_when: You hit 'sandbox jail' or see a tool/elevated refusal and want the exact config key to change. status: active -summary: 为什么工具会被阻止：沙箱运行时、工具允许/拒绝策略，以及提权执行门禁 -title: 沙箱与工具策略与提权执行的区别 +summary: 工具为何会被阻止：沙箱运行时、工具允许/拒绝策略，以及提权执行门禁 +title: 沙箱 vs 工具策略 vs 提权执行 x-i18n: - generated_at: "2026-04-20T18:29:33Z" + generated_at: "2026-04-23T19:24:40Z" model: gpt-5.4 provider: openai - source_hash: a85378343df0594be451212cb4c95b349a0cc7cd1f242b9306be89903a450db1 + source_hash: cfc54cdb1adbe37a2cfa837560d3d3862c1aa2732dcb8a73377114d4b873e569 source_path: gateway/sandbox-vs-tool-policy-vs-elevated.md workflow: 15 --- -# 沙箱与工具策略与提权执行的区别 +# 沙箱 vs 工具策略 vs 提权执行 -OpenClaw 有三种相关但不同的控制方式： +OpenClaw 有三个相关但不同的控制项： 1. **沙箱**（`agents.defaults.sandbox.*` / `agents.list[].sandbox.*`）决定**工具在哪里运行**（沙箱后端还是主机）。 -2. **工具策略**（`tools.*`、`tools.sandbox.tools.*`、`agents.list[].tools.*`）决定**哪些工具可用 / 被允许**。 -3. **提权执行**（`tools.elevated.*`、`agents.list[].tools.elevated.*`）是一个**仅限 exec 的逃生通道**：当你处于沙箱中时，可用于在沙箱外运行（默认是 `gateway`，或者当 exec 目标被配置为 `node` 时使用 `node`）。 +2. **工具策略**（`tools.*`、`tools.sandbox.tools.*`、`agents.list[].tools.*`）决定**哪些工具可用/允许使用**。 +3. **提权执行**（`tools.elevated.*`、`agents.list[].tools.elevated.*`）是一个**仅针对 exec 的逃逸通道**：当你处于沙箱中时，可让其在沙箱外运行（默认是 `gateway`，或者当 exec 目标配置为 `node` 时使用 `node`）。 ## 快速调试 -使用检查器查看 OpenClaw **实际**在做什么： +使用检查器查看 OpenClaw _实际_ 在做什么： ```bash openclaw sandbox explain @@ -33,9 +33,9 @@ openclaw sandbox explain --json 它会输出： -- 生效的沙箱模式 / 作用域 / 工作区访问权限 -- 当前会话是否处于沙箱中（主会话与非主会话） -- 生效的沙箱工具允许 / 拒绝设置（以及它来自智能体 / 全局 / 默认配置中的哪一层） +- 生效中的沙箱模式 / 作用域 / 工作区访问权限 +- 当前会话是否处于沙箱中（主会话 vs 非主会话） +- 生效中的沙箱工具允许 / 拒绝规则（以及其来源是智能体 / 全局 / 默认值） - 提权执行门禁和修复建议键路径 ## 沙箱：工具在哪里运行 @@ -43,20 +43,20 @@ openclaw sandbox explain --json 沙箱隔离由 `agents.defaults.sandbox.mode` 控制： - `"off"`：所有内容都在主机上运行。 -- `"non-main"`：只有非主会话会进入沙箱（这是群组 / 渠道场景中常见的“意外”来源）。 +- `"non-main"`：只有非主会话会被沙箱隔离（这是群组 / 渠道中常见的“意外”来源）。 - `"all"`：所有内容都在沙箱中运行。 完整矩阵（作用域、工作区挂载、镜像）请参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 ### 绑定挂载（安全快速检查） -- `docker.binds` 会**穿透**沙箱文件系统：你挂载的任何内容都会以你设置的模式（`:ro` 或 `:rw`）在容器内可见。 -- 如果你省略模式，默认是可读写；对于源码 / 密钥，优先使用 `:ro`。 -- `scope: "shared"` 会忽略每个智能体的独立绑定挂载（只应用全局绑定挂载）。 -- OpenClaw 会对绑定源进行两次校验：先检查规范化后的源路径，然后在通过最深的现有祖先路径解析后再次检查。通过符号链接父目录逃逸，无法绕过被阻止路径或允许根目录检查。 -- 不存在的叶子路径也会被安全检查。如果 `/workspace/alias-out/new-file` 通过一个符号链接父目录解析到被阻止路径，或超出已配置的允许根目录范围，该绑定挂载会被拒绝。 -- 挂载 `/var/run/docker.sock` 实际上等于把主机控制权交给沙箱；只有在你明确知道自己在做什么时才应这样做。 -- 工作区访问权限（`workspaceAccess: "ro"` / `"rw"`）与绑定挂载模式相互独立。 +- `docker.binds` 会_穿透_沙箱文件系统：你挂载的任何内容都会以你设置的模式（`:ro` 或 `:rw`）出现在容器内。 +- 如果省略模式，默认是读写；对于源码 / 密钥，优先使用 `:ro`。 +- `scope: "shared"` 会忽略按智能体设置的挂载（仅应用全局挂载）。 +- OpenClaw 会对绑定源路径进行两次验证：首先验证规范化后的源路径，然后在通过最深的现有祖先路径解析后再次验证。基于父级符号链接的逃逸无法绕过阻止路径或允许根路径检查。 +- 不存在的叶子路径仍会被安全检查。如果 `/workspace/alias-out/new-file` 通过符号链接父路径解析到某个被阻止的路径，或位于已配置允许根路径之外，则该绑定会被拒绝。 +- 绑定 `/var/run/docker.sock` 实际上等于把主机控制权交给沙箱；只有在你明确有此意图时才应这样做。 +- 工作区访问（`workspaceAccess: "ro"` / `"rw"`）与绑定模式无关。 ## 工具策略：哪些工具存在 / 可调用 @@ -64,21 +64,21 @@ openclaw sandbox explain --json - **工具配置文件**：`tools.profile` 和 `agents.list[].tools.profile`（基础允许列表） - **提供商工具配置文件**：`tools.byProvider[provider].profile` 和 `agents.list[].tools.byProvider[provider].profile` -- **全局 / 每智能体工具策略**：`tools.allow` / `tools.deny` 和 `agents.list[].tools.allow` / `agents.list[].tools.deny` +- **全局 / 按智能体工具策略**：`tools.allow` / `tools.deny` 和 `agents.list[].tools.allow` / `agents.list[].tools.deny` - **提供商工具策略**：`tools.byProvider[provider].allow/deny` 和 `agents.list[].tools.byProvider[provider].allow/deny` -- **沙箱工具策略**（仅在处于沙箱中时生效）：`tools.sandbox.tools.allow` / `tools.sandbox.tools.deny` 和 `agents.list[].tools.sandbox.tools.*` +- **沙箱工具策略**（仅在处于沙箱时生效）：`tools.sandbox.tools.allow` / `tools.sandbox.tools.deny` 和 `agents.list[].tools.sandbox.tools.*` 经验规则： -- `deny` 永远优先。 -- 如果 `allow` 非空，其他所有内容都会被视为已阻止。 +- `deny` 总是优先生效。 +- 如果 `allow` 非空，则其他所有内容都视为被阻止。 - 工具策略是硬性终止条件：`/exec` 不能覆盖被拒绝的 `exec` 工具。 -- `/exec` 只会为已授权发送者修改会话默认值；它不会授予工具访问权限。 - 提供商工具键既可以使用 `provider`（例如 `google-antigravity`），也可以使用 `provider/model`（例如 `openai/gpt-5.4`）。 +- `/exec` 只会为已授权发送者更改会话默认值；它不会授予工具访问权限。 + 提供商工具键可接受 `provider`（例如 `google-antigravity`）或 `provider/model`（例如 `openai/gpt-5.5`）。 ### 工具组（简写） -工具策略（全局、智能体、沙箱）支持 `group:*` 条目，它会展开为多个工具： +工具策略（全局、智能体、沙箱）支持 `group:*` 条目，可展开为多个工具： ```json5 { @@ -92,9 +92,10 @@ openclaw sandbox explain --json } ``` -可用的工具组： +可用组： -- `group:runtime`：`exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名） +- `group:runtime`：`exec`、`process`、`code_execution`（`bash` 可作为 + `exec` 的别名使用） - `group:fs`：`read`、`write`、`edit`、`apply_patch` - `group:sessions`：`sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`sessions_yield`、`subagents`、`session_status` - `group:memory`：`memory_search`、`memory_get` @@ -105,25 +106,25 @@ openclaw sandbox explain --json - `group:nodes`：`nodes` - `group:agents`：`agents_list` - `group:media`：`image`、`image_generate`、`video_generate`、`tts` -- `group:openclaw`：所有内置 OpenClaw 工具（不包括提供商插件） +- `group:openclaw`：所有 OpenClaw 内置工具（不包括提供商插件） -## 提权执行：仅限 exec 的“在主机上运行” +## 提权执行：仅针对 exec 的“在主机上运行” 提权执行**不会**授予额外工具；它只影响 `exec`。 - 如果你处于沙箱中，`/elevated on`（或带 `elevated: true` 的 `exec`）会在沙箱外运行（仍可能需要审批）。 -- 使用 `/elevated full` 可跳过该会话中的 exec 审批。 -- 如果你本来就是直接运行，提权执行实际上没有效果（但仍受门禁控制）。 -- 提权执行**不**受 Skills 作用域限制，也**不**会覆盖工具允许 / 拒绝策略。 -- 提权执行不会从 `host=auto` 授予任意跨主机覆盖；它遵循正常的 exec 目标规则，并且只有在配置的 / 会话中的目标本来就是 `node` 时，才会保留 `node`。 -- `/exec` 与提权执行是分开的。它只会为已授权发送者调整每个会话的 exec 默认值。 +- 使用 `/elevated full` 可为当前会话跳过 exec 审批。 +- 如果你已经在直接运行环境中，提权执行实际上不会产生效果（但仍受门禁控制）。 +- 提权执行**不是** Skills 作用域的，也**不会**覆盖工具允许 / 拒绝规则。 +- 提权执行不会从 `host=auto` 授予任意跨主机覆盖；它遵循正常的 exec 目标规则，且仅在配置的 / 会话的目标本来就是 `node` 时才保留 `node`。 +- `/exec` 与提权执行是分开的。它只会为已授权发送者调整按会话生效的 exec 默认值。 门禁： -- 启用开关：`tools.elevated.enabled`（以及可选的 `agents.list[].tools.elevated.enabled`） +- 启用项：`tools.elevated.enabled`（以及可选的 `agents.list[].tools.elevated.enabled`） - 发送者允许列表：`tools.elevated.allowFrom.`（以及可选的 `agents.list[].tools.elevated.allowFrom.`） -参见 [提权执行模式](/zh-CN/tools/elevated)。 +请参见 [提权模式](/zh-CN/tools/elevated)。 ## 常见“沙箱牢笼”修复方法 @@ -132,16 +133,16 @@ openclaw sandbox explain --json 修复建议键（任选其一）： - 禁用沙箱：`agents.defaults.sandbox.mode=off`（或按智能体设置 `agents.list[].sandbox.mode=off`） -- 允许该工具在沙箱中使用： - - 从 `tools.sandbox.tools.deny` 中移除它（或按智能体从 `agents.list[].tools.sandbox.tools.deny` 中移除） - - 或者把它添加到 `tools.sandbox.tools.allow`（或按智能体添加到 allow） +- 允许该工具在沙箱内使用： + - 将其从 `tools.sandbox.tools.deny` 中移除（或按智能体从 `agents.list[].tools.sandbox.tools.deny` 中移除） + - 或将其添加到 `tools.sandbox.tools.allow`（或按智能体添加到 allow） -### “我以为这是主会话，为什么它在沙箱里？” +### “我以为这是主会话，为什么它被沙箱隔离了？” -在 `"non-main"` 模式下，群组 / 渠道键**不是**主会话。请使用主会话键（由 `sandbox explain` 显示），或将模式切换为 `"off"`。 +在 `"non-main"` 模式下，群组 / 渠道键_不是_主会话。请使用主会话键（由 `sandbox explain` 显示），或将模式切换为 `"off"`。 ## 另请参见 -- [沙箱隔离](/zh-CN/gateway/sandboxing) -- 完整的沙箱参考（模式、作用域、后端、镜像） -- [多智能体沙箱与工具](/zh-CN/tools/multi-agent-sandbox-tools) -- 每个智能体的覆盖项和优先级 -- [提权执行模式](/zh-CN/tools/elevated) +- [沙箱隔离](/zh-CN/gateway/sandboxing) -- 完整沙箱参考（模式、作用域、后端、镜像） +- [多智能体沙箱与工具](/zh-CN/tools/multi-agent-sandbox-tools) -- 按智能体覆盖和优先级 +- [提权模式](/zh-CN/tools/elevated) diff --git a/docs/zh-CN/help/faq.md b/docs/zh-CN/help/faq.md index 3d9cc281f..f1efb54f1 100644 --- a/docs/zh-CN/help/faq.md +++ b/docs/zh-CN/help/faq.md @@ -1,25 +1,25 @@ --- read_when: - - 解答常见的设置、安装、新手引导或运行时支持问题 - - 在进行更深入的调试之前，先对用户报告的问题进行初步分类和分诊 -summary: 关于 OpenClaw 设置、配置和使用的常见问题 + - 回答常见的设置、安装、新手引导或运行时支持问题 + - 在深入调试之前对用户报告的问题进行初步分诊 +summary: 有关 OpenClaw 设置、配置和使用的常见问题 title: 常见问题 x-i18n: - generated_at: "2026-04-23T18:24:14Z" + generated_at: "2026-04-23T19:24:51Z" model: gpt-5.4 provider: openai - source_hash: ffa69fef2b88175cc1ed1d2d587f355eb189a38b592af95571240501c15df4a6 + source_hash: e80ee4444c0bf72ecabe248fdacb9f1f8ee64db46189e37a898a9a1242185f75 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)。有关完整的配置参考，请参阅 [配置](/zh-CN/gateway/configuration)。 -## 如果出现问题，最初的六十秒 +## 出问题时最初的六十秒 -1. **快速状态（第一项检查）** +1. **快速状态（首次检查）** ```bash openclaw status @@ -33,7 +33,7 @@ x-i18n: openclaw status --all ``` - 只读诊断，附带日志尾部（令牌已脱敏）。 + 只读诊断，附带日志尾部（token 已脱敏）。 3. **守护进程 + 端口状态** @@ -41,7 +41,7 @@ x-i18n: openclaw gateway status ``` - 显示 supervisor 运行时与 RPC 可达性、探测目标 URL，以及服务可能使用了哪份配置。 + 显示 supervisor 运行时与 RPC 可达性、探测目标 URL，以及服务可能使用的是哪份配置。 4. **深度探测** @@ -49,22 +49,22 @@ x-i18n: openclaw status --deep ``` - 运行实时 Gateway 网关健康探测，在支持时还包括渠道探测 - （需要可达的 Gateway 网关）。请参阅 [Health](/zh-CN/gateway/health)。 + 运行实时 Gateway 网关健康探测，包括在支持时的渠道探测 + （需要 Gateway 网关可达）。参见 [Health](/zh-CN/gateway/health)。 -5. **查看最新日志** +5. **跟踪最新日志** ```bash openclaw logs --follow ``` - 如果 RPC 不可用，则退回到： + 如果 RPC 不可用，则回退到： ```bash tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" ``` - 文件日志与服务日志相互独立；请参阅 [Logging](/zh-CN/logging) 和 [故障排除](/zh-CN/gateway/troubleshooting)。 + 文件日志与服务日志是分开的；参见 [Logging](/zh-CN/logging) 和 [故障排除](/zh-CN/gateway/troubleshooting)。 6. **运行 Doctor（修复）** @@ -72,48 +72,47 @@ x-i18n: openclaw doctor ``` - 修复/迁移配置与状态 + 运行健康检查。请参阅 [Doctor](/zh-CN/gateway/doctor)。 + 修复/迁移配置和状态 + 运行健康检查。参见 [Doctor](/zh-CN/gateway/doctor)。 7. **Gateway 网关快照** ```bash openclaw health --json - openclaw health --verbose # 在报错时显示目标 URL + 配置路径 + 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/) - 这些工具可以读取仓库、运行命令、检查日志，并帮助修复你的机器级设置 - （PATH、服务、权限、认证文件）。通过可修改的（git）安装方式， - 把**完整的源码检出**提供给它们： + 这些工具可以读取仓库、运行命令、检查日志，并帮助修复机器层面的 + 设置问题（PATH、服务、权限、auth 文件）。通过可修改的（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： + 如果你发现了真实的 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,42 +122,42 @@ x-i18n: 它们的作用： - - `openclaw status`：快速查看 Gateway 网关/智能体健康状况 + 基础配置。 - - `openclaw models status`：检查提供商认证 + 模型可用性。 - - `openclaw doctor`：验证并修复常见的配置/状态问题。 + - `openclaw status`：Gateway 网关/智能体健康状态 + 基本配置的快速快照。 + - `openclaw models status`：检查提供商身份验证 + 模型可用性。 + - `openclaw doctor`：验证并修复常见配置/状态问题。 其他有用的 CLI 检查：`openclaw status --all`、`openclaw logs --follow`、 `openclaw gateway status`、`openclaw health --verbose`。 - 快速调试循环：[如果出现问题，最初的六十秒](#first-60-seconds-if-something-is-broken)。 + 快速调试循环：[出问题时最初的六十秒](#first-60-seconds-if-something-is-broken)。 安装文档：[Install](/zh-CN/install)、[Installer flags](/zh-CN/install/installer)、[Updating](/zh-CN/install/updating)。 - - 常见的 Heartbeat 跳过原因： + + 常见的 heartbeat 跳过原因： - - `quiet-hours`：当前不在已配置的 active-hours 时间窗口内 - - `empty-heartbeat-file`：`HEARTBEAT.md` 存在，但只包含空白/仅标题的脚手架内容 - - `no-tasks-due`：`HEARTBEAT.md` 任务模式已启用，但目前没有任何任务间隔到期 - - `alerts-disabled`：所有 Heartbeat 可见性都已关闭（`showOk`、`showAlerts` 和 `useIndicator` 全部关闭） + - `quiet-hours`：超出已配置的 active-hours 时间窗口 + - `empty-heartbeat-file`：`HEARTBEAT.md` 存在，但只包含空白内容/仅标题脚手架 + - `no-tasks-due`：`HEARTBEAT.md` 任务模式已启用，但还没有任何任务间隔到期 + - `alerts-disabled`：所有 heartbeat 可见性都已禁用（`showOk`、`showAlerts` 和 `useIndicator` 全部关闭） - 在任务模式下，只有在真实的 Heartbeat 运行 - 完成之后，才会推进到期时间戳。被跳过的运行不会将任务标记为已完成。 + 在任务模式下，只有在真正的 heartbeat 运行 + 完成之后，到期时间戳才会被推进。被跳过的运行不会把任务标记为已完成。 文档：[Heartbeat](/zh-CN/gateway/heartbeat)、[Automation & Tasks](/zh-CN/automation)。 - 仓库推荐从源码运行并使用新手引导： + 仓库推荐从源码运行，并使用新手引导： ```bash curl -fsSL https://openclaw.ai/install.sh | bash openclaw onboard --install-daemon ``` - 向导还可以自动构建 UI 资源。完成新手引导后，你通常会在端口 **18789** 上运行 Gateway 网关。 + 向导也可以自动构建 UI 资源。完成新手引导后，你通常会在 **18789** 端口运行 Gateway 网关。 从源码运行（贡献者/开发者）： @@ -175,28 +174,28 @@ x-i18n: - - 向导会在新手引导完成后立即用浏览器打开一个干净的（不带令牌的）仪表板 URL，并且也会在摘要中打印该链接。请保持该标签页打开；如果没有自动启动，就在同一台机器上复制/粘贴打印出来的 URL。 + + 向导会在新手引导完成后立即在你的浏览器中打开一个干净的（不带 token 的）仪表板 URL，并且也会在摘要中打印该链接。请保持那个标签页打开；如果它没有自动启动，请在同一台机器上复制/粘贴打印出来的 URL。 - + **Localhost（同一台机器）：** - 打开 `http://127.0.0.1:18789/`。 - - 如果它要求共享密钥认证，请将已配置的令牌或密码粘贴到 Control UI 设置中。 - - 令牌来源：`gateway.auth.token`（或 `OPENCLAW_GATEWAY_TOKEN`）。 + - 如果它要求 shared-secret 身份验证，请将已配置的 token 或密码粘贴到 Control UI 设置中。 + - Token 来源：`gateway.auth.token`（或 `OPENCLAW_GATEWAY_TOKEN`）。 - 密码来源：`gateway.auth.password`（或 `OPENCLAW_GATEWAY_PASSWORD`）。 - - 如果还没有配置共享密钥，可通过 `openclaw doctor --generate-gateway-token` 生成令牌。 + - 如果尚未配置 shared secret，可使用 `openclaw doctor --generate-gateway-token` 生成 token。 **不在 localhost：** - - **Tailscale Serve**（推荐）：保持绑定到 loopback，运行 `openclaw gateway --tailscale serve`，打开 `https:///`。如果 `gateway.auth.allowTailscale` 为 `true`，身份头会满足 Control UI/WebSocket 认证要求（无需粘贴共享密钥，假设 Gateway 网关主机受信任）；HTTP API 仍然需要共享密钥认证，除非你有意使用 private-ingress `none` 或 trusted-proxy HTTP 认证。 - 来自同一客户端的错误并发 Serve 认证尝试会在 failed-auth limiter 记录之前被串行化，因此第二次错误重试可能已经显示 `retry later`。 - - **Tailnet 绑定**：运行 `openclaw gateway --bind tailnet --token ""`（或配置密码认证），打开 `http://:18789/`，然后在仪表板设置中粘贴匹配的共享密钥。 - - **支持身份感知的反向代理**：让 Gateway 网关继续位于非 loopback 的受信任代理之后，配置 `gateway.auth.mode: "trusted-proxy"`，然后打开代理 URL。 - - **SSH 隧道**：`ssh -N -L 18789:127.0.0.1:18789 user@host`，然后打开 `http://127.0.0.1:18789/`。通过隧道时共享密钥认证仍然有效；如果出现提示，请粘贴已配置的令牌或密码。 + - **Tailscale Serve**（推荐）：保持绑定到 loopback，运行 `openclaw gateway --tailscale serve`，然后打开 `https:///`。如果 `gateway.auth.allowTailscale` 为 `true`，身份头会满足 Control UI/WebSocket 身份验证（无需粘贴 shared secret，前提是假定 Gateway 网关主机可信）；HTTP API 仍然需要 shared-secret 身份验证，除非你明确使用 private-ingress `none` 或 trusted-proxy HTTP 身份验证。 + 来自同一客户端的并发 Serve 错误身份验证尝试会在失败身份验证限流器记录之前被串行化，因此第二次错误重试可能已经显示 `retry later`。 + - **Tailnet 绑定**：运行 `openclaw gateway --bind tailnet --token ""`（或配置密码身份验证），打开 `http://:18789/`，然后在仪表板设置中粘贴匹配的 shared secret。 + - **具备身份感知的反向代理**：将 Gateway 网关保留在非 loopback 的可信代理之后，配置 `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 身份验证仍然适用；如有提示，请粘贴已配置的 token 或密码。 - 有关绑定模式和认证细节，请参阅 [Dashboard](/zh-CN/web/dashboard) 和 [Web surfaces](/zh-CN/web)。 + 有关绑定模式和身份验证详情，请参阅 [Dashboard](/zh-CN/web/dashboard) 和 [Web surfaces](/zh-CN/web)。 @@ -204,57 +203,57 @@ x-i18n: 它们控制的是不同层级： - `approvals.exec`：将审批提示转发到聊天目标 - - `channels..execApprovals`：让该渠道作为 exec 审批的原生审批客户端 + - `channels..execApprovals`：让该渠道充当 exec 审批的原生审批客户端 - 主机 exec 策略仍然是真正的审批门禁。聊天配置只控制审批 - 提示显示在哪里，以及用户如何响应。 + 主机 exec 策略仍然是真正的审批门槛。聊天配置只控制审批 + 提示出现在哪里，以及人们如何进行回应。 - 在大多数部署中，你**不**需要同时配置两者： + 在大多数设置中，你**不需要**同时配置两者： - - 如果该聊天已经支持命令和回复，那么同一聊天内的 `/approve` 会通过共享路径生效。 - - 如果受支持的原生渠道能够安全推断审批人，OpenClaw 现在会在 `channels..execApprovals.enabled` 未设置或为 `"auto"` 时，自动启用优先私信的原生审批。 - - 当存在原生审批卡片/按钮时，该原生 UI 是主要路径；只有当工具结果表明聊天审批不可用，或手动审批是唯一可用路径时，智能体才应包含手动 `/approve` 命令。 - - 仅当审批提示还需要转发到其他聊天或明确的运维房间时，才使用 `approvals.exec`。 - - 仅当你明确希望把审批提示重新发回发起的房间/主题时，才使用 `channels..execApprovals.target: "channel"` 或 `"both"`。 - - 插件审批则是另一套机制：默认使用同一聊天内的 `/approve`，可选 `approvals.plugin` 转发，而且只有部分原生渠道会在此基础上继续保留插件审批原生处理。 + - 如果该聊天已经支持命令和回复，那么同一聊天中的 `/approve` 会通过共享路径工作。 + - 如果某个受支持的原生渠道可以安全推断 approver，OpenClaw 现在会在 `channels..execApprovals.enabled` 未设置或为 `"auto"` 时，自动启用私信优先的原生审批。 + - 当提供原生审批卡片/按钮时，该原生 UI 是主要路径；只有在工具结果表明聊天审批不可用，或手动审批是唯一途径时，智能体才应包含手动 `/approve` 命令。 + - 仅在提示还必须转发到其他聊天或显式 ops 房间时使用 `approvals.exec`。 + - 仅在你明确希望将审批提示发回原始房间/主题时，才使用 `channels..execApprovals.target: "channel"` 或 `"both"`。 + - 插件审批则是另一套单独机制：默认使用同一聊天中的 `/approve`、可选的 `approvals.plugin` 转发，并且只有某些原生渠道会在此之上继续保留插件审批的原生处理。 - 简短来说：转发用于路由，原生客户端配置用于提供更丰富的渠道专属 UX。 - 请参阅 [Exec Approvals](/zh-CN/tools/exec-approvals)。 + 简而言之：转发用于路由，原生客户端配置用于更丰富的渠道特定 UX。 + 参见 [Exec Approvals](/zh-CN/tools/exec-approvals)。 - 需要 Node **>= 22**。推荐使用 `pnpm`。Gateway 网关**不推荐**使用 Bun。 + 需要 Node **>= 22**。推荐使用 `pnpm`。**不推荐**对 Gateway 网关使用 Bun。 - 可以。Gateway 网关很轻量——文档中列出**512MB-1GB RAM**、**1 个核心**以及约 **500MB** - 磁盘空间就足够个人使用，并说明 **Raspberry Pi 4 可以运行它**。 + 可以。Gateway 网关很轻量——文档列出个人使用只需 **512MB-1GB RAM**、**1 个核心** 和大约 **500MB** + 磁盘空间，并说明 **Raspberry Pi 4 可以运行它**。 - 如果你想要更多余量（日志、媒体、其他服务），推荐 **2GB**，但这 - 不是硬性最低要求。 + 如果你想保留更多余量（日志、媒体、其他服务），推荐 **2GB**， + 但这不是硬性最低要求。 - 提示：小型 Pi/VPS 可以托管 Gateway 网关，而你可以在笔记本/手机上配对**节点**， - 用于本地屏幕/相机/canvas 或命令执行。请参阅 [Nodes](/zh-CN/nodes)。 + 提示：一个小型 Pi/VPS 可以托管 Gateway 网关，而你可以在笔记本电脑/手机上配对 **nodes** 以进行 + 本地屏幕/摄像头/canvas 或命令执行。参见 [Nodes](/zh-CN/nodes)。 - 简短版本：可以运行，但要预期会有一些边角问题。 + 简短回答：可以运行，但可能会遇到一些粗糙边缘问题。 - - 使用 **64 位**操作系统，并保持 Node >= 22。 + - 使用 **64 位** 操作系统，并保持 Node >= 22。 - 优先选择**可修改的（git）安装**，这样你可以查看日志并快速更新。 - - 先不要启用渠道/Skills，之后再逐个添加。 - - 如果遇到奇怪的二进制问题，通常是 **ARM 兼容性**问题。 + - 先不要启用渠道/Skills，然后一个一个添加。 + - 如果你遇到奇怪的二进制问题，通常是 **ARM 兼容性** 问题。 文档：[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 网关： @@ -262,7 +261,7 @@ x-i18n: openclaw gateway restart ``` - 2. 检查状态 + 认证： + 2. 检查状态 + 身份验证： ```bash openclaw status @@ -276,14 +275,14 @@ x-i18n: openclaw doctor ``` - 如果 Gateway 网关是远程的，请确保隧道/Tailscale 连接已建立，并且 UI - 指向了正确的 Gateway 网关。请参阅 [Remote access](/zh-CN/gateway/remote)。 + 如果 Gateway 网关是远程的，请确保隧道/Tailscale 连接正常，并且 UI + 指向的是正确的 Gateway 网关。参见 [Remote access](/zh-CN/gateway/remote)。 - - 可以。复制**状态目录**和**工作区**，然后运行一次 Doctor 即可。这样 - 可以让你的机器人“完全保持原样”（记忆、会话历史、认证和渠道 + + 可以。复制**状态目录**和**工作区**，然后运行一次 Doctor。这会 + 让你的机器人“保持完全一样”（记忆、会话历史、身份验证和渠道 状态），前提是你复制了**这两个**位置： 1. 在新机器上安装 OpenClaw。 @@ -291,60 +290,62 @@ x-i18n: 3. 复制你的工作区（默认：`~/.openclaw/workspace`）。 4. 运行 `openclaw doctor` 并重启 Gateway 网关服务。 - 这会保留配置、认证配置文件、WhatsApp 凭据、会话和记忆。如果你处于 - 远程模式，请记住会话存储和工作区归 Gateway 网关主机所有。 + 这会保留配置、auth profiles、WhatsApp 凭证、会话和记忆。如果你处于 + remote 模式，请记住会话存储和工作区归 Gateway 网关主机所有。 - **重要：**如果你只是将工作区提交/推送到 GitHub，你备份的是 - **记忆 + 引导文件**，但**不包括**会话历史或认证。那些内容位于 + **重要：**如果你只是将工作区提交/推送到 GitHub，你备份的其实是 + **记忆 + 引导文件**，但**不是**会话历史或身份验证信息。后两者存放在 `~/.openclaw/` 下（例如 `~/.openclaw/agents//sessions/`）。 - 相关内容：[Migrating](/zh-CN/install/migrating)、[磁盘上的文件位置](#where-things-live-on-disk)、 + 相关内容：[Migrating](/zh-CN/install/migrating)、[磁盘上的存储位置](#where-things-live-on-disk)、 [智能体工作区](/zh-CN/concepts/agent-workspace)、[Doctor](/zh-CN/gateway/doctor)、 - [远程模式](/zh-CN/gateway/remote)。 + [Remote mode](/zh-CN/gateway/remote)。 - + 请查看 GitHub 更新日志： [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - 最新条目位于顶部。如果顶部章节标记为 **Unreleased**，则下一个带日期的 - 章节就是最近发布的版本。条目按 **Highlights**、**Changes** 和 - **Fixes** 分组（在需要时还会有 docs/other 等章节）。 + 最新条目位于顶部。如果顶部部分标记为 **Unreleased**，那么下一个带日期的 + 部分就是最近发布的版本。条目按 **Highlights**、**Changes** 和 + **Fixes** 分组（在需要时还会有 docs/other 部分）。 - 某些 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) - - **稳定版** 和 **beta** 是 **npm dist-tags**，不是彼此独立的代码线： + + **Stable** 和 **beta** 是 **npm dist-tags**，而不是独立的代码线： - - `latest` = 稳定版 - - `beta` = 用于测试的早期构建版本 + - `latest` = stable + - `beta` = 用于测试的早期构建 - 通常，稳定版发布会先落到 **beta**，然后再通过一个明确的 + 通常，一个稳定版本会先发布到 **beta**，然后通过一次显式的 提升步骤将同一个版本移动到 `latest`。维护者也可以在需要时 - 直接发布到 `latest`。这就是为什么 beta 和稳定版在提升后 + 直接发布到 `latest`。这就是为什么 beta 和 stable 在提升后 可能会指向**同一个版本**。 - 查看具体变更： + 查看有哪些变更： [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - 关于安装单行命令以及 beta 和 dev 的区别，请参阅下面的折叠项。 + 有关安装单行命令以及 beta 和 dev 区别的更多信息，请参阅下面的折叠项。 **Beta** 是 npm dist-tag `beta`（提升后可能与 `latest` 相同）。 - **Dev** 是 `main` 的动态最新头部版本（git）；发布后会使用 npm dist-tag `dev`。 + **Dev** 是 `main` 的移动头部（git）；发布后，它使用 npm dist-tag `dev`。 单行命令（macOS/Linux）： @@ -363,7 +364,7 @@ x-i18n: - + 有两个选项： 1. **Dev 渠道（git 检出）：** @@ -374,15 +375,15 @@ x-i18n: 这会切换到 `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 @@ -396,25 +397,25 @@ x-i18n: - + 大致参考： - - **安装：**2-5 分钟 - - **新手引导：**5-15 分钟，取决于你配置了多少渠道/模型 + - **安装：**2–5 分钟 + - **新手引导：**5–15 分钟，取决于你配置了多少渠道/模型 - 如果卡住了，请参阅 [Installer stuck](#quick-start-and-first-run-setup) - 以及 [我卡住了](#quick-start-and-first-run-setup) 中的快速调试循环。 + 如果卡住了，请参阅 [安装器卡住了](#quick-start-and-first-run-setup) + 和 [我卡住了](#quick-start-and-first-run-setup) 中的快速调试循环。 - + 使用**详细输出**重新运行安装器： ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose ``` - 使用详细输出安装 beta： + 带详细输出的 beta 安装： ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose @@ -426,10 +427,10 @@ x-i18n: curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose ``` - Windows（PowerShell）等效方式： + 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 @@ -442,37 +443,37 @@ x-i18n: 这是两个常见的 Windows 问题： - **1）npm 错误 spawn git / git not found** + **1) npm 错误 spawn git / git not found** - 安装 **Git for Windows**，并确保 `git` 已加入你的 PATH。 - 关闭并重新打开 PowerShell，然后重新运行安装器。 - **2）安装后提示 openclaw is not recognized** + **2) 安装后 openclaw is not recognized** - - 你的 npm 全局 bin 目录没有加入 PATH。 + - 你的 npm 全局 bin 文件夹不在 PATH 中。 - 检查路径： ```powershell npm config get prefix ``` - - 将该目录添加到你的用户 PATH 中（Windows 上不需要 `\bin` 后缀；在大多数系统中它是 `%AppData%\npm`）。 + - 将该目录添加到你的用户 PATH（Windows 上不需要 `\bin` 后缀；在大多数系统中它是 `%AppData%\npm`）。 - 更新 PATH 后，关闭并重新打开 PowerShell。 - 如果你想获得最顺畅的 Windows 安装体验，请使用 **WSL2**，而不是原生 Windows。 + 如果你想获得最顺畅的 Windows 设置体验，请使用 **WSL2** 而不是原生 Windows。 文档：[Windows](/zh-CN/platforms/windows)。 - + 这通常是原生 Windows shell 中控制台代码页不匹配导致的。 症状： - `system.run`/`exec` 输出中的中文显示为乱码 - - 同一个命令在另一个终端配置中显示正常 + - 同一条命令在另一个终端配置中看起来正常 - PowerShell 中的快速变通方法： + PowerShell 中的快速变通办法： ```powershell chcp 65001 @@ -487,15 +488,15 @@ x-i18n: 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 @@ -506,7 +507,7 @@ x-i18n: - 简短回答：遵循 Linux 指南，然后运行新手引导。 + 简短回答：按照 Linux 指南操作，然后运行新手引导。 - Linux 快速路径 + 服务安装：[Linux](/zh-CN/platforms/linux)。 - 完整演练：[入门指南](/zh-CN/start/getting-started)。 @@ -515,7 +516,7 @@ x-i18n: - 任何 Linux VPS 都可以。在服务器上安装，然后使用 SSH/Tailscale 连接到 Gateway 网关。 + 任意 Linux VPS 都可以。安装到服务器上，然后通过 SSH/Tailscale 访问 Gateway 网关。 指南：[exe.dev](/zh-CN/install/exe-dev)、[Hetzner](/zh-CN/install/hetzner)、[Fly.io](/zh-CN/install/fly)。 远程访问：[Gateway remote](/zh-CN/gateway/remote)。 @@ -523,29 +524,30 @@ x-i18n: - 我们提供了一个**托管中心**，汇总了常见提供商。选择一个并按照指南操作： + 我们维护了一个包含常见提供商的**托管中心**。选择一个并按照指南操作： - [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/headless）配对到该云端 Gateway 网关，以访问 - 本地屏幕/相机/canvas，或在笔记本上运行命令，同时仍将 + 你可以将 **nodes**（Mac/iOS/Android/headless）配对到该云端 Gateway 网关，以访问 + 本地屏幕/摄像头/canvas，或在你的笔记本电脑上运行命令，同时让 Gateway 网关保留在云端。 - 中心页：[Platforms](/zh-CN/platforms)。远程访问：[Gateway remote](/zh-CN/gateway/remote)。 - 节点：[Nodes](/zh-CN/nodes)、[Nodes CLI](/zh-CN/cli/nodes)。 + 中心：[Platforms](/zh-CN/platforms)。远程访问：[Gateway remote](/zh-CN/gateway/remote)。 + Nodes：[Nodes](/zh-CN/nodes)、[Nodes CLI](/zh-CN/cli/nodes)。 简短回答：**可以，但不推荐**。更新流程可能会重启 - Gateway 网关（这会中断当前会话），可能需要一个干净的 git 检出，并且 - 还可能要求确认。更安全的做法是：由操作员在 shell 中执行更新。 + Gateway 网关（这会中断当前会话），可能需要干净的 git 检出，并且 + 可能提示你确认。更安全的做法是由操作员在 shell 中运行更新。 使用 CLI： @@ -557,7 +559,7 @@ x-i18n: openclaw update --no-restart ``` - 如果你必须从智能体中自动化执行： + 如果你必须通过智能体自动化： ```bash openclaw update --yes --no-restart @@ -571,33 +573,33 @@ x-i18n: `openclaw onboard` 是推荐的设置路径。在**本地模式**下，它会引导你完成： - - **模型/认证设置**（提供商 OAuth、API 密钥、Anthropic 设置令牌，以及 LM Studio 等本地模型选项） + - **模型/auth 设置**（提供商 OAuth、API 密钥、Anthropic setup-token，以及 LM Studio 等本地模型选项） - **工作区**位置 + 引导文件 - - **Gateway 网关设置**（绑定/端口/认证/Tailscale） - - **渠道**（WhatsApp、Telegram、Discord、Mattermost、Signal、iMessage，以及像 QQ Bot 这样的内置渠道插件） + - **Gateway 网关设置**（bind/port/auth/tailscale） + - **渠道**（WhatsApp、Telegram、Discord、Mattermost、Signal、iMessage，以及 QQ Bot 等内置渠道插件） - **守护进程安装**（macOS 上为 LaunchAgent；Linux/WSL2 上为 systemd 用户单元） - - **健康检查** 和 **Skills** 选择 + - **健康检查**和 **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 正常计费 - - **OpenClaw 中的 Claude CLI / Claude 订阅认证**：Anthropic 工作人员 - 告诉我们这种用法再次被允许，OpenClaw 当前将 `claude -p` - 的用法视为该集成的许可用法，除非 Anthropic 发布新的 - 政策 + - **Anthropic API key**：正常的 Anthropic API 计费 + - **在 OpenClaw 中使用 Claude CLI / Claude 订阅身份验证**：Anthropic 员工 + 告诉我们这种用法再次被允许，除非 Anthropic 发布新的 + 策略，否则 OpenClaw 会将此集成中的 `claude -p` + 用法视为受认可的 - 对于长期运行的 Gateway 网关主机，Anthropic API 密钥仍然是更 - 可预测的设置方式。OpenAI Codex OAuth 已明确支持用于 OpenClaw - 这样的外部工具。 + 对于长期运行的 Gateway 网关主机，Anthropic API key 仍然是 + 更可预测的设置。OpenAI Codex OAuth 明确支持用于 OpenClaw 这样的外部 + 工具。 OpenClaw 还支持其他托管式订阅选项，包括 **Qwen Cloud Coding Plan**、**MiniMax Coding Plan** 和 @@ -610,25 +612,27 @@ x-i18n: - + 可以。 - Anthropic 工作人员告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此 - 除非 Anthropic 发布新政策，否则 OpenClaw 会将 Claude 订阅认证和 `claude -p` 的使用视为该集成下获得许可的用法。如果你想要 - 最可预测的服务器端设置，请改用 Anthropic API 密钥。 + Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此 + 除非 Anthropic 发布新的政策，否则 OpenClaw 会将 Claude 订阅身份验证和 `claude -p` 用法视为 + 该集成中的受认可方式。如果你希望获得最可预测的服务器端设置， + 请改用 Anthropic API key。 - + 支持。 - Anthropic 工作人员告诉我们，这种用法再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 会将 - Claude CLI 复用和 `claude -p` 的使用视为该集成下获得许可的用法。 + Anthropic 员工告诉我们，这种用法再次被允许，因此除非 Anthropic 发布新的政策， + 否则 OpenClaw 会将 Claude CLI 复用和 `claude -p` 用法视为 + 该集成中的受认可方式。 - Anthropic setup-token 仍然是 OpenClaw 支持的令牌路径，但 OpenClaw 现在在可用时更倾向于使用 Claude CLI 复用和 `claude -p`。 - 对于生产环境或多用户工作负载，Anthropic API 密钥认证仍然是 - 更安全、更可预测的选择。如果你想在 OpenClaw 中使用其他托管式订阅选项， - 请参阅 [OpenAI](/zh-CN/providers/openai)、[Qwen / Model + Anthropic setup-token 仍然是 OpenClaw 支持的 token 路径，但 OpenClaw 现在在可用时更倾向于使用 Claude CLI 复用和 `claude -p`。 + 对于生产环境或多用户工作负载，Anthropic API key 身份验证仍然是 + 更安全、更可预测的选择。如果你想了解 OpenClaw 中其他托管式订阅 + 选项，请参阅 [OpenAI](/zh-CN/providers/openai)、[Qwen / Model Cloud](/zh-CN/providers/qwen)、[MiniMax](/zh-CN/providers/minimax) 和 [GLM Models](/zh-CN/providers/glm)。 @@ -639,171 +643,169 @@ x-i18n: - - 这表示你在当前时间窗口内的 **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 的 + 凭证有资格进行长上下文计费时才可用（API key 计费，或者启用了 Extra Usage 的 OpenClaw Claude 登录路径）。 - 提示：设置一个 **回退模型**，这样当某个提供商受到速率限制时，OpenClaw 仍可继续回复。 - 请参阅 [Models](/zh-CN/cli/models)、[OAuth](/zh-CN/concepts/oauth) 和 + 提示：设置一个**回退模型**，这样当某个提供商受到速率限制时，OpenClaw 仍然可以继续回复。 + 参见 [Models](/zh-CN/cli/models)、[OAuth](/zh-CN/concepts/oauth) 和 [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/zh-CN/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context)。 - 支持。OpenClaw 内置了 **Amazon Bedrock（Converse）** 提供商。在存在 AWS 环境标记时，OpenClaw 可以自动发现支持流式/文本的 Bedrock 模型目录，并将其合并为隐式的 `amazon-bedrock` 提供商；否则你也可以显式启用 `plugins.entries.amazon-bedrock.config.discovery.enabled`，或手动添加一个提供商条目。请参阅 [Amazon Bedrock](/zh-CN/providers/bedrock) 和 [Model providers](/zh-CN/providers/models)。如果你更偏好托管式密钥流程，在 Bedrock 前面使用一个兼容 OpenAI 的代理仍然是可行选项。 + 支持。OpenClaw 内置了 **Amazon Bedrock Mantle** 提供商。在存在 AWS 环境标记时，OpenClaw 可以自动发现支持流式传输/文本的 Bedrock 目录，并将其合并为隐式的 `amazon-bedrock` 提供商；否则，你也可以显式启用 `plugins.entries.amazon-bedrock.config.discovery.enabled`，或添加手动 provider 条目。参见 [Amazon Bedrock](/zh-CN/providers/bedrock) 和 [模型提供商](/zh-CN/providers/models)。如果你更喜欢托管式密钥流，在 Bedrock 前面放置一个兼容 OpenAI 的代理仍然是有效选项。 - - OpenClaw 通过 OAuth（ChatGPT 登录）支持 **OpenAI Code（Codex）**。新手引导可以运行 OAuth 流程，并会在适当时将默认模型设置为 `openai-codex/gpt-5.4`。请参阅 [Model providers](/zh-CN/concepts/model-providers) 和 [新手引导（CLI）](/zh-CN/start/wizard)。 + + OpenClaw 通过 OAuth（ChatGPT 登录）支持 **OpenAI Code（Codex）**。新手引导可以运行 OAuth 流程，并会在适当时将默认模型设置为 `openai-codex/gpt-5.5`。参见 [模型提供商](/zh-CN/concepts/model-providers) 和 [新手引导（CLI）](/zh-CN/start/wizard)。 - - OpenClaw 将这两种路径分别处理： + + OpenClaw 将这两条路径分开处理： - - `openai-codex/gpt-5.4` = ChatGPT/Codex OAuth - - `openai/gpt-5.4` = 直接 OpenAI Platform API + - `openai-codex/gpt-5.5` = ChatGPT/Codex OAuth + - `openai/gpt-5.5` = 直接 OpenAI Platform API - 在 OpenClaw 中，ChatGPT/Codex 登录连接的是 `openai-codex/*` 路径， - 而不是直接的 `openai/*` 路径。如果你想在 OpenClaw 中使用直接 API 路径， - 请设置 `OPENAI_API_KEY`（或等效的 OpenAI 提供商配置）。 + 在 OpenClaw 中，ChatGPT/Codex 登录接入的是 `openai-codex/*` 路径， + 而不是直接的 `openai/*` 路径。如果你想在 + OpenClaw 中使用直接 API 路径，请设置 `OPENAI_API_KEY`（或等效的 OpenAI provider 配置）。 如果你想在 OpenClaw 中使用 ChatGPT/Codex 登录，请使用 `openai-codex/*`。 - `openai-codex/*` 使用 Codex OAuth 路径，其可用的配额窗口由 - OpenAI 管理，并取决于套餐。实际上，即使两者绑定到同一账户， - 这些限制也可能与 ChatGPT 网站/应用中的体验不同。 + `openai-codex/*` 使用 Codex OAuth 路径，而其可用的配额窗口由 + OpenAI 管理，并取决于你的套餐。在实际使用中，即使两者都绑定到同一个账户， + 这些限制也可能与 ChatGPT 网站/app 的体验不同。 OpenClaw 可以在 - `openclaw models status` 中显示当前可见的提供商用量/配额窗口，但不会虚构或标准化 ChatGPT 网页版 - 权益，使其变成直接 API 访问。如果你想使用直接 OpenAI Platform - 计费/限制路径，请结合 API 密钥使用 `openai/*`。 + `openclaw models status` 中显示当前可见的 provider 用量/配额窗口，但它不会凭空创建， + 也不会将 ChatGPT 网页版权益标准化为直接 API 访问。如果你想使用直接的 OpenAI Platform + 计费/限额路径，请用 API key 配置 `openai/*`。 - + 支持。OpenClaw 完全支持 **OpenAI Code（Codex）订阅 OAuth**。 - OpenAI 明确允许在 OpenClaw 这样的外部工具/工作流中使用订阅 OAuth。 - 新手引导可以为你运行 OAuth 流程。 + OpenAI 明确允许在像 OpenClaw 这样的外部工具/工作流中 + 使用订阅 OAuth。新手引导可以为你运行 OAuth 流程。 - 请参阅 [OAuth](/zh-CN/concepts/oauth)、[Model providers](/zh-CN/concepts/model-providers) 和 [新手引导（CLI）](/zh-CN/start/wizard)。 + 参见 [OAuth](/zh-CN/concepts/oauth)、[模型提供商](/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 网关主机上的认证配置文件中。详情请参阅：[Model providers](/zh-CN/concepts/model-providers)。 + 这会将 OAuth token 存储在 gateway 主机上的 auth profiles 中。详情参见：[模型提供商](/zh-CN/concepts/model-providers)。 - 通常不适合。OpenClaw 需要大上下文 + 强安全性；小卡模型会截断并泄露内容。如果你必须使用，请在本地运行你能承载的**最大**模型构建版本（LM Studio），并参阅 [/gateway/local-models](/zh-CN/gateway/local-models)。更小/量化的模型会增加提示注入风险——请参阅 [Security](/zh-CN/gateway/security)。 + 通常不适合。OpenClaw 需要大上下文 + 强安全性；小卡模型会截断并泄漏。如果你确实需要，请在本地运行你能承受的**最大**模型构建（LM Studio），并参见 [/gateway/local-models](/zh-CN/gateway/local-models)。更小/量化的模型会增加提示注入风险——参见 [Security](/zh-CN/gateway/security)。 - - 请选择区域固定的端点。OpenRouter 为 MiniMax、Kimi 和 GLM 提供了美国托管选项；选择美国托管变体即可让数据保留在该区域内。你仍然可以通过使用 `models.mode: "merge"` 将 Anthropic/OpenAI 与这些提供商一起列出，这样在遵守所选区域提供商限制的同时，回退选项仍然可用。 + + 请选择区域固定的端点。OpenRouter 为 MiniMax、Kimi 和 GLM 提供了美国托管选项；选择美国托管变体即可将数据保留在该区域内。你仍然可以通过使用 `models.mode: "merge"` 将 Anthropic/OpenAI 与这些选项一起列出，这样在遵循你所选区域 provider 的同时仍能保留回退能力。 - - 不需要。OpenClaw 可运行在 macOS 或 Linux 上（Windows 通过 WSL2）。Mac mini 是可选的——有些人 - 会买一台作为常开主机，但小型 VPS、家用服务器或 Raspberry Pi 级别的设备也可以。 + + 不需要。OpenClaw 可运行在 macOS 或 Linux 上（Windows 通过 WSL2）。Mac mini 是可选项——有些人 + 会买一台作为常开主机，但小型 VPS、家用服务器，或 Raspberry Pi 级别的机器也可以。 - 只有在你需要**仅限 macOS 的工具**时才需要 Mac。对于 iMessage，请使用 [BlueBubbles](/zh-CN/channels/bluebubbles)（推荐）——BlueBubbles 服务器运行在任意 Mac 上，而 Gateway 网关可以运行在 Linux 或其他地方。如果你还想使用其他仅限 macOS 的工具，可以在 Mac 上运行 Gateway 网关，或配对一个 macOS 节点。 + 只有在使用**仅限 macOS 的工具**时你才需要 Mac。对于 iMessage，请使用 [BlueBubbles](/zh-CN/channels/bluebubbles)（推荐）——BlueBubbles 服务器可运行在任意 Mac 上，而 Gateway 网关可以运行在 Linux 或其他地方。如果你想使用其他仅限 macOS 的工具，请在 Mac 上运行 Gateway 网关，或配对一个 macOS 节点。 文档：[BlueBubbles](/zh-CN/channels/bluebubbles)、[Nodes](/zh-CN/nodes)、[Mac remote mode](/zh-CN/platforms/mac/remote)。 - 你需要**某种 macOS 设备**登录到 Messages。它**不必**是 Mac mini—— - 任何 Mac 都可以。对于 iMessage，请**使用 [BlueBubbles](/zh-CN/channels/bluebubbles)**（推荐）——BlueBubbles 服务器运行在 macOS 上，而 Gateway 网关可以运行在 Linux 或其他地方。 + 你需要**某种已登录 Messages 的 macOS 设备**。它**不一定**是 Mac mini—— + 任意 Mac 都可以。对于 iMessage，**请使用 [BlueBubbles](/zh-CN/channels/bluebubbles)**（推荐）——BlueBubbles 服务器运行在 macOS 上，而 Gateway 网关可以运行在 Linux 或其他地方。 - 常见部署方式： + 常见设置： - - 在 Linux/VPS 上运行 Gateway 网关，并在任意登录了 Messages 的 Mac 上运行 BlueBubbles 服务器。 - - 如果你想要最简单的单机部署，也可以把所有内容都运行在这台 Mac 上。 + - 将 Gateway 网关运行在 Linux/VPS 上，并在任意一台已登录 Messages 的 Mac 上运行 BlueBubbles 服务器。 + - 如果你想要最简单的单机设置，也可以把所有内容都运行在这台 Mac 上。 文档：[BlueBubbles](/zh-CN/channels/bluebubbles)、[Nodes](/zh-CN/nodes)、 [Mac remote mode](/zh-CN/platforms/mac/remote)。 - + 可以。**Mac mini 可以运行 Gateway 网关**，而你的 MacBook Pro 可以作为 - **节点**（配套设备）连接。节点并不运行 Gateway 网关——它们会在该设备上提供额外能力， - 比如 screen/camera/canvas 和 `system.run`。 + **节点**（配套设备）连接。节点本身不运行 Gateway 网关——它们提供额外 + 能力，例如该设备上的屏幕/摄像头/canvas，以及 `system.run`。 常见模式： - - Gateway 网关运行在 Mac mini 上（始终在线）。 - - MacBook Pro 运行 macOS 应用或节点主机，并与 Gateway 网关配对。 + - Gateway 网关运行在 Mac mini 上（常开）。 + - MacBook Pro 运行 macOS app 或节点主机，并与 Gateway 网关配对。 - 使用 `openclaw nodes status` / `openclaw nodes list` 查看它。 文档：[Nodes](/zh-CN/nodes)、[Nodes CLI](/zh-CN/cli/nodes)。 - - **不推荐**使用 Bun。我们观察到运行时 bug，尤其是在 WhatsApp 和 Telegram 场景中。 - 稳定运行的 Gateway 网关请使用 **Node**。 + + **不推荐**使用 Bun。我们观察到运行时 bug，尤其是在 WhatsApp 和 Telegram 上。 + 要获得稳定的 Gateway 网关，请使用 **Node**。 - 如果你仍想试验 Bun，请在非生产 Gateway 网关上使用， + 如果你仍然想尝试 Bun，请仅在非生产环境的 Gateway 网关上进行， 并且不要启用 WhatsApp/Telegram。 - - `channels.telegram.allowFrom` 是**真人发送者的 Telegram 用户 ID**（数字）。 - 它不是机器人用户名。 + + `channels.telegram.allowFrom` 是**真人发送者的 Telegram 用户 ID**（数字），不是 bot 用户名。 - 设置流程只接受数字用户 ID。如果你的配置中已有旧版 `@username` 条目，`openclaw doctor --fix` 可以尝试解析它们。 + 设置流程只要求填写数字用户 ID。如果你的配置中已经有旧的 `@username` 条目，`openclaw doctor --fix` 可以尝试解析它们。 - 更安全的方式（无需第三方机器人）： + 更安全的方法（不使用第三方 bot）： - - 先私信你的机器人，然后运行 `openclaw logs --follow`，读取 `from.id`。 + - 给你的 bot 发私信，然后运行 `openclaw logs --follow` 并读取 `from.id`。 官方 Bot API： - - 私信你的机器人，然后调用 `https://api.telegram.org/bot/getUpdates`，读取 `message.from.id`。 + - 给你的 bot 发私信，然后调用 `https://api.telegram.org/bot/getUpdates` 并读取 `message.from.id`。 - 第三方方式（隐私性较差）： + 第三方方式（隐私性较低）： - - 私信 `@userinfobot` 或 `@getidsbot`。 + - 给 `@userinfobot` 或 `@getidsbot` 发私信。 - 请参阅 [/channels/telegram](/zh-CN/channels/telegram#access-control-and-activation)。 + 参见 [/channels/telegram](/zh-CN/channels/telegram#access-control-and-activation)。 - - 可以，通过**多智能体路由**实现。将每个发送者的 WhatsApp **私信** - （peer `kind: "direct"`，发送者 E.164 形如 `+15551234567`）绑定到不同的 `agentId`，这样每个人都会获得自己的工作区和会话存储。回复仍然来自**同一个 WhatsApp 账户**，而私信访问控制（`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`）在每个 WhatsApp 账户范围内是全局的。请参阅 [Multi-Agent Routing](/zh-CN/concepts/multi-agent) 和 [WhatsApp](/zh-CN/channels/whatsapp)。 + + 可以，通过**多智能体路由**实现。将每个发送者的 WhatsApp **私信**（peer `kind: "direct"`，发送者 E.164 格式例如 `+15551234567`）绑定到不同的 `agentId`，这样每个人都会获得各自独立的工作区和会话存储。回复仍然来自**同一个 WhatsApp 账户**，而私信访问控制（`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`）则对每个 WhatsApp 账户全局生效。参见 [多智能体路由](/zh-CN/concepts/multi-agent) 和 [WhatsApp](/zh-CN/channels/whatsapp)。 - - 可以。使用多智能体路由：为每个智能体设置各自的默认模型，然后将入站路由（提供商账户或特定 peers）绑定到对应智能体。示例配置见 [Multi-Agent Routing](/zh-CN/concepts/multi-agent)。另请参阅 [Models](/zh-CN/concepts/models) 和 [配置](/zh-CN/gateway/configuration)。 + + 可以。使用多智能体路由：给每个智能体设置各自的默认模型，然后将入站路由（provider 账户或特定 peer）绑定到对应智能体。示例配置见 [多智能体路由](/zh-CN/concepts/multi-agent)。另请参阅 [Models](/zh-CN/concepts/models) 和 [配置](/zh-CN/gateway/configuration)。 - + 可以。Homebrew 支持 Linux（Linuxbrew）。快速设置： ```bash @@ -813,14 +815,14 @@ x-i18n: brew install ``` - 如果你通过 systemd 运行 OpenClaw，请确保服务的 PATH 包含 `/home/linuxbrew/.linuxbrew/bin`（或你的 brew 前缀），这样 `brew` 安装的工具才能在非登录 shell 中被正确解析。 - 较新的构建版本还会在 Linux systemd 服务中预先添加常见的用户 bin 目录（例如 `~/.local/bin`、`~/.npm-global/bin`、`~/.local/share/pnpm`、`~/.bun/bin`），并在已设置时遵循 `PNPM_HOME`、`NPM_CONFIG_PREFIX`、`BUN_INSTALL`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`NVM_DIR` 和 `FNM_DIR`。 + 如果你通过 systemd 运行 OpenClaw，请确保服务的 PATH 包含 `/home/linuxbrew/.linuxbrew/bin`（或你的 brew 前缀），这样在非登录 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`。 - **可修改的（git）安装：**完整源码检出、可编辑，最适合贡献者。 - 你可以在本地运行构建，也可以修补代码/文档。 + 你可以在本地运行构建，并修改代码/文档。 - **npm install：**全局 CLI 安装，不包含仓库，最适合“直接运行”。 更新来自 npm dist-tags。 @@ -828,10 +830,10 @@ x-i18n: - - 可以。安装另一种形式后，再运行 Doctor，让 Gateway 网关服务指向新的入口点。 - 这**不会删除你的数据**——它只会更改 OpenClaw 代码的安装方式。你的状态 - （`~/.openclaw`）和工作区（`~/.openclaw/workspace`）都会保持不变。 + + 可以。安装另一种形式后，再运行 Doctor，让 gateway 服务指向新的入口点。 + 这**不会删除你的数据**——它只会更改 OpenClaw 代码安装方式。你的状态 + （`~/.openclaw`）和工作区（`~/.openclaw/workspace`）都不会受影响。 从 npm 切换到 git： @@ -852,147 +854,151 @@ x-i18n: openclaw gateway restart ``` - Doctor 会检测 Gateway 网关服务入口点不匹配的问题，并提供将服务配置重写为匹配当前安装的选项（在自动化中使用 `--repair`）。 + Doctor 会检测 gateway 服务入口点不匹配，并提供将服务配置重写为与当前安装相匹配的选项（在自动化中使用 `--repair`）。 - 备份建议：请参阅 [备份策略](#where-things-live-on-disk)。 + 备份提示：参见 [备份策略](#where-things-live-on-disk)。 - + 简短回答：**如果你想要 24/7 的可靠性，请使用 VPS**。如果你想要 - 最低摩擦，并且可以接受休眠/重启，那就在本地运行。 + 最低摩擦，并且可以接受休眠/重启，那么就在本地运行。 **笔记本电脑（本地 Gateway 网关）** - - **优点：**没有服务器成本，可直接访问本地文件，有可见的浏览器窗口。 - - **缺点：**休眠/网络中断 = 断连，操作系统更新/重启会打断运行，必须保持唤醒。 + - **优点：**没有服务器成本、可直接访问本地文件、可看到实时浏览器窗口。 + - **缺点：**休眠/网络中断 = 断连，操作系统更新/重启会打断运行，而且必须保持唤醒。 **VPS / 云端** - - **优点：**始终在线，网络稳定，没有笔记本休眠问题，更容易保持持续运行。 - - **缺点：**通常以无头方式运行（使用截图），只能远程访问文件，更新时必须通过 SSH。 + - **优点：**常开、网络稳定、没有笔记本休眠问题、更容易持续运行。 + - **缺点：**通常是 headless 运行（请用截图），只能远程访问文件，而且你必须通过 SSH 进行更新。 - **OpenClaw 特定说明：**WhatsApp/Telegram/Slack/Mattermost/Discord 都可以在 VPS 上正常运行。真正的权衡点只有 **无头浏览器** 与可见窗口之间的差异。请参阅 [Browser](/zh-CN/tools/browser)。 + **OpenClaw 特有说明：**WhatsApp/Telegram/Slack/Mattermost/Discord 在 VPS 上都能正常工作。唯一真正的权衡是**headless 浏览器**还是可见窗口。参见 [Browser](/zh-CN/tools/browser)。 - **推荐默认选择：**如果你之前遇到过 Gateway 网关断开连接，请使用 VPS。本地运行也很适合你正在积极使用 Mac，并且想要访问本地文件或使用可见浏览器进行 UI 自动化的时候。 + **推荐默认方案：**如果你之前遇到过 gateway 断连，就用 VPS。本地运行很适合你正在主动使用 Mac，并且希望访问本地文件或使用可见浏览器进行 UI 自动化的情况。 - 不是必需的，但为了**可靠性和隔离性**，这是推荐做法。 + 不是必须，但**为了可靠性和隔离性，推荐这样做**。 - - **专用主机（VPS/Mac mini/Pi）：**始终在线，更少受到休眠/重启打断，权限更干净，更容易保持持续运行。 - - **共享笔记本/台式机：**完全可以用于测试和日常主动使用，但当机器休眠或更新时，预计会出现暂停。 + - **专用主机（VPS/Mac mini/Pi）：**常开，更少的休眠/重启中断，更干净的权限边界，更容易长期运行。 + - **共享笔记本/台式机：**非常适合测试和主动使用，但在机器休眠或更新时预计会出现暂停。 - 如果你想兼得两者优点，可以把 Gateway 网关放在专用主机上，再把你的笔记本配对为一个**节点**，用于本地 screen/camera/exec 工具。请参阅 [Nodes](/zh-CN/nodes)。 - 如需安全性指导，请阅读 [Security](/zh-CN/gateway/security)。 + 如果你想兼顾两者优点，可以将 Gateway 网关放在专用主机上，并把你的笔记本电脑作为**节点**配对，以提供本地屏幕/摄像头/exec 工具。参见 [Nodes](/zh-CN/nodes)。 + 有关安全指导，请阅读 [Security](/zh-CN/gateway/security)。 - + OpenClaw 很轻量。对于基础的 Gateway 网关 + 一个聊天渠道： - **绝对最低配置：**1 vCPU、1GB RAM、约 500MB 磁盘。 - - **推荐配置：**1-2 vCPU、2GB RAM 或更多冗余空间（用于日志、媒体、多个渠道）。节点工具和浏览器自动化可能比较吃资源。 + - **推荐配置：**1–2 vCPU、2GB RAM 或更多余量（日志、媒体、多个渠道）。节点工具和浏览器自动化可能比较吃资源。 - 操作系统：使用 **Ubuntu LTS**（或任何现代 Debian/Ubuntu）。Linux 安装路径在这些系统上测试得最充分。 + 操作系统：使用 **Ubuntu LTS**（或任何现代 Debian/Ubuntu）。Linux 安装路径在这些系统上测试最充分。 文档：[Linux](/zh-CN/platforms/linux)、[VPS hosting](/zh-CN/vps)。 - - 可以。将 VM 视作 VPS 即可：它需要始终在线、可访问，并且有足够的 - RAM 来运行 Gateway 网关以及你启用的任何渠道。 + + 可以。把虚拟机当成 VPS 对待即可：它需要常开、可达，并为 + Gateway 网关和你启用的任何渠道提供足够的 RAM。 基线建议： - **绝对最低配置：**1 vCPU、1GB RAM。 - - **推荐配置：**如果你运行多个渠道、浏览器自动化或媒体工具，建议 2GB RAM 或更多。 + - **推荐配置：**如果你运行多个渠道、浏览器自动化或媒体工具，请使用 2GB RAM 或更多。 - **操作系统：**Ubuntu LTS 或其他现代 Debian/Ubuntu。 - 如果你使用的是 Windows，**WSL2 是最简单的 VM 风格部署方式**，并且拥有最佳的工具链 - 兼容性。请参阅 [Windows](/zh-CN/platforms/windows)、[VPS hosting](/zh-CN/vps)。 - 如果你在 VM 中运行 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 的一个包装器”。它是一个**本地优先的控制平面**，让你可以在**自己的硬件**上运行一个能力强大的助手，并通过你已经在使用的聊天应用访问它，同时具备有状态会话、记忆和工具——而无需把你的工作流控制权交给托管式 + OpenClaw 不只是“Claude 包装器”。它是一个**local-first 控制平面**，让你能够在**自己的硬件**上运行一个 + 功能强大的助手，并通过你已经使用的聊天应用访问它，同时拥有 + 有状态的会话、记忆和工具——而无需把你的工作流控制权交给托管式 SaaS。 亮点： - - **你的设备，你的数据：**你可以在任何你想要的地方运行 Gateway 网关（Mac、Linux、VPS），并将工作区 + 会话历史保留在本地。 - - **真实渠道，而不是 Web 沙箱：**WhatsApp/Telegram/Slack/Discord/Signal/iMessage 等， - 并且在支持的平台上还包括移动语音和 Canvas。 - - **模型无关：**可使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，并支持按智能体路由 + - **你的设备，你的数据：**在你想要的任何地方运行 Gateway 网关（Mac、Linux、VPS），并让 + 工作区 + 会话历史保留在本地。 + - **真实渠道，而不是 web 沙箱：**WhatsApp/Telegram/Slack/Discord/Signal/iMessage 等， + 以及在受支持平台上的移动语音和 Canvas。 + - **与模型无关：**使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，并支持按智能体路由 和故障切换。 - **纯本地选项：**运行本地模型，这样如果你愿意，**所有数据都可以保留在你的设备上**。 - - **多智能体路由：**按渠道、账户或任务拆分不同智能体，每个都有各自的 + - **多智能体路由：**按渠道、账户或任务拆分不同智能体，每个都有自己的 工作区和默认设置。 - - **开源且可修改：**可自行检查、扩展和自托管，不会被供应商锁定。 + - **开源且可修改：**可检查、可扩展、可自托管，没有厂商锁定。 - 文档：[Gateway](/zh-CN/gateway)、[Channels](/zh-CN/channels)、[Multi-agent](/zh-CN/concepts/multi-agent)、 - [Memory](/zh-CN/concepts/memory)。 + 文档：[Gateway 网关](/zh-CN/gateway)、[Channels](/zh-CN/channels)、[多智能体](/zh-CN/concepts/multi-agent)、 + [记忆](/zh-CN/concepts/memory)。 - - 很适合作为起步的项目包括： + + 很适合作为起步的项目： - - 搭建一个网站（WordPress、Shopify，或简单静态站点）。 - - 制作一个移动应用原型（大纲、界面、API 计划）。 + - 构建一个网站（WordPress、Shopify，或一个简单的静态站点）。 + - 为移动 app 做原型（大纲、界面、API 计划）。 - 整理文件和文件夹（清理、命名、打标签）。 - - 连接 Gmail，并自动化摘要或后续跟进。 + - 连接 Gmail，并自动生成摘要或跟进事项。 - 它可以处理大型任务，但当你把任务拆分成多个阶段，并 - 使用子智能体并行工作时，效果通常最好。 + 它可以处理大型任务，但当你将任务拆分为多个阶段， + 并使用子智能体并行工作时，效果最好。 - 日常最常见的收益通常是： + 日常高价值使用通常包括： - - **个人简报：**总结你关心的收件箱、日历和新闻。 + - **个人简报：**整理你关心的收件箱、日历和新闻摘要。 - **研究与起草：**快速研究、摘要，以及邮件或文档的初稿。 - - **提醒与跟进：**由 cron 或 Heartbeat 驱动的提示和清单。 - - **浏览器自动化：**填写表单、收集数据、重复执行 Web 任务。 - - **跨设备协作：**从手机发起任务，让 Gateway 网关在服务器上执行，并在聊天中把结果返回给你。 + - **提醒与跟进：**由 cron 或 heartbeat 驱动的提醒和清单。 + - **浏览器自动化：**填写表单、收集数据、重复执行网页任务。 + - **跨设备协作：**从手机发送任务，让 Gateway 网关在服务器上执行，并将结果返回到聊天中。 - 可以，用于**研究、筛选和起草**。它可以扫描网站、建立候选名单、 - 总结潜在客户信息，并撰写外联或广告文案草稿。 + 可以用于**研究、资格筛选和起草**。它可以扫描网站、建立候选名单、 + 总结潜在客户信息，并撰写外联文案或广告文案草稿。 - 对于**外联或广告投放**，请保留人工参与。避免垃圾信息，遵守当地法律和 - 平台政策，并在发送前审核所有内容。最安全的模式是让 + 对于**外联或广告投放**，请始终保留人工参与。避免垃圾信息，遵守当地法律和 + 平台政策，并在发送之前审阅所有内容。最安全的模式是让 OpenClaw 起草，由你审批。 文档：[Security](/zh-CN/gateway/security)。 - - OpenClaw 是一个**个人助手**和协作编排层，不是 IDE 的替代品。对于仓库内最快的直接编码循环，请使用 - Claude Code 或 Codex。当你需要持久记忆、跨设备访问和工具编排时，请使用 OpenClaw。 + + OpenClaw 是一个**个人助手**和协作编排层，而不是 IDE 替代品。对于仓库内最快的直接编码循环， + 请使用 Claude Code 或 Codex。需要持久记忆、跨设备访问和工具编排时， + 请使用 OpenClaw。 优势： - - **持久记忆 + 工作区**，跨会话保留 + - **跨会话持久记忆 + 工作区** - **多平台访问**（WhatsApp、Telegram、TUI、WebChat） - **工具编排**（浏览器、文件、调度、hooks） - - **始终在线的 Gateway 网关**（可运行在 VPS 上，并可随时随地交互） - - 用于本地 browser/screen/camera/exec 的 **节点** + - **始终在线的 Gateway 网关**（运行在 VPS 上，可随时随地交互） + - 用于本地浏览器/屏幕/摄像头/exec 的 **Nodes** 展示页：[https://openclaw.ai/showcase](https://openclaw.ai/showcase) @@ -1002,69 +1008,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。如果你需要全局安装某个技能，但只希望某些智能体能看到它，可以将共享副本保存在 `~/.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`。如果某个技能只应对特定智能体可见，请配合 `agents.defaults.skills` 或 `agents.list[].skills` 使用。 + + 可以。通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加额外目录（最低优先级）。默认优先级顺序是 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`。`clawhub` 默认安装到 `./skills`，OpenClaw 会在下一次会话中将其视为 `/skills`。如果该 skill 只应对某些智能体可见，请配合 `agents.defaults.skills` 或 `agents.list[].skills` 使用。 - 当前支持的模式有： + 目前支持的模式有： - - **Cron jobs**：隔离作业可以按作业设置 `model` 覆盖。 + - **Cron 作业**：独立作业可以为每个作业设置 `model` 覆盖。 - **子智能体**：将任务路由到具有不同默认模型的独立智能体。 - - **按需切换**：随时使用 `/model` 切换当前会话模型。 + - **按需切换**：使用 `/model` 随时切换当前会话模型。 - 请参阅 [Cron jobs](/zh-CN/automation/cron-jobs)、[Multi-Agent Routing](/zh-CN/concepts/multi-agent) 和 [Slash commands](/zh-CN/tools/slash-commands)。 + 参见 [Cron jobs](/zh-CN/automation/cron-jobs)、[多智能体路由](/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` 为子智能体设置 更便宜的模型。 - 文档：[Sub-agents](/zh-CN/tools/subagents)、[Background Tasks](/zh-CN/automation/tasks)。 + 文档：[子智能体](/zh-CN/tools/subagents)、[后台任务](/zh-CN/automation/tasks)。 - - 使用线程绑定。你可以把一个 Discord 线程绑定到某个子智能体或会话目标，这样该线程中的后续消息就会持续留在该绑定会话上。 + + 使用 thread 绑定。你可以将 Discord thread 绑定到某个子智能体或会话目标，这样该 thread 中的后续消息就会始终留在那个绑定会话上。 基本流程： - - 使用 `sessions_spawn` 并设置 `thread: true` 进行生成（可选再加上 `mode: "session"` 以支持持久后续交互）。 - - 或者通过 `/focus ` 手动绑定。 - - 使用 `/agents` 检查绑定状态。 + - 使用 `sessions_spawn` 并设置 `thread: true` 启动（也可以附加 `mode: "session"` 以支持持久后续跟进）。 + - 或者使用 `/focus ` 手动绑定。 + - 使用 `/agents` 查看绑定状态。 - 使用 `/session idle ` 和 `/session max-age ` 控制自动取消聚焦。 - - 使用 `/unfocus` 解除线程绑定。 + - 使用 `/unfocus` 解除 thread 绑定。 所需配置： - 全局默认值：`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`。 + - Discord 覆盖：`channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours`。 + - 在启动时自动绑定：设置 `channels.discord.threadBindings.spawnSubagentSessions: true`。 - 文档：[Sub-agents](/zh-CN/tools/subagents)、[Discord](/zh-CN/channels/discord)、[Configuration Reference](/zh-CN/gateway/configuration-reference)、[Slash commands](/zh-CN/tools/slash-commands)。 + 文档：[子智能体](/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 会有意抑制公告，而不是发送过时的早期进度。 - - 如果子智能体在只进行了工具调用后超时，公告可能会将其折叠成一条简短的部分进度摘要，而不是重放原始工具输出。 + - 完成模式的子智能体投递会在存在绑定 thread 或会话路由时优先使用它们。 + - 如果完成来源只携带渠道，OpenClaw 会回退到请求方会话存储的路由（`lastChannel` / `lastTo` / `lastAccountId`），这样直接投递仍有机会成功。 + - 如果既没有绑定路由，也没有可用的存储路由，直接投递可能失败，结果会回退到排队会话投递，而不是立即发到聊天中。 + - 无效或过期的目标仍然可能强制触发队列回退或最终投递失败。 + - 如果子任务最后一条可见的助手回复正好是静默 token `NO_REPLY` / `no_reply`，或正好是 `ANNOUNCE_SKIP`，OpenClaw 会有意抑制 announce，而不是发布先前过期的进度。 + - 如果子任务在只进行了工具调用之后超时，announce 可能会将其折叠为简短的部分进度摘要，而不是回放原始工具输出。 调试： @@ -1072,19 +1078,19 @@ x-i18n: openclaw tasks show ``` - 文档：[Sub-agents](/zh-CN/tools/subagents)、[Background Tasks](/zh-CN/automation/tasks)、[Session Tools](/zh-CN/concepts/session-tool)。 + 文档：[子智能体](/zh-CN/tools/subagents)、[后台任务](/zh-CN/automation/tasks)、[Session Tools](/zh-CN/concepts/session-tool)。 - Cron 在 Gateway 网关进程内运行。如果 Gateway 网关不是持续运行的， - 定时作业就不会运行。 + Cron 运行在 Gateway 网关进程内部。如果 Gateway 网关没有持续运行， + 计划作业就不会执行。 检查清单： - - 确认 cron 已启用（`cron.enabled`），并且未设置 `OPENCLAW_SKIP_CRON`。 + - 确认 cron 已启用（`cron.enabled`），并且没有设置 `OPENCLAW_SKIP_CRON`。 - 检查 Gateway 网关是否 24/7 运行（没有休眠/重启）。 - - 验证作业的时区设置（`--tz` 与主机时区）。 + - 验证作业的时区设置（`--tz` 与主机时区是否一致）。 调试： @@ -1097,17 +1103,17 @@ x-i18n: - + 先检查投递模式： - - `--no-deliver` / `delivery.mode: "none"` 表示不应期待 runner 回退发送。 - - 缺少或无效的公告目标（`channel` / `to`）意味着 runner 跳过了出站投递。 - - 渠道认证失败（`unauthorized`、`Forbidden`）意味着 runner 尝试投递了，但被凭据拦住了。 - - 静默的隔离结果（只有 `NO_REPLY` / `no_reply`）会被视为有意不投递，因此 runner 也会抑制排队回退投递。 + - `--no-deliver` / `delivery.mode: "none"` 表示不应期待运行器执行回退发送。 + - announce 目标缺失或无效（`channel` / `to`）意味着运行器跳过了出站投递。 + - 渠道身份验证失败（`unauthorized`、`Forbidden`）意味着运行器尝试投递了，但被凭证阻止。 + - 静默的独立结果（只有 `NO_REPLY` / `no_reply`）会被视为有意不投递，因此运行器也会抑制排队回退投递。 - 对于隔离的 cron 作业，只要有可用的聊天路由，智能体仍然可以通过 `message` - 工具直接发送。`--announce` 只控制 runner 的 - 最终文本回退路径，即智能体尚未自行发送的那部分内容。 + 对于独立 cron 作业，只要存在可用的聊天路由，智能体仍然可以通过 `message` + 工具直接发送。`--announce` 只控制运行器对 + 智能体尚未发送的最终文本的回退路径。 调试： @@ -1116,26 +1122,26 @@ x-i18n: openclaw tasks show ``` - 文档：[Cron jobs](/zh-CN/automation/cron-jobs)、[Background Tasks](/zh-CN/automation/tasks)。 + 文档：[Cron jobs](/zh-CN/automation/cron-jobs)、[后台任务](/zh-CN/automation/tasks)。 - + 这通常是实时模型切换路径，而不是重复调度。 - 隔离的 cron 在活动运行抛出 `LiveSessionModelSwitchError` 时， - 可以持久化运行时模型切换并重试。重试会保留切换后的 - provider/model；如果切换中还带有新的认证配置文件覆盖，cron + 独立 cron 可以在活动运行抛出 `LiveSessionModelSwitchError` 时持久化运行时模型交接并重试。 + 重试会保留切换后的 + provider/model；如果切换还携带了新的 auth profile 覆盖，cron 也会在重试前将其持久化。 - 相关的选择规则： + 相关选择规则： - 适用时，Gmail hook 模型覆盖优先级最高。 - - 然后是按作业设置的 `model`。 + - 其次是按作业指定的 `model`。 - 然后是任何已存储的 cron 会话模型覆盖。 - 最后才是正常的智能体/默认模型选择。 - 重试循环是有边界的。初始尝试加上 2 次切换重试之后， + 重试循环是有边界的。在初始尝试再加 2 次切换重试之后， cron 会中止，而不是无限循环。 调试： @@ -1150,7 +1156,7 @@ x-i18n: - 使用原生 `openclaw skills` 命令，或直接将 Skills 放入你的工作区。macOS 的 Skills UI 在 Linux 上不可用。 + 使用原生 `openclaw skills` 命令，或将 Skills 放入你的工作区。macOS 的 Skills UI 在 Linux 上不可用。 可在 [https://clawhub.ai](https://clawhub.ai) 浏览 Skills。 ```bash @@ -1164,40 +1170,41 @@ x-i18n: openclaw skills check ``` - 原生 `openclaw skills install` 会写入当前活动工作区的 `skills/` - 目录。只有在你想发布或同步你自己的 Skills 时，才需要安装单独的 `clawhub` CLI。对于跨智能体共享安装，请将技能放在 - `~/.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 网关调度器： - - **Cron jobs**：用于定时或周期性任务（重启后仍会保留）。 + - **Cron 作业**：用于计划任务或循环任务（重启后仍会保留）。 - **Heartbeat**：用于“主会话”的周期性检查。 - - **隔离作业**：用于可自主运行并发布摘要或向聊天投递内容的智能体。 + - **独立作业**：用于会发布摘要或投递到聊天中的自治智能体。 文档：[Cron jobs](/zh-CN/automation/cron-jobs)、[Automation & Tasks](/zh-CN/automation)、 [Heartbeat](/zh-CN/gateway/heartbeat)。 - - 不能直接运行。macOS Skills 受 `metadata.openclaw.os` 和所需二进制文件共同限制，并且只有当它们在 **Gateway 网关主机** 上符合条件时，Skills 才会出现在 system prompt 中。在 Linux 上，`darwin` 专属 Skills（如 `apple-notes`、`apple-reminders`、`things-mac`）不会加载，除非你覆盖这层限制。 + + 不能直接运行。macOS Skills 受 `metadata.openclaw.os` 和所需二进制文件约束，且只有当它们在 **Gateway 网关主机** 上符合条件时，Skills 才会出现在系统提示中。在 Linux 上，`darwin` 专属 Skills（如 `apple-notes`、`apple-reminders`、`things-mac`）不会加载，除非你覆盖这些限制条件。 你有三种受支持的模式： - **选项 A - 在 Mac 上运行 Gateway 网关（最简单）。** - 在存在这些 macOS 二进制文件的机器上运行 Gateway 网关，然后通过 [远程模式](#gateway-ports-already-running-and-remote-mode) 或 Tailscale 从 Linux 连接。由于 Gateway 网关主机是 macOS，这些 Skills 会正常加载。 + **选项 A —— 在 Mac 上运行 Gateway 网关（最简单）。** + 在具备 macOS 二进制文件的地方运行 Gateway 网关，然后通过 [远程模式](#gateway-ports-already-running-and-remote-mode) 或 Tailscale 从 Linux 连接。Skills 会正常加载，因为 Gateway 网关主机是 macOS。 - **选项 B - 使用 macOS 节点（无需 SSH）。** - 在 Linux 上运行 Gateway 网关，配对一个 macOS 节点（菜单栏应用），并将 **Node Run Commands** 在 Mac 上设置为 “Always Ask” 或 “Always Allow”。当所需二进制文件存在于该节点上时，OpenClaw 可以将仅限 macOS 的 Skills 视为符合条件。智能体会通过 `nodes` 工具运行这些 Skills。如果你选择 “Always Ask”，在提示中批准 “Always Allow” 会把该命令加入允许列表。 + **选项 B —— 使用 macOS 节点（无需 SSH）。** + 在 Linux 上运行 Gateway 网关，配对一个 macOS 节点（菜单栏 app），并在 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 包装器。然后覆盖技能配置以允许 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 @@ -1205,36 +1212,36 @@ x-i18n: exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@" ``` - 2. 将该包装器放到 Linux 主机的 `PATH` 中（例如 `~/bin/memo`）。 - 3. 覆盖技能元数据（工作区中或 `~/.openclaw/skills`）以允许 Linux： + 2. 将包装器放到 Linux 主机的 `PATH` 中（例如 `~/bin/memo`）。 + 3. 覆盖 skill 元数据（工作区或 `~/.openclaw/skills`）以允许 Linux： ```markdown --- name: apple-notes - description: 通过 macOS 上的 memo CLI 管理 Apple Notes。 + description: Manage Apple Notes via the memo CLI on macOS. metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } } --- ``` - 4. 启动一个新会话，以刷新 Skills 快照。 + 4. 启动一个新会话，以便刷新 Skills 快照。 目前没有内置。 - 选项： + 可选方案： - - **自定义技能 / 插件：**这是实现可靠 API 访问的最佳方式（Notion/HeyGen 都有 API）。 - - **浏览器自动化：**无需写代码，但速度较慢，也更脆弱。 + - **自定义 skill / 插件：**最适合可靠的 API 访问（Notion/HeyGen 都有 API）。 + - **浏览器自动化：**无需写代码，但速度更慢，也更脆弱。 - 如果你想为每个客户保留上下文（代理工作流），一个简单模式是： + 如果你想为每个客户保留上下文（代理机构工作流），一种简单模式是： - 每个客户一个 Notion 页面（上下文 + 偏好 + 当前工作）。 - 让智能体在会话开始时获取该页面。 如果你想要原生集成，请提交功能请求，或构建一个 - 面向这些 API 的技能。 + 面向这些 API 的 skill。 安装 Skills： @@ -1243,11 +1250,11 @@ 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 连接： ```bash @@ -1255,20 +1262,20 @@ x-i18n: 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`，并且当前一次只支持一个文件 - - `responsebody`、PDF 导出、下载拦截和批量操作仍然需要托管浏览器或原始 CDP 配置文件 + - 操作是基于 ref 驱动的，而不是基于 CSS 选择器驱动 + - 上传需要 `ref` / `inputRef`，并且目前一次只支持一个文件 + - `responsebody`、PDF 导出、下载拦截和批量操作仍然需要受管浏览器或原始 CDP 配置文件 @@ -1276,16 +1283,16 @@ x-i18n: ## 沙箱隔离和记忆 - - 有。请参阅 [沙箱隔离](/zh-CN/gateway/sandboxing)。对于 Docker 专用设置（在 Docker 中运行完整 Gateway 网关或沙箱镜像），请参阅 [Docker](/zh-CN/install/docker)。 + + 有。参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。对于 Docker 专用设置（在 Docker 中运行完整 gateway 或沙箱镜像），参见 [Docker](/zh-CN/install/docker)。 - 默认镜像以安全优先为原则，并以 `node` 用户身份运行，因此它不 + 默认镜像以安全优先方式运行，并以 `node` 用户身份执行，因此它不 包含系统软件包、Homebrew 或内置浏览器。若要获得更完整的设置： - - 使用 `OPENCLAW_HOME_VOLUME` 持久化 `/home/node`，这样缓存才能保留下来。 - - 使用 `OPENCLAW_DOCKER_APT_PACKAGES` 将系统依赖烘焙进镜像中。 + - 使用 `OPENCLAW_HOME_VOLUME` 持久化 `/home/node`，以便缓存保留。 + - 使用 `OPENCLAW_DOCKER_APT_PACKAGES` 将系统依赖烘焙进镜像。 - 通过内置 CLI 安装 Playwright 浏览器： `node /app/node_modules/playwright-core/cli.js install chromium` - 设置 `PLAYWRIGHT_BROWSERS_PATH`，并确保该路径已持久化。 @@ -1294,133 +1301,133 @@ x-i18n: - - 可以——前提是你的私有流量是**私信**，而公开流量是**群组**。 + + 可以——前提是你的私密流量是**私信**，而公开流量是**群组**。 - 使用 `agents.defaults.sandbox.mode: "non-main"`，这样群组/渠道会话（非主会话键）会在已配置的沙箱后端中运行，而主私信会话仍保留在主机上。如果你没有选择具体后端，Docker 是默认后端。然后通过 `tools.sandbox.tools` 限制沙箱隔离会话中可用的工具。 + 使用 `agents.defaults.sandbox.mode: "non-main"`，这样群组/渠道会话（非 main 键）会在已配置的沙箱后端中运行，而主私信会话仍在主机上运行。如果你没有选择后端，Docker 是默认后端。然后通过 `tools.sandbox.tools` 限制沙箱隔离会话中可用的工具。 - 设置演练 + 示例配置：[群组：私人私信 + 公开群组](/zh-CN/channels/groups#pattern-personal-dms-public-groups-single-agent) + 设置演练 + 示例配置： [群组：私密私信 + 公开群组](/zh-CN/channels/groups#pattern-personal-dms-public-groups-single-agent) 关键配置参考：[Gateway 网关配置](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox) - - 将 `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 会根据规范化路径，以及通过最深层已存在祖先目录解析出的规范路径，同时校验 bind 源。这意味着即使最后一个路径段尚不存在，通过符号链接父目录进行逃逸的情况也会被默认拒绝，而允许根目录检查在符号链接解析之后仍然适用。 + OpenClaw 会同时根据规范化路径，以及通过最深层现有祖先解析出的规范路径，来验证绑定源。这意味着即使最后一个路径段尚不存在，通过符号链接父级逃逸的情况也会默认失败关闭，而允许根目录检查在符号链接解析后仍然适用。 - 示例和安全说明请参阅 [沙箱隔离](/zh-CN/gateway/sandboxing#custom-bind-mounts) 和 [Sandbox vs Tool Policy vs Elevated](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check)。 + 有关示例和安全说明，请参见 [沙箱隔离](/zh-CN/gateway/sandboxing#custom-bind-mounts) 和 [沙箱 vs 工具策略 vs 提权](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check)。 - OpenClaw 的记忆就是智能体工作区中的 Markdown 文件： + OpenClaw 的记忆其实就是智能体工作区中的 Markdown 文件： - - `memory/YYYY-MM-DD.md` 中的每日笔记 - - `MEMORY.md` 中整理过的长期笔记（仅主/私密会话） + - `memory/YYYY-MM-DD.md` 中的每日日志 + - `MEMORY.md` 中整理好的长期笔记（仅主会话/私密会话） - OpenClaw 还会运行一个**静默的预压缩记忆刷新**，提醒模型 - 在自动压缩前写入持久笔记。该操作仅在工作区 - 可写时运行（只读沙箱会跳过它）。请参阅 [Memory](/zh-CN/concepts/memory)。 + OpenClaw 还会运行一个**静默的预压缩记忆刷新**，以提醒模型 + 在自动压缩前写下持久笔记。这个过程只会在工作区 + 可写时运行（只读沙箱会跳过）。参见 [记忆](/zh-CN/concepts/memory)。 - - 让机器人**把这个事实写入记忆**。长期笔记应写入 `MEMORY.md`， + + 让机器人**把这个事实写入记忆**。长期笔记应该写入 `MEMORY.md`， 短期上下文则写入 `memory/YYYY-MM-DD.md`。 这是我们仍在持续改进的领域。提醒模型存储记忆会有帮助； - 它会知道该怎么做。如果它还是经常忘记，请确认 Gateway 网关每次运行时 - 使用的是同一个工作区。 + 它会知道该怎么做。如果它总是忘记，请确认 Gateway 网关每次运行 + 都使用同一个工作区。 - 文档：[Memory](/zh-CN/concepts/memory)、[智能体工作区](/zh-CN/concepts/agent-workspace)。 + 文档：[记忆](/zh-CN/concepts/memory)、[智能体工作区](/zh-CN/concepts/agent-workspace)。 - - 记忆文件保存在磁盘上，除非你删除它们，否则会一直存在。限制来自你的 - 存储空间，而不是模型本身。**会话上下文**仍然受模型 - 上下文窗口限制，因此长对话可能会被压缩或截断。这就是为什么 - 会有记忆搜索——它只会把相关部分重新拉回上下文。 + + 记忆文件存储在磁盘上，除非你删除它们，否则会一直保留。限制来自你的 + 存储空间，而不是模型。**会话上下文**仍然受模型上下文窗口 + 限制，因此长对话可能会被压缩或截断。这就是为什么会有 + 记忆搜索——它只会把相关部分拉回上下文中。 - 文档：[Memory](/zh-CN/concepts/memory)、[Context](/zh-CN/concepts/context)。 + 文档：[记忆](/zh-CN/concepts/memory)、[上下文](/zh-CN/concepts/context)。 - + 只有当你使用 **OpenAI embeddings** 时才需要。Codex OAuth 仅覆盖聊天/补全， - **不**提供 embeddings 访问权限，因此**使用 Codex 登录（OAuth 或 - Codex CLI 登录）**对语义记忆搜索没有帮助。OpenAI embeddings - 仍然需要真实的 API 密钥（`OPENAI_API_KEY` 或 `models.providers.openai.apiKey`）。 + **不**提供 embeddings 访问，因此**使用 Codex 登录（OAuth 或 + Codex CLI 登录）**并不能帮助语义记忆搜索。OpenAI embeddings + 仍然需要真正的 API key（`OPENAI_API_KEY` 或 `models.providers.openai.apiKey`）。 - 如果你没有显式设置提供商，OpenClaw 会在能够解析 API 密钥时 - 自动选择一个提供商（认证配置文件、`models.providers.*.apiKey` 或环境变量）。 - 如果能解析出 OpenAI 密钥，它会优先选择 OpenAI；否则如果能解析出 Gemini 密钥， - 则选择 Gemini；然后是 Voyage；再然后是 Mistral。如果没有可用的远程密钥，记忆 - 搜索会保持禁用，直到你完成配置。如果你已配置并存在本地模型路径，OpenClaw + 如果你没有显式设置 provider，只要 OpenClaw 能解析出 API key， + 它就会自动选择一个 provider（来自 auth profiles、`models.providers.*.apiKey` 或环境变量）。 + 如果能解析出 OpenAI key，它会优先选择 OpenAI；否则如果能解析出 Gemini key， + 就选择 Gemini；然后是 Voyage；再然后是 Mistral。如果没有可用的远程 key， + 记忆搜索会保持禁用，直到你完成配置。如果你已经配置并提供了本地模型路径，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** - 嵌入模型——请参阅 [Memory](/zh-CN/concepts/memory) 了解设置细节。 + `memorySearch.remote.apiKey`）。我们支持 **OpenAI、Gemini、Voyage、Mistral、Ollama 或 local** embeddings + 模型——设置细节参见 [记忆](/zh-CN/concepts/memory)。 -## 磁盘上的文件位置 +## 磁盘上的存储位置 - - 不会——**OpenClaw 的状态保存在本地**，但**外部服务仍然能看到你发送给它们的内容**。 + + 不会——**OpenClaw 的状态是在本地的**，但**外部服务仍然会看到你发送给它们的内容**。 - - **默认本地：**会话、记忆文件、配置和工作区都保存在 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)。 + 相关内容：[智能体工作区](/zh-CN/concepts/agent-workspace)、[记忆](/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/secrets.json` | `file` SecretRef 提供商使用的可选文件支持的 secret 负载 | - | `$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//sessions/` | 对话历史和状态（按智能体） | - | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | 会话元数据（按智能体） | + | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | 旧版 OAuth 导入文件（首次使用时会复制到 auth profiles） | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Auth profiles（OAuth、API keys，以及可选的 `keyRef`/`tokenRef`） | + | `$OPENCLAW_STATE_DIR/secrets.json` | `file` SecretRef provider 的可选文件后备 secret 负载 | + | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | 旧版兼容文件（静态 `api_key` 条目已被清理） | + | `$OPENCLAW_STATE_DIR/credentials/` | Provider 状态（例如 `whatsapp//creds.json`） | + | `$OPENCLAW_STATE_DIR/agents/` | 按智能体划分的状态（agentDir + sessions） | + | `$OPENCLAW_STATE_DIR/agents//sessions/` | 对话历史和状态（按智能体） | + | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | 会话元数据（按智能体） | 旧版单智能体路径：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移）。 - 你的**工作区**（AGENTS.md、记忆文件、Skills 等）是分开的，并通过 `agents.defaults.workspace` 配置（默认：`~/.openclaw/workspace`）。 + 你的**工作区**（`AGENTS.md`、记忆文件、Skills 等）是独立的，并通过 `agents.defaults.workspace` 配置（默认：`~/.openclaw/workspace`）。 这些文件位于**智能体工作区**中，而不是 `~/.openclaw`。 - - **工作区（按智能体）：**`AGENTS.md`、`SOUL.md`、`IDENTITY.md`、`USER.md`、 + - **工作区（按智能体）**：`AGENTS.md`、`SOUL.md`、`IDENTITY.md`、`USER.md`、 `MEMORY.md`、`memory/YYYY-MM-DD.md`，以及可选的 `HEARTBEAT.md`。 - 小写根目录 `memory.md` 仅作为旧版修复输入；当两个文件都存在时，`openclaw doctor --fix` + 小写根目录 `memory.md` 仅作为旧版修复输入使用；当两个文件都存在时，`openclaw doctor --fix` 可以将其合并到 `MEMORY.md` 中。 - - **状态目录（`~/.openclaw`）：**配置、渠道/提供商状态、认证配置文件、会话、日志， + - **状态目录（`~/.openclaw`）**：配置、渠道/provider 状态、auth profiles、会话、日志， 以及共享 Skills（`~/.openclaw/skills`）。 - 默认工作区为 `~/.openclaw/workspace`，可通过以下方式配置： + 默认工作区是 `~/.openclaw/workspace`，可通过以下配置更改： ```json5 { @@ -1428,23 +1435,23 @@ x-i18n: } ``` - 如果机器人在重启后“忘记”了内容，请确认 Gateway 网关每次启动时 - 使用的是同一个工作区（并且记住：远程模式使用的是**Gateway 网关主机的** - 工作区，而不是你的本地笔记本）。 + 如果机器人在重启后“忘记了”东西，请确认 Gateway 网关每次启动 + 都使用同一个工作区（并记住：remote 模式使用的是**gateway 主机** + 的工作区，而不是你本地笔记本电脑的工作区）。 - 提示：如果你希望某种行为或偏好能够长期保留，请让机器人**将其写入 + 提示：如果你希望某种行为或偏好能够长期保留，请让机器人**把它写进 AGENTS.md 或 MEMORY.md**，而不是依赖聊天历史。 - 请参阅 [智能体工作区](/zh-CN/concepts/agent-workspace) 和 [Memory](/zh-CN/concepts/memory)。 + 参见 [智能体工作区](/zh-CN/concepts/agent-workspace) 和 [记忆](/zh-CN/concepts/memory)。 - 请将你的**智能体工作区**放入一个**私有** git 仓库，并将其备份到某个 - 私有位置（例如 GitHub 私有仓库）。这样可以保存记忆 + AGENTS/SOUL/USER - 文件，并让你之后可以恢复这个助手的“心智”。 + 将你的**智能体工作区**放在一个**私有** git 仓库中，并备份到某个 + 私密位置（例如 GitHub 私有仓库）。这样可以保留记忆 + AGENTS/SOUL/USER + 文件，并让你以后能够恢复助手的“心智”。 - **不要**提交 `~/.openclaw` 下的任何内容（凭据、会话、令牌或加密 secret 负载）。 + **不要**提交 `~/.openclaw` 下的任何内容（凭证、会话、token 或加密的 secrets 负载）。 如果你需要完整恢复，请分别备份工作区和状态目录 （参见上面的迁移问题）。 @@ -1453,16 +1460,16 @@ x-i18n: - 请参阅专门指南：[Uninstall](/zh-CN/install/uninstall)。 + 参见专门指南：[Uninstall](/zh-CN/install/uninstall)。 - 可以。工作区是默认的 **cwd** 和记忆锚点，而不是一个硬性沙箱。 - 相对路径会在工作区内解析，但绝对路径仍可访问其他 - 主机位置，除非启用了沙箱隔离。如果你需要隔离，请使用 + 可以。工作区是默认的 **cwd** 和记忆锚点，而不是硬性沙箱。 + 相对路径会在工作区内解析，但绝对路径仍可访问主机上的其他 + 位置，除非启用了沙箱隔离。如果你需要隔离，请使用 [`agents.defaults.sandbox`](/zh-CN/gateway/sandboxing) 或按智能体设置沙箱。如果你 - 希望某个仓库成为默认工作目录，请将该智能体的 - `workspace` 指向仓库根目录。OpenClaw 仓库本身只是源码；除非你明确想让智能体在其中工作，否则请保持 + 想让某个仓库成为默认工作目录，请把那个智能体的 + `workspace` 指向仓库根目录。OpenClaw 仓库本身只是源码；除非你有意让智能体在其中工作，否则请保持 工作区与其分离。 示例（将仓库作为默认 cwd）： @@ -1479,30 +1486,30 @@ x-i18n: - - 会话状态由**Gateway 网关主机**持有。如果你处于远程模式，你真正关心的会话存储位于远程机器上，而不是本地笔记本。请参阅 [会话管理](/zh-CN/concepts/session)。 + + 会话状态归**gateway 主机**所有。如果你处于 remote 模式，那么你关心的会话存储位于远程机器上，而不是你本地笔记本电脑上。参见 [会话管理](/zh-CN/concepts/session)。 ## 配置基础 - - OpenClaw 会从 `$OPENCLAW_CONFIG_PATH` 读取可选的 **JSON5** 配置（默认：`~/.openclaw/openclaw.json`）： + + OpenClaw 会从 `$OPENCLAW_CONFIG_PATH`（默认：`~/.openclaw/openclaw.json`）读取可选的 **JSON5** 配置： ``` $OPENCLAW_CONFIG_PATH ``` - 如果该文件不存在，它会使用相对安全的默认值（包括默认工作区 `~/.openclaw/workspace`）。 + 如果文件不存在，它会使用相对安全的默认值（包括默认工作区 `~/.openclaw/workspace`）。 - - 非 loopback 绑定**需要有效的 Gateway 网关认证路径**。实际来说，这意味着： + + 非 loopback 绑定**需要有效的 gateway 身份验证路径**。实际配置通常意味着： - - 共享密钥认证：令牌或密码 - - `gateway.auth.mode: "trusted-proxy"`，位于配置正确的非 loopback、支持身份感知的反向代理之后 + - shared-secret 身份验证：token 或密码 + - `gateway.auth.mode: "trusted-proxy"`，且位于正确配置的非 loopback 身份感知反向代理之后 ```json5 { @@ -1518,31 +1525,31 @@ x-i18n: 说明： - - `gateway.remote.token` / `.password` **不会**单独启用本地 Gateway 网关认证。 - - 只有在 `gateway.auth.*` 未设置时，本地调用路径才会将 `gateway.remote.*` 用作回退。 - - 对于密码认证，请改为设置 `gateway.auth.mode: "password"` 以及 `gateway.auth.password`（或 `OPENCLAW_GATEWAY_PASSWORD`）。 - - 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password`，但无法解析，则解析会默认拒绝（不会再用远程回退掩盖问题）。 - - 基于共享密钥的 Control UI 部署通过 `connect.params.auth.token` 或 `connect.params.auth.password` 进行认证（存储在应用/UI 设置中）。像 Tailscale Serve 或 `trusted-proxy` 这样的带身份模式则使用请求头。避免将共享密钥放入 URL 中。 - - 在 `gateway.auth.mode: "trusted-proxy"` 下，同主机 loopback 反向代理仍然**不能**满足 trusted-proxy 认证。trusted proxy 必须是已配置的非 loopback 来源。 + - `gateway.remote.token` / `.password` 本身**不会**启用本地 gateway 身份验证。 + - 只有在 `gateway.auth.*` 未设置时，本地调用路径才会把 `gateway.remote.*` 作为回退使用。 + - 对于密码身份验证，请改为设置 `gateway.auth.mode: "password"`，并同时设置 `gateway.auth.password`（或 `OPENCLAW_GATEWAY_PASSWORD`）。 + - 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 但无法解析，则会失败关闭（不会由远程回退进行掩盖）。 + - 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 来源。 - - 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"`（默认）：安全更改热应用，关键更改则重启 - 也支持 `hot`、`restart`、`off` - + 在配置中设置 `cli.banner.taglineMode`： ```json5 @@ -1555,24 +1562,24 @@ x-i18n: } ``` - - `off`：隐藏标语文本，但保留横幅标题/版本行。 + - `off`：隐藏标语文本，但保留 banner 标题/版本行。 - `default`：每次都使用 `All your chats, one OpenClaw.`。 - - `random`：轮换显示有趣/节日标语（默认行为）。 - - 如果你想完全不显示横幅，请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 + - `random`：轮换显示有趣/季节性标语（默认行为）。 + - 如果你想完全不显示 banner，请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 - - `web_fetch` 无需 API 密钥即可工作。`web_search` 取决于你所选择的 - 提供商： + + `web_fetch` 无需 API key 即可工作。`web_search` 取决于你所选的 + provider： - - Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Perplexity 和 Tavily 等基于 API 的提供商需要按其常规方式配置 API 密钥。 - - Ollama Web 搜索无需密钥，但它会使用你已配置的 Ollama 主机，并且需要 `ollama signin`。 - - DuckDuckGo 无需密钥，但它是一个非官方的基于 HTML 的集成。 + - Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Perplexity 和 Tavily 等基于 API 的 provider，需要其常规 API key 设置。 + - Ollama Web 搜索 无需密钥，但它使用你配置的 Ollama 主机，并要求执行 `ollama signin`。 + - DuckDuckGo 无需密钥，但这是基于 HTML 的非官方集成。 - SearXNG 无需密钥/可自托管；请配置 `SEARXNG_BASE_URL` 或 `plugins.entries.searxng.config.webSearch.baseUrl`。 - **推荐：**运行 `openclaw configure --section web` 并选择一个提供商。 - 也可以使用环境变量： + **推荐：**运行 `openclaw configure --section web` 并选择一个 provider。 + 环境变量替代方式： - Brave：`BRAVE_API_KEY` - Exa：`EXA_API_KEY` @@ -1614,69 +1621,69 @@ x-i18n: } ``` - 提供商专属的 Web 搜索配置现在位于 `plugins.entries..config.webSearch.*` 下。 - 为了兼容，旧版 `tools.web.search.*` 提供商路径目前仍会临时加载，但新配置不应再使用它们。 - Firecrawl Web 抓取回退配置位于 `plugins.entries.firecrawl.config.webFetch.*` 下。 + provider 专属的 web 搜索配置现在位于 `plugins.entries..config.webSearch.*` 下。 + 旧版 `tools.web.search.*` provider 路径目前仍会暂时加载以保持兼容，但不应再用于新配置。 + Firecrawl 的 web 抓取回退配置位于 `plugins.entries.firecrawl.config.webFetch.*` 下。 说明： - - 如果你使用 allowlist，请加入 `web_search`/`web_fetch`/`x_search` 或 `group:web`。 - - `web_fetch` 默认启用（除非被显式禁用）。 - - 如果省略 `tools.web.fetch.provider`，OpenClaw 会从可用凭据中自动检测第一个就绪的抓取回退提供商。目前内置提供商是 Firecrawl。 + - 如果你使用 allowlists，请添加 `web_search`/`web_fetch`/`x_search` 或 `group:web`。 + - `web_fetch` 默认启用（除非显式禁用）。 + - 如果省略 `tools.web.fetch.provider`，OpenClaw 会根据可用凭证自动检测第一个可用的抓取回退 provider。目前内置 provider 是 Firecrawl。 - 守护进程会从 `~/.openclaw/.env`（或服务环境）读取环境变量。 - 文档：[Web tools](/zh-CN/tools/web)。 + 文档：[Web 工具](/zh-CN/tools/web)。 - + `config.apply` 会替换**整个配置**。如果你发送的是部分对象，其他所有内容 都会被移除。 - 当前 OpenClaw 会防止许多意外覆盖： + 当前的 OpenClaw 会防止许多意外覆写： - - OpenClaw 自有的配置写入会在写入前验证更改后的完整配置。 + - OpenClaw 自己执行的配置写入会在写入前验证变更后的完整配置。 - 无效或破坏性的 OpenClaw 自有写入会被拒绝，并保存为 `openclaw.json.rejected.*`。 - - 如果直接编辑破坏了启动或热重载，Gateway 网关会恢复最近一次已知正常配置，并将被拒绝的文件保存为 `openclaw.json.clobbered.*`。 - - 恢复后，主智能体会收到启动警告，以防它再次盲目写入错误配置。 + - 如果直接编辑破坏了启动或热重载，Gateway 网关会恢复最后一个已知正常配置，并将被拒绝的文件保存为 `openclaw.json.clobbered.*`。 + - 恢复后，主智能体会收到启动警告，这样它就不会再次盲目写入那个错误配置。 - 恢复方法： + 恢复方式： - 检查 `openclaw logs --follow` 中是否有 `Config auto-restored from last-known-good`、`Config write rejected:` 或 `config reload restored last-known-good config`。 - - 在活动配置旁边检查最新的 `openclaw.json.clobbered.*` 或 `openclaw.json.rejected.*`。 - - 如果当前恢复后的活动配置可用，就保留它，然后只用 `openclaw config set` 或 `config.patch` 把你原本想改的键复制回来。 + - 检查活动配置旁边最新的 `openclaw.json.clobbered.*` 或 `openclaw.json.rejected.*`。 + - 如果当前恢复后的活动配置可用，就保留它，然后用 `openclaw config set` 或 `config.patch` 只把你原本想改的键复制回去。 - 运行 `openclaw config validate` 和 `openclaw doctor`。 - - 如果你没有 last-known-good 或被拒绝的负载，请从备份恢复，或重新运行 `openclaw doctor` 并重新配置渠道/模型。 - - 如果这是意料之外的行为，请提交 bug，并附上你最后已知的配置或任何备份。 + - 如果你没有 last-known-good 或被拒绝的负载，请从备份恢复，或者重新运行 `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`。 + - 如果你在智能体运行中使用仅限所有者的 `gateway` 工具，它仍然会拒绝写入 `tools.exec.ask` / `tools.exec.security`（包括会规范化到相同受保护 exec 路径的旧版 `tools.bash.*` 别名）。 文档：[配置](/zh-CN/cli/config)、[Configure](/zh-CN/cli/configure)、[Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)、[Doctor](/zh-CN/gateway/doctor)。 - + 常见模式是**一个 Gateway 网关**（例如 Raspberry Pi）加上**节点**和**智能体**： - **Gateway 网关（中心）：**负责渠道（Signal/WhatsApp）、路由和会话。 - **节点（设备）：**Mac/iOS/Android 作为外围设备连接，并暴露本地工具（`system.run`、`canvas`、`camera`）。 - - **智能体（工作节点）：**用于特定角色的独立“大脑”/工作区（例如“Hetzner 运维”“个人数据”）。 - - **子智能体：**当你想要并行处理时，从主智能体生成后台工作。 + - **智能体（工作节点）：**为特殊角色提供独立的大脑/工作区（例如“Hetzner 运维”“个人数据”）。 + - **子智能体：**当你想并行处理时，从主智能体中启动后台工作。 - **TUI：**连接到 Gateway 网关并切换智能体/会话。 - 文档：[Nodes](/zh-CN/nodes)、[远程访问](/zh-CN/gateway/remote)、[Multi-Agent Routing](/zh-CN/concepts/multi-agent)、[Sub-agents](/zh-CN/tools/subagents)、[TUI](/zh-CN/web/tui)。 + 文档：[Nodes](/zh-CN/nodes)、[远程访问](/zh-CN/gateway/remote)、[多智能体路由](/zh-CN/concepts/multi-agent)、[子智能体](/zh-CN/tools/subagents)、[TUI](/zh-CN/web/tui)。 - - 可以。这是一个配置项： + + 可以。这是一个配置选项： ```json5 { @@ -1689,19 +1696,19 @@ x-i18n: } ``` - 默认值是 `false`（有头模式）。在某些网站上，无头模式更容易触发反机器人检查。请参阅 [Browser](/zh-CN/tools/browser)。 + 默认值为 `false`（headful）。在某些网站上，headless 模式更容易触发反机器人检测。参见 [Browser](/zh-CN/tools/browser)。 - 无头模式使用**相同的 Chromium 引擎**，适用于大多数自动化任务（表单、点击、抓取、登录）。主要区别在于： + Headless 使用**同一个 Chromium 引擎**，适用于大多数自动化任务（表单、点击、抓取、登录）。主要区别是： - - 没有可见的浏览器窗口（如果你需要视觉反馈，请使用截图）。 - - 某些网站对无头模式下的自动化更严格（CAPTCHA、反机器人）。 - 例如，X/Twitter 经常会拦截无头会话。 + - 没有可见的浏览器窗口（如果你需要可视内容，请使用截图）。 + - 某些网站在 headless 模式下对自动化更严格（CAPTCHA、反机器人）。 + 例如，X/Twitter 通常会阻止 headless 会话。 将 `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)。 @@ -1709,26 +1716,26 @@ x-i18n: - Telegram 消息由 **Gateway 网关** 处理。Gateway 网关运行智能体，然后 - 只有在需要节点工具时，才会通过 **Gateway WebSocket** 调用节点： + Telegram 消息由**gateway**处理。Gateway 网关运行智能体，并且 + 只有在需要节点工具时，才会通过**Gateway WebSocket** 调用节点： Telegram → Gateway 网关 → 智能体 → `node.*` → 节点 → Gateway 网关 → Telegram - 节点看不到入站提供商流量；它们只接收节点 RPC 调用。 + 节点看不到入站 provider 流量；它们只接收节点 RPC 调用。 - - 简短回答：**把你的电脑配对为一个节点**。Gateway 网关运行在别处，但它可以 + + 简短回答：**将你的电脑配对为一个节点**。Gateway 网关运行在别处，但它可以 通过 Gateway WebSocket 在你的本地机器上调用 `node.*` 工具（屏幕、摄像头、系统）。 - 典型部署方式： + 典型设置： - 1. 在始终在线的主机上运行 Gateway 网关（VPS/家用服务器）。 - 2. 将 Gateway 网关主机和你的电脑放到同一个 tailnet 中。 - 3. 确保 Gateway 网关 WS 可达（tailnet 绑定或 SSH 隧道）。 - 4. 在本地打开 macOS 应用，并以**通过 SSH 远程连接**模式（或直接 tailnet） - 连接，以便它可以注册为一个节点。 + 1. 在始终在线的主机上运行 Gateway 网关（VPS/家庭服务器）。 + 2. 让 Gateway 网关主机和你的电脑位于同一个 tailnet 中。 + 3. 确保 Gateway WS 可达（tailnet 绑定或 SSH 隧道）。 + 4. 在本地打开 macOS app，并以**Remote over SSH** 模式（或直接 tailnet） + 连接，以便它能注册为节点。 5. 在 Gateway 网关上批准该节点： ```bash @@ -1738,101 +1745,101 @@ x-i18n: 不需要单独的 TCP bridge；节点通过 Gateway WebSocket 连接。 - 安全提醒：配对 macOS 节点将允许在该机器上运行 `system.run`。只 - 配对你信任的设备，并查阅 [Security](/zh-CN/gateway/security)。 + 安全提醒：配对一个 macOS 节点意味着允许在那台机器上执行 `system.run`。只 + 配对你信任的设备，并查看 [Security](/zh-CN/gateway/security)。 - 文档：[Nodes](/zh-CN/nodes)、[Gateway protocol](/zh-CN/gateway/protocol)、[macOS 远程模式](/zh-CN/platforms/mac/remote)、[Security](/zh-CN/gateway/security)。 + 文档：[Nodes](/zh-CN/nodes)、[Gateway 协议](/zh-CN/gateway/protocol)、[macOS 远程模式](/zh-CN/platforms/mac/remote)、[Security](/zh-CN/gateway/security)。 - + 先检查基础项： - Gateway 网关正在运行：`openclaw gateway status` - Gateway 网关健康状态：`openclaw status` - 渠道健康状态：`openclaw channels status` - 然后验证认证和路由： + 然后验证身份验证和路由： - - 如果你使用 Tailscale Serve，请确认 `gateway.auth.allowTailscale` 设置正确。 - - 如果你通过 SSH 隧道连接，请确认本地隧道已建立，并且指向正确端口。 - - 确认你的 allowlist（私信或群组）包含你的账户。 + - 如果你使用 Tailscale Serve，请确保 `gateway.auth.allowTailscale` 设置正确。 + - 如果你通过 SSH 隧道连接，请确认本地隧道已启动并指向正确端口。 + - 确认你的 allowlists（私信或群组）包含你的账户。 文档：[Tailscale](/zh-CN/gateway/tailscale)、[远程访问](/zh-CN/gateway/remote)、[Channels](/zh-CN/channels)。 - - 可以。虽然没有内置的“bot-to-bot”桥接，但你可以通过几种 - 可靠方式将其连接起来： + + 可以。虽然没有内置的“bot 对 bot”桥接，但你可以通过几种 + 可靠方式实现： - **最简单：**使用两个机器人都能访问的普通聊天渠道（Telegram/Slack/WhatsApp）。 - 让 Bot A 向 Bot B 发送一条消息，然后让 Bot B 像平常一样回复。 + **最简单：**使用两个 bot 都能访问的普通聊天渠道（Telegram/Slack/WhatsApp）。 + 让 Bot A 给 Bot B 发送消息，然后让 Bot B 正常回复。 - **CLI bridge（通用）：**运行一个脚本，使用 - `openclaw agent --message ... --deliver` 调用另一个 Gateway 网关，目标指向另一个机器人 - 正在监听的聊天。如果其中一个机器人位于远程 VPS 上，请通过 SSH/Tailscale - 将你的 CLI 指向那个远程 Gateway 网关（参见 [远程访问](/zh-CN/gateway/remote)）。 + **CLI bridge（通用）：**运行一个脚本，通过 + `openclaw agent --message ... --deliver` 调用另一个 Gateway 网关，并将目标设为另一个 bot + 正在监听的聊天。如果其中一个 bot 位于远程 VPS 上，请让你的 CLI + 通过 SSH/Tailscale 指向那个远程 Gateway 网关（参见 [远程访问](/zh-CN/gateway/remote)）。 - 示例模式（在能访问目标 Gateway 网关的机器上运行）： + 示例模式（在能够访问目标 Gateway 网关的机器上运行）： ```bash openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to ``` - 提示：请添加一道防护，避免两个机器人无休止地相互循环（仅在被提及时回复、渠道 - allowlist，或“不要回复机器人消息”的规则）。 + 提示：添加一个保护措施，避免两个 bot 无限循环（仅在被提及时响应、渠道 + allowlists，或者“不要回复 bot 消息”的规则）。 文档：[远程访问](/zh-CN/gateway/remote)、[Agent CLI](/zh-CN/cli/agent)、[Agent send](/zh-CN/tools/agent-send)。 - - 不需要。一个 Gateway 网关可以托管多个智能体，每个都有自己的工作区、模型默认值 - 和路由。这是正常的部署方式，而且比为每个智能体各跑一个 VPS - 更便宜也更简单。 + + 不需要。一个 Gateway 网关可以托管多个智能体，每个智能体都有自己的工作区、默认模型 + 和路由。这是正常设置，也比为每个智能体单独运行 + 一个 VPS 更便宜、更简单。 - 只有在你需要强隔离（安全边界）或需要彼此完全不同、又不想共享的 - 配置时，才使用多个 VPS。否则，保持一个 Gateway 网关，并 + 只有在你需要硬隔离（安全边界）或需要完全不同且不想共享的 + 配置时，才需要使用独立 VPS。否则，请保留一个 Gateway 网关，并 使用多个智能体或子智能体。 - - 有——节点是从远程 Gateway 网关访问你笔记本的一级方式，而且它们 + + 有——节点是从远程 Gateway 网关访问你笔记本电脑的一等方式，而且它们 解锁的不只是 shell 访问。Gateway 网关运行在 macOS/Linux 上（Windows 通过 WSL2），并且 - 很轻量（小型 VPS 或 Raspberry Pi 级别的设备就够用；4 GB RAM 已经很充足），因此一种常见 - 部署方式是使用一台始终在线的主机，再把你的笔记本作为一个节点。 + 很轻量（小型 VPS 或 Raspberry Pi 级别的机器就足够；4 GB RAM 已经很充裕），所以一种常见 + 设置是始终在线的主机加上你的笔记本电脑作为节点。 - - **无需入站 SSH。**节点会主动连接到 Gateway WebSocket，并使用设备配对。 - - **更安全的执行控制。**`system.run` 受该笔记本上的节点 allowlist/审批机制保护。 - - **更多设备工具。**节点除了 `system.run` 之外，还会暴露 `canvas`、`camera` 和 `screen`。 - - **本地浏览器自动化。**可将 Gateway 网关保留在 VPS 上，但通过笔记本上的节点主机在本地运行 Chrome，或通过 Chrome MCP 连接到主机上的本地 Chrome。 + - **不需要入站 SSH。**节点会主动连接到 Gateway WebSocket，并使用设备配对。 + - **更安全的执行控制。**`system.run` 受那台笔记本电脑上的节点 allowlists/审批控制。 + - **更多设备工具。**除了 `system.run` 之外，节点还暴露 `canvas`、`camera` 和 `screen`。 + - **本地浏览器自动化。**让 Gateway 网关运行在 VPS 上，但通过笔记本电脑上的节点主机在本地运行 Chrome，或通过 Chrome MCP 连接到主机上的本地 Chrome。 - SSH 适合临时性的 shell 访问，但对于持续运行的智能体工作流和 - 设备自动化来说，节点更简单。 + 对于临时 shell 访问，SSH 没问题；但对于持续的智能体工作流和 + 设备自动化，节点更简单。 文档：[Nodes](/zh-CN/nodes)、[Nodes CLI](/zh-CN/cli/nodes)、[Browser](/zh-CN/tools/browser)。 - - 不会。除非你有意运行隔离的配置文件，否则每台主机上应该只运行**一个 Gateway 网关**（参见 [Multiple gateways](/zh-CN/gateway/multiple-gateways)）。节点是连接到 - Gateway 网关的外围设备（iOS/Android 节点，或菜单栏应用中的 macOS “node mode”）。关于无头节点 - 主机和 CLI 控制，请参阅 [Node host CLI](/zh-CN/cli/node)。 + + 不会。除非你有意运行隔离配置文件（参见 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)），否则每台主机上应该只运行**一个 gateway**。节点是连接到 + gateway 的外围设备（iOS/Android 节点，或菜单栏 app 中的 macOS “node mode”）。有关 headless 节点 + 主机和 CLI 控制，请参见 [Node host CLI](/zh-CN/cli/node)。 - 对 `gateway`、`discovery` 和 `canvasHost` 的更改需要完整重启。 + 对 `gateway`、`discovery` 和 `canvasHost` 的更改需要完全重启。 - + 有。 - - `config.schema.lookup`：在写入之前检查某个配置子树，包括其浅层 schema 节点、匹配的 UI 提示和直接子节点摘要 + - `config.schema.lookup`：在写入前检查某个配置子树，包括其浅层 schema 节点、匹配的 UI 提示，以及直接子项摘要 - `config.get`：获取当前快照 + hash - `config.patch`：安全的部分更新（大多数 RPC 编辑的首选）；可热重载时热重载，必要时重启 - `config.apply`：验证 + 替换完整配置；可热重载时热重载，必要时重启 - - 仅限 owner 的 `gateway` 运行时工具仍然拒绝重写 `tools.exec.ask` / `tools.exec.security`；旧版 `tools.bash.*` 别名会规范化到同样受保护的 exec 路径 + - 仅限所有者的 `gateway` 运行时工具仍然拒绝重写 `tools.exec.ask` / `tools.exec.security`；旧版 `tools.bash.*` 别名会规范化到相同的受保护 exec 路径 @@ -1844,27 +1851,27 @@ 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 app，并登录到同一个 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： @@ -1872,37 +1879,37 @@ x-i18n: openclaw gateway --tailscale serve ``` - 这样会让 Gateway 网关继续绑定到 loopback，并通过 Tailscale 暴露 HTTPS。请参阅 [Tailscale](/zh-CN/gateway/tailscale)。 + 这样会让 gateway 保持绑定在 loopback 上，并通过 Tailscale 暴露 HTTPS。参见 [Tailscale](/zh-CN/gateway/tailscale)。 - Serve 会暴露 **Gateway Control UI + WS**。节点通过同一个 Gateway WS 端点连接。 + Serve 会暴露**Gateway Control UI + WS**。节点会通过同一个 Gateway WS 端点连接。 推荐设置： - 1. **确保 VPS 和 Mac 在同一个 tailnet 中**。 - 2. **在远程模式下使用 macOS 应用**（SSH 目标可以是 tailnet 主机名）。 - 该应用会为 Gateway 网关端口建立隧道，并以节点身份连接。 - 3. **在 Gateway 网关上批准该节点：** + 1. **确保 VPS 和 Mac 位于同一个 tailnet 中**。 + 2. **使用 macOS app 的 Remote 模式**（SSH 目标可以是 tailnet 主机名）。 + 该 app 会为 Gateway 端口建立隧道，并作为节点连接。 + 3. **在 gateway 上批准节点：** ```bash openclaw devices list openclaw devices approve ``` - 文档：[Gateway protocol](/zh-CN/gateway/protocol)、[Discovery](/zh-CN/gateway/discovery)、[macOS 远程模式](/zh-CN/platforms/mac/remote)。 + 文档：[Gateway 协议](/zh-CN/gateway/protocol)、[设备发现](/zh-CN/gateway/discovery)、[macOS 远程模式](/zh-CN/platforms/mac/remote)。 - - 如果你只需要在第二台笔记本上使用**本地工具**（screen/camera/exec），那就把它添加为一个 - **节点**。这样可以保持单个 Gateway 网关，并避免重复配置。当前本地节点工具 + + 如果你只需要第二台笔记本电脑上的**本地工具**（屏幕/摄像头/exec），就把它添加为 + **节点**。这样可以保留单一 Gateway 网关，并避免重复配置。当前本地节点工具 仅支持 macOS，但我们计划扩展到其他操作系统。 - 只有当你需要**强隔离**或两个完全独立的机器人时，才安装第二个 Gateway 网关。 + 只有在你需要**硬隔离**或两个完全独立的机器人时，才安装第二个 Gateway 网关。 - 文档：[Nodes](/zh-CN/nodes)、[Nodes CLI](/zh-CN/cli/nodes)、[Multiple gateways](/zh-CN/gateway/multiple-gateways)。 + 文档：[Nodes](/zh-CN/nodes)、[Nodes CLI](/zh-CN/cli/nodes)、[多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。 @@ -1910,15 +1917,15 @@ x-i18n: ## 环境变量和 .env 加载 - + OpenClaw 会从父进程（shell、launchd/systemd、CI 等）读取环境变量，并额外加载： - 当前工作目录中的 `.env` - - 来自 `~/.openclaw/.env`（即 `$OPENCLAW_STATE_DIR/.env`）的全局回退 `.env` + - 来自 `~/.openclaw/.env`（也就是 `$OPENCLAW_STATE_DIR/.env`）的全局后备 `.env` - 两个 `.env` 文件都不会覆盖现有环境变量。 + 这两个 `.env` 文件都不会覆盖现有环境变量。 - 你也可以在配置中定义内联环境变量（仅当进程环境中缺失时才应用）： + 你也可以在配置中定义内联环境变量（仅在进程环境中缺失时才应用）： ```json5 { @@ -1929,15 +1936,15 @@ x-i18n: } ``` - 完整的优先级和来源请参阅 [/environment](/zh-CN/help/environment)。 + 完整优先级和来源参见 [/environment](/zh-CN/help/environment)。 - - 两种常见修复方法： + + 有两个常见修复方式： - 1. 把缺失的键放到 `~/.openclaw/.env` 中，这样即使服务没有继承你的 shell 环境，也能读取到。 - 2. 启用 shell 导入（选择加入的便捷功能）： + 1. 将缺失的键放到 `~/.openclaw/.env` 中，这样即使服务没有继承你的 shell 环境，它们也会被读取。 + 2. 启用 shell 导入（可选的便捷功能）： ```json5 { @@ -1950,36 +1957,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 - 环境。可通过以下方式之一修复： + 环境。可通过以下方式修复： - 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)。 @@ -1987,15 +1994,15 @@ x-i18n: ## 会话和多个聊天 - - 发送 `/new` 或 `/reset` 作为一条独立消息。请参阅 [会话管理](/zh-CN/concepts/session)。 + + 发送单独一条 `/new` 或 `/reset` 消息。参见 [会话管理](/zh-CN/concepts/session)。 - 会话可以在 `session.idleMinutes` 之后过期，但这项功能**默认禁用**（默认值为 **0**）。 - 将其设置为正值即可启用空闲过期。启用后，在空闲期之后收到的**下一条** + 会话可以在 `session.idleMinutes` 之后过期，但这项功能**默认关闭**（默认值为 **0**）。 + 将其设置为正值即可启用空闲过期。启用后，在空闲期结束后的**下一条** 消息会为该聊天键启动一个新的会话 ID。 - 这不会删除转录内容——它只是开始一个新会话。 + 这不会删除记录——只是开始一个新会话。 ```json5 { @@ -2007,35 +2014,35 @@ x-i18n: - - 可以，通过**多智能体路由**和**子智能体**实现。你可以创建一个协调型 - 智能体，以及多个拥有各自工作区和模型的工作智能体。 + + 有，可以通过**多智能体路由**和**子智能体**实现。你可以创建一个协调者 + 智能体，以及多个具有各自工作区和模型的工作智能体。 - 不过，这更适合作为一个**有趣的实验**。它会消耗大量令牌，而且通常 - 不如使用一个机器人配合不同会话来得高效。我们所设想的典型模型是： - 你与一个机器人对话，同时为并行工作使用不同会话。必要时，该 - 机器人也可以生成子智能体。 + 不过，这更适合作为一种**有趣的实验**。它会消耗大量 token，而且 + 通常没有一个机器人配合多个独立会话高效。我们设想的典型模型是 + 一个你与之交流的机器人，通过不同会话处理并行工作。必要时，这个 + 机器人也可以启动子智能体。 - 文档：[多智能体路由](/zh-CN/concepts/multi-agent)、[Sub-agents](/zh-CN/tools/subagents)、[Agents CLI](/zh-CN/cli/agents)。 + 文档：[多智能体路由](/zh-CN/concepts/multi-agent)、[子智能体](/zh-CN/tools/subagents)、[Agents CLI](/zh-CN/cli/agents)。 - - 会话上下文受模型窗口限制。长聊天、大量工具输出或许多 + + 会话上下文受模型窗口限制。长聊天、大量工具输出，或过多 文件都可能触发压缩或截断。 有帮助的做法： - 让机器人总结当前状态并写入文件。 - - 在长任务前使用 `/compact`，切换话题时使用 `/new`。 + - 在长任务前使用 `/compact`，切换主题时使用 `/new`。 - 将重要上下文保存在工作区中，并让机器人重新读取它。 - - 对长时间或并行工作使用子智能体，这样主聊天可以保持更小。 - - 如果这种情况经常发生，选择一个上下文窗口更大的模型。 + - 对于长时间或并行工作，使用子智能体，这样主聊天会保持较小。 + - 如果这种情况经常发生，请选择具有更大上下文窗口的模型。 - - 使用重置命令： + + 使用 reset 命令： ```bash openclaw reset @@ -2055,16 +2062,16 @@ x-i18n: 说明： - - 如果新手引导检测到现有配置，也会提供**重置**选项。请参阅 [新手引导（CLI）](/zh-CN/start/wizard)。 - - 如果你使用了配置文件（`--profile` / `OPENCLAW_PROFILE`），请分别重置每个状态目录（默认是 `~/.openclaw-`）。 - - 开发重置：`openclaw gateway --dev --reset`（仅限开发环境；会清除开发配置 + 凭据 + 会话 + 工作区）。 + - 如果新手引导检测到现有配置，也会提供**重置**选项。参见 [新手引导（CLI）](/zh-CN/start/wizard)。 + - 如果你使用了 profiles（`--profile` / `OPENCLAW_PROFILE`），请分别重置每个状态目录（默认是 `~/.openclaw-`）。 + - 开发重置：`openclaw gateway --dev --reset`（仅限开发；会清除开发配置 + 凭证 + 会话 + 工作区）。 - - 使用以下方法之一： + + 使用以下方式之一： - - **压缩**（保留对话，但总结较早的轮次）： + - **压缩**（保留对话，但总结较早轮次）： ``` /compact @@ -2072,7 +2079,7 @@ x-i18n: 或使用 `/compact ` 来指导摘要内容。 - - **重置**（为同一聊天键创建新的会话 ID）： + - **重置**（为同一聊天键创建一个全新的会话 ID）： ``` /new @@ -2081,50 +2088,50 @@ x-i18n: 如果这种情况持续发生： - - 启用或调整**会话修剪**（`agents.defaults.contextPruning`），以裁剪旧的工具输出。 - - 使用上下文窗口更大的模型。 + - 启用或调整**会话裁剪**（`agents.defaults.contextPruning`）以裁掉旧的工具输出。 + - 使用具有更大上下文窗口的模型。 - 文档：[Compaction](/zh-CN/concepts/compaction)、[Session pruning](/zh-CN/concepts/session-pruning)、[会话管理](/zh-CN/concepts/session)。 + 文档：[压缩](/zh-CN/concepts/compaction)、[会话裁剪](/zh-CN/concepts/session-pruning)、[会话管理](/zh-CN/concepts/session)。 - 这是提供商验证错误：模型发出了一个 `tool_use` 块，但缺少必需的 - `input`。这通常意味着会话历史已经过时或损坏（常见于长线程 + 这是 provider 验证错误：模型发出了一个缺少必需 + `input` 的 `tool_use` 块。通常说明会话历史已过时或损坏（经常出现在长 thread 或工具/schema 变更之后）。 - 修复方法：使用 `/new`（作为独立消息）开始一个新会话。 + 修复方法：发送单独的 `/new` 消息，开始一个新会话。 - - Heartbeat 默认每 **30m** 运行一次（使用 OAuth 认证时为 **1h**）。可进行调优或禁用： + + Heartbeat 默认每 **30m** 运行一次（使用 OAuth 身份验证时为 **1h**）。你可以调整或禁用它们： ```json5 { agents: { defaults: { heartbeat: { - every: "2h", // 或设为 "0m" 以禁用 + every: "2h", // 或 "0m" 以禁用 }, }, }, } ``` - 如果 `HEARTBEAT.md` 存在，但实际上是空的（只有空行和 Markdown - 标题，如 `# Heading`），OpenClaw 会跳过该次 Heartbeat 运行，以节省 API 调用。 - 如果该文件不存在，Heartbeat 仍会运行，并由模型决定要做什么。 + 如果 `HEARTBEAT.md` 存在但实际上是空的（只有空行和 Markdown + 标题如 `# Heading`），OpenClaw 会跳过 heartbeat 运行以节省 API 调用。 + 如果文件缺失，heartbeat 仍会运行，并由模型决定要做什么。 - 按智能体的覆盖项使用 `agents.list[].heartbeat`。文档：[Heartbeat](/zh-CN/gateway/heartbeat)。 + 按智能体覆盖使用 `agents.list[].heartbeat`。文档：[Heartbeat](/zh-CN/gateway/heartbeat)。 - - 不需要。OpenClaw 运行在**你自己的账号**上，所以只要你在群里，OpenClaw 就能看到它。 + + 不需要。OpenClaw 运行在**你自己的账号**上，所以只要你在群组里，OpenClaw 就能看到它。 默认情况下，在你允许发送者之前，群组回复会被阻止（`groupPolicy: "allowlist"`）。 - 如果你希望只有**你自己**可以触发群组回复： + 如果你希望只有**你自己**能够触发群组回复： ```json5 { @@ -2140,7 +2147,7 @@ x-i18n: - 选项 1（最快）：查看日志，并在群里发送一条测试消息： + 选项 1（最快）：跟踪日志，然后在群里发送一条测试消息： ```bash openclaw logs --follow --json @@ -2149,7 +2156,7 @@ x-i18n: 查找以 `@g.us` 结尾的 `chatId`（或 `from`），例如： `1234567890-1234567890@g.us`。 - 选项 2（如果已配置/已加入 allowlist）：从配置中列出群组： + 选项 2（如果已经配置/加入允许列表）：从配置中列出群组： ```bash openclaw directory groups list --channel whatsapp @@ -2163,44 +2170,44 @@ x-i18n: 两个常见原因： - 提及门控已开启（默认）。你必须 @ 提及机器人（或匹配 `mentionPatterns`）。 - - 你配置了 `channels.whatsapp.groups`，但没有包含 `"*"`，并且该群组不在 allowlist 中。 + - 你配置了 `channels.whatsapp.groups` 但没有包含 `"*"`，而该群组不在允许列表中。 - 请参阅 [Groups](/zh-CN/channels/groups) 和 [Group messages](/zh-CN/channels/group-messages)。 + 参见 [Groups](/zh-CN/channels/groups) 和 [Group messages](/zh-CN/channels/group-messages)。 - - 直接聊天默认会折叠到主会话。群组/渠道拥有各自的会话键，而 Telegram 话题 / Discord 线程则是独立会话。请参阅 [Groups](/zh-CN/channels/groups) 和 [Group messages](/zh-CN/channels/group-messages)。 + + 直接聊天默认会折叠到主会话。群组/渠道拥有各自独立的会话键，而 Telegram topics / Discord threads 也是独立会话。参见 [Groups](/zh-CN/channels/groups) 和 [Group messages](/zh-CN/channels/group-messages)。 - 没有硬性限制。几十个（甚至几百个）都没问题，但要注意： + 没有硬性限制。几十个（甚至上百个）都没问题，但请注意： - - **磁盘增长：**会话 + 转录内容位于 `~/.openclaw/agents//sessions/` 下。 - - **令牌成本：**更多智能体意味着更多并发模型使用。 - - **运维开销：**按智能体划分的认证配置文件、工作区和渠道路由。 + - **磁盘增长：**会话 + 记录存储在 `~/.openclaw/agents//sessions/` 下。 + - **Token 成本：**更多智能体意味着更多并发模型使用。 + - **运维开销：**按智能体划分的 auth profiles、工作区和渠道路由。 提示： - - 为每个智能体保留一个**活动**工作区（`agents.defaults.workspace`）。 - - 如果磁盘增长明显，请清理旧会话（删除 JSONL 或 store 条目）。 - - 使用 `openclaw doctor` 检查散落的工作区和配置文件不匹配问题。 + - 为每个智能体保留一个**活动中的**工作区（`agents.defaults.workspace`）。 + - 如果磁盘变大，请清理旧会话（删除 JSONL 或存储条目）。 + - 使用 `openclaw doctor` 发现零散工作区和 profile 不匹配问题。 - - 可以。使用**多智能体路由**运行多个隔离智能体，并按 - 渠道/账户/peer 路由入站消息。Slack 作为一个渠道受支持，并且可以绑定到特定智能体。 + + 可以。使用**多智能体路由**来运行多个相互隔离的智能体，并按 + 渠道/账户/peer 路由入站消息。Slack 作为渠道受支持，也可以绑定到特定智能体。 - 浏览器访问能力很强，但并不等于“能做人类能做的一切”——反机器人机制、CAPTCHA 和 MFA 仍然可能 - 阻止自动化。若要获得最可靠的浏览器控制，请在主机上使用本地 Chrome MCP， + 浏览器访问能力很强，但并不意味着“能做任何人类能做的事”——反机器人机制、CAPTCHA 和 MFA + 仍然可能阻止自动化。若要获得最可靠的浏览器控制，请在主机上使用本地 Chrome MCP， 或在实际运行浏览器的机器上使用 CDP。 - 最佳实践部署： + 最佳实践设置： - 始终在线的 Gateway 网关主机（VPS/Mac mini）。 - 每个角色一个智能体（bindings）。 - - 将 Slack 渠道绑定到这些智能体。 + - 绑定到这些智能体的 Slack 渠道。 - 需要时通过 Chrome MCP 或节点访问本地浏览器。 文档：[多智能体路由](/zh-CN/concepts/multi-agent)、[Slack](/zh-CN/channels/slack)、 @@ -2213,38 +2220,38 @@ x-i18n: - OpenClaw 的默认模型就是你设置在以下位置的模型： + OpenClaw 的默认模型就是你设置在这里的内容： ``` agents.defaults.model.primary ``` - 模型以 `provider/model` 的形式引用（例如：`openai/gpt-5.4`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该确切模型 id 唯一匹配的已配置提供商，最后才会回退到已配置的默认提供商这一已弃用的兼容路径。如果该提供商已不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是继续暴露一个已移除提供商的过时默认值。你仍然应该**显式**设置 `provider/model`。 + 模型以 `provider/model` 形式引用（例如：`openai/gpt-5.5`）。如果你省略 provider，OpenClaw 会先尝试别名，然后尝试已配置 provider 中该确切模型 id 的唯一匹配，最后才会回退到已配置的默认 provider，这是一条已弃用的兼容路径。如果该 provider 不再提供已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider/model，而不是继续暴露一个过期、已移除 provider 的默认值。你仍然应该**显式**设置 `provider/model`。 - - **推荐默认值：**使用你当前提供商栈中可用的最强新一代模型。 - **对于启用了工具或会接收不受信任输入的智能体：**优先考虑模型能力，而不是成本。 - **对于常规/低风险聊天：**使用更便宜的回退模型，并按智能体角色进行路由。 + + **推荐默认值：**使用你 provider 栈中可用的最强、最新一代模型。 + **对于启用了工具或会处理不可信输入的智能体：**优先考虑模型能力，而不是成本。 + **对于日常/低风险聊天：**使用更便宜的回退模型，并按智能体角色进行路由。 - MiniMax 有其专门文档：[MiniMax](/zh-CN/providers/minimax) 和 + MiniMax 有单独文档：[MiniMax](/zh-CN/providers/minimax) 和 [Local models](/zh-CN/gateway/local-models)。 - 经验法则是：对于高风险工作，使用你**负担得起的最佳模型**；对于常规 - 聊天或摘要，则使用更便宜的模型。你可以按智能体路由模型，也可以使用子智能体来 - 并行处理长任务（每个子智能体都会消耗令牌）。请参阅 [Models](/zh-CN/concepts/models) 和 - [Sub-agents](/zh-CN/tools/subagents)。 + 经验法则：对于高风险工作，使用你**负担得起的最佳模型**；对于日常聊天或摘要， + 使用更便宜的模型。你可以按智能体路由模型，并使用子智能体来 + 并行化长任务（每个子智能体都会消耗 token）。参见 [Models](/zh-CN/concepts/models) 和 + [子智能体](/zh-CN/tools/subagents)。 - 强烈警告：较弱或过度量化的模型更容易受到提示 - 注入和不安全行为的影响。请参阅 [Security](/zh-CN/gateway/security)。 + 强烈警告：较弱或量化过度的模型更容易受到提示注入 + 和不安全行为影响。参见 [Security](/zh-CN/gateway/security)。 - 更多背景信息：[Models](/zh-CN/concepts/models)。 + 更多背景：[Models](/zh-CN/concepts/models)。 - 使用**模型命令**，或仅编辑**模型**字段。避免整份配置替换。 + 使用**模型命令**，或只编辑**模型**字段。避免完整替换配置。 安全选项： @@ -2253,10 +2260,10 @@ x-i18n: - `openclaw configure --section model`（交互式） - 编辑 `~/.openclaw/openclaw.json` 中的 `agents.defaults.model` - 除非你确实打算替换整个配置，否则不要用部分对象调用 `config.apply`。 - 对于 RPC 编辑，请先用 `config.schema.lookup` 检查，并优先使用 `config.patch`。lookup 负载会提供规范化路径、浅层 schema 文档/约束以及直接子节点摘要， - 用于进行部分更新。 - 如果你已经覆盖了配置，请从备份恢复，或重新运行 `openclaw doctor` 进行修复。 + 除非你打算替换整个配置，否则请避免对部分对象使用 `config.apply`。 + 对于 RPC 编辑，请先用 `config.schema.lookup` 检查，并优先使用 `config.patch`。lookup 负载会给你规范化路径、浅层 schema 文档/约束，以及直接子项摘要， + 以便进行部分更新。 + 如果你确实覆盖了配置，请从备份恢复，或重新运行 `openclaw doctor` 进行修复。 文档：[Models](/zh-CN/concepts/models)、[Configure](/zh-CN/cli/configure)、[配置](/zh-CN/cli/config)、[Doctor](/zh-CN/gateway/doctor)。 @@ -2265,11 +2272,11 @@ x-i18n: 可以。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` @@ -2279,24 +2286,24 @@ x-i18n: - 像 `kimi-k2.5:cloud` 这样的云模型不需要本地拉取 - 若要手动切换，请使用 `openclaw models list` 和 `openclaw models set ollama/` - 安全说明：更小或高度量化的模型更容易受到提示 - 注入攻击。对于任何可以使用工具的机器人，我们都强烈推荐**大模型**。 - 如果你仍然想使用小模型，请启用沙箱隔离和严格的工具 allowlist。 + 安全说明：较小或重度量化的模型更容易受到提示注入影响。 + 对于任何可以使用工具的机器人，我们强烈建议使用**大模型**。 + 如果你仍想使用小模型，请启用沙箱隔离和严格的工具 allowlists。 文档：[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/concepts/model-providers)、[Security](/zh-CN/gateway/security)、 [沙箱隔离](/zh-CN/gateway/sandboxing)。 - - - 这些部署可能各不相同，并且会随着时间变化；没有固定的提供商推荐。 - - 请在每个 Gateway 网关上使用 `openclaw models status` 检查当前运行时设置。 - - 对于安全敏感/启用工具的智能体，请使用当前可用的最强新一代模型。 + + - 这些部署可能不同，并且会随时间变化；没有固定的 provider 推荐。 + - 请在各自 gateway 上通过 `openclaw models status` 检查当前运行时设置。 + - 对于安全敏感/启用工具的智能体，请使用可用的最强最新一代模型。 - 将 `/model` 命令作为独立消息发送： + 将 `/model` 命令作为单独消息发送： ``` /model sonnet @@ -2308,56 +2315,56 @@ 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`）会显示一个紧凑的编号选择器。通过数字选择： + `/model`（以及 `/model list`）会显示一个紧凑的编号选择器。可按编号选择： ``` /model 3 ``` - 你还可以为提供商强制指定某个认证配置文件（按会话）： + 你还可以为该 provider 强制指定某个 auth profile（按会话）： ``` /model opus@anthropic:default /model opus@anthropic:work ``` - 提示：`/model status` 会显示当前活动的是哪个智能体、正在使用哪个 `auth-profiles.json` 文件，以及下一个将尝试哪个认证配置文件。 - 如果可用，它还会显示已配置的提供商端点（`baseUrl`）和 API 模式（`api`）。 + 提示：`/model status` 会显示当前激活的是哪个智能体、正在使用哪个 `auth-profiles.json` 文件，以及接下来会尝试哪个 auth profile。 + 在可用时，它还会显示已配置的 provider 端点（`baseUrl`）和 API 模式（`api`）。 - **如何取消我用 @profile 设置的 profile 固定？** + **如何取消固定用 `@profile` 设置的 profile？** - 重新运行 `/model`，**不要**带 `@profile` 后缀： + 重新运行 `/model`，但**不要**带 `@profile` 后缀： ``` /model anthropic/claude-opus-4-6 ``` - 如果你想返回默认值，请从 `/model` 中重新选择它（或发送 `/model `）。 - 使用 `/model status` 确认当前活动的认证配置文件。 + 如果你想回到默认值，请在 `/model` 中选择默认项（或发送 `/model `）。 + 使用 `/model status` 确认当前激活的是哪个 auth profile。 - - 可以。将一个设为默认值，需要时再切换： + + 可以。将其中一个设为默认值，并按需切换： - - **快速切换（按会话）：**日常任务用 `/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.5`，使用 Codex OAuth 编码时使用 `/model openai-codex/gpt-5.5`。 + - **默认值 + 切换：**将 `agents.defaults.model.primary` 设为 `openai/gpt-5.5`，然后在编码时切换到 `openai-codex/gpt-5.5`（或者反过来）。 + - **子智能体：**将编码任务路由到使用不同默认模型的子智能体。 - 请参阅 [Models](/zh-CN/concepts/models) 和 [Slash commands](/zh-CN/tools/slash-commands)。 + 参见 [Models](/zh-CN/concepts/models) 和 [Slash commands](/zh-CN/tools/slash-commands)。 - - 你可以使用会话开关或配置默认值： + + 你可以使用按会话切换或配置默认值： - - **按会话：**当会话使用 `openai/gpt-5.4` 或 `openai-codex/gpt-5.4` 时，发送 `/fast on`。 - - **按模型默认值：**将 `agents.defaults.models["openai/gpt-5.4"].params.fastMode` 设为 `true`。 - - **Codex OAuth 也一样：**如果你也使用 `openai-codex/gpt-5.4`，请在那边设置同样的标志。 + - **按会话：**当会话使用 `openai/gpt-5.5` 或 `openai-codex/gpt-5.5` 时，发送 `/fast on`。 + - **按模型默认值：**将 `agents.defaults.models["openai/gpt-5.5"].params.fastMode` 设置为 `true`。 + - **Codex OAuth 同样适用：**如果你也使用 `openai-codex/gpt-5.5`，请在那一项上设置相同标志。 示例： @@ -2366,12 +2373,12 @@ x-i18n: agents: { defaults: { models: { - "openai/gpt-5.4": { + "openai/gpt-5.5": { params: { fastMode: true, }, }, - "openai-codex/gpt-5.4": { + "openai-codex/gpt-5.5": { params: { fastMode: true, }, @@ -2382,39 +2389,40 @@ x-i18n: } ``` - 对于 OpenAI，快速模式会映射为受支持原生 Responses 请求中的 `service_tier = "priority"`。会话级 `/fast` 覆盖项优先于配置默认值。 + 对于 OpenAI，快速模式会在受支持的原生 Responses 请求上映射为 `service_tier = "priority"`。会话级 `/fast` 覆盖优先于配置默认值。 - 请参阅 [Thinking and fast mode](/zh-CN/tools/thinking) 和 [OpenAI fast mode](/zh-CN/providers/openai#openai-fast-mode)。 + 参见 [Thinking and fast mode](/zh-CN/tools/thinking) 和 [OpenAI fast mode](/zh-CN/providers/openai#openai-fast-mode)。 - - 如果设置了 `agents.defaults.models`，它就会成为 `/model` 和任何 - 会话覆盖项的**allowlist**。选择一个不在该列表中的模型会返回： + + 如果设置了 `agents.defaults.models`，它就会成为 `/model` 以及任何 + 会话覆盖的**允许列表**。选择一个不在该列表中的模型会返回： ``` Model "provider/model" is not allowed. Use /model to list available models. ``` - 该错误会**代替**正常回复返回。修复方法：将该模型加入 - `agents.defaults.models`，移除 allowlist，或从 `/model list` 中选择一个模型。 + 这个错误会**替代**正常回复返回。修复方法：将该模型加入 + `agents.defaults.models`，移除允许列表，或从 `/model list` 中选择一个模型。 - 这意味着**提供商未配置**（未找到 MiniMax 提供商配置或认证 - 配置文件），因此无法解析该模型。 + 这意味着**provider 未配置**（找不到 MiniMax provider 配置或 auth + profile），因此无法解析该模型。 修复检查清单： - 1. 升级到当前的 OpenClaw 发布版本（或直接从源码 `main` 运行），然后重启 Gateway 网关。 - 2. 确保已配置 MiniMax（通过向导或 JSON），或者环境变量/认证配置文件中存在 MiniMax 认证， - 这样才能注入匹配的提供商 + 1. 升级到当前的 OpenClaw 版本（或直接从源码 `main` 运行），然后重启 gateway。 + 2. 确保 MiniMax 已配置（通过向导或 JSON），或者在环境变量/auth profiles 中存在 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 key + 配置使用 `minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed`， + OAuth 配置则使用 `minimax-portal/MiniMax-M2.7` / `minimax-portal/MiniMax-M2.7-highspeed`。 4. 运行： @@ -2424,13 +2432,13 @@ x-i18n: 然后从列表中选择（或在聊天中使用 `/model list`）。 - 请参阅 [MiniMax](/zh-CN/providers/minimax) 和 [Models](/zh-CN/concepts/models)。 + 参见 [MiniMax](/zh-CN/providers/minimax) 和 [Models](/zh-CN/concepts/models)。 - + 可以。将 **MiniMax 设为默认值**，并在需要时**按会话**切换模型。 - 回退用于处理**错误**，而不是“高难度任务”，所以请使用 `/model` 或单独的智能体。 + 回退是为**错误**而设计的，不是为“高难任务”而设计，所以请使用 `/model` 或单独的智能体。 **选项 A：按会话切换** @@ -2442,7 +2450,7 @@ x-i18n: model: { primary: "minimax/MiniMax-M2.7" }, models: { "minimax/MiniMax-M2.7": { alias: "minimax" }, - "openai/gpt-5.4": { alias: "gpt" }, + "openai/gpt-5.5": { alias: "gpt" }, }, }, }, @@ -2455,34 +2463,34 @@ x-i18n: /model gpt ``` - **选项 B：使用单独的智能体** + **选项 B：使用独立智能体** - 智能体 A 默认：MiniMax - 智能体 B 默认：OpenAI - - 按智能体路由，或使用 `/agent` 切换 + - 通过智能体路由，或使用 `/agent` 切换 - 文档：[Models](/zh-CN/concepts/models)、[Multi-Agent Routing](/zh-CN/concepts/multi-agent)、[MiniMax](/zh-CN/providers/minimax)、[OpenAI](/zh-CN/providers/openai)。 + 文档：[Models](/zh-CN/concepts/models)、[多智能体路由](/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` - - `gpt` → `openai/gpt-5.4` + - `gpt` → `openai/gpt-5.5` - `gpt-mini` → `openai/gpt-5.4-mini` - `gpt-nano` → `openai/gpt-5.4-nano` - `gemini` → `google/gemini-3.1-pro-preview` - `gemini-flash` → `google/gemini-3-flash-preview` - `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview` - 如果你自定义了同名 alias，则以你的值为准。 + 如果你设置了同名自定义别名，将以你的值为准。 - - Alias 来自 `agents.defaults.models..alias`。例如： + + 别名来自 `agents.defaults.models..alias`。示例： ```json5 { @@ -2499,12 +2507,12 @@ x-i18n: } ``` - 然后 `/model sonnet`（或在支持时使用 `/`）就会解析到对应模型 ID。 + 然后 `/model sonnet`（或在支持时使用 `/`）就会解析为对应的模型 ID。 - - OpenRouter（按令牌付费；有很多模型）： + + OpenRouter（按 token 计费；模型很多）： ```json5 { @@ -2532,131 +2540,132 @@ 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** - 这通常意味着**新智能体**的认证存储是空的。认证是按智能体区分的，并存储在： + 这通常意味着**新智能体**的 auth 存储是空的。身份验证是按智能体隔离的，并 + 存储在： ``` ~/.openclaw/agents//agent/auth-profiles.json ``` - 修复选项： + 修复方式： - - 运行 `openclaw agents add `，并在向导中配置认证。 + - 运行 `openclaw agents add `，并在向导中配置身份验证。 - 或将主智能体 `agentDir` 中的 `auth-profiles.json` 复制到新智能体的 `agentDir` 中。 - **不要**在多个智能体之间复用 `agentDir`；这会导致认证/会话冲突。 + **不要**在多个智能体之间复用 `agentDir`；这会导致 auth/会话冲突。 -## 模型回退和 “All models failed” +## 模型故障切换和 “All models failed” - - 回退分两个阶段发生： + + 故障切换分两个阶段： - 1. **在同一提供商内轮换认证配置文件**。 + 1. 同一 provider 内的 **auth profile 轮换**。 2. **模型回退**到 `agents.defaults.model.fallbacks` 中的下一个模型。 - 失败的配置文件会进入冷却期（指数退避），因此即使某个提供商受到速率限制或临时故障，OpenClaw 仍能继续响应。 + 对失败的 profile 会应用冷却时间（指数退避），因此即使某个 provider 遇到速率限制或暂时失败，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` + 响应也仍然会保留在该暂时性错误桶中。如果 provider 在 `401` 或 `403` 上返回 + 明确的计费文本，OpenClaw 仍然可以将其保留在 + 计费通道中，但 provider 专属文本匹配器仍然只作用于拥有它们的 + provider（例如 OpenRouter 的 `Key limit exceeded`）。如果某个 `402` 消息看起来更像可重试的用量窗口或 - 组织/工作区支出限制（`daily limit reached, resets tomorrow`、 + 组织/工作区开销限制（`daily limit reached, resets tomorrow`、 `organization spending limit exceeded`），OpenClaw 会将其视为 `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` 这类特征，会停留在压缩/重试路径上，而不是推进到模型 + `input is too long for the model`，或 `ollama error: context length + exceeded` 这样的特征会保留在压缩/重试路径上，而不会推进模型 回退。 - 通用服务器错误文本的判定范围会刻意比“任何包含 - unknown/error 的内容”更窄。OpenClaw 的确会将提供商范围内的瞬时错误形态 - 视为值得触发回退的超时/过载信号，例如 Anthropic 的裸 `An unknown error occurred`、OpenRouter 的裸 - `Provider returned error`、像 `Unhandled stop reason: - error` 这样的 stop-reason 错误、带有瞬时服务器文本的 JSON `api_error` - 负载（`internal server error`、`unknown error, 520`、`upstream error`、`backend - error`），以及像 `ModelNotReadyException` 这样的提供商繁忙错误，前提是提供商上下文 - 匹配。 - 而像 `LLM request failed with an unknown - error.` 这类通用内部回退文本则会保持保守，不会单独触发模型回退。 + 通用服务器错误文本的判断有意比“任何带有 + unknown/error 的内容”更窄。OpenClaw 会在 provider 上下文 + 匹配时，将某些 provider 范围内的暂时性模式视为值得故障切换的 + 超时/过载信号，例如 Anthropic 的裸 `An unknown error occurred`、OpenRouter 的裸 + `Provider returned error`、停止原因错误如 `Unhandled stop reason: + error`、带有暂时性服务器文本的 JSON `api_error` 负载 + （`internal server error`、`unknown error, 520`、`upstream error`、`backend + error`），以及 provider 繁忙错误如 `ModelNotReadyException`。 + 像 `LLM request failed with an unknown + error.` 这样的通用内部回退文本会保持保守，不会单独触发模型回退。 - 这表示系统尝试使用认证配置文件 ID `anthropic:default`，但在预期的认证存储中找不到它对应的凭据。 + 这表示系统尝试使用 auth profile ID `anthropic:default`，但无法在预期的 auth 存储中找到对应凭证。 **修复检查清单：** - - **确认认证配置文件存放位置**（新路径与旧路径） - - 当前路径：`~/.openclaw/agents//agent/auth-profiles.json` - - 旧路径：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移） - - **确认 Gateway 网关已加载你的环境变量** - - 如果你在 shell 中设置了 `ANTHROPIC_API_KEY`，但通过 systemd/launchd 运行 Gateway 网关，它可能不会继承。请将其放到 `~/.openclaw/.env` 中，或启用 `env.shellEnv`。 - - **确保你正在编辑正确的智能体** - - 多智能体部署意味着可能存在多个 `auth-profiles.json` 文件。 - - **做一个模型/认证状态的完整性检查** - - 使用 `openclaw models status` 查看已配置模型，以及提供商是否已认证。 + - **确认 auth profiles 的位置**（新旧路径） + - 当前：`~/.openclaw/agents//agent/auth-profiles.json` + - 旧版：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移） + - **确认环境变量已被 Gateway 网关加载** + - 如果你在 shell 中设置了 `ANTHROPIC_API_KEY`，但通过 systemd/launchd 运行 Gateway 网关，它可能不会继承该变量。请将其放入 `~/.openclaw/.env`，或启用 `env.shellEnv`。 + - **确保你编辑的是正确的智能体** + - 在多智能体设置中，可能存在多个 `auth-profiles.json` 文件。 + - **做一次模型/auth 状态的完整性检查** + - 使用 `openclaw models status` 查看已配置模型，以及各 provider 是否已完成身份验证。 **针对 “No credentials found for profile anthropic” 的修复检查清单** - 这表示当前运行被固定到了某个 Anthropic 认证配置文件，但 Gateway 网关 - 无法在其认证存储中找到它。 + 这表示本次运行被固定到了某个 Anthropic auth profile，但 Gateway 网关 + 无法在其 auth 存储中找到它。 - **使用 Claude CLI** - - 在 Gateway 网关主机上运行 `openclaw models auth login --provider anthropic --method cli --set-default`。 - - **如果你想改用 API 密钥** - - 在**Gateway 网关主机**上的 `~/.openclaw/.env` 中放入 `ANTHROPIC_API_KEY`。 - - 清除任何强制使用缺失配置文件的固定顺序： + - 在 gateway 主机上运行 `openclaw models auth login --provider anthropic --method cli --set-default`。 + - **如果你想改用 API key** + - 将 `ANTHROPIC_API_KEY` 放入**gateway 主机**上的 `~/.openclaw/.env`。 + - 清除任何强制使用缺失 profile 的固定顺序： ```bash openclaw models auth order clear --provider anthropic ``` - - **确认你是在 Gateway 网关主机上运行命令** - - 在远程模式下，认证配置文件位于 Gateway 网关机器上，而不是你的笔记本上。 + - **确认你是在 gateway 主机上运行命令** + - 在 remote 模式下，auth profiles 存在于 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` / aliases 中移除或避免 Google 模型，这样回退就不会路由到那里。 + 修复方法：要么提供 Google 身份验证，要么从 `agents.defaults.model.fallbacks` / 别名中移除或避免 Google 模型，这样回退就不会路由到那里。 **LLM request rejected: thinking signature required（Google Antigravity）** - 原因：会话历史中包含**没有签名的 thinking blocks**（通常来自 - 中止/部分流）。Google Antigravity 要求 thinking blocks 带有签名。 + 原因：会话历史中包含**没有签名的 thinking 块**（通常来自 + 被中止/部分完成的流式输出）。Google Antigravity 要求 thinking 块必须带签名。 - 修复方法：OpenClaw 现在会为 Google Antigravity Claude 清除未签名的 thinking blocks。如果仍然出现，请开始一个**新会话**，或为该智能体设置 `/thinking off`。 + 修复：OpenClaw 现在会为 Google Antigravity Claude 去掉未签名的 thinking 块。如果问题仍然出现，请开始一个**新会话**，或为该智能体设置 `/thinking off`。 -## 认证配置文件：它们是什么，如何管理 +## Auth profiles：它们是什么，以及如何管理 -相关内容：[/concepts/oauth](/zh-CN/concepts/oauth)（OAuth 流程、令牌存储、多账户模式） +相关内容：[/concepts/oauth](/zh-CN/concepts/oauth)（OAuth 流程、token 存储、多账户模式） - - 认证配置文件是一个与提供商绑定的具名凭据记录（OAuth 或 API 密钥）。配置文件存储在： + + Auth profile 是一个绑定到某个 provider 的命名凭证记录（OAuth 或 API key）。Profiles 存放在： ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -2664,73 +2673,73 @@ x-i18n: - - OpenClaw 使用带提供商前缀的 ID，例如： + + OpenClaw 使用带 provider 前缀的 ID，例如： - - `anthropic:default`（没有 email 身份时很常见） - - `anthropic:` 用于 OAuth 身份 + - `anthropic:default`（常见于没有 email 身份时） + - `anthropic:`（用于 OAuth 身份） - 你自己选择的自定义 ID（例如 `anthropic:work`） - - 可以。配置支持为配置文件设置可选元数据，以及按提供商排序（`auth.order.`）。这**不会**存储 secret；它只是把 ID 映射到 provider/mode，并设置轮换顺序。 + + 可以。配置支持为 profiles 设置可选元数据，以及按 provider 指定排序（`auth.order.`）。这**不会**存储 secrets；它只是将 ID 映射到 provider/mode，并设置轮换顺序。 - 如果某个配置文件处于短期**冷却**状态（速率限制/超时/认证失败）或较长的**禁用**状态（计费/余额不足），OpenClaw 可能会暂时跳过它。要检查这一点，请运行 `openclaw models status --json` 并查看 `auth.unusableProfiles`。调优项：`auth.cooldowns.billingBackoffHours*`。 + 如果某个 profile 处于短暂**冷却**状态（速率限制/超时/auth 失败）或较长的**禁用**状态（计费/余额不足），OpenClaw 可能会临时跳过它。要检查这一点，请运行 `openclaw models status --json`，并查看 `auth.unusableProfiles`。调优项：`auth.cooldowns.billingBackoffHours*`。 - 速率限制冷却可以按模型划分。某个配置文件即使对一个模型处于冷却中， - 对同一提供商下的同类模型仍然可能可用， - 而计费/禁用窗口则仍会阻止整个配置文件。 + 速率限制冷却可以按模型范围生效。一个 profile 可能对某个模型 + 处于冷却中，但对同一 provider 下的兄弟模型仍然可用， + 而计费/禁用窗口仍会阻止整个 profile。 - 你还可以通过 CLI 设置**按智能体**的顺序覆盖（存储在该智能体的 `auth-state.json` 中）： + 你也可以通过 CLI 设置**按智能体**的顺序覆盖（存储在该智能体的 `auth-state.json` 中）： ```bash - # 默认使用已配置的默认智能体（省略 --agent） + # 默认作用于已配置的默认智能体（省略 --agent） openclaw models auth order get --provider anthropic - # 将轮换锁定到单个配置文件（只尝试这个） + # 将轮换锁定为单个 profile（只尝试这一个） openclaw models auth order set --provider anthropic anthropic:default - # 或设置一个显式顺序（提供商内部回退） + # 或设置显式顺序（provider 内部回退） openclaw models auth order set --provider anthropic anthropic:work anthropic:default - # 清除覆盖（回退到 config auth.order / round-robin） + # 清除覆盖（回退到配置中的 auth.order / round-robin） openclaw models auth order clear --provider anthropic ``` - 要定位到特定智能体： + 若要指定某个特定智能体： ```bash openclaw models auth order set --provider anthropic --agent main anthropic:default ``` - 要验证实际会尝试哪些配置文件，请使用： + 要验证实际会尝试什么，请使用： ```bash openclaw models status --probe ``` - 如果某个已存储的配置文件被显式顺序排除，probe 会为该配置文件报告 - `excluded_by_auth_order`，而不是悄悄尝试它。 + 如果某个已存储 profile 未包含在显式顺序中，probe 会为该 profile 报告 + `excluded_by_auth_order`，而不是静默尝试它。 - + OpenClaw 两者都支持： - - **OAuth** 在适用情况下通常利用订阅访问权限。 - - **API 密钥** 使用按令牌计费。 + - **OAuth** 通常会利用订阅访问权限（在适用时）。 + - **API keys** 使用按 token 计费。 - 向导明确支持 Anthropic Claude CLI、OpenAI Codex OAuth 和 API 密钥。 + 向导明确支持 Anthropic Claude CLI、OpenAI Codex OAuth 和 API keys。 -## Gateway 网关：端口、“已在运行”和远程模式 +## Gateway 网关：端口、“already running”和 remote 模式 - `gateway.port` 控制用于 WebSocket + HTTP（Control UI、hooks 等）的单一复用端口。 + `gateway.port` 控制单个复用端口，供 WebSocket + HTTP（Control UI、hooks 等）共同使用。 优先级： @@ -2741,18 +2750,18 @@ x-i18n: - 因为 “running” 是 **supervisor** 的视角（launchd/systemd/schtasks）。而 connectivity probe 是 CLI 实际去连接 Gateway 网关 WebSocket 的结果。 + 因为 “running” 是 **supervisor** 的视角（launchd/systemd/schtasks）。而 connectivity probe 是 CLI 实际去连接 gateway WebSocket 的结果。 - 请使用 `openclaw gateway status` 并重点看这些行： + 使用 `openclaw gateway status`，并以这些行的信息为准： - `Probe target:`（探测实际使用的 URL） - - `Listening:`（端口上实际绑定了什么） - - `Last gateway error:`（当进程还活着但端口未监听时，最常见的根因） + - `Listening:`（端口上实际绑定的内容） + - `Last gateway error:`（当进程仍活着但端口未监听时，常见的根因） - - 你编辑的是一个配置文件，而服务运行的是另一个（通常是 `--profile` / `OPENCLAW_STATE_DIR` 不匹配）。 + + 你正在编辑一个配置文件，但服务运行的是另一个配置文件（通常是 `--profile` / `OPENCLAW_STATE_DIR` 不匹配）。 修复方法： @@ -2760,19 +2769,19 @@ x-i18n: openclaw gateway install --force ``` - 请在你希望服务使用的同一个 `--profile` / 环境下运行该命令。 + 请在你希望服务使用的同一个 `--profile` / 环境下运行这条命令。 - OpenClaw 通过在启动时立即绑定 WebSocket 监听器来强制执行运行时锁（默认 `ws://127.0.0.1:18789`）。如果绑定因 `EADDRINUSE` 失败，它会抛出 `GatewayLockError`，表示已有另一个实例在监听。 + OpenClaw 会在启动时立即绑定 WebSocket 监听器（默认 `ws://127.0.0.1:18789`），以此强制执行运行时锁。如果绑定因 `EADDRINUSE` 失败，就会抛出 `GatewayLockError`，表示已有另一个实例正在监听。 修复方法：停止另一个实例、释放端口，或使用 `openclaw gateway --port ` 在其他端口运行。 - - 设置 `gateway.mode: "remote"`，并指向远程 WebSocket URL；如有需要，还可附带共享密钥远程凭据： + + 设置 `gateway.mode: "remote"` 并指向远程 WebSocket URL，可选提供 shared-secret 远程凭证： ```json5 { @@ -2789,98 +2798,98 @@ x-i18n: 说明： - - 只有在 `gateway.mode` 为 `local` 时，`openclaw gateway` 才会启动（除非你传入覆盖标志）。 - - macOS 应用会监视配置文件，并在这些值变化时实时切换模式。 - - `gateway.remote.token` / `.password` 只是客户端侧远程凭据；它们本身不会启用本地 Gateway 网关认证。 + - 只有当 `gateway.mode` 为 `local`（或你传入覆盖标志）时，`openclaw gateway` 才会启动。 + - macOS app 会监视配置文件，并在这些值变化时实时切换模式。 + - `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`），受信任客户端可以使用缓存的设备令牌进行一次有边界的重试。 - - 该缓存令牌重试现在会复用与设备令牌一起存储的已批准 scopes。显式 `deviceToken` / 显式 `scopes` 调用方仍会保留其请求的 scope 集，而不是继承缓存 scopes。 - - 在该重试路径之外，连接认证优先级是：显式共享令牌/密码优先，然后是显式 `deviceToken`，再然后是已存储设备令牌，最后是 bootstrap 令牌。 - - Bootstrap 令牌的 scope 检查带有角色前缀。内置 bootstrap operator allowlist 仅满足 operator 请求；node 或其他非 operator 角色仍然需要其各自角色前缀下的 scopes。 + - Control UI 会将 token 保存在当前浏览器标签页会话和所选 gateway URL 的 `sessionStorage` 中，因此同标签页刷新仍然可用，而无需恢复持久性的本地 `localStorage` token。 + - 在 `AUTH_TOKEN_MISMATCH` 情况下，当 gateway 返回重试提示（`canRetryWithDeviceToken=true`、`recommendedNextStep=retry_with_device_token`）时，受信任客户端可以用缓存的 device token 尝试一次有界重试。 + - 该缓存 token 重试现在会复用与 device token 一起存储的已批准 scopes。显式传入 `deviceToken` / 显式 `scopes` 的调用方，仍会保留自己请求的 scope 集，而不会继承缓存 scope。 + - 在这条重试路径之外，连接身份验证优先级是：显式 shared token/password 优先，然后是显式 `deviceToken`，再然后是已存储的 device 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/`。 - - 共享密钥模式：设置 `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，尝试打开；如果是 headless，会显示 SSH 提示）。 + - 如果你还没有 token：`openclaw doctor --generate-gateway-token`。 + - 如果是远程环境，先建立隧道：`ssh -N -L 18789:127.0.0.1:18789 user@host`，然后打开 `http://127.0.0.1:18789/`。 + - Shared-secret 模式：设置 `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` 或 `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`，然后在 Control UI 设置中粘贴匹配的 secret。 + - Tailscale Serve 模式：确保 `gateway.auth.allowTailscale` 已启用，并且你打开的是 Serve URL，而不是绕过 Tailscale 身份头的原始 loopback/tailnet URL。 + - Trusted-proxy 模式：确保你是通过已配置的非 loopback 身份感知代理访问的，而不是通过同机 loopback 代理或原始 gateway URL。 + - 如果一次重试之后仍然不匹配，请轮换/重新批准配对的 device token： - `openclaw devices list` - `openclaw devices rotate --device --role operator` - - 如果该 rotate 调用提示被拒绝，请检查两点： - - 配对设备会话只能轮换它们**自己的**设备，除非同时具有 `operator.admin` + - 如果该轮换调用提示被拒绝，请检查两点： + - 配对设备会话只能轮换**它们自己的**设备，除非它们同时拥有 `operator.admin` - 显式 `--scope` 值不能超过调用方当前的 operator scopes - - 还是卡住？运行 `openclaw status --all`，并按照 [故障排除](/zh-CN/gateway/troubleshooting) 操作。认证细节请参阅 [Dashboard](/zh-CN/web/dashboard)。 + - 还是卡住？运行 `openclaw status --all`，并按照 [故障排除](/zh-CN/gateway/troubleshooting) 操作。身份验证详情参见 [Dashboard](/zh-CN/web/dashboard)。 - - `tailnet` 绑定会从你的网络接口中选择一个 Tailscale IP（100.64.0.0/10）。如果该机器未加入 Tailscale（或接口已断开），那就没有可绑定的地址。 + + `tailnet` 绑定会从你的网络接口中选择一个 Tailscale IP（100.64.0.0/10）。如果该机器不在 Tailscale 中（或接口已关闭），就没有可供绑定的地址。 修复方法： - - 在该主机上启动 Tailscale（让它拥有一个 100.x 地址），或者 - - 切换到 `gateway.bind: "loopback"` / `"lan"`。 + - 在那台主机上启动 Tailscale（这样它才会拥有 100.x 地址），或者 + - 改用 `gateway.bind: "loopback"` / `"lan"`。 - 说明：`tailnet` 是显式模式。`auto` 更倾向于 loopback；当你想仅绑定到 tailnet 时，请使用 `gateway.bind: "tailnet"`。 + 注意：`tailnet` 是显式的。`auto` 更偏向 loopback；如果你想只绑定到 tailnet，请使用 `gateway.bind: "tailnet"`。 - 通常不需要——一个 Gateway 网关就可以运行多个消息渠道和智能体。只有当你需要冗余（例如救援机器人）或强隔离时，才使用多个 Gateway 网关。 + 通常不可以——一个 Gateway 网关就能运行多个消息渠道和智能体。只有在你需要冗余（例如救援 bot）或硬隔离时，才使用多个 Gateway 网关。 - 但确实可以，只是你必须隔离以下内容： + 可以，但你必须隔离： - - `OPENCLAW_CONFIG_PATH`（按实例分开的配置） - - `OPENCLAW_STATE_DIR`（按实例分开的状态） + - `OPENCLAW_CONFIG_PATH`（按实例独立配置） + - `OPENCLAW_STATE_DIR`（按实例独立状态） - `agents.defaults.workspace`（工作区隔离） - `gateway.port`（唯一端口） 快速设置（推荐）： - - 每个实例使用 `openclaw --profile ...`（会自动创建 `~/.openclaw-`）。 - - 在每个 profile 配置中设置唯一的 `gateway.port`（或在手动运行时传入 `--port`）。 - - 为每个 profile 安装一个服务：`openclaw --profile gateway install`。 + - 每个实例都使用 `openclaw --profile ...`（会自动创建 `~/.openclaw-`）。 + - 在每个 profile 配置中设置唯一的 `gateway.port`（或手动运行时传入 `--port`）。 + - 安装按 profile 区分的服务：`openclaw --profile gateway install`。 - Profiles 也会给服务名加后缀（`ai.openclaw.`；旧版为 `com.openclaw.*`、`openclaw-gateway-.service`、`OpenClaw Gateway ()`）。 - 完整指南：[Multiple gateways](/zh-CN/gateway/multiple-gateways)。 + Profiles 也会给服务名添加后缀（`ai.openclaw.`；旧版为 `com.openclaw.*`、`openclaw-gateway-.service`、`OpenClaw Gateway ()`）。 + 完整指南：[多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。 - + Gateway 网关是一个 **WebSocket server**，并且它期望收到的第一条消息 - 是一个 `connect` 帧。如果收到的是其他内容，它就会以 - **代码 1008**（策略违规）关闭连接。 + 是一个 `connect` 帧。如果收到其他任何内容，它就会以 + **code 1008**（策略违规）关闭连接。 常见原因： - 你在浏览器中打开了 **HTTP** URL（`http://...`），而不是使用 WS 客户端。 - 你用了错误的端口或路径。 - - 某个代理或隧道剥离了认证头，或发送了非 Gateway 网关请求。 + - 代理或隧道剥离了身份验证头，或发送了非 Gateway 网关请求。 快速修复： - 1. 使用 WS URL：`ws://:18789`（如果启用了 HTTPS，则使用 `wss://...`）。 + 1. 使用 WS URL：`ws://:18789`（如果是 HTTPS，则用 `wss://...`）。 2. 不要在普通浏览器标签页中打开 WS 端口。 - 3. 如果启用了认证，请在 `connect` 帧中包含令牌/密码。 + 3. 如果启用了身份验证，请在 `connect` 帧中包含 token/password。 - 如果你使用的是 CLI 或 TUI，URL 应该是这样的： + 如果你使用的是 CLI 或 TUI，URL 应类似于： ``` openclaw tui --url ws://:18789 --token ``` - 协议细节：[Gateway protocol](/zh-CN/gateway/protocol)。 + 协议详情：[Gateway 协议](/zh-CN/gateway/protocol)。 @@ -2895,38 +2904,38 @@ 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/...`；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 内部。 @@ -2938,7 +2947,7 @@ x-i18n: openclaw gateway restart ``` - 如果你从未安装服务，请在前台启动它： + 如果你从未安装服务，请以前台方式启动： ```bash openclaw gateway run @@ -2946,7 +2955,7 @@ x-i18n: **2）原生 Windows（不推荐）：**Gateway 网关直接运行在 Windows 中。 - 打开 PowerShell 并运行： + 打开 PowerShell，然后运行： ```powershell openclaw gateway status @@ -2959,12 +2968,12 @@ x-i18n: openclaw gateway run ``` - 文档：[Windows（WSL2）](/zh-CN/platforms/windows)、[Gateway service runbook](/zh-CN/gateway)。 + 文档：[Windows（WSL2）](/zh-CN/platforms/windows)、[Gateway 网关服务操作手册](/zh-CN/gateway)。 - - 先做一次快速健康检查： + + 先做一轮快速健康检查： ```bash openclaw status @@ -2975,26 +2984,26 @@ x-i18n: 常见原因： - - 模型认证未在 **Gateway 网关主机** 上加载（检查 `models status`）。 + - 模型身份验证没有在**gateway 主机**上加载（检查 `models status`）。 - 渠道配对/allowlist 阻止了回复（检查渠道配置 + 日志）。 - - WebChat/Dashboard 打开时未使用正确的令牌。 + - WebChat/Dashboard 打开时没有使用正确 token。 - 如果你处于远程模式，请确认隧道/Tailscale 连接已建立，并且 - Gateway 网关 WebSocket 可达。 + 如果你处于远程环境，请确认隧道/Tailscale 连接正常，并且 + Gateway WebSocket 可达。 文档：[Channels](/zh-CN/channels)、[故障排除](/zh-CN/gateway/troubleshooting)、[远程访问](/zh-CN/gateway/remote)。 - - 这通常表示 UI 丢失了与 Gateway 网关的 WebSocket 连接。请检查： + + 这通常意味着 UI 丢失了 WebSocket 连接。请检查： 1. Gateway 网关是否正在运行？`openclaw gateway status` 2. Gateway 网关是否健康？`openclaw status` - 3. UI 是否持有正确令牌？`openclaw dashboard` - 4. 如果是远程模式，隧道/Tailscale 连接是否正常？ + 3. UI 是否拥有正确 token？`openclaw dashboard` + 4. 如果是远程环境，隧道/Tailscale 连接是否正常？ - 然后查看日志尾部： + 然后跟踪日志： ```bash openclaw logs --follow @@ -3005,26 +3014,26 @@ x-i18n: - 先查看日志和渠道状态： + 先从日志和渠道状态开始： ```bash openclaw channels status openclaw channels logs --channel telegram ``` - 然后对照错误类型： + 然后根据错误进行匹配： - - `BOT_COMMANDS_TOO_MUCH`：Telegram 菜单条目过多。OpenClaw 已经会裁剪到 Telegram 的上限并用更少的命令重试，但某些菜单项仍然需要进一步删减。请减少插件/Skills/自定义命令，或者如果你不需要菜单，就禁用 `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 上或位于代理之后，请确认允许出站 HTTPS，并且 `api.telegram.org` 的 DNS 解析正常。 - 如果 Gateway 网关是远程的，请确认你查看的是 Gateway 网关主机上的日志。 + 如果 Gateway 网关是远程的，请确保你查看的是 Gateway 网关主机上的日志。 文档：[Telegram](/zh-CN/channels/telegram)、[渠道故障排除](/zh-CN/channels/troubleshooting)。 - - 先确认 Gateway 网关可达，并且智能体可以运行： + + 先确认 Gateway 网关可达，并且智能体能够运行： ```bash openclaw status @@ -3032,53 +3041,53 @@ x-i18n: openclaw logs --follow ``` - 在 TUI 中，使用 `/status` 查看当前状态。如果你希望回复发送到某个聊天 - 渠道，请确认已启用投递（`/deliver on`）。 + 在 TUI 中，使用 `/status` 查看当前状态。如果你期望回复出现在聊天 + 渠道中，请确保投递已启用（`/deliver on`）。 文档：[TUI](/zh-CN/web/tui)、[Slash commands](/zh-CN/tools/slash-commands)。 - - 如果你已安装服务： + + 如果你安装了服务： ```bash openclaw gateway stop openclaw gateway start ``` - 这会停止/启动**受监管服务**（macOS 上为 launchd，Linux 上为 systemd）。 + 这会停止/启动**受监管的服务**（macOS 上是 launchd，Linux 上是 systemd）。 当 Gateway 网关作为后台守护进程运行时，请使用这种方式。 - 如果你是在前台运行，先用 Ctrl-C 停止，然后： + 如果你是在前台运行，请用 Ctrl-C 停止，然后执行： ```bash openclaw gateway run ``` - 文档：[Gateway service runbook](/zh-CN/gateway)。 + 文档：[Gateway 网关服务操作手册](/zh-CN/gateway)。 - + - `openclaw gateway restart`：重启**后台服务**（launchd/systemd）。 - - `openclaw gateway`：在当前终端会话中**前台运行** Gateway 网关。 + - `openclaw gateway`：在**前台**为当前终端会话运行 gateway。 - 如果你已经安装了服务，就使用 gateway 相关命令。需要一次性的前台运行时， - 使用 `openclaw gateway`。 + 如果你安装了服务，就使用 gateway 命令组。当你 + 想进行一次性前台运行时，使用 `openclaw gateway`。 - - 使用 `--verbose` 启动 Gateway 网关，以获取更多控制台细节。然后检查日志文件中的渠道认证、模型路由和 RPC 错误。 + + 使用 `--verbose` 启动 Gateway 网关，以获得更多控制台细节。然后检查日志文件，查看渠道身份验证、模型路由和 RPC 错误。 ## 媒体和附件 - - 智能体发出的附件必须包含一行 `MEDIA:`（单独一行）。请参阅 [OpenClaw assistant setup](/zh-CN/start/openclaw) 和 [Agent send](/zh-CN/tools/agent-send)。 + + 智能体发出的附件必须包含一行 `MEDIA:`（单独占一行）。参见 [OpenClaw 助手设置](/zh-CN/start/openclaw) 和 [Agent send](/zh-CN/tools/agent-send)。 CLI 发送方式： @@ -3086,14 +3095,14 @@ x-i18n: openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png ``` - 还要检查： + 还请检查： - - 目标渠道支持出站媒体，并且未被 allowlist 阻止。 - - 文件未超过提供商的大小限制（图片会被调整为最大 2048px）。 - - `tools.fs.workspaceOnly=true` 会将本地路径发送限制在工作区、temp/media-store 和通过沙箱校验的文件内。 - - `tools.fs.workspaceOnly=false` 允许 `MEDIA:` 发送智能体本就能读取的主机本地文件，但仅限媒体和安全文档类型（图片、音频、视频、PDF 以及 Office 文档）。纯文本和类似 secret 的文件仍会被阻止。 + - 目标渠道支持发送媒体，并且没有被 allowlists 阻止。 + - 文件在 provider 的大小限制之内（图片会被调整为最长边不超过 2048px）。 + - `tools.fs.workspaceOnly=true` 会将本地路径发送限制在工作区、临时/media-store 和通过沙箱验证的文件范围内。 + - `tools.fs.workspaceOnly=false` 允许 `MEDIA:` 发送智能体已经可以读取的主机本地文件，但仅限媒体以及安全文档类型（图片、音频、视频、PDF 和 Office 文档）。纯文本和类似 secret 的文件仍然会被阻止。 - 请参阅 [Images](/zh-CN/nodes/images)。 + 参见 [Images](/zh-CN/nodes/images)。 @@ -3101,73 +3110,73 @@ x-i18n: ## 安全和访问控制 - - 请将入站私信视为不受信任输入。默认设置旨在降低风险： + + 请将入站私信视为不可信输入。默认设置就是为了降低风险而设计的： - - 在支持私信的渠道上，默认行为是**配对**： + - 具备私信能力的渠道默认行为是**配对**： - 未知发送者会收到一个配对码；机器人不会处理他们的消息。 - - 批准方式：`openclaw pairing approve --channel [--account ] ` - - 每个渠道的待处理请求上限为 **3 个**；如果没有收到代码，请检查 `openclaw pairing list --channel [--account ]` - - 想公开开放私信，需要显式选择加入（`dmPolicy: "open"` 且 allowlist 为 `"*"`）。 + - 通过以下方式批准：`openclaw pairing approve --channel [--account ] ` + - 每个渠道的待处理请求上限为 **3 个**；如果代码没有到达，请检查 `openclaw pairing list --channel [--account ]` + - 若要公开开放私信，必须显式启用（`dmPolicy: "open"` 且 allowlist 为 `"*"`）。 - 运行 `openclaw doctor` 可以发现有风险的私信策略。 + 运行 `openclaw doctor` 可以发现风险较高的私信策略。 - - 不是。提示注入关乎的是**不受信任的内容**，而不只是“谁可以给机器人发私信”。 - 如果你的助手会读取外部内容（Web 搜索/抓取、浏览器页面、邮件、 - 文档、附件、粘贴的日志），这些内容中都可能包含试图 - 劫持模型的指令。即使**只有你自己**是发送者，也会发生这种情况。 + + 不是。提示注入针对的是**不可信内容**，而不只是“谁能给 bot 发私信”。 + 如果你的助手会读取外部内容（web 搜索/抓取、浏览器页面、邮件、 + 文档、附件、粘贴的日志），这些内容都可能包含试图 + 劫持模型的指令。即使**只有你自己是发送者**，这种情况也会发生。 - 最大的风险出现在启用工具时：模型可能被诱导 - 泄露上下文，或代表你调用工具。可通过以下方式降低影响范围： + 最大的风险出现在启用了工具时：模型可能被诱导去 + 泄露上下文，或代表你调用工具。你可以通过以下方式降低影响范围： - - 使用一个只读或禁用工具的“reader”智能体来总结不受信任内容 - - 对启用工具的智能体关闭 `web_search` / `web_fetch` / `browser` - - 同样将解码后的文件/文档文本视为不受信任：OpenResponses - `input_file` 和媒体附件提取都会把提取出的文本包裹在 - 明确的外部内容边界标记中，而不是直接传递原始文件文本 - - 使用沙箱隔离和严格的工具 allowlist + - 使用只读或禁用工具的“阅读器”智能体来总结不可信内容 + - 对启用了工具的智能体关闭 `web_search` / `web_fetch` / `browser` + - 也要将解码后的文件/文档文本视为不可信：OpenResponses + `input_file` 和媒体附件提取都会将提取文本包裹在 + 明确的外部内容边界标记中，而不是直接传入原始文件文本 + - 启用沙箱隔离和严格的工具 allowlists - 详情：[Security](/zh-CN/gateway/security)。 + 详情参见：[Security](/zh-CN/gateway/security)。 - - 对于大多数部署，是的。通过单独的账号和手机号将机器人隔离出来， + + 对大多数设置来说，应该如此。使用独立的账号和手机号来隔离 bot， 可以在出问题时缩小影响范围。这样也更容易轮换 - 凭据或撤销访问，而不会影响你的个人账号。 + 凭证或撤销访问，而不会影响你的个人账号。 - 从小规模开始。只赋予它你实际需要的工具和账号访问权限， - 如果后续需要，再逐步扩展。 + 从小规模开始。只给它真正需要的工具和账号访问权限， + 如果后续确有需要，再逐步扩展。 - 文档：[Security](/zh-CN/gateway/security)、[Pairing](/zh-CN/channels/pairing)。 + 文档：[Security](/zh-CN/gateway/security)、[配对](/zh-CN/channels/pairing)。 - 我们**不**推荐让它对你的个人消息拥有完全自主权。最安全的模式是： + 我们**不建议**让它完全自主处理你的个人消息。最安全的模式是： - - 将私信保持在**配对模式**或严格的 allowlist 下。 - - 如果你希望它代表你发消息，请使用**单独的号码或账号**。 - - 让它先起草，然后**发送前再审批**。 + - 将私信保持在**配对模式**或严格 allowlist 中。 + - 如果你想让它代表你发消息，请使用**独立的号码或账号**。 + - 让它先起草，然后在发送前**由你审批**。 - 如果你想试验，请在专用账号上进行，并保持隔离。请参阅 + 如果你想尝试，请在一个专用账号上进行，并保持隔离。参见 [Security](/zh-CN/gateway/security)。 - - 可以，**前提是**该智能体仅用于聊天，并且输入是可信的。较小档位 - 更容易受到指令劫持，因此不要将其用于启用工具的智能体， - 或用于读取不受信任内容的场景。如果你必须使用较小模型，请锁紧 - 工具，并在沙箱中运行。请参阅 [Security](/zh-CN/gateway/security)。 + + 可以，**前提是**该智能体只用于聊天，且输入是可信的。较小档位的模型 + 更容易受到指令劫持，因此不要将它们用于启用了工具的智能体， + 或用于读取不可信内容的场景。如果你必须使用较小模型，请锁紧 + 工具并在沙箱中运行。参见 [Security](/zh-CN/gateway/security)。 - - 只有当未知发送者向机器人发消息，并且 - `dmPolicy: "pairing"` 已启用时，才会发送配对码。单独发送 `/start` 不会生成代码。 + + 只有当未知发送者给 bot 发消息，且 + `dmPolicy: "pairing"` 已启用时，才会发送配对码。单独执行 `/start` 本身不会生成代码。 检查待处理请求： @@ -3175,14 +3184,14 @@ x-i18n: openclaw pairing list telegram ``` - 如果你想立即访问，请将你的发送者 id 加入 allowlist，或为该账户设置 `dmPolicy: "open"`。 + 如果你想立即获得访问权限，请将你的发送者 id 加入 allowlist，或为该账户设置 `dmPolicy: "open"`。 - 不会。WhatsApp 私信默认策略是**配对**。未知发送者只会收到一个配对码，而他们的消息**不会被处理**。OpenClaw 只会回复它收到的聊天，或你显式触发的发送。 + 不会。WhatsApp 私信的默认策略是**配对**。未知发送者只会收到一个配对码，他们的消息**不会被处理**。OpenClaw 只会回复它收到的聊天，或者回复由你显式触发的发送。 - 批准配对： + 通过以下命令批准配对： ```bash openclaw pairing approve whatsapp @@ -3194,18 +3203,19 @@ x-i18n: openclaw pairing list whatsapp ``` - 向导中的手机号提示：它用于设置你的**allowlist/owner**，从而允许你自己的私信。它不会用于自动发送。如果你运行在自己的 WhatsApp 号码上，请使用该号码，并启用 `channels.whatsapp.selfChatMode`。 + 向导中的手机号提示用于设置你的**allowlist/owner**，以便允许你自己的私信。它不会用于自动发送。如果你是在个人 WhatsApp 号码上运行，请使用该号码，并启用 `channels.whatsapp.selfChatMode`。 -## 聊天命令、终止任务，以及“它停不下来” +## 聊天命令、中止任务，以及“它停不下来” - - 大多数内部消息或工具消息只会在该会话启用了 **verbose**、**trace** 或 **reasoning** 时出现。 + + 大多数内部消息或工具消息只会在该会话启用了 **verbose**、**trace** 或 **reasoning** 时 + 显示出来。 - 在你看到这些内容的聊天里执行以下命令： + 在出现这些内容的聊天中执行以下命令： ``` /verbose off @@ -3214,15 +3224,15 @@ x-i18n: ``` 如果仍然很吵，请检查 Control UI 中的会话设置，并将 verbose - 设为 **inherit**。同时确认你没有使用在配置中将 `verboseDefault` 设为 - `on` 的机器人配置文件。 + 设置为 **inherit**。同时确认你没有在配置中使用将 `verboseDefault` 设为 + `on` 的 bot profile。 文档：[Thinking and verbose](/zh-CN/tools/thinking)、[Security](/zh-CN/gateway/security#reasoning-verbose-output-in-groups)。 - - 将以下任意内容**作为独立消息发送**（不要加斜杠）： + + 将以下任意内容**作为单独消息发送**（不要带斜杠）： ``` stop @@ -3254,17 +3264,17 @@ x-i18n: process action:kill sessionId:XXX ``` - 斜杠命令总览：请参阅 [Slash commands](/zh-CN/tools/slash-commands)。 + 斜杠命令概览：参见 [Slash commands](/zh-CN/tools/slash-commands)。 - 大多数命令必须作为一条**独立**消息发送，并且以 `/` 开头，但有少数快捷命令（例如 `/status`）对于 allowlist 中的发送者也可以内联使用。 + 大多数命令必须作为**单独消息**发送，并且以 `/` 开头，但也有少数快捷方式（如 `/status`）对 allowlist 中的发送者支持内联使用。 - 默认情况下，OpenClaw 会阻止**跨提供商**消息发送。如果某次工具调用绑定 - 在 Telegram 上，它就不会发送到 Discord，除非你显式允许。 + 默认情况下，OpenClaw 会阻止**跨 provider**消息发送。如果某个工具调用绑定到了 + Telegram，它就不会发送到 Discord，除非你显式允许。 - 为该智能体启用跨提供商消息发送： + 为该智能体启用跨 provider 消息发送： ```json5 { @@ -3279,32 +3289,32 @@ x-i18n: } ``` - 编辑配置后重启 Gateway 网关。 + 编辑配置后请重启 gateway。 - - 队列模式控制新消息如何与正在进行中的运行交互。使用 `/queue` 更改模式： + + 队列模式决定新消息如何与正在进行中的运行交互。使用 `/queue` 更改模式： - `steer` - 新消息会重定向当前任务 - - `followup` - 消息逐条运行 - - `collect` - 批量收集消息并统一回复一次（默认） - - `steer-backlog` - 先转向当前任务，再处理积压 + - `followup` - 消息逐条依次运行 + - `collect` - 批量收集消息后一次性回复（默认） + - `steer-backlog` - 先重定向当前任务，再处理积压 - `interrupt` - 中止当前运行并重新开始 - 对于 followup 模式，你还可以添加如 `debounce:2s cap:25 drop:summarize` 这样的选项。 + 你还可以为 followup 模式添加 `debounce:2s cap:25 drop:summarize` 等选项。 -## 杂项 +## 其他 - - 在 OpenClaw 中，凭据和模型选择是分离的。设置 `ANTHROPIC_API_KEY`（或在认证配置文件中存储 Anthropic API 密钥）会启用认证，但实际默认模型取决于你在 `agents.defaults.model.primary` 中配置的值（例如 `anthropic/claude-sonnet-4-6` 或 `anthropic/claude-opus-4-6`）。如果你看到 `No credentials found for profile "anthropic:default"`，这表示 Gateway 网关无法在当前运行智能体对应的 `auth-profiles.json` 中找到 Anthropic 凭据。 + + 在 OpenClaw 中，凭证和模型选择是分开的。设置 `ANTHROPIC_API_KEY`（或在 auth profiles 中存储 Anthropic API key）会启用身份验证，但实际默认模型取决于你在 `agents.defaults.model.primary` 中配置的内容（例如 `anthropic/claude-sonnet-4-6` 或 `anthropic/claude-opus-4-6`）。如果你看到 `No credentials found for profile "anthropic:default"`，说明 Gateway 网关无法在当前运行智能体的预期 `auth-profiles.json` 中找到 Anthropic 凭证。 --- -如果还是卡住了？请到 [Discord](https://discord.com/invite/clawd) 提问，或发起一个 [GitHub discussion](https://github.com/openclaw/openclaw/discussions)。 +还是卡住了？欢迎到 [Discord](https://discord.com/invite/clawd) 提问，或发起 [GitHub discussion](https://github.com/openclaw/openclaw/discussions)。 diff --git a/docs/zh-CN/help/testing.md b/docs/zh-CN/help/testing.md index 615d91f13..7e392df45 100644 --- a/docs/zh-CN/help/testing.md +++ b/docs/zh-CN/help/testing.md @@ -1,128 +1,132 @@ --- read_when: - 在本地或 CI 中运行测试 - - 为模型 / 提供商 bug 添加回归测试 + - 为模型 / 提供商缺陷添加回归测试 - 调试 Gateway 网关 + 智能体行为 -summary: 测试工具包：单元 / e2e / live 测试套件、Docker 运行器，以及每种测试覆盖的内容 +summary: 测试工具包：单元 / e2e / 实时测试套件、Docker 运行器，以及各类测试分别覆盖的内容 title: 测试 x-i18n: - generated_at: "2026-04-23T18:44:49Z" + generated_at: "2026-04-23T19:25:09Z" model: gpt-5.4 provider: openai - source_hash: ea28cf3495b45d81d389b04b2e939fa157b3b6bc6e22e3480179337aad6af5f2 + source_hash: 1a26531abaab4e09f27976a12c5f4394f5f30eade060659670ba57adfc5fdc71 source_path: help/testing.md workflow: 15 --- -OpenClaw 有三个 Vitest 测试套件（unit/integration、e2e、live）以及一小组 Docker 运行器。本文档是一份“我们如何测试”的指南： +OpenClaw 有三个 Vitest 测试套件（单元 / 集成、e2e、实时），以及一小组 Docker 运行器。本文档是一份“我们如何测试”的指南： -- 每个测试套件覆盖什么（以及它有意 _不_ 覆盖什么）。 -- 常见工作流（本地、推送前、调试）应运行哪些命令。 -- live 测试如何发现凭证并选择模型 / 提供商。 +- 每个测试套件覆盖什么（以及它**刻意不**覆盖什么）。 +- 常见工作流应运行哪些命令（本地、推送前、调试）。 +- 实时测试如何发现凭证并选择模型 / 提供商。 - 如何为真实世界中的模型 / 提供商问题添加回归测试。 ## 快速开始 大多数时候： -- 完整门禁（预期在推送前执行）：`pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- 在配置充裕的机器上更快地运行本地全套测试：`pnpm test:max` -- 直接使用 Vitest 观察循环：`pnpm test:watch` -- 直接按文件定位现在也会路由 `extensions` / `channel` 路径：`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- 当你在迭代单个失败用例时，优先先跑有针对性的测试。 +- 完整门禁（预计在推送前运行）：`pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- 在配置较高的机器上更快地运行本地完整测试套件：`pnpm test:max` +- 直接进入 Vitest 监视循环：`pnpm test:watch` +- 直接指定文件现在也支持 extension / channel 路径：`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- 当你在迭代某个单独失败用例时，优先运行定向测试。 - Docker 支持的 QA 站点：`pnpm qa:lab:up` - Linux VM 支持的 QA 通道：`pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -当你修改了测试或想获得额外信心时： +当你改动了测试，或希望获得更高把握时： - 覆盖率门禁：`pnpm test:coverage` - E2E 测试套件：`pnpm test:e2e` -当你在调试真实的提供商 / 模型时（需要真实凭证）： +当你在调试真实提供商 / 模型时（需要真实凭证）： -- live 测试套件（模型 + Gateway 网关 工具 / 图像探针）：`pnpm test:live` -- 静默方式只跑一个 live 文件：`pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Docker live 模型扫描：`pnpm test:docker:live-models` - - 现在每个选中的模型都会运行一次文本轮次加一个小型类文件读取探针。元数据声明支持 `image` 输入的模型还会运行一个极小图像轮次。隔离提供商故障时，可通过 `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` 或 `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` 禁用这些额外探针。 - - CI 覆盖：每日的 `OpenClaw Scheduled Live And E2E Checks` 与手动触发的 `OpenClaw Release Checks` 都会调用可复用的 live / E2E 工作流，并设置 `include_live_suites: true`，其中包含按提供商分片的独立 Docker live 模型矩阵作业。 - - 对于聚焦的 CI 重跑，可触发 `OpenClaw Live And E2E Checks (Reusable)`，并设置 `include_live_suites: true` 与 `live_models_only: true`。 - - 将新的高信号提供商 secret 添加到 `scripts/ci-hydrate-live-auth.sh` 以及 `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` 及其 schedule / release 调用方中。 -- Moonshot / Kimi 成本冒烟测试：设置 `MOONSHOT_API_KEY` 后，先运行 `openclaw models list --provider moonshot --json`，然后针对 `moonshot/kimi-k2.6` 运行隔离的 `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json`。验证 JSON 报告的是 Moonshot / K2.6，并且 assistant transcript 存储了规范化后的 `usage.cost`。 +- 实时测试套件（模型 + Gateway 网关工具 / 图片探测）：`pnpm test:live` +- 安静地只运行一个实时测试文件：`pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Docker 实时模型扫描：`pnpm test:docker:live-models` + - 现在每个选中的模型都会运行一次文本轮次外加一次小型文件读取风格探测。元数据声明支持 `image` 输入的模型还会运行一个极小的图片轮次。隔离提供商故障时，可通过 `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` 或 `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` 禁用这些额外探测。 + - CI 覆盖：每日的 `OpenClaw Scheduled Live And E2E Checks` 和手动触发的 `OpenClaw Release Checks` 都会调用可复用的实时 / E2E 工作流，并设置 `include_live_suites: true`，其中包括按提供商分片的独立 Docker 实时模型矩阵作业。 + - 若要进行有针对性的 CI 重跑，请触发 `OpenClaw Live And E2E Checks (Reusable)`，并设置 `include_live_suites: true` 和 `live_models_only: true`。 + - 将新的高信号提供商密钥添加到 `scripts/ci-hydrate-live-auth.sh`、`.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` 及其计划 / 发布调用方中。 +- Moonshot / Kimi 成本冒烟测试：设置 `MOONSHOT_API_KEY` 后，运行 + `openclaw models list --provider moonshot --json`，然后针对 `moonshot/kimi-k2.6` 单独运行 + `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` + 。验证 JSON 报告的是 Moonshot / K2.6，并且助手转录中存储了规范化后的 `usage.cost`。 -提示：当你只需要一个失败用例时，优先通过下面描述的 allowlist 环境变量来收窄 live 测试范围。 +提示：如果你只需要一个失败用例，优先使用下文所述的允许列表环境变量来缩小实时测试范围。 ## QA 专用运行器 -当你需要 QA-lab 级别的真实性时，这些命令与主测试套件并列存在： +当你需要更接近 QA lab 真实环境的测试时，这些命令与主测试套件并列使用： -CI 会在专用工作流中运行 QA Lab。`Parity gate` 会在匹配的 PR 上运行，也可通过手动触发结合 mock 提供商运行。`QA-Lab - All Lanes` 会在 `main` 上每夜运行，也可通过手动触发并行运行 mock parity gate、live Matrix 通道和 Convex 管理的 live Telegram 通道。`OpenClaw Release Checks` 会在发布审批前运行相同的通道。 +CI 会在专用工作流中运行 QA Lab。`Parity gate` 会在匹配的 PR 和手动触发时，以 mock 提供商运行。`QA-Lab - All Lanes` 会在 `main` 上每晚运行，也可手动触发，并以 mock parity gate、实时 Matrix 通道和由 Convex 管理的实时 Telegram 通道作为并行作业运行。`OpenClaw Release Checks` 会在发布审批前运行相同通道。 - `pnpm openclaw qa suite` - - 直接在宿主机上运行基于仓库的 QA 场景。 - - 默认情况下，会使用隔离的 Gateway 网关 worker 并行运行多个选中的场景。`qa-channel` 默认并发数为 4（受所选场景数量限制）。使用 `--concurrency ` 调整 worker 数量，或使用 `--concurrency 1` 启用旧的串行通道。 - - 任一场景失败时以非零状态退出。当你希望生成工件但不希望退出码失败时，使用 `--allow-failures`。 - - 支持 `live-frontier`、`mock-openai` 和 `aimock` 三种提供商模式。`aimock` 会启动一个本地的 AIMock 支持提供商服务器，用于实验性的 fixture 和协议 mock 覆盖，但不会替代具备场景感知能力的 `mock-openai` 通道。 + - 直接在主机上运行基于仓库的 QA 场景。 + - 默认以隔离的 Gateway 网关工作进程并行运行多个选定场景。`qa-channel` 默认并发数为 4（受所选场景数量限制）。使用 `--concurrency ` 调整工作进程数量，或使用 `--concurrency 1` 启用旧式串行通道。 + - 任一场景失败时以非零退出。若你希望生成工件但不返回失败退出码，请使用 `--allow-failures`。 + - 支持提供商模式 `live-frontier`、`mock-openai` 和 `aimock`。 + `aimock` 会启动一个本地 AIMock 支持的提供商服务器，用于实验性的夹具和协议 mock 覆盖，而不是替代带有场景感知能力的 `mock-openai` 通道。 - `pnpm openclaw qa suite --runner multipass` - - 在一次性的 Multipass Linux VM 中运行相同的 QA 测试套件。 - - 与宿主机上的 `qa suite` 保持相同的场景选择行为。 + - 在一次性的 Multipass Linux VM 中运行同一套 QA 测试。 + - 与主机上的 `qa suite` 保持相同的场景选择行为。 - 复用与 `qa suite` 相同的提供商 / 模型选择标志。 - - live 运行会转发对 guest 可行的受支持 QA 认证输入：基于 env 的提供商密钥、QA live 提供商配置路径，以及存在时的 `CODEX_HOME`。 - - 输出目录必须保持在仓库根目录下，以便 guest 能通过挂载的工作区回写。 - - 会在 `.artifacts/qa-e2e/...` 下写入常规 QA 报告 + 摘要，以及 Multipass 日志。 + - 实时运行会将对访客系统切实可行的受支持 QA 认证输入转发过去：基于环境变量的提供商密钥、QA 实时提供商配置路径，以及存在时的 `CODEX_HOME`。 + - 输出目录必须位于仓库根目录下，以便访客系统可以通过挂载的工作区回写。 + - 将常规 QA 报告 + 摘要以及 Multipass 日志写入 `.artifacts/qa-e2e/...`。 - `pnpm qa:lab:up` - - 启动 Docker 支持的 QA 站点，用于面向操作员风格的 QA 工作。 + - 启动 Docker 支持的 QA 站点，用于偏操作员风格的 QA 工作。 - `pnpm test:docker:npm-onboard-channel-agent` - - 从当前 checkout 构建一个 npm tarball，在 Docker 中全局安装它，运行非交互式 OpenAI API-key 新手引导，默认配置 Telegram，验证启用插件时会按需安装运行时依赖，运行 doctor，并针对一个 mock OpenAI 端点运行一次本地智能体轮次。 - - 使用 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 可通过 Discord 运行同样的打包安装通道。 + - 基于当前 checkout 构建 npm tarball，在 Docker 中全局安装，以非交互方式运行 OpenAI API 密钥 onboarding，默认配置 Telegram，验证启用插件时会按需安装运行时依赖，运行 doctor，并针对一个模拟的 OpenAI 端点运行一次本地智能体轮次。 + - 使用 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 可在 Discord 上运行相同的打包安装通道。 - `pnpm test:docker:bundled-channel-deps` - - 在 Docker 中打包并安装当前 OpenClaw 构建，启动已配置 OpenAI 的 Gateway 网关，然后通过编辑配置启用内置渠道 / 插件。 - - 验证设置发现流程会让未配置插件的运行时依赖保持未安装状态；首次配置后的 Gateway 网关 或 doctor 运行会按需安装每个内置插件的运行时依赖；第二次重启不会重复安装已经激活的依赖。 - - 还会安装一个已知的较旧 npm 基线，在运行 `openclaw update --tag ` 之前启用 Telegram，并验证候选版本在更新后的 doctor 中会修复内置渠道运行时依赖，而无需测试框架侧的 postinstall 修复。 + - 在 Docker 中打包并安装当前 OpenClaw 构建，启动已配置 OpenAI 的 Gateway 网关，然后通过编辑配置启用内置 channel / plugin。 + - 验证设置发现阶段不会预先安装未配置插件的运行时依赖，首次配置后的 Gateway 网关或 doctor 运行会按需安装每个内置插件的运行时依赖，第二次重启不会重复安装已激活的依赖。 + - 同时还会安装一个已知的较旧 npm 基线，在运行 `openclaw update --tag ` 之前启用 Telegram，并验证候选版本在更新后的 doctor 会修复内置 channel 运行时依赖，而无需依赖 harness 侧的 postinstall 修复。 - `pnpm openclaw qa aimock` - 仅启动本地 AIMock 提供商服务器，用于直接协议冒烟测试。 - `pnpm openclaw qa matrix` - - 针对一次性的 Docker 支持 Tuwunel homeserver 运行 Matrix live QA 通道。 - - 这个 QA 宿主目前仅供仓库 / 开发使用。打包后的 OpenClaw 安装不附带 `qa-lab`，因此不会暴露 `openclaw qa`。 + - 针对一次性的 Docker 支持 Tuwunel homeserver 运行 Matrix 实时 QA 通道。 + - 该 QA 主机目前仅供仓库 / 开发环境使用。打包后的 OpenClaw 安装不附带 `qa-lab`，因此也不会暴露 `openclaw qa`。 - 仓库 checkout 会直接加载内置运行器；不需要单独安装插件。 - - 预配三个临时 Matrix 用户（`driver`、`sut`、`observer`）和一个私有房间，然后启动一个 QA gateway 子进程，使用真实 Matrix 插件作为 SUT 传输层。 - - 默认使用固定的稳定版 Tuwunel 镜像 `ghcr.io/matrix-construct/tuwunel:v1.5.1`。当你需要测试不同镜像时，可使用 `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` 覆盖。 - - Matrix 不暴露共享 credential-source 标志，因为该通道会在本地预配一次性用户。 - - 会在 `.artifacts/qa-e2e/...` 下写入 Matrix QA 报告、摘要、observed-events 工件，以及合并后的 stdout / stderr 输出日志。 + - 配置三个临时 Matrix 用户（`driver`、`sut`、`observer`）和一个私有房间，然后启动一个使用真实 Matrix 插件作为 SUT 传输层的 QA gateway 子进程。 + - 默认使用固定的稳定 Tuwunel 镜像 `ghcr.io/matrix-construct/tuwunel:v1.5.1`。如需测试其他镜像，可通过 `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` 覆盖。 + - Matrix 不暴露共享的凭证来源标志，因为该通道会在本地配置一次性用户。 + - 将 Matrix QA 报告、摘要、observed-events 工件以及合并后的 stdout / stderr 输出日志写入 `.artifacts/qa-e2e/...`。 - `pnpm openclaw qa telegram` - - 使用 env 中的 driver 和 SUT bot token，针对一个真实私有群组运行 Telegram live QA 通道。 - - 需要 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` 和 `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`。群组 id 必须是 Telegram chat 的数字 id。 - - 支持 `--credential-source convex` 以使用共享池化凭证。默认使用 env 模式，或设置 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` 以启用池化租约。 - - 任一场景失败时以非零状态退出。当你希望生成工件但不希望退出码失败时，使用 `--allow-failures`。 - - 需要同一个私有群组中的两个不同 bot，且 SUT bot 需要暴露 Telegram 用户名。 - - 为了稳定观察 bot 到 bot 通信，请在 `@BotFather` 中为两个 bot 启用 Bot-to-Bot Communication Mode，并确保 driver bot 可以观察群组中的 bot 流量。 - - 会在 `.artifacts/qa-e2e/...` 下写入 Telegram QA 报告、摘要和 observed-messages 工件。回复场景包含从 driver 发送请求到观察到 SUT 回复之间的 RTT。 + - 使用来自环境变量的 driver 和 SUT 机器人令牌，在真实私有群组上运行 Telegram 实时 QA 通道。 + - 需要 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` 和 `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`。群组 id 必须是 Telegram 聊天的数字 id。 + - 支持 `--credential-source convex` 以使用共享凭证池。默认使用 env 模式，或设置 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` 以选择使用池化租约。 + - 任一场景失败时以非零退出。若你希望生成工件但不返回失败退出码，请使用 `--allow-failures`。 + - 需要两个不同的机器人位于同一个私有群组中，并且 SUT 机器人需暴露 Telegram 用户名。 + - 为了实现稳定的 bot-to-bot 观察，请在 `@BotFather` 中为两个机器人都启用 Bot-to-Bot Communication Mode，并确保 driver 机器人能够观察群组中的机器人流量。 + - 将 Telegram QA 报告、摘要和 observed-messages 工件写入 `.artifacts/qa-e2e/...`。回复类场景还会包含从 driver 发送请求到观察到 SUT 回复之间的 RTT。 -live 传输通道共享一个标准契约，从而避免新传输层发生漂移： +实时传输通道共享同一个标准契约，以避免新传输方式发生漂移： -`qa-channel` 仍然是广泛的合成 QA 测试套件，不属于 live 传输覆盖矩阵的一部分。 +`qa-channel` 仍是范围广泛的合成 QA 套件，不属于实时传输覆盖矩阵的一部分。 -| 通道 | Canary | Mention gating | Allowlist block | 顶层回复 | 重启恢复 | 线程跟进 | 线程隔离 | 反应观察 | 帮助命令 | +| 通道 | Canary | 提及门禁 | 允许列表阻止 | 顶层回复 | 重启恢复 | 线程跟进 | 线程隔离 | 反应观察 | 帮助命令 | | -------- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | | Matrix | x | x | x | x | x | x | x | x | | | Telegram | x | | | | | | | | x | ### 通过 Convex 共享 Telegram 凭证（v1） -当为 `openclaw qa telegram` 启用 `--credential-source convex`（或 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）时，QA lab 会从 Convex 支持的池中获取一个独占租约，在通道运行期间为该租约发送 heartbeat，并在关闭时释放该租约。 +当为 `openclaw qa telegram` 启用 `--credential-source convex`（或 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）时，QA lab 会从 Convex 支持的池中获取一个独占租约，在该通道运行期间持续发送该租约的心跳，并在关闭时释放租约。 参考用 Convex 项目脚手架： - `qa/convex-credential-broker/` -必需的环境变量： +所需环境变量： - `OPENCLAW_QA_CONVEX_SITE_URL`（例如 `https://your-deployment.convex.site`） -- 为所选角色提供一个 secret： - - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` 用于 `maintainer` - - `OPENCLAW_QA_CONVEX_SECRET_CI` 用于 `ci` +- 为所选角色提供一个密钥： + - `maintainer` 使用 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` + - `ci` 使用 `OPENCLAW_QA_CONVEX_SECRET_CI` - 凭证角色选择： - CLI：`--credential-role maintainer|ci` - - env 默认值：`OPENCLAW_QA_CREDENTIAL_ROLE`（在 CI 中默认是 `ci`，否则是 `maintainer`） + - 环境默认值：`OPENCLAW_QA_CREDENTIAL_ROLE`（在 CI 中默认是 `ci`，其他情况下默认是 `maintainer`） 可选环境变量： @@ -131,14 +135,15 @@ live 传输通道共享一个标准契约，从而避免新传输层发生漂移 - `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS`（默认 `90000`） - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS`（默认 `15000`） - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX`（默认 `/qa-credentials/v1`） -- `OPENCLAW_QA_CREDENTIAL_OWNER_ID`（可选 trace id） +- `OPENCLAW_QA_CREDENTIAL_OWNER_ID`（可选追踪 id） - `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` 允许在仅限本地开发时使用 loopback `http://` Convex URL。 -`OPENCLAW_QA_CONVEX_SITE_URL` 在正常运行中应使用 `https://`。 +正常运行时，`OPENCLAW_QA_CONVEX_SITE_URL` 应使用 `https://`。 -维护者管理命令（池添加 / 删除 / 列表）必须明确使用 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`。 +维护者管理命令（池添加 / 删除 / 列表）必须明确使用 +`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`。 -供维护者使用的 CLI 辅助命令： +面向维护者的 CLI 辅助命令： ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -146,85 +151,85 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -在脚本和 CI 工具中使用 `--json` 可获得机器可读输出。 +在脚本和 CI 工具中，使用 `--json` 获取机器可读输出。 默认端点契约（`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`）： - `POST /acquire` - 请求：`{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` - 成功：`{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` - - 池已耗尽 / 可重试：`{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` + - 耗尽 / 可重试：`{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - 请求：`{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - - 成功：`{ status: "ok" }`（或空 `2xx`） + - 成功：`{ status: "ok" }`（或空的 `2xx`） - `POST /release` - 请求：`{ kind, ownerId, actorRole, credentialId, leaseToken }` - - 成功：`{ status: "ok" }`（或空 `2xx`） -- `POST /admin/add`（仅 maintainer secret） + - 成功：`{ status: "ok" }`（或空的 `2xx`） +- `POST /admin/add`（仅限 maintainer 密钥） - 请求：`{ kind, actorId, payload, note?, status? }` - 成功：`{ status: "ok", credential }` -- `POST /admin/remove`（仅 maintainer secret） +- `POST /admin/remove`（仅限 maintainer 密钥） - 请求：`{ credentialId, actorId }` - 成功：`{ status: "ok", changed, credential }` - 活跃租约保护：`{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list`（仅 maintainer secret） +- `POST /admin/list`（仅限 maintainer 密钥） - 请求：`{ kind?, status?, includePayload?, limit? }` - 成功：`{ status: "ok", credentials, count }` -Telegram 类型的负载结构： +Telegram 类型的 payload 结构： - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` 必须是 Telegram chat id 的数字字符串。 -- `admin/add` 会为 `kind: "telegram"` 验证此结构，并拒绝格式错误的负载。 +- `groupId` 必须是 Telegram 聊天数字 id 的字符串。 +- `admin/add` 会对 `kind: "telegram"` 验证该结构，并拒绝格式错误的 payload。 ### 向 QA 添加一个渠道 -向 markdown QA 系统添加一个渠道，严格来说只需要两样东西： +要将一个渠道添加到 Markdown QA 系统中，必须且只需要两样东西： 1. 该渠道的传输适配器。 -2. 一个用于验证该渠道契约的场景包。 +2. 一组用于验证该渠道契约的场景包。 -当共享的 `qa-lab` 宿主能够承载该流程时，不要新增顶层 QA 命令根。 +当共享的 `qa-lab` 主机可以承载该流程时，不要新增一个顶层 QA 命令根。 -`qa-lab` 负责共享宿主机制： +`qa-lab` 负责共享主机机制： - `openclaw qa` 命令根 -- 测试套件启动与关闭 +- 测试套件启动和拆除 - worker 并发 - 工件写入 - 报告生成 - 场景执行 -- 对旧版 `qa-channel` 场景的兼容别名 +- 面向旧版 `qa-channel` 场景的兼容别名 运行器插件负责传输契约： -- `openclaw qa ` 如何挂载到共享的 `qa` 根下 -- 如何为该传输配置 gateway +- 如何将 `openclaw qa ` 挂载到共享 `qa` 根下 +- 如何为该传输配置 Gateway 网关 - 如何检查就绪状态 - 如何注入入站事件 - 如何观察出站消息 -- 如何暴露 transcript 和规范化后的传输状态 +- 如何公开转录记录和规范化后的传输状态 - 如何执行基于传输的操作 - 如何处理传输特定的重置或清理 新渠道的最低接入门槛是： -1. 保持 `qa-lab` 作为共享 `qa` 根的所有者。 -2. 在共享的 `qa-lab` 宿主接缝上实现传输运行器。 -3. 将传输特定机制保留在运行器插件或渠道测试框架中。 +1. 保持由 `qa-lab` 作为共享 `qa` 根的所有者。 +2. 在共享的 `qa-lab` 主机接缝上实现该传输运行器。 +3. 将传输特定机制保留在运行器插件或渠道 harness 内部。 4. 将运行器挂载为 `openclaw qa `，而不是注册一个相互竞争的根命令。 - 运行器插件应在 `openclaw.plugin.json` 中声明 `qaRunners`，并从 `runtime-api.ts` 导出匹配的 `qaRunnerCliRegistrations` 数组。 - 保持 `runtime-api.ts` 足够轻量；惰性 CLI 和运行器执行应放在独立入口点之后。 -5. 在主题化的 `qa/scenarios/` 目录下编写或改造 markdown 场景。 -6. 为新场景使用通用场景辅助函数。 -7. 除非仓库正在进行有意的迁移，否则应保持现有兼容别名继续可用。 + 运行器插件应在 `openclaw.plugin.json` 中声明 `qaRunners`，并在 `runtime-api.ts` 中导出对应的 `qaRunnerCliRegistrations` 数组。 + 保持 `runtime-api.ts` 轻量；惰性 CLI 和运行器执行应放在独立入口点之后。 +5. 在按主题组织的 `qa/scenarios/` 目录下编写或改造 Markdown 场景。 +6. 对新场景使用通用场景辅助函数。 +7. 保持现有兼容别名继续可用，除非仓库正在进行有意的迁移。 -决策规则非常严格： +决策规则很严格： -- 如果某个行为可以在 `qa-lab` 中一次性表达，就把它放进 `qa-lab`。 -- 如果某个行为依赖单一渠道传输，就把它保留在该运行器插件或插件测试框架中。 -- 如果某个场景需要多个渠道都可复用的新能力，就添加一个通用辅助函数，而不是在 `suite.ts` 中加入渠道特定分支。 -- 如果某个行为只对一种传输有意义，就保持该场景为传输特定，并在场景契约中明确说明。 +- 如果某个行为可以在 `qa-lab` 中统一表达一次，就放到 `qa-lab` 中。 +- 如果某个行为依赖单一渠道传输，就把它保留在该运行器插件或插件 harness 中。 +- 如果某个场景需要一个多个渠道都可使用的新能力，应添加通用辅助函数，而不是在 `suite.ts` 中加入渠道特定分支。 +- 如果某个行为只对一种传输有意义，就让该场景保持传输特定，并在场景契约中明确这一点。 新场景推荐使用的通用辅助函数名称是： @@ -249,278 +254,281 @@ Telegram 类型的负载结构： - `formatConversationTranscript` - `resetBus` -新的渠道工作应使用这些通用辅助函数名称。 -兼容别名的存在是为了避免一次性强制迁移，而不是作为新场景编写的范式。 +新的渠道工作应使用通用辅助函数名称。 +兼容别名的存在是为了避免一次性迁移，而不是作为新场景编写的范式。 ## 测试套件（各自运行位置） -可以把这些测试套件理解为“真实性逐步提高”（同时波动性 / 成本也逐步提高）： +可以将这些测试套件理解为“真实度逐步提升”（同时不稳定性 / 成本也逐步上升）： -### Unit / integration（默认） +### 单元 / 集成（默认） - 命令：`pnpm test` -- 配置：未定向运行使用 `vitest.full-*.config.ts` 分片集，并且可能会将多项目分片展开为按项目划分的配置，以便并行调度 -- 文件：核心 / unit 清单位于 `src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts`，以及 `vitest.unit.config.ts` 覆盖的白名单 `ui` node 测试 +- 配置：未定向运行使用 `vitest.full-*.config.ts` 分片集，并可能将多项目分片展开为按项目划分的配置，以便并行调度 +- 文件：位于 `src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts` 下的 core / unit 清单，以及 `vitest.unit.config.ts` 覆盖的白名单 `ui` node 测试 - 范围： - 纯单元测试 - - 进程内集成测试（gateway 认证、路由、工具、解析、配置） - - 已知 bug 的确定性回归测试 + - 进程内集成测试（Gateway 网关认证、路由、工具、解析、配置） + - 针对已知缺陷的确定性回归测试 - 预期： - 在 CI 中运行 - 不需要真实密钥 - 应该快速且稳定 - - 未定向的 `pnpm test` 会运行 12 个更小的分片配置（`core-unit-fast`、`core-unit-src`、`core-unit-security`、`core-unit-ui`、`core-unit-support`、`core-support-boundary`、`core-contracts`、`core-bundled`、`core-runtime`、`agentic`、`auto-reply`、`extensions`），而不是启动一个巨大的原生根项目进程。这样可以降低高负载机器上的 RSS 峰值，并避免 auto-reply / extension 工作拖慢无关测试套件。 - `pnpm test --watch` 仍然使用原生根 `vitest.config.ts` 项目图，因为多分片的 watch 循环并不现实。 - `pnpm test`、`pnpm test:watch` 和 `pnpm test:perf:imports` 会优先通过作用域通道处理显式文件 / 目录目标，因此 `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` 不必承担完整根项目启动的成本。 - 当 diff 只触及可路由的源码 / 测试文件时，`pnpm test:changed` 会将变更的 git 路径展开到相同的作用域通道；配置 / setup 修改仍会回退到更广泛的根项目重跑。 - `pnpm check:changed` 是处理小范围工作的标准智能本地门禁。它会将 diff 归类为核心、核心测试、extensions、extension 测试、apps、文档、发布元数据和工具，然后运行匹配的 typecheck / lint / test 通道。公开的插件 SDK 和插件契约变更会包含 extension 验证，因为 extensions 依赖这些核心契约。仅包含发布元数据版本变更的修改会运行定向的版本 / 配置 / 根依赖检查，而不是完整测试套件，并带有一个守卫，用于拒绝顶层版本字段以外的 package 变更。 - 来自 agents、commands、plugins、auto-reply 辅助函数、`plugin-sdk` 以及类似纯工具区域的 import 较轻的单元测试，会通过 `unit-fast` 通道运行，该通道会跳过 `test/setup-openclaw-runtime.ts`；有状态 / 运行时较重的文件则保留在现有通道中。 - 某些选定的 `plugin-sdk` 和 `commands` 辅助源码文件，在 changed 模式运行时也会映射到这些轻量通道中的显式同级测试，因此辅助函数修改无需为该目录重跑完整的重型测试套件。 - `auto-reply` 具有三个专用桶：顶层核心辅助函数、顶层 `reply.*` 集成测试，以及 `src/auto-reply/reply/**` 子树。这让最重的 reply 测试框架工作不会影响便宜的状态 / chunk / token 测试。 + - 未定向的 `pnpm test` 运行的是十二个更小的分片配置（`core-unit-fast`、`core-unit-src`、`core-unit-security`、`core-unit-ui`、`core-unit-support`、`core-support-boundary`、`core-contracts`、`core-bundled`、`core-runtime`、`agentic`、`auto-reply`、`extensions`），而不是一个巨大的原生根项目进程。这样可以降低高负载机器上的峰值 RSS，并避免 auto-reply / extension 工作拖慢无关的测试套件。 - `pnpm test --watch` 仍然使用原生根 `vitest.config.ts` 项目图，因为多分片 watch 循环并不现实。 - `pnpm test`、`pnpm test:watch` 和 `pnpm test:perf:imports` 现在会优先通过定向通道处理显式文件 / 目录目标，因此 `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` 不必承担完整根项目启动的成本。 - 当变更仅涉及可路由的源文件 / 测试文件时，`pnpm test:changed` 会将变更后的 git 路径展开到相同的定向通道；配置 / setup 编辑仍会回退到更广泛的根项目重跑。 - `pnpm check:changed` 是针对小范围工作常规使用的智能本地门禁。它会将 diff 分类到 core、core 测试、extensions、extension 测试、apps、docs、发布元数据和工具中，然后运行对应的 typecheck / lint / 测试通道。公共插件 SDK 和插件契约变更会包含 extension 验证，因为 extensions 依赖这些 core 契约。仅包含发布元数据的版本提升会运行定向版本 / 配置 / 根依赖检查，而不是完整套件，并带有一个保护措施，用于拒绝顶层 version 字段之外的 package 变更。 - 来自 agents、commands、plugins、auto-reply 辅助函数、`plugin-sdk` 以及类似纯工具区域的轻导入单元测试会走 `unit-fast` 通道，该通道会跳过 `test/setup-openclaw-runtime.ts`；有状态 / 运行时较重的文件则保留在现有通道中。 - 部分 `plugin-sdk` 和 `commands` 辅助源文件在 changed 模式下也会映射到这些轻量通道中的显式同级测试，因此辅助函数编辑无需为该目录重跑整套重型测试。 - `auto-reply` 有三个专用桶：顶层 core 辅助函数、顶层 `reply.*` 集成测试，以及 `src/auto-reply/reply/**` 子树。这能让最重的 reply harness 工作不影响廉价的状态 / 分块 / token 测试。 - - 当你修改消息工具发现输入或压缩运行时上下文时，要同时保留这两个层级的覆盖。 - - 为纯路由与规范化边界添加聚焦的辅助函数回归测试。 + - 当你修改消息工具发现输入或压缩运行时上下文时，要同时保持两个层级的覆盖。 + - 为纯路由和规范化边界添加聚焦的辅助函数回归测试。 - 保持嵌入式运行器集成测试套件健康： `src/agents/pi-embedded-runner/compact.hooks.test.ts`、 `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` 和 `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`。 - - 这些测试套件会验证作用域 id 和压缩行为仍然通过真实的 `run.ts` / `compact.ts` 路径流动；仅有辅助函数测试不足以替代这些集成路径。 + - 这些测试套件会验证带作用域的 id 和压缩行为仍然会流经真实的 `run.ts` / `compact.ts` 路径；仅有辅助函数测试并不足以替代这些集成路径。 - 基础 Vitest 配置默认使用 `threads`。 - - 共享 Vitest 配置固定 `isolate: false`，并在根项目、e2e 和 live 配置中使用非隔离运行器。 - - 根 UI 通道保留其 `jsdom` setup 和 optimizer，但也运行在共享的非隔离运行器上。 + - 共享 Vitest 配置固定 `isolate: false`，并在根项目、e2e 和实时配置中使用非隔离运行器。 + - 根 UI 通道保留其 `jsdom` setup 和优化器，但同样运行在共享的非隔离运行器上。 - 每个 `pnpm test` 分片都从共享 Vitest 配置继承相同的 `threads` + `isolate: false` 默认值。 - - `scripts/run-vitest.mjs` 默认会为 Vitest 子 Node 进程添加 `--no-maglev`，以减少大型本地运行期间的 V8 编译抖动。设置 `OPENCLAW_VITEST_ENABLE_MAGLEV=1` 可与原生 V8 行为进行对比。 + - `scripts/run-vitest.mjs` 默认会为 Vitest 子 Node 进程添加 `--no-maglev`，以减少大型本地运行中的 V8 编译抖动。 + 设置 `OPENCLAW_VITEST_ENABLE_MAGLEV=1` 可与原生 V8 行为进行对比。 - - `pnpm changed:lanes` 会显示某个 diff 触发了哪些架构通道。 - - pre-commit hook 会在 staged 格式化 / lint 之后运行 `pnpm check:changed --staged`，因此纯核心提交不会承担 extension 测试成本，除非它们触及面向 extension 的公开契约。仅发布元数据的提交会保留在定向版本 / 配置 / 根依赖通道中。 - - 如果完全相同的 staged 变更集已经通过同等或更强的门禁验证，可使用 `scripts/committer --fast "" ` 仅跳过 changed-scope hook 的重跑。staged format / lint 仍会运行。在交接中请说明已完成的门禁。这也适用于隔离的偶发 hook 失败在重跑并通过且具有作用域证明之后。 - - `pnpm test:changed` 会在变更路径可以清晰映射到更小测试套件时，通过作用域通道运行。 + - `pnpm changed:lanes` 会显示某个 diff 会触发哪些架构通道。 + - pre-commit hook 会在已暂存格式化 / lint 之后运行 `pnpm check:changed --staged`，因此纯 core 提交无需承担 extension 测试成本，除非它们触及面向 extension 的公共契约。仅发布元数据提交会保留在定向的版本 / 配置 / 根依赖通道中。 + - 如果完全相同的已暂存变更集已经通过同等或更强的门禁验证，可使用 + `scripts/committer --fast "" ` 仅跳过 changed-scope hook 的重复运行。已暂存的 format / lint 仍会运行。请在交接中说明已完成的门禁。这也适用于 isolated flaky hook 故障被重跑并以定向证据通过之后。 + - `pnpm test:changed` 会在变更路径能明确映射到更小测试套件时，通过定向通道运行。 - `pnpm test:max` 和 `pnpm test:changed:max` 保持相同的路由行为，只是使用更高的 worker 上限。 - - 本地 worker 自动扩缩策略刻意较为保守，并会在宿主 load average 已经很高时回退，因此默认情况下多个并发 Vitest 运行造成的影响会更小。 - - 基础 Vitest 配置将项目 / 配置文件标记为 `forceRerunTriggers`，从而确保测试接线变更时 changed 模式重跑仍然正确。 - - 该配置会在受支持宿主上保持启用 `OPENCLAW_VITEST_FS_MODULE_CACHE`；如果你想为直接性能分析指定一个显式缓存位置，可设置 `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`。 + - 本地 worker 自动扩缩容故意保持保守，当主机负载平均值已较高时会回退，因此默认情况下多个并发 Vitest 运行造成的影响更小。 + - 基础 Vitest 配置会将项目 / 配置文件标记为 `forceRerunTriggers`，从而保证当测试接线变更时，changed 模式重跑仍然正确。 + - 在受支持的主机上，配置会保持启用 `OPENCLAW_VITEST_FS_MODULE_CACHE`；如果你想为直接分析指定一个显式缓存位置，可设置 `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`。 - - `pnpm test:perf:imports` 会启用 Vitest import-duration 报告以及 import-breakdown 输出。 - - `pnpm test:perf:imports:changed` 会将相同的性能分析视图限定到自 `origin/main` 以来发生变更的文件。 - - `pnpm test:perf:changed:bench -- --ref ` 会针对该已提交 diff，对路由后的 `test:changed` 与原生根项目路径进行比较，并输出 wall time 和 macOS 最大 RSS。 - - `pnpm test:perf:changed:bench -- --worktree` 会通过将变更文件列表路由到 `scripts/test-projects.mjs` 和根 Vitest 配置，对当前未提交工作树进行基准测试。 - - `pnpm test:perf:profile:main` 会为 Vitest / Vite 启动和 transform 开销写入主线程 CPU profile。 - - `pnpm test:perf:profile:runner` 会在禁用文件级并行的情况下，为 unit 测试套件写入运行器 CPU + heap profile。 + - `pnpm test:perf:imports` 会启用 Vitest 导入时长报告以及导入拆解输出。 + - `pnpm test:perf:imports:changed` 会将同一分析视图限定到自 `origin/main` 以来发生变更的文件。 + - `pnpm test:perf:changed:bench -- --ref ` 会针对该已提交 diff，将定向 `test:changed` 与原生根项目路径进行比较，并输出墙钟时间和 macOS 最大 RSS。 + - `pnpm test:perf:changed:bench -- --worktree` 会通过将变更文件列表路由到 + `scripts/test-projects.mjs` 和根 Vitest 配置，对当前脏工作树进行基准测试。 + - `pnpm test:perf:profile:main` 会为 Vitest / Vite 启动和转换开销写入主线程 CPU profile。 + - `pnpm test:perf:profile:runner` 会在禁用文件并行的情况下，为单元测试套件写入运行器 CPU + 堆 profile。 -### 稳定性（gateway） +### 稳定性（Gateway 网关） - 命令：`pnpm test:stability:gateway` -- 配置：`vitest.gateway.config.ts`，强制单 worker +- 配置：`vitest.gateway.config.ts`，强制使用一个 worker - 范围： - - 启动一个真实的 loopback Gateway 网关，默认启用 diagnostics - - 通过诊断事件路径驱动合成的 gateway 消息、内存和大负载抖动 + - 启动一个默认启用诊断的真实 loopback Gateway 网关 + - 通过诊断事件路径驱动合成的 Gateway 网关消息、内存和大负载抖动 - 通过 Gateway 网关 WS RPC 查询 `diagnostics.stability` - 覆盖诊断稳定性 bundle 持久化辅助函数 - - 断言 recorder 保持有界，合成 RSS 样本保持在压力预算以下，并且每个会话的队列深度会回落到零 + - 断言记录器保持有界、合成 RSS 采样保持在压力预算以下，并且按会话划分的队列深度能够回落到零 - 预期： - 对 CI 安全且不需要密钥 - - 用于稳定性回归跟进的窄通道，不替代完整 Gateway 网关 测试套件 + - 这是用于稳定性回归跟进的窄通道，不是完整 Gateway 网关测试套件的替代品 -### E2E（gateway 冒烟） +### E2E（Gateway 网关冒烟） - 命令：`pnpm test:e2e` - 配置：`vitest.e2e.config.ts` -- 文件：`src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts`，以及 `extensions/` 下内置插件的 E2E 测试 +- 文件：`src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts`，以及 `extensions/` 下的内置插件 E2E 测试 - 运行时默认值： - 使用 Vitest `threads` 且 `isolate: false`，与仓库其余部分保持一致。 - 使用自适应 worker（CI：最多 2 个，本地：默认 1 个）。 - - 默认以静默模式运行，以减少控制台 I/O 开销。 -- 有用的覆盖项： - - `OPENCLAW_E2E_WORKERS=` 可强制指定 worker 数量（上限为 16）。 - - `OPENCLAW_E2E_VERBOSE=1` 可重新启用详细控制台输出。 + - 默认以静默模式运行，以降低控制台 I/O 开销。 +- 常用覆盖项： + - `OPENCLAW_E2E_WORKERS=`：强制指定 worker 数量（上限为 16）。 + - `OPENCLAW_E2E_VERBOSE=1`：重新启用详细控制台输出。 - 范围： - - 多实例 gateway 端到端行为 - - WebSocket / HTTP 接口、节点配对以及更重型的网络交互 + - 多实例 Gateway 网关端到端行为 + - WebSocket / HTTP 表面、节点配对以及更重的网络交互 - 预期： - - 会在 CI 中运行（当在流水线中启用时） + - 会在 CI 中运行（当流水线启用时） - 不需要真实密钥 - - 比单元测试包含更多活动部件（可能更慢） + - 比单元测试包含更多活动部件（因此可能更慢） ### E2E：OpenShell 后端冒烟测试 - 命令：`pnpm test:e2e:openshell` - 文件：`extensions/openshell/src/backend.e2e.test.ts` - 范围： - - 通过 Docker 在宿主机上启动一个隔离的 OpenShell gateway - - 从一个临时本地 Dockerfile 创建沙箱 - - 通过真实的 `sandbox ssh-config` + SSH exec 运行 OpenClaw 的 OpenShell 后端 - - 通过沙箱 fs bridge 验证远程规范化文件系统行为 + - 通过 Docker 在主机上启动一个隔离的 OpenShell Gateway 网关 + - 从一个临时本地 Dockerfile 创建一个沙箱 + - 通过真实的 `sandbox ssh-config` + SSH exec 练习 OpenClaw 的 OpenShell 后端 + - 通过沙箱 fs 桥验证远程规范文件系统行为 - 预期： - 仅按需启用；不属于默认的 `pnpm test:e2e` 运行 - - 需要本地 `openshell` CLI 和可用的 Docker daemon - - 使用隔离的 `HOME` / `XDG_CONFIG_HOME`，然后销毁测试 gateway 和沙箱 -- 有用的覆盖项： - - `OPENCLAW_E2E_OPENSHELL=1`：在手动运行更广泛的 e2e 测试套件时启用该测试 - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`：指向非默认 CLI 二进制或包装脚本 + - 需要本地 `openshell` CLI 和一个可工作的 Docker daemon + - 使用隔离的 `HOME` / `XDG_CONFIG_HOME`，然后销毁测试 Gateway 网关和沙箱 +- 常用覆盖项： + - `OPENCLAW_E2E_OPENSHELL=1`：在手动运行更大范围的 e2e 套件时启用该测试 + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`：指向非默认 CLI 二进制文件或包装脚本 -### Live（真实提供商 + 真实模型） +### 实时测试（真实提供商 + 真实模型） - 命令：`pnpm test:live` - 配置：`vitest.live.config.ts` -- 文件：`src/**/*.live.test.ts`、`test/**/*.live.test.ts`，以及 `extensions/` 下内置插件的 live 测试 +- 文件：`src/**/*.live.test.ts`、`test/**/*.live.test.ts`，以及 `extensions/` 下的内置插件实时测试 - 默认：由 `pnpm test:live` **启用**（设置 `OPENCLAW_LIVE_TEST=1`） - 范围： - - “这个提供商 / 模型在 _今天_ 搭配真实凭证是否真的可用？” - - 捕获提供商格式变化、工具调用怪癖、认证问题以及速率限制行为 + - “这个提供商 / 模型**今天**在真实凭证下是否真的可用？” + - 捕获提供商格式变更、工具调用怪异行为、认证问题和速率限制行为 - 预期： - - 按设计不具备 CI 稳定性（真实网络、真实提供商策略、配额、故障） + - 按设计并非 CI 稳定（真实网络、真实提供商策略、配额、故障） - 会花钱 / 消耗速率限制 - - 优先运行收窄后的子集，而不是“一次跑全部” -- live 运行会读取 `~/.profile`，以获取缺失的 API key。 -- 默认情况下，live 运行仍会隔离 `HOME`，并将配置 / 认证材料复制到一个临时测试 home 中，这样 unit fixture 就无法修改你的真实 `~/.openclaw`。 -- 只有在你明确需要 live 测试使用真实 home 目录时，才设置 `OPENCLAW_LIVE_USE_REAL_HOME=1`。 -- `pnpm test:live` 现在默认使用更安静的模式：会保留 `[live] ...` 进度输出，但会隐藏额外的 `~/.profile` 提示，并静默 gateway 启动日志 / Bonjour 杂讯。如果你想恢复完整启动日志，请设置 `OPENCLAW_LIVE_TEST_QUIET=0`。 -- API key 轮换（按提供商区分）：设置 `*_API_KEYS`（逗号 / 分号格式）或 `*_API_KEY_1`、`*_API_KEY_2`（例如 `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`），或通过 `OPENCLAW_LIVE_*_KEY` 进行每次 live 运行覆盖；测试会在遇到速率限制响应时重试。 -- 进度 / heartbeat 输出： - - live 测试套件现在会将进度行输出到 stderr，这样即使 Vitest 控制台捕获较安静，较长的提供商调用期间也能看到活动状态。 - - `vitest.live.config.ts` 会禁用 Vitest 的控制台拦截，因此提供商 / gateway 进度行会在 live 运行期间立即流式输出。 - - 使用 `OPENCLAW_LIVE_HEARTBEAT_MS` 调整 direct-model heartbeat。 - - 使用 `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` 调整 gateway / probe heartbeat。 + - 优先运行缩小范围的子集，而不是“全部” +- 实时运行会读取 `~/.profile`，以补齐缺失的 API 密钥。 +- 默认情况下，实时运行仍会隔离 `HOME`，并将配置 / 认证材料复制到临时测试 home 中，以免单元夹具修改你真实的 `~/.openclaw`。 +- 仅当你明确需要实时测试使用真实 home 目录时，才设置 `OPENCLAW_LIVE_USE_REAL_HOME=1`。 +- `pnpm test:live` 现在默认使用更安静的模式：保留 `[live] ...` 进度输出，但会隐藏额外的 `~/.profile` 提示，并静默 Gateway 网关引导日志 / Bonjour 噪声。如果你想恢复完整启动日志，请设置 `OPENCLAW_LIVE_TEST_QUIET=0`。 +- API 密钥轮换（按提供商区分）：设置 `*_API_KEYS` 为逗号 / 分号格式，或使用 `*_API_KEY_1`、`*_API_KEY_2`（例如 `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`），或通过 `OPENCLAW_LIVE_*_KEY` 进行按实时测试覆盖；测试会在收到速率限制响应时重试。 +- 进度 / 心跳输出： + - 实时测试套件现在会向 stderr 输出进度行，因此即使 Vitest 控制台捕获较安静，长时间运行的提供商调用也能明显看出仍在活动。 + - `vitest.live.config.ts` 会禁用 Vitest 控制台拦截，因此提供商 / Gateway 网关进度行会在实时运行期间立即流出。 + - 使用 `OPENCLAW_LIVE_HEARTBEAT_MS` 调整直接模型心跳。 + - 使用 `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` 调整 Gateway 网关 / 探测心跳。 ## 我应该运行哪个测试套件？ -使用下面的决策表： +请使用下表决策： -- 编辑逻辑 / 测试：运行 `pnpm test`（如果改动很多，再加 `pnpm test:coverage`） -- 触及 gateway 网络 / WS 协议 / 配对：额外运行 `pnpm test:e2e` -- 调试“我的 bot 挂了” / 提供商特定故障 / 工具调用：运行收窄后的 `pnpm test:live` +- 编辑逻辑 / 测试：运行 `pnpm test`（如果改动较多，再运行 `pnpm test:coverage`） +- 触及 Gateway 网关网络 / WS 协议 / 配对：追加运行 `pnpm test:e2e` +- 调试“我的 bot 挂了” / 提供商特定故障 / 工具调用：运行缩小范围的 `pnpm test:live` -## Live：Android 节点能力扫描 +## 实时测试：Android 节点能力扫描 - 测试：`src/gateway/android-node.capabilities.live.test.ts` - 脚本：`pnpm android:test:integration` -- 目标：调用已连接 Android 节点当前公布的**每个命令**，并断言命令契约行为。 +- 目标：调用已连接 Android 节点当前公布的**每一条命令**，并断言命令契约行为。 - 范围： - - 预先准备 / 手动 setup（该测试套件不会安装 / 运行 / 配对 app）。 - - 针对所选 Android 节点逐命令验证 gateway `node.invoke`。 -- 必需的预先 setup： - - Android app 已连接并已与 gateway 配对。 - - app 保持在前台。 - - 已为你希望通过的能力授予权限 / 捕获同意。 + - 依赖预先条件 / 手动设置（该测试套件不会安装 / 运行 / 配对 app）。 + - 针对选定 Android 节点逐条验证 Gateway 网关 `node.invoke`。 +- 所需预先设置： + - Android app 已经连接并配对到 Gateway 网关。 + - App 保持在前台。 + - 已授予你期望通过的能力所需的权限 / 捕获同意。 - 可选目标覆盖项： - `OPENCLAW_ANDROID_NODE_ID` 或 `OPENCLAW_ANDROID_NODE_NAME`。 - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`。 -- 完整 Android setup 细节：[Android App](/zh-CN/platforms/android) +- 完整 Android 设置详情： [Android App](/zh-CN/platforms/android) -## Live：模型冒烟测试（profile keys） +## 实时测试：模型冒烟测试（profile keys） -live 测试拆分为两层，以便我们隔离故障： +实时测试分为两层，这样我们可以隔离故障： -- “Direct model” 告诉我们该提供商 / 模型在给定密钥下是否至少能响应。 -- “Gateway smoke” 告诉我们完整的 gateway + 智能体 流程是否适用于该模型（会话、历史、工具、沙箱策略等）。 +- “直接模型”告诉我们：给定密钥下，提供商 / 模型是否至少能作答。 +- “Gateway 网关冒烟测试”告诉我们：该模型的完整 Gateway 网关 + 智能体管线是否工作正常（会话、历史、工具、沙箱策略等）。 -### 第 1 层：Direct model completion（无 gateway） +### 第 1 层：直接模型补全（无 Gateway 网关） - 测试：`src/agents/models.profiles.live.test.ts` - 目标： - 枚举已发现的模型 - 使用 `getApiKeyForModel` 选择你拥有凭证的模型 - - 为每个模型运行一个小型 completion（并在需要时运行定向回归测试） + - 对每个模型运行一个小型补全（并在需要时运行定向回归） - 启用方式： - `pnpm test:live`（或在直接调用 Vitest 时设置 `OPENCLAW_LIVE_TEST=1`） -- 设置 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，它是 modern 的别名）来实际运行该测试套件；否则它会跳过，以便让 `pnpm test:live` 聚焦于 gateway 冒烟测试 +- 设置 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，是 modern 的别名）才会真正运行该测试套件；否则会跳过，以便让 `pnpm test:live` 聚焦于 Gateway 网关冒烟测试 - 如何选择模型： - - `OPENCLAW_LIVE_MODELS=modern`：运行 modern allowlist（Opus / Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4） - - `OPENCLAW_LIVE_MODELS=all` 是 modern allowlist 的别名 - - 或 `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."`（逗号分隔 allowlist） - - modern / all 扫描默认使用精心挑选的高信号上限；设置 `OPENCLAW_LIVE_MAX_MODELS=0` 可执行完整的 modern 扫描，或设置为正数以使用更小上限。 + - `OPENCLAW_LIVE_MODELS=modern`：运行 modern 允许列表（Opus / Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4） + - `OPENCLAW_LIVE_MODELS=all`：modern 允许列表的别名 + - 或 `OPENCLAW_LIVE_MODELS="openai/gpt-5.5,anthropic/claude-opus-4-6,..."`（逗号分隔允许列表） + - modern / all 扫描默认使用精心挑选的高信号上限；设置 `OPENCLAW_LIVE_MAX_MODELS=0` 可进行穷尽式 modern 扫描，或设置为正数以使用更小上限。 - 如何选择提供商： - - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（逗号分隔 allowlist） + - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（逗号分隔允许列表） - 密钥来源： - - 默认：profile store 和 env 回退值 - - 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制**仅使用 profile store** -- 这个测试存在的原因： - - 将“提供商 API 坏了 / 密钥无效”和“gateway 智能体 流程坏了”分离开来 - - 容纳小而隔离的回归测试（例如：OpenAI Responses / Codex Responses 推理重放 + 工具调用流程） + - 默认：profile 存储和环境变量回退 + - 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 以强制**仅使用 profile 存储** +- 存在意义： + - 将“提供商 API 坏了 / 密钥无效”与“Gateway 网关智能体管线坏了”区分开来 + - 容纳小型、隔离的回归测试（例如：OpenAI Responses / Codex Responses 推理回放 + 工具调用流程） -### 第 2 层：Gateway + dev 智能体 冒烟测试（即 “@openclaw” 实际做的事） +### 第 2 层：Gateway 网关 + dev 智能体冒烟测试（也就是 `@openclaw` 实际在做的事） - 测试：`src/gateway/gateway-models.profiles.live.test.ts` - 目标： - - 启动一个进程内 gateway - - 创建 / 修补一个 `agent:dev:*` 会话（每次运行按模型覆盖） - - 遍历带密钥的模型并断言： - - “有意义”的响应（无工具） - - 真实工具调用可用（read 探针） - - 可选的额外工具探针（exec+read 探针） - - OpenAI 回归路径（仅工具调用 → 后续跟进）持续有效 -- 探针细节（这样你能快速解释故障）： - - `read` 探针：测试会在工作区写入一个 nonce 文件，并要求智能体 `read` 该文件再将 nonce 回显回来。 - - `exec+read` 探针：测试会要求智能体通过 `exec` 将一个 nonce 写入临时文件，再通过 `read` 读回来。 - - 图像探针：测试会附加一个生成的 PNG（猫 + 随机代码），并预期模型返回 `cat `。 + - 启动一个进程内 Gateway 网关 + - 创建 / 修补一个 `agent:dev:*` 会话（每次运行覆盖模型） + - 遍历有密钥的模型并断言： + - 有“有意义的”回复（无工具） + - 真正的工具调用能正常工作（read 探测） + - 可选的额外工具探测（exec + read 探测） + - OpenAI 回归路径（仅工具调用 → 后续跟进）仍然正常 +- 探测细节（便于你快速解释故障）： + - `read` 探测：测试会在工作区写入一个 nonce 文件，并要求智能体 `read` 该文件并回显 nonce。 + - `exec+read` 探测：测试会要求智能体通过 `exec` 将 nonce 写入临时文件，然后再 `read` 回来。 + - 图片探测：测试会附加一个生成的 PNG（猫 + 随机代码），并期望模型返回 `cat `。 - 实现参考：`src/gateway/gateway-models.profiles.live.test.ts` 和 `src/gateway/live-image-probe.ts`。 - 启用方式： - `pnpm test:live`（或在直接调用 Vitest 时设置 `OPENCLAW_LIVE_TEST=1`） - 如何选择模型： - - 默认：modern allowlist（Opus / Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4） - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` 是 modern allowlist 的别名 - - 或设置 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（或逗号列表）进行收窄 - - modern / all gateway 扫描默认使用精心挑选的高信号上限；设置 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` 可执行完整的 modern 扫描，或设置为正数以使用更小上限。 -- 如何选择提供商（避免“OpenRouter 全都跑一遍”）： - - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（逗号分隔 allowlist） -- 工具 + 图像探针在此 live 测试中始终启用： - - `read` 探针 + `exec+read` 探针（工具压力测试） - - 当模型声明支持图像输入时，运行图像探针 - - 流程（高层）： - - 测试生成一个带有 “CAT” + 随机代码的微型 PNG（`src/gateway/live-image-probe.ts`） - - 通过 `agent` 的 `attachments: [{ mimeType: "image/png", content: "" }]` 发送 - - Gateway 网关 将附件解析为 `images[]`（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`） - - 嵌入式智能体向模型转发一条多模态用户消息 - - 断言：回复中包含 `cat` + 该代码（OCR 容错：允许轻微错误） + - 默认：modern 允许列表（Opus / Sonnet 4.6+、GPT-5.x + Codex、Gemini 3、GLM 4.7、MiniMax M2.7、Grok 4） + - `OPENCLAW_LIVE_GATEWAY_MODELS=all`：modern 允许列表的别名 + - 或设置 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（或逗号列表）进行缩小 + - modern / all Gateway 网关扫描默认使用精心挑选的高信号上限；设置 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` 可进行穷尽式 modern 扫描，或设置为正数以使用更小上限。 +- 如何选择提供商（避免“OpenRouter 全部都跑”）： + - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（逗号分隔允许列表） +- 在这个实时测试中，工具 + 图片探测始终开启： + - `read` 探测 + `exec+read` 探测（工具压力测试） + - 当模型声明支持图片输入时，会运行图片探测 + - 流程（高层概述）： + - 测试生成一个带有 “CAT” + 随机代码的极小 PNG（`src/gateway/live-image-probe.ts`） + - 通过 `agent` `attachments: [{ mimeType: "image/png", content: "" }]` 发送 + - Gateway 网关将附件解析为 `images[]`（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`） + - 嵌入式智能体将多模态用户消息转发给模型 + - 断言：回复中包含 `cat` + 代码（OCR 容错：允许轻微错误） -提示：要查看你的机器上可以测试什么（以及精确的 `provider/model` id），请运行： +提示：若要查看你机器上可以测试哪些内容（以及精确的 `provider/model` id），请运行： ```bash openclaw models list openclaw models list --json ``` -## Live：CLI 后端冒烟测试（Claude、Codex、Gemini 或其他本地 CLI） +## 实时测试：CLI 后端冒烟测试（Claude、Codex、Gemini 或其他本地 CLI） - 测试：`src/gateway/gateway-cli-backend.live.test.ts` -- 目标：使用本地 CLI 后端验证 Gateway 网关 + 智能体 流程，而不触碰你的默认配置。 -- 后端特定的冒烟测试默认值位于所属 extension 的 `cli-backend.ts` 定义中。 +- 目标：在不触碰默认配置的情况下，使用本地 CLI 后端验证 Gateway 网关 + 智能体管线。 +- 后端特定的冒烟测试默认值保存在所属扩展的 `cli-backend.ts` 定义中。 - 启用： - `pnpm test:live`（或在直接调用 Vitest 时设置 `OPENCLAW_LIVE_TEST=1`） - `OPENCLAW_LIVE_CLI_BACKEND=1` - 默认值： - - 默认提供商 / 模型：`claude-cli/claude-sonnet-4-6` - - command / args / image 行为来自所属 CLI 后端插件元数据。 + - 默认 provider / model：`claude-cli/claude-sonnet-4-6` + - command / args / 图片行为来自所属 CLI 后端插件元数据。 - 覆盖项（可选）： - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.5"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`：发送真实图像附件（路径会注入到提示中）。 - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`：将图像文件路径作为 CLI 参数传递，而不是通过提示注入。 - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（或 `"list"`）：当设置 `IMAGE_ARG` 时，控制图像参数的传递方式。 + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`：发送真实图片附件（路径会注入到提示词中）。 + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`：将图片文件路径作为 CLI 参数传递，而不是注入提示词。 + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（或 `"list"`）：当设置 `IMAGE_ARG` 时，控制图片参数的传递方式。 - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`：发送第二轮并验证恢复流程。 - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`：禁用默认的 Claude Sonnet -> Opus 同会话连续性探针（当所选模型支持切换目标时，设置为 `1` 可强制启用）。 + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`：禁用默认的 Claude Sonnet -> Opus 同会话连续性探测（当所选模型支持切换目标时，设置为 `1` 可强制启用）。 示例： ```bash OPENCLAW_LIVE_CLI_BACKEND=1 \ - OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4" \ + OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.5" \ pnpm test:live src/gateway/gateway-cli-backend.live.test.ts ``` -Docker 配方： +Docker 用法： ```bash pnpm test:docker:live-cli-backend ``` -单提供商 Docker 配方： +单提供商 Docker 用法： ```bash pnpm test:docker:live-cli-backend:claude @@ -532,27 +540,27 @@ pnpm test:docker:live-cli-backend:gemini 说明： - Docker 运行器位于 `scripts/test-live-cli-backend-docker.sh`。 -- 它会以非 root 的 `node` 用户身份，在仓库 Docker 镜像中运行 live CLI 后端冒烟测试。 -- 它会从所属 extension 解析 CLI 冒烟测试元数据，然后将匹配的 Linux CLI 包（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）安装到可缓存、可写的前缀 `OPENCLAW_DOCKER_CLI_TOOLS_DIR` 中（默认值：`~/.cache/openclaw/docker-cli-tools`）。 -- `pnpm test:docker:live-cli-backend:claude-subscription` 需要可移植的 Claude Code 订阅 OAuth，可通过带有 `claudeAiOauth.subscriptionType` 的 `~/.claude/.credentials.json`，或来自 `claude setup-token` 的 `CLAUDE_CODE_OAUTH_TOKEN` 提供。它会先在 Docker 中验证直接 `claude -p` 可用，然后在不保留 Anthropic API key 环境变量的情况下运行两轮 Gateway 网关 CLI 后端交互。这个订阅通道默认禁用 Claude MCP / 工具和图像探针，因为 Claude 目前会通过额外用量计费来处理第三方 app 使用，而不是使用普通订阅套餐额度。 -- live CLI 后端冒烟测试现在会为 Claude、Codex 和 Gemini 运行相同的端到端流程：文本轮次、图像分类轮次，然后通过 gateway CLI 验证 MCP `cron` 工具调用。 -- Claude 的默认冒烟测试还会将会话从 Sonnet 修补到 Opus，并验证恢复后的会话仍然记得先前的备注。 +- 它会在仓库 Docker 镜像中以非 root 的 `node` 用户运行实时 CLI 后端冒烟测试。 +- 它会从所属扩展解析 CLI 冒烟测试元数据，然后将对应的 Linux CLI 包（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）安装到位于 `OPENCLAW_DOCKER_CLI_TOOLS_DIR` 的可写缓存前缀中（默认：`~/.cache/openclaw/docker-cli-tools`）。 +- `pnpm test:docker:live-cli-backend:claude-subscription` 需要可移植的 Claude Code 订阅 OAuth，可通过带有 `claudeAiOauth.subscriptionType` 的 `~/.claude/.credentials.json`，或来自 `claude setup-token` 的 `CLAUDE_CODE_OAUTH_TOKEN` 提供。它会先在 Docker 中验证直接 `claude -p` 可用，然后在不保留 Anthropic API 密钥环境变量的情况下运行两次 Gateway 网关 CLI 后端轮次。由于 Claude 当前会将第三方 app 使用量路由到额外用量计费，而不是普通订阅套餐额度，因此该订阅通道默认禁用 Claude MCP / 工具和图片探测。 +- 实时 CLI 后端冒烟测试现在会对 Claude、Codex 和 Gemini 运行相同的端到端流程：文本轮次、图片分类轮次，然后通过 gateway CLI 验证 MCP `cron` 工具调用。 +- Claude 的默认冒烟测试还会将会话从 Sonnet 修补为 Opus，并验证恢复后的会话仍记得之前的备注。 -## Live：ACP 绑定冒烟测试（`/acp spawn ... --bind here`） +## 实时测试：ACP 绑定冒烟测试（`/acp spawn ... --bind here`） - 测试：`src/gateway/gateway-acp-bind.live.test.ts` -- 目标：使用一个 live ACP 智能体验证真实的 ACP 会话绑定流程： +- 目标：使用实时 ACP 智能体验证真实的 ACP 对话绑定流程： - 发送 `/acp spawn --bind here` - - 就地绑定一个合成的消息渠道会话 - - 在同一个会话上发送普通后续消息 - - 验证后续消息落入绑定后的 ACP 会话 transcript 中 + - 原地绑定一个合成的消息渠道对话 + - 在同一对话上发送普通后续消息 + - 验证该后续消息落入已绑定的 ACP 会话转录中 - 启用： - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - 默认值： - Docker 中的 ACP 智能体：`claude,codex,gemini` - - 直接 `pnpm test:live ...` 使用的 ACP 智能体：`claude` - - 合成渠道：Slack 风格的私信会话上下文 + - 用于直接 `pnpm test:live ...` 的 ACP 智能体：`claude` + - 合成渠道：Slack 私信风格对话上下文 - ACP 后端：`acpx` - 覆盖项： - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -560,10 +568,10 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_AGENT=gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - - `OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.4` + - `OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.5` - 说明： - - 此通道使用 gateway 的 `chat.send` 接口，并带有仅管理员可用的合成 originating-route 字段，因此测试可以附加消息渠道上下文，而无需假装进行外部投递。 - - 当未设置 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 时，测试会使用内置 `acpx` 插件中为所选 ACP 测试智能体提供的内置智能体注册表。 + - 该通道使用 gateway `chat.send` 表面，并带有仅管理员可用的合成 originating-route 字段，因此测试可以附加消息渠道上下文，而无需假装对外投递。 + - 当未设置 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 时，测试会使用内置 `acpx` 插件的内建智能体注册表来选择 ACP harness 智能体。 示例： @@ -573,13 +581,13 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:live src/gateway/gateway-acp-bind.live.test.ts ``` -Docker 配方： +Docker 用法： ```bash pnpm test:docker:live-acp-bind ``` -单智能体 Docker 配方： +单智能体 Docker 用法： ```bash pnpm test:docker:live-acp-bind:claude @@ -590,30 +598,34 @@ pnpm test:docker:live-acp-bind:gemini Docker 说明： - Docker 运行器位于 `scripts/test-live-acp-bind-docker.sh`。 -- 默认情况下，它会按顺序针对所有受支持的 live CLI 智能体运行 ACP 绑定冒烟测试：`claude`、`codex`，然后是 `gemini`。 -- 使用 `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` 或 `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` 可收窄矩阵。 -- 它会读取 `~/.profile`，将匹配的 CLI 认证材料暂存到容器中，把 `acpx` 安装到可写的 npm 前缀中，然后在缺失时安装所请求的 live CLI（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）。 -- 在 Docker 内部，运行器会设置 `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`，以便 acpx 让来自已读取 profile 的提供商环境变量继续对其子测试 CLI 可用。 +- 默认情况下，它会按顺序针对所有受支持的实时 CLI 智能体运行 ACP 绑定冒烟测试：`claude`、`codex`、然后 `gemini`。 +- 使用 `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` 或 `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` 可缩小矩阵范围。 +- 它会读取 `~/.profile`，将匹配的 CLI 认证材料暂存到容器中，把 `acpx` 安装到可写 npm 前缀中，然后在缺失时安装所请求的实时 CLI（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）。 +- 在 Docker 内，运行器会设置 `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`，以便 acpx 使来自已读取 profile 的提供商环境变量继续对其子 harness CLI 可用。 -## Live：Codex app-server 测试框架冒烟测试 +## 实时测试：Codex app-server harness 冒烟测试 -- 目标：通过常规 gateway `agent` 方法验证插件自有的 Codex 测试框架： +- 目标：通过常规 gateway + `agent` 方法验证插件所属的 Codex harness： - 加载内置 `codex` 插件 - 选择 `OPENCLAW_AGENT_RUNTIME=codex` - - 向 `codex/gpt-5.4` 发送第一轮 gateway 智能体 请求 - - 向同一个 OpenClaw 会话发送第二轮请求，并验证 app-server 线程可以恢复 + - 向 `codex/gpt-5.5` 发送第一条 gateway 智能体轮次 + - 向同一个 OpenClaw 会话发送第二条消息，并验证 app-server + 线程能够恢复 - 通过同一条 gateway 命令路径运行 `/codex status` 和 `/codex models` - - 可选地运行两个经过 Guardian 审核的提权 shell 探针：一个应被批准的无害命令，以及一个应被拒绝并导致智能体回问的伪 secret 上传 + - 可选地运行两个经 Guardian 审核的提权 shell 探测：一个应被批准的无害命令，以及一个应被拒绝的伪密钥上传，从而让智能体回过头来询问 - 测试：`src/gateway/gateway-codex-harness.live.test.ts` - 启用：`OPENCLAW_LIVE_CODEX_HARNESS=1` -- 默认模型：`codex/gpt-5.4` -- 可选图像探针：`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- 可选 MCP / 工具探针：`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- 可选 Guardian 探针：`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` -- 该冒烟测试会设置 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，以确保损坏的 Codex 测试框架不会因静默回退到 PI 而“通过”。 -- 认证：来自 shell / profile 的 `OPENAI_API_KEY`，外加可选复制的 `~/.codex/auth.json` 和 `~/.codex/config.toml` +- 默认模型：`codex/gpt-5.5` +- 可选图片探测：`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- 可选 MCP / 工具探测：`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- 可选 Guardian 探测：`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` +- 该冒烟测试会设置 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，因此损坏的 Codex + harness 不能通过悄悄回退到 PI 而蒙混过关。 +- 认证：来自 shell / profile 的 `OPENAI_API_KEY`，以及可选复制的 + `~/.codex/auth.json` 和 `~/.codex/config.toml` -本地配方： +本地用法： ```bash source ~/.profile @@ -621,11 +633,11 @@ OPENCLAW_LIVE_CODEX_HARNESS=1 \ OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1 \ OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1 \ OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1 \ - OPENCLAW_LIVE_CODEX_HARNESS_MODEL=codex/gpt-5.4 \ + OPENCLAW_LIVE_CODEX_HARNESS_MODEL=codex/gpt-5.5 \ pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts ``` -Docker 配方： +Docker 用法： ```bash source ~/.profile @@ -635,404 +647,415 @@ pnpm test:docker:live-codex-harness Docker 说明： - Docker 运行器位于 `scripts/test-live-codex-harness-docker.sh`。 -- 它会读取挂载的 `~/.profile`，传递 `OPENAI_API_KEY`，在存在时复制 Codex CLI 认证文件，将 `@openai/codex` 安装到一个可写的挂载 npm 前缀中，暂存源码树，然后仅运行 Codex 测试框架 live 测试。 -- Docker 默认启用图像、MCP / 工具和 Guardian 探针。当你需要更窄的调试运行时，可设置 `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` 或 `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` 或 `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`。 -- Docker 还会导出 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，与 live 测试配置保持一致，因此 `openai-codex/*` 或 PI 回退都无法掩盖 Codex 测试框架回归。 +- 它会读取挂载的 `~/.profile`，传递 `OPENAI_API_KEY`，在存在时复制 Codex CLI + 认证文件，将 `@openai/codex` 安装到可写的挂载 npm 前缀中，暂存源代码树，然后只运行 Codex harness 实时测试。 +- Docker 默认启用图片、MCP / 工具和 Guardian 探测。当你需要更窄范围的调试运行时，可设置 + `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` 或 + `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` 或 + `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`。 +- Docker 还会导出 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，与实时 + 测试配置保持一致，因此 `openai-codex/*` 或 PI 回退无法掩盖 Codex harness + 回归问题。 -### 推荐的 live 配方 +### 推荐的实时测试用法 -范围窄、显式的 allowlist 最快，也最不容易波动： +范围窄且明确的允许列表最快、也最不容易不稳定： -- 单模型，direct（无 gateway）： - - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` +- 单模型，直接模式（无 Gateway 网关）： + - `OPENCLAW_LIVE_MODELS="openai/gpt-5.5" pnpm test:live src/agents/models.profiles.live.test.ts` -- 单模型，gateway 冒烟测试： - - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +- 单模型，Gateway 网关冒烟测试： + - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- 多提供商工具调用： - - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +- 多个提供商的工具调用： + - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- 聚焦 Google（Gemini API key + Antigravity）： - - Gemini（API key）：`OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +- Google 聚焦（Gemini API 密钥 + Antigravity）： + - Gemini（API 密钥）：`OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity（OAuth）：`OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` 说明： -- `google/...` 使用 Gemini API（API key）。 -- `google-antigravity/...` 使用 Antigravity OAuth bridge（Cloud Code Assist 风格的智能体端点）。 -- `google-gemini-cli/...` 使用你机器上的本地 Gemini CLI（单独的认证 + 工具怪癖）。 -- Gemini API 与 Gemini CLI： - - API：OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API（API key / profile 认证）；大多数用户所说的 “Gemini” 指的就是这个。 - - CLI：OpenClaw 通过 shell 调用本地 `gemini` 二进制；它有自己的认证，并且行为可能不同（流式传输 / 工具支持 / 版本偏差）。 +- `google/...` 使用 Gemini API（API 密钥）。 +- `google-antigravity/...` 使用 Antigravity OAuth 桥（Cloud Code Assist 风格智能体端点）。 +- `google-gemini-cli/...` 使用你机器上的本地 Gemini CLI（具有独立的认证方式和工具怪异行为）。 +- Gemini API vs Gemini CLI： + - API：OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API（API 密钥 / profile 认证）；这通常是大多数用户所说的 “Gemini”。 + - CLI：OpenClaw 会调用本地 `gemini` 二进制文件；它有自己的认证方式，而且其行为可能不同（流式传输 / 工具支持 / 版本偏差）。 -## Live：模型矩阵（我们覆盖什么） +## 实时测试：模型矩阵（我们覆盖什么） -没有固定的 “CI 模型列表”（live 是按需启用的），但以下是建议在装有密钥的开发机器上定期覆盖的**推荐**模型。 +没有固定的“CI 模型列表”（实时测试是按需启用的），但以下是在带有密钥的开发机上建议定期覆盖的**推荐**模型。 -### 现代冒烟测试集（工具调用 + 图像） +### 现代冒烟测试集（工具调用 + 图片） -这是我们预期应持续可用的“常用模型”运行集： +这是我们期望持续可用的“常见模型”运行集： -- OpenAI（非 Codex）：`openai/gpt-5.4`（可选：`openai/gpt-5.4-mini`） -- OpenAI Codex：`openai-codex/gpt-5.4` +- OpenAI（非 Codex）：`openai/gpt-5.5`（可选：`openai/gpt-5.4-mini`） +- OpenAI Codex：`openai-codex/gpt-5.5` - Anthropic：`anthropic/claude-opus-4-6`（或 `anthropic/claude-sonnet-4-6`） - Google（Gemini API）：`google/gemini-3.1-pro-preview` 和 `google/gemini-3-flash-preview`（避免较旧的 Gemini 2.x 模型） - Google（Antigravity）：`google-antigravity/claude-opus-4-6-thinking` 和 `google-antigravity/gemini-3-flash` - Z.AI（GLM）：`zai/glm-4.7` - MiniMax：`minimax/MiniMax-M2.7` -运行带工具 + 图像的 gateway 冒烟测试： -`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +运行带工具 + 图片的 Gateway 网关冒烟测试： +`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` ### 基线：工具调用（Read + 可选 Exec） 每个提供商家族至少选一个： -- OpenAI：`openai/gpt-5.4`（或 `openai/gpt-5.4-mini`） +- OpenAI：`openai/gpt-5.5`（或 `openai/gpt-5.4-mini`） - Anthropic：`anthropic/claude-opus-4-6`（或 `anthropic/claude-sonnet-4-6`） - Google：`google/gemini-3-flash-preview`（或 `google/gemini-3.1-pro-preview`） - Z.AI（GLM）：`zai/glm-4.7` - MiniMax：`minimax/MiniMax-M2.7` -可选的额外覆盖（有更好，没有也行）： +可选附加覆盖（有则更好）： - xAI：`xai/grok-4`（或最新可用版本） -- Mistral：`mistral/`…（选择一个你已启用、支持工具的模型） +- Mistral：`mistral/`…（选择一个已启用、支持工具的模型） - Cerebras：`cerebras/`…（如果你有访问权限） - LM Studio：`lmstudio/`…（本地；工具调用取决于 API 模式） -### Vision：图像发送（附件 → 多模态消息） +### 视觉：图片发送（附件 → 多模态消息） -在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中至少包含一个支持图像的模型（Claude / Gemini / OpenAI 支持 vision 的变体等），以覆盖图像探针。 +在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中至少包含一个支持图片的模型（Claude / Gemini / OpenAI 支持视觉的变体等），以覆盖图片探测。 ### 聚合器 / 替代 Gateway 网关 -如果你已启用相关密钥，我们也支持通过以下方式测试： +如果你已启用相应密钥，我们也支持通过以下方式测试： -- OpenRouter：`openrouter/...`（数百个模型；使用 `openclaw models scan` 查找支持工具 + 图像的候选） -- OpenCode：`opencode/...` 用于 Zen，`opencode-go/...` 用于 Go（通过 `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY` 认证） +- OpenRouter：`openrouter/...`（数百个模型；使用 `openclaw models scan` 找出支持工具 + 图片的候选） +- OpenCode：Zen 使用 `opencode/...`，Go 使用 `opencode-go/...`（通过 `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY` 认证） -如果你有凭证 / 配置，还可以将更多提供商纳入 live 矩阵： +如果你有凭证 / 配置，也可以将更多提供商纳入实时矩阵： - 内置：`openai`、`openai-codex`、`anthropic`、`google`、`google-vertex`、`google-antigravity`、`google-gemini-cli`、`zai`、`openrouter`、`opencode`、`opencode-go`、`xai`、`groq`、`cerebras`、`mistral`、`github-copilot` -- 通过 `models.providers`（自定义端点）：`minimax`（云端 / API），以及任何兼容 OpenAI / Anthropic 的代理（LM Studio、vLLM、LiteLLM 等） +- 通过 `models.providers`（自定义端点）：`minimax`（云端 / API），以及任意兼容 OpenAI / Anthropic 的代理（LM Studio、vLLM、LiteLLM 等） -提示：不要试图在文档中硬编码“所有模型”。权威列表始终是你的机器上 `discoverModels(...)` 返回的内容，再加上可用密钥所允许的模型。 +提示：不要试图在文档中硬编码“所有模型”。权威列表始终是你机器上 `discoverModels(...)` 返回的结果，以及当前可用的密钥。 -## 凭证（切勿提交） +## 凭证（绝不要提交） -live 测试发现凭证的方式与 CLI 完全相同。实际含义是： +实时测试发现凭证的方式与 CLI 相同。实际含义是： -- 如果 CLI 能用，live 测试通常也应能找到同样的密钥。 -- 如果某个 live 测试提示“没有凭证”，就按你调试 `openclaw models list` / 模型选择的方式来调试。 +- 如果 CLI 能工作，实时测试通常也应能找到相同的密钥。 +- 如果某个实时测试提示“没有凭证”，调试方式应与调试 `openclaw models list` / 模型选择相同。 -- 每个智能体的认证 profile：`~/.openclaw/agents//agent/auth-profiles.json`（这就是 live 测试中 “profile keys” 的含义） +- 按智能体存储的认证配置文件：`~/.openclaw/agents//agent/auth-profiles.json`（这就是实时测试中 “profile keys” 的含义） - 配置：`~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`） -- 旧版状态目录：`~/.openclaw/credentials/`（存在时会复制到 staged live home 中，但它不是主 profile-key 存储） -- 本地 live 运行默认会将当前活动配置、每个智能体的 `auth-profiles.json` 文件、旧版 `credentials/` 以及受支持的外部 CLI 认证目录复制到一个临时测试 home 中；staged live home 会跳过 `workspace/` 和 `sandboxes/`，并移除 `agents.*.workspace` / `agentDir` 路径覆盖，从而让探针不会落到你的真实宿主工作区上。 +- 旧版状态目录：`~/.openclaw/credentials/`（若存在，会被复制到暂存的实时测试 home 中，但它不是主 profile-key 存储） +- 默认情况下，本地实时运行会将当前活动配置、按智能体划分的 `auth-profiles.json` 文件、旧版 `credentials/` 以及受支持的外部 CLI 认证目录复制到临时测试 home 中；暂存的实时测试 home 会跳过 `workspace/` 和 `sandboxes/`，并剥离 `agents.*.workspace` / `agentDir` 路径覆盖项，以确保探测不会触碰你真实主机工作区。 -如果你想依赖环境变量密钥（例如导出在你的 `~/.profile` 中），请在执行本地测试前先运行 `source ~/.profile`，或者使用下面的 Docker 运行器（它们可以将 `~/.profile` 挂载到容器中）。 +如果你想依赖环境变量密钥（例如在你的 `~/.profile` 中导出的密钥），请在运行本地测试前执行 `source ~/.profile`，或者使用下面的 Docker 运行器（它们可以将 `~/.profile` 挂载到容器中）。 -## Deepgram live（音频转录） +## Deepgram 实时测试（音频转录） - 测试：`extensions/deepgram/audio.live.test.ts` - 启用：`DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts` -## BytePlus（国际版） 编码计划 live +## BytePlus（国际版）编码计划实时测试 - 测试：`extensions/byteplus/live.test.ts` - 启用：`BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts` - 可选模型覆盖：`BYTEPLUS_CODING_MODEL=ark-code-latest` -## ComfyUI 工作流媒体 live +## ComfyUI 工作流媒体实时测试 - 测试：`extensions/comfy/comfy.live.test.ts` - 启用：`OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - 范围： - - 覆盖内置 comfy 图像、视频和 `music_generate` 路径 - - 除非配置了 `models.providers.comfy.`，否则会跳过各项能力 + - 覆盖内置 comfy 图片、视频和 `music_generate` 路径 + - 除非配置了 `models.providers.comfy.`，否则会跳过对应能力 - 在修改 comfy 工作流提交、轮询、下载或插件注册后很有用 -## 图像生成 live +## 图片生成实时测试 - 测试：`test/image-generation.runtime.live.test.ts` - 命令：`pnpm test:live test/image-generation.runtime.live.test.ts` -- 测试框架：`pnpm test:live:media image` +- Harness：`pnpm test:live:media image` - 范围： - - 枚举每个已注册的图像生成提供商插件 - - 在探测前从你的登录 shell（`~/.profile`）加载缺失的提供商环境变量 - - 默认优先使用 live / env API key，而不是已存储的认证 profile，这样 `auth-profiles.json` 中陈旧的测试密钥就不会掩盖真实的 shell 凭证 - - 跳过没有可用认证 / profile / 模型的提供商 - - 通过共享运行时能力运行标准图像生成变体： + - 枚举每个已注册的图片生成提供商插件 + - 在探测前，从你的登录 shell（`~/.profile`）加载缺失的提供商环境变量 + - 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的认证配置文件，因此 `auth-profiles.json` 中陈旧的测试密钥不会掩盖真实 shell 凭证 + - 跳过没有可用认证 / 配置文件 / 模型的提供商 + - 通过共享运行时能力运行标准图片生成变体： - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- 当前已覆盖的内置提供商： +- 当前覆盖的内置提供商： - `fal` - `google` - `minimax` - `openai` - `vydra` - `xai` -- 可选收窄： +- 可选缩小范围： - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google,xai"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,xai:default-generate,xai:default-edit"` - 可选认证行为： - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制使用 profile store 认证，并忽略仅 env 提供的覆盖 + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`：强制使用 profile 存储认证，并忽略仅环境变量中的覆盖项 -## 音乐生成 live +## 音乐生成实时测试 - 测试：`extensions/music-generation-providers.live.test.ts` - 启用：`OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` -- 测试框架：`pnpm test:live:media music` +- Harness：`pnpm test:live:media music` - 范围： - 覆盖共享的内置音乐生成提供商路径 - 当前覆盖 Google 和 MiniMax - - 在探测前从你的登录 shell（`~/.profile`）加载提供商环境变量 - - 默认优先使用 live / env API key，而不是已存储的认证 profile，这样 `auth-profiles.json` 中陈旧的测试密钥就不会掩盖真实的 shell 凭证 - - 跳过没有可用认证 / profile / 模型的提供商 - - 在可用时运行两种已声明的运行时模式： - - 使用仅 prompt 输入的 `generate` - - 当提供商声明 `capabilities.edit.enabled` 时运行 `edit` + - 在探测前，从你的登录 shell（`~/.profile`）加载提供商环境变量 + - 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的认证配置文件，因此 `auth-profiles.json` 中陈旧的测试密钥不会掩盖真实 shell 凭证 + - 跳过没有可用认证 / 配置文件 / 模型的提供商 + - 在可用时运行两种声明的运行模式： + - `generate`：仅提示词输入 + - `edit`：当提供商声明 `capabilities.edit.enabled` 时 - 当前共享通道覆盖： - `google`：`generate`、`edit` - `minimax`：`generate` - - `comfy`：单独的 Comfy live 文件，不在这个共享扫描中 -- 可选收窄： + - `comfy`：单独的 Comfy 实时测试文件，不属于此共享扫描 +- 可选缩小范围： - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` - 可选认证行为： - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制使用 profile store 认证，并忽略仅 env 提供的覆盖 + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`：强制使用 profile 存储认证，并忽略仅环境变量中的覆盖项 -## 视频生成 live +## 视频生成实时测试 - 测试：`extensions/video-generation-providers.live.test.ts` - 启用：`OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` -- 测试框架：`pnpm test:live:media video` +- Harness：`pnpm test:live:media video` - 范围： - 覆盖共享的内置视频生成提供商路径 - - 默认使用发布安全的冒烟测试路径：非 FAL 提供商、每个提供商一个文生视频请求、1 秒龙虾 prompt，以及来自 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 的每提供商操作上限（默认 `180000`） - - 默认跳过 FAL，因为提供商侧队列延迟可能主导发布时间；传入 `--video-providers fal` 或 `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` 可显式运行 - - 在探测前从你的登录 shell（`~/.profile`）加载提供商环境变量 - - 默认优先使用 live / env API key，而不是已存储的认证 profile，这样 `auth-profiles.json` 中陈旧的测试密钥就不会掩盖真实的 shell 凭证 - - 跳过没有可用认证 / profile / 模型的提供商 - - 默认仅运行 `generate` - - 设置 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` 后，如果可用，还会运行已声明的 transform 模式： - - 当提供商声明 `capabilities.imageToVideo.enabled`，且所选提供商 / 模型在共享扫描中接受基于 buffer 的本地图像输入时，运行 `imageToVideo` - - 当提供商声明 `capabilities.videoToVideo.enabled`，且所选提供商 / 模型在共享扫描中接受基于 buffer 的本地视频输入时，运行 `videoToVideo` + - 默认采用对发布安全的冒烟测试路径：非 FAL 提供商、每个提供商一次文生视频请求、1 秒龙虾提示词，以及由 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 控制的按提供商操作上限（默认 `180000`） + - 默认跳过 FAL，因为提供商端队列延迟可能主导发布耗时；显式传入 `--video-providers fal` 或 `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` 才会运行它 + - 在探测前，从你的登录 shell（`~/.profile`）加载提供商环境变量 + - 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的认证配置文件，因此 `auth-profiles.json` 中陈旧的测试密钥不会掩盖真实 shell 凭证 + - 跳过没有可用认证 / 配置文件 / 模型的提供商 + - 默认只运行 `generate` + - 设置 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` 后，如有可用，也会运行已声明的转换模式： + - `imageToVideo`：当提供商声明 `capabilities.imageToVideo.enabled`，且所选提供商 / 模型在共享扫描中接受基于 buffer 的本地图像输入时 + - `videoToVideo`：当提供商声明 `capabilities.videoToVideo.enabled`，且所选提供商 / 模型在共享扫描中接受基于 buffer 的本地视频输入时 - 当前在共享扫描中已声明但跳过的 `imageToVideo` 提供商： - - `vydra`，因为内置 `veo3` 仅支持文本，而内置 `kling` 需要远程图像 URL - - 提供商特定的 Vydra 覆盖： + - `vydra`，因为内置 `veo3` 仅支持文本，而内置 `kling` 需要远程图片 URL + - Vydra 特定覆盖： - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - 该文件会运行 `veo3` 文生视频，以及一个默认使用远程图像 URL fixture 的 `kling` 通道 - - 当前 `videoToVideo` live 覆盖： - - 仅 `runway`，且所选模型为 `runway/gen4_aleph` 时 + - 该文件会运行 `veo3` 文生视频，以及默认使用远程图片 URL 夹具的 `kling` 通道 + - 当前 `videoToVideo` 实时覆盖： + - 仅当所选模型为 `runway/gen4_aleph` 时覆盖 `runway` - 当前在共享扫描中已声明但跳过的 `videoToVideo` 提供商： - - `alibaba`、`qwen`、`xai`，因为这些路径目前需要远程 `http(s)` / MP4 参考 URL - - `google`，因为当前共享 Gemini / Veo 通道使用基于本地 buffer 的输入，而共享扫描不接受该路径 - - `openai`，因为当前共享通道无法保证拥有组织特定的视频 inpaint / remix 访问权限 -- 可选收窄： + - `alibaba`、`qwen`、`xai`，因为这些路径当前需要远程 `http(s)` / MP4 参考 URL + - `google`，因为当前共享 Gemini / Veo 通道使用基于本地 buffer 的输入，而该路径在共享扫描中不被接受 + - `openai`，因为当前共享通道缺乏针对组织的稳定视频修补 / remix 访问保障 +- 可选缩小范围： - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` 可将所有提供商都纳入默认扫描，包括 FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` 可在激进冒烟测试运行中缩短每个提供商的操作上限 + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`：在默认扫描中包含所有提供商，包括 FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`：将每个提供商的操作上限降低，用于更激进的冒烟测试运行 - 可选认证行为： - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制使用 profile store 认证，并忽略仅 env 提供的覆盖 + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`：强制使用 profile 存储认证，并忽略仅环境变量中的覆盖项 -## 媒体 live 测试框架 +## 媒体实时测试 Harness - 命令：`pnpm test:live:media` - 目的： - - 通过一个仓库原生入口点运行共享的图像、音乐和视频 live 测试套件 + - 通过一个原生仓库入口点运行共享的图片、音乐和视频实时测试套件 - 自动从 `~/.profile` 加载缺失的提供商环境变量 - - 默认自动将每个测试套件收窄为当前具有可用认证的提供商 - - 复用 `scripts/test-live.mjs`，因此 heartbeat 和 quiet mode 行为保持一致 + - 默认自动将每个测试套件缩小到当前拥有可用认证的提供商 + - 复用 `scripts/test-live.mjs`，因此心跳和安静模式行为保持一致 - 示例： - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Docker 运行器（可选的“可在 Linux 中运行”检查） +## Docker 运行器（可选的“在 Linux 中可用”检查） -这些 Docker 运行器分成两类： +这些 Docker 运行器分为两类： -- live 模型运行器：`test:docker:live-models` 和 `test:docker:live-gateway` 仅在仓库 Docker 镜像中运行各自匹配的 profile-key live 文件（`src/agents/models.profiles.live.test.ts` 和 `src/gateway/gateway-models.profiles.live.test.ts`），会挂载你的本地配置目录和工作区（如果已挂载，也会读取 `~/.profile`）。对应的本地入口点是 `test:live:models-profiles` 和 `test:live:gateway-profiles`。 -- Docker live 运行器默认使用更小的冒烟测试上限，以保证完整 Docker 扫描仍然可行： +- 实时模型运行器：`test:docker:live-models` 和 `test:docker:live-gateway` 只会在仓库 Docker 镜像中运行与之对应的 profile-key 实时测试文件（`src/agents/models.profiles.live.test.ts` 和 `src/gateway/gateway-models.profiles.live.test.ts`），并挂载你的本地配置目录和工作区（如果已挂载，也会读取 `~/.profile`）。对应的本地入口点是 `test:live:models-profiles` 和 `test:live:gateway-profiles`。 +- Docker 实时运行器默认使用更小的冒烟测试上限，以保持完整 Docker 扫描的可行性： `test:docker:live-models` 默认设置 `OPENCLAW_LIVE_MAX_MODELS=12`，而 `test:docker:live-gateway` 默认设置 `OPENCLAW_LIVE_GATEWAY_SMOKE=1`、 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`、 `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`，以及 - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`。当你明确需要更大、更彻底的扫描时，可覆盖这些环境变量。 -- `test:docker:all` 会先通过 `test:docker:live-build` 构建一次 live Docker 镜像，然后在两个 live Docker 通道中复用它。它还会通过 `test:docker:e2e-build` 构建一个共享的 `scripts/e2e/Dockerfile` 镜像，并在执行已构建 app 的 E2E 容器冒烟测试运行器中复用它。 -- 容器冒烟测试运行器：`test:docker:openwebui`、`test:docker:onboard`、`test:docker:npm-onboard-channel-agent`、`test:docker:gateway-network`、`test:docker:mcp-channels`、`test:docker:pi-bundle-mcp-tools`、`test:docker:cron-mcp-cleanup`、`test:docker:plugins`、`test:docker:plugin-update` 和 `test:docker:config-reload` 会启动一个或多个真实容器，并验证更高层级的集成路径。 + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`。当你明确需要更大规模的穷尽扫描时，可覆盖这些环境变量。 +- `test:docker:all` 会先通过 `test:docker:live-build` 构建一次实时 Docker 镜像，然后在两个实时 Docker 通道中复用它。它还会通过 `test:docker:e2e-build` 构建一个共享的 `scripts/e2e/Dockerfile` 镜像，并在对已构建应用进行测试的 E2E 容器冒烟运行器中复用它。 +- 容器冒烟运行器：`test:docker:openwebui`、`test:docker:onboard`、`test:docker:npm-onboard-channel-agent`、`test:docker:gateway-network`、`test:docker:mcp-channels`、`test:docker:pi-bundle-mcp-tools`、`test:docker:cron-mcp-cleanup`、`test:docker:plugins`、`test:docker:plugin-update` 和 `test:docker:config-reload` 会启动一个或多个真实容器，并验证更高层的集成路径。 -live 模型 Docker 运行器还会仅 bind-mount 所需的 CLI 认证 home（如果运行未收窄，则挂载所有受支持的认证 home），然后在运行前将它们复制到容器 home 中，这样外部 CLI OAuth 就可以刷新 token，而不会修改宿主机认证存储： +实时模型 Docker 运行器还只会绑定挂载所需的 CLI 认证 home（如果运行未缩小范围，则挂载所有受支持的），然后在运行前将其复制到容器 home 中，这样外部 CLI OAuth 就能刷新令牌，而不会修改主机上的认证存储： -- Direct model：`pnpm test:docker:live-models`（脚本：`scripts/test-live-models-docker.sh`） +- 直接模型：`pnpm test:docker:live-models`（脚本：`scripts/test-live-models-docker.sh`） - ACP 绑定冒烟测试：`pnpm test:docker:live-acp-bind`（脚本：`scripts/test-live-acp-bind-docker.sh`） - CLI 后端冒烟测试：`pnpm test:docker:live-cli-backend`（脚本：`scripts/test-live-cli-backend-docker.sh`） -- Codex app-server 测试框架冒烟测试：`pnpm test:docker:live-codex-harness`（脚本：`scripts/test-live-codex-harness-docker.sh`） +- Codex app-server harness 冒烟测试：`pnpm test:docker:live-codex-harness`（脚本：`scripts/test-live-codex-harness-docker.sh`） - Gateway 网关 + dev 智能体：`pnpm test:docker:live-gateway`（脚本：`scripts/test-live-gateway-models-docker.sh`） -- Open WebUI live 冒烟测试：`pnpm test:docker:openwebui`（脚本：`scripts/e2e/openwebui-docker.sh`） -- onboarding 向导（TTY，完整脚手架）：`pnpm test:docker:onboard`（脚本：`scripts/e2e/onboard-docker.sh`） -- npm tarball onboarding / 渠道 / 智能体 冒烟测试：`pnpm test:docker:npm-onboard-channel-agent` 会在 Docker 中全局安装打包后的 OpenClaw tarball，通过 env-ref onboarding 配置 OpenAI，并默认配置 Telegram，验证启用插件时会按需安装其运行时依赖，运行 doctor，并执行一次 mock OpenAI 智能体 轮次。可通过 `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 复用预构建 tarball，通过 `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` 跳过宿主重建，或通过 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 切换渠道。 -- Gateway 网关 网络（两个容器，WS 认证 + health）：`pnpm test:docker:gateway-network`（脚本：`scripts/e2e/gateway-network-docker.sh`） -- OpenAI Responses `web_search` 最小推理回归测试：`pnpm test:docker:openai-web-search-minimal`（脚本：`scripts/e2e/openai-web-search-minimal-docker.sh`）会通过 Gateway 网关 运行一个 mock OpenAI 服务器，验证 `web_search` 会将 `reasoning.effort` 从 `minimal` 提升为 `low`，然后强制提供商 schema 拒绝，并检查原始详细信息是否出现在 Gateway 网关 日志中。 -- MCP 渠道桥接（预置 Gateway 网关 + stdio bridge + 原始 Claude 通知帧冒烟测试）：`pnpm test:docker:mcp-channels`（脚本：`scripts/e2e/mcp-channels-docker.sh`） -- Pi bundle MCP 工具（真实 stdio MCP 服务器 + 嵌入式 Pi profile allow / deny 冒烟测试）：`pnpm test:docker:pi-bundle-mcp-tools`（脚本：`scripts/e2e/pi-bundle-mcp-tools-docker.sh`） -- Cron / subagent MCP 清理（真实 Gateway 网关 + 在隔离 cron 和一次性 subagent 运行后清理 stdio MCP 子进程）：`pnpm test:docker:cron-mcp-cleanup`（脚本：`scripts/e2e/cron-mcp-cleanup-docker.sh`） +- Open WebUI 实时冒烟测试：`pnpm test:docker:openwebui`（脚本：`scripts/e2e/openwebui-docker.sh`） +- 新手引导向导（TTY，完整脚手架）：`pnpm test:docker:onboard`（脚本：`scripts/e2e/onboard-docker.sh`） +- Npm tarball 新手引导 / 渠道 / 智能体冒烟测试：`pnpm test:docker:npm-onboard-channel-agent` 会在 Docker 中全局安装打包好的 OpenClaw tarball，通过 env-ref onboarding 配置 OpenAI，并默认配置 Telegram，验证启用插件时会按需安装其运行时依赖，运行 doctor，并执行一次模拟的 OpenAI 智能体轮次。可通过 `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 复用预构建 tarball，通过 `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` 跳过主机构建，或通过 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 切换渠道。 +- Gateway 网关网络（两个容器，WS 认证 + 健康检查）：`pnpm test:docker:gateway-network`（脚本：`scripts/e2e/gateway-network-docker.sh`） +- OpenAI Responses `web_search` 最小推理回归测试：`pnpm test:docker:openai-web-search-minimal`（脚本：`scripts/e2e/openai-web-search-minimal-docker.sh`）会通过 Gateway 网关运行一个模拟 OpenAI 服务器，验证 `web_search` 会将 `reasoning.effort` 从 `minimal` 提升到 `low`，然后强制提供商 schema 拒绝，并检查原始细节是否出现在 Gateway 网关日志中。 +- MCP 渠道桥（带种子的 Gateway 网关 + stdio 桥 + 原始 Claude 通知帧冒烟测试）：`pnpm test:docker:mcp-channels`（脚本：`scripts/e2e/mcp-channels-docker.sh`） +- Pi bundle MCP 工具（真实 stdio MCP 服务器 + 嵌入式 Pi profile 允许 / 拒绝冒烟测试）：`pnpm test:docker:pi-bundle-mcp-tools`（脚本：`scripts/e2e/pi-bundle-mcp-tools-docker.sh`） +- Cron / subagent MCP 清理（真实 Gateway 网关 + stdio MCP 子进程在隔离的 cron 和一次性 subagent 运行后退出）：`pnpm test:docker:cron-mcp-cleanup`（脚本：`scripts/e2e/cron-mcp-cleanup-docker.sh`） - 插件（安装冒烟测试 + `/plugin` 别名 + Claude bundle 重启语义）：`pnpm test:docker:plugins`（脚本：`scripts/e2e/plugins-docker.sh`） -- 插件更新未变化冒烟测试：`pnpm test:docker:plugin-update`（脚本：`scripts/e2e/plugin-update-unchanged-docker.sh`） +- 插件更新无变更冒烟测试：`pnpm test:docker:plugin-update`（脚本：`scripts/e2e/plugin-update-unchanged-docker.sh`） - 配置热重载元数据冒烟测试：`pnpm test:docker:config-reload`（脚本：`scripts/e2e/config-reload-source-docker.sh`） -- 内置插件运行时依赖：`pnpm test:docker:bundled-channel-deps` 默认会构建一个小型 Docker 运行器镜像，在宿主机上构建并打包一次 OpenClaw，然后将该 tarball 挂载到每个 Linux 安装场景中。可通过 `OPENCLAW_SKIP_DOCKER_BUILD=1` 复用该镜像，在完成一次新的本地构建后通过 `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` 跳过宿主重建，或通过 `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 指向现有 tarball。 -- 在迭代期间，可通过禁用不相关场景来收窄内置插件运行时依赖测试，例如： +- 内置插件运行时依赖：`pnpm test:docker:bundled-channel-deps` 默认会构建一个小型 Docker 运行器镜像，在主机上构建并打包一次 OpenClaw，然后将该 tarball 挂载到每个 Linux 安装场景中。可通过 `OPENCLAW_SKIP_DOCKER_BUILD=1` 复用镜像；在本地完成一次全新构建后，可通过 `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` 跳过主机构建；也可通过 `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 指向现有 tarball。 +- 在迭代过程中，如果想缩小内置插件运行时依赖测试范围，可以禁用无关场景，例如： `OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps`。 -要手动预构建并复用共享 built-app 镜像： +如需手动预构建并复用共享的 built-app 镜像： ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -设置后，诸如 `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` 之类的测试套件专属镜像覆盖仍然优先生效。当 `OPENCLAW_SKIP_DOCKER_BUILD=1` 指向远程共享镜像时，如果该镜像尚未存在于本地，脚本会先拉取它。QR 和安装器 Docker 测试保留各自的 Dockerfile，因为它们验证的是 package / install 行为，而不是共享 built-app 运行时。 +当设置了特定测试套件的镜像覆盖项（如 `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`）时，它们仍然优先生效。当 `OPENCLAW_SKIP_DOCKER_BUILD=1` 指向远程共享镜像时，如果本地尚无该镜像，脚本会先拉取它。QR 和安装器 Docker 测试仍保留各自的 Dockerfile，因为它们验证的是 package / install 行为，而不是共享的 built-app 运行时。 -live 模型 Docker 运行器还会以只读方式 bind-mount 当前 checkout，并在容器内部将其暂存到一个临时 workdir 中。这样既能保持运行时镜像精简，又能让 Vitest 针对你精确的本地源码 / 配置运行。 -暂存步骤会跳过大型本地专用缓存和 app 构建输出，例如 +实时模型 Docker 运行器还会以只读方式绑定挂载当前 checkout，并将其暂存到容器内的临时工作目录中。这样可以在保持运行时镜像精简的同时，仍然针对你当前本地的精确源代码 / 配置运行 Vitest。 +该暂存步骤会跳过较大的本地专用缓存和 app 构建输出，例如 `.pnpm-store`、`.worktrees`、`__openclaw_vitest__`，以及 app 本地 `.build` 或 -Gradle 输出目录，因此 Docker live 运行不会浪费数分钟复制机器特定工件。 -它们还会设置 `OPENCLAW_SKIP_CHANNELS=1`，这样 gateway live 探针就不会在容器中启动真实的 Telegram / Discord / 等渠道 worker。 -`test:docker:live-models` 仍然会运行 `pnpm test:live`，因此当你需要从该 Docker 通道中收窄或排除 gateway live 覆盖时，也请一并传入 `OPENCLAW_LIVE_GATEWAY_*`。 -`test:docker:openwebui` 是一个更高层次的兼容性冒烟测试：它会启动一个启用了 OpenAI 兼容 HTTP 端点的 OpenClaw gateway 容器，启动一个固定版本的 Open WebUI 容器指向该 gateway，通过 Open WebUI 登录，验证 `/api/models` 暴露 `openclaw/default`，然后通过 Open WebUI 的 `/api/chat/completions` 代理发送一个真实聊天请求。 -首次运行可能明显更慢，因为 Docker 可能需要拉取 Open WebUI 镜像，而 Open WebUI 也可能需要完成自己的冷启动 setup。 -该通道需要一个可用的 live 模型密钥，而 `OPENCLAW_PROFILE_FILE` -（默认是 `~/.profile`）是在 Docker 化运行中提供该密钥的主要方式。 -成功运行会打印一个小型 JSON 负载，如 `{ "ok": true, "model": +Gradle 输出目录，从而避免 Docker 实时运行花费数分钟复制机器特定工件。 +它们还会设置 `OPENCLAW_SKIP_CHANNELS=1`，这样 Gateway 网关实时探测就不会在容器内启动真实的 Telegram / Discord / 等渠道工作进程。 +`test:docker:live-models` 仍然会运行 `pnpm test:live`，因此当你需要缩小范围或排除该 Docker 通道中的 Gateway 网关实时覆盖时，也请一并传入 +`OPENCLAW_LIVE_GATEWAY_*`。 +`test:docker:openwebui` 是更高层的兼容性冒烟测试：它会启动启用了 OpenAI 兼容 HTTP 端点的 OpenClaw Gateway 网关容器，针对该 Gateway 网关启动一个固定版本的 Open WebUI 容器，通过 Open WebUI 完成登录，验证 `/api/models` 暴露了 `openclaw/default`，然后通过 Open WebUI 的 `/api/chat/completions` 代理发送一次真实聊天请求。 +首次运行可能明显更慢，因为 Docker 可能需要拉取 +Open WebUI 镜像，而且 Open WebUI 可能还需要完成自身的冷启动设置。 +该通道需要一个可用的实时模型密钥，而 `OPENCLAW_PROFILE_FILE` +（默认 `~/.profile`）是在 Docker 化运行中提供该密钥的主要方式。 +成功运行后，会打印一小段 JSON 负载，例如 `{ "ok": true, "model": "openclaw/default", ... }`。 -`test:docker:mcp-channels` 刻意设计为确定性测试，不需要真实的 Telegram、Discord 或 iMessage 账号。它会启动一个已预置的 Gateway 网关 容器，再启动第二个容器运行 `openclaw mcp serve`，然后通过真实的 stdio MCP bridge 验证路由会话发现、transcript 读取、附件元数据、live 事件队列行为、出站发送路由，以及 Claude 风格的渠道 + 权限通知。通知检查会直接检查原始 stdio MCP 帧，因此该冒烟测试验证的是 bridge 实际发出的内容，而不只是某个特定客户端 SDK 恰好暴露出来的内容。 -`test:docker:pi-bundle-mcp-tools` 是确定性测试，不需要 live 模型密钥。它会构建仓库 Docker 镜像，在容器中启动一个真实 stdio MCP 探针服务器，通过嵌入式 Pi bundle MCP 运行时实例化该服务器，执行该工具，然后验证 `coding` 和 `messaging` 会保留 `bundle-mcp` 工具，而 `minimal` 和 `tools.deny: ["bundle-mcp"]` 会将其过滤掉。 -`test:docker:cron-mcp-cleanup` 是确定性测试，不需要 live 模型密钥。它会启动一个带真实 stdio MCP 探针服务器的预置 Gateway 网关，运行一次隔离的 cron 轮次和一次 `/subagents spawn` 一次性子智能体轮次，然后验证 MCP 子进程会在每次运行后退出。 +`test:docker:mcp-channels` 刻意设计为确定性测试，不需要真实的 +Telegram、Discord 或 iMessage 账户。它会启动一个带种子的 Gateway 网关容器，启动第二个会生成 `openclaw mcp serve` 的容器，然后通过真实的 stdio MCP 桥验证路由会话发现、转录读取、附件元数据、实时事件队列行为、出站发送路由，以及 Claude 风格的渠道 + 权限通知。 +通知检查会直接检查原始 stdio MCP 帧，因此该冒烟测试验证的是桥实际发出的内容，而不是某个特定客户端 SDK 恰好暴露出的内容。 +`test:docker:pi-bundle-mcp-tools` 是确定性的，不需要实时模型密钥。它会构建仓库 Docker 镜像，在容器内启动一个真实的 stdio MCP 探测服务器，通过嵌入式 Pi bundle MCP 运行时将该服务器实体化，执行工具，然后验证 `coding` 和 `messaging` 会保留 +`bundle-mcp` 工具，而 `minimal` 和 `tools.deny: ["bundle-mcp"]` 会将其过滤掉。 +`test:docker:cron-mcp-cleanup` 也是确定性的，不需要实时模型密钥。它会启动一个带真实 stdio MCP 探测服务器的带种子 Gateway 网关，运行一次隔离的 cron 轮次和一次 `/subagents spawn` 单次子智能体轮次，然后验证 MCP 子进程会在每次运行后退出。 -手动 ACP 自然语言线程冒烟测试（不在 CI 中运行）： +手动 ACP 自然语言线程冒烟测试（非 CI）： - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- 请将此脚本保留用于回归 / 调试工作流。它未来可能仍会用于 ACP 线程路由验证，因此不要删除它。 +- 请保留此脚本用于回归 / 调试工作流。未来可能还会再次需要它来验证 ACP 线程路由，因此不要删除。 -有用的环境变量： +常用环境变量： - `OPENCLAW_CONFIG_DIR=...`（默认：`~/.openclaw`）挂载到 `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...`（默认：`~/.openclaw/workspace`）挂载到 `/home/node/.openclaw/workspace` - `OPENCLAW_PROFILE_FILE=...`（默认：`~/.profile`）挂载到 `/home/node/.profile`，并在运行测试前读取 -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`：仅验证从 `OPENCLAW_PROFILE_FILE` 读取的环境变量，使用临时配置 / 工作区目录，并且不挂载外部 CLI 认证 -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（默认：`~/.cache/openclaw/docker-cli-tools`）挂载到 `/home/node/.npm-global`，用于在 Docker 中缓存 CLI 安装 +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`：只验证从 `OPENCLAW_PROFILE_FILE` 读取的环境变量，使用临时配置 / 工作区目录且不挂载外部 CLI 认证 +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（默认：`~/.cache/openclaw/docker-cli-tools`）挂载到 `/home/node/.npm-global`，用于缓存 Docker 内部的 CLI 安装 - `$HOME` 下的外部 CLI 认证目录 / 文件会以只读方式挂载到 `/host-auth...` 下，然后在测试开始前复制到 `/home/node/...` - 默认目录：`.minimax` - 默认文件：`~/.codex/auth.json`、`~/.codex/config.toml`、`.claude.json`、`~/.claude/.credentials.json`、`~/.claude/settings.json`、`~/.claude/settings.local.json` - - 收窄后的提供商运行只会挂载从 `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` 推断出的所需目录 / 文件 + - 缩小范围的提供商运行只会挂载从 `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` 推断出的所需目录 / 文件 - 可通过 `OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none` 或逗号列表（例如 `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex`）手动覆盖 -- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` 用于收窄运行范围 -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` 用于在容器内筛选提供商 -- `OPENCLAW_SKIP_DOCKER_BUILD=1`：对不需要重建的重跑复用现有 `openclaw:local-live` 镜像 -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`：确保凭证来自 profile store（而不是 env） -- `OPENCLAW_OPENWEBUI_MODEL=...`：选择 gateway 为 Open WebUI 冒烟测试暴露的模型 -- `OPENCLAW_OPENWEBUI_PROMPT=...`：覆盖 Open WebUI 冒烟测试使用的 nonce 检查 prompt +- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`：缩小运行范围 +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`：在容器中过滤提供商 +- `OPENCLAW_SKIP_DOCKER_BUILD=1`：复用现有的 `openclaw:local-live` 镜像，用于不需要重建的重跑 +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`：确保凭证来自 profile 存储（而不是环境变量） +- `OPENCLAW_OPENWEBUI_MODEL=...`：选择 Gateway 网关为 Open WebUI 冒烟测试暴露的模型 +- `OPENCLAW_OPENWEBUI_PROMPT=...`：覆盖 Open WebUI 冒烟测试中使用的 nonce 检查提示词 - `OPENWEBUI_IMAGE=...`：覆盖固定的 Open WebUI 镜像标签 ## 文档完整性检查 -在修改文档后运行文档检查：`pnpm check:docs`。 -当你还需要页内标题检查时，运行完整的 Mintlify 锚点校验：`pnpm docs:check-links:anchors`。 +编辑文档后运行文档检查：`pnpm check:docs`。 +如果还需要页内标题检查，请运行完整的 Mintlify 锚点验证：`pnpm docs:check-links:anchors`。 ## 离线回归测试（对 CI 安全） -这些是不依赖真实提供商的“真实流程”回归测试： +这些是“真实管线”回归测试，但不依赖真实提供商： -- Gateway 网关 工具调用（mock OpenAI，真实 gateway + 智能体 循环）：`src/gateway/gateway.test.ts`（用例：“runs a mock OpenAI tool call end-to-end via gateway agent loop”） -- Gateway 网关 向导（WS `wizard.start` / `wizard.next`，写入配置 + 强制认证）：`src/gateway/gateway.test.ts`（用例：“runs wizard over ws and writes auth token config”） +- Gateway 网关工具调用（模拟 OpenAI，真实 gateway + 智能体循环）：`src/gateway/gateway.test.ts`（用例：“runs a mock OpenAI tool call end-to-end via gateway agent loop”） +- Gateway 网关向导（WS `wizard.start` / `wizard.next`，写入配置 + 强制认证）：`src/gateway/gateway.test.ts`（用例：“runs wizard over ws and writes auth token config”） ## 智能体可靠性评估（Skills） -我们已经有一些对 CI 安全的测试，它们的行为类似“智能体可靠性评估”： +我们已经有一些对 CI 安全、行为类似“智能体可靠性评估”的测试： -- 通过真实 gateway + 智能体 循环的 mock 工具调用（`src/gateway/gateway.test.ts`）。 -- 验证会话接线和配置效果的端到端向导流程（`src/gateway/gateway.test.ts`）。 +- 通过真实 gateway + 智能体循环进行模拟工具调用（`src/gateway/gateway.test.ts`）。 +- 端到端向导流程，用于验证会话接线和配置效果（`src/gateway/gateway.test.ts`）。 -对于 Skills（参见 [Skills](/zh-CN/tools/skills)），目前仍缺少： +对于 Skills（参见 [Skills](/zh-CN/tools/skills)），目前仍然缺少： -- **决策能力：** 当 prompt 中列出 Skills 时，智能体能否选择正确的 Skills（或避开无关的 Skills）？ -- **合规性：** 智能体是否会在使用前读取 `SKILL.md`，并遵循必需的步骤 / 参数？ -- **工作流契约：** 断言工具顺序、会话历史延续和沙箱边界的多轮场景。 +- **决策能力：** 当提示词中列出 Skills 时，智能体是否会选择正确的 Skill（或避开无关 Skill）？ +- **合规性：** 智能体在使用前是否会读取 `SKILL.md`，并遵循要求的步骤 / 参数？ +- **工作流契约：** 多轮场景，用于断言工具顺序、会话历史承接和沙箱边界。 未来的评估应优先保持确定性： -- 一个使用 mock 提供商的场景运行器，用于断言工具调用 + 顺序、skill 文件读取和会话接线。 -- 一小组聚焦 skill 的场景（使用与避免、门控、prompt 注入）。 -- 只有在 CI 安全测试套件就绪后，才添加可选的 live 评估（按需启用、受 env 控制）。 +- 一个使用模拟提供商的场景运行器，用于断言工具调用 + 顺序、Skill 文件读取和会话接线。 +- 一小组以 Skill 为中心的场景（使用 vs 避免、门禁、提示词注入）。 +- 只有在对 CI 安全的测试套件就位之后，才增加可选的实时评估（按需启用、由环境变量门禁控制）。 -## 契约测试（插件与渠道结构） +## 契约测试（插件和渠道形状） -契约测试会验证每个已注册插件和渠道都符合其接口契约。它们会遍历所有已发现的插件，并运行一组结构和行为断言。默认的 `pnpm test` unit 通道会有意跳过这些共享接缝和冒烟测试文件；当你修改共享渠道或提供商接口时，请显式运行这些契约命令。 +契约测试用于验证每个已注册插件和渠道都符合其接口契约。它们会遍历所有已发现的插件，并运行一组针对形状和行为的断言。默认的 `pnpm test` 单元测试通道会刻意跳过这些共享接缝和冒烟测试文件；当你修改共享渠道或提供商表面时，请显式运行契约命令。 ### 命令 -- 所有契约：`pnpm test:contracts` -- 仅渠道契约：`pnpm test:contracts:channels` -- 仅提供商契约：`pnpm test:contracts:plugins` +- 全部契约测试：`pnpm test:contracts` +- 仅渠道契约测试：`pnpm test:contracts:channels` +- 仅提供商契约测试：`pnpm test:contracts:plugins` -### 渠道契约 +### 渠道契约测试 位于 `src/channels/plugins/contracts/*.contract.test.ts`： -- **plugin** - 基础插件结构（id、名称、能力） +- **plugin** - 基础插件形状（id、名称、能力） - **setup** - 设置向导契约 - **session-binding** - 会话绑定行为 - **outbound-payload** - 消息负载结构 - **inbound** - 入站消息处理 -- **actions** - 渠道动作处理器 +- **actions** - 渠道操作处理器 - **threading** - 线程 ID 处理 - **directory** - 目录 / roster API -- **group-policy** - 群组策略执行 +- **group-policy** - 群组策略强制执行 -### 提供商状态契约 +### 提供商状态契约测试 位于 `src/plugins/contracts/*.contract.test.ts`。 -- **status** - 渠道状态探针 -- **registry** - 插件注册表结构 +- **status** - 渠道状态探测 +- **registry** - 插件注册表形状 -### 提供商契约 +### 提供商契约测试 位于 `src/plugins/contracts/*.contract.test.ts`： - **auth** - 认证流程契约 -- **auth-choice** - 认证选择 / 选择逻辑 +- **auth-choice** - 认证选择 / 选取 - **catalog** - 模型目录 API - **discovery** - 插件发现 - **loader** - 插件加载 - **runtime** - 提供商运行时 -- **shape** - 插件结构 / 接口 +- **shape** - 插件形状 / 接口 - **wizard** - 设置向导 ### 何时运行 -- 在修改插件 SDK 导出或子路径之后 -- 在添加或修改渠道或提供商插件之后 -- 在重构插件注册或发现逻辑之后 +- 修改插件 SDK 导出或子路径后 +- 添加或修改渠道或提供商插件后 +- 重构插件注册或发现逻辑后 -契约测试会在 CI 中运行，不需要真实 API key。 +契约测试会在 CI 中运行，不需要真实 API 密钥。 -## 添加回归测试（指南） +## 添加回归测试（指导） -当你修复在 live 中发现的提供商 / 模型问题时： +当你修复了在实时测试中发现的提供商 / 模型问题时： -- 如果可能，添加一个对 CI 安全的回归测试（mock / stub 提供商，或捕获精确的请求结构转换） -- 如果它天然只能在 live 中验证（速率限制、认证策略），请保持 live 测试范围窄，并通过环境变量按需启用 -- 优先定位到能捕获该 bug 的最小层级： - - 提供商请求转换 / 重放 bug → direct models 测试 - - gateway 会话 / 历史 / 工具流程 bug → gateway live 冒烟测试或对 CI 安全的 gateway mock 测试 -- SecretRef 遍历防护： - - `src/secrets/exec-secret-ref-id-parity.test.ts` 会从注册表元数据（`listSecretTargetRegistryEntries()`）中为每个 SecretRef 类派生一个采样目标，然后断言会拒绝遍历片段 exec id。 - - 如果你在 `src/secrets/target-registry-data.ts` 中添加了新的 `includeInPlan` SecretRef 目标族，请更新该测试中的 `classifyTargetClass`。该测试会在遇到未分类目标 id 时故意失败，以确保新类别不会被悄悄跳过。 +- 如果可能，添加一个对 CI 安全的回归测试（模拟 / stub 提供商，或捕获精确的请求形状转换） +- 如果它本质上只能做实时测试（速率限制、认证策略），就让实时测试保持范围窄，并通过环境变量按需启用 +- 优先针对能捕获该缺陷的最小层： + - 提供商请求转换 / 回放缺陷 → 直接模型测试 + - Gateway 网关会话 / 历史 / 工具管线缺陷 → Gateway 网关实时冒烟测试或对 CI 安全的 gateway mock 测试 +- SecretRef 遍历保护规则： + - `src/secrets/exec-secret-ref-id-parity.test.ts` 会从注册表元数据（`listSecretTargetRegistryEntries()`）中为每个 SecretRef 类派生一个采样目标，然后断言遍历段 exec id 会被拒绝。 + - 如果你在 `src/secrets/target-registry-data.ts` 中新增了 `includeInPlan` SecretRef 目标家族，请更新该测试中的 `classifyTargetClass`。该测试会在遇到未分类目标 id 时故意失败，以确保新类别不会被悄悄跳过。 diff --git a/docs/zh-CN/install/fly.md b/docs/zh-CN/install/fly.md index ed089aa14..c7c73f49c 100644 --- a/docs/zh-CN/install/fly.md +++ b/docs/zh-CN/install/fly.md @@ -1,35 +1,35 @@ --- read_when: - 在 Fly.io 上部署 OpenClaw - - 设置 Fly volume、密钥和首次运行配置 -summary: 在 Fly.io 上逐步部署 OpenClaw，包含持久化存储和 HTTPS + - 设置 Fly 卷、密钥和首次运行配置 +summary: 面向 OpenClaw 的 Fly.io 逐步部署指南，包含持久化存储和 HTTPS title: Fly.io x-i18n: - generated_at: "2026-04-05T08:27:10Z" + generated_at: "2026-04-23T19:25:09Z" model: gpt-5.4 provider: openai - source_hash: a5f8c2c03295d786c0d8df98f8a5ae9335fa0346a188b81aae3e07d566a2c0ef + source_hash: 565bae44242217f7a2fa118fbdb1c2f4b989fed1d1fa011129a0983f1f5997f6 source_path: install/fly.md workflow: 15 --- # Fly.io 部署 -**目标：** 在 [Fly.io](https://fly.io) 机器上运行 OpenClaw Gateway 网关，具备持久化存储、自动 HTTPS 和 Discord/渠道访问能力。 +**目标：** 让 OpenClaw Gateway 网关运行在 [Fly.io](https://fly.io) 机器上，并具备持久化存储、自动 HTTPS，以及 Discord/渠道访问能力。 ## 你需要准备的内容 - 已安装 [flyctl CLI](https://fly.io/docs/hands-on/install-flyctl/) -- Fly.io 账户（免费层可用） -- 模型鉴权：你所选模型提供商的 API 密钥 -- 渠道凭证：Discord 机器人 token、Telegram token 等 +- 一个 Fly.io 账号（免费层即可） +- 模型认证：你所选模型提供商的 API 密钥 +- 渠道凭证：Discord 机器人令牌、Telegram 令牌等 -## 面向初学者的快速路径 +## 面向新手的快速路径 1. 克隆仓库 → 自定义 `fly.toml` -2. 创建应用 + volume → 设置密钥 +2. 创建应用和卷 → 设置密钥 3. 使用 `fly deploy` 部署 -4. SSH 登录创建配置，或使用 Control UI +4. 通过 SSH 登录以创建配置，或使用控制 UI @@ -38,21 +38,21 @@ x-i18n: git clone https://github.com/openclaw/openclaw.git cd openclaw - # 创建新的 Fly 应用（请自行选择名称） + # 创建一个新的 Fly 应用（请自行选择名称） fly apps create my-openclaw - # 创建持久化 volume（通常 1GB 就足够） + # 创建一个持久卷（通常 1GB 就够用） fly volumes create openclaw_data --size 1 --region iad ``` - **提示：** 选择离你最近的区域。常见选项：`lhr`（伦敦）、`iad`（弗吉尼亚）、`sjc`（圣何塞）。 + **提示：** 选择一个离你较近的区域。常见选项：`lhr`（伦敦）、`iad`（弗吉尼亚）、`sjc`（圣何塞）。 - 编辑 `fly.toml` 以匹配你的应用名称和需求。 + 编辑 `fly.toml`，使其符合你的应用名称和需求。 - **安全说明：** 默认配置会暴露一个公共 URL。如果你想要无公网 IP 的加固部署，请参见[私有部署](#private-deployment-hardened)或使用 `fly.private.toml`。 + **安全说明：** 默认配置会公开一个公共 URL。若需不带公共 IP 的强化部署，请参见 [Private Deployment](#private-deployment-hardened) 或使用 `fly.private.toml`。 ```toml app = "my-openclaw" # 你的应用名称 @@ -89,19 +89,19 @@ x-i18n: **关键设置：** - | Setting | Why | + | 设置 | 原因 | | ------------------------------ | --------------------------------------------------------------------------- | - | `--bind lan` | 绑定到 `0.0.0.0`，这样 Fly 的代理才能访问 Gateway 网关 | - | `--allow-unconfigured` | 在没有配置文件的情况下启动（你稍后会创建） | - | `internal_port = 3000` | 必须与 `--port 3000`（或 `OPENCLAW_GATEWAY_PORT`）匹配，以通过 Fly 健康检查 | - | `memory = "2048mb"` | 512MB 太小；建议使用 2GB | - | `OPENCLAW_STATE_DIR = "/data"` | 将状态持久化到 volume | + | `--bind lan` | 绑定到 `0.0.0.0`，这样 Fly 的代理才能访问 Gateway 网关 | + | `--allow-unconfigured` | 可在没有配置文件的情况下启动（你会在之后创建它） | + | `internal_port = 3000` | 必须与 `--port 3000`（或 `OPENCLAW_GATEWAY_PORT`）一致，以通过 Fly 健康检查 | + | `memory = "2048mb"` | 512MB 太小；推荐 2GB | + | `OPENCLAW_STATE_DIR = "/data"` | 将状态持久保存到卷中 | ```bash - # 必需：Gateway 网关 token（用于非 loopback 绑定） + # 必需：Gateway 网关令牌（用于非 loopback 绑定） fly secrets set OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32) # 模型提供商 API 密钥 @@ -111,15 +111,15 @@ x-i18n: fly secrets set OPENAI_API_KEY=sk-... fly secrets set GOOGLE_API_KEY=... - # 渠道 token + # 渠道令牌 fly secrets set DISCORD_BOT_TOKEN=MTQ... ``` **说明：** - - 非 loopback 绑定（`--bind lan`）要求存在有效的 Gateway 网关鉴权路径。这个 Fly.io 示例使用 `OPENCLAW_GATEWAY_TOKEN`，但 `gateway.auth.password` 或正确配置的非 loopback `trusted-proxy` 部署也满足要求。 - - 请将这些 token 视为密码。 - - **所有 API 密钥和 token 都优先使用环境变量，而不是配置文件。** 这样可以避免将密钥写入 `openclaw.json`，从而降低被意外暴露或记录的风险。 + - 非 loopback 绑定（`--bind lan`）要求存在有效的 Gateway 网关认证路径。本 Fly.io 示例使用 `OPENCLAW_GATEWAY_TOKEN`，但 `gateway.auth.password` 或配置正确的非 loopback `trusted-proxy` 部署也能满足该要求。 + - 像对待密码一样对待这些令牌。 + - 对所有 API 密钥和令牌，**优先使用环境变量而不是配置文件**。这样可以避免密钥出现在 `openclaw.json` 中，降低意外暴露或被记录到日志中的风险。 @@ -128,16 +128,16 @@ x-i18n: fly deploy ``` - 首次部署会构建 Docker 镜像（约 2-3 分钟）。后续部署会更快。 + 首次部署会构建 Docker 镜像（约 2–3 分钟）。后续部署会更快。 - 部署后，验证： + 部署后，请验证： ```bash fly status fly logs ``` - 你应该看到： + 你应该会看到： ``` [gateway] listening on ws://0.0.0.0:3000 (PID xxx) @@ -147,7 +147,7 @@ x-i18n: - 通过 SSH 登录机器以创建正式配置： + 通过 SSH 登录到机器以创建正式配置： ```bash fly ssh console @@ -163,7 +163,7 @@ x-i18n: "defaults": { "model": { "primary": "anthropic/claude-opus-4-6", - "fallbacks": ["anthropic/claude-sonnet-4-6", "openai/gpt-5.4"] + "fallbacks": ["anthropic/claude-sonnet-4-6", "openai/gpt-5.5"] }, "maxConcurrent": 4 }, @@ -207,14 +207,14 @@ x-i18n: EOF ``` - **说明：** 由于 `OPENCLAW_STATE_DIR=/data`，配置路径是 `/data/openclaw.json`。 + **注意：** 由于设置了 `OPENCLAW_STATE_DIR=/data`，配置路径为 `/data/openclaw.json`。 - **说明：** Discord token 可以来自以下任一方式： + **注意：** Discord 令牌可以来自以下任一位置： - - 环境变量：`DISCORD_BOT_TOKEN`（推荐用于密钥） + - 环境变量：`DISCORD_BOT_TOKEN`（推荐用于存放密钥） - 配置文件：`channels.discord.token` - 如果使用环境变量，就无需把 token 添加到配置中。Gateway 网关会自动读取 `DISCORD_BOT_TOKEN`。 + 如果使用环境变量，则无需将令牌加入配置中。Gateway 网关会自动读取 `DISCORD_BOT_TOKEN`。 重启以应用配置： @@ -226,7 +226,7 @@ x-i18n: - ### Control UI + ### 控制 UI 在浏览器中打开： @@ -236,9 +236,7 @@ x-i18n: 或访问 `https://my-openclaw.fly.dev/` - 使用已配置的共享密钥进行鉴权。本指南使用来自 `OPENCLAW_GATEWAY_TOKEN` 的 Gateway 网关 - token；如果你改用了密码鉴权，请改用 - 该密码。 + 使用已配置的共享密钥进行认证。本指南使用 `OPENCLAW_GATEWAY_TOKEN` 中的 Gateway 网关令牌；如果你改用了密码认证，请改用该密码。 ### 日志 @@ -262,19 +260,19 @@ x-i18n: Gateway 网关绑定到了 `127.0.0.1`，而不是 `0.0.0.0`。 -**修复：** 在 `fly.toml` 的进程命令中添加 `--bind lan`。 +**修复方法：** 在 `fly.toml` 的进程命令中添加 `--bind lan`。 -### 健康检查失败 / 连接被拒绝 +### 健康检查失败 / connection refused -Fly 无法通过配置端口访问 Gateway 网关。 +Fly 无法通过配置的端口访问 Gateway 网关。 -**修复：** 确保 `internal_port` 与 Gateway 网关端口匹配（设置 `--port 3000` 或 `OPENCLAW_GATEWAY_PORT=3000`）。 +**修复方法：** 确保 `internal_port` 与 Gateway 网关端口一致（设置 `--port 3000` 或 `OPENCLAW_GATEWAY_PORT=3000`）。 ### OOM / 内存问题 -容器不断重启或被杀死。迹象包括：`SIGABRT`、`v8::internal::Runtime_AllocateInYoungGeneration` 或静默重启。 +容器持续重启或被杀死。迹象包括：`SIGABRT`、`v8::internal::Runtime_AllocateInYoungGeneration`，或无提示重启。 -**修复：** 增加 `fly.toml` 中的内存： +**修复方法：** 增加 `fly.toml` 中的内存： ```toml [[vm]] @@ -287,15 +285,15 @@ Fly 无法通过配置端口访问 Gateway 网关。 fly machine update --vm-memory 2048 -y ``` -**说明：** 512MB 太小。1GB 可能可以运行，但在负载较高或启用详细日志时可能 OOM。**建议使用 2GB。** +**注意：** 512MB 太小。1GB 也许能运行，但在有负载或启用详细日志时可能会 OOM。**推荐使用 2GB。** -### Gateway 网关锁问题 +### Gateway 网关锁文件问题 -Gateway 网关因“already running”错误而拒绝启动。 +Gateway 网关拒绝启动，并报出 “already running” 错误。 -当容器重启但 PID 锁文件仍保留在 volume 上时，就会出现这种情况。 +这通常发生在容器重启后，但 PID 锁文件仍保留在卷中。 -**修复：** 删除锁文件： +**修复方法：** 删除锁文件： ```bash fly ssh console --command "rm -f /data/gateway.*.lock" @@ -306,7 +304,7 @@ fly machine restart ### 未读取配置 -`--allow-unconfigured` 只会绕过启动保护。它不会创建或修复 `/data/openclaw.json`，所以请确保你的实际配置存在，并且在你希望正常以本地 Gateway 网关方式启动时包含 `gateway.mode="local"`。 +`--allow-unconfigured` 只会绕过启动保护。它不会创建或修复 `/data/openclaw.json`，因此请确保你的实际配置存在，并且在你希望正常以本地模式启动 Gateway 网关时包含 `gateway.mode="local"`。 验证配置是否存在： @@ -319,7 +317,7 @@ fly ssh console --command "cat /data/openclaw.json" `fly ssh console -C` 命令不支持 shell 重定向。要写入配置文件： ```bash -# 使用 echo + tee（从本地通过管道传到远程） +# 使用 echo + tee（从本地管道到远程） echo '{"your":"config"}' | fly ssh console -C "tee /data/openclaw.json" # 或使用 sftp @@ -327,18 +325,18 @@ fly sftp shell > put /local/path/config.json /data/openclaw.json ``` -**说明：** 如果文件已存在，`fly sftp` 可能失败。请先删除： +**注意：** 如果文件已存在，`fly sftp` 可能会失败。请先删除： ```bash fly ssh console --command "rm /data/openclaw.json" ``` -### 状态未持久化 +### 状态未持久保存 -如果你在重启后丢失 auth profile、渠道/提供商状态或会话， -说明状态目录写到了容器文件系统中。 +如果重启后你丢失了认证配置档、渠道/提供商状态或会话数据， +说明状态目录被写入到了容器文件系统中。 -**修复：** 确保在 `fly.toml` 中设置了 `OPENCLAW_STATE_DIR=/data`，然后重新部署。 +**修复方法：** 确保在 `fly.toml` 中设置了 `OPENCLAW_STATE_DIR=/data`，然后重新部署。 ## 更新 @@ -356,7 +354,7 @@ fly logs ### 更新机器命令 -如果你需要在不完整重新部署的情况下更改启动命令： +如果你需要在不完整重新部署的情况下修改启动命令： ```bash # 获取机器 ID @@ -369,49 +367,49 @@ fly machine update --command "node dist/index.js gateway --port 300 fly machine update --vm-memory 2048 --command "node dist/index.js gateway --port 3000 --bind lan" -y ``` -**说明：** 在执行 `fly deploy` 后，机器命令可能会重置为 `fly.toml` 中的内容。如果你做过手动更改，请在部署后重新应用这些更改。 +**注意：** 执行 `fly deploy` 后，机器命令可能会重置为 `fly.toml` 中的内容。如果你做过手动修改，请在部署后重新应用这些修改。 -## 私有部署（加固版） +## 私有部署（强化版） -默认情况下，Fly 会分配公网 IP，这意味着你的 Gateway 网关可以通过 `https://your-app.fly.dev` 访问。这很方便，但也意味着你的部署可被互联网扫描器（Shodan、Censys 等）发现。 +默认情况下，Fly 会分配公共 IP，这会让你的 Gateway 网关可通过 `https://your-app.fly.dev` 访问。这样做很方便，但也意味着你的部署可被互联网扫描器（Shodan、Censys 等）发现。 -如果你希望获得**完全不暴露公网**的加固部署，请使用私有模板。 +如果你希望进行**完全不对公网暴露**的强化部署，请使用私有模板。 ### 何时使用私有部署 -- 你只进行**出站**调用/消息（没有入站 webhook） -- 你为任何 webhook 回调使用 **ngrok 或 Tailscale** 隧道 +- 你只进行**出站**调用/发消息（没有入站 webhook） +- 你使用 **ngrok 或 Tailscale** 隧道处理所有 webhook 回调 - 你通过 **SSH、代理或 WireGuard** 访问 Gateway 网关，而不是浏览器 - 你希望部署**对互联网扫描器隐藏** ### 设置 -使用 `fly.private.toml`，而不是标准配置： +使用 `fly.private.toml` 而不是标准配置： ```bash # 使用私有配置部署 fly deploy -c fly.private.toml ``` -或者将现有部署转换为私有： +或者将现有部署转换为私有部署： ```bash # 列出当前 IP fly ips list -a my-openclaw -# 释放公网 IP +# 释放公共 IP fly ips release -a my-openclaw fly ips release -a my-openclaw -# 切换到私有配置，以便后续部署不会重新分配公网 IP -# （移除 [http_service]，或使用私有模板部署） +# 切换到私有配置，这样未来部署就不会重新分配公共 IP +# （移除 [http_service] 或使用私有模板部署） fly deploy -c fly.private.toml -# 分配仅私有 IPv6 +# 分配仅私有的 IPv6 fly ips allocate-v6 --private -a my-openclaw ``` -此后，`fly ips list` 应只显示一个 `private` 类型 IP： +完成后，`fly ips list` 应只显示一个 `private` 类型 IP： ``` VERSION IP TYPE REGION @@ -420,12 +418,12 @@ v6 fdaa:x:x:x:x::x private global ### 访问私有部署 -由于没有公共 URL，请使用以下方式之一： +由于没有公共 URL，请使用以下任一方式： **选项 1：本地代理（最简单）** ```bash -# 将本地端口 3000 转发到应用 +# 将本地 3000 端口转发到应用 fly proxy 3000:3000 -a my-openclaw # 然后在浏览器中打开 http://localhost:3000 @@ -447,15 +445,15 @@ fly wireguard create fly ssh console -a my-openclaw ``` -### 私有部署中的 webhook +### 私有部署中的 Webhooks -如果你在不暴露公网的情况下仍然需要 webhook 回调（Twilio、Telnyx 等）： +如果你在不公开暴露的前提下仍需要 webhook 回调（Twilio、Telnyx 等）： -1. **ngrok 隧道** —— 在容器内或作为 sidecar 运行 ngrok -2. **Tailscale Funnel** —— 通过 Tailscale 暴露特定路径 -3. **仅出站** —— 某些提供商（Twilio）在没有 webhook 的情况下也能正常进行出站呼叫 +1. **ngrok 隧道** - 在容器内或作为 sidecar 运行 ngrok +2. **Tailscale Funnel** - 通过 Tailscale 暴露特定路径 +3. **仅出站** - 某些提供商（如 Twilio）在无 webhook 的情况下也能良好支持出站呼叫 -使用 ngrok 的语音通话配置示例： +语音通话使用 ngrok 的配置示例： ```json5 { @@ -476,36 +474,36 @@ fly ssh console -a my-openclaw } ``` -ngrok 隧道运行在容器内，并提供公共 webhook URL，而不会暴露 Fly 应用本身。请将 `webhookSecurity.allowedHosts` 设置为该公共隧道主机名，以便接受转发后的 host header。 +ngrok 隧道在容器内部运行，并提供一个公共 webhook URL，而不会暴露 Fly 应用本身。请将 `webhookSecurity.allowedHosts` 设置为该公共隧道主机名，这样才会接受被转发的 Host 请求头。 ### 安全收益 -| Aspect | Public | Private | +| 方面 | 公共部署 | 私有部署 | | ----------------- | ------------ | ---------- | -| Internet scanners | 可发现 | 隐藏 | -| Direct attacks | 可能 | 被阻止 | -| Control UI access | 浏览器 | 代理/VPN | -| Webhook delivery | 直接 | 通过隧道 | +| 互联网扫描器 | 可发现 | 已隐藏 | +| 直接攻击 | 可能 | 已阻止 | +| 控制 UI 访问 | 浏览器 | 代理/VPN | +| webhook 投递 | 直接 | 通过隧道 | ## 说明 -- Fly.io 使用 **x86 架构**（不是 ARM） -- Dockerfile 兼容两种架构 +- Fly.io 使用的是 **x86 架构**（不是 ARM） +- Dockerfile 同时兼容这两种架构 - 对于 WhatsApp/Telegram 新手引导，请使用 `fly ssh console` -- 持久化数据位于 `/data` volume 上 +- 持久化数据存储在卷的 `/data` 路径下 - Signal 需要 Java + signal-cli；请使用自定义镜像，并将内存保持在 2GB 以上。 ## 成本 -使用推荐配置（`shared-cpu-2x`，2GB RAM）时： +使用推荐配置（`shared-cpu-2x`、2GB RAM）时： -- 约 $10-15/月，取决于使用情况 +- 取决于使用情况，约为每月 10–15 美元 - 免费层包含一定额度 详情请参见 [Fly.io pricing](https://fly.io/docs/about/pricing/)。 ## 后续步骤 -- 设置消息渠道：[Channels](/channels) -- 配置 Gateway 网关：[Gateway configuration](/gateway/configuration) -- 让 OpenClaw 保持最新：[Updating](/install/updating) +- 设置消息渠道：[Channels](/zh-CN/channels) +- 配置 Gateway 网关：[Gateway configuration](/zh-CN/gateway/configuration) +- 保持 OpenClaw 为最新版本：[Updating](/zh-CN/install/updating) diff --git a/docs/zh-CN/nodes/media-understanding.md b/docs/zh-CN/nodes/media-understanding.md index 4f376d5b6..833f58eed 100644 --- a/docs/zh-CN/nodes/media-understanding.md +++ b/docs/zh-CN/nodes/media-understanding.md @@ -1,58 +1,58 @@ --- read_when: - 设计或重构媒体理解 - - 调整入站音频/视频/图像预处理 -summary: 入站图像/音频/视频理解（可选），并提供提供商 + CLI 回退方案 + - 调优入站音频/视频/图像预处理 +summary: 入站图像/音频/视频理解（可选），支持提供商 + CLI 回退方案 title: 媒体理解 x-i18n: - generated_at: "2026-04-23T00:08:05Z" + generated_at: "2026-04-23T19:25:16Z" model: gpt-5.4 provider: openai - source_hash: 5bb2d0eab59d857c2849f329435f8fad3eeff427f7984d011bd5b7d9fd7bf51c + source_hash: 89e89b0db8cc4a53270492ce5dfa1bb0a0d0f2dec7f4900ea9984bf98bbbc189 source_path: nodes/media-understanding.md workflow: 15 --- # 媒体理解 - 入站（2026-01-17） -OpenClaw 可以在回复流水线运行前，**总结入站媒体**（图像/音频/视频）。它会在检测到本地工具或提供商密钥可用时自动启用，也可以被禁用或自定义。如果理解功能关闭，模型仍会像往常一样接收原始文件/URL。 +OpenClaw 可以在回复流水线运行前**总结入站媒体**（图像/音频/视频）。它会在本地工具或提供商密钥可用时自动检测，也可以被禁用或自定义。如果理解功能关闭，模型仍会像往常一样接收原始文件/URL。 特定厂商的媒体行为由厂商插件注册，而 OpenClaw -核心负责共享的 `tools.media` 配置、回退顺序以及回复流水线集成。 +核心负责共享的 `tools.media` 配置、回退顺序，以及与回复流水线的集成。 ## 目标 - 可选：将入站媒体预先整理为简短文本，以实现更快的路由和更好的命令解析。 - 始终保留向模型传递原始媒体。 -- 支持 **provider API** 和 **CLI 回退方案**。 -- 允许多个模型按顺序回退（错误/大小/超时）。 +- 支持**提供商 API** 和 **CLI 回退方案**。 +- 允许多个模型并按顺序回退（错误/大小/超时）。 ## 高层行为 1. 收集入站附件（`MediaPaths`、`MediaUrls`、`MediaTypes`）。 -2. 对每个已启用的能力，按策略选择附件（默认：**第一个**）。 -3. 选择第一个符合条件的模型条目（大小 + 能力 + 认证）。 -4. 如果模型失败或媒体过大，**回退到下一个条目**。 +2. 对每种已启用能力（图像/音频/视频），按策略选择附件（默认：**第一个**）。 +3. 选择第一个符合条件的模型条目（大小 + 能力 + 身份验证）。 +4. 如果某个模型失败或媒体过大，则**回退到下一个条目**。 5. 成功时： - - `Body` 变为 `[Image]`、`[Audio]` 或 `[Video]` 块。 - - 音频会设置 `{{Transcript}}`；如果存在说明文字，命令解析使用说明文字，否则使用转录文本。 - - 说明文字会作为 `User text:` 保留在块中。 + - `Body` 会变成 `[Image]`、`[Audio]` 或 `[Video]` 区块。 + - 音频会设置 `{{Transcript}}`；存在说明文字时，命令解析使用说明文字，否则使用转录文本。 + - 说明文字会作为 `User text:` 保留在区块内。 如果理解失败或被禁用，**回复流程会继续**，并使用原始正文 + 附件。 ## 配置概览 -`tools.media` 支持**共享模型**以及按能力分别覆盖： +`tools.media` 支持**共享模型**以及按能力划分的覆盖项： - `tools.media.models`：共享模型列表（使用 `capabilities` 进行限制）。 - `tools.media.image` / `tools.media.audio` / `tools.media.video`： - 默认值（`prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`） - - 提供商覆盖（`baseUrl`、`headers`、`providerOptions`） + - 提供商覆盖项（`baseUrl`、`headers`、`providerOptions`） - 通过 `tools.media.audio.providerOptions.deepgram` 设置 Deepgram 音频选项 - 音频转录回显控制（`echoTranscript`，默认 `false`；`echoFormat`） - 可选的**按能力划分的 `models` 列表**（优先于共享模型） - `attachments` 策略（`mode`、`maxAttachments`、`prefer`） - - `scope`（可选，按渠道/聊天类型/会话键进行限制） + - `scope`（可选，按渠道/chatType/会话键进行限制） - `tools.media.concurrency`：最大并发能力运行数（默认 **2**）。 ```json5 @@ -63,15 +63,15 @@ OpenClaw 可以在回复流水线运行前，**总结入站媒体**（图像/音 /* 共享列表 */ ], image: { - /* 可选覆盖 */ + /* 可选覆盖项 */ }, audio: { - /* 可选覆盖 */ + /* 可选覆盖项 */ echoTranscript: true, echoFormat: '📝 "{transcript}"', }, video: { - /* 可选覆盖 */ + /* 可选覆盖项 */ }, }, }, @@ -80,13 +80,13 @@ OpenClaw 可以在回复流水线运行前，**总结入站媒体**（图像/音 ### 模型条目 -每个 `models[]` 条目都可以是 **provider** 或 **CLI**： +每个 `models[]` 条目都可以是**提供商**或 **CLI**： ```json5 { - type: "provider", // 如果省略则为默认值 + type: "provider", // 如果省略，则默认为该值 provider: "openai", - model: "gpt-5.4-mini", + model: "gpt-5.5", prompt: "Describe the image in <= 500 chars.", maxChars: 500, maxBytes: 10485760, @@ -119,9 +119,9 @@ CLI 模板还可以使用： - `{{MediaDir}}`（包含媒体文件的目录） - `{{OutputDir}}`（为本次运行创建的临时目录） -- `{{OutputBase}}`（临时文件基础路径，不带扩展名） +- `{{OutputBase}}`（临时输出文件基础路径，不含扩展名） -## 默认值和限制 +## 默认值与限制 推荐默认值： @@ -134,32 +134,30 @@ CLI 模板还可以使用： 规则： -- 如果媒体超过 `maxBytes`，该模型将被跳过，并**尝试下一个模型**。 -- 小于 **1024 字节**的音频文件会被视为空/损坏，并在 provider/CLI 转录前跳过。 +- 如果媒体超过 `maxBytes`，则跳过该模型并**尝试下一个模型**。 +- 小于 **1024 字节**的音频文件会被视为空或损坏，并在提供商/CLI 转录之前跳过。 - 如果模型返回的内容超过 `maxChars`，输出会被截断。 - `prompt` 默认为简单的 “Describe the {media}.”，并附带 `maxChars` 指引（仅图像/视频）。 -- 如果当前主图像模型已经原生支持视觉能力，OpenClaw - 会跳过 `[Image]` 摘要块，而是直接将原始图像传递给模型。 -- 显式的 `openclaw infer image describe --model ` 请求不同：它们会直接运行该支持图像能力的 provider/model，包括 - `ollama/qwen2.5vl:7b` 这类 Ollama 引用。 -- 如果 `.enabled: true` 但未配置任何模型，当其 provider 支持该能力时，OpenClaw 会尝试使用**当前活动回复模型**。 +- 如果当前激活的主图像模型本身已原生支持视觉能力，OpenClaw + 会跳过 `[Image]` 摘要区块，而是将原始图像直接传给模型。 +- 显式的 `openclaw infer image describe --model ` 请求则不同：它们会直接运行该具备图像能力的 provider/model，包括诸如 `ollama/qwen2.5vl:7b` 这样的 Ollama 引用。 +- 如果 `.enabled: true` 但未配置任何模型，当其提供商支持该能力时，OpenClaw 会尝试使用**当前激活的回复模型**。 ### 自动检测媒体理解（默认） -如果 `tools.media..enabled` **未**设置为 `false`，并且你没有配置模型，OpenClaw 会按以下顺序自动检测，并在**第一个可用选项**处停止： +如果 `tools.media..enabled` **未**被设置为 `false`，并且你尚未配置模型，OpenClaw 会按以下顺序自动检测，并在**找到第一个可用选项后停止**： -1. **当前活动回复模型**，前提是其 provider 支持该能力。 +1. **当前激活的回复模型**，前提是其提供商支持该能力。 2. **`agents.defaults.imageModel`** 主/回退引用（仅图像）。 3. **本地 CLI**（仅音频；如果已安装） - `sherpa-onnx-offline`（需要 `SHERPA_ONNX_MODEL_DIR`，其中包含 encoder/decoder/joiner/tokens） - `whisper-cli`（`whisper-cpp`；使用 `WHISPER_CPP_MODEL` 或内置的 tiny 模型） - `whisper`（Python CLI；自动下载模型） 4. **Gemini CLI**（`gemini`），使用 `read_many_files` -5. **提供商认证** - - 已配置的、支持该能力的 `models.providers.*` 条目会优先于内置回退顺序进行尝试。 - - 仅图像的配置提供商，只要包含支持图像能力的模型，即使它们不是内置厂商插件，也会自动注册用于媒体理解。 - - 当显式选择时，Ollama 图像理解可用，例如通过 `agents.defaults.imageModel` 或 - `openclaw infer image describe --model ollama/`。 +5. **提供商身份验证** + - 已配置的 `models.providers.*` 条目中，支持该能力的会在内置回退顺序之前尝试。 + - 使用具备图像能力模型的仅图像配置提供商，即使不是内置厂商插件，也会自动为媒体理解注册。 + - 当显式选择时，Ollama 图像理解可用，例如通过 `agents.defaults.imageModel` 或 `openclaw infer image describe --model ollama/`。 - 内置回退顺序： - 音频：OpenAI → Groq → xAI → Deepgram → Google → Mistral - 图像：OpenAI → Anthropic → Google → MiniMax → MiniMax Portal → Z.AI @@ -179,24 +177,24 @@ CLI 模板还可以使用： } ``` -注意：二进制检测在 macOS/Linux/Windows 上均为尽力而为；请确保 CLI 在 `PATH` 中（我们会展开 `~`），或者设置带完整命令路径的显式 CLI 模型。 +注意：在 macOS/Linux/Windows 上，二进制检测都只是尽力而为；请确保 CLI 位于 `PATH` 中（我们会展开 `~`），或者设置带有完整命令路径的显式 CLI 模型。 -### 代理环境支持（provider 模型） +### 代理环境支持（提供商模型） -启用基于 provider 的**音频**和**视频**媒体理解时，OpenClaw -会在 provider HTTP 调用中遵循标准的出站代理环境变量： +启用基于提供商的**音频**和**视频**媒体理解时，OpenClaw +会在调用提供商 HTTP 时遵循标准的出站代理环境变量： - `HTTPS_PROXY` - `HTTP_PROXY` - `https_proxy` - `http_proxy` -如果未设置任何代理环境变量，媒体理解将使用直连出口。 +如果未设置代理环境变量，媒体理解将直接出网。 如果代理值格式错误，OpenClaw 会记录警告并回退为直接抓取。 ## 能力（可选） -如果你设置了 `capabilities`，该条目只会用于这些媒体类型。对于共享列表，OpenClaw 可以推断默认值： +如果你设置了 `capabilities`，该条目只会对这些媒体类型运行。对于共享列表，OpenClaw 可以推断默认值： - `openai`、`anthropic`、`minimax`：**图像** - `minimax-portal`：**图像** @@ -209,33 +207,31 @@ CLI 模板还可以使用： - `groq`：**音频** - `xai`：**音频** - `deepgram`：**音频** -- 任何带有支持图像能力模型的 `models.providers..models[]` 目录：**图像** +- 任意 `models.providers..models[]` 目录中带有具备图像能力模型的条目：**图像** 对于 CLI 条目，**请显式设置 `capabilities`**，以避免意外匹配。 -如果你省略 `capabilities`，该条目将适用于其所在列表。 +如果省略 `capabilities`，则该条目会对其所在列表适用。 -## Provider 支持矩阵（OpenClaw 集成） +## 提供商支持矩阵（OpenClaw 集成） -| Capability | Provider integration | Notes | -| ---------- | -------------------- | ----- | -| 图像 | OpenAI、OpenRouter、Anthropic、Google、MiniMax、Moonshot、Qwen、Z.AI、配置提供商 | 厂商插件注册图像支持；MiniMax 和 MiniMax OAuth 都使用 `MiniMax-VL-01`；支持图像的配置提供商会自动注册。 | -| 音频 | OpenAI、Groq、Deepgram、Google、Mistral | 提供商转录（Whisper/Deepgram/Gemini/Voxtral）。 | -| 视频 | Google、Qwen、Moonshot | 通过厂商插件提供视频理解；Qwen 视频理解使用标准的 DashScope 端点。 | +| Capability | 提供商集成 | 说明 | +| ---------- | ---------- | ---- | +| Image | OpenAI、OpenRouter、Anthropic、Google、MiniMax、Moonshot、Qwen、Z.AI、配置提供商 | 厂商插件会注册图像支持；MiniMax 和 MiniMax OAuth 都使用 `MiniMax-VL-01`；具备图像能力的配置提供商会自动注册。 | +| Audio | OpenAI、Groq、Deepgram、Google、Mistral | 提供商转录（Whisper/Deepgram/Gemini/Voxtral）。 | +| Video | Google、Qwen、Moonshot | 通过厂商插件提供视频理解；Qwen 视频理解使用标准 DashScope 端点。 | MiniMax 说明： -- `minimax` 和 `minimax-portal` 图像理解来自插件拥有的 - `MiniMax-VL-01` 媒体提供商。 -- 内置的 MiniMax 文本目录仍然以纯文本为起点；显式的 - `models.providers.minimax` 条目会实例化支持图像能力的 M2.7 chat 引用。 +- `minimax` 和 `minimax-portal` 图像理解来自插件拥有的 `MiniMax-VL-01` 媒体提供商。 +- 内置的 MiniMax 文本目录仍从仅文本开始；显式的 `models.providers.minimax` 条目会具体化支持图像的 M2.7 聊天引用。 -## 模型选择指导 +## 模型选择指引 -- 当质量和安全性很重要时，优先为每种媒体能力选择可用的、能力最强的最新一代模型。 -- 对于处理不可信输入的启用工具的智能体，避免使用较旧/较弱的媒体模型。 -- 每种能力至少保留一个回退方案以确保可用性（高质量模型 + 更快/更便宜的模型）。 -- 当 provider API 不可用时，CLI 回退方案（`whisper-cli`、`whisper`、`gemini`）很有用。 -- `parakeet-mlx` 说明：使用 `--output-dir` 时，如果输出格式为 `txt`（或未指定），OpenClaw 会读取 `/.txt`；非 `txt` 格式会回退到 stdout。 +- 当质量和安全性很重要时，应优先为每种媒体能力选择可用的最新一代最强模型。 +- 对于处理不受信任输入的启用工具智能体，避免使用较旧/较弱的媒体模型。 +- 每种能力至少保留一个回退项以确保可用性（高质量模型 + 更快/更便宜的模型）。 +- CLI 回退方案（`whisper-cli`、`whisper`、`gemini`）在提供商 API 不可用时很有帮助。 +- `parakeet-mlx` 说明：使用 `--output-dir` 时，当输出格式为 `txt`（或未指定）时，OpenClaw 会读取 `/.txt`；非 `txt` 格式则回退到 stdout。 ## 附件策略 @@ -249,26 +245,26 @@ MiniMax 说明： 文件附件提取行为： -- 提取的文件文本会先包装为**不可信外部内容**，然后再附加到媒体提示中。 -- 注入块使用显式边界标记，例如 +- 提取出的文件文本会先包装为**不受信任的外部内容**，然后再附加到媒体提示词中。 +- 注入的区块会使用明确的边界标记，例如 `<<>>` / - `<<>>`，并包含 - `Source: External` 元数据行。 -- 该附件提取路径有意省略较长的 - `SECURITY NOTICE:` 横幅，以避免媒体提示过于臃肿；边界标记和元数据仍会保留。 + `<<>>`，并包含一行 + `Source: External` 元数据。 +- 此附件提取路径有意省略了较长的 + `SECURITY NOTICE:` 横幅，以避免媒体提示词膨胀；但边界标记和元数据仍会保留。 - 如果文件没有可提取文本，OpenClaw 会注入 `[No extractable text]`。 -- 如果 PDF 在该路径中回退为渲染后的页面图像，媒体提示会保留占位符 `[PDF content rendered to images; images not forwarded to model]`，因为这个附件提取步骤转发的是文本块，而不是渲染后的 PDF 图像。 +- 如果 PDF 在此路径中回退为渲染后的页面图像，媒体提示词会保留占位符 `[PDF content rendered to images; images not forwarded to model]`，因为该附件提取步骤传递的是文本区块，而不是渲染后的 PDF 图像。 ## 配置示例 -### 1) 共享模型列表 + 覆盖 +### 1）共享模型列表 + 覆盖项 ```json5 { tools: { media: { models: [ - { provider: "openai", model: "gpt-5.4-mini", capabilities: ["image"] }, + { provider: "openai", model: "gpt-5.5", capabilities: ["image"] }, { provider: "google", model: "gemini-3-flash-preview", @@ -298,7 +294,7 @@ MiniMax 说明： } ``` -### 2) 仅音频 + 视频（关闭图像） +### 2）仅音频 + 视频（关闭图像） ```json5 { @@ -338,7 +334,7 @@ MiniMax 说明： } ``` -### 3) 可选图像理解 +### 3）可选的图像理解 ```json5 { @@ -349,7 +345,7 @@ MiniMax 说明： maxBytes: 10485760, maxChars: 500, models: [ - { provider: "openai", model: "gpt-5.4-mini" }, + { provider: "openai", model: "gpt-5.5" }, { provider: "anthropic", model: "claude-opus-4-6" }, { type: "cli", @@ -369,7 +365,7 @@ MiniMax 说明： } ``` -### 4) 多模态单条目（显式能力） +### 4）多模态单条目（显式 capabilities） ```json5 { @@ -409,21 +405,21 @@ MiniMax 说明： ## 状态输出 -当媒体理解运行时，`/status` 会包含一条简短的摘要行： +当媒体理解运行时，`/status` 会包含一行简短摘要： ``` -📎 Media: image ok (openai/gpt-5.4-mini) · audio skipped (maxBytes) +📎 Media: image ok (openai/gpt-5.5) · audio skipped (maxBytes) ``` -这会显示各项能力的结果，以及适用时所选的 provider/model。 +这会显示按能力划分的结果，以及适用时所选的 provider/model。 ## 说明 -- 理解是**尽力而为**的。错误不会阻止回复。 -- 即使理解被禁用，附件仍会传递给模型。 -- 使用 `scope` 来限制理解运行的位置（例如仅在私信中）。 +- 理解功能是**尽力而为**的。错误不会阻止回复。 +- 即使理解功能被禁用，附件仍会传递给模型。 +- 使用 `scope` 可限制理解功能的运行范围（例如仅在私信中）。 ## 相关文档 - [配置](/zh-CN/gateway/configuration) -- [图像和媒体支持](/zh-CN/nodes/images) +- [图像与媒体支持](/zh-CN/nodes/images) diff --git a/docs/zh-CN/plugins/codex-harness.md b/docs/zh-CN/plugins/codex-harness.md index 0557a7537..92ca9f4ee 100644 --- a/docs/zh-CN/plugins/codex-harness.md +++ b/docs/zh-CN/plugins/codex-harness.md @@ -1,73 +1,77 @@ --- read_when: - - 你想使用内置的 Codex 应用服务器测试工具 + - 你想使用内置的 Codex app-server harness - 你需要 Codex 模型引用和配置示例 - - 你想为仅使用 Codex 的部署禁用 Pi 回退机制 -summary: 通过内置的 Codex 应用服务器测试工具运行 OpenClaw 嵌入式智能体轮次 -title: Codex 测试工具 + - 你想为仅使用 Codex 的部署禁用 PI 回退 +summary: 通过内置的 Codex app-server harness 运行 OpenClaw 嵌入式智能体轮次 +title: Codex Harness x-i18n: - generated_at: "2026-04-23T16:04:44Z" + generated_at: "2026-04-23T19:25:20Z" model: gpt-5.4 provider: openai - source_hash: 07e7fb033cd4025e53d65a719bab7bd704335933bf19bfb10648cede42cdee46 + source_hash: 99ca00550be4e41aa154a99298e3e1b027f8199d541249149cb0ec722e035876 source_path: plugins/codex-harness.md workflow: 15 --- -# Codex 测试工具 +# Codex Harness -内置的 `codex` 插件让 OpenClaw 通过 Codex 应用服务器运行嵌入式智能体轮次，而不是使用内置的 Pi 测试工具。 +内置的 `codex` 插件让 OpenClaw 可以通过 Codex app-server，而不是内置的 PI harness，来运行嵌入式智能体轮次。 -当你希望由 Codex 接管底层智能体会话时，请使用此方式：模型发现、原生线程恢复、原生压缩以及应用服务器执行。 -OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、审批、媒体传递，以及可见的转录镜像。 +当你希望由 Codex 接管底层智能体会话时，请使用它：模型发现、原生线程恢复、原生压缩，以及 app-server 执行。 +OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、审批、媒体投递，以及可见的转录镜像。 -原生 Codex 轮次也会遵循共享的插件钩子，因此提示词 shim、感知压缩的自动化、工具中间件和生命周期观察器都会与 Pi 测试工具保持一致： +原生 Codex 轮次同样遵循共享插件钩子，因此 prompt shim、具备 compaction 感知的自动化、工具中间件和生命周期观察器都能与 PI harness 保持一致： - `before_prompt_build` -- `before_compaction`, `after_compaction` -- `llm_input`, `llm_output` -- `tool_result`, `after_tool_call` +- `before_compaction`、`after_compaction` +- `llm_input`、`llm_output` +- `tool_result`、`after_tool_call` - `before_message_write` - `agent_end` -内置插件还可以注册一个 Codex 应用服务器扩展工厂，以添加异步 `tool_result` 中间件。 +内置插件还可以注册一个 Codex app-server extension factory，以添加异步 `tool_result` 中间件。 -该测试工具默认关闭。只有在启用 `codex` 插件且解析后的模型是 `codex/*` 模型时，或者你显式强制设置 `embeddedHarness.runtime: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex` 时，才会选中它。 -如果你从未配置 `codex/*`，现有的 Pi、OpenAI、Anthropic、Gemini、本地和自定义提供商运行都会保持当前行为。 +该 harness 默认关闭。只有在启用了 `codex` 插件且解析后的模型是 `codex/*` 模型时，或者你显式强制设置 `embeddedHarness.runtime: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex` 时，才会选择它。 +如果你从未配置 `codex/*`，现有的 PI、OpenAI、Anthropic、Gemini、local 和自定义 provider 运行都会保持当前行为。 ## 选择正确的模型前缀 -OpenClaw 为 OpenAI 访问方式和 Codex 风格的访问方式提供了不同路径： +OpenClaw 为 OpenAI 访问和 Codex 形态的访问提供了不同路由： -| 模型引用 | 运行时路径 | 使用场景 | +| 模型引用 | 运行时路径 | 适用场景 | | ---------------------- | -------------------------------------------- | ----------------------------------------------------------------------- | -| `openai/gpt-5.4` | 通过 OpenClaw/Pi 流程的 OpenAI 提供商 | 你想通过 `OPENAI_API_KEY` 直接访问 OpenAI Platform API。 | -| `openai-codex/gpt-5.4` | 通过 Pi 的 OpenAI Codex OAuth 提供商 | 你想使用 ChatGPT/Codex OAuth，但不使用 Codex 应用服务器测试工具。 | -| `codex/gpt-5.4` | 内置 Codex 提供商加 Codex 测试工具 | 你希望嵌入式智能体轮次使用原生 Codex 应用服务器执行。 | +| `openai/gpt-5.5` | 通过 OpenClaw/PI 管线的 OpenAI provider | 你希望通过 `OPENAI_API_KEY` 直接访问 OpenAI Platform API。 | +| `openai-codex/gpt-5.5` | 通过 PI 的 OpenAI Codex OAuth provider | 你希望使用 ChatGPT/Codex OAuth，但不使用 Codex app-server harness。 | +| `codex/gpt-5.5` | 内置 Codex provider 加 Codex harness | 你希望嵌入式智能体轮次使用原生 Codex app-server 执行。 | -Codex 测试工具只会接管 `codex/*` 模型引用。现有的 `openai/*`、`openai-codex/*`、Anthropic、Gemini、xAI、本地和自定义提供商引用都会保持其正常路径。 +Codex harness 只接管 `codex/*` 模型引用。现有的 `openai/*`、`openai-codex/*`、Anthropic、Gemini、xAI、local 和自定义 provider 引用都会继续走各自的正常路径。 -测试工具选择不是实时会话控制。当嵌入式轮次运行时，OpenClaw 会在该会话上记录所选测试工具的 id，并在同一会话 id 的后续轮次中继续使用它。若你希望未来的会话使用另一种测试工具，请更改 `embeddedHarness` 配置或 `OPENCLAW_AGENT_RUNTIME`；在现有对话于 Pi 和 Codex 之间切换前，请使用 `/new` 或 `/reset` 启动一个新会话。 -这样可以避免同一份转录被重放到两个不兼容的原生会话系统中。 +Harness 选择不是实时会话控制。当嵌入式轮次运行时，OpenClaw 会在该会话上记录所选 harness ID，并在同一会话 ID 的后续轮次中持续使用它。 +当你希望未来的新会话使用其他 harness 时，请修改 `embeddedHarness` 配置或 `OPENCLAW_AGENT_RUNTIME`；在将现有对话从 PI 切换到 Codex 之前，请使用 `/new` 或 `/reset` 启动一个全新会话。 +这样可以避免将同一份转录通过两套不兼容的原生会话系统重放。 -在测试工具固定机制引入之前创建的旧会话，一旦已有转录历史，就会被视为固定到 Pi。更改配置后，使用 `/new` 或 `/reset` 可让该对话改为使用 Codex。 +在 harness 固定机制引入之前创建的旧会话，只要已有转录历史，就会被视为固定到 PI。 +更改配置后，使用 `/new` 或 `/reset` 可让该对话切换到 Codex。 -`/status` 会在 `Fast` 旁边显示生效的非 Pi 测试工具，例如 `Fast · codex`。默认的 Pi 测试工具不会显示。 +`/status` 会在 `Fast` 旁边显示生效中的非 PI harness，例如 `Fast · codex`。 +默认的 PI harness 不会显示。 ## 要求 -- OpenClaw，且可使用内置的 `codex` 插件。 -- Codex 应用服务器 `0.118.0` 或更高版本。 -- 应用服务器进程可用的 Codex 身份验证。 +- OpenClaw，并且可使用内置的 `codex` 插件。 +- Codex app-server `0.118.0` 或更高版本。 +- app-server 进程可用的 Codex 认证信息。 -该插件会阻止过旧或未标明版本的应用服务器握手。 -这样可以让 OpenClaw 保持在已验证过的协议范围内运行。 +该插件会阻止版本过旧或未提供版本信息的 app-server 握手。 +这样可以确保 OpenClaw 只运行在它已测试过的协议表面上。 -对于实时测试和 Docker 冒烟测试，身份验证通常来自 `OPENAI_API_KEY`，以及可选的 Codex CLI 文件，例如 `~/.codex/auth.json` 和 `~/.codex/config.toml`。请使用与你本地 Codex 应用服务器相同的认证材料。 +对于 live 和 Docker smoke 测试，认证通常来自 `OPENAI_API_KEY`，以及可选的 Codex CLI 文件，例如 `~/.codex/auth.json` 和 `~/.codex/config.toml`。 +请使用与你本地 Codex app-server 相同的认证材料。 ## 最小配置 -使用 `codex/gpt-5.4`，启用内置插件，并强制使用 `codex` 测试工具： +使用 `codex/gpt-5.5`，启用内置插件，并强制使用 `codex` harness： ```json5 { @@ -80,7 +84,7 @@ Codex 测试工具只会接管 `codex/*` 模型引用。现有的 `openai/*`、` }, agents: { defaults: { - model: "codex/gpt-5.4", + model: "codex/gpt-5.5", embeddedHarness: { runtime: "codex", fallback: "none", @@ -90,7 +94,7 @@ Codex 测试工具只会接管 `codex/*` 模型引用。现有的 `openai/*`、` } ``` -如果你的配置使用 `plugins.allow`，也要在其中加入 `codex`： +如果你的配置使用了 `plugins.allow`，也请把 `codex` 加进去： ```json5 { @@ -105,11 +109,12 @@ Codex 测试工具只会接管 `codex/*` 模型引用。现有的 `openai/*`、` } ``` -将 `agents.defaults.model` 或某个智能体模型设置为 `codex/` 时，也会自动启用内置的 `codex` 插件。在共享配置中，显式写出插件条目仍然很有用，因为这能清楚表明部署意图。 +将 `agents.defaults.model` 或某个智能体模型设置为 `codex/`，也会自动启用内置的 `codex` 插件。 +在共享配置中，显式写出插件条目仍然很有用，因为它能更清楚地表明部署意图。 -## 添加 Codex，但不替换其他模型 +## 在不替换其他模型的情况下添加 Codex -如果你希望 `codex/*` 模型使用 Codex，而其他模型仍使用 Pi，请保留 `runtime: "auto"`： +如果你希望 `codex/*` 模型使用 Codex，而其他所有模型继续使用 PI，请保持 `runtime: "auto"`： ```json5 { @@ -123,13 +128,13 @@ Codex 测试工具只会接管 `codex/*` 模型引用。现有的 `openai/*`、` agents: { defaults: { model: { - primary: "codex/gpt-5.4", - fallbacks: ["openai/gpt-5.4", "anthropic/claude-opus-4-6"], + primary: "codex/gpt-5.5", + fallbacks: ["openai/gpt-5.5", "anthropic/claude-opus-4-6"], }, models: { - "codex/gpt-5.4": { alias: "codex" }, + "codex/gpt-5.5": { alias: "codex" }, "codex/gpt-5.4-mini": { alias: "codex-mini" }, - "openai/gpt-5.4": { alias: "gpt" }, + "openai/gpt-5.5": { alias: "gpt" }, "anthropic/claude-opus-4-6": { alias: "opus" }, }, embeddedHarness: { @@ -141,22 +146,22 @@ Codex 测试工具只会接管 `codex/*` 模型引用。现有的 `openai/*`、` } ``` -采用这种配置时： +在这种配置下： -- `/model codex` 或 `/model codex/gpt-5.4` 会使用 Codex 应用服务器测试工具。 -- `/model gpt` 或 `/model openai/gpt-5.4` 会使用 OpenAI 提供商路径。 -- `/model opus` 会使用 Anthropic 提供商路径。 -- 如果选择的是非 Codex 模型，Pi 仍然会作为兼容性测试工具。 +- `/model codex` 或 `/model codex/gpt-5.5` 使用 Codex app-server harness。 +- `/model gpt` 或 `/model openai/gpt-5.5` 使用 OpenAI provider 路径。 +- `/model opus` 使用 Anthropic provider 路径。 +- 如果选择的是非 Codex 模型，PI 仍然是兼容性 harness。 -## 仅使用 Codex 的部署 +## 仅 Codex 部署 -当你需要证明每一次嵌入式智能体轮次都使用 Codex 测试工具时，请禁用 Pi 回退： +当你需要证明每一个嵌入式智能体轮次都使用 Codex harness 时，请禁用 PI 回退： ```json5 { agents: { defaults: { - model: "codex/gpt-5.4", + model: "codex/gpt-5.5", embeddedHarness: { runtime: "codex", fallback: "none", @@ -174,11 +179,11 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -禁用回退后，如果 Codex 插件被禁用、请求的模型不是 `codex/*` 引用、应用服务器版本过旧，或应用服务器无法启动，OpenClaw 都会尽早失败。 +禁用回退后，如果 Codex 插件被禁用、请求的模型不是 `codex/*` 引用、app-server 版本过旧，或者 app-server 无法启动，OpenClaw 都会尽早失败。 -## 按智能体使用 Codex +## 每智能体 Codex -你可以只让某一个智能体专用 Codex，而默认智能体仍保持正常的自动选择： +你可以让某一个智能体仅使用 Codex，而默认智能体仍保留正常的自动选择： ```json5 { @@ -198,7 +203,7 @@ openclaw gateway run { id: "codex", name: "Codex", - model: "codex/gpt-5.4", + model: "codex/gpt-5.5", embeddedHarness: { runtime: "codex", fallback: "none", @@ -209,14 +214,16 @@ openclaw gateway run } ``` -使用常规会话命令切换智能体和模型。`/new` 会创建一个新的 OpenClaw 会话，而 Codex 测试工具会按需为其创建或恢复配套的应用服务器线程。`/reset` 会清除该线程对应的 OpenClaw 会话绑定，并让下一轮再次根据当前配置解析测试工具。 +使用普通会话命令即可切换智能体和模型。 +`/new` 会创建一个新的 OpenClaw 会话，而 Codex harness 会按需创建或恢复其 sidecar app-server 线程。 +`/reset` 会清除该线程的 OpenClaw 会话绑定，并让下一轮根据当前配置重新解析 harness。 ## 模型发现 -默认情况下，Codex 插件会向应用服务器请求可用模型。 -如果发现失败或超时，它会使用内置的回退目录： +默认情况下，Codex 插件会向 app-server 请求可用模型。 +如果发现失败或超时，它会使用内置回退目录： -- `codex/gpt-5.4` +- `codex/gpt-5.5` - `codex/gpt-5.4-mini` - `codex/gpt-5.2` @@ -259,19 +266,20 @@ openclaw gateway run } ``` -## 应用服务器连接与策略 +## App-server 连接与策略 -默认情况下，插件会用以下命令在本地启动 Codex： +默认情况下，插件会使用以下命令在本地启动 Codex： ```bash codex app-server --listen stdio:// ``` -默认情况下，OpenClaw 会以 YOLO 模式启动本地 Codex 测试工具会话： +默认情况下，OpenClaw 会以 YOLO 模式启动本地 Codex harness 会话： `approvalPolicy: "never"`、`approvalsReviewer: "user"`，以及 -`sandbox: "danger-full-access"`。这是用于自主心跳的受信任本地操作员姿态：Codex 可以使用 shell 和网络工具，而不会因为无人响应的原生审批提示而中断。 +`sandbox: "danger-full-access"`。 +这是用于自治心跳的可信本地操作员姿态：Codex 可以使用 shell 和网络工具，而不会因为没有人可响应的原生审批提示而停下来。 -如果要启用由 Codex Guardian 审核的审批，请设置 `appServer.mode: +如果你想启用由 Codex guardian 审核的审批，请设置 `appServer.mode: "guardian"`： ```json5 @@ -292,11 +300,15 @@ codex app-server --listen stdio:// } ``` -Guardian 是原生的 Codex 审批审核器。当 Codex 请求离开沙箱、在工作区外写入，或添加诸如网络访问之类的权限时，Codex 会将该审批请求路由给一个审核子智能体，而不是向人工发出提示。审核器会应用 Codex 的风险框架，并批准或拒绝该具体请求。如果你希望比 YOLO 模式有更多防护措施，但仍需要无人值守的智能体持续推进，请使用 Guardian。 +Guardian 是原生 Codex 审批审核者。 +当 Codex 请求离开沙箱、在工作区外写入，或添加诸如网络访问之类的权限时，Codex 会将该审批请求路由给一个 reviewer 子智能体，而不是发给人工提示。 +该 reviewer 会应用 Codex 的风险框架，并批准或拒绝具体请求。 +如果你希望比 YOLO 模式有更多防护措施，但仍需要无人值守的智能体持续推进，请使用 Guardian。 -`guardian` 预设会展开为 `approvalPolicy: "on-request"`、`approvalsReviewer: "guardian_subagent"` 和 `sandbox: "workspace-write"`。各个策略字段仍会覆盖 `mode`，因此高级部署可以将该预设与显式选项混合使用。 +`guardian` 预设会展开为 `approvalPolicy: "on-request"`、`approvalsReviewer: "guardian_subagent"` 和 `sandbox: "workspace-write"`。 +各个单独的策略字段仍会覆盖 `mode`，因此高级部署可以将该预设与显式选择混合使用。 -对于已经在运行的应用服务器，请使用 WebSocket 传输： +对于已经在运行的 app-server，可使用 WebSocket 传输： ```json5 { @@ -323,19 +335,19 @@ Guardian 是原生的 Codex 审批审核器。当 Codex 请求离开沙箱、在 | 字段 | 默认值 | 含义 | | ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `transport` | `"stdio"` | `"stdio"` 会启动 Codex；`"websocket"` 会连接到 `url`。 | -| `command` | `"codex"` | 用于 stdio 传输的可执行文件。 | -| `args` | `["app-server", "--listen", "stdio://"]` | 用于 stdio 传输的参数。 | -| `url` | 未设置 | WebSocket 应用服务器 URL。 | -| `authToken` | 未设置 | 用于 WebSocket 传输的 Bearer token。 | -| `headers` | `{}` | 额外的 WebSocket 标头。 | -| `requestTimeoutMs` | `60000` | 应用服务器控制平面调用的超时时间。 | -| `mode` | `"yolo"` | 用于 YOLO 或 Guardian 审核执行的预设。 | -| `approvalPolicy` | `"never"` | 发送到线程启动/恢复/轮次的原生 Codex 审批策略。 | -| `sandbox` | `"danger-full-access"` | 发送到线程启动/恢复的原生 Codex 沙箱模式。 | -| `approvalsReviewer` | `"user"` | 使用 `"guardian_subagent"` 让 Codex Guardian 审核提示。 | -| `serviceTier` | 未设置 | 可选的 Codex 应用服务器服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧版值会被忽略。 | +| `command` | `"codex"` | `stdio` 传输使用的可执行文件。 | +| `args` | `["app-server", "--listen", "stdio://"]` | `stdio` 传输使用的参数。 | +| `url` | 未设置 | WebSocket app-server URL。 | +| `authToken` | 未设置 | WebSocket 传输使用的 Bearer token。 | +| `headers` | `{}` | 额外的 WebSocket headers。 | +| `requestTimeoutMs` | `60000` | app-server 控制平面调用的超时时间。 | +| `mode` | `"yolo"` | YOLO 或 guardian 审核执行的预设。 | +| `approvalPolicy` | `"never"` | 发送到线程 start/resume/turn 的原生 Codex 审批策略。 | +| `sandbox` | `"danger-full-access"` | 发送到线程 start/resume 的原生 Codex 沙箱模式。 | +| `approvalsReviewer` | `"user"` | 使用 `"guardian_subagent"` 可让 Codex Guardian 审核提示。 | +| `serviceTier` | 未设置 | 可选的 Codex app-server 服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧版值会被忽略。 | -当对应配置字段未设置时，较旧的环境变量仍可作为本地测试的回退方式： +当匹配的配置字段未设置时，较旧的环境变量仍可作为本地测试的回退方式： - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -344,13 +356,13 @@ Guardian 是原生的 Codex 审批审核器。当 Codex 请求离开沙箱、在 - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` `OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` 已被移除。请改用 -`plugins.entries.codex.config.appServer.mode: "guardian"`，或在一次性本地测试时使用 -`OPENCLAW_CODEX_APP_SERVER_MODE=guardian`。对于可重复部署，推荐使用配置， -因为这样可以将插件行为与 Codex 测试工具设置的其余部分放在同一个经过审查的文件中。 +`plugins.entries.codex.config.appServer.mode: "guardian"`，或在一次性本地测试中使用 +`OPENCLAW_CODEX_APP_SERVER_MODE=guardian`。对于可重复部署，优先使用配置， +因为这样能将插件行为与 Codex harness 其余设置放在同一个经过审查的文件中。 -## 常见用法 +## 常见配方 -使用默认 stdio 传输的本地 Codex： +使用默认 `stdio` 传输的本地 Codex： ```json5 { @@ -364,7 +376,7 @@ Guardian 是原生的 Codex 审批审核器。当 Codex 请求离开沙箱、在 } ``` -仅使用 Codex 的测试工具验证，禁用 Pi 回退： +仅 Codex harness 验证，并禁用 PI 回退： ```json5 { @@ -403,7 +415,7 @@ Guardian 是原生的 Codex 审批审核器。当 Codex 请求离开沙箱、在 } ``` -带显式标头的远程应用服务器： +带显式 headers 的远程 app-server： ```json5 { @@ -426,73 +438,72 @@ Guardian 是原生的 Codex 审批审核器。当 Codex 请求离开沙箱、在 } ``` -模型切换仍由 OpenClaw 控制。当一个 OpenClaw 会话附加到现有的 Codex 线程时， -下一轮会再次将当前选定的 `codex/*` 模型、提供商、审批策略、沙箱和服务层级发送给 -应用服务器。从 `codex/gpt-5.4` 切换到 `codex/gpt-5.2` 时，会保留线程绑定，但会要求 -Codex 使用新选定的模型继续执行。 +模型切换仍由 OpenClaw 控制。当一个 OpenClaw 会话附加到现有 Codex 线程时， +下一轮会再次把当前选中的 `codex/*` 模型、provider、审批策略、沙箱和服务层级发送给 +app-server。将 `codex/gpt-5.5` 切换到 `codex/gpt-5.2` 时，会保留线程绑定， +但会要求 Codex 使用新选择的模型继续执行。 ## Codex 命令 -内置插件将 `/codex` 注册为授权斜杠命令。它是通用的，可在任何支持 OpenClaw 文本命令的渠道中使用。 +内置插件会将 `/codex` 注册为一个已授权的斜杠命令。它是通用的，可在任何支持 OpenClaw 文本命令的渠道中使用。 常见形式： -- `/codex status` 显示实时应用服务器连接状态、模型、账户、速率限制、MCP 服务器和 skills。 -- `/codex models` 列出实时 Codex 应用服务器模型。 +- `/codex status` 显示实时 app-server 连接状态、模型、账户、速率限制、MCP 服务器和 Skills。 +- `/codex models` 列出实时 Codex app-server 模型。 - `/codex threads [filter]` 列出最近的 Codex 线程。 - `/codex resume ` 将当前 OpenClaw 会话附加到现有 Codex 线程。 -- `/codex compact` 请求 Codex 应用服务器压缩已附加的线程。 -- `/codex review` 为已附加的线程启动 Codex 原生审查。 +- `/codex compact` 请求 Codex app-server 压缩已附加线程。 +- `/codex review` 为已附加线程启动 Codex 原生审查。 - `/codex account` 显示账户和速率限制状态。 -- `/codex mcp` 列出 Codex 应用服务器 MCP 服务器状态。 -- `/codex skills` 列出 Codex 应用服务器 Skills。 +- `/codex mcp` 列出 Codex app-server MCP 服务器状态。 +- `/codex skills` 列出 Codex app-server Skills。 -`/codex resume` 会写入与测试工具正常轮次所使用的同一个配套绑定文件。 -在下一条消息中，OpenClaw 会恢复该 Codex 线程，将当前选定的 OpenClaw `codex/*` -模型传入应用服务器，并保持启用扩展历史记录。 +`/codex resume` 会写入与 harness 正常轮次相同的 sidecar 绑定文件。 +在下一条消息时，OpenClaw 会恢复该 Codex 线程，将当前选中的 OpenClaw `codex/*` 模型传入 app-server，并保持扩展历史记录启用。 -该命令功能要求 Codex 应用服务器版本为 `0.118.0` 或更高。如果未来版本或自定义的应用服务器 -未暴露某个 JSON-RPC 方法，各个控制方法会显示为 `unsupported by this Codex app-server`。 +该命令面要求 Codex app-server `0.118.0` 或更高版本。如果未来版本或自定义 app-server 未暴露某个 JSON-RPC 方法，则各个控制方法会显示为 `unsupported by this Codex app-server`。 ## 工具、媒体与压缩 -Codex 测试工具仅改变底层嵌入式智能体执行器。 +Codex harness 只会改变底层嵌入式智能体执行器。 -OpenClaw 仍然构建工具列表，并从测试工具接收动态工具结果。文本、图像、视频、音乐、TTS、 -审批和消息工具输出会继续通过正常的 OpenClaw 传递路径处理。 +OpenClaw 仍然会构建工具列表，并从 harness 接收动态工具结果。文本、图像、视频、音乐、TTS、审批以及消息工具输出，都会继续通过 OpenClaw 的常规投递路径传输。 -当 Codex 将 `_meta.codex_approval_kind` 标记为 `"mcp_tool_call"` 时，Codex MCP 工具审批请求会通过 OpenClaw 的插件审批流程路由；其他请求输入和自由格式输入请求仍会以失败关闭的方式处理。 +当 Codex 将 `_meta.codex_approval_kind` 标记为 +`"mcp_tool_call"` 时，Codex MCP 工具审批请求会通过 OpenClaw 的插件审批流程进行路由； +其他请求输入和自由格式输入请求仍然会以失败关闭方式处理。 -当所选模型使用 Codex 测试工具时，原生线程压缩会委托给 Codex 应用服务器。OpenClaw 会保留一份转录镜像，用于渠道历史记录、搜索、`/new`、`/reset`，以及未来的模型或测试工具切换。该镜像包括用户提示、最终助手文本，以及在应用服务器发出时包含轻量级的 Codex 推理或计划记录。目前，OpenClaw 只记录原生压缩开始和完成信号。它尚未提供人类可读的压缩摘要，也未提供 Codex 在压缩后保留了哪些条目的可审计列表。 +当所选模型使用 Codex harness 时，原生线程压缩会委托给 Codex app-server。 +OpenClaw 会继续保留一个转录镜像，用于渠道历史记录、搜索、`/new`、`/reset`，以及未来的模型或 harness 切换。该镜像包含用户提示、最终助手文本，以及 app-server 发出时的轻量级 Codex 推理或计划记录。当前，OpenClaw 只记录原生压缩开始和完成信号。它尚未提供人类可读的压缩摘要，也未提供一份可审计清单来说明压缩后 Codex 保留了哪些条目。 -媒体生成不需要 Pi。图像、视频、音乐、PDF、TTS 和媒体理解会继续使用相应的提供商/模型设置，例如 `agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和 `messages.tts`。 +媒体生成不需要 PI。图像、视频、音乐、PDF、TTS 和媒体理解仍会使用相应的 provider/模型设置，例如 `agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和 `messages.tts`。 ## 故障排除 -**`/model` 中未显示 Codex：** 启用 `plugins.entries.codex.enabled`， +**`/model` 中没有出现 Codex：** 启用 `plugins.entries.codex.enabled`， 设置一个 `codex/*` 模型引用，或检查 `plugins.allow` 是否排除了 `codex`。 -**OpenClaw 使用的是 Pi 而不是 Codex：** 如果没有 Codex 测试工具接管该运行， -OpenClaw 可能会使用 Pi 作为兼容性后端。测试时设置 +**OpenClaw 使用的是 PI 而不是 Codex：** 如果没有 Codex harness 接管该运行， +OpenClaw 可能会将 PI 用作兼容性后端。测试时请设置 `embeddedHarness.runtime: "codex"` 以强制选择 Codex，或设置 -`embeddedHarness.fallback: "none"` 以在没有匹配的插件测试工具时直接失败。 -一旦选中了 Codex 应用服务器，它的失败会直接暴露出来，无需额外的回退配置。 +`embeddedHarness.fallback: "none"` 以在没有插件 harness 匹配时直接失败。一旦选中 Codex app-server，其失败会直接暴露出来，而不会再经过额外的回退配置。 -**应用服务器被拒绝：** 升级 Codex，使应用服务器握手报告版本 +**app-server 被拒绝：** 升级 Codex，使 app-server 握手报告版本为 `0.118.0` 或更高。 -**模型发现很慢：** 降低 `plugins.entries.codex.config.discovery.timeoutMs` +**模型发现太慢：** 降低 `plugins.entries.codex.config.discovery.timeoutMs` 或禁用发现。 **WebSocket 传输立即失败：** 检查 `appServer.url`、`authToken`， -并确认远程应用服务器使用相同的 Codex 应用服务器协议版本。 +以及远程 app-server 是否使用相同版本的 Codex app-server 协议。 -**非 Codex 模型使用了 Pi：** 这是预期行为。Codex 测试工具只会接管 +**非 Codex 模型使用了 PI：** 这是预期行为。Codex harness 只接管 `codex/*` 模型引用。 ## 相关内容 -- [智能体测试工具插件](/zh-CN/plugins/sdk-agent-harness) +- [智能体 Harness 插件](/zh-CN/plugins/sdk-agent-harness) - [模型提供商](/zh-CN/concepts/model-providers) - [配置参考](/zh-CN/gateway/configuration-reference) - [测试](/zh-CN/help/testing#live-codex-app-server-harness-smoke) diff --git a/docs/zh-CN/plugins/manifest.md b/docs/zh-CN/plugins/manifest.md index 073941b6c..31d5feffe 100644 --- a/docs/zh-CN/plugins/manifest.md +++ b/docs/zh-CN/plugins/manifest.md @@ -1,55 +1,65 @@ --- read_when: - 你正在构建一个 OpenClaw 插件 - - 你需要发布一个插件配置 schema，或调试插件校验错误 -summary: 插件清单 + JSON schema 要求（严格配置校验） + - 你需要提供插件配置 schema，或调试插件验证错误 +summary: 插件清单 + JSON schema 要求（严格配置验证） title: 插件清单 x-i18n: - generated_at: "2026-04-23T16:56:50Z" + generated_at: "2026-04-23T19:25:24Z" model: gpt-5.4 provider: openai - source_hash: e9e7bca47b076cc49080bd6921ef9d295c840e9a19c5271dbfea83d9882ea404 + source_hash: 4dd7c7e91637ff93ea60ee5d8069a9263382749435ca22a804fece05fc5f94ac source_path: plugins/manifest.md workflow: 15 --- # 插件清单（`openclaw.plugin.json`） -本页仅适用于 **OpenClaw 原生插件清单**。 +本页仅适用于**原生 OpenClaw 插件清单**。 -有关兼容的 bundle 布局，请参阅 [插件 bundle](/zh-CN/plugins/bundles)。 +有关兼容的 bundle 布局，请参见 [插件 bundles](/zh-CN/plugins/bundles)。 兼容的 bundle 格式使用不同的清单文件： - Codex bundle：`.codex-plugin/plugin.json` -- Claude bundle：`.claude-plugin/plugin.json`，或不带清单的默认 Claude 组件布局 +- Claude bundle：`.claude-plugin/plugin.json`，或不带清单的默认 Claude 组件 + 布局 - Cursor bundle：`.cursor-plugin/plugin.json` -OpenClaw 也会自动检测这些 bundle 布局，但不会根据此处描述的 `openclaw.plugin.json` schema 对它们进行校验。 +OpenClaw 也会自动检测这些 bundle 布局，但不会按照此处描述的 `openclaw.plugin.json` schema +对它们进行验证。 -对于兼容 bundle，OpenClaw 当前会在布局符合 OpenClaw 运行时预期时，读取 bundle 元数据，以及已声明的 skill 根目录、Claude 命令根目录、Claude bundle `settings.json` 默认值、Claude bundle LSP 默认值和受支持的 hook 包。 +对于兼容 bundle，当前在布局符合 OpenClaw 运行时预期时， +OpenClaw 会读取 bundle 元数据、已声明的 skill 根目录、Claude 命令根目录、Claude bundle 的 `settings.json` 默认值、 +Claude bundle 的 LSP 默认值，以及受支持的 hook pack。 -每个原生 OpenClaw 插件都 **必须** 在**插件根目录**中提供一个 `openclaw.plugin.json` 文件。OpenClaw 使用此清单在**不执行插件代码的情况下**验证配置。缺失或无效的清单会被视为插件错误，并阻止配置校验。 +每个原生 OpenClaw 插件**都必须**在 +**插件根目录**中提供一个 `openclaw.plugin.json` 文件。OpenClaw 使用此清单在**不执行插件代码** +的情况下验证配置。缺失或无效的清单会被视为 +插件错误，并阻止配置验证。 -查看完整的插件系统指南：[插件](/zh-CN/tools/plugin)。 -有关原生能力模型以及当前外部兼容性指导，请参阅： +请参见完整的插件系统指南：[插件](/zh-CN/tools/plugin)。 +有关原生能力模型和当前的外部兼容性指引： [能力模型](/zh-CN/plugins/architecture#public-capability-model)。 ## 此文件的作用 -`openclaw.plugin.json` 是 OpenClaw 在**加载你的插件代码之前**读取的元数据。以下所有内容都必须足够轻量，以便在不启动插件运行时的情况下进行检查。 +`openclaw.plugin.json` 是 OpenClaw 在**加载你的 +插件代码之前**读取的元数据。下面的所有内容都必须足够轻量，以便在不启动 +插件运行时的情况下进行检查。 -**用于：** +**可用于：** -- 插件标识、配置校验和配置 UI 提示 +- 插件标识、配置验证和配置 UI 提示 - 认证、新手引导和设置元数据（别名、自动启用、提供商环境变量、认证选项） - 控制平面界面的激活提示 -- 简写模型家族归属 +- 简写模型系列归属 - 静态能力归属快照（`contracts`） -- 共享 `openclaw qa` 主机可检查的 QA 运行器元数据 -- 合并到目录和校验界面中的渠道专用配置元数据 +- 供共享 `openclaw qa` 主机检查的 QA 运行器元数据 +- 合并到目录和验证界面中的渠道专用配置元数据 -**不要用于：** 注册运行时行为、声明代码入口点，或 npm 安装元数据。这些应放在你的插件代码和 `package.json` 中。 +**不要用于：**注册运行时行为、声明代码入口点， +或 npm 安装元数据。这些应放在你的插件代码和 `package.json` 中。 ## 最小示例 @@ -132,62 +142,64 @@ OpenClaw 也会自动检测这些 bundle 布局，但不会根据此处描述的 | 字段 | 必填 | 类型 | 含义 | | ------------------------------------ | -------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | 是 | `string` | 规范插件 id。这是在 `plugins.entries.` 中使用的 id。 | -| `configSchema` | 是 | `object` | 此插件配置的内联 JSON Schema。 | -| `enabledByDefault` | 否 | `true` | 将内置插件标记为默认启用。省略此字段，或将其设为任何非 `true` 的值，则该插件默认保持禁用。 | -| `legacyPluginIds` | 否 | `string[]` | 会规范化为此规范插件 id 的旧版 id。 | +| `configSchema` | 是 | `object` | 该插件配置的内联 JSON Schema。 | +| `enabledByDefault` | 否 | `true` | 将某个内置插件标记为默认启用。省略它，或设置为任何非 `true` 的值，以使插件默认保持禁用。 | +| `legacyPluginIds` | 否 | `string[]` | 会被标准化为此规范插件 id 的旧版 id。 | | `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当认证、配置或模型引用提到这些提供商 id 时，应自动启用此插件。 | -| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明一个由 `plugins.slots.*` 使用的互斥插件类型。 | -| `channels` | 否 | `string[]` | 由此插件拥有的渠道 id。用于设备发现和配置校验。 | +| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明由 `plugins.slots.*` 使用的互斥插件类型。 | +| `channels` | 否 | `string[]` | 由此插件拥有的渠道 id。用于发现和配置验证。 | | `providers` | 否 | `string[]` | 由此插件拥有的提供商 id。 | -| `modelSupport` | 否 | `object` | 由清单拥有的简写模型家族元数据，用于在运行时之前自动加载插件。 | -| `providerEndpoints` | 否 | `object[]` | 由清单拥有的 endpoint 主机 / `baseUrl` 元数据，用于核心在提供商运行时加载前对提供商路由进行分类。 | -| `cliBackends` | 否 | `string[]` | 由此插件拥有的 CLI 推理后端 id。用于在显式配置引用时于启动阶段自动激活。 | -| `syntheticAuthRefs` | 否 | `string[]` | 在运行时加载前的冷启动模型发现期间，应探测其插件自有 synthetic auth hook 的提供商或 CLI 后端引用。 | -| `nonSecretAuthMarkers` | 否 | `string[]` | 由内置插件拥有的占位 API key 值，表示非秘密的本地、OAuth 或环境凭证状态。 | -| `commandAliases` | 否 | `object[]` | 由此插件拥有的命令名称，应在运行时加载前产生具备插件感知的配置和 CLI 诊断信息。 | -| `providerAuthEnvVars` | 否 | `Record` | OpenClaw 可在不加载插件代码的情况下检查的轻量提供商认证环境变量元数据。 | -| `providerAuthAliases` | 否 | `Record` | 应复用另一个提供商 id 进行认证查找的提供商 id，例如共享基础提供商 API key 和认证配置文件的编码提供商。 | -| `channelEnvVars` | 否 | `Record` | OpenClaw 可在不加载插件代码的情况下检查的轻量渠道环境变量元数据。将其用于由环境变量驱动的渠道设置或认证界面，以便通用启动 / 配置辅助逻辑能够识别。 | -| `providerAuthChoices` | 否 | `object[]` | 用于新手引导选择器、首选提供商解析和简单 CLI 标志接线的轻量认证选项元数据。 | -| `activation` | 否 | `object` | 用于提供商、命令、渠道、路由和能力触发加载的轻量激活提示。仅为元数据；插件运行时仍拥有实际行为。 | -| `setup` | 否 | `object` | 供设备发现和设置界面在不加载插件运行时的情况下检查的轻量设置 / 新手引导描述符。 | -| `qaRunners` | 否 | `object[]` | 由共享 `openclaw qa` 主机在插件运行时加载前使用的轻量 QA 运行器描述符。 | -| `contracts` | 否 | `object` | 外部认证 hook、speech、实时转录、实时语音、媒体理解、图像生成、音乐生成、视频生成、网页抓取、网页搜索和工具归属的静态内置能力快照。 | -| `mediaUnderstandingProviderMetadata` | 否 | `Record` | 为 `contracts.mediaUnderstandingProviders` 中声明的提供商 id 提供的轻量媒体理解默认元数据。 | -| `channelConfigs` | 否 | `Record` | 由清单拥有的渠道配置元数据，在运行时加载前合并到设备发现和校验界面中。 | +| `modelSupport` | 否 | `object` | 由清单拥有的简写模型系列元数据，用于在运行时之前自动加载插件。 | +| `providerEndpoints` | 否 | `object[]` | 由清单拥有的端点 host / baseUrl 元数据，用于那些在提供商运行时加载前，核心必须先分类的提供商路由。 | +| `cliBackends` | 否 | `string[]` | 由此插件拥有的 CLI 推理后端 id。用于根据显式配置引用在启动时自动激活。 | +| `syntheticAuthRefs` | 否 | `string[]` | 在运行时加载前进行冷启动模型发现时，需探测其由插件拥有的 synthetic auth hook 的提供商或 CLI 后端引用。 | +| `nonSecretAuthMarkers` | 否 | `string[]` | 由内置插件拥有的占位 API 密钥值，表示非机密的本地、OAuth 或环境凭证状态。 | +| `commandAliases` | 否 | `object[]` | 由此插件拥有的命令名称，在运行时加载前，这些命令应产生带有插件感知的配置和 CLI 诊断信息。 | +| `providerAuthEnvVars` | 否 | `Record` | OpenClaw 可在不加载插件代码的情况下检查的轻量级提供商认证环境变量元数据。 | +| `providerAuthAliases` | 否 | `Record` | 应复用另一个提供商 id 进行认证查找的提供商 id，例如与基础提供商共享 API 密钥和 auth profile 的编码提供商。 | +| `channelEnvVars` | 否 | `Record` | OpenClaw 可在不加载插件代码的情况下检查的轻量级渠道环境变量元数据。将其用于通用启动 / 配置辅助工具需要识别的、由环境变量驱动的渠道设置或认证界面。 | +| `providerAuthChoices` | 否 | `object[]` | 用于新手引导选择器、首选提供商解析和简单 CLI flag 绑定的轻量级认证选项元数据。 | +| `activation` | 否 | `object` | 用于提供商、命令、渠道、路由和能力触发加载的轻量级激活提示。仅为元数据；实际行为仍由插件运行时负责。 | +| `setup` | 否 | `object` | 供发现和设置界面在不加载插件运行时的情况下检查的轻量级设置 / 新手引导描述符。 | +| `qaRunners` | 否 | `object[]` | 共享 `openclaw qa` 主机在插件运行时加载前使用的轻量级 QA 运行器描述符。 | +| `contracts` | 否 | `object` | 面向外部认证 hook、语音、实时转录、实时语音、媒体理解、图像生成、音乐生成、视频生成、网页抓取、Web 搜索和工具归属的静态内置能力快照。 | +| `mediaUnderstandingProviderMetadata` | 否 | `Record` | 为 `contracts.mediaUnderstandingProviders` 中声明的提供商 id 提供的轻量级媒体理解默认元数据。 | +| `channelConfigs` | 否 | `Record` | 在运行时加载前，合并到发现和验证界面中的、由清单拥有的渠道配置元数据。 | | `skills` | 否 | `string[]` | 要加载的 Skills 目录，相对于插件根目录。 | | `name` | 否 | `string` | 人类可读的插件名称。 | -| `description` | 否 | `string` | 显示在插件界面中的简短摘要。 | +| `description` | 否 | `string` | 在插件界面中显示的简短摘要。 | | `version` | 否 | `string` | 信息性插件版本。 | | `uiHints` | 否 | `Record` | 配置字段的 UI 标签、占位符和敏感性提示。 | ## `providerAuthChoices` 参考 每个 `providerAuthChoices` 条目描述一个新手引导或认证选项。 -OpenClaw 会在提供商运行时加载前读取它。 +OpenClaw 会在提供商运行时加载之前读取它。 | 字段 | 必填 | 类型 | 含义 | | --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `provider` | 是 | `string` | 此选项所属的提供商 id。 | -| `method` | 是 | `string` | 要分派到的认证方法 id。 | +| `method` | 是 | `string` | 要分发到的认证方法 id。 | | `choiceId` | 是 | `string` | 供新手引导和 CLI 流程使用的稳定认证选项 id。 | -| `choiceLabel` | 否 | `string` | 面向用户的标签。如果省略，OpenClaw 会回退到 `choiceId`。 | -| `choiceHint` | 否 | `string` | 选择器的简短辅助文本。 | +| `choiceLabel` | 否 | `string` | 面向用户的标签。若省略，OpenClaw 会回退为 `choiceId`。 | +| `choiceHint` | 否 | `string` | 选择器中的简短辅助文本。 | | `assistantPriority` | 否 | `number` | 在由助手驱动的交互式选择器中，值越小排序越靠前。 | | `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 在助手选择器中隐藏该选项，但仍允许手动通过 CLI 选择。 | | `deprecatedChoiceIds` | 否 | `string[]` | 应将用户重定向到此替代选项的旧版选项 id。 | -| `groupId` | 否 | `string` | 用于对相关选项分组的可选组 id。 | -| `groupLabel` | 否 | `string` | 该组的面向用户标签。 | -| `groupHint` | 否 | `string` | 该组的简短辅助文本。 | -| `optionKey` | 否 | `string` | 用于简单单标志认证流程的内部选项键。 | -| `cliFlag` | 否 | `string` | CLI 标志名称，例如 `--openrouter-api-key`。 | +| `groupId` | 否 | `string` | 用于分组相关选项的可选分组 id。 | +| `groupLabel` | 否 | `string` | 该分组面向用户的标签。 | +| `groupHint` | 否 | `string` | 该分组的简短辅助文本。 | +| `optionKey` | 否 | `string` | 用于简单单 flag 认证流程的内部选项键。 | +| `cliFlag` | 否 | `string` | CLI flag 名称，例如 `--openrouter-api-key`。 | | `cliOption` | 否 | `string` | 完整 CLI 选项形式，例如 `--openrouter-api-key `。 | -| `cliDescription` | 否 | `string` | 用于 CLI 帮助中的说明。 | -| `onboardingScopes` | 否 | `Array<"text-inference" \| "image-generation">` | 此选项应出现在哪些新手引导界面中。如果省略，默认值为 `["text-inference"]`。 | +| `cliDescription` | 否 | `string` | 用于 CLI 帮助中的描述。 | +| `onboardingScopes` | 否 | `Array<"text-inference" \| "image-generation">` | 此选项应显示在哪些新手引导界面中。若省略，默认值为 `["text-inference"]`。 | ## `commandAliases` 参考 -当插件拥有一个运行时命令名称，而用户可能会误将其放入 `plugins.allow`，或尝试将其作为根 CLI 命令运行时，请使用 `commandAliases`。OpenClaw 使用此元数据在不导入插件运行时代码的情况下提供诊断信息。 +当插件拥有一个运行时命令名，而用户可能 +错误地将其放入 `plugins.allow` 或尝试将其作为根 CLI 命令运行时，请使用 `commandAliases`。OpenClaw +使用此元数据在不导入插件运行时代码的情况下提供诊断信息。 ```json { @@ -205,15 +217,18 @@ OpenClaw 会在提供商运行时加载前读取它。 | ------------ | -------- | ----------------- | ----------------------------------------------------------------------- | | `name` | 是 | `string` | 属于此插件的命令名称。 | | `kind` | 否 | `"runtime-slash"` | 将该别名标记为聊天斜杠命令，而不是根 CLI 命令。 | -| `cliCommand` | 否 | `string` | 若存在相关根 CLI 命令，则建议用于 CLI 操作的该命令。 | +| `cliCommand` | 否 | `string` | 若存在，用于建议给 CLI 操作的相关根 CLI 命令。 | ## `activation` 参考 -当插件可以以低成本声明哪些控制平面事件应在之后激活它时，请使用 `activation`。 +当插件能够以低成本声明后续哪些控制平面事件 +应激活它时，请使用 `activation`。 ## `qaRunners` 参考 -当插件在共享的 `openclaw qa` 根命令下提供一个或多个传输运行器时，请使用 `qaRunners`。保持此元数据轻量且静态；插件运行时仍通过导出 `qaRunnerCliRegistrations` 的轻量 `runtime-api.ts` 界面拥有实际 CLI 注册逻辑。 +当插件在共享 `openclaw qa` 根命令下贡献一个或多个传输运行器时，请使用 `qaRunners`。保持此元数据轻量且静态；实际的 CLI 注册仍由插件 +运行时通过导出 `qaRunnerCliRegistrations` 的轻量级 +`runtime-api.ts` 接口负责。 ```json { @@ -229,11 +244,13 @@ OpenClaw 会在提供商运行时加载前读取它。 | 字段 | 必填 | 类型 | 含义 | | ------------- | -------- | -------- | ------------------------------------------------------------------ | | `commandName` | 是 | `string` | 挂载在 `openclaw qa` 下的子命令，例如 `matrix`。 | -| `description` | 否 | `string` | 当共享主机需要一个存根命令时使用的回退帮助文本。 | +| `description` | 否 | `string` | 当共享主机需要一个占位命令时使用的回退帮助文本。 | -此块仅为元数据。它不会注册运行时行为，也不会替代 `register(...)`、`setupEntry` 或其他运行时 / 插件入口点。 - -当前消费者会将其用作在更广泛插件加载前的缩小范围提示，因此缺少激活元数据通常只会带来性能成本；只要旧版清单归属回退仍然存在，它就不应影响正确性。 +这个区块仅是元数据。它不会注册运行时行为，也 +不会替代 `register(...)`、`setupEntry` 或其他运行时 / 插件入口点。 +当前使用方将其作为在更广泛插件加载前缩小范围的提示，因此 +缺失激活元数据通常只会带来性能损耗；在旧版清单归属回退仍存在时， +它不应改变正确性。 ```json { @@ -249,21 +266,25 @@ OpenClaw 会在提供商运行时加载前读取它。 | 字段 | 必填 | 类型 | 含义 | | ---------------- | -------- | ---------------------------------------------------- | ----------------------------------------------------------------- | -| `onProviders` | 否 | `string[]` | 请求这些提供商 id 时应激活此插件。 | +| `onProviders` | 否 | `string[]` | 当请求这些提供商 id 时，应激活此插件。 | | `onCommands` | 否 | `string[]` | 应激活此插件的命令 id。 | | `onChannels` | 否 | `string[]` | 应激活此插件的渠道 id。 | | `onRoutes` | 否 | `string[]` | 应激活此插件的路由类型。 | -| `onCapabilities` | 否 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 控制平面激活规划使用的广义能力提示。 | +| `onCapabilities` | 否 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 控制平面激活规划使用的宽泛能力提示。 | -当前在线使用方： +当前实时使用方： -- 由命令触发的 CLI 规划会回退到旧版 `commandAliases[].cliCommand` 或 `commandAliases[].name` -- 当缺少显式渠道激活元数据时，由渠道触发的设置 / 渠道规划会回退到旧版 `channels[]` 归属 -- 当缺少显式提供商激活元数据时，由提供商触发的设置 / 运行时规划会回退到旧版 `providers[]` 和顶层 `cliBackends[]` 归属 +- 由命令触发的 CLI 规划会回退到旧版 + `commandAliases[].cliCommand` 或 `commandAliases[].name` +- 当缺少显式渠道激活元数据时，渠道触发的设置 / 渠道规划会回退到旧版 `channels[]` + 归属 +- 当缺少显式提供商激活元数据时，提供商触发的设置 / 运行时规划会回退到旧版 + `providers[]` 和顶层 `cliBackends[]` 归属 ## `setup` 参考 -当设置和新手引导界面需要在运行时加载前读取轻量、由插件拥有的元数据时，请使用 `setup`。 +当设置和新手引导界面在运行时加载前需要轻量级、由插件拥有的元数据时， +请使用 `setup`。 ```json { @@ -282,18 +303,25 @@ OpenClaw 会在提供商运行时加载前读取它。 } ``` -顶层 `cliBackends` 仍然有效，并继续描述 CLI 推理后端。`setup.cliBackends` 是控制平面 / 设置流程的设置专用描述符界面，应保持为纯元数据。 +顶层 `cliBackends` 仍然有效，并继续描述 CLI 推理 +后端。`setup.cliBackends` 是面向控制平面 / 设置流程的 +设置专用描述符接口，应保持仅元数据。 -如果存在，`setup.providers` 和 `setup.cliBackends` 是设置发现时首选的描述符优先查找界面。如果该描述符只用于缩小候选插件范围，而设置仍需要更丰富的设置期运行时 hook，请将 `requiresRuntime` 设为 `true`，并保留 `setup-api` 作为回退执行路径。 +存在时，`setup.providers` 和 `setup.cliBackends` 是设置发现时首选的 +“描述符优先”查找接口。如果描述符只能缩小候选插件范围，而设置仍需要更丰富的设置期运行时 hook， +请设置 `requiresRuntime: true`，并保留 `setup-api` 作为 +回退执行路径。 -由于设置查找可能会执行插件拥有的 `setup-api` 代码，规范化后的 `setup.providers[].id` 和 `setup.cliBackends[]` 值必须在已发现插件之间保持唯一。归属不明确时会默认失败关闭，而不是按发现顺序选出一个赢家。 +由于设置查找可能执行由插件拥有的 `setup-api` 代码， +标准化后的 `setup.providers[].id` 和 `setup.cliBackends[]` 值必须在所有已发现插件中保持唯一。 +归属不明确时会以保守方式失败关闭，而不是按发现顺序挑选赢家。 ### `setup.providers` 参考 | 字段 | 必填 | 类型 | 含义 | | ------------- | -------- | ---------- | ------------------------------------------------------------------------------------ | -| `id` | 是 | `string` | 在设置或新手引导期间暴露的提供商 id。保持规范化 id 在全局唯一。 | -| `authMethods` | 否 | `string[]` | 此提供商在不加载完整运行时的情况下支持的设置 / 认证方法 id。 | +| `id` | 是 | `string` | 在设置或新手引导期间暴露的提供商 id。保持标准化 id 在全局范围内唯一。 | +| `authMethods` | 否 | `string[]` | 该提供商在不加载完整运行时的情况下支持的设置 / 认证方法 id。 | | `envVars` | 否 | `string[]` | 通用设置 / 状态界面可在插件运行时加载前检查的环境变量。 | ### `setup` 字段 @@ -301,13 +329,13 @@ OpenClaw 会在提供商运行时加载前读取它。 | 字段 | 必填 | 类型 | 含义 | | ------------------ | -------- | ---------- | --------------------------------------------------------------------------------------------------- | | `providers` | 否 | `object[]` | 在设置和新手引导期间暴露的提供商设置描述符。 | -| `cliBackends` | 否 | `string[]` | 用于描述符优先设置查找的设置期后端 id。保持规范化 id 在全局唯一。 | -| `configMigrations` | 否 | `string[]` | 由此插件设置界面拥有的配置迁移 id。 | +| `cliBackends` | 否 | `string[]` | 用于“描述符优先”设置查找的设置期后端 id。保持标准化 id 在全局范围内唯一。 | +| `configMigrations` | 否 | `string[]` | 由此插件的设置界面拥有的配置迁移 id。 | | `requiresRuntime` | 否 | `boolean` | 在描述符查找之后，设置是否仍需要执行 `setup-api`。 | ## `uiHints` 参考 -`uiHints` 是从配置字段名称到小型渲染提示的映射。 +`uiHints` 是从配置字段名到小型渲染提示的映射。 ```json { @@ -328,14 +356,15 @@ OpenClaw 会在提供商运行时加载前读取它。 | ------------- | ---------- | --------------------------------------- | | `label` | `string` | 面向用户的字段标签。 | | `help` | `string` | 简短辅助文本。 | -| `tags` | `string[]` | 可选 UI 标签。 | -| `advanced` | `boolean` | 将该字段标记为高级。 | -| `sensitive` | `boolean` | 将该字段标记为密钥或敏感信息。 | +| `tags` | `string[]` | 可选的 UI 标签。 | +| `advanced` | `boolean` | 将该字段标记为高级项。 | +| `sensitive` | `boolean` | 将该字段标记为机密或敏感。 | | `placeholder` | `string` | 表单输入的占位文本。 | ## `contracts` 参考 -仅将 `contracts` 用于 OpenClaw 可在不导入插件运行时的情况下读取的静态能力归属元数据。 +仅在 OpenClaw 可以在不导入插件运行时的情况下 +读取静态能力归属元数据时，才使用 `contracts`。 ```json { @@ -360,22 +389,28 @@ OpenClaw 会在提供商运行时加载前读取它。 | 字段 | 类型 | 含义 | | -------------------------------- | ---------- | ----------------------------------------------------------------- | | `embeddedExtensionFactories` | `string[]` | 内置插件可为其注册工厂的嵌入式运行时 id。 | -| `externalAuthProviders` | `string[]` | 此插件拥有其外部认证配置文件 hook 的提供商 id。 | -| `speechProviders` | `string[]` | 此插件拥有的 speech 提供商 id。 | +| `externalAuthProviders` | `string[]` | 此插件拥有其外部认证 profile hook 的提供商 id。 | +| `speechProviders` | `string[]` | 此插件拥有的语音提供商 id。 | | `realtimeTranscriptionProviders` | `string[]` | 此插件拥有的实时转录提供商 id。 | | `realtimeVoiceProviders` | `string[]` | 此插件拥有的实时语音提供商 id。 | | `mediaUnderstandingProviders` | `string[]` | 此插件拥有的媒体理解提供商 id。 | | `imageGenerationProviders` | `string[]` | 此插件拥有的图像生成提供商 id。 | | `videoGenerationProviders` | `string[]` | 此插件拥有的视频生成提供商 id。 | | `webFetchProviders` | `string[]` | 此插件拥有的网页抓取提供商 id。 | -| `webSearchProviders` | `string[]` | 此插件拥有的网页搜索提供商 id。 | -| `tools` | `string[]` | 此插件为内置合约检查所拥有的智能体工具名称。 | +| `webSearchProviders` | `string[]` | 此插件拥有的 Web 搜索提供商 id。 | +| `tools` | `string[]` | 此插件为内置契约检查所拥有的智能体工具名称。 | -实现 `resolveExternalAuthProfiles` 的提供商插件应声明 `contracts.externalAuthProviders`。未声明的插件仍会通过已弃用的兼容性回退路径运行，但该回退更慢，并将在迁移窗口结束后移除。 +实现 `resolveExternalAuthProfiles` 的提供商插件应声明 +`contracts.externalAuthProviders`。未声明该项的插件仍会通过 +已弃用的兼容性回退路径运行，但该回退更慢， +并将在迁移窗口结束后移除。 ## `mediaUnderstandingProviderMetadata` 参考 -当媒体理解提供商具有默认模型、自动认证回退优先级，或通用核心辅助逻辑在运行时加载前所需的原生文档支持时，请使用 `mediaUnderstandingProviderMetadata`。键名也必须在 `contracts.mediaUnderstandingProviders` 中声明。 +当媒体理解提供商具有默认模型、自动认证回退优先级， +或需要通用核心辅助工具在运行时加载前知晓的原生文档支持时， +请使用 `mediaUnderstandingProviderMetadata`。其键也必须在 +`contracts.mediaUnderstandingProviders` 中声明。 ```json { @@ -403,13 +438,14 @@ OpenClaw 会在提供商运行时加载前读取它。 | 字段 | 类型 | 含义 | | ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- | | `capabilities` | `("image" \| "audio" \| "video")[]` | 此提供商公开的媒体能力。 | -| `defaultModels` | `Record` | 当配置未指定模型时使用的“能力到模型”默认映射。 | -| `autoPriority` | `Record` | 用于基于凭证的自动提供商回退时，数值越小排序越靠前。 | +| `defaultModels` | `Record` | 当配置未指定模型时使用的能力到模型默认映射。 | +| `autoPriority` | `Record` | 对于基于凭证的自动提供商回退，数字越小排序越靠前。 | | `nativeDocumentInputs` | `"pdf"[]` | 该提供商支持的原生文档输入。 | ## `channelConfigs` 参考 -当渠道插件在运行时加载前需要轻量配置元数据时，请使用 `channelConfigs`。 +当渠道插件在运行时加载前需要轻量级配置元数据时， +请使用 `channelConfigs`。 ```json { @@ -441,14 +477,16 @@ OpenClaw 会在提供商运行时加载前读取它。 | 字段 | 类型 | 含义 | | ------------- | ------------------------ | ----------------------------------------------------------------------------------------- | | `schema` | `object` | `channels.` 的 JSON Schema。每个已声明的渠道配置条目都必须提供。 | -| `uiHints` | `Record` | 该渠道配置部分的可选 UI 标签 / 占位符 / 敏感性提示。 | +| `uiHints` | `Record` | 该渠道配置区块的可选 UI 标签 / 占位符 / 敏感性提示。 | | `label` | `string` | 当运行时元数据尚未就绪时，合并到选择器和检查界面中的渠道标签。 | -| `description` | `string` | 用于检查和目录界面的简短渠道说明。 | -| `preferOver` | `string[]` | 在选择界面中，此渠道应优先于的旧版或较低优先级插件 id。 | +| `description` | `string` | 用于检查和目录界面的简短渠道描述。 | +| `preferOver` | `string[]` | 此渠道在选择界面中应优先于的旧版或较低优先级插件 id。 | ## `modelSupport` 参考 -当 OpenClaw 应在插件运行时加载前，根据 `gpt-5.4` 或 `claude-sonnet-4.6` 之类的简写模型 id 推断你的提供商插件时，请使用 `modelSupport`。 +当 OpenClaw 应该在插件运行时加载前， +根据 `gpt-5.5` 或 `claude-sonnet-4.6` 这样的简写模型 id 推断你的提供商插件时， +请使用 `modelSupport`。 ```json { @@ -463,35 +501,43 @@ OpenClaw 按以下优先级处理： - 显式 `provider/model` 引用使用所属 `providers` 清单元数据 - `modelPatterns` 优先于 `modelPrefixes` -- 如果一个非内置插件和一个内置插件都匹配，则非内置插件胜出 -- 其余歧义会被忽略，直到用户或配置明确指定提供商 +- 如果一个非内置插件和一个内置插件同时匹配，则非内置 + 插件胜出 +- 对于剩余的歧义，在用户或配置指定提供商之前会被忽略 字段： | 字段 | 类型 | 含义 | | --------------- | ---------- | ------------------------------------------------------------------------------- | | `modelPrefixes` | `string[]` | 对简写模型 id 使用 `startsWith` 进行匹配的前缀。 | -| `modelPatterns` | `string[]` | 在移除配置文件后缀后，对简写模型 id 进行匹配的正则表达式源码。 | +| `modelPatterns` | `string[]` | 在移除 profile 后缀后，对简写模型 id 进行匹配的正则来源字符串。 | -旧版顶层能力键已弃用。使用 `openclaw doctor --fix` 将 `speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders` 和 `webSearchProviders` 移动到 `contracts` 下；常规清单加载不再将这些顶层字段视为能力归属。 +旧版顶层 capability 键已弃用。请使用 `openclaw doctor --fix` 将 +`speechProviders`、`realtimeTranscriptionProviders`、 +`realtimeVoiceProviders`、`mediaUnderstandingProviders`、 +`imageGenerationProviders`、`videoGenerationProviders`、 +`webFetchProviders` 和 `webSearchProviders` 移动到 `contracts` 下；常规 +清单加载已不再将这些顶层字段视为 capability +归属信息。 ## 清单与 `package.json` -这两个文件承担不同职责： +这两个文件的职责不同： | 文件 | 用途 | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | 设备发现、配置校验、认证选项元数据，以及必须在插件代码运行前存在的 UI 提示 | -| `package.json` | npm 元数据、依赖安装，以及用于入口点、安装门控、设置或目录元数据的 `openclaw` 代码块 | +| `openclaw.plugin.json` | 发现、配置验证、认证选项元数据，以及必须在插件代码运行前存在的 UI 提示 | +| `package.json` | npm 元数据、依赖安装，以及用于入口点、安装门控、设置或目录元数据的 `openclaw` 区块 | -如果你不确定某项元数据应该放在哪里，请使用以下规则： +如果你不确定某项元数据应放在哪里，请使用以下规则： -- 如果 OpenClaw 必须在加载插件代码前知道它，就放入 `openclaw.plugin.json` -- 如果它与打包、入口文件或 npm 安装行为有关，就放入 `package.json` +- 如果 OpenClaw 必须在加载插件代码之前知道它，就放进 `openclaw.plugin.json` +- 如果它与打包、入口文件或 npm 安装行为有关，就放进 `package.json` -### 影响设备发现的 `package.json` 字段 +### 影响发现的 `package.json` 字段 -某些运行时前的插件元数据会有意放在 `package.json` 的 `openclaw` 代码块下，而不是 `openclaw.plugin.json` 中。 +有些运行时前的插件元数据有意放在 `package.json` 的 +`openclaw` 区块中，而不是 `openclaw.plugin.json` 中。 重要示例： @@ -499,31 +545,52 @@ OpenClaw 按以下优先级处理： | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `openclaw.extensions` | 声明原生插件入口点。必须保持在插件包目录内。 | | `openclaw.runtimeExtensions` | 为已安装包声明构建后的 JavaScript 运行时入口点。必须保持在插件包目录内。 | -| `openclaw.setupEntry` | 在新手引导、延迟渠道启动和只读渠道状态 / SecretRef 发现期间使用的轻量仅设置入口点。必须保持在插件包目录内。 | +| `openclaw.setupEntry` | 在新手引导、延后渠道启动以及只读渠道状态 / SecretRef 发现期间使用的轻量级仅设置入口点。必须保持在插件包目录内。 | | `openclaw.runtimeSetupEntry` | 为已安装包声明构建后的 JavaScript 设置入口点。必须保持在插件包目录内。 | -| `openclaw.channel` | 轻量渠道目录元数据，例如标签、文档路径、别名和选择文案。 | -| `openclaw.channel.configuredState` | 轻量已配置状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已存在仅环境变量的设置？”。 | -| `openclaw.channel.persistedAuthState` | 轻量持久化认证状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已有任何内容登录？”。 | +| `openclaw.channel` | 轻量级渠道目录元数据，例如标签、文档路径、别名和选择说明文案。 | +| `openclaw.channel.configuredState` | 轻量级已配置状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已存在仅靠环境变量的设置？” | +| `openclaw.channel.persistedAuthState` | 轻量级持久化认证检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已经有任何账号登录？” | | `openclaw.install.npmSpec` / `openclaw.install.localPath` | 内置和外部发布插件的安装 / 更新提示。 | -| `openclaw.install.defaultChoice` | 当有多个安装来源可用时的首选安装路径。 | -| `openclaw.install.minHostVersion` | 最低支持的 OpenClaw 主机版本，使用如 `>=2026.3.22` 这样的 semver 下限。 | -| `openclaw.install.expectedIntegrity` | 预期的 npm 分发完整性字符串，例如 `sha512-...`；安装和更新流程会据此校验获取的制品。 | -| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许一个受限的内置插件重新安装恢复路径。 | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许在启动期间，完整渠道插件之前先加载仅设置的渠道界面。 | +| `openclaw.install.defaultChoice` | 当存在多个安装来源时，首选的安装路径。 | +| `openclaw.install.minHostVersion` | 最低受支持的 OpenClaw 主机版本，使用类似 `>=2026.3.22` 的 semver 下限。 | +| `openclaw.install.expectedIntegrity` | 预期的 npm dist 完整性字符串，例如 `sha512-...`；安装和更新流程会据此校验获取到的制品。 | +| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许一个范围很窄的内置插件重装恢复路径。 | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许仅设置的渠道界面在启动期间先于完整渠道插件加载。 | -清单元数据决定在运行时加载前，新手引导中会出现哪些提供商 / 渠道 / 设置选项。`package.json#openclaw.install` 告诉新手引导在用户选择其中某项时，如何获取或启用该插件。不要将安装提示移动到 `openclaw.plugin.json` 中。 +清单元数据决定了在运行时加载前， +新手引导中会出现哪些提供商 / 渠道 / 设置选项。`package.json#openclaw.install` 告诉 +新手引导，当用户选择这些选项之一时，应如何获取或启用该插件。不要将安装提示移入 `openclaw.plugin.json`。 -`openclaw.install.minHostVersion` 会在安装和清单注册表加载期间强制执行。无效值会被拒绝；较新但有效的值会使旧主机跳过该插件。 +`openclaw.install.minHostVersion` 会在安装和清单 +注册表加载期间强制执行。无效值会被拒绝；较新的但有效的值会使插件在较旧主机上被跳过。 -精确的 npm 版本固定已存在于 `npmSpec` 中，例如 `"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`。如果你希望在获取的 npm 制品不再匹配固定发布版本时，让更新流程默认失败关闭，请将其与 `expectedIntegrity` 搭配使用。交互式新手引导会提供受信任注册表 npm 规格，包括裸包名和 dist-tag。存在 `expectedIntegrity` 时，安装 / 更新流程会强制执行它；省略时，注册表解析结果会被记录，但不会附带完整性固定。 +精确的 npm 版本固定已经放在 `npmSpec` 中，例如 +`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`。当你希望更新流程在获取到的 +npm 制品不再匹配固定版本时以保守方式失败，请将其与 +`expectedIntegrity` 搭配使用。交互式新手引导 +会提供可信注册表 npm 规范，包括裸包名和 dist-tag。 +当存在 `expectedIntegrity` 时，安装 / 更新流程会强制校验它；当省略时， +会记录注册表解析结果，但不附带完整性固定。 -当状态、渠道列表或 SecretRef 扫描需要在不加载完整运行时的情况下识别已配置账号时，渠道插件应提供 `openclaw.setupEntry`。设置入口点应公开渠道元数据，以及对设置安全的配置、状态和 secrets 适配器；将网络客户端、Gateway 网关监听器和传输运行时保留在主扩展入口点中。 +当状态、渠道列表或 SecretRef 扫描需要在不加载完整 +运行时的情况下识别已配置账号时，渠道插件应提供 `openclaw.setupEntry`。 +该设置入口点应公开渠道元数据以及适用于设置场景的配置、 +状态和密钥适配器；网络客户端、Gateway 网关监听器和 +传输运行时应保留在主扩展入口点中。 -运行时入口点字段不会绕过针对源码入口点字段的包边界检查。例如，`openclaw.runtimeExtensions` 不能让一个越界的 `openclaw.extensions` 路径变得可加载。 +运行时入口点字段不会覆盖针对源码 +入口点字段的包边界检查。例如， +`openclaw.runtimeExtensions` 不能让越界的 `openclaw.extensions` 路径变为可加载。 -`openclaw.install.allowInvalidConfigRecovery` 的设计范围是刻意收窄的。它不会让任意损坏的配置变得可安装。当前它只允许安装流程从特定的陈旧内置插件升级失败中恢复，例如缺失的内置插件路径，或同一内置插件对应的陈旧 `channels.` 条目。无关的配置错误仍会阻止安装，并引导运维人员执行 `openclaw doctor --fix`。 +`openclaw.install.allowInvalidConfigRecovery` 的设计范围刻意很窄。它并 +不会让任意损坏的配置都变得可安装。 +目前它仅允许安装流程从某些特定的陈旧内置插件升级失败中恢复，例如 +缺失的内置插件路径，或同一内置插件对应的陈旧 `channels.` 条目。 +无关的配置错误仍会阻止安装，并将操作人员引导到 +`openclaw doctor --fix`。 -`openclaw.channel.persistedAuthState` 是一个微型检查器模块的包元数据： +`openclaw.channel.persistedAuthState` 是一个微型检查器 +模块的包元数据： ```json { @@ -539,9 +606,12 @@ OpenClaw 按以下优先级处理： } ``` -当设置、Doctor 或已配置状态流程需要在完整渠道插件加载前执行一个低成本的“是 / 否”认证探测时，请使用它。目标导出应是一个只读取持久化状态的小函数；不要通过完整渠道运行时 barrel 转发它。 +当设置、Doctor 或已配置状态流程在完整渠道插件加载前， +需要一个低成本的“是 / 否”认证探测时，请使用它。目标导出应是一个仅仅读取持久化状态的小函数； +不要通过完整渠道运行时 barrel 转发它。 -`openclaw.channel.configuredState` 对低成本的仅环境变量已配置检查采用相同结构： +`openclaw.channel.configuredState` 对低成本、仅基于环境变量的 +已配置检查采用相同形式： ```json { @@ -557,50 +627,57 @@ OpenClaw 按以下优先级处理： } ``` -当一个渠道可以根据环境变量或其他微型非运行时输入回答已配置状态时，请使用它。如果检查需要完整配置解析或真实渠道运行时，请将该逻辑保留在插件 `config.hasConfiguredState` hook 中。 +当某个渠道可以仅根据环境变量或其他轻量级 +非运行时输入来判断已配置状态时，请使用它。如果检查需要完整配置解析或真实的 +渠道运行时，请将该逻辑保留在插件 `config.hasConfiguredState` +hook 中。 -## 设备发现优先级（重复插件 id） +## 发现优先级（重复插件 id） -OpenClaw 会从多个根目录发现插件（内置、全局安装、工作区、配置中显式选择的路径）。如果两个发现结果共享相同的 `id`，则只保留**优先级最高**的清单；低优先级的重复项会被丢弃，而不会与其并列加载。 +OpenClaw 会从多个根位置发现插件（内置、全局安装、工作区、显式配置选定路径）。如果两个发现结果共享相同的 `id`，则只保留**优先级最高**的清单；较低优先级的重复项会被丢弃，而不是与之并行加载。 优先级从高到低如下： -1. **配置中选定** —— 在 `plugins.entries.` 中显式固定的路径 -2. **内置** —— 随 OpenClaw 一起发布的插件 +1. **配置选定** —— 在 `plugins.entries.` 中显式固定的路径 +2. **内置** —— 随 OpenClaw 一起分发的插件 3. **全局安装** —— 安装到全局 OpenClaw 插件根目录中的插件 4. **工作区** —— 相对于当前工作区发现的插件 影响： -- 工作区中放置的某个内置插件分叉版本或陈旧副本，不会覆盖内置构建版本。 -- 若要真正用本地插件覆盖内置插件，请通过 `plugins.entries.` 固定它，使其依靠优先级获胜，而不是依赖工作区发现。 -- 被丢弃的重复项会被记录日志，以便 Doctor 和启动诊断能指向被舍弃的副本。 +- 工作区中某个内置插件的 fork 或陈旧副本不会遮蔽内置构建版本。 +- 若要真正用本地插件覆盖内置插件，请通过 `plugins.entries.` 固定它，使其通过优先级获胜，而不是依赖工作区发现。 +- 被丢弃的重复项会记录日志，以便 Doctor 和启动诊断指出被丢弃的副本。 ## JSON Schema 要求 - **每个插件都必须提供一个 JSON Schema**，即使它不接受任何配置。 - 可以使用空 schema（例如 `{ "type": "object", "additionalProperties": false }`）。 -- Schema 会在配置读写时校验，而不是在运行时校验。 +- Schema 会在配置读取 / 写入时验证，而不是在运行时验证。 -## 校验行为 +## 验证行为 -- 未知的 `channels.*` 键是**错误**，除非该渠道 id 由某个插件清单声明。 -- `plugins.entries.`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*` 必须引用**可发现的**插件 id。未知 id 是**错误**。 -- 如果某个插件已安装，但其清单或 schema 损坏或缺失，校验会失败，Doctor 会报告该插件错误。 -- 如果插件配置存在，但插件处于**禁用**状态，该配置会被保留，并且 Doctor + 日志中会显示**警告**。 +- 未知的 `channels.*` 键会被视为**错误**，除非该渠道 id 已由 + 某个插件清单声明。 +- `plugins.entries.`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*` + 必须引用**可发现的**插件 id。未知 id 会被视为**错误**。 +- 如果某个插件已安装，但其清单或 schema 损坏或缺失， + 验证将失败，Doctor 会报告该插件错误。 +- 如果插件配置存在，但插件**已禁用**，则配置会被保留， + 并且 Doctor + 日志中会显示**警告**。 -完整的 `plugins.*` schema，请参阅[配置参考](/zh-CN/gateway/configuration)。 +有关完整的 `plugins.*` schema，请参见 [配置参考](/zh-CN/gateway/configuration)。 ## 说明 -- 对于原生 OpenClaw 插件，包括本地文件系统加载，清单都是**必需的**。运行时仍会单独加载插件模块；清单仅用于设备发现 + 校验。 -- 原生清单使用 JSON5 解析，因此允许注释、尾随逗号和未加引号的键，只要最终值仍然是一个对象即可。 -- 清单加载器只读取文档中说明的清单字段。避免使用自定义顶层键。 -- 当插件不需要时，可以省略 `channels`、`providers`、`cliBackends` 和 `skills`。 -- 互斥插件类型通过 `plugins.slots.*` 选择：`kind: "memory"` 对应 `plugins.slots.memory`，`kind: "context-engine"` 对应 `plugins.slots.contextEngine`（默认 `legacy`）。 -- 环境变量元数据（`providerAuthEnvVars`、`channelEnvVars`）仅是声明式的。状态、审计、cron 投递校验及其他只读界面在将某个环境变量视为已配置之前，仍会应用插件信任和有效激活策略。 -- 有关需要提供商代码的运行时向导元数据，请参阅[提供商运行时 hooks](/zh-CN/plugins/architecture#provider-runtime-hooks)。 -- 如果你的插件依赖原生模块，请记录构建步骤以及所有包管理器 allowlist 要求（例如 pnpm `allow-build-scripts` + `pnpm rebuild `）。 +- 对于**原生 OpenClaw 插件**，包括本地文件系统加载，清单都是**必需的**。运行时仍会单独加载插件模块；清单仅用于发现 + 验证。 +- 原生清单使用 JSON5 解析，因此支持注释、尾随逗号和未加引号的键，只要最终值仍然是对象即可。 +- 清单加载器只会读取文档中说明的清单字段。避免使用自定义顶层键。 +- 当插件不需要这些项时，`channels`、`providers`、`cliBackends` 和 `skills` 都可以省略。 +- 互斥插件类型通过 `plugins.slots.*` 选择：`kind: "memory"` 使用 `plugins.slots.memory`，`kind: "context-engine"` 使用 `plugins.slots.contextEngine`（默认 `legacy`）。 +- 环境变量元数据（`providerAuthEnvVars`、`channelEnvVars`）仅为声明式元数据。状态、审计、cron 投递验证以及其他只读界面在将环境变量视为已配置之前，仍会应用插件信任和生效中的激活策略。 +- 对于需要提供商代码的运行时向导元数据，请参见 [提供商运行时 hook](/zh-CN/plugins/architecture#provider-runtime-hooks)。 +- 如果你的插件依赖原生模块，请记录构建步骤以及任何包管理器允许列表要求（例如 pnpm `allow-build-scripts` + `pnpm rebuild `）。 ## 相关内容 @@ -611,7 +688,7 @@ OpenClaw 会从多个根目录发现插件（内置、全局安装、工作区 内部架构和能力模型。 - + 插件 SDK 参考和子路径导入。 diff --git a/docs/zh-CN/plugins/sdk-agent-harness.md b/docs/zh-CN/plugins/sdk-agent-harness.md index a61d42039..b846ff748 100644 --- a/docs/zh-CN/plugins/sdk-agent-harness.md +++ b/docs/zh-CN/plugins/sdk-agent-harness.md @@ -1,53 +1,54 @@ --- read_when: - 你正在更改嵌入式智能体运行时或 Harness 注册表 - - 你正在从内置或受信任的插件注册一个智能体 Harness + - 你正在从内置或受信任插件注册一个智能体 Harness - 你需要了解 Codex 插件与模型提供商之间的关系 sidebarTitle: Agent Harness -summary: 用于替换底层嵌入式智能体执行器的插件实验性 SDK 接口面 +summary: 面向替换底层嵌入式智能体执行器的插件的实验性 SDK 界面 title: 智能体 Harness 插件 x-i18n: - generated_at: "2026-04-23T16:04:43Z" + generated_at: "2026-04-23T19:26:03Z" model: gpt-5.4 provider: openai - source_hash: ec858acedaae8670c730022f8cc700499ac3b95d3d4144584e01051b224fee64 + source_hash: c0822248298c61f9dda7ec342558e8cda7c936876060b471ed01dc6c90779010 source_path: plugins/sdk-agent-harness.md workflow: 15 --- # 智能体 Harness 插件 -**智能体 harness** 是一个已准备好的 OpenClaw 智能体单次轮次的底层执行器。它不是模型提供商，不是渠道，也不是工具注册表。 +**智能体 Harness** 是为一次已准备好的 OpenClaw 智能体轮次提供底层执行的执行器。 +它不是模型提供商，不是渠道，也不是工具注册表。 -仅对内置或受信任的原生插件使用此接口面。该契约仍然是实验性的，因为参数类型有意映射当前的嵌入式运行器。 +仅将此界面用于内置或受信任的原生插件。该契约仍然是实验性的，因为其参数类型有意镜像当前的嵌入式运行器。 -## 何时使用 harness +## 何时使用 Harness -当某个模型家族拥有自己的原生会话运行时，而常规 OpenClaw 提供商传输抽象并不适合时，注册一个智能体 harness。 +当某个模型家族拥有自己的原生会话运行时，而普通的 OpenClaw 提供商传输层并不是正确抽象时，请注册一个智能体 Harness。 -例如： +示例： -- 拥有线程与压缩能力的原生 coding-agent 服务器 -- 必须流式传输原生计划 / 推理 / 工具事件的本地 CLI 或守护进程 -- 除 OpenClaw 会话转录之外，还需要自身 resume id 的模型运行时 +- 拥有线程和压缩能力的原生编码智能体服务器 +- 必须流式传输原生计划/推理/工具事件的本地 CLI 或守护进程 +- 除 OpenClaw 会话转录外，还需要维护自己 resume id 的模型运行时 -不要仅仅为了添加一个新的 LLM API 而注册 harness。对于常规 HTTP 或 WebSocket 模型 API，请构建一个[提供商插件](/zh-CN/plugins/sdk-provider-plugins)。 +不要仅仅为了添加新的 LLM API 而注册 Harness。对于普通的 HTTP 或 WebSocket 模型 API，请构建一个[提供商插件](/zh-CN/plugins/sdk-provider-plugins)。 -## 核心仍然负责的内容 +## 核心仍负责的内容 -在选择 harness 之前，OpenClaw 已经解析了： +在选择 Harness 之前，OpenClaw 已经完成了以下解析： - 提供商和模型 -- 运行时凭证状态 -- 思考级别和上下文预算 -- OpenClaw 转录 / 会话文件 +- 运行时认证状态 +- thinking 级别和上下文预算 +- OpenClaw 转录/会话文件 - 工作区、沙箱和工具策略 - 渠道回复回调和流式传输回调 - 模型回退和实时模型切换策略 -这种划分是有意设计的。harness 运行的是一个已准备好的尝试；它不会选择提供商、替代渠道投递，或静默切换模型。 +这种划分是有意为之。Harness 运行的是一次已准备好的尝试；它不会选择提供商、替代渠道投递，也不会静默切换模型。 -## 注册 harness +## 注册一个 Harness **导入：** `openclaw/plugin-sdk/agent-harness` @@ -85,64 +86,68 @@ export default definePluginEntry({ ## 选择策略 -OpenClaw 会在提供商 / 模型解析之后选择一个 harness： +OpenClaw 会在提供商/模型解析之后选择 Harness： -1. 现有会话中记录的 harness id 优先生效，因此配置 / 环境变量的变化不会将该转录热切换到另一个运行时。 -2. `OPENCLAW_AGENT_RUNTIME=` 会为尚未固定的会话强制使用具有该 id 的已注册 harness。 -3. `OPENCLAW_AGENT_RUNTIME=pi` 会强制使用内置的 PI harness。 -4. `OPENCLAW_AGENT_RUNTIME=auto` 会询问已注册的 harness 是否支持已解析的提供商 / 模型。 -5. 如果没有匹配的已注册 harness，除非禁用了 PI 回退，否则 OpenClaw 会使用 PI。 +1. 现有会话中已记录的 Harness id 优先，这样配置/环境变更就不会将该转录热切换到另一个运行时。 +2. `OPENCLAW_AGENT_RUNTIME=` 会为尚未固定的会话强制使用具有该 id 的已注册 Harness。 +3. `OPENCLAW_AGENT_RUNTIME=pi` 会强制使用内置的 PI Harness。 +4. `OPENCLAW_AGENT_RUNTIME=auto` 会询问已注册的 Harness 是否支持已解析的提供商/模型。 +5. 如果没有已注册的 Harness 匹配，OpenClaw 会使用 PI，除非已禁用 PI 回退。 -插件 harness 失败会表现为运行失败。在 `auto` 模式下，仅当没有已注册的插件 harness 支持已解析的提供商 / 模型时，才会使用 PI 回退。一旦某个插件 harness 已接管一次运行，OpenClaw 就不会通过 PI 重放同一轮次，因为这可能改变凭证 / 运行时语义或造成副作用重复。 +插件 Harness 失败会表现为运行失败。在 `auto` 模式下，只有当没有已注册插件 Harness 支持已解析的提供商/模型时，才会使用 PI 回退。一旦某个插件 Harness 已认领一次运行，OpenClaw 就不会再通过 PI 重放同一轮次，因为这可能会改变认证/运行时语义，或导致副作用重复发生。 -嵌入式运行后，所选 harness id 会与会话 id 一起持久化。在 harness 固定机制之前创建的旧会话，一旦拥有转录历史，就会被视为固定到 PI。要在 PI 与原生插件 harness 之间切换，请使用新的 / 重置后的会话。`/status` 会在 `Fast` 旁显示诸如 `codex` 之类的非默认 harness id；PI 作为默认兼容路径则会被隐藏。 +选定的 Harness id 会在一次嵌入式运行后，与会话 id 一起持久化保存。对于在 Harness 固定机制出现之前创建的旧会话，只要它们已有转录历史，就会被视为固定到 PI。在 PI 与原生插件 Harness 之间切换时，请使用新的/重置的会话。`/status` 会在 `Fast` 旁边显示诸如 `codex` 之类的非默认 Harness id；PI 不会显示，因为它是默认的兼容路径。 -内置 Codex 插件将 `codex` 注册为它的 harness id。核心将其视为普通的插件 harness id；Codex 专用别名应属于插件或操作员配置，而不应放在共享运行时选择器中。 +内置 Codex 插件将 `codex` 注册为其 Harness id。核心将其视为普通插件 Harness id；Codex 专用别名应属于插件或操作员配置，而不是共享运行时选择器。 -## 提供商与 harness 配对 +## 提供商与 Harness 配对 -大多数 harness 也应同时注册一个提供商。提供商让模型引用、凭证状态、模型元数据和 `/model` 选择对 OpenClaw 的其余部分可见。然后，harness 在 `supports(...)` 中声明对该提供商的支持。 +大多数 Harness 也应注册一个提供商。提供商会让模型引用、认证状态、模型元数据和 `/model` 选择对 OpenClaw 的其余部分可见。然后 Harness 在 `supports(...)` 中认领该提供商。 -内置 Codex 插件遵循这种模式： +内置 Codex 插件采用这种模式： - provider id：`codex` -- 用户模型引用：`codex/gpt-5.4`、`codex/gpt-5.2`，或 Codex app server 返回的其他模型 +- 用户模型引用：`codex/gpt-5.5`、`codex/gpt-5.2`，或 Codex 应用服务器返回的其他模型 - harness id：`codex` -- 凭证：合成的提供商可用性，因为 Codex harness 拥有原生 Codex 登录 / 会话 -- app-server 请求：OpenClaw 向 Codex 发送裸模型 id，并让 harness 与原生 app-server 协议通信 +- 认证：合成的提供商可用性，因为 Codex Harness 拥有原生 Codex 登录/会话 +- 应用服务器请求：OpenClaw 将裸模型 id 发送给 Codex，并由 Harness 与原生 app-server 协议通信 -Codex 插件是增量式的。普通的 `openai/gpt-*` 引用仍然是 OpenAI 提供商引用，并继续使用常规 OpenClaw 提供商路径。当你需要 Codex 管理的凭证、Codex 模型发现、原生线程和 Codex app-server 执行时，请选择 `codex/gpt-*`。`/model` 可以在 Codex app server 返回的 Codex 模型之间切换，而无需 OpenAI 提供商凭证。 +Codex 插件是增量式的。普通 `openai/gpt-*` 引用仍然是 OpenAI 提供商引用，并继续使用常规 OpenClaw 提供商路径。当你希望使用由 Codex 管理的认证、Codex 模型发现、原生线程和 Codex app-server 执行时，请选择 `codex/gpt-*`。`/model` 可以在 Codex app-server 返回的 Codex 模型之间切换，而无需 OpenAI 提供商凭证。 -有关操作员设置、模型前缀示例和仅限 Codex 的配置，请参阅 [Codex Harness](/zh-CN/plugins/codex-harness)。 +有关操作员设置、模型前缀示例和仅适用于 Codex 的配置，请参见 +[Codex Harness](/zh-CN/plugins/codex-harness)。 -OpenClaw 要求 Codex app-server 版本为 `0.118.0` 或更高。Codex 插件会检查 app-server 初始化握手，并阻止较旧或未带版本信息的服务器，以确保 OpenClaw 只运行在其已测试过的协议接口面之上。 +OpenClaw 要求 Codex app-server 为 `0.118.0` 或更新版本。Codex 插件会检查 app-server 初始化握手，并阻止较旧或无版本服务器，以确保 OpenClaw 只在它已测试过的协议界面上运行。 ### Codex app-server 工具结果中间件 -当清单声明 `contracts.embeddedExtensionFactories: ["codex-app-server"]` 时，内置插件还可以通过 `api.registerCodexAppServerExtensionFactory(...)` 附加 Codex app-server 专用的 `tool_result` 中间件。这是受信任插件的接口，用于那些需要在原生 Codex harness 内部运行、并在工具输出被投影回 OpenClaw 转录之前执行的异步工具结果转换。 +当内置插件的清单声明 `contracts.embeddedExtensionFactories: ["codex-app-server"]` 时，它们还可以通过 `api.registerCodexAppServerExtensionFactory(...)` 附加 Codex app-server 专用的 `tool_result` 中间件。 +这是面向受信任插件的扩展点，用于那些需要在原生 Codex Harness 内运行、并在工具输出回投到 OpenClaw 转录之前进行异步工具结果转换的场景。 -### 原生 Codex harness 模式 +### 原生 Codex Harness 模式 -内置的 `codex` harness 是嵌入式 OpenClaw 智能体轮次的原生 Codex 模式。请先启用内置 `codex` 插件；如果你的配置使用了限制性 allowlist，还要将 `codex` 加入 `plugins.allow`。它与 `openai-codex/*` 不同： +内置 `codex` Harness 是嵌入式 OpenClaw 智能体轮次的原生 Codex 模式。请先启用内置 `codex` 插件；如果你的配置使用受限 allowlist，还需要将 `codex` 包含在 `plugins.allow` 中。它不同于 `openai-codex/*`： -- `openai-codex/*` 通过常规 OpenClaw 提供商路径使用 ChatGPT / Codex OAuth。 -- `codex/*` 使用内置 Codex 提供商，并通过 Codex app-server 路由该轮次。 +- `openai-codex/*` 通过常规 OpenClaw 提供商路径使用 ChatGPT/Codex OAuth +- `codex/*` 使用内置 Codex 提供商，并通过 Codex app-server 路由该轮次 -当此模式运行时，Codex 负责原生线程 id、resume 行为、压缩和 app-server 执行。OpenClaw 仍然负责聊天渠道、可见转录镜像、工具策略、审批、媒体投递和会话选择。当你需要证明只有 Codex app-server 路径可以接管运行时，请使用 `embeddedHarness.runtime: "codex"` 配合 `embeddedHarness.fallback: "none"`。该配置仅是一个选择保护：Codex app-server 失败本来就会直接失败，而不会通过 PI 重试。 +当该模式运行时，Codex 负责原生线程 id、resume 行为、压缩以及 app-server 执行。OpenClaw 仍然负责聊天渠道、可见转录镜像、工具策略、审批、媒体投递和会话选择。当你需要证明只有 Codex app-server 路径能够认领该运行时，请使用 `embeddedHarness.runtime: "codex"` 并设置 +`embeddedHarness.fallback: "none"`。该配置只是选择保护：Codex app-server 失败本来就会直接失败，而不会再通过 PI 重试。 ## 禁用 PI 回退 -默认情况下，OpenClaw 以 `agents.defaults.embeddedHarness` 设置为 `{ runtime: "auto", fallback: "pi" }` 来运行嵌入式智能体。在 `auto` 模式下，已注册的插件 harness 可以接管某个提供商 / 模型组合。如果没有任何匹配，OpenClaw 会回退到 PI。 +默认情况下，OpenClaw 使用 `agents.defaults.embeddedHarness` +设为 `{ runtime: "auto", fallback: "pi" }` 来运行嵌入式智能体。在 `auto` 模式下，已注册插件 Harness 可以认领某个提供商/模型对。如果没有匹配项，OpenClaw 会回退到 PI。 -当你需要在缺少插件 harness 选择时直接失败，而不是使用 PI 时，请设置 `fallback: "none"`。已选中的插件 harness 失败本来就会硬失败。这不会阻止显式的 `runtime: "pi"` 或 `OPENCLAW_AGENT_RUNTIME=pi`。 +当你需要在缺少插件 Harness 选择时直接失败，而不是使用 PI 时，请设置 `fallback: "none"`。已选中的插件 Harness 失败本来就会硬失败。这不会阻止显式的 `runtime: "pi"` 或 `OPENCLAW_AGENT_RUNTIME=pi`。 -对于仅限 Codex 的嵌入式运行： +对于仅 Codex 的嵌入式运行： ```json { "agents": { "defaults": { - "model": "codex/gpt-5.4", + "model": "codex/gpt-5.5", "embeddedHarness": { "runtime": "codex", "fallback": "none" @@ -152,7 +157,7 @@ OpenClaw 要求 Codex app-server 版本为 `0.118.0` 或更高。Codex 插件会 } ``` -如果你希望任何已注册的插件 harness 都能接管匹配的模型，但又绝不希望 OpenClaw 静默回退到 PI，请保持 `runtime: "auto"` 并禁用回退： +如果你希望任何已注册的插件 Harness 都能认领匹配模型，但又不希望 OpenClaw 静默回退到 PI，请保持 `runtime: "auto"` 并禁用回退： ```json { @@ -167,7 +172,7 @@ OpenClaw 要求 Codex app-server 版本为 `0.118.0` 或更高。Codex 插件会 } ``` -按智能体覆盖使用相同的结构： +每个智能体的覆盖使用相同结构： ```json { @@ -181,7 +186,7 @@ OpenClaw 要求 Codex app-server 版本为 `0.118.0` 或更高。Codex 插件会 "list": [ { "id": "codex-only", - "model": "codex/gpt-5.4", + "model": "codex/gpt-5.5", "embeddedHarness": { "runtime": "codex", "fallback": "none" @@ -192,7 +197,8 @@ OpenClaw 要求 Codex app-server 版本为 `0.118.0` 或更高。Codex 插件会 } ``` -`OPENCLAW_AGENT_RUNTIME` 仍然会覆盖已配置的运行时。使用 `OPENCLAW_AGENT_HARNESS_FALLBACK=none` 可通过环境变量禁用 PI 回退。 +`OPENCLAW_AGENT_RUNTIME` 仍会覆盖已配置的运行时。使用 +`OPENCLAW_AGENT_HARNESS_FALLBACK=none` 可通过环境变量禁用 PI 回退。 ```bash OPENCLAW_AGENT_RUNTIME=codex \ @@ -200,34 +206,36 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -在禁用回退后，如果请求的 harness 未注册、不支持已解析的提供商 / 模型，或者在产生轮次副作用之前失败，则会话会尽早失败。这对仅限 Codex 的部署以及必须证明 Codex app-server 路径确实在使用中的实时测试而言，是有意设计的行为。 +禁用回退后，如果请求的 Harness 未注册、不支持已解析的提供商/模型，或在产生轮次副作用之前就已失败，则会话会提前失败。对于仅 Codex 的部署，以及必须证明实际使用了 Codex app-server 路径的实时测试，这正是预期行为。 -此设置只控制嵌入式智能体 harness。它不会禁用图像、视频、音乐、TTS、PDF 或其他提供商特定的模型路由。 +此设置仅控制嵌入式智能体 Harness。它不会禁用图像、视频、音乐、TTS、PDF 或其他提供商专用模型路由。 ## 原生会话与转录镜像 -harness 可以保留原生会话 id、线程 id 或守护进程侧的 resume token。请将这种绑定明确关联到 OpenClaw 会话，并继续将用户可见的助手 / 工具输出镜像到 OpenClaw 转录中。 +Harness 可以维护原生 session id、thread id 或守护进程侧的 resume token。 +请将这种绑定明确关联到 OpenClaw 会话，并持续将用户可见的助手/工具输出镜像到 OpenClaw 转录中。 -OpenClaw 转录仍然是以下场景的兼容层： +OpenClaw 转录仍是以下能力的兼容层： - 渠道可见的会话历史 -- 转录搜索与索引 -- 在后续轮次切换回内置 PI harness +- 转录搜索和索引 +- 在后续轮次切换回内置 PI Harness - 通用的 `/new`、`/reset` 和会话删除行为 -如果你的 harness 存储了 sidecar 绑定，请实现 `reset(...)`，这样 OpenClaw 才能在所属 OpenClaw 会话被重置时清除它。 +如果你的 Harness 存储了 sidecar 绑定，请实现 `reset(...)`，以便 OpenClaw 能在所属 OpenClaw 会话被重置时清除它。 -## 工具与媒体结果 +## 工具和媒体结果 -核心会构建 OpenClaw 工具列表，并将其传入已准备好的尝试中。当 harness 执行动态工具调用时，请通过 harness 结果结构返回工具结果，而不是自行发送渠道媒体。 +核心会构建 OpenClaw 工具列表，并将其传入已准备好的尝试中。 +当 Harness 执行动态工具调用时，请通过 Harness 结果结构返回工具结果，而不是自行发送渠道媒体。 -这样可以让文本、图像、视频、音乐、TTS、审批以及消息工具输出，与由 PI 支持的运行走同一条投递路径。 +这样可以让文本、图像、视频、音乐、TTS、审批和消息工具输出，与由 PI 支持的运行使用同一条投递路径。 ## 当前限制 -- 公共导入路径是通用的，但某些 attempt / result 类型别名仍然保留 `Pi` 名称以保持兼容性。 -- 第三方 harness 安装仍处于实验阶段。在你确实需要原生会话运行时之前，优先使用提供商插件。 -- 支持跨轮次切换 harness。不要在一轮进行过程中、在原生工具、审批、助手文本或消息发送已经开始之后切换 harness。 +- 公共导入路径是通用的，但部分 attempt/result 类型别名仍然保留 `Pi` 命名以保持兼容性。 +- 第三方 Harness 安装仍属实验性功能。在你确实需要原生会话运行时时，才应优先考虑它；否则请优先使用提供商插件。 +- 支持跨轮次切换 Harness。不要在某一轮次中途、在原生工具、审批、助手文本或消息发送已经开始之后切换 Harness。 ## 相关内容 diff --git a/docs/zh-CN/providers/kilocode.md b/docs/zh-CN/providers/kilocode.md index 54517c0ec..b107ca50d 100644 --- a/docs/zh-CN/providers/kilocode.md +++ b/docs/zh-CN/providers/kilocode.md @@ -1,26 +1,27 @@ --- read_when: - - 你想用一个 API 密钥访问多个 LLM - - 你想在 OpenClaw 中通过 Kilo Gateway 运行模型 -summary: 使用 Kilo Gateway 的统一 API 在 OpenClaw 中访问多种模型 + - 你希望用一个 API 密钥访问多种 LLM + - 你想在 OpenClaw 中通过 Kilo Gateway 网关运行模型 +summary: 使用 Kilo Gateway 网关的统一 API 在 OpenClaw 中访问多种模型 title: Kilocode x-i18n: - generated_at: "2026-04-12T10:43:06Z" + generated_at: "2026-04-23T19:26:11Z" model: gpt-5.4 provider: openai - source_hash: 32946f2187f3933115341cbe81006718b10583abc4deea7440b5e56366025f4a + source_hash: 4c0fa1c4949a76a353f76c47010510b75a6da6dc6d5b993f8e1f5e9b6fef53ce source_path: providers/kilocode.md workflow: 15 --- # Kilo Gateway -Kilo Gateway 提供一个**统一 API**，可将请求路由到单个端点和 API 密钥背后的多种模型。它兼容 OpenAI，因此大多数 OpenAI SDK 只需切换 base URL 即可使用。 +Kilo Gateway 提供一个**统一 API**，可通过单一端点和 API 密钥将请求路由到多个模型。 +它兼容 OpenAI，因此大多数 OpenAI SDK 只需切换 base URL 即可使用。 -| Property | Value | -| -------- | ----- | +| 属性 | 值 | +| -------- | ---------------------------------- | | 提供商 | `kilocode` | -| 认证 | `KILOCODE_API_KEY` | +| 凭证 | `KILOCODE_API_KEY` | | API | 兼容 OpenAI | | Base URL | `https://api.kilo.ai/api/gateway/` | @@ -28,7 +29,7 @@ Kilo Gateway 提供一个**统一 API**，可将请求路由到单个端点和 A - 前往 [app.kilo.ai](https://app.kilo.ai)，登录或创建账户，然后导航到 API Keys 并生成一个新密钥。 + 前往 [app.kilo.ai](https://app.kilo.ai)，登录或创建账户，然后进入 API Keys 页面生成一个新密钥。 ```bash @@ -42,7 +43,7 @@ Kilo Gateway 提供一个**统一 API**，可将请求路由到单个端点和 A ``` - + ```bash openclaw models list --provider kilocode ``` @@ -51,10 +52,10 @@ Kilo Gateway 提供一个**统一 API**，可将请求路由到单个端点和 A ## 默认模型 -默认模型是 `kilocode/kilo/auto`，这是一个由 Kilo Gateway 管理、由提供商拥有的智能路由模型。 +默认模型是 `kilocode/kilo/auto`，这是一个由提供商维护的智能路由模型，由 Kilo Gateway 管理。 -OpenClaw 将 `kilocode/kilo/auto` 视为稳定的默认引用，但不会发布该路由从任务到上游模型映射的源码依据。`kilocode/kilo/auto` 背后的确切上游路由由 Kilo Gateway 决定，而不是在 OpenClaw 中硬编码。 +OpenClaw 将 `kilocode/kilo/auto` 视为稳定的默认引用，但不会发布该路由从任务到上游模型的源支持映射。`kilocode/kilo/auto` 背后的确切上游路由由 Kilo Gateway 负责，而不是在 OpenClaw 中硬编码。 ## 可用模型 @@ -62,18 +63,18 @@ OpenClaw 将 `kilocode/kilo/auto` 视为稳定的默认引用，但不会发布 OpenClaw 会在启动时从 Kilo Gateway 动态发现可用模型。使用 `/models kilocode` 可查看你的账户可用的完整模型列表。 -Gateway 网关上任何可用模型都可以配合 `kilocode/` 前缀使用： +Gateway 网关上任何可用模型都可以使用 `kilocode/` 前缀： | 模型引用 | 说明 | -| -------- | ---- | -| `kilocode/kilo/auto` | 默认 —— 智能路由 | +| -------------------------------------- | ---------------------------------- | +| `kilocode/kilo/auto` | 默认 — 智能路由 | | `kilocode/anthropic/claude-sonnet-4` | 通过 Kilo 使用 Anthropic | -| `kilocode/openai/gpt-5.4` | 通过 Kilo 使用 OpenAI | +| `kilocode/openai/gpt-5.5` | 通过 Kilo 使用 OpenAI | | `kilocode/google/gemini-3-pro-preview` | 通过 Kilo 使用 Google | -| ...以及更多 | 使用 `/models kilocode` 列出全部 | +| ……以及更多 | 使用 `/models kilocode` 列出全部 | -启动时，OpenClaw 会查询 `GET https://api.kilo.ai/api/gateway/models`，并将发现的模型合并到静态后备目录之前。内置后备目录始终包含 `kilocode/kilo/auto`（`Kilo Auto`），其参数为 `input: ["text", "image"]`、`reasoning: true`、`contextWindow: 1000000` 和 `maxTokens: 128000`。 +启动时，OpenClaw 会查询 `GET https://api.kilo.ai/api/gateway/models`，并将发现的模型合并到静态回退目录之前。内置回退目录始终包含 `kilocode/kilo/auto`（`Kilo Auto`），其配置为 `input: ["text", "image"]`、`reasoning: true`、`contextWindow: 1000000` 和 `maxTokens: 128000`。 ## 配置示例 @@ -91,26 +92,26 @@ Gateway 网关上任何可用模型都可以配合 `kilocode/` 前缀使用： - 源码中将 Kilo Gateway 记录为兼容 OpenRouter，因此它会保留在代理风格的 OpenAI 兼容路径上，而不是使用原生 OpenAI 请求整形。 + 源代码中将 Kilo Gateway 记录为兼容 OpenRouter，因此它会保留在代理式的 OpenAI 兼容路径上，而不是使用原生 OpenAI 请求整形。 - - 由 Gemini 支持的 Kilo 引用会保留在 proxy-Gemini 路径上，因此 OpenClaw 会继续在该路径执行 Gemini thought-signature 清理，而不会启用原生 Gemini 重放校验或 bootstrap 重写。 + - 由 Gemini 支持的 Kilo 引用会保留在 proxy-Gemini 路径上，因此 OpenClaw 会在那里继续执行 Gemini thought-signature 清理，而不会启用原生 Gemini 重放校验或 bootstrap 重写。 - Kilo Gateway 在底层使用带有你的 API 密钥的 Bearer token。 - - Kilo 的共享流包装器会添加 provider app header，并为受支持的具体模型引用规范化代理推理负载。 + + Kilo 的共享流包装器会添加提供商应用头，并为受支持的具体模型引用规范化代理 reasoning 负载。 - `kilocode/kilo/auto` 和其他不支持代理推理的提示会跳过推理注入。如果你需要推理支持，请使用具体的模型引用，例如 `kilocode/anthropic/claude-sonnet-4`。 + `kilocode/kilo/auto` 以及其他不支持代理 reasoning 的提示会跳过 reasoning 注入。如果你需要 reasoning 支持，请使用具体模型引用，例如 `kilocode/anthropic/claude-sonnet-4`。 - - 如果模型发现过程在启动时失败，OpenClaw 会回退到包含 `kilocode/kilo/auto` 的内置静态目录。 - - 确认你的 API 密钥有效，并且你的 Kilo 账户已启用所需模型。 - - 当 Gateway 网关以守护进程方式运行时，确保 `KILOCODE_API_KEY` 对该进程可用（例如放在 `~/.openclaw/.env` 中，或通过 `env.shellEnv` 提供）。 + - 如果启动时模型发现失败，OpenClaw 会回退到包含 `kilocode/kilo/auto` 的内置静态目录。 + - 请确认你的 API 密钥有效，并且你的 Kilo 账户已启用所需模型。 + - 当 Gateway 网关以守护进程方式运行时，请确保 `KILOCODE_API_KEY` 对该进程可用（例如放在 `~/.openclaw/.env` 中，或通过 `env.shellEnv` 提供）。 @@ -118,12 +119,12 @@ Gateway 网关上任何可用模型都可以配合 `kilocode/` 前缀使用： - 选择提供商、模型引用和故障转移行为。 + 选择提供商、模型引用和回退行为。 - 完整的 OpenClaw 配置参考。 + OpenClaw 完整配置参考。 - Kilo Gateway 仪表板、API 密钥和账户管理。 + Kilo Gateway 控制台、API 密钥和账户管理。 diff --git a/docs/zh-CN/providers/openai.md b/docs/zh-CN/providers/openai.md index 450e67c1b..2a0709abc 100644 --- a/docs/zh-CN/providers/openai.md +++ b/docs/zh-CN/providers/openai.md @@ -1,46 +1,46 @@ --- read_when: - 你想在 OpenClaw 中使用 OpenAI 模型 - - 你想使用 Codex 订阅认证，而不是 API 密钥 + - 你想使用 Codex 订阅身份验证，而不是 API 密钥 - 你需要更严格的 GPT-5 智能体执行行为 summary: 在 OpenClaw 中通过 API 密钥或 Codex 订阅使用 OpenAI title: OpenAI x-i18n: - generated_at: "2026-04-23T18:44:56Z" + generated_at: "2026-04-23T19:26:09Z" model: gpt-5.4 provider: openai - source_hash: 69aa2a3badd2d3667e2164c4c492cb8e9caa8b911c750f9210b211b1a6c3ba66 + source_hash: 75c0492abf21cc2f0dfb83f32111b2b7e41cb85dd09ede6c1c45b18a135e46e1 source_path: providers/openai.md workflow: 15 --- # OpenAI - OpenAI 提供用于 GPT 模型的开发者 API。OpenClaw 支持两种认证方式： + OpenAI 为 GPT 模型提供开发者 API。OpenClaw 支持两种身份验证方式： - - **API 密钥** — 直接访问 OpenAI Platform，并按使用量计费（`openai/*` 模型） - - **Codex 订阅** — 通过 ChatGPT/Codex 登录并使用订阅访问（`openai-codex/*` 模型） + - **API 密钥** —— 通过 OpenAI Platform 直接访问，按使用量计费（`openai/*` 模型） + - **Codex 订阅** —— 通过 ChatGPT/Codex 登录并使用订阅访问（`openai-codex/*` 模型） - OpenAI 明确支持在像 OpenClaw 这样的外部工具和工作流中使用订阅 OAuth。 + OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OAuth。 ## OpenClaw 功能覆盖范围 - | OpenAI 能力 | OpenClaw 对应功能 | 状态 | + | OpenAI 能力 | OpenClaw 接口 | 状态 | | ------------------------- | ----------------------------------------- | ------------------------------------------------------ | - | 聊天 / Responses | `openai/` 模型提供商 | 是 | - | Codex 订阅模型 | `openai-codex/` 模型提供商 | 是 | - | 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，在启用 Web 搜索且未固定提供商时可用 | - | 图像 | `image_generate` | 是 | - | 视频 | `video_generate` | 是 | - | 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 | - | 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 | - | 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 | - | 实时语音 | Voice Call `realtime.provider: "openai"` | 是 | - | Embeddings | memory embedding provider | 是 | + | 聊天 / Responses | `openai/` 模型提供商 | 是 | + | Codex 订阅模型 | `openai-codex/` 模型提供商 | 是 | + | 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，当启用 Web 搜索且未固定提供商时 | + | 图像 | `image_generate` | 是 | + | 视频 | `video_generate` | 是 | + | 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 | + | 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 | + | 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 | + | 实时语音 | Voice Call `realtime.provider: "openai"` | 是 | + | Embeddings | memory embedding provider | 是 | ## 入门指南 - 选择你偏好的认证方式，并按照设置步骤进行操作。 + 选择你偏好的身份验证方式，并按步骤完成设置。 @@ -48,32 +48,32 @@ x-i18n: - 在 [OpenAI Platform 控制台](https://platform.openai.com/api-keys) 创建或复制一个 API 密钥。 + 在 [OpenAI Platform 仪表板](https://platform.openai.com/api-keys) 中创建或复制一个 API 密钥。 ```bash openclaw onboard --auth-choice openai-api-key ``` - 或者直接传入密钥： + 或直接传入密钥： ```bash openclaw onboard --openai-api-key "$OPENAI_API_KEY" ``` - + ```bash openclaw models list --provider openai ``` - ### 路由概览 + ### 路由摘要 - | Model ref | Route | Auth | + | Model ref | 路由 | 身份验证 | |-----------|-------|------| - | `openai/gpt-5.4` | 直接 OpenAI Platform API | `OPENAI_API_KEY` | - | `openai/gpt-5.4-pro` | 直接 OpenAI Platform API | `OPENAI_API_KEY` | + | `openai/gpt-5.5` | 直接 OpenAI Platform API | `OPENAI_API_KEY` | + | `openai/gpt-5.5-pro` | 直接 OpenAI Platform API | `OPENAI_API_KEY` | ChatGPT/Codex 登录通过 `openai-codex/*` 路由，而不是 `openai/*`。 @@ -84,18 +84,18 @@ x-i18n: ```json5 { env: { OPENAI_API_KEY: "sk-..." }, - agents: { defaults: { model: { primary: "openai/gpt-5.4" } } }, + agents: { defaults: { model: { primary: "openai/gpt-5.5" } } }, } ``` - OpenClaw **不会** 在直接 API 路径上公开 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型。Spark 仅限 Codex。 + OpenClaw **不会**在直接 API 路径中暴露 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型。Spark 仅限 Codex。 - **最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex 云端需要使用 ChatGPT 登录。 + **最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex cloud 需要 ChatGPT 登录。 @@ -109,7 +109,7 @@ x-i18n: openclaw models auth login --provider openai-codex ``` - 对于无头环境或不适合回调的设置，可添加 `--device-code`，通过 ChatGPT 设备码流程登录，而不是使用 localhost 浏览器回调： + 对于无头环境或不适合回调的设置，可添加 `--device-code`，使用 ChatGPT 设备码流程登录，而不是 localhost 浏览器回调： ```bash openclaw models auth login --provider openai-codex --device-code @@ -117,56 +117,56 @@ x-i18n: ```bash - openclaw config set agents.defaults.model.primary openai-codex/gpt-5.4 + openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5 ``` - + ```bash openclaw models list --provider openai-codex ``` - ### 路由概览 + ### 路由摘要 - | Model ref | Route | Auth | + | Model ref | 路由 | 身份验证 | |-----------|-------|------| - | `openai-codex/gpt-5.4` | ChatGPT/Codex OAuth | Codex 登录 | - | `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Codex 登录（取决于 entitlement） | + | `openai-codex/gpt-5.5` | ChatGPT/Codex OAuth | Codex 登录 | + | `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Codex 登录（取决于授权资格） | - 这一路由与 `openai/gpt-5.4` 是有意分开的。直接 Platform 访问请配合 API 密钥使用 `openai/*`，Codex 订阅访问请使用 `openai-codex/*`。 + 该路由与 `openai/gpt-5.5` 是刻意分开的。直接 Platform 访问请使用带 API 密钥的 `openai/*`，Codex 订阅访问请使用 `openai-codex/*`。 ### 配置示例 ```json5 { - agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } }, + agents: { defaults: { model: { primary: "openai-codex/gpt-5.5" } } }, } ``` - 新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备码流程登录——OpenClaw 会在其自己的智能体认证存储中管理生成的凭证。 + 新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备码流程登录 —— OpenClaw 会在自己的智能体身份验证存储中管理生成的凭证。 ### 上下文窗口上限 OpenClaw 将模型元数据和运行时上下文上限视为两个独立的值。 - 对于 `openai-codex/gpt-5.4`： + 对于 `openai-codex/gpt-5.5`： - - 原生 `contextWindow`：`1050000` + - 原生 `contextWindow`：`1000000` - 默认运行时 `contextTokens` 上限：`272000` - 在实际使用中，较小的默认上限通常具有更好的延迟和质量表现。你可以通过 `contextTokens` 覆盖它： + 在实践中，较小的默认上限通常具有更好的延迟和质量表现。你可以通过 `contextTokens` 覆盖它： ```json5 { models: { providers: { "openai-codex": { - models: [{ id: "gpt-5.4", contextTokens: 160000 }], + models: [{ id: "gpt-5.5", contextTokens: 160000 }], }, }, }, @@ -182,15 +182,15 @@ x-i18n: ## 图像生成 -内置的 `openai` 插件通过 `image_generate` 工具注册图像生成功能。 +内置的 `openai` 插件通过 `image_generate` 工具注册图像生成能力。 -| 能力 | 值 | +| Capability | Value | | ------------------------- | ---------------------------------- | -| 默认模型 | `openai/gpt-image-2` | -| 每次请求的最大图像数 | 4 | +| 默认模型 | `openai/gpt-image-2` | +| 每次请求的最大图像数 | 4 | | 编辑模式 | 已启用（最多 5 张参考图像） | -| 尺寸覆盖 | 支持，包括 2K/4K 尺寸 | -| 宽高比 / 分辨率 | 不会传递给 OpenAI Images API | +| 尺寸覆盖 | 支持，包括 2K/4K 尺寸 | +| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API | ```json5 { @@ -206,7 +206,7 @@ x-i18n: 有关共享工具参数、提供商选择和故障切换行为，请参见 [图像生成](/zh-CN/tools/image-generation)。 -`gpt-image-2` 是 OpenAI 文生图生成和图像编辑的默认模型。`gpt-image-1` 仍可作为显式模型覆盖使用，但新的 OpenAI 图像工作流应使用 `openai/gpt-image-2`。 +`gpt-image-2` 是 OpenAI 文生图和图像编辑的默认模型。`gpt-image-1` 仍可作为显式模型覆盖项使用，但新的 OpenAI 图像工作流应使用 `openai/gpt-image-2`。 生成： @@ -222,11 +222,11 @@ x-i18n: ## 视频生成 -内置的 `openai` 插件通过 `video_generate` 工具注册视频生成功能。 +内置的 `openai` 插件通过 `video_generate` 工具注册视频生成能力。 -| 能力 | 值 | +| Capability | Value | | ---------------- | --------------------------------------------------------------------------------- | -| 默认模型 | `openai/sora-2` | +| 默认模型 | `openai/sora-2` | | 模式 | 文生视频、图生视频、单视频编辑 | | 参考输入 | 1 张图像或 1 个视频 | | 尺寸覆盖 | 支持 | @@ -246,19 +246,19 @@ x-i18n: 有关共享工具参数、提供商选择和故障切换行为，请参见 [视频生成](/zh-CN/tools/video-generation)。 -## GPT-5 提示词扩展 +## GPT-5 提示词贡献 -OpenClaw 为跨提供商的 GPT-5 系列运行添加了共享的 GPT-5 提示词扩展。它按模型 id 应用，因此 `openai/gpt-5.4`、`openai-codex/gpt-5.4`、`openrouter/openai/gpt-5.4`、`opencode/gpt-5.4` 以及其他兼容的 GPT-5 引用都会接收相同的覆盖层。较旧的 GPT-4.x 模型则不会。 +OpenClaw 会为跨提供商的 GPT-5 系列运行添加一个共享的 GPT-5 提示词贡献。它按模型 id 生效，因此 `openai/gpt-5.5`、`openai-codex/gpt-5.5`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 以及其他兼容的 GPT-5 引用都会收到相同的叠加层。较旧的 GPT-4.x 模型不会应用。 -内置的原生 Codex harness 提供商（`codex/*`）通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和心跳覆盖层，因此 `codex/gpt-5.x` 会话即使其余 harness 提示词由 Codex 控制，也会保持相同的后续执行和主动心跳指导。 +内置的原生 Codex harness 提供商（`codex/*`）通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和 heartbeat 叠加层，因此即使 Codex 负责其余 harness 提示词，`codex/gpt-5.x` 会话仍会保持相同的后续跟进和主动 heartbeat 指引。 -GPT-5 扩展添加了带标签的行为契约，用于规范 persona 持续性、执行安全性、工具纪律、输出形态、完成检查和验证。渠道特定的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站传递策略中。GPT-5 指导始终对匹配的模型启用。友好交互风格层是单独的，并且可配置。 +GPT-5 贡献会添加一个带标签的行为契约，用于规范人格持续性、执行安全、工具纪律、输出形状、完成检查和验证。特定渠道的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站传递策略中。GPT-5 指引对匹配模型始终启用。友好交互风格层是独立的，并且可配置。 -| 值 | 效果 | +| Value | Effect | | ---------------------- | ------------------------------------------- | | `"friendly"`（默认） | 启用友好交互风格层 | -| `"on"` | `"friendly"` 的别名 | -| `"off"` | 仅禁用友好风格层 | +| `"on"` | `"friendly"` 的别名 | +| `"off"` | 仅禁用友好风格层 | @@ -282,30 +282,30 @@ GPT-5 扩展添加了带标签的行为契约，用于规范 persona 持续性 -这些值在运行时不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。 +运行时对值不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。 -旧版 `plugins.entries.openai.config.personality` 仍会作为兼容性回退项读取，但仅在未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 时生效。 +旧版 `plugins.entries.openai.config.personality` 在未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 时，仍会作为兼容性回退项读取。 -## 语音和语音识别 +## 语音与语音处理 - 内置的 `openai` 插件为 `messages.tts` 功能面注册了语音合成功能。 + 内置的 `openai` 插件会为 `messages.tts` 接口注册语音合成功能。 - | 设置 | 配置路径 | 默认值 | + | Setting | Config path | Default | |---------|------------|---------| | 模型 | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` | - | 音色 | `messages.tts.providers.openai.voice` | `coral` | - | 语速 | `messages.tts.providers.openai.speed` | （未设置） | + | 语音 | `messages.tts.providers.openai.voice` | `coral` | + | 速度 | `messages.tts.providers.openai.speed` | （未设置） | | 指令 | `messages.tts.providers.openai.instructions` | （未设置，仅 `gpt-4o-mini-tts`） | - | 格式 | `messages.tts.providers.openai.responseFormat` | 语音便笺为 `opus`，文件为 `mp3` | + | 格式 | `messages.tts.providers.openai.responseFormat` | 语音笔记为 `opus`，文件为 `mp3` | | API 密钥 | `messages.tts.providers.openai.apiKey` | 回退到 `OPENAI_API_KEY` | - | Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` | + | 基础 URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` | - 可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用音色：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。 + 可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用语音：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。 ```json5 { @@ -320,22 +320,23 @@ GPT-5 扩展添加了带标签的行为契约，用于规范 persona 持续性 ``` - 设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 的 Base URL，而不会影响聊天 API 端点。 + 设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 基础 URL，而不会影响聊天 API 端点。 - 内置的 `openai` 插件通过 OpenClaw 的媒体理解转录功能面注册批量语音转文本功能。 + 内置的 `openai` 插件通过 + OpenClaw 的媒体理解转录接口注册批量语音转文本功能。 - 默认模型：`gpt-4o-transcribe` - 端点：OpenAI REST `/v1/audio/transcriptions` - 输入路径：multipart 音频文件上传 - - 在 OpenClaw 中，凡是入站音频转录使用 - `tools.media.audio` 的地方都支持，包括 Discord 语音频道片段和渠道 + - 在 OpenClaw 中，只要入站音频转录使用 + `tools.media.audio`，就会受支持，包括 Discord 语音频道片段和渠道 音频附件 - 如需强制将 OpenAI 用于入站音频转录： + 如需强制对入站音频转录使用 OpenAI： ```json5 { @@ -355,14 +356,14 @@ GPT-5 扩展添加了带标签的行为契约，用于规范 persona 持续性 } ``` - 当共享音频媒体配置或每次调用的转录请求提供语言和提示词线索时，这些信息会转发给 OpenAI。 + 当共享音频媒体配置或按次调用的转录请求提供了语言和提示词提示时，这些内容会转发给 OpenAI。 - 内置的 `openai` 插件为 Voice Call 插件注册实时转录功能。 + 内置的 `openai` 插件会为 Voice Call 插件注册实时转录功能。 - | 设置 | 配置路径 | 默认值 | + | Setting | Config path | Default | |---------|------------|---------| | 模型 | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` | | 语言 | `...openai.language` | （未设置） | @@ -372,19 +373,19 @@ GPT-5 扩展添加了带标签的行为契约，用于规范 persona 持续性 | API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` | - 使用到 `wss://api.openai.com/v1/realtime` 的 WebSocket 连接，并采用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。此流式提供商用于 Voice Call 的实时转录路径；Discord 语音目前仍记录短片段，并改用批量 `tools.media.audio` 转录路径。 + 使用 WebSocket 连接到 `wss://api.openai.com/v1/realtime`，并采用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。该流式提供商用于 Voice Call 的实时转录路径；Discord 语音当前仍会录制短片段，并改用批量 `tools.media.audio` 转录路径。 - 内置的 `openai` 插件为 Voice Call 插件注册实时语音功能。 + 内置的 `openai` 插件会为 Voice Call 插件注册实时语音功能。 - | 设置 | 配置路径 | 默认值 | + | Setting | Config path | Default | |---------|------------|---------| | 模型 | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` | - | 音色 | `...openai.voice` | `alloy` | - | 温度 | `...openai.temperature` | `0.8` | + | 语音 | `...openai.voice` | `alloy` | + | Temperature | `...openai.temperature` | `0.8` | | VAD 阈值 | `...openai.vadThreshold` | `0.5` | | 静音时长 | `...openai.silenceDurationMs` | `500` | | API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` | @@ -398,21 +399,24 @@ GPT-5 扩展添加了带标签的行为契约，用于规范 persona 持续性 ## Azure OpenAI 端点 -内置的 `openai` 提供商可以通过覆盖 base URL，将图像生成请求定向到 Azure OpenAI 资源。在图像生成路径上，OpenClaw 会检测 `models.providers.openai.baseUrl` 中的 Azure 主机名，并自动切换到 Azure 的请求格式。 +内置的 `openai` 提供商可以通过覆盖基础 URL，将图像 +生成请求定向到 Azure OpenAI 资源。在图像生成路径上，OpenClaw +会检测 `models.providers.openai.baseUrl` 上的 Azure 主机名，并自动切换到 +Azure 的请求格式。 -实时语音使用独立的配置路径 +实时语音使用单独的配置路径 （`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`）， -不受 `models.providers.openai.baseUrl` 影响。其 Azure 设置请参见 -[语音和语音识别](#voice-and-speech) 下的 **实时语音** +不会受 `models.providers.openai.baseUrl` 影响。其 Azure +设置请参见 [语音与语音处理](#voice-and-speech) 下的**实时语音** 折叠面板。 -在以下情况下使用 Azure OpenAI： +以下情况下可使用 Azure OpenAI： -- 你已经有 Azure OpenAI 订阅、配额或企业协议 +- 你已经拥有 Azure OpenAI 订阅、配额或企业协议 - 你需要 Azure 提供的区域数据驻留或合规控制 -- 你希望将流量保留在现有 Azure 租户内 +- 你希望将流量保留在现有 Azure 租户内部 ### 配置 @@ -433,26 +437,27 @@ Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）： } ``` -OpenClaw 会将以下 Azure 主机后缀识别为 Azure 图像生成路由： +OpenClaw 会识别以下 Azure 主机后缀，并将其用于 Azure 图像生成 +路由： - `*.openai.azure.com` - `*.services.ai.azure.com` - `*.cognitiveservices.azure.com` -对于发往已识别 Azure 主机的图像生成请求，OpenClaw 会： +对于识别出的 Azure 主机上的图像生成请求，OpenClaw 会： -- 发送 `api-key` 请求头，而不是 `Authorization: Bearer` -- 使用以 deployment 为范围的路径（`/openai/deployments/{deployment}/...`） -- 为每个请求追加 `?api-version=...` +- 发送 `api-key` 标头，而不是 `Authorization: Bearer` +- 使用以部署为作用域的路径（`/openai/deployments/{deployment}/...`） +- 在每个请求后追加 `?api-version=...` -其他 base URL（公共 OpenAI、兼容 OpenAI 的代理）会继续使用标准的 +其他基础 URL（公共 OpenAI、兼容 OpenAI 的代理）会继续使用标准 OpenAI 图像请求格式。 `openai` 提供商图像生成路径的 Azure 路由要求 OpenClaw 2026.4.22 或更高版本。更早版本会将任何自定义 -`openai.baseUrl` 都当作公共 OpenAI 端点处理，因此在 Azure -图像 deployment 上会失败。 +`openai.baseUrl` 视为公共 OpenAI 端点，因此会在 Azure +图像部署上失败。 ### API 版本 @@ -465,70 +470,72 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview" 当该变量未设置时，默认值为 `2024-12-01-preview`。 -### 模型名称就是 deployment 名称 +### 模型名称就是部署名称 -Azure OpenAI 会将模型绑定到 deployment。对于通过内置 `openai` 提供商路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段必须是你在 Azure 门户中配置的 **Azure deployment 名称**，而不是公共 OpenAI 模型 id。 +Azure OpenAI 会将模型绑定到部署。对于通过内置 `openai` 提供商路由的 Azure 图像生成请求， +OpenClaw 中的 `model` 字段必须是你在 Azure 门户中配置的 **Azure 部署名称**， +而不是公开的 OpenAI 模型 id。 -如果你创建了一个名为 `gpt-image-2-prod` 的 deployment，用于提供 `gpt-image-2`： +如果你创建了一个名为 `gpt-image-2-prod` 且提供 `gpt-image-2` 的部署： ``` /tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1 ``` -同样的 deployment 名称规则也适用于通过内置 `openai` 提供商路由的图像生成调用。 +同样的部署名称规则也适用于通过内置 `openai` 提供商路由的图像生成调用。 ### 区域可用性 -Azure 图像生成目前仅在部分区域可用 +Azure 图像生成当前仅在部分区域可用 （例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、 -`uaenorth`）。创建 deployment 之前，请先查看 Microsoft 当前的区域列表，并确认你的区域提供该特定模型。 +`uaenorth`）。创建 +部署前，请先检查 Microsoft 当前的区域列表，并确认特定模型在你的区域中可用。 ### 参数差异 -Azure OpenAI 和公共 OpenAI 并不总是接受相同的图像参数。 -Azure 可能会拒绝公共 OpenAI 允许的某些选项（例如 +Azure OpenAI 与公共 OpenAI 并不总是接受相同的图像参数。 +Azure 可能会拒绝公共 OpenAI 允许的选项（例如 `gpt-image-2` 上某些 `background` 值），或者仅在特定模型 -版本上提供这些选项。这些差异来自 Azure 和底层模型，而不是 -OpenClaw。如果 Azure 请求因验证错误失败，请在 -Azure 门户中检查你的特定 deployment 和 API 版本所支持的参数集。 +版本中提供这些选项。这些差异来自 Azure 和底层模型，而不是 +OpenClaw。如果 Azure 请求因验证错误而失败，请检查 +Azure 门户中你的具体部署和 API 版本所支持的参数集。 -Azure OpenAI 使用原生传输和兼容行为，但不会收到 -OpenClaw 的隐藏归因请求头——详见 [高级配置](#advanced-configuration) 下 -**原生与兼容 OpenAI 路由** -折叠面板。 +Azure OpenAI 使用原生传输和兼容行为，但不会接收 +OpenClaw 的隐藏归因标头——参见 [高级配置](#advanced-configuration) 下 +**原生 vs OpenAI 兼容路由** 折叠面板。 -若要在 Azure 上处理聊天或 Responses 流量（除图像生成之外），请使用 +对于 Azure 上的聊天或 Responses 流量（除图像生成之外），请使用 新手引导流程或专用的 Azure 提供商配置——仅设置 `openai.baseUrl` -并不会启用 Azure 的 API / 认证格式。另有一个单独的 -`azure-openai-responses/*` 提供商；请参见 -下方的“服务端压缩”折叠面板。 +不会自动采用 Azure 的 API/身份验证格式。另有一个独立的 +`azure-openai-responses/*` 提供商；请参见下面的 +服务端压缩折叠面板。 ## 高级配置 - - OpenClaw 对 `openai/*` 和 `openai-codex/*` 都采用 WebSocket 优先，并在失败时回退到 SSE（`"auto"`）。 + + OpenClaw 对 `openai/*` 和 `openai-codex/*` 均默认使用 WebSocket 优先并在失败时回退到 SSE（`"auto"`）。 在 `"auto"` 模式下，OpenClaw 会： - 在回退到 SSE 之前，对一次早期 WebSocket 失败进行一次重试 - - 失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE - - 为重试和重连附加稳定的会话和轮次身份请求头 + - 发生失败后，将 WebSocket 标记为降级状态约 60 秒，并在冷却期间使用 SSE + - 为重试和重连附加稳定的会话和轮次身份标头 - 在不同传输变体之间标准化用量计数器（`input_tokens` / `prompt_tokens`） - | 值 | 行为 | + | Value | Behavior | |-------|----------| - | `"auto"`（默认） | WebSocket 优先，SSE 回退 | - | `"sse"` | 仅强制使用 SSE | - | `"websocket"` | 仅强制使用 WebSocket | + | `"auto"`（默认） | WebSocket 优先，失败时回退到 SSE | + | `"sse"` | 强制仅使用 SSE | + | `"websocket"` | 强制仅使用 WebSocket | ```json5 { agents: { defaults: { models: { - "openai-codex/gpt-5.4": { + "openai-codex/gpt-5.5": { params: { transport: "auto" }, }, }, @@ -544,7 +551,7 @@ OpenClaw 的隐藏归因请求头——详见 [高级配置](#advanced-configura - OpenClaw 默认对 `openai/*` 启用 WebSocket 预热，以降低首轮延迟。 + OpenClaw 默认会为 `openai/*` 启用 WebSocket 预热，以降低首轮延迟。 ```json5 // 禁用预热 @@ -552,7 +559,7 @@ OpenClaw 的隐藏归因请求头——详见 [高级配置](#advanced-configura agents: { defaults: { models: { - "openai/gpt-5.4": { + "openai/gpt-5.5": { params: { openaiWsWarmup: false }, }, }, @@ -564,20 +571,20 @@ OpenClaw 的隐藏归因请求头——详见 [高级配置](#advanced-configura - OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供共享的快速模式开关： + OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供统一的快速模式开关： - - **聊天 / UI：** `/fast status|on|off` + - **聊天/UI：** `/fast status|on|off` - **配置：** `agents.defaults.models["/"].params.fastMode` - 启用后，OpenClaw 会将快速模式映射到 OpenAI 优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，快速模式不会改写 `reasoning` 或 `text.verbosity`。 + 启用后，OpenClaw 会将快速模式映射为 OpenAI 优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，快速模式不会重写 `reasoning` 或 `text.verbosity`。 ```json5 { agents: { defaults: { models: { - "openai/gpt-5.4": { params: { fastMode: true } }, - "openai-codex/gpt-5.4": { params: { fastMode: true } }, + "openai/gpt-5.5": { params: { fastMode: true } }, + "openai-codex/gpt-5.5": { params: { fastMode: true } }, }, }, }, @@ -585,21 +592,21 @@ OpenClaw 的隐藏归因请求头——详见 [高级配置](#advanced-configura ``` - 会话覆盖优先于配置。清除 Sessions UI 中的会话覆盖后，会话将返回配置的默认值。 + 会话覆盖的优先级高于配置。在 Sessions UI 中清除会话覆盖项后，会话将返回到配置的默认值。 - OpenAI 的 API 通过 `service_tier` 提供优先处理能力。你可以在 OpenClaw 中按模型设置： + OpenAI 的 API 通过 `service_tier` 暴露优先处理能力。你可以在 OpenClaw 中按模型设置它： ```json5 { agents: { defaults: { models: { - "openai/gpt-5.4": { params: { serviceTier: "priority" } }, - "openai-codex/gpt-5.4": { params: { serviceTier: "priority" } }, + "openai/gpt-5.5": { params: { serviceTier: "priority" } }, + "openai-codex/gpt-5.5": { params: { serviceTier: "priority" } }, }, }, }, @@ -609,7 +616,7 @@ OpenClaw 的隐藏归因请求头——详见 [高级配置](#advanced-configura 支持的值：`auto`、`default`、`flex`、`priority`。 - `serviceTier` 仅会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 会保持 `service_tier` 不变。 + `serviceTier` 仅会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由其中任一提供商，OpenClaw 会保持 `service_tier` 不变。 @@ -617,20 +624,20 @@ OpenClaw 的隐藏归因请求头——详见 [高级配置](#advanced-configura 对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenClaw 会自动启用服务端压缩： - - 强制设置 `store: true`（除非模型兼容性设置了 `supportsStore: false`） + - 强制 `store: true`（除非模型兼容性设置了 `supportsStore: false`） - 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]` - 默认 `compact_threshold`：`contextWindow` 的 70%（如果不可用则为 `80000`） - 对于兼容端点（如 Azure OpenAI Responses）很有用： + 对 Azure OpenAI Responses 这类兼容端点很有用： ```json5 { agents: { defaults: { models: { - "azure-openai-responses/gpt-5.4": { + "azure-openai-responses/gpt-5.5": { params: { responsesServerCompaction: true }, }, }, @@ -645,7 +652,7 @@ OpenClaw 的隐藏归因请求头——详见 [高级配置](#advanced-configura agents: { defaults: { models: { - "openai/gpt-5.4": { + "openai/gpt-5.5": { params: { responsesServerCompaction: true, responsesCompactThreshold: 120000, @@ -663,7 +670,7 @@ OpenClaw 的隐藏归因请求头——详见 [高级配置](#advanced-configura agents: { defaults: { models: { - "openai/gpt-5.4": { + "openai/gpt-5.5": { params: { responsesServerCompaction: false }, }, }, @@ -675,13 +682,13 @@ OpenClaw 的隐藏归因请求头——详见 [高级配置](#advanced-configura - `responsesServerCompaction` 仅控制 `context_management` 的注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性配置将 `supportsStore` 设为 `false`。 + `responsesServerCompaction` 仅控制 `context_management` 注入。直接 OpenAI Responses 模型仍会强制 `store: true`，除非兼容性设置了 `supportsStore: false`。 - - 对于 `openai/*` 和 `openai-codex/*` 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的嵌入式执行契约： + + 对于 `openai/*` 和 `openai-codex/*` 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的内嵌执行契约： ```json5 { @@ -693,33 +700,33 @@ OpenClaw 的隐藏归因请求头——详见 [高级配置](#advanced-configura } ``` - 启用 `strict-agentic` 后，OpenClaw 会： - - 当工具操作可用时，不再将仅有计划的轮次视为成功进展 - - 使用“立即行动”的引导重试该轮 - - 在处理较大任务时自动启用 `update_plan` - - 如果模型持续只做规划而不执行操作，则显示明确的阻塞状态 + 使用 `strict-agentic` 时，OpenClaw 会： + - 当有工具操作可用时，不再将仅规划的轮次视为成功进展 + - 使用“立即行动”的引导重试该轮次 + - 对于重要工作，自动启用 `update_plan` + - 如果模型持续规划而不执行，则显式显示阻塞状态 - 仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧的模型系列仍保持默认行为。 + 仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧的模型系列会保持默认行为。 - - OpenClaw 会区别对待直接 OpenAI、Codex 和 Azure OpenAI 端点，与通用兼容 OpenAI 的 `/v1` 代理不同： + + OpenClaw 会以不同方式处理直接 OpenAI、Codex 和 Azure OpenAI 端点，与通用兼容 OpenAI 的 `/v1` 代理不同： **原生路由**（`openai/*`、`openai-codex/*`、Azure OpenAI）： - 仅对支持 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }` - - 对拒绝 `reasoning.effort: "none"` 的模型或代理省略已禁用的 reasoning + - 对于会拒绝 `reasoning.effort: "none"` 的模型或代理，省略禁用推理设置 - 默认将工具 schema 设为严格模式 - - 仅在经过验证的原生主机上附加隐藏归因请求头 - - 保留 OpenAI 专用的请求整形（`service_tier`、`store`、reasoning 兼容性、提示词缓存提示） + - 仅在已验证的原生主机上附加隐藏归因标头 + - 保留仅适用于 OpenAI 的请求整形（`service_tier`、`store`、reasoning 兼容性、提示词缓存提示） - **代理 / 兼容路由：** - - 使用更宽松的兼容行为 - - 不强制严格工具 schema，也不附加原生专用请求头 + **代理/兼容路由：** + - 使用更宽松的兼容性行为 + - 不强制严格工具 schema，也不附加仅原生支持的标头 - Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因请求头。 + Azure OpenAI 使用原生传输和兼容性行为，但不会接收隐藏归因标头。 @@ -736,7 +743,7 @@ OpenClaw 的隐藏归因请求头——详见 [高级配置](#advanced-configura 共享视频工具参数和提供商选择。 - - 认证细节和凭证复用规则。 + + 身份验证细节和凭证复用规则。 diff --git a/docs/zh-CN/providers/opencode.md b/docs/zh-CN/providers/opencode.md index cd55e1769..69bac891b 100644 --- a/docs/zh-CN/providers/opencode.md +++ b/docs/zh-CN/providers/opencode.md @@ -1,14 +1,14 @@ --- read_when: - - 你想要通过 OpenCode 托管的模型访问 - - 你想在 Zen 目录和 Go 目录之间进行选择 -summary: 使用 OpenCode Zen 和 Go 目录配合 OpenClaw + - 你想使用 OpenCode 托管的模型访问方式 + - 你想在 Zen 和 Go 目录之间进行选择 +summary: 将 OpenCode Zen 和 Go 目录与 OpenClaw 一起使用 title: OpenCode x-i18n: - generated_at: "2026-04-12T10:36:44Z" + generated_at: "2026-04-23T19:26:30Z" model: gpt-5.4 provider: openai - source_hash: a68444d8c403c3caba4a18ea47f078c7a4c163f874560e1fad0e818afb6e0e60 + source_hash: d958a8b32277cf4e40f086e6f8281826c70a7583823216403bca09108778f3b3 source_path: providers/opencode.md workflow: 15 --- @@ -17,13 +17,13 @@ x-i18n: OpenCode 在 OpenClaw 中提供两个托管目录： -| 目录 | 前缀 | 运行时提供商 | +| 目录 | 前缀 | 运行时提供商 | | ------- | ----------------- | ---------------- | -| **Zen** | `opencode/...` | `opencode` | -| **Go** | `opencode-go/...` | `opencode-go` | +| **Zen** | `opencode/...` | `opencode` | +| **Go** | `opencode-go/...` | `opencode-go` | -两个目录都使用同一个 OpenCode API 密钥。OpenClaw 会将运行时提供商 id 分开， -以确保上游按模型路由保持正确，但新手引导和文档会将它们视为同一个 OpenCode 设置。 +这两个目录使用同一个 OpenCode API key。OpenClaw 会将运行时 provider ID 拆分开， +以确保上游的按模型路由保持正确，但新手引导和文档会将它们视为同一个 OpenCode 设置。 ## 入门指南 @@ -37,7 +37,7 @@ OpenCode 在 OpenClaw 中提供两个托管目录： openclaw onboard --auth-choice opencode-zen ``` - 或者直接传入密钥： + 或直接传入 key： ```bash openclaw onboard --opencode-zen-api-key "$OPENCODE_API_KEY" @@ -58,7 +58,7 @@ OpenCode 在 OpenClaw 中提供两个托管目录： - **最适合：** 由 OpenCode 托管的 Kimi、GLM 和 MiniMax 阵容。 + **最适合：** OpenCode 托管的 Kimi、GLM 和 MiniMax 产品线。 @@ -66,7 +66,7 @@ OpenCode 在 OpenClaw 中提供两个托管目录： openclaw onboard --auth-choice opencode-go ``` - 或者直接传入密钥： + 或直接传入 key： ```bash openclaw onboard --opencode-go-api-key "$OPENCODE_API_KEY" @@ -100,39 +100,39 @@ OpenCode 在 OpenClaw 中提供两个托管目录： ### Zen -| 属性 | 值 | +| 属性 | 值 | | ---------------- | ----------------------------------------------------------------------- | -| 运行时提供商 | `opencode` | -| 示例模型 | `opencode/claude-opus-4-6`, `opencode/gpt-5.4`, `opencode/gemini-3-pro` | +| 运行时提供商 | `opencode` | +| 示例模型 | `opencode/claude-opus-4-6`、`opencode/gpt-5.5`、`opencode/gemini-3-pro` | ### Go -| 属性 | 值 | +| 属性 | 值 | | ---------------- | ------------------------------------------------------------------------ | -| 运行时提供商 | `opencode-go` | -| 示例模型 | `opencode-go/kimi-k2.5`, `opencode-go/glm-5`, `opencode-go/minimax-m2.5` | +| 运行时提供商 | `opencode-go` | +| 示例模型 | `opencode-go/kimi-k2.5`、`opencode-go/glm-5`、`opencode-go/minimax-m2.5` | ## 高级说明 - + 也支持将 `OPENCODE_ZEN_API_KEY` 作为 `OPENCODE_API_KEY` 的别名。 - 在设置期间输入一个 OpenCode 密钥后，会为两个运行时提供商都存储凭证。 - 你不需要分别为每个目录单独进行新手引导。 + 在设置期间输入一个 OpenCode key，会为两个运行时 provider 都存储凭证。 + 你不需要分别为每个目录执行新手引导。 - - 你需要登录 OpenCode，添加计费信息，并复制你的 API 密钥。计费 - 和目录可用性由 OpenCode 控制台统一管理。 + + 你需要登录 OpenCode、添加计费信息并复制你的 API key。计费 + 和目录可用性都在 OpenCode 控制台中管理。 由 Gemini 支持的 OpenCode 引用会保留在 proxy-Gemini 路径上，因此 OpenClaw 会 - 在该路径上保留 Gemini thought-signature 清理，而不会启用原生 Gemini - 重放验证或 bootstrap 重写。 + 在该路径上继续保留 Gemini thought-signature 清理，而不会启用原生 Gemini + 重放校验或 bootstrap 重写。 @@ -141,17 +141,17 @@ OpenCode 在 OpenClaw 中提供两个托管目录： -在设置期间输入一个 OpenCode 密钥后，会为 Zen 和 Go -运行时提供商都存储凭证，因此你只需要进行一次新手引导。 +在设置期间输入一个 OpenCode key，会为 Zen 和 +Go 两个运行时 provider 都存储凭证，因此你只需要执行一次新手引导。 ## 相关内容 - 选择提供商、模型引用和故障切换行为。 + 选择 provider、模型引用和故障切换行为。 - agents、models 和 providers 的完整配置参考。 + 智能体、模型和 provider 的完整配置参考。 diff --git a/docs/zh-CN/providers/vercel-ai-gateway.md b/docs/zh-CN/providers/vercel-ai-gateway.md index 5e1718aa2..5bc58451c 100644 --- a/docs/zh-CN/providers/vercel-ai-gateway.md +++ b/docs/zh-CN/providers/vercel-ai-gateway.md @@ -1,38 +1,41 @@ --- read_when: - 你想将 Vercel AI Gateway 与 OpenClaw 一起使用 - - 你需要 API 密钥环境变量或 CLI 认证选项 -summary: Vercel AI Gateway 设置（认证 + 模型选择） -title: Vercel AI Gateway 网关 + - 你需要 API 密钥环境变量或 CLI 凭证选择项 +summary: Vercel AI Gateway 设置（凭证 + 模型选择） +title: Vercel AI Gateway x-i18n: - generated_at: "2026-04-22T03:53:30Z" + generated_at: "2026-04-23T19:26:32Z" model: gpt-5.4 provider: openai - source_hash: 11c0f764d4c35633d0fbfc189bae0fc451dc799002fc1a6d0c84fc73842bbe31 + source_hash: 410dfb7c0f44337653906b661612d946ccf48716ae700a718a4f004b03bc1261 source_path: providers/vercel-ai-gateway.md workflow: 15 --- -# Vercel AI Gateway 网关 +# Vercel AI Gateway -[Vercel AI Gateway](https://vercel.com/ai-gateway) 提供统一的 API，让你通过单个端点访问数百种模型。 +[Vercel AI Gateway](https://vercel.com/ai-gateway) 提供统一 API，可通过单一端点访问数百种模型。 -| Property | Value | +| 属性 | 值 | | ------------- | -------------------------------- | | 提供商 | `vercel-ai-gateway` | -| 认证 | `AI_GATEWAY_API_KEY` | -| API | 与 Anthropic Messages 兼容 | +| 凭证 | `AI_GATEWAY_API_KEY` | +| API | 兼容 Anthropic Messages | | 模型目录 | 通过 `/v1/models` 自动发现 | -OpenClaw 会自动发现 Gateway 网关 的 `/v1/models` 目录，因此 `/models vercel-ai-gateway` 会包含当前的模型引用，例如 `vercel-ai-gateway/openai/gpt-5.4` 和 `vercel-ai-gateway/moonshotai/kimi-k2.6`。 +OpenClaw 会自动发现 Gateway 网关的 `/v1/models` 目录，因此 +`/models vercel-ai-gateway` 会包含当前模型引用，例如 +`vercel-ai-gateway/openai/gpt-5.5` 和 +`vercel-ai-gateway/moonshotai/kimi-k2.6`。 ## 入门指南 - 运行新手引导并选择 AI Gateway 网关 认证选项： + 运行新手引导并选择 AI Gateway 凭证选项： ```bash openclaw onboard --auth-choice ai-gateway-api-key @@ -40,7 +43,7 @@ OpenClaw 会自动发现 Gateway 网关 的 `/v1/models` 目录，因此 `/model - 将该模型添加到你的 OpenClaw 配置中： + 将模型添加到你的 OpenClaw 配置中： ```json5 { @@ -62,7 +65,7 @@ OpenClaw 会自动发现 Gateway 网关 的 `/v1/models` 目录，因此 `/model ## 非交互式示例 -对于脚本化或 CI 设置，请在命令行中传递所有值： +对于脚本化或 CI 设置，请在命令行中传入所有值： ```bash openclaw onboard --non-interactive \ @@ -73,31 +76,32 @@ openclaw onboard --non-interactive \ ## 模型 ID 简写 -OpenClaw 接受 Vercel Claude 的简写模型引用，并会在运行时将其标准化： +OpenClaw 接受 Vercel Claude 简写模型引用，并会在运行时将其规范化： -| 简写输入 | 标准化后的模型引用 | +| 简写输入 | 规范化后的模型引用 | | ----------------------------------- | --------------------------------------------- | | `vercel-ai-gateway/claude-opus-4.6` | `vercel-ai-gateway/anthropic/claude-opus-4.6` | | `vercel-ai-gateway/opus-4.6` | `vercel-ai-gateway/anthropic/claude-opus-4-6` | -你可以在配置中使用简写或完整限定的模型引用。OpenClaw 会自动解析为规范形式。 +你可以在配置中使用简写，也可以使用完整模型引用。OpenClaw 会自动解析为规范形式。 ## 高级说明 - - 如果 OpenClaw Gateway 网关 以守护进程（launchd/systemd）方式运行，请确保 `AI_GATEWAY_API_KEY` 可供该进程使用。 + + 如果 OpenClaw Gateway 网关以守护进程方式运行（launchd/systemd），请确保 + `AI_GATEWAY_API_KEY` 对该进程可用。 - 如果密钥只设置在 `~/.profile` 中，除非显式导入该环境，否则 launchd/systemd 守护进程将无法看到它。请在 `~/.openclaw/.env` 中设置该密钥，或通过 `env.shellEnv` 设置，以确保 Gateway 网关 进程可以读取它。 + 如果密钥仅设置在 `~/.profile` 中，那么 launchd/systemd 守护进程将无法看到它，除非显式导入该环境。请将密钥设置在 `~/.openclaw/.env` 中，或通过 `env.shellEnv` 提供，以确保 Gateway 网关进程可以读取它。 - Vercel AI Gateway 网关 会根据模型引用前缀将请求路由到上游提供商。例如，`vercel-ai-gateway/anthropic/claude-opus-4.6` 会通过 Anthropic 路由，`vercel-ai-gateway/openai/gpt-5.4` 会通过 OpenAI 路由，而 `vercel-ai-gateway/moonshotai/kimi-k2.6` 会通过 Moonshot AI 路由。单个 `AI_GATEWAY_API_KEY` 即可处理所有上游提供商的认证。 + Vercel AI Gateway 会根据模型引用前缀将请求路由到上游提供商。例如，`vercel-ai-gateway/anthropic/claude-opus-4.6` 会通过 Anthropic 路由，而 `vercel-ai-gateway/openai/gpt-5.5` 会通过 OpenAI 路由，`vercel-ai-gateway/moonshotai/kimi-k2.6` 会通过 MoonshotAI 路由。你的单个 `AI_GATEWAY_API_KEY` 会处理所有上游提供商的认证。 @@ -105,9 +109,9 @@ OpenClaw 接受 Vercel Claude 的简写模型引用，并会在运行时将其 - 选择提供商、模型引用和故障切换行为。 + 选择提供商、模型引用和回退行为。 - 常规故障排除和常见问题。 + 通用故障排除和常见问题。 diff --git a/docs/zh-CN/refactor/qa.md b/docs/zh-CN/refactor/qa.md index cb033602f..211e3efdb 100644 --- a/docs/zh-CN/refactor/qa.md +++ b/docs/zh-CN/refactor/qa.md @@ -1,14 +1,14 @@ --- read_when: - - 重构 QA 场景定义或 qa-lab 测试框架代码 - - 在 Markdown 场景与 TypeScript 测试框架逻辑之间迁移 QA 行为 -summary: QA 重构：场景目录与测试框架整合计划 + - 重构 QA 场景定义或 qa-lab Harness 代码 + - 在 Markdown 场景与 TypeScript Harness 逻辑之间迁移 QA 行为 +summary: 用于场景目录和 Harness 整合的 QA 重构计划 title: QA 重构 x-i18n: - generated_at: "2026-04-23T06:43:04Z" + generated_at: "2026-04-23T19:26:47Z" model: gpt-5.4 provider: openai - source_hash: 16867d5be372ab414aa516144193144414c326ea53a52627f3ff91f85b8fdf9d + source_hash: ffb9c79628fa6208dfaf731c6fb4c767e85a126c8f2066ca859721c5f62b9ab9 source_path: refactor/qa.md workflow: 15 --- @@ -19,21 +19,21 @@ x-i18n: ## 目标 -将 OpenClaw QA 从分裂定义模型迁移为单一事实来源： +将 OpenClaw QA 从分裂式定义模型迁移为单一事实来源： - 场景元数据 - 发送给模型的提示词 -- 设置与清理 -- 测试框架逻辑 +- setup 和 teardown +- Harness 逻辑 - 断言与成功标准 - 产物与报告提示 -期望的最终状态是：一个通用 QA 测试框架加载功能强大的场景定义文件，而不是在 TypeScript 中硬编码大部分行为。 +期望的最终状态是：一个通用 QA Harness 加载强大的场景定义文件，而不是将大部分行为硬编码在 TypeScript 中。 ## 当前状态 -当前的主要事实来源已位于 `qa/scenarios/index.md`，以及 -`qa/scenarios//*.md` 下每个场景对应的单独文件中。 +主要事实来源现在位于 `qa/scenarios/index.md`，以及每个场景对应的 +`qa/scenarios//*.md` 文件。 已实现： @@ -44,29 +44,29 @@ x-i18n: - `qa/scenarios//*.md` - 每个场景一个 Markdown 文件 - 场景元数据 - - handler 绑定 - - 场景特定执行配置 + - 处理器绑定 + - 场景专用执行配置 - `extensions/qa-lab/src/scenario-catalog.ts` - Markdown 包解析器 + zod 校验 - `extensions/qa-lab/src/qa-agent-bootstrap.ts` - - 从 Markdown 包渲染计划 + - 基于 Markdown 包渲染计划 - `extensions/qa-lab/src/qa-agent-workspace.ts` - - 生成兼容性种子文件以及 `QA_SCENARIOS.md` + - 生成兼容性文件以及 `QA_SCENARIOS.md` - `extensions/qa-lab/src/suite.ts` - - 通过 Markdown 定义的 handler 绑定选择可执行场景 + - 通过 Markdown 定义的处理器绑定选择可执行场景 - QA bus 协议 + UI - 用于图像/视频/音频/文件渲染的通用内联附件 -仍然分裂的表面： +仍然存在的分裂界面： - `extensions/qa-lab/src/suite.ts` - - 仍然承载大部分可执行的自定义 handler 逻辑 + - 仍然承载大部分可执行的自定义处理器逻辑 - `extensions/qa-lab/src/report.ts` - - 仍然从运行时输出中推导报告结构 + - 仍然从运行时输出推导报告结构 -因此，事实来源分裂的问题已修复，但执行层面目前仍主要依赖 handler，而非完全声明式。 +因此，事实来源分裂的问题已经修复，但执行层仍主要由处理器支持，而不是完全声明式。 -## 实际的场景表面是什么样的 +## 实际的场景界面是什么样的 阅读当前 suite 可以看到几类不同的场景。 @@ -74,16 +74,16 @@ x-i18n: - 渠道基线 - 私信基线 -- 线程跟进 +- 线程后续跟进 - 模型切换 -- 审批继续执行 -- 反应/编辑/删除 +- 审批后续执行 +- reaction/edit/delete ### 配置与运行时变更 -- 配置补丁禁用 Skills -- 配置应用后重启唤醒 -- 配置重启能力切换 +- config patch 技能禁用 +- config apply 重启唤醒 +- config restart 能力切换 - 运行时清单漂移检查 ### 文件系统与仓库断言 @@ -92,47 +92,47 @@ x-i18n: - 构建 Lobster Invaders - 生成图像产物查找 -### Memory 编排 +### 内存编排 -- 记忆召回 -- 渠道上下文中的记忆工具 -- 记忆失败回退 -- 会话记忆排序 -- 线程记忆隔离 -- 记忆 Dreaming 扫描 +- 内存回忆 +- 渠道上下文中的内存工具 +- 内存失败回退 +- 会话内存排序 +- 线程内存隔离 +- memory dreaming sweep ### 工具与插件集成 - MCP plugin-tools 调用 -- skill 可见性 -- skill 热安装 +- 技能可见性 +- 技能热安装 - 原生图像生成 - 图像往返 -- 从附件理解图像 +- 基于附件的图像理解 -### 多轮与多参与者 +### 多轮次与多参与者 -- 子智能体移交 -- 子智能体扇出综合 +- subagent 切换交接 +- subagent 扇出综合 - 重启恢复类流程 -这些分类之所以重要，是因为它们决定了 DSL 的需求。仅有“提示词 + 期望文本”的扁平列表是不够的。 +这些类别很重要，因为它们决定 DSL 需求。仅有“提示词 + 预期文本”的扁平列表是不够的。 ## 方向 ### 单一事实来源 -使用 `qa/scenarios/index.md` 和 `qa/scenarios//*.md` 作为编写时的单一事实来源。 +使用 `qa/scenarios/index.md` 和 `qa/scenarios//*.md` 作为编写层面的事实来源。 -这个包应保持： +该场景包应保持： -- 在评审中人类可读 -- 机器可解析 -- 足够丰富，能够驱动： +- 便于人工评审阅读 +- 可供机器解析 +- 足够丰富，以驱动： - suite 执行 - - QA 工作区引导 + - QA 工作区 bootstrap - QA Lab UI 元数据 - - 文档/发现提示词 + - docs/discovery 提示词 - 报告生成 ### 首选编写格式 @@ -160,15 +160,15 @@ x-i18n: - assertions - cleanup -这样可以获得： +这样可以带来： -- 比大型 JSON 更好的 PR 可读性 -- 比纯 YAML 更丰富的上下文 +- 比庞大的 JSON 更适合在 PR 中阅读 +- 比纯 YAML 具有更丰富的上下文 - 严格解析和 zod 校验 -原始 JSON 只应作为中间生成形式被接受。 +仅在作为中间生成形式时，才接受原始 JSON。 -## 建议的场景文件结构 +## 提议的场景文件结构 示例： @@ -179,7 +179,7 @@ title: Image generation roundtrip surface: image tags: [media, image, roundtrip] models: - primary: openai/gpt-5.4 + primary: openai/gpt-5.5 requires: tools: [image_generate] plugins: [openai, qa-channel] @@ -193,7 +193,7 @@ codeRefs: # Objective -验证生成的媒体会在后续轮次中重新附加。 +Verify generated media is reattached on the follow-up turn. # Setup @@ -214,7 +214,7 @@ codeRefs: - action: agent.send session: agent:qa:image-roundtrip message: | - 图像生成检查：生成一张 QA 灯塔图像，并用一句简短的话总结它。 + Image generation check: generate a QA lighthouse image and summarize it in one short sentence. - action: artifact.capture kind: generated-image promptSnippet: Image generation check @@ -222,7 +222,7 @@ codeRefs: - action: agent.send session: agent:qa:image-roundtrip message: | - 图像往返检查：用一句简短的话描述生成的灯塔附件。 + Roundtrip image inspection check: describe the generated lighthouse attachment in one short sentence. attachments: - fromArtifact: lighthouseImage ``` @@ -241,11 +241,11 @@ codeRefs: ``` ```` -## DSL 必须覆盖的 Runner 能力 +## DSL 必须覆盖的运行器能力 -根据当前 suite，通用 runner 需要的不仅仅是执行提示词。 +根据当前 suite，通用运行器需要的不只是提示词执行。 -### 环境与设置操作 +### 环境与 setup 动作 - `bus.reset` - `gateway.waitHealthy` @@ -254,14 +254,14 @@ codeRefs: - `thread.create` - `workspace.writeSkill` -### 智能体轮次操作 +### 智能体轮次动作 - `agent.send` - `agent.wait` - `bus.injectInbound` - `bus.injectOutbound` -### 配置与运行时操作 +### 配置与运行时动作 - `config.get` - `config.patch` @@ -270,7 +270,7 @@ codeRefs: - `tools.effective` - `skills.status` -### 文件与产物操作 +### 文件与产物动作 - `file.write` - `file.read` @@ -279,7 +279,7 @@ codeRefs: - `artifact.captureGeneratedImage` - `artifact.capturePath` -### Memory 与 cron 操作 +### 内存与 cron 动作 - `memory.indexForce` - `memory.searchCli` @@ -289,7 +289,7 @@ codeRefs: - `cron.waitCompletion` - `sessionTranscript.write` -### MCP 操作 +### MCP 动作 - `mcp.callTool` @@ -311,43 +311,43 @@ codeRefs: ## 变量与产物引用 -DSL 必须支持保存输出并在后续引用。 +DSL 必须支持保存输出以及后续引用。 来自当前 suite 的示例： - 创建线程，然后复用 `threadId` - 创建会话，然后复用 `sessionKey` -- 生成图像，然后在下一轮附加该文件 -- 生成一个唤醒标记字符串，然后断言它稍后出现 +- 生成图像，然后在下一轮中附加该文件 +- 生成一个唤醒标记字符串，然后断言它稍后会出现 所需能力： - `saveAs` - `${vars.name}` - `${artifacts.name}` -- 路径、会话键、线程 ID、标记、工具输出的类型化引用 +- 针对路径、会话键、线程 id、标记、工具输出的类型化引用 -如果没有变量支持，测试框架逻辑仍会不断从 DSL 泄漏回 TypeScript。 +如果没有变量支持，Harness 将继续把场景逻辑泄漏回 TypeScript 中。 ## 哪些内容应保留为逃生口 -在第一阶段，实现一个完全纯声明式的 runner 并不现实。 +在第 1 阶段，实现一个完全纯粹的声明式运行器并不现实。 -有些场景天生就更偏编排： +有些场景天然就需要大量编排： -- 记忆 Dreaming 扫描 -- 配置应用后重启唤醒 -- 配置重启能力切换 -- 基于时间戳/路径解析生成图像产物 +- memory dreaming sweep +- config apply 重启唤醒 +- config restart 能力切换 +- 按时间戳/路径解析生成图像产物 - discovery-report 评估 -目前这些应继续使用显式自定义 handler。 +这些场景目前应继续使用显式自定义处理器。 推荐规则： - 85–90% 声明式 -- 对于剩余复杂部分，使用显式 `customHandler` 步骤 -- 仅允许已命名并有文档的自定义 handler +- 对于剩余的困难部分，使用显式 `customHandler` 步骤 +- 只允许具名且有文档的自定义处理器 - 场景文件中不允许匿名内联代码 这样既能保持通用引擎整洁，又能继续推进。 @@ -356,19 +356,19 @@ DSL 必须支持保存输出并在后续引用。 ### 当前 -场景 Markdown 现在已是以下内容的事实来源： +场景 Markdown 已经是以下内容的事实来源： - suite 执行 -- 工作区引导文件 +- 工作区 bootstrap 文件 - QA Lab UI 场景目录 - 报告元数据 -- 发现提示词 +- discovery 提示词 -已生成的兼容性内容： +生成的兼容层： -- 种子工作区仍包含 `QA_KICKOFF_TASK.md` -- 种子工作区仍包含 `QA_SCENARIO_PLAN.md` -- 种子工作区现在还包含 `QA_SCENARIOS.md` +- 已植入的工作区仍然包含 `QA_KICKOFF_TASK.md` +- 已植入的工作区仍然包含 `QA_SCENARIO_PLAN.md` +- 已植入的工作区现在还包含 `QA_SCENARIOS.md` ## 重构计划 @@ -378,10 +378,10 @@ DSL 必须支持保存输出并在后续引用。 - 添加了 `qa/scenarios/index.md` - 将场景拆分到 `qa/scenarios//*.md` -- 添加了命名 Markdown YAML 包内容解析器 +- 为具名 Markdown YAML 包内容添加了解析器 - 使用 zod 进行校验 -- 将消费者切换到解析后的包 -- 移除了仓库级的 `qa/seed-scenarios.json` 和 `qa/QA_KICKOFF_TASK.md` +- 将消费者切换到解析后的场景包 +- 删除了仓库级 `qa/seed-scenarios.json` 和 `qa/QA_KICKOFF_TASK.md` ### 第 2 阶段：通用引擎 @@ -395,13 +395,13 @@ DSL 必须支持保存输出并在后续引用。 交付物： -- 引擎可执行简单的声明式场景 +- 引擎能够执行简单的声明式场景 -从主要是“提示词 + 等待 + 断言”的场景开始： +从那些大多由“提示词 + 等待 + 断言”构成的场景开始： -- 线程跟进 -- 从附件理解图像 -- skill 可见性与调用 +- 线程后续跟进 +- 基于附件的图像理解 +- 技能可见性与调用 - 渠道基线 交付物： @@ -411,35 +411,35 @@ DSL 必须支持保存输出并在后续引用。 ### 第 4 阶段：迁移中等复杂度场景 - 图像生成往返 -- 渠道上下文中的记忆工具 -- 会话记忆排序 -- 子智能体移交 -- 子智能体扇出综合 +- 渠道上下文中的内存工具 +- 会话内存排序 +- subagent 切换交接 +- subagent 扇出综合 交付物： -- 变量、产物、工具断言、request-log 断言得到验证 +- 变量、产物、工具断言、请求日志断言都得到验证 -### 第 5 阶段：将复杂场景保留在自定义 handler 中 +### 第 5 阶段：将困难场景保留在自定义处理器中 -- 记忆 Dreaming 扫描 -- 配置应用后重启唤醒 -- 配置重启能力切换 +- memory dreaming sweep +- config apply 重启唤醒 +- config restart 能力切换 - 运行时清单漂移 交付物： -- 保持相同的编写格式，但在需要时使用显式自定义步骤块 +- 仍使用同一种编写格式，但在需要时使用显式自定义步骤块 ### 第 6 阶段：删除硬编码场景映射 -当包覆盖率足够高后： +当场景包覆盖率足够高后： -- 删除 `extensions/qa-lab/src/suite.ts` 中大部分特定场景的 TypeScript 分支逻辑 +- 删除 `extensions/qa-lab/src/suite.ts` 中大部分场景专用 TypeScript 分支 -## Fake Slack / 富媒体支持 +## 假 Slack / 富媒体支持 -当前的 QA bus 以文本为主。 +当前 QA bus 以文本为主。 相关文件： @@ -449,17 +449,17 @@ DSL 必须支持保存输出并在后续引用。 - `extensions/qa-lab/src/bus-server.ts` - `extensions/qa-lab/web/src/ui-render.ts` -当前 QA bus 支持： +目前 QA bus 支持： - 文本 -- 反应 +- reactions - 线程 它尚未对内联媒体附件建模。 -### 所需传输契约 +### 所需的传输契约 -添加一个通用 QA bus 附件模型： +添加一个通用的 QA bus 附件模型： ```ts type QaBusAttachment = { @@ -478,67 +478,67 @@ type QaBusAttachment = { }; ``` -然后将 `attachments?: QaBusAttachment[]` 添加到： +然后为以下类型添加 `attachments?: QaBusAttachment[]`： - `QaBusMessage` - `QaBusInboundMessageInput` - `QaBusOutboundMessageInput` -### 为什么先做通用模型 +### 为什么要先做通用层 -不要构建仅限 Slack 的媒体模型。 +不要构建 Slack 专用的媒体模型。 -而应采用： +应当改为： -- 一个通用 QA 传输模型 -- 其上支持多个渲染器 - - 当前的 QA Lab 聊天 - - 未来的 fake Slack web - - 其他任何 fake transport 视图 +- 一个通用的 QA 传输模型 +- 其上构建多个渲染器 + - 当前 QA Lab 聊天界面 + - 未来的假 Slack 网页界面 + - 其他任何假传输视图 -这样可以避免重复逻辑，并让媒体场景保持与传输方式无关。 +这样可以避免重复逻辑，并让媒体场景保持与传输层无关。 -### 所需 UI 工作 +### 需要的 UI 工作 更新 QA UI，以渲染： -- 内联图片预览 +- 内联图像预览 - 内联音频播放器 - 内联视频播放器 - 文件附件 chip -当前 UI 已能渲染线程和反应，因此附件渲染应能叠加到相同的消息卡片模型上。 +当前 UI 已经可以渲染线程和 reactions，因此附件渲染应能叠加到同一套消息卡片模型上。 -### 媒体传输将启用的场景工作 +### 媒体传输启用后的场景工作 -一旦附件可以通过 QA bus 流动，我们就能添加更丰富的 fake-chat 场景： +一旦附件能够通过 QA bus 流转，我们就可以添加更丰富的假聊天场景： -- fake Slack 中的内联图片回复 +- 假 Slack 中的内联图像回复 - 音频附件理解 - 视频附件理解 - 混合附件顺序 -- 保留媒体的线程回复 +- 在线程回复中保留媒体 ## 建议 -下一块实现应当是： +下一块实现工作应当是： 1. 添加 Markdown 场景加载器 + zod schema 2. 从 Markdown 生成当前目录 3. 先迁移几个简单场景 4. 添加通用 QA bus 附件支持 -5. 在 QA UI 中渲染内联图片 +5. 在 QA UI 中渲染内联图像 6. 然后扩展到音频和视频 -这是能同时验证两个目标的最小路径： +这是能够同时证明以下两个目标的最小路径： -- 通用、由 Markdown 定义的 QA -- 更丰富的 fake messaging 表面 +- 通用的、由 Markdown 定义的 QA +- 更丰富的假消息界面 -## 未决问题 +## 未解决问题 - 场景文件是否应允许嵌入带变量插值的 Markdown 提示词模板 -- 设置/清理应作为命名区段存在，还是仅作为有序操作列表 -- 产物引用在 schema 中应为强类型，还是基于字符串 -- 自定义 handler 应放在一个统一注册表中，还是按 surface 分注册表 -- 在迁移期间，生成的 JSON 兼容文件是否应继续保留为已检入状态 +- setup/cleanup 是否应为具名分节，还是仅作为有序动作列表 +- 产物引用在 schema 中是否应采用强类型，还是基于字符串 +- 自定义处理器应放在单一注册表中，还是按 surface 分注册表 +- 迁移期间生成的 JSON 兼容文件是否应继续保留在版本控制中 diff --git a/docs/zh-CN/reference/wizard.md b/docs/zh-CN/reference/wizard.md index 64012ec60..1abc4085e 100644 --- a/docs/zh-CN/reference/wizard.md +++ b/docs/zh-CN/reference/wizard.md @@ -1,16 +1,16 @@ --- read_when: - 查找特定的新手引导步骤或标志 - - 使用非交互模式自动化新手引导 + - 使用非交互模式自动执行新手引导 - 调试新手引导行为 sidebarTitle: Onboarding Reference -summary: CLI 新手引导的完整参考：每个步骤、标志和配置字段 +summary: CLI 新手引导完整参考：每个步骤、标志和配置字段 title: 新手引导参考 x-i18n: - generated_at: "2026-04-23T02:36:29Z" + generated_at: "2026-04-23T19:26:48Z" model: gpt-5.4 provider: openai - source_hash: 51405f5d9ba3d9553662fd0a03254a709d5eb4b27339c5edfe1da1111629d0dd + source_hash: 136fd90adfaaa9f0481168642e5efadb4f9ee67def0ac1bb40433d178f791474 source_path: reference/wizard.md workflow: 15 --- @@ -18,63 +18,63 @@ x-i18n: # 新手引导参考 这是 `openclaw onboard` 的完整参考。 -如需高层概览，请参阅 [设置向导（CLI）](/zh-CN/start/wizard)。 +如需高层概览，请参见 [设置向导（CLI）](/zh-CN/start/wizard)。 -## 流程详情（本地模式） +## 流程细节（本地模式） - - - 如果 `~/.openclaw/openclaw.json` 存在，选择 **保留 / 修改 / 重置**。 - - 重新运行新手引导**不会**清除任何内容，除非你明确选择 **重置** + + - 如果 `~/.openclaw/openclaw.json` 已存在，可选择 **保留 / 修改 / 重置**。 + - 重新运行新手引导**不会**清除任何内容，除非你显式选择 **重置** （或传入 `--reset`）。 - CLI `--reset` 默认作用于 `config+creds+sessions`；使用 `--reset-scope full` - 可额外删除工作区。 - - 如果配置无效或包含旧版键名，向导会停止，并要求 - 你在继续之前运行 `openclaw doctor`。 + 可额外移除工作区。 + - 如果配置无效或包含旧版键，向导会停止，并要求 + 你先运行 `openclaw doctor` 再继续。 - 重置使用 `trash`（绝不使用 `rm`），并提供以下范围： - 仅配置 - 配置 + 凭证 + 会话 - - 完全重置（也会删除工作区） + - 完整重置（同时移除工作区） - - - **Anthropic API 密钥**：如果存在则使用 `ANTHROPIC_API_KEY`，否则提示你输入密钥，然后保存以供守护进程使用。 - - **Anthropic API 密钥**：在新手引导/配置中是 Anthropic 助手的首选项。 - - **Anthropic setup-token**：在新手引导/配置中仍然可用，不过 OpenClaw 现在在可用时更倾向于复用 Claude CLI。 - - **OpenAI Code（Codex）订阅（OAuth）**：浏览器流程；粘贴 `code#state`。 - - 当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.4`。 - - **OpenAI Code（Codex）订阅（设备配对）**：使用短时效设备代码的浏览器配对流程。 - - 当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.4`。 - - **OpenAI API 密钥**：如果存在则使用 `OPENAI_API_KEY`，否则提示你输入密钥，然后将其存储到凭证配置文件中。 - - 当模型未设置、为 `openai/*` 或 `openai-codex/*` 时，将 `agents.defaults.model` 设置为 `openai/gpt-5.4`。 - - **xAI（Grok）API 密钥**：提示输入 `XAI_API_KEY`，并将 xAI 配置为模型提供商。 - - **OpenCode**：提示输入 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`，可在 https://opencode.ai/auth 获取），并允许你选择 Zen 或 Go 目录。 - - **Ollama**：首先提供 **Cloud + Local**、**仅 Cloud** 或 **仅 Local**。`仅 Cloud` 会提示输入 `OLLAMA_API_KEY` 并使用 `https://ollama.com`；依赖主机的模式会提示输入 Ollama 基础 URL、发现可用模型，并在需要时自动拉取所选本地模型；`Cloud + Local` 还会检查该 Ollama 主机是否已登录以使用云访问。 - - 更多详情：[Ollama](/zh-CN/providers/ollama) - - **API 密钥**：会为你存储该密钥。 - - **Vercel AI Gateway（多模型代理）**：提示输入 `AI_GATEWAY_API_KEY`。 - - 更多详情：[Vercel AI Gateway](/zh-CN/providers/vercel-ai-gateway) + + - **Anthropic API key**：如果存在则使用 `ANTHROPIC_API_KEY`，否则提示输入 key，然后保存以供守护进程使用。 + - **Anthropic API key**：在新手引导/配置中是首选的 Anthropic assistant 选择。 + - **Anthropic setup-token**：在新手引导/配置中仍可用，不过 OpenClaw 现在在可用时更倾向于复用 Claude CLI。 + - **OpenAI Code (Codex) subscription (OAuth)**：浏览器流程；粘贴 `code#state`。 + - 当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设为 `openai-codex/gpt-5.5`。 + - **OpenAI Code (Codex) subscription (device pairing)**：使用短时有效设备码的浏览器配对流程。 + - 当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设为 `openai-codex/gpt-5.5`。 + - **OpenAI API key**：如果存在则使用 `OPENAI_API_KEY`，否则提示输入 key，然后将其存入 auth profiles。 + - 当模型未设置、为 `openai/*`，或为 `openai-codex/*` 时，将 `agents.defaults.model` 设为 `openai/gpt-5.5`。 + - **xAI (Grok) API key**：提示输入 `XAI_API_KEY`，并将 xAI 配置为模型 provider。 + - **OpenCode**：提示输入 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`，可在 https://opencode.ai/auth 获取），并让你选择 Zen 或 Go 目录。 + - **Ollama**：首先提供 **Cloud + Local**、**仅 Cloud** 或 **仅 Local**。`仅 Cloud` 会提示输入 `OLLAMA_API_KEY` 并使用 `https://ollama.com`；基于主机的模式会提示输入 Ollama 基础 URL、发现可用模型，并在需要时自动拉取所选本地模型；`Cloud + Local` 还会检查该 Ollama 主机是否已登录并可访问云服务。 + - 更多细节： [Ollama](/zh-CN/providers/ollama) + - **API key**：会为你存储该 key。 + - **Vercel AI Gateway (multi-model proxy)**：提示输入 `AI_GATEWAY_API_KEY`。 + - 更多细节： [Vercel AI Gateway](/zh-CN/providers/vercel-ai-gateway) - **Cloudflare AI Gateway**：提示输入 Account ID、Gateway ID 和 `CLOUDFLARE_AI_GATEWAY_API_KEY`。 - - 更多详情：[Cloudflare AI Gateway](/zh-CN/providers/cloudflare-ai-gateway) + - 更多细节： [Cloudflare AI Gateway](/zh-CN/providers/cloudflare-ai-gateway) - **MiniMax**：会自动写入配置；托管默认值是 `MiniMax-M2.7`。 - API 密钥设置使用 `minimax/...`，OAuth 设置使用 + API key 设置使用 `minimax/...`，而 OAuth 设置使用 `minimax-portal/...`。 - - 更多详情：[MiniMax](/zh-CN/providers/minimax) - - **StepFun**：会为中国或全球端点上的 StepFun standard 或 Step Plan 自动写入配置。 - - Standard 当前包含 `step-3.5-flash`，Step Plan 还包含 `step-3.5-flash-2603`。 - - 更多详情：[StepFun](/zh-CN/providers/stepfun) - - **Synthetic（兼容 Anthropic）**：提示输入 `SYNTHETIC_API_KEY`。 - - 更多详情：[Synthetic](/zh-CN/providers/synthetic) - - **Moonshot（Kimi K2）**：会自动写入配置。 + - 更多细节： [MiniMax](/zh-CN/providers/minimax) + - **StepFun**：会自动为中国区或全球端点上的 StepFun standard 或 Step Plan 写入配置。 + - Standard 当前包含 `step-3.5-flash`，Step Plan 也包含 `step-3.5-flash-2603`。 + - 更多细节： [StepFun](/zh-CN/providers/stepfun) + - **Synthetic (Anthropic-compatible)**：提示输入 `SYNTHETIC_API_KEY`。 + - 更多细节： [Synthetic](/zh-CN/providers/synthetic) + - **Moonshot (Kimi K2)**：会自动写入配置。 - **Kimi Coding**：会自动写入配置。 - - 更多详情：[Moonshot AI（Kimi + Kimi Coding）](/zh-CN/providers/moonshot) - - **跳过**：暂不配置凭证。 - - 从检测到的选项中选择一个默认模型（或手动输入 provider/model）。为获得最佳质量并降低提示注入风险，请选择你的提供商栈中可用的最新一代最强模型。 - - 新手引导会执行模型检查；如果配置的模型未知或缺少凭证，会发出警告。 - - API 密钥存储模式默认使用明文 auth-profile 值。使用 `--secret-input-mode ref` 可改为存储基于环境变量的引用（例如 `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`）。 - - 凭证配置文件位于 `~/.openclaw/agents//agent/auth-profiles.json`（API 密钥 + OAuth）。`~/.openclaw/credentials/oauth.json` 仅用于导入旧版数据。 - - 更多详情：[/concepts/oauth](/zh-CN/concepts/oauth) + - 更多细节： [Moonshot AI (Kimi + Kimi Coding)](/zh-CN/providers/moonshot) + - **跳过**：暂不配置认证。 + - 从检测到的选项中选择默认模型（或手动输入 provider/model）。为了获得最佳质量并降低 prompt injection 风险，请选择你的 provider 栈中可用的最新一代最强模型。 + - 新手引导会运行模型检查，并在配置的模型未知或缺少认证时发出警告。 + - API key 存储模式默认使用明文 auth-profile 值。使用 `--secret-input-mode ref` 可改为存储基于环境变量的引用（例如 `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`）。 + - Auth profiles 位于 `~/.openclaw/agents//agent/auth-profiles.json`（API key + OAuth）。`~/.openclaw/credentials/oauth.json` 仅用于导入旧版数据。 + - 更多细节： [/concepts/oauth](/zh-CN/concepts/oauth) - 无头/服务器提示：先在有浏览器的机器上完成 OAuth，然后复制 + 无头/服务器提示：可先在有浏览器的机器上完成 OAuth，然后复制 该智能体的 `auth-profiles.json`（例如 `~/.openclaw/agents//agent/auth-profiles.json`，或对应的 `$OPENCLAW_STATE_DIR/...` 路径）到 Gateway 网关主机。`credentials/oauth.json` @@ -82,64 +82,64 @@ x-i18n: - - 默认为 `~/.openclaw/workspace`（可配置）。 - - 会初始化智能体引导仪式所需的工作区文件。 - - 完整工作区布局和备份指南：[智能体工作区](/zh-CN/concepts/agent-workspace) + - 默认是 `~/.openclaw/workspace`（可配置）。 + - 会预填智能体 bootstrap 仪式所需的工作区文件。 + - 完整工作区布局 + 备份指南： [智能体工作区](/zh-CN/concepts/agent-workspace) - 端口、绑定、认证模式、Tailscale 暴露。 - - 认证建议：即使是 loopback，也保留 **Token**，这样本地 WS 客户端也必须进行认证。 + - 认证建议：即使是 loopback，也请保持 **Token**，这样本地 WS 客户端仍必须进行认证。 - 在 token 模式下，交互式设置提供： - **生成/存储明文 token**（默认） - **使用 SecretRef**（可选启用） - - 快速开始会在新手引导探测/仪表板引导中，复用 `env`、`file` 和 `exec` 提供商上现有的 `gateway.auth.token` SecretRef。 - - 如果该 SecretRef 已配置但无法解析，新手引导会尽早失败，并给出清晰的修复信息，而不是静默降级运行时认证。 - - 在 password 模式下，交互式设置同样支持明文或 SecretRef 存储。 - - 非交互式 token SecretRef 路径：`--gateway-token-ref-env `。 - - 要求在新手引导进程环境中存在非空环境变量。 + - 快速开始会跨 `env`、`file` 和 `exec` provider 复用现有的 `gateway.auth.token` SecretRef，用于新手引导探测/控制面板 bootstrap。 + - 如果该 SecretRef 已配置但无法解析，新手引导会尽早失败，并给出明确修复信息，而不是静默降级运行时认证。 + - 在 password 模式下，交互式设置也支持明文或 SecretRef 存储。 + - 非交互 token SecretRef 路径：`--gateway-token-ref-env `。 + - 要求新手引导进程环境中存在且非空的环境变量。 - 不能与 `--gateway-token` 同时使用。 - - 只有在你完全信任每个本地进程时才禁用认证。 + - 仅当你完全信任每一个本地进程时，才禁用认证。 - 非 loopback 绑定仍然要求认证。 - - [WhatsApp](/zh-CN/channels/whatsapp)：可选二维码登录。 - - [Telegram](/zh-CN/channels/telegram)：机器人 token。 - - [Discord](/zh-CN/channels/discord)：机器人 token。 - - [Google Chat](/zh-CN/channels/googlechat)：服务账号 JSON + webhook audience。 - - [Mattermost](/zh-CN/channels/mattermost)（插件）：机器人 token + 基础 URL。 - - [Signal](/zh-CN/channels/signal)：可选安装 `signal-cli` + 账号配置。 - - [BlueBubbles](/zh-CN/channels/bluebubbles)：**推荐用于 iMessage**；服务器 URL + 密码 + webhook。 + - [WhatsApp](/zh-CN/channels/whatsapp)：可选 QR 登录。 + - [Telegram](/zh-CN/channels/telegram)：bot token。 + - [Discord](/zh-CN/channels/discord)：bot token。 + - [Google Chat](/zh-CN/channels/googlechat)：服务账户 JSON + webhook audience。 + - [Mattermost](/zh-CN/channels/mattermost)（plugin）：bot token + 基础 URL。 + - [Signal](/zh-CN/channels/signal)：可选安装 `signal-cli` + 账户配置。 + - [BlueBubbles](/zh-CN/channels/bluebubbles)：**iMessage 的推荐方案**；服务器 URL + password + webhook。 - [iMessage](/zh-CN/channels/imessage)：旧版 `imsg` CLI 路径 + DB 访问。 - - 私信安全：默认启用配对。首次私信会发送验证码；通过 `openclaw pairing approve ` 批准，或使用允许列表。 + - 私信安全：默认是配对。第一条私信会发送一个代码；通过 `openclaw pairing approve ` 批准，或使用 allowlist。 - - 选择一个受支持的提供商，例如 Brave、DuckDuckGo、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Ollama Web 搜索、Perplexity、SearXNG 或 Tavily（或跳过）。 - - 基于 API 的提供商可使用环境变量或现有配置进行快速设置；无密钥提供商则使用其特定前置条件。 + - 选择一个受支持的 provider，例如 Brave、DuckDuckGo、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Ollama Web 搜索、Perplexity、SearXNG 或 Tavily（或跳过）。 + - 基于 API 的 provider 可使用环境变量或现有配置进行快速设置；无 key 的 provider 则使用其各自的前置条件。 - 使用 `--skip-search` 跳过。 - 稍后配置：`openclaw configure --section web`。 - + - macOS：LaunchAgent - - 需要已登录的用户会话；对于无头环境，请使用自定义 LaunchDaemon（未随附）。 + - 需要已登录的用户会话；对于无头场景，请使用自定义 LaunchDaemon（未内置提供）。 - Linux（以及通过 WSL2 的 Windows）：systemd 用户单元 - - 新手引导会尝试通过 `loginctl enable-linger ` 启用 lingering，这样 Gateway 网关会在注销后继续运行。 - - 可能会提示输入 sudo（会写入 `/var/lib/systemd/linger`）；它会先尝试不使用 sudo。 - - **运行时选择：** Node（推荐；WhatsApp/Telegram 必需）。Bun **不推荐**。 - - 如果 token 认证需要 token，且 `gateway.auth.token` 由 SecretRef 管理，守护进程安装会验证它，但不会将解析后的明文 token 值持久化到监督服务环境元数据中。 - - 如果 token 认证需要 token，而已配置的 token SecretRef 未解析，守护进程安装会被阻止，并提供可执行的指导。 - - 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，但未设置 `gateway.auth.mode`，守护进程安装会被阻止，直到显式设置模式。 + - 新手引导会尝试启用 lingering：`loginctl enable-linger `，以便 Gateway 网关在登出后继续运行。 + - 可能会提示使用 sudo（写入 `/var/lib/systemd/linger`）；会先尝试不使用 sudo。 + - **运行时选择：** Node（推荐；WhatsApp/Telegram 必需）。**不推荐** Bun。 + - 如果 token 认证需要 token，且 `gateway.auth.token` 由 SecretRef 管理，守护进程安装会验证它，但不会将解析出的明文 token 值持久化到 supervisor 服务环境元数据中。 + - 如果 token 认证需要 token，且配置的 token SecretRef 无法解析，守护进程安装会被阻止，并给出可执行的指导。 + - 如果 `gateway.auth.token` 和 `gateway.auth.password` 都已配置，而 `gateway.auth.mode` 未设置，守护进程安装会被阻止，直到显式设置 mode。 - - 启动 Gateway 网关（如有需要）并运行 `openclaw health`。 - - 提示：`openclaw status --deep` 会将实时 Gateway 网关健康探测添加到状态输出中，包括在支持时的渠道探测（需要 Gateway 网关可访问）。 + - 启动 Gateway 网关（如有需要），并运行 `openclaw health`。 + - 提示：`openclaw status --deep` 会在状态输出中加入实时 Gateway 网关健康探测，包括支持时的渠道探测（要求 Gateway 网关可达）。 - - 读取可用的 Skills 并检查要求。 - - 让你选择一个节点管理器：**npm / pnpm**（bun 不推荐）。 - - 安装可选依赖项（其中一些在 macOS 上使用 Homebrew）。 + - 读取可用 Skills 并检查要求。 + - 让你选择一个节点管理器：**npm / pnpm**（不推荐 bun）。 + - 安装可选依赖（有些在 macOS 上使用 Homebrew）。 - - 摘要 + 后续步骤，包括提供更多功能的 iOS/Android/macOS 应用。 + - 摘要 + 后续步骤，包括 iOS/Android/macOS 应用以获得更多功能。 @@ -150,7 +150,7 @@ x-i18n: ## 非交互模式 -使用 `--non-interactive` 来自动化或编写新手引导脚本： +使用 `--non-interactive` 可自动化或脚本化新手引导： ```bash openclaw onboard --non-interactive \ @@ -166,7 +166,7 @@ openclaw onboard --non-interactive \ 添加 `--json` 可获得机器可读摘要。 -在非交互模式下使用 Gateway 网关 token SecretRef： +非交互模式中的 Gateway 网关 token SecretRef： ```bash export OPENCLAW_GATEWAY_TOKEN="your-token" @@ -177,13 +177,13 @@ openclaw onboard --non-interactive \ --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN ``` -`--gateway-token` 与 `--gateway-token-ref-env` 互斥。 +`--gateway-token` 和 `--gateway-token-ref-env` 互斥。 -`--json` **不**意味着非交互模式。脚本中请使用 `--non-interactive`（以及 `--workspace`）。 +`--json` **不**意味着非交互模式。对于脚本，请使用 `--non-interactive`（以及 `--workspace`）。 -各提供商的命令示例见 [CLI 自动化](/zh-CN/start/wizard-cli-automation#provider-specific-examples)。 +provider 专用命令示例位于 [CLI 自动化](/zh-CN/start/wizard-cli-automation#provider-specific-examples)。 本参考页用于说明标志语义和步骤顺序。 ### 添加智能体（非交互） @@ -191,22 +191,22 @@ openclaw onboard --non-interactive \ ```bash openclaw agents add work \ --workspace ~/.openclaw/workspace-work \ - --model openai/gpt-5.4 \ + --model openai/gpt-5.5 \ --bind whatsapp:biz \ --non-interactive \ --json ``` -## Gateway 网关向导 RPC +## Gateway 向导 RPC Gateway 网关通过 RPC 暴露新手引导流程（`wizard.start`、`wizard.next`、`wizard.cancel`、`wizard.status`）。 -客户端（macOS 应用、Control UI）可以渲染各步骤，而无需重新实现新手引导逻辑。 +客户端（macOS 应用、Control UI）可以渲染这些步骤，而无需重新实现新手引导逻辑。 ## Signal 设置（signal-cli） 新手引导可以从 GitHub Releases 安装 `signal-cli`： -- 下载相应的发布资源。 +- 下载适当的发布资源。 - 将其存储到 `~/.openclaw/tools/signal-cli//` 下。 - 将 `channels.signal.cliPath` 写入你的配置。 @@ -214,19 +214,19 @@ Gateway 网关通过 RPC 暴露新手引导流程（`wizard.start`、`wizard.nex - JVM 构建需要 **Java 21**。 - 在可用时会使用原生构建。 -- Windows 使用 WSL2；`signal-cli` 安装会在 WSL 内按 Linux 流程执行。 +- Windows 使用 WSL2；`signal-cli` 安装会在 WSL 内遵循 Linux 流程。 -## 向导会写入什么 +## 向导会写入什么内容 `~/.openclaw/openclaw.json` 中的典型字段： - `agents.defaults.workspace` - `agents.defaults.model` / `models.providers`（如果选择了 MiniMax） -- `tools.profile`（本地新手引导在未设置时默认使用 `"coding"`；现有的显式值会被保留） -- `gateway.*`（模式、绑定、认证、Tailscale） -- `session.dmScope`（行为详情：[CLI 设置参考](/zh-CN/start/wizard-cli-reference#outputs-and-internals)） +- `tools.profile`（本地新手引导在未设置时默认使用 `"coding"`；现有显式值会被保留） +- `gateway.*`（mode、bind、auth、tailscale） +- `session.dmScope`（行为细节： [CLI 设置参考](/zh-CN/start/wizard-cli-reference#outputs-and-internals)） - `channels.telegram.botToken`、`channels.discord.token`、`channels.matrix.*`、`channels.signal.*`、`channels.imessage.*` -- 如果你在提示中选择启用，还会写入渠道允许列表（Slack/Discord/Matrix/Microsoft Teams）；在可能的情况下，名称会解析为 ID。 +- 当你在提示中选择启用时，写入渠道 allowlist（Slack/Discord/Matrix/Microsoft Teams）（如果可能，名称会解析为 ID）。 - `skills.install.nodeManager` - `setup --node-manager` 接受 `npm`、`pnpm` 或 `bun`。 - 手动配置仍可通过直接设置 `skills.install.nodeManager` 来使用 `yarn`。 @@ -238,16 +238,16 @@ Gateway 网关通过 RPC 暴露新手引导流程（`wizard.start`、`wizard.nex `openclaw agents add` 会写入 `agents.list[]` 和可选的 `bindings`。 -WhatsApp 凭证存储在 `~/.openclaw/credentials/whatsapp//` 下。 +WhatsApp 凭证位于 `~/.openclaw/credentials/whatsapp//` 下。 会话存储在 `~/.openclaw/agents//sessions/` 下。 -某些渠道以插件形式提供。当你在设置期间选择其中之一时，新手引导 -会先提示安装它（npm 或本地路径），然后才能进行配置。 +有些渠道以 plugin 形式提供。当你在设置期间选择其中一个时，新手引导 +会先提示安装它（npm 或本地路径），然后才能继续配置。 ## 相关文档 -- 新手引导概览：[设置向导（CLI）](/zh-CN/start/wizard) -- macOS 应用新手引导：[新手引导](/zh-CN/start/onboarding) -- 配置参考：[Gateway 网关配置](/zh-CN/gateway/configuration) -- 提供商：[WhatsApp](/zh-CN/channels/whatsapp)、[Telegram](/zh-CN/channels/telegram)、[Discord](/zh-CN/channels/discord)、[Google Chat](/zh-CN/channels/googlechat)、[Signal](/zh-CN/channels/signal)、[BlueBubbles](/zh-CN/channels/bluebubbles)（iMessage）、[iMessage](/zh-CN/channels/imessage)（旧版） -- Skills：[Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) +- 新手引导概览： [设置向导（CLI）](/zh-CN/start/wizard) +- macOS 应用新手引导： [新手引导](/zh-CN/start/onboarding) +- 配置参考： [Gateway 网关配置](/zh-CN/gateway/configuration) +- Providers： [WhatsApp](/zh-CN/channels/whatsapp)、[Telegram](/zh-CN/channels/telegram)、[Discord](/zh-CN/channels/discord)、[Google Chat](/zh-CN/channels/googlechat)、[Signal](/zh-CN/channels/signal)、[BlueBubbles](/zh-CN/channels/bluebubbles)（iMessage）、[iMessage](/zh-CN/channels/imessage)（旧版） +- Skills： [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) diff --git a/docs/zh-CN/start/wizard-cli-automation.md b/docs/zh-CN/start/wizard-cli-automation.md index 68d25e093..cd1ffff81 100644 --- a/docs/zh-CN/start/wizard-cli-automation.md +++ b/docs/zh-CN/start/wizard-cli-automation.md @@ -1,25 +1,25 @@ --- read_when: - - 你正在脚本或 CI 中自动化新手引导 - - 你需要针对特定提供商的非交互式示例 + - 你正在脚本或 CI 中自动执行新手引导 + - 你需要特定提供商的非交互式示例 sidebarTitle: CLI automation -summary: 用于 OpenClaw CLI 的脚本化新手引导和智能体设置 +summary: OpenClaw CLI 的脚本化新手引导与智能体设置 title: CLI 自动化 x-i18n: - generated_at: "2026-04-06T15:31:32Z" + generated_at: "2026-04-23T19:26:48Z" model: gpt-5.4 provider: openai - source_hash: bca2dd6e482a16b27284fc76319e936e8df0ff5558134827c19f6875436cc652 + source_hash: 755be6e44f88154fbd647278bc9122886a0b08bfcf72213c194f58ee57575551 source_path: start/wizard-cli-automation.md workflow: 15 --- # CLI 自动化 -使用 `--non-interactive` 来自动化 `openclaw onboard`。 +使用 `--non-interactive` 可自动执行 `openclaw onboard`。 -`--json` 并不意味着非交互模式。对于脚本，请使用 `--non-interactive`（以及 `--workspace`）。 +`--json` 不意味着非交互模式。对于脚本，请使用 `--non-interactive`（以及 `--workspace`）。 ## 基础非交互式示例 @@ -37,13 +37,13 @@ openclaw onboard --non-interactive \ --skip-skills ``` -添加 `--json` 以获得机器可读的摘要。 +添加 `--json` 可获得机器可读的摘要。 -使用 `--secret-input-mode ref` 可将基于环境变量的引用存储到认证 profile 中，而不是存储明文值。 +使用 `--secret-input-mode ref` 可将基于环境变量的引用存储到凭证配置中，而不是存储明文值。 在新手引导流程中，支持在环境变量引用和已配置的提供商引用（`file` 或 `exec`）之间进行交互式选择。 -在非交互式 `ref` 模式下，提供商环境变量必须在进程环境中设置。 -传入内联密钥标志但未设置对应环境变量时，现在会快速失败。 +在非交互式 `ref` 模式下，必须在进程环境中设置提供商环境变量。 +如果传入内联密钥标志，但未设置对应环境变量，现在会快速失败。 示例： @@ -55,7 +55,7 @@ openclaw onboard --non-interactive \ --accept-risk ``` -## 提供商特定示例 +## 提供商专用示例 @@ -110,7 +110,7 @@ openclaw onboard --non-interactive \ --gateway-bind loopback ``` - + ```bash openclaw onboard --non-interactive \ --mode local \ @@ -149,7 +149,7 @@ openclaw onboard --non-interactive \ --gateway-port 18789 \ --gateway-bind loopback ``` - 如果要使用 Go catalog，请改为 `--auth-choice opencode-go --opencode-go-api-key "$OPENCODE_API_KEY"`。 + 如需使用 Go 目录，请改为 `--auth-choice opencode-go --opencode-go-api-key "$OPENCODE_API_KEY"`。 ```bash @@ -176,9 +176,9 @@ openclaw onboard --non-interactive \ --gateway-bind loopback ``` - `--custom-api-key` 是可选项。如果省略，新手引导会检查 `CUSTOM_API_KEY`。 + `--custom-api-key` 为可选项。如果省略，新手引导会检查 `CUSTOM_API_KEY`。 - ref 模式变体： + `ref` 模式变体： ```bash export CUSTOM_API_KEY="your-key" @@ -194,23 +194,22 @@ openclaw onboard --non-interactive \ --gateway-bind loopback ``` - 在该模式下，新手引导会将 `apiKey` 存储为 `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`。 + 在此模式下，新手引导会将 `apiKey` 存储为 `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`。 -Anthropic setup-token 仍然可作为受支持的新手引导令牌路径使用，但 OpenClaw 现在在可用时更优先使用 Claude CLI 复用。 -在生产环境中，优先使用 Anthropic API 密钥。 +Anthropic setup-token 仍然作为受支持的新手引导 token 路径保留，但 OpenClaw 现在在可用时更倾向于复用 Claude CLI。 +在生产环境中，建议优先使用 Anthropic API 密钥。 ## 添加另一个智能体 -使用 `openclaw agents add ` 创建一个单独的智能体，它拥有自己的工作区、 -会话和认证 profile。不带 `--workspace` 运行会启动向导。 +使用 `openclaw agents add ` 创建一个单独的智能体，它拥有自己的工作区、会话和凭证配置。不带 `--workspace` 运行会启动向导。 ```bash openclaw agents add work \ --workspace ~/.openclaw/workspace-work \ - --model openai/gpt-5.4 \ + --model openai/gpt-5.5 \ --bind whatsapp:biz \ --non-interactive \ --json @@ -225,11 +224,11 @@ openclaw agents add work \ 说明： - 默认工作区遵循 `~/.openclaw/workspace-`。 -- 添加 `bindings` 以路由入站消息（向导可以完成此操作）。 +- 添加 `bindings` 以路由传入消息（向导可以完成此操作）。 - 非交互式标志：`--model`、`--agent-dir`、`--bind`、`--non-interactive`。 ## 相关文档 - 新手引导中心：[设置向导（CLI）](/zh-CN/start/wizard) - 完整参考：[CLI 设置参考](/zh-CN/start/wizard-cli-reference) -- 命令参考：[`openclaw onboard`](/cli/onboard) +- 命令参考：[`openclaw onboard`](/zh-CN/cli/onboard) diff --git a/docs/zh-CN/start/wizard-cli-reference.md b/docs/zh-CN/start/wizard-cli-reference.md index fbd4c111a..9498fb126 100644 --- a/docs/zh-CN/start/wizard-cli-reference.md +++ b/docs/zh-CN/start/wizard-cli-reference.md @@ -1,15 +1,15 @@ --- read_when: - - 你需要了解 `openclaw onboard` 的详细行为 - - 你正在调试新手引导结果，或集成新手引导客户端 + - 你需要 `openclaw onboard` 的详细行为说明 + - 你正在调试新手引导结果或集成新手引导客户端 sidebarTitle: CLI reference -summary: CLI 设置流程、凭证 / 模型设置、输出和内部机制的完整参考 +summary: CLI 设置流程、凭证/模型设置、输出和内部机制的完整参考 title: CLI 设置参考 x-i18n: - generated_at: "2026-04-23T02:36:28Z" + generated_at: "2026-04-23T19:27:12Z" model: gpt-5.4 provider: openai - source_hash: 60b47a3cd7eaa6e10b5e7108ba4eb331afddffa55a321eac98243611fd7e721b + source_hash: 485f7d074b5f9cde9cb9342bd213a93a8221c3561a92184edeceb98c40267d1d source_path: start/wizard-cli-reference.md workflow: 15 --- @@ -17,88 +17,88 @@ x-i18n: # CLI 设置参考 本页是 `openclaw onboard` 的完整参考。 -简短指南见 [设置向导（CLI）](/zh-CN/start/wizard)。 +简要指南请参阅[设置向导（CLI）](/zh-CN/start/wizard)。 -## 向导的作用 +## 向导会执行什么 -本地模式（默认）会引导你完成： +本地模式（默认）会引导你完成以下内容： -- 模型和凭证设置（OpenAI Code 订阅 OAuth、Anthropic Claude CLI 或 API 密钥，以及 MiniMax、GLM、Ollama、Moonshot、StepFun 和 AI Gateway 选项） -- 工作区位置和引导文件 -- Gateway 网关设置（端口、绑定、凭证、Tailscale） -- 渠道和提供商（Telegram、WhatsApp、Discord、Google Chat、Mattermost、Signal、BlueBubbles，以及其他内置渠道插件） +- 模型和凭证设置（OpenAI Code subscription OAuth、Anthropic Claude CLI 或 API 密钥，以及 MiniMax、GLM、Ollama、Moonshot、StepFun 和 AI Gateway 选项） +- 工作区位置和 bootstrap 文件 +- Gateway 网关设置（port、bind、auth、Tailscale） +- 渠道和提供商（Telegram、WhatsApp、Discord、Google Chat、Mattermost、Signal、BlueBubbles 及其他内置渠道插件） - 守护进程安装（LaunchAgent、systemd 用户单元，或原生 Windows Scheduled Task，并在失败时回退到 Startup 文件夹） - 健康检查 - Skills 设置 -远程模式会将这台机器配置为连接到其他位置的 Gateway 网关。 +远程模式会将本机配置为连接到其他地方的 Gateway 网关。 它不会在远程主机上安装或修改任何内容。 ## 本地流程详情 - - - 如果存在 `~/.openclaw/openclaw.json`，可选择保留、修改或重置。 - - 重新运行向导不会清除任何内容，除非你明确选择重置（或传入 `--reset`）。 - - CLI `--reset` 默认作用于 `config+creds+sessions`；使用 `--reset-scope full` 还会移除工作区。 - - 如果配置无效或包含旧版键名，向导会停止，并要求你先运行 `openclaw doctor` 后再继续。 + + - 如果 `~/.openclaw/openclaw.json` 已存在，可选择保留、修改或重置。 + - 重新运行向导不会清除任何内容，除非你明确选择“重置”（或传入 `--reset`）。 + - CLI `--reset` 默认作用于 `config+creds+sessions`；使用 `--reset-scope full` 可连同工作区一起移除。 + - 如果配置无效或包含旧版键名，向导会停止，并要求你先运行 `openclaw doctor` 再继续。 - 重置使用 `trash`，并提供以下范围： - 仅配置 - 配置 + 凭证 + 会话 - - 完整重置（同时移除工作区） + - 完全重置（还会移除工作区） - - - 完整选项矩阵见 [凭证和模型选项](#auth-and-model-options)。 + + - 完整选项矩阵见[凭证与模型选项](#auth-and-model-options)。 - - 默认值为 `~/.openclaw/workspace`（可配置）。 - - 会写入首次运行引导仪式所需的工作区文件。 - - 工作区布局见：[智能体工作区](/zh-CN/concepts/agent-workspace)。 + - 默认 `~/.openclaw/workspace`（可配置）。 + - 会为首次运行 bootstrap ritual 预置所需工作区文件。 + - 工作区布局： [智能体工作区](/zh-CN/concepts/agent-workspace)。 - - 会提示你设置端口、绑定、凭证模式和 Tailscale 暴露方式。 - - 推荐：即使仅用于 loopback，也保持启用令牌凭证，这样本地 WS 客户端也必须进行认证。 - - 在令牌模式下，交互式设置提供： - - **生成 / 存储明文令牌**（默认） + - 会提示输入 port、bind、auth 模式和 Tailscale 暴露设置。 + - 建议：即使使用 loopback，也保留 token 认证开启，这样本地 WS 客户端也必须进行认证。 + - 在 token 模式下，交互式设置提供： + - **生成/存储明文 token**（默认） - **使用 SecretRef**（可选启用） - - 在密码模式下，交互式设置也支持明文或 SecretRef 存储。 - - 非交互式令牌 SecretRef 路径：`--gateway-token-ref-env `。 - - 要求新手引导进程环境中存在非空环境变量。 + - 在 password 模式下，交互式设置也支持明文或 SecretRef 存储。 + - 非交互式 token SecretRef 路径：`--gateway-token-ref-env `。 + - 要求在新手引导进程环境中提供非空环境变量。 - 不能与 `--gateway-token` 同时使用。 - - 仅当你完全信任每个本地进程时，才禁用凭证。 - - 非 loopback 绑定仍然需要凭证。 + - 只有在你完全信任每个本地进程时，才建议禁用认证。 + - 非 loopback 绑定仍然需要认证。 - [WhatsApp](/zh-CN/channels/whatsapp)：可选 QR 登录 - - [Telegram](/zh-CN/channels/telegram)：机器人令牌 - - [Discord](/zh-CN/channels/discord)：机器人令牌 + - [Telegram](/zh-CN/channels/telegram)：bot token + - [Discord](/zh-CN/channels/discord)：bot token - [Google Chat](/zh-CN/channels/googlechat)：服务账号 JSON + webhook audience - - [Mattermost](/zh-CN/channels/mattermost)：机器人令牌 + 基础 URL + - [Mattermost](/zh-CN/channels/mattermost)：bot token + base URL - [Signal](/zh-CN/channels/signal)：可选 `signal-cli` 安装 + 账号配置 - [BlueBubbles](/zh-CN/channels/bluebubbles)：推荐用于 iMessage；服务器 URL + 密码 + webhook - [iMessage](/zh-CN/channels/imessage)：旧版 `imsg` CLI 路径 + DB 访问 - - 私信安全：默认为配对。首次私信会发送一个代码；可通过 - `openclaw pairing approve ` 批准，或使用 allowlist。 + - 私信安全：默认是 pairing。首次私信会发送一个代码；可通过 + `openclaw pairing approve ` 批准，或使用允许列表。 - + - macOS：LaunchAgent - - 需要已登录的用户会话；对于无头环境，请使用自定义 LaunchDaemon（未随产品提供）。 + - 需要已登录的用户会话；对于无头环境，请使用自定义 LaunchDaemon（未内置提供）。 - Linux 和通过 WSL2 的 Windows：systemd 用户单元 - - 向导会尝试执行 `loginctl enable-linger `，以便 Gateway 网关在注销后继续运行。 - - 可能会提示 sudo（写入 `/var/lib/systemd/linger`）；它会先尝试无 sudo 方式。 + - 向导会尝试执行 `loginctl enable-linger `，以便登出后 Gateway 网关仍保持运行。 + - 可能会请求 sudo（写入 `/var/lib/systemd/linger`）；会先尝试不使用 sudo。 - 原生 Windows：优先使用 Scheduled Task - 如果任务创建被拒绝，OpenClaw 会回退到每用户 Startup 文件夹登录项，并立即启动 Gateway 网关。 - - 仍优先推荐 Scheduled Task，因为它们提供更好的主管理器状态信息。 - - 运行时选择：Node（推荐；WhatsApp 和 Telegram 需要）。不推荐使用 Bun。 + - 仍然优先推荐 Scheduled Tasks，因为它们提供更好的 supervisor 状态。 + - 运行时选择：Node（推荐；WhatsApp 和 Telegram 必需）。不建议使用 Bun。 - - 启动 Gateway 网关（如有需要）并运行 `openclaw health`。 - - `openclaw status --deep` 会在状态输出中加入实时 Gateway 网关健康探测，包括支持时的渠道探测。 + - 启动 Gateway 网关（如果需要）并运行 `openclaw health`。 + - `openclaw status --deep` 会将实时 Gateway 网关健康探测加入状态输出，在支持时还包括渠道探测。 - - 读取可用 Skills 并检查要求。 - - 让你选择 Node 管理器：npm、pnpm 或 bun。 - - 安装可选依赖（其中一些在 macOS 上使用 Homebrew）。 + - 读取可用 Skills 并检查依赖要求。 + - 让你选择 node 管理器：npm、pnpm 或 bun。 + - 安装可选依赖（部分在 macOS 上使用 Homebrew）。 - 显示摘要和后续步骤，包括 iOS、Android 和 macOS 应用选项。 @@ -107,12 +107,12 @@ x-i18n: 如果未检测到 GUI，向导会打印用于 Control UI 的 SSH 端口转发说明，而不是打开浏览器。 -如果缺少 Control UI 资源，向导会尝试构建它们；回退命令为 `pnpm ui:build`（会自动安装 UI 依赖）。 +如果缺少 Control UI 资源，向导会尝试构建；回退命令为 `pnpm ui:build`（会自动安装 UI 依赖）。 ## 远程模式详情 -远程模式会将这台机器配置为连接到其他位置的 Gateway 网关。 +远程模式会将本机配置为连接到其他地方的 Gateway 网关。 远程模式不会在远程主机上安装或修改任何内容。 @@ -121,44 +121,44 @@ x-i18n: 你需要设置： - 远程 Gateway 网关 URL（`ws://...`） -- 如果远程 Gateway 网关需要凭证，则设置令牌（推荐） +- 如果远程 Gateway 网关需要认证，则设置 token（推荐） -- 如果 Gateway 网关仅绑定到 loopback，请使用 SSH 隧道或 tailnet。 -- 发现提示： +- 如果 Gateway 网关仅绑定 loopback，请使用 SSH 隧道或 tailnet。 +- 设备发现提示： - macOS：Bonjour（`dns-sd`） - Linux：Avahi（`avahi-browse`） -## 凭证和模型选项 +## 凭证与模型选项 - 如果存在 `ANTHROPIC_API_KEY` 则使用它，否则提示输入密钥，然后保存供守护进程使用。 + 如果存在 `ANTHROPIC_API_KEY` 则使用它，否则提示输入密钥，然后将其保存以供守护进程使用。 - + 浏览器流程；粘贴 `code#state`。 - 当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.4`。 + 当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.5`。 - - 浏览器配对流程，使用短时有效的设备代码。 + + 浏览器配对流程，使用短期有效的设备码。 - 当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.4`。 + 当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.5`。 - 如果存在 `OPENAI_API_KEY` 则使用它，否则提示输入密钥，然后将该凭证存储到凭证配置文件中。 + 如果存在 `OPENAI_API_KEY` 则使用它，否则提示输入密钥，然后将凭证存储到凭证配置中。 - 当模型未设置、为 `openai/*` 或 `openai-codex/*` 时，将 `agents.defaults.model` 设置为 `openai/gpt-5.4`。 + 当模型未设置、为 `openai/*` 或为 `openai-codex/*` 时，将 `agents.defaults.model` 设置为 `openai/gpt-5.5`。 提示输入 `XAI_API_KEY`，并将 xAI 配置为模型提供商。 - 提示输入 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`），并让你选择 Zen 或 Go 目录。 + 提示输入 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`），并允许你选择 Zen 或 Go 目录。 设置 URL：[opencode.ai/auth](https://opencode.ai/auth)。 @@ -166,43 +166,43 @@ x-i18n: 提示输入 `AI_GATEWAY_API_KEY`。 - 更多详情见：[Vercel AI Gateway](/zh-CN/providers/vercel-ai-gateway)。 + 更多细节： [Vercel AI Gateway](/zh-CN/providers/vercel-ai-gateway)。 - 提示输入账号 ID、Gateway 网关 ID 和 `CLOUDFLARE_AI_GATEWAY_API_KEY`。 - 更多详情见：[Cloudflare AI Gateway](/zh-CN/providers/cloudflare-ai-gateway)。 + 提示输入 account ID、gateway ID 和 `CLOUDFLARE_AI_GATEWAY_API_KEY`。 + 更多细节： [Cloudflare AI Gateway](/zh-CN/providers/cloudflare-ai-gateway)。 配置会自动写入。托管默认值为 `MiniMax-M2.7`；API 密钥设置使用 `minimax/...`，OAuth 设置使用 `minimax-portal/...`。 - 更多详情见：[MiniMax](/zh-CN/providers/minimax)。 + 更多细节： [MiniMax](/zh-CN/providers/minimax)。 - 配置会针对中国或全球端点的 StepFun standard 或 Step Plan 自动写入。 - Standard 当前包括 `step-3.5-flash`，Step Plan 还包括 `step-3.5-flash-2603`。 - 更多详情见：[StepFun](/zh-CN/providers/stepfun)。 + 会为中国或全球端点上的 StepFun standard 或 Step Plan 自动写入配置。 + StepFun standard 当前包括 `step-3.5-flash`，Step Plan 还包括 `step-3.5-flash-2603`。 + 更多细节： [StepFun](/zh-CN/providers/stepfun)。 提示输入 `SYNTHETIC_API_KEY`。 - 更多详情见：[Synthetic](/zh-CN/providers/synthetic)。 + 更多细节： [Synthetic](/zh-CN/providers/synthetic)。 - + 会先提示选择 `Cloud + Local`、`Cloud only` 或 `Local only`。 `Cloud only` 使用 `OLLAMA_API_KEY` 和 `https://ollama.com`。 - 基于主机的模式会提示输入基础 URL（默认 `http://127.0.0.1:11434`），发现可用模型，并建议默认值。 - `Cloud + Local` 还会检查该 Ollama 主机是否已登录以访问云端。 - 更多详情见：[Ollama](/zh-CN/providers/ollama)。 + 基于主机的模式会提示输入 base URL（默认 `http://127.0.0.1:11434`），发现可用模型，并给出默认建议。 + `Cloud + Local` 还会检查该 Ollama 主机是否已登录以获得 cloud 访问权限。 + 更多细节： [Ollama](/zh-CN/providers/ollama)。 Moonshot（Kimi K2）和 Kimi Coding 配置会自动写入。 - 更多详情见：[Moonshot AI（Kimi + Kimi Coding）](/zh-CN/providers/moonshot)。 + 更多细节： [Moonshot AI（Kimi + Kimi Coding）](/zh-CN/providers/moonshot)。 - 适用于兼容 OpenAI 和兼容 Anthropic 的端点。 + 可用于兼容 OpenAI 和兼容 Anthropic 的端点。 - 交互式新手引导支持与其他提供商 API 密钥流程相同的 API 密钥存储选项： - - **立即粘贴 API 密钥**（明文） - - **使用 secret reference**（环境变量引用或已配置的提供商引用，带预检校验） + 交互式新手引导支持与其他提供商 API 密钥流程相同的 API 密钥存储方式： + - **现在粘贴 API 密钥**（明文） + - **使用密钥引用**（环境变量引用或已配置提供商引用，带预检校验） 非交互式标志： - `--auth-choice custom-api-key` @@ -221,47 +221,42 @@ x-i18n: 模型行为： - 从检测到的选项中选择默认模型，或手动输入提供商和模型。 -- 当新手引导从某个提供商凭证选项开始时，模型选择器会自动优先 - 该提供商。对于 Volcengine 和 BytePlus，此优先级 - 也会匹配它们的 coding-plan 变体（`volcengine-plan/*`、 - `byteplus-plan/*`）。 -- 如果该优先提供商过滤后为空，选择器会回退到 - 完整目录，而不是显示没有模型。 -- 向导会运行模型检查，并在配置的模型未知或缺少凭证时发出警告。 +- 当新手引导从某个提供商凭证选项开始时，模型选择器会自动优先该提供商。对于 Volcengine 和 BytePlus，同样的偏好也会匹配它们的 coding-plan 变体（`volcengine-plan/*`、`byteplus-plan/*`）。 +- 如果这种按优先提供商过滤后会得到空结果，选择器会回退到完整目录，而不是显示无模型可选。 +- 向导会运行模型检查，并在已配置模型未知或缺少凭证时发出警告。 -凭证和配置文件路径： +凭证和配置路径： -- 凭证配置文件（API 密钥 + OAuth）：`~/.openclaw/agents//agent/auth-profiles.json` +- 凭证配置（API 密钥 + OAuth）：`~/.openclaw/agents//agent/auth-profiles.json` - 旧版 OAuth 导入：`~/.openclaw/credentials/oauth.json` 凭证存储模式： -- 默认新手引导行为会将 API 密钥作为明文值持久化到凭证配置文件中。 +- 默认新手引导行为会将 API 密钥以明文值形式持久化到凭证配置中。 - `--secret-input-mode ref` 会启用引用模式，而不是明文密钥存储。 - 在交互式设置中，你可以选择以下任一方式： + 在交互式设置中，你可以选择以下任一项： - 环境变量引用（例如 `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`） - - 已配置的提供商引用（`file` 或 `exec`），包含提供商别名 + id -- 交互式引用模式在保存前会执行快速预检校验。 + - 已配置提供商引用（`file` 或 `exec`），带提供商别名和 id +- 交互式引用模式会在保存前执行快速预检校验。 - 环境变量引用：校验变量名，以及当前新手引导环境中的非空值。 - 提供商引用：校验提供商配置并解析请求的 id。 - 如果预检失败，新手引导会显示错误并允许你重试。 -- 在非交互式模式下，`--secret-input-mode ref` 仅支持基于环境变量。 +- 在非交互式模式下，`--secret-input-mode ref` 仅支持基于环境变量的方式。 - 在新手引导进程环境中设置提供商环境变量。 - - 内联密钥标志（例如 `--openai-api-key`）要求该环境变量已设置；否则新手引导会快速失败。 + - 内联密钥标志（例如 `--openai-api-key`）要求对应环境变量已设置；否则新手引导会快速失败。 - 对于自定义提供商，非交互式 `ref` 模式会将 `models.providers..apiKey` 存储为 `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`。 - - 在该自定义提供商场景中，`--custom-api-key` 要求必须设置 `CUSTOM_API_KEY`；否则新手引导会快速失败。 -- Gateway 网关凭证凭据在交互式设置中支持明文和 SecretRef 选项： - - 令牌模式：**生成 / 存储明文令牌**（默认）或 **使用 SecretRef**。 - - 密码模式：明文或 SecretRef。 -- 非交互式令牌 SecretRef 路径：`--gateway-token-ref-env `。 -- 现有的明文设置会继续保持不变并正常工作。 + - 在该自定义提供商场景中，`--custom-api-key` 要求已设置 `CUSTOM_API_KEY`；否则新手引导会快速失败。 +- Gateway 网关认证凭证在交互式设置中支持明文和 SecretRef 两种选择： + - Token 模式：**生成/存储明文 token**（默认）或 **使用 SecretRef**。 + - Password 模式：明文或 SecretRef。 +- 非交互式 token SecretRef 路径：`--gateway-token-ref-env `。 +- 现有的明文设置仍可继续正常使用。 -无头环境和服务器提示：先在有浏览器的机器上完成 OAuth，然后复制 -该智能体的 `auth-profiles.json`（例如 +无头环境和服务器提示：请先在有浏览器的机器上完成 OAuth，然后将该智能体的 `auth-profiles.json`（例如 `~/.openclaw/agents//agent/auth-profiles.json`，或对应的 -`$OPENCLAW_STATE_DIR/...` 路径）到 Gateway 网关主机。`credentials/oauth.json` -仅是旧版导入来源。 +`$OPENCLAW_STATE_DIR/...` 路径）复制到 Gateway 网关主机。`credentials/oauth.json` +仅作为旧版导入来源。 ## 输出和内部机制 @@ -269,15 +264,15 @@ x-i18n: `~/.openclaw/openclaw.json` 中的典型字段： - `agents.defaults.workspace` -- `agents.defaults.model` / `models.providers`（如果选择了 MiniMax） +- `agents.defaults.model` / `models.providers`（如果选择了 Minimax） - `tools.profile`（本地新手引导在未设置时默认使用 `"coding"`；现有显式值会被保留） -- `gateway.*`（模式、绑定、凭证、Tailscale） -- `session.dmScope`（本地新手引导在未设置时默认将其设为 `per-channel-peer`；现有显式值会被保留） +- `gateway.*`（mode、bind、auth、Tailscale） +- `session.dmScope`（本地新手引导在未设置时默认设为 `per-channel-peer`；现有显式值会被保留） - `channels.telegram.botToken`、`channels.discord.token`、`channels.matrix.*`、`channels.signal.*`、`channels.imessage.*` -- 当你在提示中选择启用时的渠道 allowlist（Slack、Discord、Matrix、Microsoft Teams）（如果可能，名称会解析为 ID） +- 在提示中选择启用时的渠道允许列表（Slack、Discord、Matrix、Microsoft Teams）（在可能时会将名称解析为 ID） - `skills.install.nodeManager` - `setup --node-manager` 标志接受 `npm`、`pnpm` 或 `bun`。 - - 稍后手动配置仍可将 `skills.install.nodeManager: "yarn"`` 设置为该值。 + - 后续手动配置仍可将 `skills.install.nodeManager: "yarn"` 设为 `"yarn"`。 - `wizard.lastRunAt` - `wizard.lastRunVersion` - `wizard.lastRunCommit` @@ -290,7 +285,7 @@ WhatsApp 凭证位于 `~/.openclaw/credentials/whatsapp//` 下。 会话存储在 `~/.openclaw/agents//sessions/` 下。 -某些渠道以插件形式提供。在设置期间选择它们时，向导会先提示你安装插件（npm 或本地路径），然后再进行渠道配置。 +某些渠道以插件形式提供。在设置过程中选择这些渠道时，向导会先提示安装插件（npm 或本地路径），然后再进行渠道配置。 Gateway 网关向导 RPC： @@ -305,14 +300,14 @@ Gateway 网关向导 RPC： Signal 设置行为： - 下载合适的发布资源 -- 将其存储在 `~/.openclaw/tools/signal-cli//` 下 +- 将其存储到 `~/.openclaw/tools/signal-cli//` - 在配置中写入 `channels.signal.cliPath` - JVM 构建需要 Java 21 -- 可用时会使用原生构建 -- Windows 使用 WSL2，并在 WSL 内遵循 Linux 的 `signal-cli` 流程 +- 可用时优先使用原生构建 +- Windows 使用 WSL2，并在 WSL 内遵循 Linux 的 signal-cli 流程 ## 相关文档 -- 新手引导中心：[设置向导（CLI）](/start/wizard) -- 自动化和脚本：[CLI 自动化](/start/wizard-cli-automation) -- 命令参考：[`openclaw onboard`](/cli/onboard) +- 新手引导中心：[设置向导（CLI）](/zh-CN/start/wizard) +- 自动化与脚本：[CLI 自动化](/zh-CN/start/wizard-cli-automation) +- 命令参考：[`openclaw onboard`](/zh-CN/cli/onboard) diff --git a/docs/zh-CN/tools/acp-agents.md b/docs/zh-CN/tools/acp-agents.md index 19ea0dd1e..a164efd6a 100644 --- a/docs/zh-CN/tools/acp-agents.md +++ b/docs/zh-CN/tools/acp-agents.md @@ -1,86 +1,88 @@ --- read_when: - 通过 ACP 运行编码 harness - - 在消息渠道上设置绑定到对话的 ACP 会话 - - 将消息渠道中的对话绑定到持久化 ACP 会话 + - 在消息渠道上设置与会话绑定的 ACP 会话 + - 将消息渠道会话绑定到持久化 ACP 会话 - 排查 ACP 后端和插件接线问题 - - 调试 ACP 完成结果投递或智能体到智能体循环问题 + - 调试 ACP 完成结果传递或智能体到智能体循环问题 - 从聊天中操作 `/acp` 命令 summary: 对 Codex、Claude Code、Cursor、Gemini CLI、OpenClaw ACP 和其他 harness 智能体使用 ACP 运行时会话 title: ACP 智能体 x-i18n: - generated_at: "2026-04-23T16:17:19Z" + generated_at: "2026-04-23T19:27:21Z" model: gpt-5.4 provider: openai - source_hash: 4a3205cf8d52564c4bf9b289e329de1c56743697d14fa22e2190946be54e4db4 + source_hash: 329e64aa98d722e649cd4f079a66d14f4f331de9994646539995d1b371bbacb3 source_path: tools/acp-agents.md workflow: 15 --- # ACP 智能体 -[Agent Client Protocol (ACP)](https://agentclientprotocol.com/) 会话让 OpenClaw 能够通过 ACP 后端插件运行外部编码 harness（例如 Pi、Claude Code、Codex、Cursor、Copilot、OpenClaw ACP、OpenCode、Gemini CLI 以及其他受支持的 ACPX harness）。 +[Agent Client Protocol（ACP）](https://agentclientprotocol.com/) 会话让 OpenClaw 能够通过 ACP 后端插件运行外部编码 harness（例如 Pi、Claude Code、Codex、Cursor、Copilot、OpenClaw ACP、OpenCode、Gemini CLI，以及其他受支持的 ACPX harness）。 -如果你用自然语言要求 OpenClaw “在 Codex 中运行这个”或“在线程中启动 Claude Code”，OpenClaw 应该将该请求路由到 ACP 运行时（而不是原生子智能体运行时）。每次 ACP 会话启动都会被跟踪为一个[后台任务](/zh-CN/automation/tasks)。 +如果你用自然语言要求 OpenClaw “在 Codex 中运行这个” 或 “在线程里启动 Claude Code”，OpenClaw 应将该请求路由到 ACP 运行时（而不是原生子智能体运行时）。每次 ACP 会话启动都会被跟踪为一个[后台任务](/zh-CN/automation/tasks)。 -如果你希望 Codex 或 Claude Code 作为外部 MCP 客户端直接连接到现有的 OpenClaw 渠道对话，请使用 [`openclaw mcp serve`](/zh-CN/cli/mcp)，而不是 ACP。 +如果你想让 Codex 或 Claude Code 作为外部 MCP 客户端直接连接 +到现有的 OpenClaw 渠道会话，请改用 [`openclaw mcp serve`](/zh-CN/cli/mcp)， +而不是 ACP。 -## 我该看哪个页面？ +## 我需要哪个页面？ -这里有三个相近但很容易混淆的功能入口： +这里附近有三个很容易混淆的界面： -| 你想要... | 使用这个 | 说明 | +| 你想要…… | 使用这个 | 说明 | | ---------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | 通过 OpenClaw 运行 Codex、Claude Code、Gemini CLI 或其他外部 harness | 本页：ACP 智能体 | 绑定聊天的会话、`/acp spawn`、`sessions_spawn({ runtime: "acp" })`、后台任务、运行时控制 | -| 将一个 OpenClaw Gateway 网关会话作为 ACP 服务器暴露给编辑器或客户端 | [`openclaw acp`](/zh-CN/cli/acp) | 桥接模式。IDE/客户端 通过 stdio/WebSocket 使用 ACP 与 OpenClaw 通信 | -| 复用本地 AI CLI 作为纯文本回退模型 | [CLI 后端](/zh-CN/gateway/cli-backends) | 不是 ACP。没有 OpenClaw 工具、没有 ACP 控制、也没有 harness 运行时 | +| 将一个 OpenClaw Gateway 网关会话作为 ACP 服务器暴露给编辑器或客户端 | [`openclaw acp`](/zh-CN/cli/acp) | 桥接模式。IDE / 客户端通过 stdio / WebSocket 向 OpenClaw 发送 ACP | +| 将本地 AI CLI 复用为仅文本的回退模型 | [CLI 后端](/zh-CN/gateway/cli-backends) | 不是 ACP。没有 OpenClaw 工具、没有 ACP 控制、也没有 harness 运行时 | -## 这开箱即用吗？ +## 开箱即用吗？ -通常可以。全新安装默认启用内置的 `acpx` 运行时插件，并附带一个插件本地固定版本的 `acpx` 二进制文件，OpenClaw 会在启动时探测并自我修复。运行 `/acp doctor` 可执行就绪性检查。 +通常可以。全新安装默认启用内置的 `acpx` 运行时插件，并带有一个插件本地固定版本的 `acpx` 二进制文件，OpenClaw 会在启动时对其进行探测和自修复。运行 `/acp doctor` 可进行就绪检查。 首次运行的注意事项： -- 目标 harness 适配器（Codex、Claude 等）可能会在你首次使用时通过 `npx` 按需获取。 -- 该 harness 所需的厂商认证仍然必须已存在于主机上。 -- 如果主机没有 npm 或没有网络访问能力，则首次运行时的适配器获取会失败，直到缓存被预热或适配器通过其他方式安装。 +- 目标 harness 适配器（Codex、Claude 等）在你首次使用时，可能会通过 `npx` 按需获取。 +- 该 harness 对应的厂商认证信息仍然必须存在于主机上。 +- 如果主机没有 npm 或网络访问能力，那么首次运行的适配器获取会失败，直到缓存预热完成或通过其他方式安装适配器。 -## 操作手册 +## 运维操作手册 在聊天中使用 `/acp` 的快速流程： -1. **启动** — `/acp spawn codex --bind here` 或 `/acp spawn codex --mode persistent --thread auto` -2. 在绑定的对话或线程中**工作**（或者显式指定会话键）。 -3. **检查状态** — `/acp status` -4. **调整** — `/acp model `、`/acp permissions `、`/acp timeout ` -5. **引导**而不替换上下文 — `/acp steer tighten logging and continue` -6. **停止** — `/acp cancel`（当前轮次）或 `/acp close`（会话 + 绑定） +1. **启动** —— `/acp spawn codex --bind here` 或 `/acp spawn codex --mode persistent --thread auto` +2. 在绑定的会话或线程中**工作**（或者显式指定会话键）。 +3. **检查状态** —— `/acp status` +4. **调优** —— `/acp model `、`/acp permissions `、`/acp timeout ` +5. 在不替换上下文的情况下**引导** —— `/acp steer tighten logging and continue` +6. **停止** —— `/acp cancel`（当前轮次）或 `/acp close`（会话 + 绑定） -应当路由到 ACP 运行时的自然语言触发示例： +应路由到 ACP 运行时的自然语言触发方式： -- “把这个 Discord 渠道绑定到 Codex。” -- “在这里的一个线程中启动持久化的 Codex 会话。” -- “把这个作为一次性的 Claude Code ACP 会话运行，并总结结果。” -- “对此任务使用 Gemini CLI 并放在线程里，然后后续继续在同一个线程中进行。” +- “把这个 Discord 频道绑定到 Codex。” +- “在这里的线程里启动一个持久的 Codex 会话。” +- “把这个作为一次性 Claude Code ACP 会话运行，并总结结果。” +- “在线程里用 Gemini CLI 处理这个任务，然后把后续跟进继续保留在同一个线程里。” -OpenClaw 会选择 `runtime: "acp"`，解析 harness 的 `agentId`，在支持时绑定到当前对话或线程，并将后续消息路由到该会话，直到关闭或过期。 +OpenClaw 会选择 `runtime: "acp"`，解析 harness `agentId`，在支持时绑定到当前会话或线程，并在关闭 / 过期之前将后续消息路由到该会话。 -## ACP 与子智能体的区别 +## ACP 与子智能体 -当你想使用外部 harness 运行时时，请使用 ACP。想使用 OpenClaw 原生委派运行时，则使用子智能体。 +当你想使用外部 harness 运行时时，请使用 ACP。当你想使用 OpenClaw 原生委派运行时，请使用子智能体。 | 区域 | ACP 会话 | 子智能体运行 | | ------------- | ------------------------------------- | ---------------------------------- | | 运行时 | ACP 后端插件（例如 acpx） | OpenClaw 原生子智能体运行时 | | 会话键 | `agent::acp:` | `agent::subagent:` | | 主要命令 | `/acp ...` | `/subagents ...` | -| 启动工具 | `sessions_spawn` 且 `runtime:"acp"` | `sessions_spawn`（默认运行时） | +| 启动工具 | `sessions_spawn` 且使用 `runtime:"acp"` | `sessions_spawn`（默认运行时） | -另请参见[子智能体](/zh-CN/tools/subagents)。 +另请参见 [子智能体](/zh-CN/tools/subagents)。 ## ACP 如何运行 Claude Code -通过 ACP 运行 Claude Code 时，调用栈如下： +对于通过 ACP 运行的 Claude Code，其栈如下： 1. OpenClaw ACP 会话控制平面 2. 内置的 `acpx` 运行时插件 @@ -89,56 +91,56 @@ OpenClaw 会选择 `runtime: "acp"`，解析 harness 的 `agentId`，在支持 重要区别： -- ACP Claude 是一个 harness 会话，带有 ACP 控制、会话恢复、后台任务跟踪，以及可选的对话 / 线程绑定。 -- CLI 后端是独立的纯文本本地回退运行时。参见 [CLI 后端](/zh-CN/gateway/cli-backends)。 +- ACP Claude 是一个 harness 会话，具备 ACP 控制、会话恢复、后台任务跟踪以及可选的会话 / 线程绑定。 +- CLI 后端是单独的、仅文本的本地回退运行时。参见 [CLI 后端](/zh-CN/gateway/cli-backends)。 -对操作人员来说，实用规则是： +对运维人员来说，实用规则是： - 想要 `/acp spawn`、可绑定会话、运行时控制或持久化 harness 工作：使用 ACP -- 想通过原始 CLI 获得简单的本地文本回退：使用 CLI 后端 +- 想要通过原始 CLI 获得简单的本地文本回退：使用 CLI 后端 ## 绑定会话 -### 绑定当前对话 +### 当前会话绑定 -`/acp spawn --bind here` 会将当前对话固定绑定到已启动的 ACP 会话——不会创建子线程，仍在同一聊天界面。OpenClaw 继续负责传输、认证、安全与投递；该对话中的后续消息会路由到同一个会话；`/new` 和 `/reset` 会在原位置重置该会话；`/acp close` 会移除该绑定。 +`/acp spawn --bind here` 会将当前会话固定到启动的 ACP 会话 —— 不创建子线程，保持在同一聊天界面。OpenClaw 仍然负责传输、认证、安全和投递；该会话中的后续消息会路由到同一个会话；`/new` 和 `/reset` 会在原地重置该会话；`/acp close` 会移除该绑定。 -理解模型： +心智模型： -- **聊天界面** —— 人们持续对话的地方（Discord 渠道、Telegram 话题、iMessage 聊天）。 +- **聊天界面** —— 人们持续对话的地方（Discord 频道、Telegram 话题、iMessage 聊天）。 - **ACP 会话** —— OpenClaw 路由到的持久化 Codex / Claude / Gemini 运行时状态。 -- **子线程 / 话题** —— 仅在使用 `--thread ...` 时创建的可选额外消息界面。 -- **运行时工作区** —— harness 运行所在的文件系统位置（`cwd`、repo 检出目录、后端工作区）。它独立于聊天界面。 +- **子线程 / 话题** —— 仅由 `--thread ...` 创建的可选额外消息界面。 +- **运行时工作区** —— harness 运行所在的文件系统位置（`cwd`、仓库 checkout、后端工作区）。它独立于聊天界面。 示例： -- `/acp spawn codex --bind here` — 保持当前聊天，启动或连接 Codex，并将后续消息路由到这里。 -- `/acp spawn codex --thread auto` — OpenClaw 可以创建一个子线程 / 话题并绑定到那里。 -- `/acp spawn codex --bind here --cwd /workspace/repo` — 仍然绑定当前聊天，但 Codex 在 `/workspace/repo` 中运行。 +- `/acp spawn codex --bind here` —— 保持当前聊天，启动或附加 Codex，并将未来消息路由到这里。 +- `/acp spawn codex --thread auto` —— OpenClaw 可能会创建一个子线程 / 话题并在那里绑定。 +- `/acp spawn codex --bind here --cwd /workspace/repo` —— 同样绑定当前聊天，Codex 在 `/workspace/repo` 中运行。 说明： - `--bind here` 和 `--thread ...` 互斥。 -- `--bind here` 仅适用于声明支持当前对话绑定的渠道；否则 OpenClaw 会返回明确的不支持提示。绑定会在 Gateway 网关重启后继续保留。 -- 在 Discord 上，仅当 OpenClaw 需要为 `--thread auto|here` 创建子线程时，才需要 `spawnAcpSessions`；`--bind here` 不需要。 -- 如果你启动到另一个 ACP 智能体且未指定 `--cwd`，OpenClaw 默认继承**目标智能体的**工作区。若继承路径不存在（`ENOENT`/`ENOTDIR`），则回退到后端默认值；其他访问错误（例如 `EACCES`）会作为启动错误直接显示。 +- `--bind here` 仅适用于声明支持当前会话绑定的渠道；否则 OpenClaw 会返回清晰的不支持提示。绑定会跨 Gateway 网关重启持久化。 +- 在 Discord 上，仅当 OpenClaw 需要为 `--thread auto|here` 创建子线程时，才需要 `spawnAcpSessions` —— `--bind here` 不需要。 +- 如果你在未指定 `--cwd` 的情况下启动到不同的 ACP 智能体，OpenClaw 默认会继承**目标智能体的**工作区。缺失的继承路径（`ENOENT` / `ENOTDIR`）会回退到后端默认值；其他访问错误（例如 `EACCES`）会作为启动错误直接显示。 -### 绑定到线程的会话 +### 线程绑定会话 当某个渠道适配器启用了线程绑定时，ACP 会话可以绑定到线程： - OpenClaw 将线程绑定到目标 ACP 会话。 -- 该线程中的后续消息会路由到已绑定的 ACP 会话。 -- ACP 输出会投递回同一个线程。 -- 失焦 / 关闭 / 归档 / 空闲超时或最大存活时间到期时，该绑定会被移除。 +- 该线程中的后续消息会路由到绑定的 ACP 会话。 +- ACP 输出会回传到同一个线程。 +- 失焦 / 关闭 / 归档 / 空闲超时或最大存活时间到期时，会移除绑定。 -线程绑定支持取决于适配器。如果当前渠道适配器不支持线程绑定，OpenClaw 会返回明确的不支持 / 不可用提示。 +线程绑定支持取决于适配器。如果当前渠道适配器不支持线程绑定，OpenClaw 会返回清晰的不支持 / 不可用消息。 -线程绑定 ACP 所需的功能标志： +线程绑定 ACP 所需的功能开关： - `acp.enabled=true` - `acp.dispatch.enabled` 默认开启（设为 `false` 可暂停 ACP 分发） -- 渠道适配器的 ACP 线程启动标志已启用（适配器特定） +- 已启用渠道适配器 ACP 线程启动开关（适配器特定） - Discord：`channels.discord.threadBindings.spawnAcpSessions=true` - Telegram：`channels.telegram.threadBindings.spawnAcpSessions=true` @@ -146,23 +148,23 @@ OpenClaw 会选择 `runtime: "acp"`，解析 harness 的 `agentId`，在支持 - 任何暴露会话 / 线程绑定能力的渠道适配器。 - 当前内置支持： - - Discord 线程 / 渠道 - - Telegram 话题（群组 / 超级群组中的 forum topics，以及私信话题） -- 渠道插件也可以通过相同的绑定接口添加支持。 + - Discord 线程 / 频道 + - Telegram 话题（群组 / 超级群组中的论坛话题，以及私信话题） +- 插件渠道也可以通过相同的绑定接口添加支持。 ## 渠道特定设置 -对于非临时工作流，请在顶层 `bindings[]` 条目中配置持久化 ACP 绑定。 +对于非临时性工作流，请在顶层 `bindings[]` 条目中配置持久化 ACP 绑定。 ### 绑定模型 -- `bindings[].type="acp"` 表示持久化 ACP 对话绑定。 -- `bindings[].match` 用于标识目标对话： - - Discord 渠道或线程：`match.channel="discord"` + `match.peer.id=""` - - Telegram forum topic：`match.channel="telegram"` + `match.peer.id=":topic:"` - - BlueBubbles 私信 / 群聊：`match.channel="bluebubbles"` + `match.peer.id=""` +- `bindings[].type="acp"` 表示一个持久化 ACP 会话绑定。 +- `bindings[].match` 标识目标会话： + - Discord 频道或线程：`match.channel="discord"` + `match.peer.id=""` + - Telegram 论坛话题：`match.channel="telegram"` + `match.peer.id=":topic:"` + - BlueBubbles 私信 / 群聊：`match.channel="bluebubbles"` + `match.peer.id=""` 对于稳定的群组绑定，优先使用 `chat_id:*` 或 `chat_identifier:*`。 - - iMessage 私信 / 群聊：`match.channel="imessage"` + `match.peer.id=""` + - iMessage 私信 / 群聊：`match.channel="imessage"` + `match.peer.id=""` 对于稳定的群组绑定，优先使用 `chat_id:*`。 - `bindings[].agentId` 是所属的 OpenClaw 智能体 id。 - 可选的 ACP 覆盖项位于 `bindings[].acp` 下： @@ -267,24 +269,24 @@ ACP 绑定会话的覆盖优先级： } ``` -行为如下： +行为： -- OpenClaw 会在使用前确保配置的 ACP 会话已存在。 -- 该渠道或话题中的消息会路由到配置好的 ACP 会话。 -- 在已绑定的对话中，`/new` 和 `/reset` 会在原位置重置同一个 ACP 会话键。 -- 临时运行时绑定（例如由线程聚焦流程创建的绑定）在存在时仍然适用。 -- 对于未显式指定 `cwd` 的跨智能体 ACP 启动，OpenClaw 会从智能体配置中继承目标智能体的工作区。 -- 缺失的继承工作区路径会回退到后端默认 `cwd`；非缺失类访问失败会作为启动错误直接显示。 +- OpenClaw 会在使用前确保已配置的 ACP 会话存在。 +- 该频道或话题中的消息会路由到已配置的 ACP 会话。 +- 在已绑定的会话中，`/new` 和 `/reset` 会在原地重置同一个 ACP 会话键。 +- 临时运行时绑定（例如由线程聚焦流程创建的绑定）在存在时仍会生效。 +- 对于未显式指定 `cwd` 的跨智能体 ACP 启动，OpenClaw 会从智能体配置继承目标智能体工作区。 +- 缺失的继承工作区路径会回退到后端默认 `cwd`；非缺失类访问失败会作为启动错误显示。 ## 启动 ACP 会话（接口） -### 从 `sessions_spawn` +### 从 `sessions_spawn` 启动 -使用 `runtime: "acp"` 从智能体轮次或工具调用中启动 ACP 会话。 +使用 `runtime: "acp"` 可从智能体轮次或工具调用中启动 ACP 会话。 ```json { - "task": "打开这个仓库并总结失败的测试", + "task": "打开仓库并总结失败的测试", "runtime": "acp", "agentId": "codex", "thread": true, @@ -294,9 +296,9 @@ ACP 绑定会话的覆盖优先级： 说明： -- `runtime` 默认是 `subagent`，因此对于 ACP 会话，要显式设置 `runtime: "acp"`。 -- 如果省略 `agentId`，则在已配置时，OpenClaw 会使用 `acp.defaultAgent`。 -- `mode: "session"` 需要 `thread: true`，以保持持久化的绑定对话。 +- `runtime` 默认为 `subagent`，因此对于 ACP 会话，请显式设置 `runtime: "acp"`。 +- 如果省略 `agentId`，OpenClaw 会在已配置时使用 `acp.defaultAgent`。 +- `mode: "session"` 需要 `thread: true`，以保持一个持久绑定的会话。 接口详情： @@ -304,62 +306,62 @@ ACP 绑定会话的覆盖优先级： - `runtime`（ACP 必填）：必须为 `"acp"`。 - `agentId`（可选）：ACP 目标 harness id。如果已设置，则回退到 `acp.defaultAgent`。 - `thread`（可选，默认 `false`）：在支持时请求线程绑定流程。 -- `mode`（可选）：`run`（一次性）或 `session`（持久化）。 - - 默认是 `run` - - 如果 `thread: true` 且省略 `mode`，OpenClaw 可能会根据运行时路径默认使用持久化行为 +- `mode`（可选）：`run`（一次性）或 `session`（持久）。 + - 默认为 `run` + - 如果 `thread: true` 且省略 mode，OpenClaw 可能会根据运行时路径默认采用持久行为 - `mode: "session"` 需要 `thread: true` -- `cwd`（可选）：请求的运行时工作目录（由后端 / 运行时策略验证）。如果省略，则在已配置时，ACP 启动会继承目标智能体的工作区；缺失的继承路径会回退到后端默认值，而真实的访问错误会被返回。 -- `label`（可选）：面向操作人员的标签，用于会话 / 横幅文本。 -- `resumeSessionId`（可选）：恢复现有 ACP 会话，而不是创建新会话。智能体会通过 `session/load` 重放其对话历史。需要 `runtime: "acp"`。 -- `streamTo`（可选）：`"parent"` 将初始 ACP 运行的进度摘要以系统事件形式流式回传到请求方会话。 - - 在可用时，接受的响应中会包含 `streamLogPath`，指向一个按会话划分的 JSONL 日志（`.acp-stream.jsonl`），你可以对其执行 tail 以查看完整的转发历史。 -- `model`（可选）：为 ACP 子会话显式覆盖模型。对于 `runtime: "acp"`，该值会生效，因此子会话会使用请求的模型，而不是静默回退到目标智能体的默认模型。 +- `cwd`（可选）：请求的运行时工作目录（由后端 / 运行时策略验证）。若省略，在已配置时，ACP 启动会继承目标智能体的工作区；缺失的继承路径会回退到后端默认值，而真实的访问错误会直接返回。 +- `label`（可选）：用于会话 / 横幅文本中的面向运维者标签。 +- `resumeSessionId`（可选）：恢复现有 ACP 会话，而不是创建新会话。智能体会通过 `session/load` 重放其会话历史。需要 `runtime: "acp"`。 +- `streamTo`（可选）：`"parent"` 会将初始 ACP 运行进度摘要作为系统事件流回请求方会话。 + - 当可用时，接受的响应会包含指向会话范围 JSONL 日志（`.acp-stream.jsonl`）的 `streamLogPath`，你可以对其执行 tail 以查看完整转发历史。 +- `model`（可选）：ACP 子会话的显式模型覆盖。对于 `runtime: "acp"` 会生效，因此子会话会使用所请求的模型，而不是静默回退到目标智能体默认值。 -## 投递模型 +## 传递模型 -ACP 会话既可以是交互式工作区，也可以是由父级持有的后台工作。投递路径取决于其形态。 +ACP 会话既可以是交互式工作区，也可以是父级拥有的后台工作。传递路径取决于其形态。 ### 交互式 ACP 会话 交互式会话用于在可见的聊天界面中持续对话： -- `/acp spawn ... --bind here` 将当前对话绑定到 ACP 会话。 -- `/acp spawn ... --thread ...` 将一个渠道线程 / 话题绑定到 ACP 会话。 -- 持久化配置的 `bindings[].type="acp"` 会将匹配的对话路由到同一个 ACP 会话。 +- `/acp spawn ... --bind here` 将当前会话绑定到 ACP 会话。 +- `/acp spawn ... --thread ...` 将渠道线程 / 话题绑定到 ACP 会话。 +- 持久化配置的 `bindings[].type="acp"` 会将匹配的会话路由到同一个 ACP 会话。 -已绑定对话中的后续消息会直接路由到 ACP 会话，ACP 输出也会回传到同一个渠道 / 线程 / 话题。 +绑定会话中的后续消息会直接路由到 ACP 会话，ACP 输出也会回传到同一个渠道 / 线程 / 话题。 -### 父级持有的一次性 ACP 会话 +### 父级拥有的一次性 ACP 会话 -由另一个智能体运行启动的一次性 ACP 会话是后台子级，类似于子智能体： +由另一个智能体运行启动的一次性 ACP 会话属于后台子任务，类似子智能体： -- 父级通过 `sessions_spawn({ runtime: "acp", mode: "run" })` 请求执行工作。 -- 子级在自己的 ACP harness 会话中运行。 -- 完成结果通过内部任务完成通知路径回传。 -- 在需要面向用户的回复时，父级会以正常助手口吻改写子级结果。 +- 父级通过 `sessions_spawn({ runtime: "acp", mode: "run" })` 请求工作。 +- 子级在其自己的 ACP harness 会话中运行。 +- 完成后通过内部任务完成通知路径回报。 +- 当需要面向用户的回复时，父级会用正常的助手口吻改写子级结果。 -不要将这一路径视为父级和子级之间的点对点聊天。子级已经有一个回传给父级的完成通道。 +不要将这条路径视为父级与子级之间的点对点聊天。子级已经有一个回传给父级的完成通道。 -### `sessions_send` 与 A2A 投递 +### `sessions_send` 与 A2A 传递 -`sessions_send` 可以在启动后以另一个会话为目标。对于普通对等会话，在注入消息后，OpenClaw 会使用智能体到智能体（A2A）后续路径： +`session_spawn` 之后，`sessions_send` 可以将目标指向另一个会话。对于普通对等会话，在注入消息后，OpenClaw 会使用智能体到智能体（A2A）的后续路径： - 等待目标会话的回复 -- 可选地让请求方和目标交换有限轮次的后续消息 -- 要求目标生成一条 announce 消息 -- 将该 announce 投递到可见的渠道或线程 +- 可选地让请求方与目标交换有限轮数的后续消息 +- 要求目标生成一条通知消息 +- 将该通知投递到可见渠道或线程 -这条 A2A 路径是对等发送场景下的一种回退机制，用于发送方需要可见后续响应的情况。当某个无关会话在广泛的 `tools.sessions.visibility` 设置下能够查看并向 ACP 目标发送消息时，该机制仍会保持启用。 +对于发送方需要一个可见后续回复的对等发送，这条 A2A 路径是一种回退机制。当一个无关会话能够看到并向 ACP 目标发消息时，它仍然保持启用，例如在较宽泛的 `tools.sessions.visibility` 设置下。 -只有当请求方是其自身所拥有的、由父级持有的一次性 ACP 子级的父级时，OpenClaw 才会跳过 A2A 后续处理。在这种情况下，如果在任务完成机制之上再运行 A2A，可能会用子级结果唤醒父级，再把父级的回复转发回子级，从而形成父 / 子回声循环。对于这种自有子级情况，`sessions_send` 结果会报告 `delivery.status="skipped"`，因为结果已由完成路径负责处理。 +仅当请求方是其自身“父级拥有的一次性 ACP 子级”的父级时，OpenClaw 才会跳过 A2A 后续流程。在这种情况下，如果在任务完成之上再运行 A2A，可能会在子级结果到达时唤醒父级，再把父级的回复转发回子级，从而形成父 / 子回声循环。对于这种“自有子级”场景，`sessions_send` 结果会报告 `delivery.status="skipped"`，因为完成路径已经负责处理结果。 ### 恢复现有会话 -使用 `resumeSessionId` 可继续之前的 ACP 会话，而不是重新开始。智能体会通过 `session/load` 重放其对话历史，因此能带着之前的完整上下文继续进行。 +使用 `resumeSessionId` 可继续之前的 ACP 会话，而不是重新开始。智能体会通过 `session/load` 重放其会话历史，因此能够在完整保留先前上下文的基础上继续。 ```json { - "task": "从我们上次停下的地方继续——修复剩余的测试失败", + "task": "从我们上次停下的地方继续 —— 修复剩余的测试失败", "runtime": "acp", "agentId": "codex", "resumeSessionId": "" @@ -368,47 +370,47 @@ ACP 会话既可以是交互式工作区，也可以是由父级持有的后台 常见用例： -- 将一个 Codex 会话从你的笔记本交接到手机——告诉你的智能体从你上次停下的地方继续 -- 继续你之前在 CLI 中以交互方式启动、现在要通过智能体无头继续的编码会话 -- 接续因 Gateway 网关重启或空闲超时而中断的工作 +- 将 Codex 会话从你的笔记本电脑移交到手机 —— 告诉你的智能体从你上次停下的地方继续 +- 继续一个你最初在 CLI 中交互式启动、现在想通过智能体无头继续的编码会话 +- 继续因 Gateway 网关重启或空闲超时而中断的工作 说明： -- `resumeSessionId` 需要 `runtime: "acp"`——如果与子智能体运行时一起使用，会返回错误。 -- `resumeSessionId` 会恢复上游 ACP 对话历史；`thread` 和 `mode` 仍然会正常应用于你正在创建的新 OpenClaw 会话，因此 `mode: "session"` 仍然要求 `thread: true`。 +- `resumeSessionId` 需要 `runtime: "acp"` —— 如果与子智能体运行时一起使用，会返回错误。 +- `resumeSessionId` 会恢复上游 ACP 会话历史；`thread` 和 `mode` 仍会正常应用于你正在创建的新 OpenClaw 会话，因此 `mode: "session"` 仍然需要 `thread: true`。 - 目标智能体必须支持 `session/load`（Codex 和 Claude Code 支持）。 -- 如果找不到该会话 ID，启动将以明确错误失败——不会静默回退到新会话。 +- 如果找不到该会话 id，则启动会以清晰错误失败 —— 不会静默回退到新会话。 - + -Gateway 网关部署后，应运行一次实时端到端检查，而不是只依赖单元测试： +在 Gateway 网关部署后，请运行一次真实的端到端检查，而不是只依赖单元测试： -1. 验证目标主机上的已部署 Gateway 网关版本和提交。 -2. 打开一个指向实时智能体的临时 ACPX 桥接会话。 -3. 要求该智能体调用 `sessions_spawn`，并设置 `runtime: "acp"`、`agentId: "codex"`、`mode: "run"`，任务为 `Reply with exactly LIVE-ACP-SPAWN-OK`。 -4. 验证 `accepted=yes`、真实的 `childSessionKey`，且没有验证器错误。 +1. 在目标主机上验证已部署的 Gateway 网关版本和提交。 +2. 打开一个到实时智能体的临时 ACPX 桥接会话。 +3. 要求该智能体调用 `sessions_spawn`，并设置 `runtime: "acp"`、`agentId: "codex"`、`mode: "run"`，以及任务 `Reply with exactly LIVE-ACP-SPAWN-OK`。 +4. 验证 `accepted=yes`、存在真实的 `childSessionKey`，且没有验证器错误。 5. 清理该临时桥接会话。 -请将检查门槛保持在 `mode: "run"`，并跳过 `streamTo: "parent"`——绑定线程的 `mode: "session"` 和流式转发路径属于另外的、更丰富的集成验证。 +保持 gate 使用 `mode: "run"`，并跳过 `streamTo: "parent"` —— 线程绑定的 `mode: "session"` 和流转发路径属于另外更丰富的集成验证流程。 ## 沙箱兼容性 -ACP 会话当前在主机运行时上运行，而不是在 OpenClaw 沙箱内运行。 +ACP 会话当前运行在主机运行时上，而不是 OpenClaw 沙箱中。 当前限制： -- 如果请求方会话处于沙箱中，则 `sessions_spawn({ runtime: "acp" })` 和 `/acp spawn` 的 ACP 启动都会被阻止。 +- 如果请求方会话处于沙箱中，则对于 `sessions_spawn({ runtime: "acp" })` 和 `/acp spawn`，ACP 启动都会被阻止。 - 错误：`Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.` - 带有 `runtime: "acp"` 的 `sessions_spawn` 不支持 `sandbox: "require"`。 - 错误：`sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".` -当你需要由沙箱强制执行的运行时，请使用 `runtime: "subagent"`。 +当你需要由沙箱强制执行的运行环境时，请使用 `runtime: "subagent"`。 -### 从 `/acp` 命令 +### 从 `/acp` 命令启动 -在需要时，使用 `/acp spawn` 从聊天中进行显式的操作控制。 +在需要时，使用 `/acp spawn` 可从聊天中进行显式运维控制。 ```text /acp spawn codex --mode persistent --thread auto @@ -417,7 +419,7 @@ ACP 会话当前在主机运行时上运行，而不是在 OpenClaw 沙箱内运 /acp spawn codex --thread here ``` -关键标志： +关键 flag： - `--mode persistent|oneshot` - `--bind here|off` @@ -425,24 +427,24 @@ ACP 会话当前在主机运行时上运行，而不是在 OpenClaw 沙箱内运 - `--cwd ` - `--label ` -参见[斜杠命令](/zh-CN/tools/slash-commands)。 +参见 [斜杠命令](/zh-CN/tools/slash-commands)。 ## 会话目标解析 -大多数 `/acp` 操作都接受可选的会话目标（`session-key`、`session-id` 或 `session-label`）。 +大多数 `/acp` 操作都接受一个可选的会话目标（`session-key`、`session-id` 或 `session-label`）。 解析顺序： 1. 显式目标参数（或 `/acp steer` 的 `--session`） - - 先尝试键 - - 然后尝试 UUID 形式的会话 id - - 最后尝试标签 -2. 当前线程绑定（如果此对话 / 线程绑定到了 ACP 会话） + - 先尝试 key + - 然后尝试 UUID 形式的 session id + - 最后尝试 label +2. 当前线程绑定（如果此会话 / 线程已绑定到某个 ACP 会话） 3. 当前请求方会话回退 -当前对话绑定和线程绑定都会参与第 2 步。 +当前会话绑定和线程绑定都会参与第 2 步。 -如果无法解析出目标，OpenClaw 会返回明确错误（`Unable to resolve session target: ...`）。 +如果无法解析出目标，OpenClaw 会返回清晰错误（`Unable to resolve session target: ...`）。 ## 启动绑定模式 @@ -450,15 +452,15 @@ ACP 会话当前在主机运行时上运行，而不是在 OpenClaw 沙箱内运 | 模式 | 行为 | | ------ | ---------------------------------------------------------------------- | -| `here` | 在原位置绑定当前活动对话；如果没有活动对话则失败。 | -| `off` | 不创建当前对话绑定。 | +| `here` | 在原地绑定当前活动会话；如果当前没有活动会话则失败。 | +| `off` | 不创建当前会话绑定。 | 说明： -- `--bind here` 是“让这个渠道或聊天由 Codex 驱动”的最简单操作路径。 +- `--bind here` 是“让这个频道或聊天由 Codex 支持”的最简单运维路径。 - `--bind here` 不会创建子线程。 -- `--bind here` 仅适用于暴露当前对话绑定支持的渠道。 -- `--bind` 和 `--thread` 不能在同一个 `/acp spawn` 调用中组合使用。 +- `--bind here` 仅在暴露当前会话绑定支持的渠道上可用。 +- `--bind` 和 `--thread` 不能在同一次 `/acp spawn` 调用中同时使用。 ## 启动线程模式 @@ -466,57 +468,57 @@ ACP 会话当前在主机运行时上运行，而不是在 OpenClaw 沙箱内运 | 模式 | 行为 | | ------ | --------------------------------------------------------------------------------------------------- | -| `auto` | 如果当前在活动线程中：绑定该线程。如果当前不在线程中：在支持时创建 / 绑定一个子线程。 | +| `auto` | 若当前在活动线程中：绑定该线程。若不在线程中：在支持时创建 / 绑定一个子线程。 | | `here` | 要求当前必须处于活动线程中；否则失败。 | | `off` | 不绑定。会话以未绑定状态启动。 | 说明： - 在不支持线程绑定的界面上，默认行为实际上等同于 `off`。 -- 绑定线程的启动需要渠道策略支持： +- 线程绑定启动需要渠道策略支持： - Discord：`channels.discord.threadBindings.spawnAcpSessions=true` - Telegram：`channels.telegram.threadBindings.spawnAcpSessions=true` -- 当你想固定当前对话而不创建子线程时，请使用 `--bind here`。 +- 如果你想固定当前会话而不创建子线程，请使用 `--bind here`。 ## ACP 控制 | 命令 | 作用 | 示例 | | -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- | -| `/acp spawn` | 创建 ACP 会话；可选当前绑定或线程绑定。 | `/acp spawn codex --bind here --cwd /repo` | -| `/acp cancel` | 取消目标会话的进行中轮次。 | `/acp cancel agent:codex:acp:` | +| `/acp spawn` | 创建 ACP 会话；可选当前会话绑定或线程绑定。 | `/acp spawn codex --bind here --cwd /repo` | +| `/acp cancel` | 取消目标会话中正在进行的轮次。 | `/acp cancel agent:codex:acp:` | | `/acp steer` | 向运行中的会话发送引导指令。 | `/acp steer --session support inbox prioritize failing tests` | | `/acp close` | 关闭会话并解绑线程目标。 | `/acp close` | -| `/acp status` | 显示后端、模式、状态、运行时选项和能力。 | `/acp status` | -| `/acp set-mode` | 为目标会话设置运行时模式。 | `/acp set-mode plan` | -| `/acp set` | 通用运行时配置选项写入。 | `/acp set model openai/gpt-5.4` | -| `/acp cwd` | 设置运行时工作目录覆盖值。 | `/acp cwd /Users/user/Projects/repo` | +| `/acp status` | 显示后端、模式、状态、运行时选项和 capabilities。 | `/acp status` | +| `/acp set-mode` | 设置目标会话的运行时模式。 | `/acp set-mode plan` | +| `/acp set` | 通用运行时配置选项写入。 | `/acp set model openai/gpt-5.5` | +| `/acp cwd` | 设置运行时工作目录覆盖。 | `/acp cwd /Users/user/Projects/repo` | | `/acp permissions` | 设置审批策略配置文件。 | `/acp permissions strict` | | `/acp timeout` | 设置运行时超时（秒）。 | `/acp timeout 120` | -| `/acp model` | 设置运行时模型覆盖值。 | `/acp model anthropic/claude-opus-4-6` | -| `/acp reset-options` | 移除会话运行时选项覆盖值。 | `/acp reset-options` | +| `/acp model` | 设置运行时模型覆盖。 | `/acp model anthropic/claude-opus-4-6` | +| `/acp reset-options` | 移除会话运行时选项覆盖。 | `/acp reset-options` | | `/acp sessions` | 从存储中列出最近的 ACP 会话。 | `/acp sessions` | -| `/acp doctor` | 后端健康状态、能力、可执行修复。 | `/acp doctor` | -| `/acp install` | 输出确定性的安装与启用步骤。 | `/acp install` | +| `/acp doctor` | 后端健康状态、capabilities 和可执行修复。 | `/acp doctor` | +| `/acp install` | 打印确定性的安装和启用步骤。 | `/acp install` | -`/acp status` 会显示生效中的运行时选项，以及运行时级别和后端级别的会话标识符。当后端缺少某项能力时，不支持的控制错误会被清晰显示。`/acp sessions` 会读取当前已绑定会话或请求方会话的存储；目标令牌（`session-key`、`session-id` 或 `session-label`）会通过 Gateway 网关会话发现进行解析，包括每个智能体自定义的 `session.store` 根路径。 +`/acp status` 会显示生效中的运行时选项，以及运行时级别和后端级别的会话标识符。当某个后端缺少某项 capability 时，不支持控制的错误会清晰显示。`/acp sessions` 会读取当前绑定会话或请求方会话的存储；目标 token（`session-key`、`session-id` 或 `session-label`）会通过 Gateway 网关会话发现进行解析，包括每个智能体自定义的 `session.store` 根目录。 ## 运行时选项映射 -`/acp` 提供便捷命令和一个通用设置器。 +`/acp` 既有便捷命令，也有通用 setter。 等价操作： - `/acp model ` 映射到运行时配置键 `model`。 - `/acp permissions ` 映射到运行时配置键 `approval_policy`。 - `/acp timeout ` 映射到运行时配置键 `timeout`。 -- `/acp cwd ` 直接更新运行时 `cwd` 覆盖值。 +- `/acp cwd ` 直接更新运行时 `cwd` 覆盖。 - `/acp set ` 是通用路径。 - - 特例：`key=cwd` 使用 `cwd` 覆盖路径。 -- `/acp reset-options` 会清除目标会话的所有运行时覆盖值。 + - 特殊情况：`key=cwd` 使用 `cwd` 覆盖路径。 +- `/acp reset-options` 会清除目标会话的所有运行时覆盖。 -## acpx harness 支持（当前） +## `acpx` harness 支持（当前） -当前 acpx 内置 harness 别名： +当前 `acpx` 内置 harness 别名： - `claude` - `codex` @@ -533,10 +535,10 @@ ACP 会话当前在主机运行时上运行，而不是在 OpenClaw 沙箱内运 - `pi` - `qwen` -当 OpenClaw 使用 acpx 后端时，除非你的 acpx 配置定义了自定义智能体别名，否则应优先将这些值用于 `agentId`。 -如果你本地安装的 Cursor 仍然将 ACP 暴露为 `agent acp`，请在你的 acpx 配置中覆盖 `cursor` 智能体命令，而不是修改内置默认值。 +当 OpenClaw 使用 `acpx` 后端时，除非你的 `acpx` 配置定义了自定义智能体别名，否则应优先将这些值用作 `agentId`。 +如果你的本地 Cursor 安装仍然通过 `agent acp` 暴露 ACP，请在你的 `acpx` 配置中覆盖 `cursor` 智能体命令，而不是更改内置默认值。 -直接使用 acpx CLI 也可以通过 `--agent ` 指向任意适配器，但这个原始逃生口是 acpx CLI 的功能（不是常规的 OpenClaw `agentId` 路径）。 +直接使用 `acpx` CLI 也可以通过 `--agent ` 定向任意适配器，但这个原始逃生舱是 `acpx` CLI 功能（不是常规的 OpenClaw `agentId` 路径）。 ## 必需配置 @@ -546,7 +548,7 @@ ACP 会话当前在主机运行时上运行，而不是在 OpenClaw 沙箱内运 { acp: { enabled: true, - // 可选。默认值为 true；设为 false 可暂停 ACP 分发，同时保留 /acp 控制。 + // 可选。默认值为 true；设为 false 可在保留 /acp 控制的同时暂停 ACP 分发。 dispatch: { enabled: true }, backend: "acpx", defaultAgent: "codex", @@ -578,7 +580,7 @@ ACP 会话当前在主机运行时上运行，而不是在 OpenClaw 沙箱内运 } ``` -线程绑定配置取决于渠道适配器。以 Discord 为例： +线程绑定配置是渠道适配器特定的。以 Discord 为例： ```json5 { @@ -600,27 +602,27 @@ ACP 会话当前在主机运行时上运行，而不是在 OpenClaw 沙箱内运 } ``` -如果绑定线程的 ACP 启动无法工作，请先验证适配器功能标志： +如果线程绑定的 ACP 启动无法工作，请先验证适配器功能开关： - Discord：`channels.discord.threadBindings.spawnAcpSessions=true` -当前对话绑定不需要创建子线程。它们需要活动的对话上下文，以及一个暴露 ACP 对话绑定能力的渠道适配器。 +当前会话绑定不需要创建子线程。它们需要一个活动会话上下文，以及一个暴露 ACP 会话绑定能力的渠道适配器。 -参见[配置参考](/zh-CN/gateway/configuration-reference)。 +参见 [配置参考](/zh-CN/gateway/configuration-reference)。 -## acpx 后端的插件设置 +## `acpx` 后端的插件设置 全新安装默认启用内置的 `acpx` 运行时插件，因此 ACP 通常无需手动安装插件即可工作。 -先从以下命令开始： +先运行： ```text /acp doctor ``` -如果你禁用了 `acpx`、通过 `plugins.allow` / `plugins.deny` 拒绝了它，或想 -切换到本地开发检出版本，请使用显式插件路径： +如果你禁用了 `acpx`、通过 `plugins.allow` / `plugins.deny` 拒绝了它，或者想 +切换到本地开发 checkout，请使用显式插件路径： ```bash openclaw plugins install acpx @@ -639,11 +641,11 @@ openclaw plugins install ./path/to/local/acpx-plugin /acp doctor ``` -### acpx 命令和版本配置 +### `acpx` 命令和版本配置 -默认情况下，内置的 `acpx` 插件使用其插件本地固定的二进制文件（插件包内部的 `node_modules/.bin/acpx`）。启动时会先将该后端注册为未就绪状态，并由一个后台作业验证 `acpx --version`；如果二进制文件缺失或版本不匹配，它会运行 `npm install --omit=dev --no-save acpx@` 并再次验证。整个过程中，Gateway 网关始终保持非阻塞。 +默认情况下，内置的 `acpx` 插件使用其插件本地固定二进制文件（插件包内的 `node_modules/.bin/acpx`）。启动时会先将该后端注册为未就绪，随后后台任务会验证 `acpx --version`；如果二进制文件缺失或版本不匹配，它会运行 `npm install --omit=dev --no-save acpx@` 并重新验证。整个过程中 Gateway 网关保持非阻塞。 -可在插件配置中覆盖命令或版本： +在插件配置中覆盖命令或版本： ```json { @@ -665,13 +667,12 @@ openclaw plugins install ./path/to/local/acpx-plugin - `expectedVersion: "any"` 会禁用严格版本匹配。 - 自定义 `command` 路径会禁用插件本地自动安装。 -参见[插件](/zh-CN/tools/plugin)。 +参见 [插件](/zh-CN/tools/plugin)。 ### 自动依赖安装 -当你通过 `npm install -g openclaw` 全局安装 OpenClaw 时，acpx -运行时依赖（平台特定的二进制文件）会通过 postinstall 钩子自动安装。 -如果自动安装失败，Gateway 网关仍会正常启动， +当你通过 `npm install -g openclaw` 全局安装 OpenClaw 时，`acpx` +运行时依赖（平台特定二进制文件）会通过 postinstall hook 自动安装。如果自动安装失败，Gateway 网关仍会正常启动， 并通过 `openclaw acp doctor` 报告缺失的依赖。 ### 插件工具 MCP 桥接 @@ -679,129 +680,129 @@ openclaw plugins install ./path/to/local/acpx-plugin 默认情况下，ACPX 会话**不会**向 ACP harness 暴露 OpenClaw 插件注册的工具。 -如果你希望 Codex 或 Claude Code 等 ACP 智能体调用已安装的 -OpenClaw 插件工具，例如 memory recall/store，请启用专用桥接： +如果你希望 Codex 或 Claude Code 之类的 ACP 智能体能够调用已安装的 +OpenClaw 插件工具，例如记忆 recall / store，请启用专用桥接： ```bash openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true ``` -其作用： +这会执行以下操作： -- 在 ACPX 会话启动引导中注入一个名为 `openclaw-plugin-tools` 的内置 MCP 服务器。 -- 暴露已安装并启用的 OpenClaw - 插件中已经注册的插件工具。 +- 在 ACPX 会话引导期间注入一个名为 `openclaw-plugin-tools` 的内置 MCP 服务器。 +- 暴露已安装且已启用的 OpenClaw + 插件已注册的插件工具。 - 保持该功能为显式启用，且默认关闭。 安全与信任说明： -- 这会扩大 ACP harness 的工具暴露面。 -- ACP 智能体只能访问 Gateway 网关中已经激活的插件工具。 -- 请将其视为与允许这些插件在 - OpenClaw 自身内部执行相同的信任边界。 -- 启用前请检查已安装的插件。 +- 这会扩展 ACP harness 的工具面。 +- ACP 智能体只能访问 Gateway 网关中已激活的插件工具。 +- 应将其视为与允许这些插件在 + OpenClaw 自身中执行相同的信任边界。 +- 启用前请审查已安装插件。 -自定义 `mcpServers` 仍会像之前一样工作。内置的插件工具桥接是一个 -额外的按需启用便捷功能，而不是通用 MCP 服务器配置的替代品。 +自定义 `mcpServers` 仍按原样工作。内置的插件工具桥接只是一个 +额外的可选便捷功能，而不是通用 MCP 服务器配置的替代品。 ### OpenClaw 工具 MCP 桥接 默认情况下，ACPX 会话也**不会**通过 -MCP 暴露内置 OpenClaw 工具。当 ACP 智能体需要使用选定的 -内置工具（例如 `cron`）时，请启用单独的核心工具桥接： +MCP 暴露 OpenClaw 内置工具。当某个 ACP 智能体需要选定的 +内置工具（如 `cron`）时，请启用单独的核心工具桥接： ```bash openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true ``` -其作用： +这会执行以下操作： -- 在 ACPX 会话启动引导中注入一个名为 `openclaw-tools` 的内置 MCP 服务器。 -- 暴露选定的内置 OpenClaw 工具。初始服务器暴露 `cron`。 +- 在 ACPX 会话引导期间注入一个名为 `openclaw-tools` 的内置 MCP 服务器。 +- 暴露选定的 OpenClaw 内置工具。初始服务器会暴露 `cron`。 - 保持核心工具暴露为显式启用，且默认关闭。 ### 运行时超时配置 -内置的 `acpx` 插件默认将嵌入式运行时轮次设置为 120 秒 -超时。这为 Gemini CLI 等较慢的 harness 提供了足够时间来完成 +内置的 `acpx` 插件默认将嵌入式运行时轮次的超时时间设置为 120 秒。 +这为 Gemini CLI 等较慢的 harness 提供了足够时间来完成 ACP 启动和初始化。如果你的主机需要不同的 -运行时限制，可以覆盖该值： +运行时限制，可以覆盖它： ```bash openclaw config set plugins.entries.acpx.config.timeoutSeconds 180 ``` -更改此值后，重启 Gateway 网关。 +更改此值后请重启 Gateway 网关。 ### 健康探测智能体配置 -内置的 `acpx` 插件在判断嵌入式运行时后端是否就绪时， -会探测一个 harness 智能体。默认值是 `codex`。如果你的部署 +内置的 `acpx` 插件在判断嵌入式 +运行时后端是否就绪时，会探测一个 harness 智能体。默认使用 `codex`。如果你的部署 使用不同的默认 ACP 智能体，请将探测智能体设置为相同的 id： ```bash openclaw config set plugins.entries.acpx.config.probeAgent claude ``` -更改此值后，重启 Gateway 网关。 +更改此值后请重启 Gateway 网关。 ## 权限配置 -ACP 会话以非交互方式运行——没有 TTY 可用于批准或拒绝文件写入与 shell 执行权限提示。acpx 插件提供了两个配置键来控制权限处理方式： +ACP 会话以非交互方式运行 —— 没有 TTY 可用于批准或拒绝文件写入和 shell 执行权限提示。`acpx` 插件提供了两个配置键来控制权限处理方式： -这些 ACPX harness 权限与 OpenClaw 执行审批是分开的，也与 CLI 后端厂商绕过标志（例如 Claude CLI `--permission-mode bypassPermissions`）分开。ACPX 的 `approve-all` 是 ACP 会话在 harness 级别的紧急放行开关。 +这些 ACPX harness 权限独立于 OpenClaw exec 审批，也独立于 CLI 后端厂商绕过 flag，例如 Claude CLI `--permission-mode bypassPermissions`。ACPX `approve-all` 是 ACP 会话的 harness 级别紧急放行开关。 ### `permissionMode` -控制 harness 智能体可在不提示的情况下执行哪些操作。 +控制 harness 智能体无需提示即可执行哪些操作。 | 值 | 行为 | | --------------- | --------------------------------------------------------- | | `approve-all` | 自动批准所有文件写入和 shell 命令。 | -| `approve-reads` | 仅自动批准读取；写入和执行需要提示。 | +| `approve-reads` | 仅自动批准读取；写入和执行仍需要提示。 | | `deny-all` | 拒绝所有权限提示。 | ### `nonInteractivePermissions` -控制当本应显示权限提示、但没有可用的交互式 TTY 时会发生什么（对于 ACP 会话，这种情况始终成立）。 +控制当本应显示权限提示、但没有可交互 TTY 可用时会发生什么（ACP 会话始终如此）。 | 值 | 行为 | | ------ | ----------------------------------------------------------------- | -| `fail` | 以 `AcpRuntimeError` 中止会话。**（默认）** | -| `deny` | 静默拒绝该权限并继续（平滑降级）。 | +| `fail` | 使用 `AcpRuntimeError` 中止会话。**（默认）** | +| `deny` | 静默拒绝该权限并继续执行（优雅降级）。 | ### 配置 -通过插件配置进行设置： +通过插件配置设置： ```bash openclaw config set plugins.entries.acpx.config.permissionMode approve-all openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail ``` -更改这些值后，重启 Gateway 网关。 +更改这些值后请重启 Gateway 网关。 > **重要：** OpenClaw 当前默认使用 `permissionMode=approve-reads` 和 `nonInteractivePermissions=fail`。在非交互式 ACP 会话中，任何触发权限提示的写入或执行操作都可能因 `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` 而失败。 > -> 如果你需要限制权限，请将 `nonInteractivePermissions` 设置为 `deny`，这样会话会平滑降级，而不是直接崩溃。 +> 如果你需要限制权限，请将 `nonInteractivePermissions` 设置为 `deny`，这样会话会优雅降级，而不是直接崩溃。 ## 故障排除 | 症状 | 可能原因 | 修复方法 | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ACP runtime backend is not configured` | 后端插件缺失或被禁用。 | 安装并启用后端插件，然后运行 `/acp doctor`。 | -| `ACP is disabled by policy (acp.enabled=false)` | ACP 被全局禁用。 | 设置 `acp.enabled=true`。 | -| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | 来自普通线程消息的分发已禁用。 | 设置 `acp.dispatch.enabled=true`。 | +| `ACP runtime backend is not configured` | 后端插件缺失或已禁用。 | 安装并启用后端插件，然后运行 `/acp doctor`。 | +| `ACP is disabled by policy (acp.enabled=false)` | ACP 在全局范围内被禁用。 | 设置 `acp.enabled=true`。 | +| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | 来自普通线程消息的分发被禁用。 | 设置 `acp.dispatch.enabled=true`。 | | `ACP agent "" is not allowed by policy` | 智能体不在允许列表中。 | 使用允许的 `agentId`，或更新 `acp.allowedAgents`。 | -| `Unable to resolve session target: ...` | 键 / id / 标签令牌错误。 | 运行 `/acp sessions`，复制精确的键 / 标签后重试。 | -| `--bind here requires running /acp spawn inside an active ... conversation` | 在没有活动可绑定对话的情况下使用了 `--bind here`。 | 移动到目标聊天 / 渠道后重试，或使用不绑定的启动。 | -| `Conversation bindings are unavailable for .` | 适配器缺少当前对话 ACP 绑定能力。 | 在支持时使用 `/acp spawn ... --thread ...`，配置顶层 `bindings[]`，或切换到受支持的渠道。 | +| `Unable to resolve session target: ...` | key / id / label token 错误。 | 运行 `/acp sessions`，复制准确的 key / label，然后重试。 | +| `--bind here requires running /acp spawn inside an active ... conversation` | 在没有活动可绑定会话的情况下使用了 `--bind here`。 | 移动到目标聊天 / 频道后重试，或使用未绑定启动。 | +| `Conversation bindings are unavailable for .` | 适配器缺少当前会话 ACP 绑定 capability。 | 在支持时使用 `/acp spawn ... --thread ...`，配置顶层 `bindings[]`，或切换到受支持的渠道。 | | `--thread here requires running /acp spawn inside an active ... thread` | 在线程上下文之外使用了 `--thread here`。 | 移动到目标线程，或使用 `--thread auto` / `off`。 | -| `Only can rebind this channel/conversation/thread.` | 另一个用户拥有当前活动绑定目标。 | 由所有者重新绑定，或使用其他对话或线程。 | -| `Thread bindings are unavailable for .` | 适配器缺少线程绑定能力。 | 使用 `--thread off`，或切换到受支持的适配器 / 渠道。 | -| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP 运行时位于主机侧；请求方会话处于沙箱中。 | 从沙箱会话中使用 `runtime="subagent"`，或从非沙箱会话中运行 ACP 启动。 | -| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | 为 ACP 运行时请求了 `sandbox="require"`。 | 对强制沙箱隔离使用 `runtime="subagent"`，或从非沙箱会话中使用带 `sandbox="inherit"` 的 ACP。 | -| 绑定会话缺少 ACP 元数据 | ACP 会话元数据已过时 / 已删除。 | 使用 `/acp spawn` 重新创建，然后重新绑定 / 聚焦线程。 | -| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` 阻止了非交互式 ACP 会话中的写入 / 执行。 | 将 `plugins.entries.acpx.config.permissionMode` 设置为 `approve-all` 并重启 Gateway 网关。参见[权限配置](#permission-configuration)。 | -| ACP 会话很早失败且几乎没有输出 | 权限提示被 `permissionMode` / `nonInteractivePermissions` 阻止。 | 检查 Gateway 网关日志中的 `AcpRuntimeError`。如需完整权限，设置 `permissionMode=approve-all`；如需平滑降级，设置 `nonInteractivePermissions=deny`。 | -| ACP 会话在工作完成后无限期卡住 | harness 进程已完成，但 ACP 会话未报告完成。 | 使用 `ps aux \| grep acpx` 监控；手动杀掉陈旧进程。 | +| `Only can rebind this channel/conversation/thread.` | 另一个用户拥有当前活动绑定目标。 | 由所有者重新绑定，或使用其他会话或线程。 | +| `Thread bindings are unavailable for .` | 适配器缺少线程绑定 capability。 | 使用 `--thread off`，或切换到受支持的适配器 / 渠道。 | +| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP 运行时位于主机侧；请求方会话处于沙箱中。 | 在沙箱会话中使用 `runtime="subagent"`，或从非沙箱会话运行 ACP 启动。 | +| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | 为 ACP 运行时请求了 `sandbox="require"`。 | 对必须使用沙箱的场景使用 `runtime="subagent"`，或从非沙箱会话中使用带 `sandbox="inherit"` 的 ACP。 | +| 绑定会话缺少 ACP 元数据 | ACP 会话元数据已陈旧 / 被删除。 | 使用 `/acp spawn` 重新创建，然后重新绑定 / 聚焦线程。 | +| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` 在非交互式 ACP 会话中阻止了写入 / 执行。 | 将 `plugins.entries.acpx.config.permissionMode` 设置为 `approve-all` 并重启 Gateway 网关。参见[权限配置](#permission-configuration)。 | +| ACP 会话很早失败且几乎没有输出 | 权限提示被 `permissionMode` / `nonInteractivePermissions` 阻止。 | 检查 Gateway 网关日志中的 `AcpRuntimeError`。如需完整权限，请设置 `permissionMode=approve-all`；如需优雅降级，请设置 `nonInteractivePermissions=deny`。 | +| ACP 会话在完成工作后无限期停滞 | harness 进程已结束，但 ACP 会话未报告完成。 | 使用 `ps aux \| grep acpx` 监控；手动杀掉陈旧进程。 | diff --git a/docs/zh-CN/tools/exec.md b/docs/zh-CN/tools/exec.md index 7410ba226..ae4d14a3e 100644 --- a/docs/zh-CN/tools/exec.md +++ b/docs/zh-CN/tools/exec.md @@ -3,73 +3,74 @@ read_when: - 使用或修改 exec 工具 - 调试 stdin 或 TTY 行为 summary: Exec 工具用法、stdin 模式和 TTY 支持 -title: Exec Tool +title: Exec 工具 x-i18n: - generated_at: "2026-04-21T06:26:43Z" + generated_at: "2026-04-23T19:27:30Z" model: gpt-5.4 provider: openai - source_hash: 5018468f31bb76fc142ddef7002c7bbc617406de7ce912670d1b9edef6a9a042 + source_hash: f191380330a86f8f0c291cde65062fe4146f20e6a6bd2169e1439f2518cd5194 source_path: tools/exec.md workflow: 15 --- # Exec 工具 -在工作区中运行 shell 命令。通过 `process` 支持前台和后台执行。 -如果 `process` 不被允许，`exec` 会同步运行，并忽略 `yieldMs`/`background`。 -后台会话按智能体隔离；`process` 只能看到来自同一智能体的会话。 +在工作区中运行 shell 命令。通过 `process` 支持前台 + 后台执行。 +如果 `process` 被禁止，`exec` 会同步运行，并忽略 `yieldMs`/`background`。 +后台会话按智能体隔离；`process` 只能看到同一智能体的会话。 ## 参数 -- `command`（必需） -- `workdir`（默认为当前工作目录） +- `command`（必填） +- `workdir`（默认为 cwd） - `env`（键/值覆盖） - `yieldMs`（默认 10000）：延迟后自动转入后台 -- `background`（布尔值）：立即转入后台 +- `background`（bool）：立即转入后台 - `timeout`（秒，默认 1800）：到期后终止 -- `pty`（布尔值）：在可用时于伪终端中运行（仅限 TTY 的 CLI、编码智能体、终端 UI） +- `pty`（bool）：可用时在伪终端中运行（仅支持 TTY 的 CLI、编码智能体、终端 UI） - `host`（`auto | sandbox | gateway | node`）：执行位置 -- `security`（`deny | allowlist | full`）：`gateway`/`node` 的执行模式 +- `security`（`deny | allowlist | full`）：`gateway`/`node` 的强制执行模式 - `ask`（`off | on-miss | always`）：`gateway`/`node` 的审批提示 -- `node`（字符串）：用于 `host=node` 的节点 id/名称 -- `elevated`（布尔值）：请求提升模式（从沙箱逃逸到已配置的主机路径）；仅当 `elevated` 最终解析为 `full` 时，才会强制 `security=full` +- `node`（string）：`host=node` 时的节点 id/名称 +- `elevated`（bool）：请求提升模式（从沙箱逃逸到已配置的主机路径）；仅当 elevated 最终解析为 `full` 时，才会强制 `security=full` -注意： +说明： -- `host` 默认为 `auto`：当会话启用了沙箱运行时时使用 `sandbox`，否则使用 `gateway`。 -- `auto` 是默认路由策略，不是通配符。可以在单次调用中使用 `host=node`；只有在当前没有启用沙箱运行时时，才允许单次调用使用 `host=gateway`。 -- 在没有额外配置时，`host=auto` 依然可以“开箱即用”：没有沙箱时会解析为 `gateway`；有正在运行的沙箱时则保持在沙箱内。 -- `elevated` 会从沙箱逃逸到已配置的主机路径：默认是 `gateway`，或者当 `tools.exec.host=node`（或会话默认是 `host=node`）时为 `node`。只有在当前会话/提供商启用了提升访问时，这个选项才可用。 -- `gateway`/`node` 的审批由 `~/.openclaw/exec-approvals.json` 控制。 -- `node` 需要一个已配对的节点（配套应用或无头节点主机）。 -- 如果有多个可用节点，请设置 `exec.node` 或 `tools.exec.node` 进行选择。 +- `host` 默认是 `auto`：当会话启用了沙箱运行时时使用沙箱，否则使用 Gateway 网关。 +- `auto` 是默认路由策略，不是通配符。每次调用都允许从 `auto` 指定 `host=node`；只有在没有活动沙箱运行时时，才允许每次调用指定 `host=gateway`。 +- 在没有额外配置的情况下，`host=auto` 仍然可以“直接使用”：没有沙箱时会解析为 `gateway`；有活动沙箱时则会保留在沙箱中。 +- `elevated` 会从沙箱逃逸到已配置的主机路径：默认是 `gateway`，或者当 `tools.exec.host=node`（或会话默认是 `host=node`）时为 `node`。只有当前会话/提供商启用了提升访问时才可用。 +- `gateway`/`node` 审批由 `~/.openclaw/exec-approvals.json` 控制。 +- `node` 需要已配对的节点（配套应用或无头节点主机）。 +- 如果有多个节点可用，请设置 `exec.node` 或 `tools.exec.node` 进行选择。 - `exec host=node` 是节点上唯一的 shell 执行路径；旧版 `nodes.run` 包装器已移除。 -- 在非 Windows 主机上，exec 会优先使用已设置的 `SHELL`；如果 `SHELL` 是 `fish`，它会优先从 `PATH` 中选择 `bash`（或 `sh`），以避免不兼容 `fish` 的脚本，然后才会在两者都不存在时回退到 `SHELL`。 -- 在 Windows 主机上，exec 会优先发现 PowerShell 7（依次检查 Program Files、ProgramW6432，然后是 `PATH`），然后回退到 Windows PowerShell 5.1。 +- 在非 Windows 主机上，exec 会在设置了 `SHELL` 时使用它；如果 `SHELL` 是 `fish`，则会优先从 `PATH` 中选择 `bash`（或 `sh`）以避免与 fish 不兼容的脚本，然后在两者都不存在时回退到 `SHELL`。 +- 在 Windows 主机上，exec 会优先发现 PowerShell 7（依次检查 Program Files、ProgramW6432，然后是 PATH），然后回退到 Windows PowerShell 5.1。 - 主机执行（`gateway`/`node`）会拒绝 `env.PATH` 和加载器覆盖（`LD_*`/`DYLD_*`），以防止二进制劫持或注入代码。 -- OpenClaw 会在启动的命令环境中设置 `OPENCLAW_SHELL=exec`（包括 PTY 和沙箱执行），这样 shell/配置文件规则就可以检测到 exec 工具上下文。 -- 重要：沙箱隔离默认**关闭**。如果沙箱隔离关闭，隐式 `host=auto` 会解析为 `gateway`。显式 `host=sandbox` 仍会以安全关闭方式失败，而不是静默地在 gateway 主机上运行。请启用沙箱隔离，或结合审批使用 `host=gateway`。 -- 脚本预检（用于发现常见的 Python/Node shell 语法错误）只会检查位于有效 `workdir` 边界内的文件。如果某个脚本路径解析到 `workdir` 之外，则会跳过该文件的预检。 -- 对于现在开始的长时间运行任务，只需启动一次，并在启用了自动完成唤醒且命令有输出或失败时依赖自动唤醒即可。 - 对日志、状态、输入或人工干预，请使用 `process`；不要用 sleep 循环、timeout 循环或重复轮询来模拟调度。 -- 对于应稍后执行或按计划执行的任务，请使用 cron，而不是用 `exec` 的 sleep/延迟模式。 +- OpenClaw 会在派生命令环境中设置 `OPENCLAW_SHELL=exec`（包括 PTY 和沙箱执行），以便 shell/profile 规则检测 exec 工具上下文。 +- 重要：沙箱隔离**默认关闭**。如果沙箱隔离关闭，隐式 `host=auto` 会解析为 `gateway`。显式 `host=sandbox` 仍会以安全关闭方式失败，而不会悄悄在 Gateway 网关主机上运行。请启用沙箱隔离，或搭配审批使用 `host=gateway`。 +- 脚本预检（用于发现常见 Python/Node shell 语法错误）只会检查有效 `workdir` 边界内的文件。如果某个脚本路径解析到 `workdir` 之外，则会跳过该文件的预检。 +- 对于现在开始的长时间运行任务，请只启动一次，并在启用了自动完成唤醒且命令产生输出或失败时依赖自动完成唤醒。 + 使用 `process` 查看日志、状态、输入或进行干预；不要用 sleep 循环、timeout 循环或重复轮询来模拟调度。 +- 对于应稍后发生或按计划运行的任务，请使用 cron，而不是 + `exec` 的 sleep/delay 模式。 ## 配置 -- `tools.exec.notifyOnExit`（默认：true）：为 true 时，转入后台的 exec 会话在退出时会将系统事件加入队列并请求一次心跳。 -- `tools.exec.approvalRunningNoticeMs`（默认：10000）：当需要审批的 exec 运行时间超过该值时，发出一次“正在运行”通知（设为 0 则禁用）。 -- `tools.exec.host`（默认：`auto`；当沙箱运行时启用时解析为 `sandbox`，否则解析为 `gateway`） -- `tools.exec.security`（默认：沙箱为 `deny`，`gateway` 和 `node` 在未设置时为 `full`） +- `tools.exec.notifyOnExit`（默认：true）：为 true 时，转入后台的 exec 会话在退出时会将系统事件加入队列，并请求一次 heartbeat。 +- `tools.exec.approvalRunningNoticeMs`（默认：10000）：当需要审批的 exec 运行时间超过该值时，发出一条“running”通知（设为 0 可禁用）。 +- `tools.exec.host`（默认：`auto`；当沙箱运行时处于活动状态时解析为 `sandbox`，否则为 `gateway`） +- `tools.exec.security`（默认：对沙箱为 `deny`，对 gateway + node 在未设置时为 `full`） - `tools.exec.ask`（默认：`off`） -- 对 `gateway` 和 `node`，默认是无需审批的主机 exec。如果你想启用审批/allowlist 行为，请同时收紧 `tools.exec.*` 和主机上的 `~/.openclaw/exec-approvals.json`；参见 [Exec 审批](/zh-CN/tools/exec-approvals#no-approval-yolo-mode)。 -- YOLO 来自主机策略默认值（`security=full`、`ask=off`），而不是来自 `host=auto`。如果你想强制走 `gateway` 或 `node` 路由，请设置 `tools.exec.host` 或使用 `/exec host=...`。 -- 在 `security=full` 且 `ask=off` 模式下，主机 exec 会直接遵循已配置策略；不存在额外的启发式命令混淆预过滤器，也不存在额外的脚本预检拒绝层。 +- 无审批的主机 exec 是 gateway + node 的默认行为。如果你希望使用审批/allowlist 行为，请同时收紧 `tools.exec.*` 和主机上的 `~/.openclaw/exec-approvals.json`；参见 [Exec 审批](/zh-CN/tools/exec-approvals#no-approval-yolo-mode)。 +- YOLO 来源于主机策略默认值（`security=full`、`ask=off`），而不是 `host=auto`。如果你想强制使用 gateway 或 node 路由，请设置 `tools.exec.host` 或使用 `/exec host=...`。 +- 在 `security=full` 且 `ask=off` 模式下，主机 exec 会直接遵循已配置策略；不存在额外的启发式命令混淆预过滤器或脚本预检拒绝层。 - `tools.exec.node`（默认：未设置） -- `tools.exec.strictInlineEval`（默认：false）：为 true 时，内联解释器求值形式，如 `python -c`、`node -e`、`ruby -e`、`perl -e`、`php -r`、`lua -e` 和 `osascript -e`，始终需要显式审批。`allow-always` 仍可持久化允许无害的解释器/脚本调用，但内联求值形式每次仍会提示。 -- `tools.exec.pathPrepend`：在 exec 运行时添加到 `PATH` 前面的目录列表（仅 `gateway` 和 `sandbox`）。 -- `tools.exec.safeBins`：仅处理 stdin 的安全二进制文件，可在没有显式 allowlist 条目的情况下运行。行为详情见 [Safe bins](/zh-CN/tools/exec-approvals#safe-bins-stdin-only)。 -- `tools.exec.safeBinTrustedDirs`：用于 `safeBins` 路径检查的其他显式可信目录。`PATH` 条目永远不会自动视为可信。内置默认值是 `/bin` 和 `/usr/bin`。 -- `tools.exec.safeBinProfiles`：为自定义 safe bin 提供的可选自定义 argv 策略（`minPositional`、`maxPositional`、`allowedValueFlags`、`deniedFlags`）。 +- `tools.exec.strictInlineEval`（默认：false）：为 true 时，内联解释器求值形式，如 `python -c`、`node -e`、`ruby -e`、`perl -e`、`php -r`、`lua -e` 和 `osascript -e`，始终需要显式审批。`allow-always` 仍可持久信任良性的解释器/脚本调用，但内联求值形式每次仍会提示。 +- `tools.exec.pathPrepend`：在 exec 运行时添加到 `PATH` 前面的目录列表（仅 gateway + sandbox）。 +- `tools.exec.safeBins`：仅 stdin 的安全二进制，可在没有显式 allowlist 条目的情况下运行。行为细节参见 [Safe bins](/zh-CN/tools/exec-approvals#safe-bins-stdin-only)。 +- `tools.exec.safeBinTrustedDirs`：用于 `safeBins` 路径检查的额外显式受信任目录。`PATH` 条目永远不会自动受信任。内置默认值为 `/bin` 和 `/usr/bin`。 +- `tools.exec.safeBinProfiles`：按 safe bin 配置的可选自定义 argv 策略（`minPositional`、`maxPositional`、`allowedValueFlags`、`deniedFlags`）。 示例： @@ -85,12 +86,13 @@ x-i18n: ### PATH 处理 -- `host=gateway`：会将你的登录 shell `PATH` 合并到 exec 环境中。主机执行会拒绝 `env.PATH` 覆盖。守护进程本身仍使用最小化的 `PATH`： +- `host=gateway`：将你的 login-shell `PATH` 合并到 exec 环境中。主机执行会拒绝 `env.PATH` 覆盖。守护进程本身仍以最小 `PATH` 运行： - macOS：`/opt/homebrew/bin`、`/usr/local/bin`、`/usr/bin`、`/bin` - Linux：`/usr/local/bin`、`/usr/bin`、`/bin` -- `host=sandbox`：在容器内运行 `sh -lc`（登录 shell），因此 `/etc/profile` 可能会重置 `PATH`。 - OpenClaw 会在配置文件加载完成后通过内部环境变量把 `env.PATH` 追加到前面（不进行 shell 插值）；`tools.exec.pathPrepend` 也会在这里生效。 -- `host=node`：只会将你传入且未被阻止的环境变量覆盖发送到节点。主机执行会拒绝 `env.PATH` 覆盖，节点主机也会忽略它。如果你需要在节点上增加额外的 PATH 条目，请配置节点主机服务环境（systemd/launchd），或将工具安装到标准位置。 +- `host=sandbox`：在容器内运行 `sh -lc`（login shell），因此 `/etc/profile` 可能会重置 `PATH`。 + OpenClaw 会在 profile 加载后通过内部环境变量将 `env.PATH` 前置进去（不进行 shell 插值）； + `tools.exec.pathPrepend` 在这里也会生效。 +- `host=node`：只会将你传入的、未被阻止的环境变量覆盖发送到节点。主机执行会拒绝 `env.PATH` 覆盖，并且节点主机会忽略它。如果你需要在节点上增加 PATH 条目，请配置节点主机服务环境（systemd/launchd），或将工具安装到标准位置。 按智能体绑定节点（在配置中使用智能体列表索引）： @@ -99,12 +101,12 @@ openclaw config get agents.list openclaw config set agents.list[0].tools.exec.node "node-id-or-name" ``` -控制 UI：Nodes 选项卡包含一个小型的“Exec 节点绑定”面板，用于配置同样的设置。 +Control UI：Nodes 标签页中包含一个小型“Exec 节点绑定”面板，用于相同设置。 -## 会话级覆盖（`/exec`） +## 会话覆盖（`/exec`） -使用 `/exec` 为 `host`、`security`、`ask` 和 `node` 设置**每个会话**的默认值。 -发送不带参数的 `/exec` 可显示当前值。 +使用 `/exec` 为 `host`、`security`、`ask` 和 `node` 设置**按会话生效**的默认值。 +不带参数发送 `/exec` 可显示当前值。 示例： @@ -114,68 +116,69 @@ openclaw config set agents.list[0].tools.exec.node "node-id-or-name" ## 授权模型 -`/exec` 只对**已授权的发送者**生效（渠道 allowlist/配对 加上 `commands.useAccessGroups`）。 -它只会更新**会话状态**，不会写入配置。若要彻底禁用 exec，请通过工具策略拒绝它 -（`tools.deny: ["exec"]` 或按智能体设置）。除非你显式设置 `security=full` 和 `ask=off`，否则主机审批仍然适用。 +`/exec` 仅对**已授权发送者**生效（渠道 allowlist/配对加上 `commands.useAccessGroups`）。 +它只会更新**会话状态**，不会写入配置。若要彻底禁用 exec，请通过工具 +策略禁止它（`tools.deny: ["exec"]` 或按智能体配置）。 +除非你显式设置 `security=full` 和 `ask=off`，否则主机审批仍然适用。 ## Exec 审批（配套应用 / 节点主机） -沙箱隔离的智能体可以要求每次请求都先获得审批，之后才允许 `exec` 在 gateway 或节点主机上运行。 -关于策略、allowlist 和 UI 流程，请参见 [Exec 审批](/zh-CN/tools/exec-approvals)。 +沙箱隔离的智能体可以要求每次请求都先审批，然后才允许 `exec` 在 Gateway 网关或节点主机上运行。 +有关策略、allowlist 和 UI 流程，请参见 [Exec 审批](/zh-CN/tools/exec-approvals)。 当需要审批时，exec 工具会立即返回， -并带有 `status: "approval-pending"` 和一个审批 id。一旦获批（或被拒绝 / 超时）， +并带有 `status: "approval-pending"` 和一个审批 id。一旦审批通过（或被拒绝 / 超时）， Gateway 网关会发出系统事件（`Exec finished` / `Exec denied`）。如果命令在 -`tools.exec.approvalRunningNoticeMs` 之后仍在运行，则会发出一次 `Exec running` 通知。 -在原生支持审批卡片/按钮的渠道中，智能体应优先依赖该原生 UI， -只有当工具结果明确说明聊天审批不可用，或手动审批是唯一方式时， -才应附带手动 `/approve` 命令。 +`tools.exec.approvalRunningNoticeMs` 之后仍在运行，则会发出一条 `Exec running` 通知。 +在支持原生审批卡片/按钮的渠道上，智能体应优先依赖该 +原生 UI，只有在工具 +结果明确说明聊天审批不可用或手动审批是唯一途径时，才应包含手动 `/approve` 命令。 -## allowlist + safe bins +## Allowlist + safe bins -手动 allowlist 强制仅匹配**已解析的二进制路径**（不匹配 basename）。当 -`security=allowlist` 时，仅当管道中的每个片段都在 allowlist 中 -或属于 safe bin 时，shell 命令才会被自动允许。在 allowlist 模式下， -链式命令（`;`、`&&`、`||`）和重定向会被拒绝，除非每个顶层片段都满足 allowlist 要求 -（包括 safe bins）。重定向仍然不受支持。 -持久化的 `allow-always` 信任不会绕过这条规则：链式命令仍然要求每个 +手动 allowlist 强制执行仅匹配**解析后的二进制路径**（不匹配 basename）。当 +`security=allowlist` 时，只有当管道中的每一段都在 +allowlist 中或属于 safe bin，shell 命令才会被自动允许。链式命令（`;`、`&&`、`||`）和重定向在 +allowlist 模式下会被拒绝，除非每个顶层片段都满足 allowlist（包括 safe bins）。 +重定向仍然不受支持。 +持久化的 `allow-always` 信任也不能绕过该规则：链式命令仍要求每个 顶层片段都匹配。 -`autoAllowSkills` 是 exec 审批中的一条独立便捷路径。它不同于 -手动路径 allowlist 条目。若要实现严格的显式信任，请保持 -`autoAllowSkills` 为禁用状态。 +`autoAllowSkills` 是 exec 审批中的一个单独便捷路径。它与 +手动路径 allowlist 条目不同。若要进行严格的显式信任，请保持 `autoAllowSkills` 关闭。 -请将这两类控制分别用于不同目的： +这两组控制各有用途： -- `tools.exec.safeBins`：小型、仅处理 stdin 的流过滤器。 -- `tools.exec.safeBinTrustedDirs`：safe bin 可执行路径的显式额外可信目录。 +- `tools.exec.safeBins`：小型、仅 stdin 的流过滤器。 +- `tools.exec.safeBinTrustedDirs`：用于 safe-bin 可执行路径的显式额外受信任目录。 - `tools.exec.safeBinProfiles`：自定义 safe bin 的显式 argv 策略。 - allowlist：对可执行路径的显式信任。 -不要把 `safeBins` 当作通用 allowlist，也不要添加解释器/运行时二进制文件（例如 `python3`、`node`、`ruby`、`bash`）。如果你需要这些，请使用显式 allowlist 条目，并保持审批提示开启。 -如果解释器/运行时 `safeBins` 条目缺少显式 profile，`openclaw security audit` 会发出警告，而 `openclaw doctor --fix` 可以为缺失的自定义 `safeBinProfiles` 条目生成脚手架。 -如果你又把 `jq` 这类行为宽泛的二进制文件显式加回 `safeBins`，`openclaw security audit` 和 `openclaw doctor` 也会发出警告。 +不要将 `safeBins` 视为通用 allowlist，也不要添加解释器/运行时二进制（例如 `python3`、`node`、`ruby`、`bash`）。如果你需要这些，请使用显式 allowlist 条目，并保持启用审批提示。 +当解释器/运行时 `safeBins` 条目缺少显式 profile 时，`openclaw security audit` 会发出警告，而 `openclaw doctor --fix` 可以为缺失的自定义 `safeBinProfiles` 条目生成脚手架。 +当你显式将 `jq` 这类行为范围较广的二进制重新加入 `safeBins` 时，`openclaw security audit` 和 `openclaw doctor` 也会发出警告。 如果你显式将解释器加入 allowlist，请启用 `tools.exec.strictInlineEval`，这样内联代码求值形式仍然需要新的审批。 -完整策略细节和示例，请参见 [Exec 审批](/zh-CN/tools/exec-approvals#safe-bins-stdin-only) 和 [Safe bins 与 allowlist 的区别](/zh-CN/tools/exec-approvals#safe-bins-versus-allowlist)。 +有关完整策略细节和示例，请参见 [Exec 审批](/zh-CN/tools/exec-approvals#safe-bins-stdin-only) 和 [Safe bins 与 allowlist 的区别](/zh-CN/tools/exec-approvals#safe-bins-versus-allowlist)。 ## 示例 -前台运行： +前台： ```json { "tool": "exec", "command": "ls -la" } ``` -后台运行 + 轮询： +后台 + 轮询： ```json {"tool":"exec","command":"npm run build","yieldMs":1000} {"tool":"process","action":"poll","sessionId":""} ``` -轮询用于按需查看状态，不应用于等待循环。如果启用了自动完成唤醒， -当命令输出内容或失败时，它可以唤醒会话。 +轮询用于按需查看状态，而不是等待循环。 +如果启用了自动完成唤醒， +命令在产生输出或失败时可以唤醒会话。 发送按键（tmux 风格）： @@ -191,7 +194,7 @@ Gateway 网关会发出系统事件（`Exec finished` / `Exec denied`）。如 { "tool": "process", "action": "submit", "sessionId": "" } ``` -粘贴（默认带 bracketed paste）： +粘贴（默认带括号包装）： ```json { "tool": "process", "action": "paste", "sessionId": "", "text": "line1\nline2\n" } @@ -200,30 +203,29 @@ Gateway 网关会发出系统事件（`Exec finished` / `Exec denied`）。如 ## apply_patch `apply_patch` 是 `exec` 的一个子工具，用于结构化的多文件编辑。 -它默认对 OpenAI 和 OpenAI Codex 模型启用。只有在你想禁用它 -或将其限制为特定模型时，才需要使用配置： +它默认对 OpenAI 和 OpenAI Codex 模型启用。仅当你想禁用它或将其限制到特定模型时，才需要使用配置： ```json5 { tools: { exec: { - applyPatch: { workspaceOnly: true, allowModels: ["gpt-5.4"] }, + applyPatch: { workspaceOnly: true, allowModels: ["gpt-5.5"] }, }, }, } ``` -注意： +说明： -- 仅适用于 OpenAI/OpenAI Codex 模型。 +- 仅对 OpenAI/OpenAI Codex 模型可用。 - 工具策略仍然适用；`allow: ["write"]` 会隐式允许 `apply_patch`。 -- 配置位于 `tools.exec.applyPatch`。 -- `tools.exec.applyPatch.enabled` 默认值为 `true`；如需对 OpenAI 模型禁用该工具，请将其设为 `false`。 -- `tools.exec.applyPatch.workspaceOnly` 默认值为 `true`（限制在工作区内）。只有在你明确希望 `apply_patch` 在工作区目录之外写入/删除内容时，才应将其设为 `false`。 +- 配置位于 `tools.exec.applyPatch` 下。 +- `tools.exec.applyPatch.enabled` 默认值为 `true`；将其设为 `false` 可为 OpenAI 模型禁用该工具。 +- `tools.exec.applyPatch.workspaceOnly` 默认值为 `true`（限制在工作区内）。仅当你确实希望 `apply_patch` 在工作区目录之外写入/删除时，才应将其设为 `false`。 ## 相关内容 -- [Exec 审批](/zh-CN/tools/exec-approvals) — shell 命令的审批门控 -- [沙箱隔离](/zh-CN/gateway/sandboxing) — 在沙箱隔离环境中运行命令 -- [后台进程](/zh-CN/gateway/background-process) — 长时间运行的 exec 和 process 工具 -- [安全](/zh-CN/gateway/security) — 工具策略和提升访问权限 +- [Exec 审批](/zh-CN/tools/exec-approvals) —— shell 命令的审批门控 +- [沙箱隔离](/zh-CN/gateway/sandboxing) —— 在沙箱隔离环境中运行命令 +- [后台进程](/zh-CN/gateway/background-process) —— 长时间运行的 exec 和 process 工具 +- [安全性](/zh-CN/gateway/security) —— 工具策略和提升访问 diff --git a/docs/zh-CN/tools/llm-task.md b/docs/zh-CN/tools/llm-task.md index 3f30c27bf..fb3ba44f0 100644 --- a/docs/zh-CN/tools/llm-task.md +++ b/docs/zh-CN/tools/llm-task.md @@ -1,23 +1,23 @@ --- read_when: - - 你想在工作流中加入一个纯 JSON 的 LLM 步骤 - - 你需要用于自动化的、经过 schema 校验的 LLM 输出 -summary: 用于工作流的纯 JSON LLM 任务（可选插件工具） -title: LLM Task + - 你想在工作流中加入一个仅 JSON 的 LLM 步骤 + - 你需要用于自动化的经 schema 验证的 LLM 输出 +summary: 面向工作流的仅 JSON LLM 任务（可选插件工具） +title: LLM 任务 x-i18n: - generated_at: "2026-04-05T10:11:37Z" + generated_at: "2026-04-23T19:27:35Z" model: gpt-5.4 provider: openai - source_hash: cbe9b286a8e958494de06a59b6e7b750a82d492158df344c7afe30fce24f0584 + source_hash: 4234b2fd9247c06fcc481be6e3339726ebdb84891f4b8324f17e2d387dac4d8a source_path: tools/llm-task.md workflow: 15 --- -# LLM Task +# LLM 任务 -`llm-task` 是一个**可选插件工具**，用于运行纯 JSON 的 LLM 任务，并返回结构化输出（可选地依据 JSON Schema 进行校验）。 +`llm-task` 是一个**可选插件工具**，用于运行仅 JSON 的 LLM 任务，并返回结构化输出（可选地根据 JSON Schema 进行验证）。 -这非常适合 Lobster 这样的工作流引擎：你可以添加一个单独的 LLM 步骤，而无需为每个工作流编写自定义 OpenClaw 代码。 +这非常适合 Lobster 之类的工作流引擎：你可以添加一个单独的 LLM 步骤，而无需为每个工作流编写自定义 OpenClaw 代码。 ## 启用插件 @@ -58,9 +58,9 @@ x-i18n: "enabled": true, "config": { "defaultProvider": "openai-codex", - "defaultModel": "gpt-5.4", + "defaultModel": "gpt-5.5", "defaultAuthProfileId": "main", - "allowedModels": ["openai-codex/gpt-5.4"], + "allowedModels": ["openai-codex/gpt-5.5"], "maxTokens": 800, "timeoutMs": 30000 } @@ -70,7 +70,7 @@ x-i18n: } ``` -`allowedModels` 是 `provider/model` 字符串的 allowlist。如果设置了它，任何不在列表中的请求都会被拒绝。 +`allowedModels` 是由 `provider/model` 字符串组成的 allowlist。如果设置了它，则任何不在该列表中的请求都会被拒绝。 ## 工具参数 @@ -85,11 +85,11 @@ x-i18n: - `maxTokens`（数字，可选） - `timeoutMs`（数字，可选） -`thinking` 接受标准的 OpenClaw 推理预设，例如 `low` 或 `medium`。 +`thinking` 接受标准 OpenClaw 推理预设，例如 `low` 或 `medium`。 ## 输出 -返回包含已解析 JSON 的 `details.json`（如果提供了 `schema`，还会依据它进行校验）。 +返回 `details.json`，其中包含已解析的 JSON（若提供了 `schema`，还会对其进行验证）。 ## 示例：Lobster 工作流步骤 @@ -115,8 +115,7 @@ openclaw.invoke --tool llm-task --action json --args-json '{ ## 安全说明 -- 该工具是**纯 JSON** 的，并会指示模型只输出 JSON（不使用 - 代码围栏，不带说明文字）。 -- 在这次运行中，不会向模型暴露任何工具。 -- 除非你使用 `schema` 进行校验，否则应将输出视为不可信。 -- 在任何会产生副作用的步骤（发送、发布、exec）之前先设置审批。 +- 该工具是**仅 JSON** 的，并会指示模型只输出 JSON（不包含代码围栏，也不包含说明性文字）。 +- 本次运行不会向模型暴露任何工具。 +- 除非你使用 `schema` 进行验证，否则应将输出视为不受信任。 +- 在任何有副作用的步骤（send、post、exec）之前放置审批。 diff --git a/docs/zh-CN/tools/multi-agent-sandbox-tools.md b/docs/zh-CN/tools/multi-agent-sandbox-tools.md index 34bfeb4ac..3015dd6b6 100644 --- a/docs/zh-CN/tools/multi-agent-sandbox-tools.md +++ b/docs/zh-CN/tools/multi-agent-sandbox-tools.md @@ -1,37 +1,36 @@ --- read_when: “You want per-agent sandboxing or per-agent tool allow/deny policies in a multi-agent gateway.” status: active -summary: “按智能体的沙箱隔离 + 工具限制、优先级和示例” +summary: “每智能体沙箱隔离 + 工具限制、优先级和示例” title: 多智能体沙箱隔离与工具 x-i18n: - generated_at: "2026-04-05T10:12:15Z" + generated_at: "2026-04-23T19:27:35Z" model: gpt-5.4 provider: openai - source_hash: 07985f7c8fae860a7b9bf685904903a4a8f90249e95e4179cf0775a1208c0597 + source_hash: dff5be3e06ca4701adb078cd8ab2eb36a66b0c705e1ab34a4ae470399cde93e5 source_path: tools/multi-agent-sandbox-tools.md workflow: 15 --- # 多智能体沙箱隔离与工具配置 -在多智能体设置中，每个智能体都可以覆盖全局沙箱隔离和工具 -策略。本页介绍按智能体的配置、优先级规则以及 -示例。 +在多智能体设置中，每个智能体都可以覆盖全局沙箱隔离和工具策略。 +本页介绍每智能体配置、优先级规则和示例。 -- **沙箱后端和模式**：参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 +- **沙箱后端与模式**：参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 - **调试被阻止的工具**：参见 [沙箱 vs 工具策略 vs Elevated](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated) 和 `openclaw sandbox explain`。 -- **Elevated exec**：参见 [Elevated Mode](/zh-CN/tools/elevated)。 +- **Elevated exec**：参见 [Elevated 模式](/zh-CN/tools/elevated)。 -认证是按智能体划分的：每个智能体都从自己的 `agentDir` 认证存储读取， +认证按智能体隔离：每个智能体都会从其自身 `agentDir` 下的认证存储读取， 路径为 `~/.openclaw/agents//agent/auth-profiles.json`。 -凭据**不会**在智能体之间共享。绝不要在多个智能体之间复用 `agentDir`。 -如果你想共享凭据，请将 `auth-profiles.json` 复制到另一个智能体的 `agentDir` 中。 +凭证**不会**在智能体之间共享。绝不要在多个智能体之间复用 `agentDir`。 +如果你想共享凭证，请将 `auth-profiles.json` 复制到另一个智能体的 `agentDir` 中。 --- ## 配置示例 -### 示例 1：个人智能体 + 受限家庭智能体 +### 示例 1：个人 + 受限家庭智能体 ```json { @@ -77,8 +76,8 @@ x-i18n: **结果：** -- `main` 智能体：在主机上运行，具有完整工具访问权限 -- `family` 智能体：在 Docker 中运行（每个智能体一个容器），仅有 `read` 工具 +- `main` 智能体：在主机上运行，拥有完整工具访问权限 +- `family` 智能体：在 Docker 中运行（每个智能体一个容器），仅可使用 `read` 工具 --- @@ -113,7 +112,7 @@ x-i18n: --- -### 示例 2b：全局 coding 配置 + 仅限消息的智能体 +### 示例 2b：全局 coding 配置 + 仅消息智能体 ```json { @@ -131,8 +130,8 @@ x-i18n: **结果：** -- 默认智能体会获得 coding 工具 -- `support` 智能体仅限消息功能（+ Slack 工具） +- 默认智能体获得 coding 工具 +- `support` 智能体仅可使用消息工具（+ Slack 工具） --- @@ -152,14 +151,14 @@ x-i18n: "id": "main", "workspace": "~/.openclaw/workspace", "sandbox": { - "mode": "off" // 覆盖：main 永不使用沙箱 + "mode": "off" // 覆盖：main 永不进入沙箱 } }, { "id": "public", "workspace": "~/.openclaw/workspace-public", "sandbox": { - "mode": "all", // 覆盖：public 始终使用沙箱 + "mode": "all", // 覆盖：public 始终进入沙箱 "scope": "agent" }, "tools": { @@ -176,11 +175,11 @@ x-i18n: ## 配置优先级 -当同时存在全局（`agents.defaults.*`）和按智能体（`agents.list[].*`）配置时： +当全局（`agents.defaults.*`）和智能体专属（`agents.list[].*`）配置同时存在时： ### 沙箱配置 -按智能体设置会覆盖全局设置： +智能体专属设置会覆盖全局设置： ``` agents.list[].sandbox.mode > agents.defaults.sandbox.mode @@ -194,29 +193,29 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.* **说明：** -- 对于该智能体，`agents.list[].sandbox.{docker,browser,prune}.*` 会覆盖 `agents.defaults.sandbox.{docker,browser,prune}.*`（当沙箱范围解析为 `"shared"` 时会被忽略）。 +- 对于该智能体，`agents.list[].sandbox.{docker,browser,prune}.*` 会覆盖 `agents.defaults.sandbox.{docker,browser,prune}.*`（当沙箱 scope 解析为 `"shared"` 时会被忽略）。 ### 工具限制 -过滤顺序为： +过滤顺序如下： -1. **工具 profile**（`tools.profile` 或 `agents.list[].tools.profile`） -2. **提供商工具 profile**（`tools.byProvider[provider].profile` 或 `agents.list[].tools.byProvider[provider].profile`） +1. **工具配置**（`tools.profile` 或 `agents.list[].tools.profile`） +2. **provider 工具配置**（`tools.byProvider[provider].profile` 或 `agents.list[].tools.byProvider[provider].profile`） 3. **全局工具策略**（`tools.allow` / `tools.deny`） -4. **提供商工具策略**（`tools.byProvider[provider].allow/deny`） -5. **按智能体的工具策略**（`agents.list[].tools.allow/deny`） -6. **智能体提供商策略**（`agents.list[].tools.byProvider[provider].allow/deny`） +4. **provider 工具策略**（`tools.byProvider[provider].allow/deny`） +5. **智能体专属工具策略**（`agents.list[].tools.allow/deny`） +6. **智能体 provider 策略**（`agents.list[].tools.byProvider[provider].allow/deny`） 7. **沙箱工具策略**（`tools.sandbox.tools` 或 `agents.list[].tools.sandbox.tools`） -8. **Subagent 工具策略**（`tools.subagents.tools`，如果适用） +8. **子智能体工具策略**（`tools.subagents.tools`，如果适用） -每一层都可以进一步限制工具，但不能重新授予之前层级已拒绝的工具。 -如果设置了 `agents.list[].tools.sandbox.tools`，它会替换该智能体的 `tools.sandbox.tools`。 -如果设置了 `agents.list[].tools.profile`，它会覆盖该智能体的 `tools.profile`。 -提供商工具键可以接受 `provider`（例如 `google-antigravity`）或 `provider/model`（例如 `openai/gpt-5.4`）。 +每一层都可以进一步限制工具，但不能重新授予前面层级已经拒绝的工具。 +如果设置了 `agents.list[].tools.sandbox.tools`，则它会替换该智能体的 `tools.sandbox.tools`。 +如果设置了 `agents.list[].tools.profile`，则它会覆盖该智能体的 `tools.profile`。 +provider 工具键既接受 `provider`（例如 `google-antigravity`），也接受 `provider/model`（例如 `openai/gpt-5.5`）。 -工具策略支持 `group:*` 简写，可展开为多个工具。完整列表参见 [工具组](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated#tool-groups-shorthands)。 +工具策略支持 `group:*` 简写，可展开为多个工具。完整列表请参见 [工具分组](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated#tool-groups-shorthands)。 -按智能体的 Elevated 覆盖（`agents.list[].tools.elevated`）还可以进一步限制特定智能体的 elevated exec。详情参见 [Elevated Mode](/zh-CN/tools/elevated)。 +每智能体 elevated 覆盖（`agents.list[].tools.elevated`）还可以进一步限制特定智能体的 elevated exec。详情请参见 [Elevated 模式](/zh-CN/tools/elevated)。 --- @@ -245,7 +244,7 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.* } ``` -**之后（具有不同配置的多智能体）：** +**之后（使用不同配置的多智能体）：** ```json { @@ -262,7 +261,7 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.* } ``` -旧版 `agent.*` 配置会由 `openclaw doctor` 迁移；今后请优先使用 `agents.defaults` + `agents.list`。 +旧版 `agent.*` 配置可由 `openclaw doctor` 迁移；今后请优先使用 `agents.defaults` + `agents.list`。 --- @@ -279,7 +278,7 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.* } ``` -### 安全执行智能体（不允许文件修改） +### 安全执行智能体（不允许修改文件） ```json { @@ -302,22 +301,22 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.* } ``` -此配置中的 `sessions_history` 仍然返回有界、已净化的 recall -视图，而不是原始 transcript 倾倒。助手 recall 会剥离 thinking 标签、 -`` 脚手架、纯文本工具调用 XML 载荷 +此配置中的 `sessions_history` 仍然返回有界、已净化的回忆视图， +而不是原始转录转储。助手回忆会去除 thinking 标签、 +`` 脚手架、纯文本工具调用 XML 负载 （包括 `...`、 `...`、`...`、 `...` 以及被截断的工具调用块）、 -降级后的工具调用脚手架、泄露的 ASCII/全角模型控制 -token，以及格式错误的 MiniMax 工具调用 XML，然后才进行脱敏/截断。 +降级后的工具调用脚手架、泄露的 ASCII/全角模型控制 token， +以及格式错误的 MiniMax 工具调用 XML，然后再执行脱敏/截断。 --- ## 常见陷阱：“non-main” -`agents.defaults.sandbox.mode: "non-main"` 基于 `session.mainKey`（默认值为 `"main"`）， -而不是智能体 id。群组/渠道会话始终拥有自己的 key，因此它们 -会被视为 non-main，并进入沙箱。如果你希望某个智能体永不进入 +`agents.defaults.sandbox.mode: "non-main"` 基于 `session.mainKey`（默认 `"main"`）， +而不是智能体 ID。群组/渠道会话始终拥有自己的键，因此它们 +会被视为非 main，并会进入沙箱。如果你希望某个智能体永不进入 沙箱，请设置 `agents.list[].sandbox.mode: "off"`。 --- @@ -352,29 +351,29 @@ token，以及格式错误的 MiniMax 工具调用 XML，然后才进行脱敏/ ## 故障排除 -### 尽管设置了 `mode: "all"`，智能体仍未进入沙箱 +### 尽管设置了 `mode: "all"`，智能体却没有进入沙箱 -- 检查是否存在覆盖它的全局 `agents.defaults.sandbox.mode` -- 按智能体配置优先级更高，因此请设置 `agents.list[].sandbox.mode: "all"` +- 检查是否存在会覆盖它的全局 `agents.defaults.sandbox.mode` +- 智能体专属配置优先级更高，因此请设置 `agents.list[].sandbox.mode: "all"` -### 尽管在拒绝列表中，工具仍然可用 +### 尽管在 deny 列表中，工具仍然可用 -- 检查工具过滤顺序：全局 → 智能体 → 沙箱 → subagent -- 每一层只能进一步限制，不能重新授予 +- 检查工具过滤顺序：全局 → 智能体 → 沙箱 → 子智能体 +- 每一层都只能进一步限制，不能重新授予 - 通过日志验证：`[tools] filtering tools for agent:${agentId}` ### 容器没有按智能体隔离 -- 在按智能体的沙箱配置中设置 `scope: "agent"` -- 默认值是 `"session"`，这会为每个会话创建一个容器 +- 在智能体专属沙箱配置中设置 `scope: "agent"` +- 默认值是 `"session"`，即每个会话创建一个容器 --- -## 另见 +## 另请参见 -- [沙箱隔离](/zh-CN/gateway/sandboxing) -- 完整的沙箱参考（模式、范围、后端、镜像） +- [沙箱隔离](/zh-CN/gateway/sandboxing) -- 完整沙箱参考（模式、scope、后端、镜像） - [沙箱 vs 工具策略 vs Elevated](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated) -- 调试“为什么这个被阻止了？” -- [Elevated Mode](/zh-CN/tools/elevated) +- [Elevated 模式](/zh-CN/tools/elevated) - [多智能体路由](/zh-CN/concepts/multi-agent) - [沙箱配置](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox) - [会话管理](/zh-CN/concepts/session) diff --git a/docs/zh-CN/tools/slash-commands.md b/docs/zh-CN/tools/slash-commands.md index 183f6a52d..a0f1912f1 100644 --- a/docs/zh-CN/tools/slash-commands.md +++ b/docs/zh-CN/tools/slash-commands.md @@ -5,31 +5,31 @@ read_when: summary: 斜杠命令：文本与原生、配置以及支持的命令 title: 斜杠命令 x-i18n: - generated_at: "2026-04-23T12:50:41Z" + generated_at: "2026-04-23T19:28:04Z" model: gpt-5.4 provider: openai - source_hash: 13290dcdf649ae66603a92a0aca68460bb63ff476179cc2dded796aaa841d66c + source_hash: 62af79d351db2ef6a62df570300bb191c7d5078ef5da2308b4a9d99a56ca7863 source_path: tools/slash-commands.md workflow: 15 --- # 斜杠命令 -命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。 -仅主机可用的 bash 聊天命令使用 `! `（`/bash ` 是别名）。 +命令由 Gateway 网关处理。大多数命令必须作为**独立**消息发送，并且以 `/` 开头。 +仅主机可用的 bash 聊天命令使用 `! `（`/bash ` 是其别名）。 这里有两个相关系统： - **命令**：独立的 `/...` 消息。 - **指令**：`/think`、`/fast`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/exec`、`/model`、`/queue`。 - - 指令会在模型看到消息之前从消息中剥离。 - - 在普通聊天消息中（不是仅含指令的消息），它们会被视为“内联提示”，且**不会**持久化会话设置。 - - 在仅含指令的消息中（消息只包含指令），它们会持久化到会话，并回复一条确认信息。 - - 指令只会对**已授权发送者**生效。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则授权来自渠道允许列表/配对以及 `commands.useAccessGroups`。 - 未授权发送者看到的指令会被当作普通文本处理。 + - 指令会在模型看到消息前被剥离。 + - 在普通聊天消息中（不是仅包含指令的消息），它们会被视为“内联提示”，并且**不会**持久化会话设置。 + - 在仅包含指令的消息中（消息只包含指令），它们会持久化到会话中，并回复一个确认消息。 + - 指令仅对**已授权发送者**生效。如果设置了 `commands.allowFrom`，它就是唯一使用的 allowlist；否则，授权来自渠道 allowlist/配对以及 `commands.useAccessGroups`。 + 未授权发送者发送的指令会被当作普通文本处理。 -还有一些**内联快捷方式**（仅限允许列表内/已授权发送者）：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 -它们会立即运行，在模型看到消息之前被剥离，剩余文本则继续走正常流程。 +还有少量**内联快捷命令**（仅限 allowlist/已授权发送者）：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 +它们会立即运行，并在模型看到消息前被剥离，剩余文本继续走正常流程。 ## 配置 @@ -59,86 +59,86 @@ x-i18n: ``` - `commands.text`（默认 `true`）启用在聊天消息中解析 `/...`。 - - 在没有原生命令的界面上（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams），即使你将其设为 `false`，文本命令仍然可用。 + - 在不支持原生命令的界面上（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams），即使你将其设为 `false`，文本命令仍然可用。 - `commands.native`（默认 `"auto"`）注册原生命令。 - - 自动：对 Discord/Telegram 开启；对 Slack 关闭（直到你添加斜杠命令）；对不支持原生能力的提供商忽略。 + - 自动：在 Discord/Telegram 上开启；在 Slack 上关闭（直到你添加 slash commands）；对于不支持原生命令的提供商则忽略。 - 设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。 - - `false` 会在启动时清除 Discord/Telegram 上此前已注册的命令。Slack 命令在 Slack 应用中管理，不会被自动移除。 -- `commands.nativeSkills`（默认 `"auto"`）会在支持时以原生方式注册 **skill** 命令。 - - 自动：对 Discord/Telegram 开启；对 Slack 关闭（Slack 需要为每个 skill 创建一个斜杠命令）。 + - `false` 会在启动时清除之前在 Discord/Telegram 上注册的命令。Slack 命令由 Slack 应用管理，不会自动移除。 +- `commands.nativeSkills`（默认 `"auto"`）在支持时以原生方式注册**技能**命令。 + - 自动：在 Discord/Telegram 上开启；在 Slack 上关闭（Slack 需要为每个技能单独创建一个 slash 命令）。 - 设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。 -- `commands.bash`（默认 `false`）启用 `! ` 来运行主机 shell 命令（`/bash ` 是别名；需要 `tools.elevated` 允许列表）。 +- `commands.bash`（默认 `false`）启用 `! ` 来运行主机 shell 命令（`/bash ` 是别名；需要 `tools.elevated` allowlist）。 - `commands.bashForegroundMs`（默认 `2000`）控制 bash 在切换到后台模式前等待多久（`0` 表示立即转入后台）。 - `commands.config`（默认 `false`）启用 `/config`（读取/写入 `openclaw.json`）。 -- `commands.mcp`（默认 `false`）启用 `/mcp`（读取/写入由 OpenClaw 管理的 `mcp.servers` 下的 MCP 配置）。 -- `commands.plugins`（默认 `false`）启用 `/plugins`（plugin 发现/状态，以及安装 + 启用/禁用控制）。 +- `commands.mcp`（默认 `false`）启用 `/mcp`（读取/写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 配置）。 +- `commands.plugins`（默认 `false`）启用 `/plugins`（插件发现/状态，以及安装 + 启用/禁用控制）。 - `commands.debug`（默认 `false`）启用 `/debug`（仅运行时覆盖）。 - `commands.restart`（默认 `true`）启用 `/restart` 以及 Gateway 网关重启工具操作。 -- `commands.ownerAllowFrom`（可选）设置仅限 owner 的命令/工具界面的显式 owner 允许列表。这与 `commands.allowFrom` 分开。 -- 每个渠道的 `channels..commands.enforceOwnerForCommands`（可选，默认 `false`）会让仅限 owner 的命令在该界面上要求**owner 身份**才能运行。设为 `true` 时，发送者必须匹配已解析的 owner 候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生 owner 元数据），或者在内部消息渠道上拥有内部 `operator.admin` 范围。渠道 `allowFrom` 中的通配符条目，或空的/无法解析的 owner 候选列表，**都不足够**——该渠道上的仅限 owner 命令会以默认拒绝方式失败。如果你希望仅限 owner 的命令只由 `ownerAllowFrom` 和标准命令允许列表控制，请保持关闭。 -- `commands.ownerDisplay` 控制 owner id 在系统提示中的显示方式：`raw` 或 `hash`。 -- `commands.ownerDisplaySecret` 可选地设置在 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。 -- `commands.allowFrom`（可选）设置用于命令授权的按提供商区分的允许列表。配置后，它会成为命令和指令的唯一授权来源（渠道允许列表/配对以及 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；提供商专用键会覆盖它。 -- `commands.useAccessGroups`（默认 `true`）在未设置 `commands.allowFrom` 时，对命令执行允许列表/策略。 +- `commands.ownerAllowFrom`（可选）为仅限 owner 的命令/工具界面设置显式 owner allowlist。这与 `commands.allowFrom` 分开。 +- 每个渠道的 `channels..commands.enforceOwnerForCommands`（可选，默认 `false`）会使该界面上的仅限 owner 命令必须由**owner 身份**执行。当其为 `true` 时，发送者必须匹配某个已解析的 owner 候选者（例如 `commands.ownerAllowFrom` 中的某个条目，或提供商原生 owner 元数据），或者在内部消息渠道上持有内部 `operator.admin` 范围。渠道 `allowFrom` 中的通配符条目，或空的/无法解析的 owner 候选列表，**都不足以**满足要求——该渠道上的仅限 owner 命令会以封闭方式失败。如果你希望仅限 owner 的命令只由 `ownerAllowFrom` 和标准命令 allowlist 控制，请保持关闭。 +- `commands.ownerDisplay` 控制 owner id 在系统提示词中的显示方式：`raw` 或 `hash`。 +- `commands.ownerDisplaySecret` 可选设置在 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。 +- `commands.allowFrom`（可选）为命令授权设置按提供商划分的 allowlist。配置后，它将成为命令和指令的唯一授权来源（渠道 allowlist/配对及 `commands.useAccessGroups` 将被忽略）。全局默认值使用 `"*"`；提供商专用键会覆盖它。 +- `commands.useAccessGroups`（默认 `true`）在未设置 `commands.allowFrom` 时，对命令强制执行 allowlist/策略。 ## 命令列表 -当前的事实来源： +当前事实来源： - 核心内置命令来自 `src/auto-reply/commands-registry.shared.ts` - 生成的 dock 命令来自 `src/auto-reply/commands-registry.data.ts` -- plugin 命令来自 plugin 的 `registerCommand()` 调用 -- 你的 Gateway 网关上的实际可用性仍取决于配置标志、渠道界面，以及已安装/已启用的 plugin +- 插件命令来自插件中的 `registerCommand()` 调用 +- 你的 Gateway 网关上实际可用的命令仍取决于配置标志、渠道界面，以及已安装/启用的插件 ### 核心内置命令 当前可用的内置命令： - `/new [model]` 启动一个新会话；`/reset` 是重置别名。 -- `/reset soft [message]` 保留当前转录内容，丢弃复用的 CLI 后端会话 id，并原地重新运行启动/系统提示加载。 +- `/reset soft [message]` 保留当前转录，丢弃复用的 CLI 后端会话 id，并原地重新运行 startup/system-prompt 加载。 - `/compact [instructions]` 压缩会话上下文。参见 [/concepts/compaction](/zh-CN/concepts/compaction)。 - `/stop` 中止当前运行。 -- `/session idle ` 和 `/session max-age ` 管理线程绑定过期时间。 -- `/think ` 设置思考级别。可选项来自当前模型的活跃提供商配置文件；常见级别有 `off`、`minimal`、`low`、`medium` 和 `high`，也可能包含 `xhigh`、`adaptive`、`max` 或仅在支持时提供的二元 `on` 等自定义级别。别名：`/thinking`、`/t`。 +- `/session idle ` 和 `/session max-age ` 管理线程绑定过期。 +- `/think ` 设置 thinking 级别。可选项来自活动模型的提供商配置档；常见级别有 `off`、`minimal`、`low`、`medium` 和 `high`，而 `xhigh`、`adaptive`、`max` 或二元 `on` 等自定义级别仅在支持时可用。别名：`/thinking`、`/t`。 - `/verbose on|off|full` 切换详细输出。别名：`/v`。 -- `/trace on|off` 切换当前会话的 plugin 跟踪输出。 +- `/trace on|off` 切换当前会话的插件追踪输出。 - `/fast [status|on|off]` 显示或设置快速模式。 - `/reasoning [on|off|stream]` 切换推理可见性。别名：`/reason`。 -- `/elevated [on|off|ask|full]` 切换提升模式。别名：`/elev`。 +- `/elevated [on|off|ask|full]` 切换 elevated 模式。别名：`/elev`。 - `/exec host= security= ask= node=` 显示或设置 exec 默认值。 - `/model [name|#|status]` 显示或设置模型。 - `/models [provider] [page] [limit=|size=|all]` 列出提供商，或列出某个提供商的模型。 -- `/queue ` 管理队列行为（`steer`、`interrupt`、`followup`、`collect`、`steer-backlog`），以及诸如 `debounce:2s cap:25 drop:summarize` 之类的选项。 -- `/help` 显示简短帮助摘要。 +- `/queue ` 管理队列行为（`steer`、`interrupt`、`followup`、`collect`、`steer-backlog`），以及如 `debounce:2s cap:25 drop:summarize` 之类的选项。 +- `/help` 显示简要帮助摘要。 - `/commands` 显示生成的命令目录。 -- `/tools [compact|verbose]` 显示当前智能体此刻可用的能力。 -- `/status` 显示运行时状态，包括 `Runtime`/`Runner` 标签，以及可用时的提供商使用情况/配额。 -- `/tasks` 列出当前会话中活跃/最近的后台任务。 -- `/context [list|detail|json]` 说明上下文是如何组装的。 +- `/tools [compact|verbose]` 显示当前智能体此刻可以使用的内容。 +- `/status` 显示运行时状态，包括 `Runtime`/`Runner` 标签，以及可用时的提供商用量/配额。 +- `/tasks` 列出当前会话的活动/最近后台任务。 +- `/context [list|detail|json]` 解释上下文是如何组装的。 - `/export-session [path]` 将当前会话导出为 HTML。别名：`/export`。 -- `/export-trajectory [path]` 为当前会话导出 JSONL [trajectory bundle](/zh-CN/tools/trajectory)。别名：`/trajectory`。 +- `/export-trajectory [path]` 为当前会话导出一个 JSONL [trajectory bundle](/zh-CN/tools/trajectory)。别名：`/trajectory`。 - `/whoami` 显示你的发送者 id。别名：`/id`。 -- `/skill [input]` 按名称运行一个 skill。 -- `/allowlist [list|add|remove] ...` 管理允许列表条目。仅文本。 +- `/skill [input]` 按名称运行一个 Skills。 +- `/allowlist [list|add|remove] ...` 管理 allowlist 条目。仅文本。 - `/approve ` 处理 exec 审批提示。 -- `/btw ` 提出一个旁支问题，而不改变后续会话上下文。参见 [/tools/btw](/zh-CN/tools/btw)。 +- `/btw ` 在不改变未来会话上下文的情况下提出一个旁支问题。参见 [/tools/btw](/zh-CN/tools/btw)。 - `/subagents list|kill|log|info|send|steer|spawn` 管理当前会话的子智能体运行。 - `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` 管理 ACP 会话和运行时选项。 -- `/focus ` 将当前 Discord 线程或 Telegram 主题/会话绑定到一个会话目标。 +- `/focus ` 将当前 Discord 线程或 Telegram topic/conversation 绑定到一个会话目标。 - `/unfocus` 移除当前绑定。 -- `/agents` 列出当前会话中线程绑定的智能体。 +- `/agents` 列出当前会话中绑定到线程的智能体。 - `/kill ` 中止一个或所有正在运行的子智能体。 -- `/steer ` 向正在运行的子智能体发送引导。别名：`/tell`。 +- `/steer ` 向一个正在运行的子智能体发送引导。别名：`/tell`。 - `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅限 owner。需要 `commands.config: true`。 - `/mcp show|get|set|unset` 读取或写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。仅限 owner。需要 `commands.mcp: true`。 -- `/plugins list|inspect|show|get|install|enable|disable` 检查或修改 plugin 状态。`/plugin` 是别名。写入操作仅限 owner。需要 `commands.plugins: true`。 +- `/plugins list|inspect|show|get|install|enable|disable` 检查或修改插件状态。`/plugin` 是别名。写入操作仅限 owner。需要 `commands.plugins: true`。 - `/debug show|set|unset|reset` 管理仅运行时的配置覆盖。仅限 owner。需要 `commands.debug: true`。 -- `/usage off|tokens|full|cost` 控制每次响应的 usage 页脚，或打印本地成本摘要。 +- `/usage off|tokens|full|cost` 控制每次响应的用量页脚，或输出本地成本摘要。 - `/tts on|off|status|provider|limit|summary|audio|help` 控制 TTS。参见 [/tools/tts](/zh-CN/tools/tts)。 -- `/restart` 在启用时重启 OpenClaw。默认：启用；设置 `commands.restart: false` 可将其禁用。 +- `/restart` 在启用时重启 OpenClaw。默认启用；设置 `commands.restart: false` 可禁用。 - `/activation mention|always` 设置群组激活模式。 - `/send on|off|inherit` 设置发送策略。仅限 owner。 -- `/bash ` 运行主机 shell 命令。仅文本。别名：`! `。需要 `commands.bash: true` 以及 `tools.elevated` 允许列表。 +- `/bash ` 运行主机 shell 命令。仅文本。别名：`! `。需要 `commands.bash: true`，以及 `tools.elevated` allowlist。 - `!poll [sessionId]` 检查后台 bash 作业。 - `!stop [sessionId]` 停止后台 bash 作业。 @@ -151,87 +151,87 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合： - `/dock-slack`（别名：`/dock_slack`） - `/dock-telegram`（别名：`/dock_telegram`） -### 内置 plugin 命令 +### 内置插件命令 -内置 plugin 可以添加更多斜杠命令。此仓库中当前的内置命令： +内置插件可以添加更多 slash commands。此仓库中当前的内置命令： -- `/dreaming [on|off|status|help]` 切换记忆 Dreaming。参见 [Dreaming](/zh-CN/concepts/dreaming)。 +- `/dreaming [on|off|status|help]` 切换 Dreaming。参见 [Dreaming](/zh-CN/concepts/dreaming)。 - `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对/设置流程。参见 [Pairing](/zh-CN/channels/pairing)。 - `/phone status|arm [duration]|disarm` 临时启用高风险手机节点命令。 -- `/voice status|list [limit]|set ` 管理 Talk 语音配置。在 Discord 上，原生命令名称是 `/talkvoice`。 +- `/voice status|list [limit]|set ` 管理 Talk 语音配置。在 Discord 上，原生命令名称为 `/talkvoice`。 - `/card ...` 发送 LINE 富卡片预设。参见 [LINE](/zh-CN/channels/line)。 -- `/codex status|models|threads|resume|compact|review|account|mcp|skills` 检查并控制内置 Codex 应用服务器 harness。参见 [Codex Harness](/zh-CN/plugins/codex-harness)。 -- 仅 QQ Bot 的命令： +- `/codex status|models|threads|resume|compact|review|account|mcp|skills` 检查并控制内置 Codex app-server Harness。参见 [Codex Harness](/zh-CN/plugins/codex-harness)。 +- 仅 QQ Bot 命令： - `/bot-ping` - `/bot-version` - `/bot-help` - `/bot-upgrade` - `/bot-logs` -### 动态 skill 命令 +### 动态 Skills 命令 -用户可调用的 Skills 也会作为斜杠命令公开： +可由用户调用的 Skills 也会作为 slash commands 暴露： - `/skill [input]` 始终可作为通用入口点使用。 -- 当 skill/plugin 注册它们时，Skills 也可能作为直接命令出现，例如 `/prose`。 -- 原生 skill 命令注册由 `commands.nativeSkills` 和 `channels..commands.nativeSkills` 控制。 +- 当 Skills/插件注册它们时，Skills 也可能直接显示为 `/prose` 这样的命令。 +- 原生 Skills 命令注册由 `commands.nativeSkills` 和 `channels..commands.nativeSkills` 控制。 -注意： +说明： -- 命令接受一个可选的 `:`，放在命令和参数之间（例如 `/think: high`、`/send: on`、`/help:`）。 -- `/new ` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配项，文本会被视为消息正文。 -- 如需查看完整的提供商 usage 明细，请使用 `openclaw status --usage`。 -- `/allowlist add|remove` 需要 `commands.config=true`，并遵循渠道 `configWrites`。 -- 在多账号渠道中，面向配置目标的 `/allowlist --account ` 和 `/config set channels..accounts....` 也会遵循目标账号的 `configWrites`。 -- `/usage` 控制每次响应的 usage 页脚；`/usage cost` 会根据 OpenClaw 会话日志输出本地成本摘要。 -- `/restart` 默认启用；设置 `commands.restart: false` 可禁用它。 -- `/plugins install ` 接受与 `openclaw plugins install` 相同的 plugin 规格：本地路径/归档、npm 包，或 `clawhub:`。 -- `/plugins enable|disable` 会更新 plugin 配置，并且可能提示你重启。 -- 仅限 Discord 的原生命令：`/vc join|leave|status` 用于控制语音频道（需要 `channels.discord.voice` 和原生命令；不提供文本形式）。 -- Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）要求实际线程绑定已启用（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。 +- 命令接受命令与参数之间可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。 +- `/new ` 接受模型别名、`provider/model`，或提供商名称（模糊匹配）；如果没有匹配项，则该文本会被视为消息正文。 +- 如需完整的提供商用量明细，请使用 `openclaw status --usage`。 +- `/allowlist add|remove` 需要 `commands.config=true`，并遵循渠道的 `configWrites`。 +- 在多账号渠道中，面向配置目标的 `/allowlist --account ` 和 `/config set channels..accounts....` 也遵循目标账号的 `configWrites`。 +- `/usage` 控制每次响应的用量页脚；`/usage cost` 会根据 OpenClaw 会话日志输出本地成本摘要。 +- `/restart` 默认启用；设置 `commands.restart: false` 可禁用。 +- `/plugins install ` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/压缩包、npm 包，或 `clawhub:`。 +- `/plugins enable|disable` 会更新插件配置，并且可能提示你重启。 +- 仅 Discord 原生命令：`/vc join|leave|status` 用于控制语音频道（需要 `channels.discord.voice` 和原生命令；不提供文本形式）。 +- Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）要求有效启用线程绑定（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。 - ACP 命令参考和运行时行为： [ACP Agents](/zh-CN/tools/acp-agents)。 -- `/verbose` 旨在用于调试和额外可见性；正常使用时请保持**关闭**。 -- `/trace` 比 `/verbose` 更窄：它只显示由 plugin 拥有的 trace/debug 行，并保持普通详细工具输出关闭。 -- `/fast on|off` 会持久化一个会话级覆盖。使用 Sessions UI 中的 `inherit` 选项可清除它，并回退到配置默认值。 -- `/fast` 是提供商特定的：OpenAI/OpenAI Codex 会在原生 Responses 端点上映射为 `service_tier=priority`，而直接发送到 `api.anthropic.com` 的公开 Anthropic 请求（包括使用 OAuth 身份验证的流量）会映射为 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。 -- 相关时仍会显示工具失败摘要，但详细失败文本仅在 `/verbose` 为 `on` 或 `full` 时才包含。 -- `/reasoning`、`/verbose` 和 `/trace` 在群组场景中具有风险：它们可能会暴露你原本无意公开的内部推理、工具输出或 plugin 诊断信息。建议保持关闭，尤其是在群聊中。 +- `/verbose` 用于调试和额外可见性；在正常使用中请保持**关闭**。 +- `/trace` 比 `/verbose` 更窄：它只显示插件拥有的 trace/debug 行，并保持普通详细工具输出关闭。 +- `/fast on|off` 会持久化一个会话覆盖。使用 Sessions UI 的 `inherit` 选项可清除该覆盖并回退到配置默认值。 +- `/fast` 是提供商相关的：OpenAI/OpenAI Codex 会在原生 Responses 端点上将其映射为 `service_tier=priority`，而直接的公共 Anthropic 请求，包括发送到 `api.anthropic.com` 的 OAuth 认证流量，则会将其映射为 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。 +- 工具失败摘要在相关时仍会显示，但详细失败文本仅会在 `/verbose` 为 `on` 或 `full` 时包含。 +- `/reasoning`、`/verbose` 和 `/trace` 在群组场景中有风险：它们可能暴露你本无意公开的内部推理、工具输出或插件诊断信息。建议保持关闭，尤其是在群聊中。 - `/model` 会立即持久化新的会话模型。 -- 如果智能体处于空闲状态，下一次运行会立刻使用它。 +- 如果智能体处于空闲状态，下一次运行会立即使用它。 - 如果某次运行已经处于活动状态，OpenClaw 会将实时切换标记为待处理，并仅在一个干净的重试点重启到新模型。 -- 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到后续的重试机会或下一个用户轮次。 -- **快速路径：** 来自允许列表发送者的纯命令消息会立即处理（绕过队列 + 模型）。 -- **群组提及门控：** 来自允许列表发送者的纯命令消息会绕过提及要求。 -- **内联快捷方式（仅限允许列表发送者）：** 某些命令嵌入在普通消息中时也可工作，并会在模型看到剩余文本前被剥离。 - - 例如：`hey /status` 会触发状态回复，而剩余文本会继续走正常流程。 +- 如果工具活动或回复输出已经开始，则待处理切换可能会一直排队，直到之后出现重试机会或下一个用户轮次。 +- **快速路径：** 来自 allowlist 发送者的纯命令消息会被立即处理（绕过队列 + 模型）。 +- **群组提及门控：** 来自 allowlist 发送者的纯命令消息会绕过提及要求。 +- **内联快捷命令（仅限 allowlist 发送者）：** 某些命令在嵌入普通消息时也能工作，并会在模型看到剩余文本前被剥离。 + - 示例：`hey /status` 会触发状态回复，而剩余文本继续经过正常流程。 - 当前包括：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 -- 未授权的纯命令消息会被静默忽略，而内联 `/...` 标记会被当作普通文本。 -- **Skill 命令：** `user-invocable` Skills 也会公开为斜杠命令。名称会被清洗为 `a-z0-9_`（最多 32 个字符）；冲突时会附加数字后缀（例如 `_2`）。 - - `/skill [input]` 按名称运行一个 skill（当原生命令限制阻止按 skill 单独创建命令时，这会很有用）。 - - 默认情况下，skill 命令会作为普通请求转发给模型。 - - Skills 可以选择声明 `command-dispatch: tool`，以将命令直接路由到工具（确定性，不经过模型）。 - - 示例：`/prose`（OpenProse plugin）——参见 [OpenProse](/zh-CN/prose)。 -- **原生命令参数：** Discord 对动态选项使用自动补全（当你省略必需参数时也会使用按钮菜单）。Telegram 和 Slack 会在命令支持选项且你省略参数时显示按钮菜单。 +- 未授权的纯命令消息会被静默忽略，而内联 `/...` 令牌会被当作普通文本处理。 +- **Skills 命令：** `user-invocable` Skills 也会作为 slash commands 暴露。名称会被规范化为 `a-z0-9_`（最大 32 个字符）；发生冲突时会加数字后缀（例如 `_2`）。 + - `/skill [input]` 按名称运行一个 Skills（当原生命令限制阻止为每个技能创建命令时，这很有用）。 + - 默认情况下，Skills 命令会作为普通请求转发给模型。 + - Skills 可选择声明 `command-dispatch: tool`，将该命令直接路由到工具（确定性，无需模型）。 + - 示例：`/prose`（OpenProse 插件）——参见 [OpenProse](/zh-CN/prose)。 +- **原生命令参数：** Discord 对动态选项使用自动补全（当你省略必填参数时，也会显示按钮菜单）。Telegram 和 Slack 会在某个命令支持选项且你省略参数时显示按钮菜单。 ## `/tools` -`/tools` 回答的是一个运行时问题，而不是配置问题：**这个智能体现在在这次对话中能使用什么**。 +`/tools` 回答的是运行时问题，而不是配置问题：**这个智能体现在在此对话中可以使用什么**。 -- 默认的 `/tools` 是紧凑模式，便于快速浏览。 +- 默认的 `/tools` 是紧凑模式，针对快速浏览进行了优化。 - `/tools verbose` 会添加简短说明。 -- 支持参数的原生命令界面会公开相同的模式切换，即 `compact|verbose`。 -- 结果是会话作用域的，因此更改智能体、渠道、线程、发送者授权或模型都可能改变输出。 -- `/tools` 包含那些在运行时实际可达的工具，包括核心工具、已连接的 plugin 工具以及由渠道拥有的工具。 +- 支持参数的原生命令界面会暴露同样的模式切换，即 `compact|verbose`。 +- 结果是按会话作用域计算的，因此更改智能体、渠道、线程、发送者授权或模型，都可能改变输出。 +- `/tools` 包含运行时实际可访问的工具，包括核心工具、已连接的插件工具以及渠道自有工具。 -如需编辑 profile 和覆盖项，请使用 Control UI 的工具面板或配置/目录界面，而不要把 `/tools` 当作静态目录。 +对于配置档和覆盖编辑，请使用控制 UI 的 Tools 面板或配置/目录界面，而不要把 `/tools` 当作静态目录。 -## Usage 界面（各处显示什么） +## 用量界面（哪些内容显示在哪里） -- **提供商 usage/配额**（例如：“Claude 剩余 80%”）会在启用 usage 跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口统一为“剩余百分比”；对于 MiniMax，仅剩余值的百分比字段会在显示前反转，而 `model_remains` 响应会优先使用聊天模型条目以及带模型标签的计划标签。 -- `/status` 中的**Token/cache 行**在实时会话快照信息稀少时，可以回退到最近的转录 usage 条目。现有的非零实时值仍然优先，而转录回退也可以在存储总量缺失或更小时恢复当前活动运行时模型标签以及一个更偏向 prompt 的较大总量。 -- **Runtime 与 runner：** `/status` 用 `Runtime` 报告生效的执行路径和沙箱状态，用 `Runner` 报告实际运行会话的是谁：内嵌 Pi、基于 CLI 的提供商，还是 ACP harness/backend。 -- **每次响应的 token/成本** 由 `/usage off|tokens|full` 控制（附加到正常回复后）。 -- `/model status` 关注的是**模型/凭证/端点**，不是 usage。 +- **提供商用量/配额**（例如：“Claude 剩余 80%”）会在启用用量跟踪时出现在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口统一标准化为“剩余百分比”；对于 MiniMax，会在显示前反转仅剩余百分比字段，而 `model_remains` 响应会优先使用聊天模型条目和带模型标签的计划标签。 +- 当实时会话快照信息稀疏时，`/status` 中的 **token/cache 行** 可以回退到最近的转录用量条目。已有的非零实时值仍然优先，而转录回退也可以在已存储总量缺失或更小时恢复活动运行时模型标签以及更大的、面向提示词的总量。 +- **Runtime 与 runner：** `/status` 使用 `Runtime` 表示有效执行路径和沙箱状态，使用 `Runner` 表示实际运行该会话的是谁：嵌入式 Pi、由 CLI 支持的提供商，还是 ACP Harness/后端。 +- **每次响应的 token/cost** 由 `/usage off|tokens|full` 控制（追加在普通回复后面）。 +- `/model status` 关注的是**模型/认证/端点**，而不是用量。 ## 模型选择（`/model`） @@ -239,29 +239,29 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合： 示例： -```text +``` /model /model list /model 3 -/model openai/gpt-5.4 +/model openai/gpt-5.5 /model opus@anthropic:default /model status ``` -注意： +说明： -- `/model` 和 `/model list` 会显示一个紧凑的编号选择器（模型家族 + 可用提供商）。 +- `/model` 和 `/model list` 会显示一个紧凑的、带编号的选择器（模型家族 + 可用提供商）。 - 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉框以及一个提交步骤。 -- `/model <#>` 会从该选择器中选择（并在可能时优先使用当前提供商）。 -- `/model status` 会显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`），如果可用。 +- `/model <#>` 会从该选择器中选择（并在可能时优先当前提供商）。 +- `/model status` 会显示详细视图，包括配置的提供商端点（`baseUrl`）和 API 模式（`api`），如果可用的话。 -## 调试覆盖项 +## 调试覆盖 -`/debug` 允许你设置**仅运行时**的配置覆盖项（内存中，不写磁盘）。仅限 owner。默认禁用；通过 `commands.debug: true` 启用。 +`/debug` 允许你设置**仅运行时**配置覆盖（存于内存，不写磁盘）。仅限 owner。默认禁用；使用 `commands.debug: true` 启用。 示例： -```text +``` /debug show /debug set messages.responsePrefix="[openclaw]" /debug set channels.whatsapp.allowFrom=["+1555","+4477"] @@ -269,14 +269,14 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合： /debug reset ``` -注意： +说明： -- 覆盖项会立即应用到新的配置读取中，但**不会**写入 `openclaw.json`。 -- 使用 `/debug reset` 清除所有覆盖项，并恢复到磁盘上的配置。 +- 覆盖会立即应用于新的配置读取，但**不会**写入 `openclaw.json`。 +- 使用 `/debug reset` 可清除所有覆盖，并返回磁盘上的配置。 -## Plugin 跟踪输出 +## 插件追踪输出 -`/trace` 允许你切换**会话作用域的 plugin trace/debug 行**，而无需开启完整详细模式。 +`/trace` 允许你切换**按会话作用域**的插件 trace/debug 行，而无需开启完整详细模式。 示例： @@ -286,22 +286,22 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合： /trace off ``` -注意： +说明： -- 不带参数的 `/trace` 会显示当前会话的 trace 状态。 -- `/trace on` 会为当前会话启用 plugin trace 行。 -- `/trace off` 会再次将其关闭。 -- Plugin trace 行可能会出现在 `/status` 中，也可能作为普通助手回复之后的后续诊断消息出现。 -- `/trace` 不能替代 `/debug`；`/debug` 仍用于管理仅运行时的配置覆盖项。 -- `/trace` 不能替代 `/verbose`；普通的详细工具/状态输出仍属于 `/verbose`。 +- 不带参数的 `/trace` 会显示当前会话的追踪状态。 +- `/trace on` 会为当前会话启用插件追踪行。 +- `/trace off` 会再次将其禁用。 +- 插件追踪行可能出现在 `/status` 中，也可能作为普通助手回复之后的附加诊断消息出现。 +- `/trace` 不能替代 `/debug`；`/debug` 仍用于管理仅运行时的配置覆盖。 +- `/trace` 也不能替代 `/verbose`；普通的详细工具/状态输出仍属于 `/verbose`。 ## 配置更新 -`/config` 会写入你的磁盘配置（`openclaw.json`）。仅限 owner。默认禁用；通过 `commands.config: true` 启用。 +`/config` 会写入你的磁盘配置（`openclaw.json`）。仅限 owner。默认禁用；使用 `commands.config: true` 启用。 示例： -```text +``` /config show /config show messages.responsePrefix /config get messages.responsePrefix @@ -309,14 +309,14 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合： /config unset messages.responsePrefix ``` -注意： +说明： -- 写入前会校验配置；无效更改会被拒绝。 -- `/config` 更新会在重启后继续保留。 +- 写入前会对配置进行验证；无效更改会被拒绝。 +- `/config` 更新会在重启后保持生效。 ## MCP 更新 -`/mcp` 会将 OpenClaw 管理的 MCP 服务器定义写入 `mcp.servers` 下。仅限 owner。默认禁用；通过 `commands.mcp: true` 启用。 +`/mcp` 会在 `mcp.servers` 下写入由 OpenClaw 管理的 MCP 服务器定义。仅限 owner。默认禁用；使用 `commands.mcp: true` 启用。 示例： @@ -327,14 +327,14 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合： /mcp unset context7 ``` -注意： +说明： -- `/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 拥有的项目设置中。 -- 运行时适配器决定哪些传输方式实际上可执行。 +- `/mcp` 将配置存储在 OpenClaw 配置中，而不是存储在由 Pi 拥有的项目设置中。 +- 运行时适配器决定哪些传输实际上可执行。 -## Plugin 更新 +## 插件更新 -`/plugins` 允许操作员检查已发现的 plugin，并在配置中切换启用状态。只读流程可使用 `/plugin` 作为别名。默认禁用；通过 `commands.plugins: true` 启用。 +`/plugins` 允许操作员检查已发现的插件，并在配置中切换启用状态。只读流程可使用 `/plugin` 作为别名。默认禁用；使用 `commands.plugins: true` 启用。 示例： @@ -346,36 +346,36 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合： /plugins disable context7 ``` -注意： +说明： -- `/plugins list` 和 `/plugins show` 会基于当前工作区和磁盘配置执行真实的 plugin 发现。 -- `/plugins enable|disable` 只更新 plugin 配置；不会安装或卸载 plugin。 -- 在启用/禁用变更后，重启 Gateway 网关以使其生效。 +- `/plugins list` 和 `/plugins show` 会根据当前工作区和磁盘配置执行真实的插件发现。 +- `/plugins enable|disable` 只更新插件配置；它不会安装或卸载插件。 +- 在启用/禁用变更后，请重启 Gateway 网关以应用它们。 ## 界面说明 -- **文本命令** 在普通聊天会话中运行（私信共享 `main`，群组有各自的会话）。 +- **文本命令** 在正常聊天会话中运行（私信共享 `main`，群组拥有各自独立会话）。 - **原生命令** 使用隔离会话： - Discord：`agent::discord:slash:` - Slack：`agent::slack:slash:`（前缀可通过 `channels.slack.slashCommand.sessionPrefix` 配置） - - Telegram：`telegram:slash:`（通过 `CommandTargetSessionKey` 定位到聊天会话） -- **`/stop`** 面向当前活动聊天会话，因此它可以中止当前运行。 -- **Slack：** `channels.slack.slashCommand` 仍然支持单个 `/openclaw` 风格的命令。如果你启用 `commands.native`，则必须为每个内置命令创建一个 Slack 斜杠命令（名称与 `/help` 相同）。Slack 的命令参数菜单会以临时的 Block Kit 按钮形式提供。 - - Slack 原生命令例外：请注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本形式的 `/status` 在 Slack 消息中仍然可用。 + - Telegram：`telegram:slash:`（通过 `CommandTargetSessionKey` 指向聊天会话） +- **`/stop`** 会指向活动聊天会话，以便中止当前运行。 +- **Slack：** `channels.slack.slashCommand` 仍支持单个 `/openclaw` 风格命令。如果启用 `commands.native`，则必须为每个内置命令创建一个 Slack slash 命令（名称与 `/help` 相同）。Slack 的命令参数菜单会以临时 Block Kit 按钮形式投递。 + - Slack 原生例外：请注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 在 Slack 消息中仍然可用。 ## BTW 旁支问题 -`/btw` 是一个关于当前会话的快速**旁支问题**。 +`/btw` 是一个关于当前会话的快捷**旁支问题**。 与普通聊天不同： - 它会使用当前会话作为背景上下文， -- 它会作为一个独立的**无工具**一次性调用运行， -- 它不会改变后续会话上下文， +- 它以一个独立的**无工具**一次性调用运行， +- 它不会改变未来的会话上下文， - 它不会写入转录历史， -- 它会作为实时旁路结果传递，而不是普通助手消息。 +- 它会以实时旁支结果的形式投递，而不是普通助手消息。 -这使得 `/btw` 在你希望主任务继续进行的同时，临时获得一个澄清时非常有用。 +这使得 `/btw` 在你希望获得临时澄清、同时主任务继续进行时非常有用。 示例： @@ -383,4 +383,4 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合： /btw what are we doing right now? ``` -有关完整行为和客户端 UX 细节，请参见 [BTW Side Questions](/zh-CN/tools/btw)。 +完整行为和客户端 UX 细节请参见 [BTW Side Questions](/zh-CN/tools/btw)。