diff --git a/docs/zh-CN/auth-credential-semantics.md b/docs/zh-CN/auth-credential-semantics.md index 50dbe95ae..06c75d6c0 100644 --- a/docs/zh-CN/auth-credential-semantics.md +++ b/docs/zh-CN/auth-credential-semantics.md @@ -1,14 +1,14 @@ --- read_when: - - 处理 auth 配置文件解析或凭证路由时 + - 处理认证配置文件解析或凭证路由时 - 调试模型认证失败或配置文件顺序时 -summary: auth 配置文件的规范凭证资格与解析语义 -title: 凭证语义 +summary: 认证配置文件的规范凭证资格与解析语义 +title: 凭证认证语义 x-i18n: - generated_at: "2026-04-24T04:00:24Z" + generated_at: "2026-04-27T07:11:15Z" model: gpt-5.4 provider: openai - source_hash: b45da872b9ab177acbac08ce353b6ee31b6a068477ace52e5e5eda32a848d8bb + source_hash: a1172a87053986567ac6051afe99946a9d36e1e838ce693cd56d56e71242d679 source_path: auth-credential-semantics.md workflow: 15 --- @@ -20,7 +20,7 @@ x-i18n: - `models status --probe` - `doctor-auth` -目标是使选择时行为与运行时行为保持一致。 +目标是保持选择时行为与运行时行为一致。 ## 稳定的探测原因代码 @@ -32,51 +32,51 @@ x-i18n: - `unresolved_ref` - `no_model` -## Token 凭证 +## 令牌凭证 -Token 凭证（`type: "token"`）支持内联 `token` 和/或 `tokenRef`。 +令牌凭证（`type: "token"`）支持内联 `token` 和/或 `tokenRef`。 ### 资格规则 -1. 当 `token` 和 `tokenRef` 均不存在时，Token 配置文件不符合资格。 +1. 当 `token` 和 `tokenRef` 都不存在时，令牌配置文件不具备资格。 2. `expires` 是可选的。 -3. 如果存在 `expires`，它必须是一个大于 `0` 的有限数字。 -4. 如果 `expires` 无效（`NaN`、`0`、负数、非有限值或类型错误），该配置文件不符合资格，原因为 `invalid_expires`。 -5. 如果 `expires` 已经过期，该配置文件不符合资格，原因为 `expired`。 -6. `tokenRef` 不会绕过对 `expires` 的校验。 +3. 如果存在 `expires`，它必须是大于 `0` 的有限数字。 +4. 如果 `expires` 无效（`NaN`、`0`、负数、非有限值或类型错误），则该配置文件不具备资格，原因为 `invalid_expires`。 +5. 如果 `expires` 已过期，则该配置文件不具备资格，原因为 `expired`。 +6. `tokenRef` 不会绕过 `expires` 验证。 ### 解析规则 1. 解析器对 `expires` 的语义与资格语义一致。 -2. 对于符合资格的配置文件，Token 材料可以从内联值或 `tokenRef` 解析得到。 +2. 对于具备资格的配置文件，令牌内容可以从内联值或 `tokenRef` 解析得到。 3. 无法解析的引用会在 `models status --probe` 输出中产生 `unresolved_ref`。 -## 显式 Auth 顺序过滤 +## 显式认证顺序过滤 -- 当为某个提供商设置了 `auth.order.` 或 auth-store 顺序覆盖时，`models status --probe` 只会探测在该提供商已解析 auth 顺序中仍然保留的配置文件 id。 -- 属于该提供商但在显式顺序中被省略的已存储配置文件，后续不会被静默尝试。探测输出会将其报告为 `reasonCode: excluded_by_auth_order`，并带有详细信息 `Excluded by auth.order for this provider.` +- 当为某个提供商设置了 `auth.order.` 或认证存储顺序覆盖时，`models status --probe` 只会探测该提供商已解析认证顺序中仍然保留的配置文件 id。 +- 某个提供商的已存储配置文件如果被显式顺序省略，不会在之后被悄悄尝试。探测输出会将其报告为 `reasonCode: excluded_by_auth_order`，详情为 `Excluded by auth.order for this provider.` ## 探测目标解析 -- 探测目标可以来自 auth 配置文件、环境变量凭证或 `models.json`。 -- 如果某个提供商具备凭证，但 OpenClaw 无法为其解析出可探测的模型候选项，则 `models status --probe` 会报告 `status: no_model` 和 `reasonCode: no_model`。 +- 探测目标可以来自认证配置文件、环境变量凭证或 `models.json`。 +- 如果某个提供商具有凭证，但 OpenClaw 无法为其解析出可探测的模型候选项，则 `models status --probe` 会报告 `status: no_model` 和 `reasonCode: no_model`。 ## OAuth SecretRef 策略保护 - SecretRef 输入仅用于静态凭证。 - 如果某个配置文件凭证的 `type` 为 `oauth`，则该配置文件凭证材料不支持 SecretRef 对象。 -- 如果 `auth.profiles..mode` 为 `"oauth"`，则会拒绝该配置文件基于 SecretRef 的 `keyRef`/`tokenRef` 输入。 -- 在启动/重载 auth 解析路径中，违反这些规则会导致硬失败。 +- 如果 `auth.profiles..mode` 为 `"oauth"`，则会拒绝该配置文件的 `keyRef`/`tokenRef` SecretRef 支持输入。 +- 违规会在启动/重载认证解析路径中导致硬失败。 -## 兼容旧版的消息 +## 兼容旧版的消息提示 为保持脚本兼容性，探测错误会保持以下首行不变： `Auth profile credentials are missing or expired.` -后续行可以添加更易于理解的详细信息和稳定的原因代码。 +可以在后续行中添加更适合人类阅读的详情和稳定原因代码。 ## 相关内容 -- [密钥管理](/zh-CN/gateway/secrets) -- [Auth 存储](/zh-CN/concepts/oauth) +- [Secrets 管理](/zh-CN/gateway/secrets) +- [认证存储](/zh-CN/concepts/oauth) diff --git a/docs/zh-CN/automation/standing-orders.md b/docs/zh-CN/automation/standing-orders.md index 08b557470..d1085e8ca 100644 --- a/docs/zh-CN/automation/standing-orders.md +++ b/docs/zh-CN/automation/standing-orders.md @@ -1,57 +1,57 @@ --- read_when: - - 设置无需逐任务提示即可运行的自治智能体工作流 - - 定义智能体可以独立完成的事项，以及哪些事项需要人工批准 - - 构建多程序智能体，并明确边界和升级规则 -summary: 为自治智能体程序定义永久运行权限 -title: 长期指令 + - 设置无需针对每项任务单独提示即可运行的自主智能体工作流 + - 定义智能体可以独立执行的内容与需要人工批准的内容 + - 为多程序智能体构建具有清晰边界和升级规则的结构 +summary: 为自主智能体程序定义永久运行权限 +title: 常设命令 x-i18n: - generated_at: "2026-04-24T16:35:15Z" + generated_at: "2026-04-27T07:11:16Z" model: gpt-5.4 provider: openai - source_hash: 4a18777284a12e99b2e9f1ce660a0dc4d18ba5782d6a6a6673b495ab32b2d8cf + source_hash: ff895378cbd53f7e8058137389037ab40201ce2cdfb34c135f480dfef775919b source_path: automation/standing-orders.md workflow: 15 --- -长期指令会为你的智能体授予针对已定义程序的**永久运行权限**。你不必每次都单独下达任务指令，而是通过明确范围、触发条件和升级规则来定义程序——然后智能体会在这些边界内自主执行。 +常设命令会为你定义的程序授予智能体**永久运行权限**。你无需每次都单独下达任务指令，而是通过清晰的范围、触发条件和升级规则来定义程序——智能体将在这些边界内自主执行。 -这相当于：不是每周五都对助手说“发送每周报告”，而是授予长期权限：“每周报告由你负责。每周五完成汇总并发送，只有在发现异常时才升级给我处理。” +这就像每周五都告诉你的助手“发送每周报告”，与授予常设权限之间的区别：“每周报告由你负责。每周五完成汇总并发送，只有在发现异常时才升级给我处理。” -## 为什么要使用长期指令？ +## 为什么需要常设命令 -**没有长期指令时：** +**没有常设命令时：** -- 你必须为每个任务都提示智能体 +- 你必须为每项任务都提示智能体 - 智能体会在请求之间处于空闲状态 -- 例行工作容易被遗忘或延迟 +- 例行工作容易被遗忘或延误 - 你会成为整个流程的瓶颈 -**有了长期指令后：** +**有常设命令时：** -- 智能体会在已定义边界内自主执行 -- 例行工作会按计划完成，无需提示 -- 你只需要参与异常情况和审批事项 +- 智能体会在定义好的边界内自主执行 +- 例行工作会按计划进行，无需提示 +- 你只需处理例外情况和审批事项 - 智能体会高效利用空闲时间 ## 它们如何工作 -长期指令定义在你的[智能体工作区](/zh-CN/concepts/agent-workspace)文件中。推荐做法是将它们直接写入 `AGENTS.md`（该文件会在每次会话中自动注入），这样智能体始终会在上下文中看到这些指令。对于更大的配置，你也可以将其放在专用文件中，例如 `standing-orders.md`，然后在 `AGENTS.md` 中引用它。 +常设命令定义在你的[智能体工作区](/zh-CN/concepts/agent-workspace)文件中。推荐做法是将其直接写入 `AGENTS.md`（每个会话都会自动注入），这样智能体始终能在上下文中看到这些命令。对于更大的配置，你也可以把它们放在专门的文件中，例如 `standing-orders.md`，然后在 `AGENTS.md` 中引用它。 每个程序都应指定： -1. **范围** —— 智能体被授权执行哪些内容 -2. **触发条件** —— 何时执行（按计划、事件触发或条件触发） -3. **审批关卡** —— 哪些操作需要先获得人工签字确认 -4. **升级规则** —— 何时停止并请求帮助 +1. **范围**——智能体被授权执行什么 +2. **触发条件**——何时执行（按计划、事件或条件） +3. **审批关卡**——哪些操作在执行前需要人工签字确认 +4. **升级规则**——何时停止并请求帮助 -智能体会在每次会话中通过工作区引导文件加载这些指令（完整自动注入文件列表参见[智能体工作区](/zh-CN/concepts/agent-workspace)），并结合 [cron jobs](/zh-CN/automation/cron-jobs) 来执行基于时间的强制调度。 +智能体会在每个会话中通过工作区引导文件加载这些指令（完整的自动注入文件列表见[智能体工作区](/zh-CN/concepts/agent-workspace)），并结合 [cron jobs](/zh-CN/automation/cron-jobs) 来执行基于时间的强制调度。 -把长期指令放在 `AGENTS.md` 中，以确保它们会在每次会话中加载。工作区引导流程会自动注入 `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md` 和 `MEMORY.md`——但不会自动注入子目录中的任意文件。 +将常设命令放在 `AGENTS.md` 中，以确保它们在每个会话中都会被加载。工作区引导流程会自动注入 `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md` 和 `MEMORY.md`——但不会注入子目录中的任意文件。 -## 长期指令的结构 +## 常设命令的结构 ```markdown ## Program: Weekly Status Report @@ -61,7 +61,7 @@ x-i18n: **Approval gate:** None for standard reports. Flag anomalies for human review. **Escalation:** If data source is unavailable or metrics look unusual (>2σ from norm) -### Execution Steps +### Execution steps 1. Pull metrics from configured sources 2. Compare to prior week and targets @@ -69,26 +69,26 @@ x-i18n: 4. Deliver summary via configured channel 5. Log completion to Agent/Logs/ -### What NOT to Do +### What NOT to do - Do not send reports to external parties - Do not modify source data - Do not skip delivery if metrics look bad — report accurately ``` -## 长期指令 + Cron Jobs +## 常设命令与 cron jobs -长期指令定义智能体被授权做**什么**。[Cron Jobs](/zh-CN/automation/cron-jobs) 定义事情在**什么时候**发生。两者协同工作： +常设命令定义智能体**被授权做什么**。[Cron jobs](/zh-CN/automation/cron-jobs) 定义**何时发生**。两者配合使用： -``` -Standing Order: "You own the daily inbox triage" +```text +常设命令：“你负责每日收件箱分拣” ↓ -Cron Job (8 AM daily): "Execute inbox triage per standing orders" +Cron Job（每日上午 8 点）：“按照常设命令执行收件箱分拣” ↓ -Agent: Reads standing orders → executes steps → reports results +智能体：读取常设命令 → 执行步骤 → 报告结果 ``` -`cron job` 提示应当引用长期指令，而不是重复书写其内容： +Cron job 提示应当引用常设命令，而不是重复写一遍： ```bash openclaw cron add \ @@ -113,13 +113,13 @@ openclaw cron add \ **Approval gate:** All posts require owner review for first 30 days, then standing approval **Trigger:** Weekly cycle (Monday review → mid-week drafts → Friday brief) -### Weekly Cycle +### Weekly cycle - **Monday:** Review platform metrics and audience engagement - **Tuesday–Thursday:** Draft social posts, create blog content - **Friday:** Compile weekly marketing brief → deliver to owner -### Content Rules +### Content rules - Voice must match the brand (see SOUL.md or brand voice guide) - Never identify as AI in public-facing content @@ -136,7 +136,7 @@ openclaw cron add \ **Approval gate:** None for analysis. Recommendations require owner approval. **Trigger:** New data file detected OR scheduled monthly cycle -### When New Data Arrives +### When new data arrives 1. Detect new file in designated input directory 2. Parse and categorize all transactions @@ -145,7 +145,7 @@ openclaw cron add \ 5. Generate report in designated output directory 6. Deliver summary to owner via configured channel -### Escalation Rules +### Escalation rules - Single item > $500: immediate alert - Category > budget by 20%: flag in report @@ -169,7 +169,7 @@ openclaw cron add \ - Pending tasks not stale (>24 hours) - Delivery channels operational -### Response Matrix +### Response matrix | Condition | Action | Escalate? | | ---------------- | ------------------------ | ------------------------ | @@ -179,16 +179,16 @@ openclaw cron add \ | Channel offline | Log and retry next cycle | If offline > 2 hours | ``` -## 执行-验证-汇报模式 +## 执行—验证—报告模式 -长期指令在与严格的执行纪律结合时效果最好。长期指令中的每个任务都应遵循以下循环： +常设命令与严格的执行纪律结合时效果最佳。常设命令中的每项任务都应遵循这个循环： -1. **执行** —— 完成实际工作（不要只是确认收到指令） -2. **验证** —— 确认结果正确无误（文件存在、消息已送达、数据已解析） -3. **汇报** —— 告诉所有者你做了什么，以及验证了什么 +1. **执行**——完成实际工作（不要只是确认收到指令） +2. **验证**——确认结果正确（文件已存在、消息已送达、数据已解析） +3. **报告**——告诉所有者完成了什么，以及验证了什么 ```markdown -### Execution Rules +### Execution rules - Every task follows Execute-Verify-Report. No exceptions. - "I'll do that" is not execution. Do it, then report. @@ -198,11 +198,11 @@ openclaw cron add \ - Never retry indefinitely — 3 attempts max, then escalate. ``` -这种模式可以防止智能体最常见的失败方式：只确认任务，却没有真正完成任务。 +这种模式可以避免最常见的智能体失误：口头确认任务，却没有真正完成。 ## 多程序架构 -对于需要管理多个事项的智能体，应将长期指令组织为多个独立程序，并明确它们之间的边界： +对于需要管理多个事项的智能体，应将常设命令组织为边界清晰的独立程序： ```markdown ## Program 1: [Domain A] (Weekly) @@ -227,31 +227,31 @@ openclaw cron add \ - 自己的**触发节奏**（每周、每月、事件驱动、持续运行） - 自己的**审批关卡**（有些程序比其他程序需要更多监督） -- 清晰的**边界**（智能体应当知道一个程序在哪里结束，另一个程序从哪里开始） +- 清晰的**边界**（智能体应知道一个程序何时结束、另一个程序何时开始） ## 最佳实践 ### 建议这样做 -- 一开始只授予较窄的权限，并随着信任建立逐步扩大 +- 从狭窄权限开始，随着信任建立逐步扩展 - 为高风险操作定义明确的审批关卡 - 加入“不要做什么”部分——边界和权限同样重要 -- 结合 Cron Jobs 使用，以实现可靠的定时执行 -- 每周检查智能体日志，确认长期指令正在被正确遵循 -- 随着需求演变更新长期指令——它们是动态文档 +- 结合 cron jobs 实现可靠的定时执行 +- 每周检查一次智能体日志，确认常设命令被正确遵循 +- 随着需求变化更新常设命令——它们是持续演进的文档 ### 避免这样做 -- 第一天就授予过宽权限（“你觉得怎么最好就怎么做”） -- 跳过升级规则——每个程序都需要“什么时候停止并询问”的条款 -- 假设智能体会记住口头指令——把所有内容都写进文件里 -- 在同一个程序中混合多个事项——不同领域应拆分为不同程序 -- 忘记通过 `cron jobs` 强制执行——没有触发器的长期指令只会变成建议 +- 第一天就授予宽泛权限（“做你认为最好的任何事”） +- 跳过升级规则——每个程序都需要“何时停止并询问”的条款 +- 假设智能体会记住口头说明——把所有内容都写进文件 +- 在同一个程序中混合多个事项——不同领域应拆分成不同程序 +- 忘记用 cron jobs 强制执行——没有触发条件的常设命令只会变成建议 ## 相关内容 -- [Automation & Tasks](/zh-CN/automation) —— 各类自动化机制总览 -- [Cron Jobs](/zh-CN/automation/cron-jobs) —— 长期指令的调度执行机制 -- [Hooks](/zh-CN/automation/hooks) —— 用于智能体生命周期事件的事件驱动脚本 -- [Webhooks](/zh-CN/automation/cron-jobs#webhooks) —— 入站 HTTP 事件触发器 -- [Agent Workspace](/zh-CN/concepts/agent-workspace) —— 长期指令的存放位置，包括完整的自动注入引导文件列表（AGENTS.md、SOUL.md 等） +- [自动化与任务](/zh-CN/automation)：快速了解所有自动化机制。 +- [Cron jobs](/zh-CN/automation/cron-jobs)：为常设命令提供计划调度。 +- [Hooks](/zh-CN/automation/hooks)：用于智能体生命周期事件的事件驱动脚本。 +- [Webhooks](/zh-CN/automation/cron-jobs#webhooks)：入站 HTTP 事件触发器。 +- [智能体工作区](/zh-CN/concepts/agent-workspace)：常设命令的存放位置，以及完整的自动注入引导文件列表（`AGENTS.md`、`SOUL.md` 等）。 diff --git a/docs/zh-CN/channels/msteams.md b/docs/zh-CN/channels/msteams.md index 13f928a66..1a8d574de 100644 --- a/docs/zh-CN/channels/msteams.md +++ b/docs/zh-CN/channels/msteams.md @@ -1,24 +1,24 @@ --- read_when: - - 开发 Microsoft Teams 渠道功能 + - 正在开发 Microsoft Teams 渠道功能 summary: Microsoft Teams 机器人支持状态、功能和配置 title: Microsoft Teams x-i18n: - generated_at: "2026-04-27T06:02:06Z" + generated_at: "2026-04-27T07:11:17Z" model: gpt-5.4 provider: openai - source_hash: 6d2e56f75a46c65ed8f631a4222d37ef1202883581742afd7457aa33ab0cfee0 + source_hash: 9e11562a30a71ae92b677ac3cf1c6b96b925d4064bfce5fd325da13489c98f99 source_path: channels/msteams.md workflow: 15 --- -状态：支持文本和私信附件；渠道/群组文件发送需要 `sharePointSiteId` + Graph 权限（参见 [在群聊中发送文件](#sending-files-in-group-chats)）。投票通过 Adaptive Cards 发送。消息操作提供显式的 `upload-file`，用于优先发送文件的场景。 +状态：支持文本 + 私信附件；渠道/群组文件发送需要 `sharePointSiteId` + Graph 权限（参见[在群聊中发送文件](#sending-files-in-group-chats)）。投票通过 Adaptive Cards 发送。消息操作公开显式的 `upload-file`，用于以文件为优先的发送。 ## 内置插件 -Microsoft Teams 在当前的 OpenClaw 版本中作为内置插件提供，因此在正常的打包构建中无需单独安装。 +Microsoft Teams 在当前的 OpenClaw 版本中作为内置插件提供，因此在常规打包构建中不需要单独安装。 -如果你使用的是较旧的构建，或者是排除了内置 Teams 的自定义安装，请手动安装： +如果你使用的是较旧版本，或使用排除了内置 Teams 的自定义安装，请手动安装： ```bash openclaw plugins install @openclaw/msteams @@ -30,18 +30,18 @@ openclaw plugins install @openclaw/msteams openclaw plugins install ./path/to/local/msteams-plugin ``` -详情： [Plugins](/zh-CN/tools/plugin) +详情：[插件](/zh-CN/tools/plugin) -## 快速设置 +## 快速开始 -[`@microsoft/teams.cli`](https://www.npmjs.com/package/@microsoft/teams.cli) 可以通过一条命令完成机器人注册、清单创建和凭据生成。 +[`@microsoft/teams.cli`](https://www.npmjs.com/package/@microsoft/teams.cli) 可通过单条命令完成机器人注册、manifest 创建和凭证生成。 **1. 安装并登录** ```bash npm install -g @microsoft/teams.cli@preview teams login -teams status # 验证你已登录，并查看你的租户信息 +teams status # 验证你已登录并看到你的租户信息 ``` @@ -50,23 +50,23 @@ Teams CLI 当前仍处于预览阶段。命令和标志可能会在不同版本 **2. 启动隧道**（Teams 无法访问 localhost） -如果你尚未安装，请先安装并完成 devtunnel CLI 的身份验证（参见[入门指南](https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/get-started)）。 +如果你还没有安装，请先安装并完成 devtunnel CLI 的认证（参见[入门指南](https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/get-started)）。 ```bash -# 一次性设置（跨会话保持持久 URL）： +# 一次性设置（跨会话持久 URL）： devtunnel create my-openclaw-bot --allow-anonymous devtunnel port create my-openclaw-bot -p 3978 --protocol auto # 每次开发会话： devtunnel host my-openclaw-bot -# 你的端点： https://.devtunnels.ms/api/messages +# 你的端点：https://.devtunnels.ms/api/messages ``` -必须使用 `--allow-anonymous`，因为 Teams 无法通过 devtunnels 进行身份验证。每个传入的机器人请求仍会由 Teams SDK 自动验证。 +`--allow-anonymous` 是必需的，因为 Teams 无法使用 devtunnels 进行身份验证。每个传入的机器人请求仍会由 Teams SDK 自动验证。 -替代方案：`ngrok http 3978` 或 `tailscale funnel 3978`（但这些方案的 URL 可能在每次会话中变化）。 +替代方案：`ngrok http 3978` 或 `tailscale funnel 3978`（但这些可能会在每次会话中更改 URL）。 **3. 创建应用** @@ -78,14 +78,14 @@ teams app create \ 这一条命令会： -- 创建一个 Entra ID（Azure AD）应用 -- 生成一个客户端密钥 -- 构建并上传 Teams 应用清单（含图标） -- 注册机器人（默认由 Teams 托管——无需 Azure 订阅） +- 创建 Entra ID（Azure AD）应用 +- 生成客户端密钥 +- 构建并上传 Teams 应用 manifest（含图标） +- 注册机器人（默认由 Teams 托管——不需要 Azure 订阅） -输出中会显示 `CLIENT_ID`、`CLIENT_SECRET`、`TENANT_ID` 和一个**Teams App ID**——请记下这些信息，以便后续步骤使用。它还会提示你直接在 Teams 中安装该应用。 +输出中会显示 `CLIENT_ID`、`CLIENT_SECRET`、`TENANT_ID` 和一个 **Teams App ID** ——请记下这些信息，用于后续步骤。它还会提供直接在 Teams 中安装应用的选项。 -**4. 配置 OpenClaw**，使用输出中的凭据： +**4. 使用输出中的凭证配置 OpenClaw：** ```json5 { @@ -105,35 +105,35 @@ teams app create \ **5. 在 Teams 中安装应用** -`teams app create` 会提示你安装该应用——选择“Install in Teams”。如果你跳过了此步骤，稍后可以获取链接： +`teams app create` 会提示你安装应用——选择“Install in Teams”。如果你跳过了这一步，之后可以获取链接： ```bash teams app get --install-link ``` -**6. 验证一切是否正常** +**6. 验证一切正常** ```bash teams app doctor ``` -这会针对机器人注册、AAD 应用配置、清单有效性和 SSO 设置运行诊断。 +这会对机器人注册、AAD 应用配置、manifest 有效性和 SSO 设置进行诊断。 -对于生产部署，建议考虑使用[联合身份验证](#federated-authentication-certificate--managed-identity)（证书或托管身份），而不是客户端密钥。 +对于生产部署，建议考虑使用[联合身份验证](#federated-authentication-certificate--managed-identity)（证书或托管身份）来替代客户端密钥。 -默认情况下，群聊会被阻止（`channels.msteams.groupPolicy: "allowlist"`）。若要允许群组回复，请设置 `channels.msteams.groupAllowFrom`，或使用 `groupPolicy: "open"` 以允许任何成员（默认仍受提及门控限制）。 +默认会阻止群聊（`channels.msteams.groupPolicy: "allowlist"`）。若要允许群组回复，请设置 `channels.msteams.groupAllowFrom`，或使用 `groupPolicy: "open"` 以允许任何成员（默认仍需提及）。 ## 目标 - 通过 Teams 私信、群聊或渠道与 OpenClaw 对话。 -- 保持路由行为可预测：回复始终返回到消息来源的渠道。 +- 保持路由确定性：回复始终返回消息到达时所在的渠道。 - 默认采用安全的渠道行为（除非另有配置，否则需要提及）。 ## 配置写入 -默认情况下，Microsoft Teams 允许写入由 `/config set|unset` 触发的配置更新（需要 `commands.config: true`）。 +默认情况下，Microsoft Teams 被允许写入由 `/config set|unset` 触发的配置更新（需要 `commands.config: true`）。 可通过以下方式禁用： @@ -147,17 +147,17 @@ teams app doctor **私信访问** -- 默认：`channels.msteams.dmPolicy = "pairing"`。未知发送者在获得批准前会被忽略。 +- 默认：`channels.msteams.dmPolicy = "pairing"`。未知发送者在获批前会被忽略。 - `channels.msteams.allowFrom` 应使用稳定的 AAD 对象 ID。 -- 不要依赖 UPN/显示名称匹配来实现 allowlist——它们可能会变化。OpenClaw 默认禁用直接名称匹配；如需启用，请显式设置 `channels.msteams.dangerouslyAllowNameMatching: true`。 -- 当凭据允许时，向导可以通过 Microsoft Graph 将名称解析为 ID。 +- 不要依赖 UPN/显示名称匹配来做允许列表——这些值可能会变化。OpenClaw 默认禁用直接名称匹配；如需启用，请显式设置 `channels.msteams.dangerouslyAllowNameMatching: true`。 +- 当凭证允许时，向导可通过 Microsoft Graph 将名称解析为 ID。 **群组访问** -- 默认：`channels.msteams.groupPolicy = "allowlist"`（除非你添加 `groupAllowFrom`，否则会被阻止）。未设置时，可使用 `channels.defaults.groupPolicy` 覆盖默认值。 +- 默认：`channels.msteams.groupPolicy = "allowlist"`（除非你添加 `groupAllowFrom`，否则会被阻止）。若未设置，可使用 `channels.defaults.groupPolicy` 覆盖默认值。 - `channels.msteams.groupAllowFrom` 控制哪些发送者可以在群聊/渠道中触发（回退到 `channels.msteams.allowFrom`）。 -- 设置 `groupPolicy: "open"` 可允许任何成员（默认仍受提及门控限制）。 -- 若要**完全不允许任何渠道**，请设置 `channels.msteams.groupPolicy: "disabled"`。 +- 设置 `groupPolicy: "open"` 可允许任何成员（默认仍需提及）。 +- 若要**不允许任何渠道**，请设置 `channels.msteams.groupPolicy: "disabled"`。 示例： @@ -172,13 +172,13 @@ teams app doctor } ``` -**Teams + 渠道 allowlist** +**Teams + 渠道允许列表** -- 通过在 `channels.msteams.teams` 下列出团队和渠道，限定群组/渠道回复范围。 +- 可通过在 `channels.msteams.teams` 下列出团队和渠道来限定群组/渠道回复范围。 - 键应使用稳定的团队 ID 和渠道会话 ID。 -- 当 `groupPolicy="allowlist"` 且存在 teams allowlist 时，只接受已列出的团队/渠道（受提及门控限制）。 -- 配置向导接受 `Team/Channel` 条目，并会为你保存。 -- 启动时，OpenClaw 会将团队/渠道和用户 allowlist 中的名称解析为 ID（当 Graph 权限允许时），并记录映射；无法解析的团队/渠道名称会按输入原样保留，但默认会在路由中被忽略，除非启用了 `channels.msteams.dangerouslyAllowNameMatching: true`。 +- 当 `groupPolicy="allowlist"` 且存在团队允许列表时，只接受列出的团队/渠道（默认仍需提及）。 +- 配置向导接受 `Team/Channel` 条目并会为你存储。 +- 启动时，OpenClaw 会将团队/渠道以及用户允许列表中的名称解析为 ID（当 Graph 权限允许时），并记录映射；无法解析的团队/渠道名称会按输入保留，但默认会在路由中被忽略，除非启用 `channels.msteams.dangerouslyAllowNameMatching: true`。 示例： @@ -209,9 +209,9 @@ teams app doctor 1. 确保 Microsoft Teams 插件可用（当前版本中为内置）。 2. 创建一个 **Azure Bot**（App ID + 密钥 + tenant ID）。 3. 构建一个 **Teams 应用包**，引用该机器人并包含下方的 RSC 权限。 -4. 将 Teams 应用上传/安装到某个团队中（或安装到个人范围以用于私信）。 +4. 将 Teams 应用上传/安装到某个团队中（或安装到个人范围用于私信）。 5. 在 `~/.openclaw/openclaw.json` 中配置 `msteams`（或使用环境变量），然后启动 Gateway 网关。 -6. Gateway 网关默认在 `/api/messages` 监听 Bot Framework webhook 流量。 +6. Gateway 网关 默认在 `/api/messages` 上监听 Bot Framework webhook 流量。 ### 第 1 步：创建 Azure Bot @@ -223,43 +223,43 @@ teams app doctor | **Bot handle** | 你的机器人名称，例如 `openclaw-msteams`（必须唯一） | | **Subscription** | 选择你的 Azure 订阅 | | **Resource group** | 新建或使用现有资源组 | - | **Pricing tier** | 开发/测试请选择 **Free** | + | **Pricing tier** | 开发/测试使用 **Free** | | **Type of App** | **Single Tenant**（推荐——见下方说明） | | **Creation type** | **Create new Microsoft App ID** | -在 2025-07-31 之后，新的多租户机器人创建已被弃用。新机器人请使用 **Single Tenant**。 +新建多租户机器人的功能在 2025-07-31 之后已弃用。新机器人请使用 **Single Tenant**。 -3. 点击 **Review + create** → **Create**（等待约 1–2 分钟） +3. 点击 **Review + create** → **Create**（等待约 1-2 分钟） -### 第 2 步：获取凭据 +### 第 2 步：获取凭证 1. 前往你的 Azure Bot 资源 → **Configuration** 2. 复制 **Microsoft App ID** → 这就是你的 `appId` 3. 点击 **Manage Password** → 进入 App Registration -4. 在 **Certificates & secrets** 下点击 **New client secret** → 复制 **Value** → 这就是你的 `appPassword` +4. 在 **Certificates & secrets** 下 → **New client secret** → 复制 **Value** → 这就是你的 `appPassword` 5. 前往 **Overview** → 复制 **Directory (tenant) ID** → 这就是你的 `tenantId` ### 第 3 步：配置消息端点 -1. 在 Azure Bot 中进入 **Configuration** +1. 在 Azure Bot 中 → **Configuration** 2. 将 **Messaging endpoint** 设置为你的 webhook URL： - 生产环境：`https://your-domain.com/api/messages` - - 本地开发：使用隧道（见下方[本地开发](#local-development-tunneling)） + - 本地开发：使用隧道（参见下方[本地开发](#local-development-tunneling)） ### 第 4 步：启用 Teams 渠道 -1. 在 Azure Bot 中进入 **Channels** +1. 在 Azure Bot 中 → **Channels** 2. 点击 **Microsoft Teams** → Configure → Save 3. 接受服务条款 -### 第 5 步：构建 Teams 应用清单 +### 第 5 步：构建 Teams 应用 Manifest - 包含一个 `bot` 条目，并设置 `botId = `。 -- 范围：`personal`、`team`、`groupChat`。 -- `supportsFiles: true`（个人范围文件处理所必需）。 -- 添加 RSC 权限（参见 [RSC 权限](#current-teams-rsc-permissions-manifest)）。 +- 作用域：`personal`、`team`、`groupChat`。 +- `supportsFiles: true`（个人作用域文件处理所必需）。 +- 添加 RSC 权限（参见[当前 Teams RSC 权限 Manifest](#current-teams-rsc-permissions-manifest)）。 - 创建图标：`outline.png`（32x32）和 `color.png`（192x192）。 - 将这三个文件一起打包为 zip：`manifest.json`、`outline.png`、`color.png`。 @@ -283,23 +283,23 @@ teams app doctor ### 第 7 步：运行 Gateway 网关 -当插件可用且存在带凭据的 `msteams` 配置时，Teams 渠道会自动启动。 +当插件可用且存在带凭证的 `msteams` 配置时，Teams 渠道会自动启动。 -## 联合身份验证（证书 + 托管身份） +## 联合身份验证（证书加托管身份） > 添加于 2026.3.24 -对于生产部署，OpenClaw 支持使用**联合身份验证**作为客户端密钥之外更安全的替代方案。提供两种方法： +对于生产部署，OpenClaw 支持 **联合身份验证** 作为客户端密钥之外更安全的替代方案。提供两种方式： ### 选项 A：基于证书的身份验证 -使用在你的 Entra ID 应用注册中登记的 PEM 证书。 +使用注册到你的 Entra ID 应用注册中的 PEM 证书。 **设置：** -1. 生成或获取一个证书（包含私钥的 PEM 格式）。 +1. 生成或获取证书（包含私钥的 PEM 格式）。 2. 在 Entra ID → App Registration → **Certificates & secrets** → **Certificates** 中上传公钥证书。 **配置：** @@ -324,24 +324,24 @@ teams app doctor - `MSTEAMS_AUTH_TYPE=federated` - `MSTEAMS_CERTIFICATE_PATH=/path/to/cert.pem` -### 选项 B：Azure 托管身份 +### 选项 B：Azure Managed Identity -使用 Azure 托管身份实现无密码身份验证。这非常适合部署在具备托管身份的 Azure 基础设施（AKS、App Service、Azure VM）上的场景。 +使用 Azure Managed Identity 实现无密码身份验证。这非常适合部署在 Azure 基础设施上的场景（AKS、App Service、Azure VM），这些环境中可提供托管身份。 **工作原理：** -1. 机器人所在的 pod/VM 拥有托管身份（系统分配或用户分配）。 -2. 一个**联合身份凭据**将该托管身份关联到 Entra ID 应用注册。 -3. 在运行时，OpenClaw 使用 `@azure/identity` 从 Azure IMDS 端点（`169.254.169.254`）获取令牌。 +1. 机器人 pod/VM 拥有一个托管身份（系统分配或用户分配）。 +2. 一个 **联合身份凭证** 将该托管身份关联到 Entra ID 应用注册。 +3. 运行时，OpenClaw 使用 `@azure/identity` 从 Azure IMDS 端点（`169.254.169.254`）获取令牌。 4. 该令牌会传递给 Teams SDK 用于机器人身份验证。 -**前置条件：** +**前提条件：** - 已启用托管身份的 Azure 基础设施（AKS workload identity、App Service、VM） -- 已在 Entra ID 应用注册上创建联合身份凭据 -- pod/VM 可通过网络访问 IMDS（`169.254.169.254:80`） +- 已在 Entra ID 应用注册上创建联合身份凭证 +- pod/VM 可网络访问 IMDS（`169.254.169.254:80`） -**配置（系统分配的托管身份）：** +**配置（系统分配托管身份）：** ```json5 { @@ -358,7 +358,7 @@ teams app doctor } ``` -**配置（用户分配的托管身份）：** +**配置（用户分配托管身份）：** ```json5 { @@ -380,14 +380,14 @@ teams app doctor - `MSTEAMS_AUTH_TYPE=federated` - `MSTEAMS_USE_MANAGED_IDENTITY=true` -- `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID=`（仅适用于用户分配的托管身份） +- `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID=`（仅用于用户分配） ### AKS Workload Identity 设置 对于使用 workload identity 的 AKS 部署： 1. 在你的 AKS 集群上**启用 workload identity**。 -2. 在 Entra ID 应用注册上**创建联合身份凭据**： +2. 在 Entra ID 应用注册上**创建联合身份凭证**： ```bash az ad app federated-credential create --id --parameters '{ @@ -409,7 +409,7 @@ teams app doctor azure.workload.identity/client-id: "" ``` -4. 为 **pod 添加标签**，以启用 workload identity 注入： +4. 为 **pod 添加标签** 以启用 workload identity 注入： ```yaml metadata: @@ -417,21 +417,21 @@ teams app doctor azure.workload.identity/use: "true" ``` -5. **确保可以通过网络访问** IMDS（`169.254.169.254`）——如果你使用 NetworkPolicy，请添加一条出口规则，允许访问 `169.254.169.254/32` 的 80 端口流量。 +5. **确保可访问 IMDS**（`169.254.169.254`）——如果使用 `NetworkPolicy`，请添加一条出口规则，允许到 `169.254.169.254/32` 的 80 端口流量。 -### 身份验证类型对比 +### authType 对比 | 方法 | 配置 | 优点 | 缺点 | | -------------------- | ---------------------------------------------- | ---------------------------------- | ------------------------------------- | | **客户端密钥** | `appPassword` | 设置简单 | 需要轮换密钥，安全性较低 | -| **证书** | `authType: "federated"` + `certificatePath` | 无需通过网络共享密钥 | 证书管理有额外开销 | -| **托管身份** | `authType: "federated"` + `useManagedIdentity` | 无密码，无需管理密钥 | 需要 Azure 基础设施 | +| **证书** | `authType: "federated"` + `certificatePath` | 网络中不传输共享密钥 | 证书管理有额外开销 | +| **Managed Identity** | `authType: "federated"` + `useManagedIdentity` | 无密码，无需管理密钥 | 需要 Azure 基础设施 | -**默认行为：**当未设置 `authType` 时，OpenClaw 默认使用客户端密钥身份验证。现有配置无需更改即可继续工作。 +**默认行为：** 当未设置 `authType` 时，OpenClaw 默认使用客户端密钥身份验证。现有配置无需修改即可继续使用。 ## 本地开发（隧道） -Teams 无法访问 `localhost`。请使用持久化开发隧道，以便你的 URL 在不同会话之间保持不变： +Teams 无法访问 `localhost`。请使用持久化开发隧道，这样你的 URL 在不同会话之间保持不变： ```bash # 一次性设置： @@ -458,17 +458,17 @@ teams app update --endpoint "https:///api/messages" teams app doctor ``` -它会一次性检查机器人注册、AAD 应用、清单和 SSO 配置。 +它会一次性检查机器人注册、AAD 应用、manifest 和 SSO 配置。 **发送测试消息：** 1. 安装 Teams 应用（使用 `teams app get --install-link` 返回的安装链接） 2. 在 Teams 中找到该机器人并发送一条私信 -3. 检查 Gateway 网关日志中的传入活动 +3. 检查 Gateway 网关 日志中的传入 activity ## 环境变量 -所有配置键也都可以通过环境变量设置： +所有配置键也可以通过环境变量设置： - `MSTEAMS_APP_ID` - `MSTEAMS_APP_PASSWORD` @@ -477,31 +477,31 @@ teams app doctor - `MSTEAMS_CERTIFICATE_PATH`（联合身份验证 + 证书） - `MSTEAMS_CERTIFICATE_THUMBPRINT`（可选，身份验证不要求） - `MSTEAMS_USE_MANAGED_IDENTITY`（联合身份验证 + 托管身份） -- `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID`（仅适用于用户分配的托管身份） +- `MSTEAMS_MANAGED_IDENTITY_CLIENT_ID`（仅用户分配的 MI） ## 成员信息操作 -OpenClaw 为 Microsoft Teams 提供了一个基于 Graph 的 `member-info` 操作，使智能体和自动化流程可以直接从 Microsoft Graph 解析渠道成员详情（显示名称、电子邮件、角色）。 +OpenClaw 为 Microsoft Teams 提供了基于 Graph 的 `member-info` 操作，因此智能体和自动化可以直接从 Microsoft Graph 解析渠道成员详情（显示名称、邮箱、角色）。 要求： -- `Member.Read.Group` RSC 权限（已包含在推荐清单中） -- 对于跨团队查询：具有管理员同意的 `User.Read.All` Graph 应用权限 +- `Member.Read.Group` RSC 权限（已包含在推荐的 manifest 中） +- 对于跨团队查询：需要 `User.Read.All` Graph 应用程序权限并已授予管理员同意 -该操作受 `channels.msteams.actions.memberInfo` 控制（默认：当 Graph 凭据可用时启用）。 +该操作受 `channels.msteams.actions.memberInfo` 控制（默认：当 Graph 凭证可用时启用）。 ## 历史上下文 -- `channels.msteams.historyLimit` 控制会被包装进提示词的最近渠道/群组消息数量。 +- `channels.msteams.historyLimit` 控制会包装进提示中的最近渠道/群组消息数量。 - 回退到 `messages.groupChat.historyLimit`。设置为 `0` 可禁用（默认值为 50）。 -- 拉取到的线程历史会按发送者 allowlist（`allowFrom` / `groupAllowFrom`）进行过滤，因此线程上下文播种仅包含来自允许发送者的消息。 -- 引用的附件上下文（从 Teams 回复 HTML 派生的 `ReplyTo*`）当前会按接收时的原样传递。 -- 换句话说，allowlist 控制谁可以触发智能体；目前只有特定的补充上下文路径会被过滤。 -- 私信历史可以通过 `channels.msteams.dmHistoryLimit`（用户轮次）进行限制。每用户覆盖：`channels.msteams.dms[""].historyLimit`。 +- 获取到的线程历史会按发送者允许列表（`allowFrom` / `groupAllowFrom`）进行过滤，因此线程上下文预填充目前只包含来自允许发送者的消息。 +- 引用附件上下文（从 Teams 回复 HTML 派生的 `ReplyTo*`）当前会按接收时的原样传递。 +- 换句话说，允许列表会控制谁可以触发智能体；当前只有特定的补充上下文路径会被过滤。 +- 私信历史可通过 `channels.msteams.dmHistoryLimit`（用户轮次）限制。按用户覆盖：`channels.msteams.dms[""].historyLimit`。 -## 当前 Teams RSC 权限（清单） +## 当前 Teams RSC 权限（manifest） -这些是我们 Teams 应用清单中**现有的 resourceSpecific 权限**。它们仅在安装该应用的团队/聊天内部生效。 +这些是我们 Teams 应用 manifest 中**现有的 resourceSpecific 权限**。它们仅在安装了应用的团队/聊天内部生效。 **对于渠道（团队范围）：** @@ -517,15 +517,15 @@ OpenClaw 为 Microsoft Teams 提供了一个基于 Graph 的 `member-info` 操 - `ChatMessage.Read.Chat`（Application）- 无需 @mention 即可接收所有群聊消息 -通过 Teams CLI 添加 RSC 权限： +若要通过 Teams CLI 添加 RSC 权限： ```bash teams app rsc add ChannelMessage.Read.Group --type Application ``` -## Teams 清单示例（已脱敏） +## 示例 Teams manifest（已脱敏） -包含必需字段的最小有效示例。请替换其中的 ID 和 URL。 +包含所需字段的最小有效示例。请替换其中的 ID 和 URL。 ```json5 { @@ -573,41 +573,41 @@ teams app rsc add ChannelMessage.Read.Group --type Application } ``` -### 清单注意事项（必备字段） +### Manifest 注意事项（必需字段） -- `bots[].botId` **必须**与 Azure Bot App ID 一致。 -- `webApplicationInfo.id` **必须**与 Azure Bot App ID 一致。 -- `bots[].scopes` 必须包含你计划使用的表面（`personal`、`team`、`groupChat`）。 -- `bots[].supportsFiles: true` 是个人范围中文件处理的必需项。 +- `bots[].botId` **必须**与 Azure Bot App ID 匹配。 +- `webApplicationInfo.id` **必须**与 Azure Bot App ID 匹配。 +- `bots[].scopes` 必须包含你计划使用的界面范围（`personal`、`team`、`groupChat`）。 +- `bots[].supportsFiles: true` 是个人范围文件处理所必需的。 - 如果你希望处理渠道流量，`authorization.permissions.resourceSpecific` 必须包含渠道读取/发送权限。 ### 更新现有应用 -要更新一个已安装的 Teams 应用（例如添加 RSC 权限）： +若要更新一个已经安装的 Teams 应用（例如添加 RSC 权限）： ```bash -# 下载、编辑并重新上传清单 +# 下载、编辑并重新上传 manifest teams app manifest download manifest.json # 在本地编辑 manifest.json... teams app manifest upload manifest.json # 如果内容发生变化，版本号会自动递增 ``` -更新后，请在每个团队中重新安装该应用，以使新权限生效，并且**彻底退出并重新启动 Teams**（而不仅仅是关闭窗口），以清除缓存的应用元数据。 +更新后，请在每个团队中重新安装该应用，以使新权限生效，并且要**完全退出并重新启动 Teams**（而不只是关闭窗口），以清除缓存的应用元数据。
-手动更新清单（不使用 CLI） +手动更新 manifest（不使用 CLI） -1. 使用新设置更新你的 `manifest.json` +1. 用新设置更新你的 `manifest.json` 2. **递增 `version` 字段**（例如 `1.0.0` → `1.1.0`） -3. **重新打包 zip**，包含清单和图标（`manifest.json`、`outline.png`、`color.png`） +3. **重新打包为 zip**，包含 manifest 和图标（`manifest.json`、`outline.png`、`color.png`） 4. 上传新的 zip： - - **Teams 管理中心：**Teams apps → Manage apps → 找到你的应用 → Upload new version - - **旁加载：**在 Teams 中 → Apps → Manage your apps → Upload a custom app + - **Teams Admin Center：** Teams apps → Manage apps → 找到你的应用 → Upload new version + - **旁加载：** 在 Teams 中 → Apps → Manage your apps → Upload a custom app
-## 功能：仅 RSC 与 Graph 的区别 +## 功能：仅 RSC 与 Graph ### 仅使用 **Teams RSC**（已安装应用，无 Graph API 权限） @@ -619,13 +619,13 @@ teams app manifest upload manifest.json 不可用： -- 渠道/群组中的**图片或文件内容**（负载仅包含 HTML 占位内容）。 +- 渠道/群组中的**图片或文件内容**（payload 仅包含 HTML 占位内容）。 - 下载存储在 SharePoint/OneDrive 中的附件。 -- 读取消息历史（超出实时 webhook 事件范围）。 +- 读取消息历史（超出实时 webhook 事件范围的部分）。 -### 使用 **Teams RSC + Microsoft Graph 应用权限** +### 使用 **Teams RSC + Microsoft Graph 应用程序权限** -可额外获得： +额外支持： - 下载托管内容（粘贴到消息中的图片）。 - 下载存储在 SharePoint/OneDrive 中的文件附件。 @@ -633,82 +633,82 @@ teams app manifest upload manifest.json ### RSC 与 Graph API -| 功能 | RSC 权限 | Graph API | +| 能力 | RSC 权限 | Graph API | | ----------------------- | -------------------- | ----------------------------------- | | **实时消息** | 是（通过 webhook） | 否（仅轮询） | | **历史消息** | 否 | 是（可查询历史） | -| **设置复杂度** | 仅应用清单 | 需要管理员同意 + 令牌流程 | -| **离线可用** | 否（必须运行中） | 是（可随时查询） | +| **设置复杂度** | 仅应用 manifest | 需要管理员同意 + 令牌流程 | +| **离线可用** | 否（必须在运行中） | 是（可随时查询） | -**结论：**RSC 用于实时监听；Graph API 用于历史访问。如果你想在离线期间补拉错过的消息，则需要带有 `ChannelMessage.Read.All` 的 Graph API（需要管理员同意）。 +**结论：** RSC 用于实时监听；Graph API 用于访问历史记录。如果你希望在离线时补回错过的消息，则需要使用具备 `ChannelMessage.Read.All` 的 Graph API（需要管理员同意）。 ## 启用 Graph 的媒体 + 历史记录（渠道必需） -如果你需要处理**渠道**中的图片/文件，或者希望拉取**消息历史**，则必须启用 Microsoft Graph 权限并授予管理员同意。 +如果你在**渠道**中需要图片/文件，或者想获取**消息历史记录**，则必须启用 Microsoft Graph 权限并授予管理员同意。 -1. 在 Entra ID（Azure AD）**应用注册**中，添加 Microsoft Graph **应用权限**： - - `ChannelMessage.Read.All`（渠道附件 + 历史） +1. 在 Entra ID（Azure AD）**应用注册**中添加 Microsoft Graph **应用程序权限**： + - `ChannelMessage.Read.All`（渠道附件 + 历史记录） - `Chat.Read.All` 或 `ChatMessage.Read.All`（群聊） 2. 为租户**授予管理员同意**。 -3. 递增 Teams 应用**清单版本**，重新上传，并在 Teams 中**重新安装应用**。 -4. **彻底退出并重新启动 Teams**，以清除缓存的应用元数据。 +3. 递增 Teams 应用 **manifest 版本**，重新上传，并在 Teams 中**重新安装应用**。 +4. **完全退出并重新启动 Teams**，以清除缓存的应用元数据。 -**用户提及所需的额外权限：**对话中的用户 @mention 开箱即用。不过，如果你想动态搜索并提及**当前对话之外**的用户，请添加 `User.Read.All`（Application）权限并授予管理员同意。 +**用户提及的额外权限：** 对于当前会话中的用户，用户 @mentions 可直接使用。但是，如果你想动态搜索并提及**当前会话之外**的用户，请添加 `User.Read.All`（Application）权限并授予管理员同意。 ## 已知限制 ### Webhook 超时 -Teams 通过 HTTP webhook 投递消息。如果处理耗时过长（例如 LLM 响应较慢），你可能会看到： +Teams 通过 HTTP webhook 传递消息。如果处理耗时过长（例如 LLM 响应较慢），你可能会看到： -- Gateway 网关超时 +- Gateway 网关 超时 - Teams 重试消息（导致重复） - 回复丢失 -OpenClaw 通过快速返回并主动发送回复来处理这一问题，但响应非常慢时仍可能出现问题。 +OpenClaw 通过快速返回并主动发送回复来处理这个问题，但在响应非常慢时仍可能出现问题。 ### 格式化 -Teams 的 markdown 能力比 Slack 或 Discord 更有限： +Teams markdown 的能力比 Slack 或 Discord 更有限： -- 基本格式可用：**粗体**、_斜体_、`code`、链接 +- 基础格式可用：**粗体**、_斜体_、`code`、链接 - 复杂 markdown（表格、嵌套列表）可能无法正确渲染 -- 支持使用 Adaptive Cards 发送投票和语义化展示内容（见下文） +- 支持将 Adaptive Cards 用于投票和语义化展示发送（见下文） ## 配置 关键设置（共享渠道模式参见 `/gateway/configuration`）： - `channels.msteams.enabled`：启用/禁用该渠道。 -- `channels.msteams.appId`、`channels.msteams.appPassword`、`channels.msteams.tenantId`：机器人凭据。 +- `channels.msteams.appId`、`channels.msteams.appPassword`、`channels.msteams.tenantId`：机器人凭证。 - `channels.msteams.webhook.port`（默认 `3978`） - `channels.msteams.webhook.path`（默认 `/api/messages`） - `channels.msteams.dmPolicy`：`pairing | allowlist | open | disabled`（默认：pairing） -- `channels.msteams.allowFrom`：私信 allowlist（推荐使用 AAD 对象 ID）。当 Graph 访问可用时，向导会在设置期间将名称解析为 ID。 -- `channels.msteams.dangerouslyAllowNameMatching`：紧急开关，用于重新启用可变的 UPN/显示名称匹配和直接的团队/渠道名称路由。 +- `channels.msteams.allowFrom`：私信允许列表（推荐使用 AAD 对象 ID）。当 Graph 访问可用时，向导会在设置期间将名称解析为 ID。 +- `channels.msteams.dangerouslyAllowNameMatching`：紧急开关，用于重新启用可变的 UPN/显示名称匹配和直接团队/渠道名称路由。 - `channels.msteams.textChunkLimit`：出站文本分块大小。 -- `channels.msteams.chunkMode`：`length`（默认）或 `newline`，先按空行（段落边界）拆分，再按长度分块。 -- `channels.msteams.mediaAllowHosts`：入站附件主机 allowlist（默认包含 Microsoft/Teams 域名）。 -- `channels.msteams.mediaAuthAllowHosts`：媒体重试时附加 Authorization 标头的主机 allowlist（默认包含 Graph + Bot Framework 主机）。 +- `channels.msteams.chunkMode`：`length`（默认）或 `newline`，可先按空行（段落边界）拆分，再按长度分块。 +- `channels.msteams.mediaAllowHosts`：传入附件主机允许列表（默认为 Microsoft/Teams 域名）。 +- `channels.msteams.mediaAuthAllowHosts`：媒体重试时附加 Authorization 头的主机允许列表（默认为 Graph + Bot Framework 主机）。 - `channels.msteams.requireMention`：在渠道/群组中要求 @mention（默认 true）。 - `channels.msteams.replyStyle`：`thread | top-level`（参见[回复样式](#reply-style-threads-vs-posts)）。 - `channels.msteams.teams..replyStyle`：按团队覆盖。 - `channels.msteams.teams..requireMention`：按团队覆盖。 -- `channels.msteams.teams..tools`：按团队设置默认工具策略覆盖（`allow`/`deny`/`alsoAllow`），当缺少渠道覆盖时使用。 +- `channels.msteams.teams..tools`：按团队的默认工具策略覆盖（`allow`/`deny`/`alsoAllow`），当缺少渠道覆盖时使用。 - `channels.msteams.teams..toolsBySender`：按团队、按发送者的默认工具策略覆盖（支持 `"*"` 通配符）。 - `channels.msteams.teams..channels..replyStyle`：按渠道覆盖。 - `channels.msteams.teams..channels..requireMention`：按渠道覆盖。 - `channels.msteams.teams..channels..tools`：按渠道的工具策略覆盖（`allow`/`deny`/`alsoAllow`）。 - `channels.msteams.teams..channels..toolsBySender`：按渠道、按发送者的工具策略覆盖（支持 `"*"` 通配符）。 - `toolsBySender` 键应使用显式前缀： - `id:`、`e164:`、`username:`、`name:`（旧版无前缀键仍只映射到 `id:`）。 -- `channels.msteams.actions.memberInfo`：启用或禁用基于 Graph 的成员信息操作（默认：当 Graph 凭据可用时启用）。 + `id:`、`e164:`、`username:`、`name:`（旧版无前缀键仍仅映射到 `id:`）。 +- `channels.msteams.actions.memberInfo`：启用或禁用基于 Graph 的成员信息操作（默认：当 Graph 凭证可用时启用）。 - `channels.msteams.authType`：身份验证类型——`"secret"`（默认）或 `"federated"`。 - `channels.msteams.certificatePath`：PEM 证书文件路径（联合身份验证 + 证书身份验证）。 - `channels.msteams.certificateThumbprint`：证书指纹（可选，身份验证不要求）。 - `channels.msteams.useManagedIdentity`：启用托管身份验证（联合模式）。 - `channels.msteams.managedIdentityClientId`：用户分配托管身份的客户端 ID。 -- `channels.msteams.sharePointSiteId`：用于群聊/渠道文件上传的 SharePoint 站点 ID（参见[在群聊中发送文件](#sending-files-in-group-chats)）。 +- `channels.msteams.sharePointSiteId`：用于群聊/渠道中文件上传的 SharePoint 站点 ID（参见[在群聊中发送文件](#sending-files-in-group-chats)）。 ## 路由与会话 @@ -720,19 +720,19 @@ Teams 的 markdown 能力比 Slack 或 Discord 更有限： ## 回复样式：线程与帖子 -Teams 最近在相同的底层数据模型之上引入了两种渠道 UI 样式： +Teams 最近在同一底层数据模型上引入了两种渠道 UI 样式： -| 样式 | 描述 | 推荐的 `replyStyle` | +| 样式 | 描述 | 推荐 `replyStyle` | | ------------------------ | --------------------------------------------------------- | ------------------------ | -| **Posts**（经典） | 消息显示为卡片，其下方带有线程回复 | `thread`（默认） | +| **Posts**（经典） | 消息显示为卡片，下方带有线程回复 | `thread`（默认） | | **Threads**（类似 Slack） | 消息线性流动，更像 Slack | `top-level` | -**问题在于：**Teams API 不会暴露某个渠道使用的是哪种 UI 样式。如果你使用了错误的 `replyStyle`： +**问题：** Teams API 不会暴露某个渠道使用的是哪种 UI 样式。如果你使用了错误的 `replyStyle`： - 在 Threads 样式的渠道中使用 `thread` → 回复会以不自然的嵌套方式显示 -- 在 Posts 样式的渠道中使用 `top-level` → 回复会作为独立的顶层帖子显示，而不是在线程中显示 +- 在 Posts 样式的渠道中使用 `top-level` → 回复会显示为独立的顶层帖子，而不是在线程中 -**解决方案：**根据渠道的设置，按渠道配置 `replyStyle`： +**解决方案：** 根据渠道的实际设置按渠道配置 `replyStyle`： ```json5 { @@ -757,13 +757,13 @@ Teams 最近在相同的底层数据模型之上引入了两种渠道 UI 样式 **当前限制：** -- **私信：**图片和文件附件可通过 Teams 机器人文件 API 工作。 -- **渠道/群组：**附件存储在 M365 存储（SharePoint/OneDrive）中。webhook 负载仅包含 HTML 占位内容，不包含实际文件字节。**下载渠道附件需要 Graph API 权限**。 -- 对于显式的优先发送文件场景，使用 `action=upload-file` 并搭配 `media` / `filePath` / `path`；可选的 `message` 会作为附带文本/评论，`filename` 会覆盖上传名称。 +- **私信：** 图片和文件附件可通过 Teams 机器人文件 API 工作。 +- **渠道/群组：** 附件存储在 M365 存储中（SharePoint/OneDrive）。webhook payload 只包含 HTML 占位内容，不包含实际文件字节。**下载渠道附件需要 Graph API 权限**。 +- 对于显式的文件优先发送，使用 `action=upload-file`，并搭配 `media` / `filePath` / `path`；可选的 `message` 会作为附带文本/评论，`filename` 会覆盖上传名称。 -如果没有 Graph 权限，带有图片的渠道消息将仅作为文本接收（机器人无法访问图片内容）。 +如果没有 Graph 权限，带图片的渠道消息将作为纯文本接收（机器人无法访问图片内容）。 默认情况下，OpenClaw 仅从 Microsoft/Teams 主机名下载媒体。可通过 `channels.msteams.mediaAllowHosts` 覆盖（使用 `["*"]` 可允许任意主机）。 -Authorization 标头仅会附加到 `channels.msteams.mediaAuthAllowHosts` 中的主机（默认包含 Graph + Bot Framework 主机）。请保持该列表严格受限（避免使用多租户后缀）。 +Authorization 头只会附加到 `channels.msteams.mediaAuthAllowHosts` 中的主机（默认为 Graph + Bot Framework 主机）。请保持此列表严格（避免多租户后缀）。 ## 在群聊中发送文件 @@ -777,28 +777,28 @@ Authorization 标头仅会附加到 `channels.msteams.mediaAuthAllowHosts` 中 ### 为什么群聊需要 SharePoint -机器人没有个人 OneDrive 驱动器（`/me/drive` Graph API 端点不适用于应用身份）。要在群聊/渠道中发送文件，机器人会上传到一个 **SharePoint 站点** 并创建共享链接。 +机器人没有个人 OneDrive drive（`/me/drive` Graph API 端点不适用于应用程序身份）。要在群聊/渠道中发送文件，机器人会上传到一个 **SharePoint 站点** 并创建共享链接。 ### 设置 -1. 在 Entra ID（Azure AD）→ App Registration 中添加 **Graph API 权限**： +1. 在 Entra ID（Azure AD）→ App Registration 中**添加 Graph API 权限**： - `Sites.ReadWrite.All`（Application）- 上传文件到 SharePoint - - `Chat.Read.All`（Application）- 可选，启用按用户的共享链接 + - `Chat.Read.All`（Application）- 可选，启用按用户共享链接 2. 为租户**授予管理员同意**。 3. **获取你的 SharePoint 站点 ID：** ```bash - # 通过 Graph Explorer 或携带有效令牌的 curl： + # 通过 Graph Explorer 或带有效令牌的 curl： curl -H "Authorization: Bearer $TOKEN" \ "https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-path}" - # 示例：对于位于 "contoso.sharepoint.com/sites/BotFiles" 的站点 + # 示例：对于站点 "contoso.sharepoint.com/sites/BotFiles" curl -H "Authorization: Bearer $TOKEN" \ "https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/BotFiles" - # 响应中包含： "id": "contoso.sharepoint.com,guid1,guid2" + # 响应包含："id": "contoso.sharepoint.com,guid1,guid2" ``` 4. **配置 OpenClaw：** @@ -818,10 +818,10 @@ Authorization 标头仅会附加到 `channels.msteams.mediaAuthAllowHosts` 中 | 权限 | 共享行为 | | --------------------------------------- | --------------------------------------------------------- | -| `Sites.ReadWrite.All` only | 组织范围共享链接（组织内任何人都可访问） | +| `Sites.ReadWrite.All` 仅有此项 | 组织范围共享链接（组织内任何人都可访问） | | `Sites.ReadWrite.All` + `Chat.Read.All` | 按用户共享链接（仅聊天成员可访问） | -按用户共享更安全，因为只有聊天参与者可以访问文件。如果缺少 `Chat.Read.All` 权限，机器人会回退到组织范围共享。 +按用户共享更安全，因为只有聊天参与者可以访问文件。如果缺少 `Chat.Read.All` 权限，机器人会回退为组织范围共享。 ### 回退行为 @@ -834,22 +834,22 @@ Authorization 标头仅会附加到 `channels.msteams.mediaAuthAllowHosts` 中 ### 文件存储位置 -上传的文件会存储在已配置 SharePoint 站点默认文档库中的 `/OpenClawShared/` 文件夹下。 +上传的文件存储在已配置 SharePoint 站点默认文档库中的 `/OpenClawShared/` 文件夹下。 ## 投票（Adaptive Cards） OpenClaw 将 Teams 投票作为 Adaptive Cards 发送（Teams 没有原生投票 API）。 - CLI：`openclaw message poll --channel msteams --target conversation: ...` -- 投票由 Gateway 网关记录在 `~/.openclaw/msteams-polls.json` 中。 -- Gateway 网关必须保持在线才能记录投票。 -- 目前投票不会自动发布结果摘要（如有需要，请检查存储文件）。 +- 投票结果由 Gateway 网关 记录在 `~/.openclaw/msteams-polls.json` 中。 +- Gateway 网关 必须保持在线才能记录投票。 +- 投票尚不会自动发布结果摘要（如有需要，请检查存储文件）。 ## 展示卡片 -使用 `message` 工具或 CLI，将语义化展示负载发送给 Teams 用户或会话。OpenClaw 会根据通用展示契约，将其渲染为 Teams Adaptive Cards。 +使用 `message` 工具或 CLI，将语义化展示 payload 发送给 Teams 用户或会话。OpenClaw 会根据通用展示契约将其渲染为 Teams Adaptive Cards。 -`presentation` 参数接受语义块。提供 `presentation` 时，消息文本可选。 +`presentation` 参数接受语义块。当提供 `presentation` 时，消息文本为可选项。 **智能体工具：** @@ -873,7 +873,7 @@ openclaw message send --channel msteams \ --presentation '{"title":"Hello","blocks":[{"type":"text","text":"Hello!"}]}' ``` -目标格式详情见下方的[目标格式](#target-formats)。 +有关目标格式的详细信息，参见下方的[目标格式](#target-formats)。 ## 目标格式 @@ -898,7 +898,7 @@ openclaw message send --channel msteams --target "user:John Smith" --message "He # 发送到群聊或渠道 openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" --message "Hello" -# 向会话发送展示卡片 +# 发送展示卡片到某个会话 openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" \ --presentation '{"title":"Hello","blocks":[{"type":"text","text":"Hello"}]}' ``` @@ -932,19 +932,19 @@ openclaw message send --channel msteams --target "conversation:19:abc...@thread. ## 主动消息 -- 只有在用户发生过交互**之后**，才可以发送主动消息，因为我们会在那时保存会话引用。 -- 关于 `dmPolicy` 和 allowlist 门控，请参见 `/gateway/configuration`。 +- 只有在用户交互**之后**才能发送主动消息，因为我们会在那时存储会话引用。 +- 有关 `dmPolicy` 和允许列表控制，参见 `/gateway/configuration`。 ## 团队和渠道 ID（常见陷阱） -Teams URL 中的 `groupId` 查询参数**不是**用于配置的团队 ID。请从 URL 路径中提取 ID： +Teams URL 中的 `groupId` 查询参数**不是**用于配置的团队 ID。请改为从 URL 路径中提取 ID： **团队 URL：** ``` https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=... └────────────────────────────┘ - Team ID（对此进行 URL 解码） + 团队 ID（对此进行 URL 解码） ``` **渠道 URL：** @@ -957,8 +957,8 @@ https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?gr **用于配置时：** -- Team ID = `/team/` 之后的路径段（URL 解码后，例如 `19:Bk4j...@thread.tacv2`） -- Channel ID = `/channel/` 之后的路径段（URL 解码后） +- 团队 ID = `/team/` 之后的路径片段（URL 解码后，例如 `19:Bk4j...@thread.tacv2`） +- 渠道 ID = `/channel/` 之后的路径片段（URL 解码后） - **忽略** `groupId` 查询参数 ## 私有渠道 @@ -968,41 +968,41 @@ https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?gr | 功能 | 标准渠道 | 私有渠道 | | ---------------------------- | ----------------- | ---------------------- | | 机器人安装 | 是 | 有限 | -| 实时消息（webhook） | 是 | 可能无法工作 | +| 实时消息（webhook） | 是 | 可能不可用 | | RSC 权限 | 是 | 行为可能不同 | | @mentions | 是 | 如果机器人可访问 | -| Graph API 历史记录 | 是 | 是（有相应权限时） | +| Graph API 历史记录 | 是 | 是（需要权限） | -**如果私有渠道无法工作，可使用以下替代方案：** +**如果私有渠道不可用，可尝试以下变通方法：** 1. 使用标准渠道进行机器人交互 2. 使用私信——用户始终可以直接向机器人发送消息 -3. 使用 Graph API 获取历史记录（需要 `ChannelMessage.Read.All`） +3. 使用 Graph API 访问历史记录（需要 `ChannelMessage.Read.All`） ## 故障排除 ### 常见问题 -- **渠道中不显示图片：**缺少 Graph 权限或管理员同意。重新安装 Teams 应用，并彻底退出/重新打开 Teams。 -- **渠道中没有响应：**默认需要提及；设置 `channels.msteams.requireMention=false` 或按团队/渠道配置。 -- **版本不匹配（Teams 仍显示旧清单）：**移除并重新添加该应用，然后彻底退出 Teams 以刷新。 -- **webhook 返回 401 Unauthorized：**如果你在没有 Azure JWT 的情况下手动测试，这是预期行为——表示端点可达，但身份验证失败。请使用 Azure Web Chat 进行正确测试。 +- **渠道中不显示图片：** 缺少 Graph 权限或管理员同意。重新安装 Teams 应用，并完全退出/重新打开 Teams。 +- **渠道中没有响应：** 默认要求 mention；请设置 `channels.msteams.requireMention=false`，或按团队/渠道进行配置。 +- **版本不匹配（Teams 仍显示旧 manifest）：** 删除后重新添加应用，并完全退出 Teams 以刷新。 +- **webhook 返回 401 Unauthorized：** 手动测试时未携带 Azure JWT，出现这种情况是预期行为——说明端点可达，但身份验证失败。请使用 Azure Web Chat 进行正确测试。 -### 清单上传错误 +### Manifest 上传错误 -- **“Icon file cannot be empty”：**清单引用的图标文件为 0 字节。请创建有效的 PNG 图标（`outline.png` 为 32x32，`color.png` 为 192x192）。 -- **“webApplicationInfo.Id already in use”：**该应用仍安装在其他团队/聊天中。请先找到并卸载，或等待 5–10 分钟让更改传播。 -- **上传时出现 “Something went wrong”：**请改用 [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com) 上传，打开浏览器 DevTools（F12）→ Network 标签，并检查响应体中的实际错误。 -- **旁加载失败：**尝试使用 “Upload an app to your org's app catalog” 而不是 “Upload a custom app”——这通常可以绕过旁加载限制。 +- **“Icon file cannot be empty”：** manifest 引用了 0 字节的图标文件。请创建有效的 PNG 图标（`outline.png` 为 32x32，`color.png` 为 192x192）。 +- **“webApplicationInfo.Id already in use”：** 该应用仍安装在其他团队/聊天中。请先找到并卸载，或等待 5-10 分钟让更改传播。 +- **上传时出现 “Something went wrong”：** 请改为通过 [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com) 上传，打开浏览器开发者工具（F12）→ Network 标签页，并检查响应体中的实际错误。 +- **旁加载失败：** 尝试使用 “Upload an app to your org's app catalog” 而不是 “Upload a custom app”——这通常可以绕过旁加载限制。 ### RSC 权限不生效 -1. 验证 `webApplicationInfo.id` 是否与你机器人的 App ID 完全一致 -2. 重新上传应用并在团队/聊天中重新安装 +1. 确认 `webApplicationInfo.id` 与你的机器人 App ID 完全匹配 +2. 重新上传应用，并在团队/聊天中重新安装 3. 检查你的组织管理员是否阻止了 RSC 权限 -4. 确认你使用了正确的范围：团队使用 `ChannelMessage.Read.Group`，群聊使用 `ChatMessage.Read.Chat` +4. 确认你使用了正确的作用域：团队用 `ChannelMessage.Read.Group`，群聊用 `ChatMessage.Read.Chat` -## 参考资料 +## 参考 - [Create Azure Bot](https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration) - Azure Bot 设置指南 - [Teams Developer Portal](https://dev.teams.microsoft.com/apps) - 创建/管理 Teams 应用 @@ -1013,10 +1013,10 @@ https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?gr - [Proactive messaging](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages) - [@microsoft/teams.cli](https://www.npmjs.com/package/@microsoft/teams.cli) - 用于机器人管理的 Teams CLI -## 相关 +## 相关内容 - [Channels Overview](/zh-CN/channels) — 所有受支持的渠道 -- [Pairing](/zh-CN/channels/pairing) — 私信身份验证和配对流程 -- [Groups](/zh-CN/channels/groups) — 群聊行为和提及门控 +- [Pairing](/zh-CN/channels/pairing) — 私信身份验证与配对流程 +- [Groups](/zh-CN/channels/groups) — 群聊行为与提及控制 - [Channel Routing](/zh-CN/channels/channel-routing) — 消息的会话路由 -- [Security](/zh-CN/gateway/security) — 访问模型与加固 +- [Security](/zh-CN/gateway/security) — 访问模型与加固措施 diff --git a/docs/zh-CN/ci.md b/docs/zh-CN/ci.md index b44cb75bf..71254740a 100644 --- a/docs/zh-CN/ci.md +++ b/docs/zh-CN/ci.md @@ -1,60 +1,60 @@ --- read_when: - - 你需要了解某个 CI 作业为什么运行了或没有运行。 - - 你正在调试失败的 GitHub Actions 检查。 -summary: CI 作业图、范围门控，以及本地等效命令 + - 你需要了解某个 CI 作业为什么运行或没有运行 + - 你正在调试失败的 GitHub Actions 检查 +summary: CI 作业图、范围门禁和本地对应命令 title: CI 流水线 x-i18n: - generated_at: "2026-04-27T06:21:49Z" + generated_at: "2026-04-27T07:11:15Z" model: gpt-5.4 provider: openai - source_hash: 9cb69d2eaa44460963bf9b540cbeb2c87ca3802842ffcfdf98780f5d9062d5da + source_hash: 197ca6bd69f47fc26f8bee3f10c90fab75536cc46c0ca2350a02342d7a3a030c source_path: ci.md workflow: 15 --- -CI 会在每次推送到 `main` 以及每个拉取请求时运行。它使用智能范围控制，在只改动了不相关区域时跳过昂贵的作业。手动触发的 `workflow_dispatch` 运行会有意绕过智能范围控制，并展开完整的常规 CI 作业图，用于发布候选版本或大范围验证。 +CI 在每次推送到 `main` 以及每个拉取请求时都会运行。它使用智能范围界定，在只更改了不相关区域时跳过高开销作业。手动 `workflow_dispatch` 运行会有意绕过智能范围界定，并展开完整的常规 CI 作业图，用于发布候选版本或广泛验证。 -`Full Release Validation` 是“发布前运行所有内容”的手动总控工作流。它接受分支、标签或完整提交 SHA，使用该目标触发手动 `CI` 工作流，并触发 `OpenClaw Release Checks`，用于安装冒烟测试、软件包验收、Docker 发布路径测试套件、实时 / E2E、OpenWebUI、QA Lab 一致性、Matrix 和 Telegram 流水线。提供已发布的软件包规范时，它还可以运行发布后的 `NPM Telegram Beta E2E` 工作流。 +`Full Release Validation` 是“发布前运行所有内容”的手动总工作流。它接受分支、标签或完整提交 SHA，使用该目标派发手动 `CI` 工作流，并派发 `OpenClaw Release Checks`，用于安装冒烟测试、包验收、Docker 发布路径测试套件、live/E2E、OpenWebUI、QA Lab 一致性、Matrix 和 Telegram 相关流程。当提供已发布的包规范时，它还可以运行发布后的 `NPM Telegram Beta E2E` 工作流。 -`Package Acceptance` 是一个侧边运行工作流，用于验证软件包工件，而不会阻塞发布工作流。它会从已发布的 npm 规范、使用所选 `workflow_ref` harness 构建的可信 `package_ref`、带 SHA-256 的 HTTPS tarball URL，或来自其他 GitHub Actions 运行的 tarball 工件中解析出一个候选包，将其上传为 `package-under-test`，然后复用 Docker 发布 / E2E 调度器，对该 tarball 进行测试，而不是重新打包工作流检出的内容。其配置文件涵盖 smoke、package、product、full 和自定义 Docker 流水线选择。`package` 配置文件使用离线插件覆盖，因此已发布软件包的验证不会受 live ClawHub 可用性影响。可选的 Telegram 流水线会在 `NPM Telegram Beta E2E` 工作流中复用 `package-under-test` 工件，而已发布 npm 规范路径仍保留用于独立触发场景。 +`Package Acceptance` 是用于验证包产物的旁路工作流，不会阻塞发布工作流。它可从以下来源解析单个候选项：已发布的 npm 规范、使用所选 `workflow_ref` harness 构建的可信 `package_ref`、带有 SHA-256 的 HTTPS tarball URL，或来自其他 GitHub Actions 运行的 tarball 产物；然后将其上传为 `package-under-test`，并复用 Docker 发布 / E2E 调度器，使用该 tarball 而不是重新打包工作流检出内容。其配置文件涵盖 smoke、package、product、full 以及自定义 Docker 流程选择。`package` 配置文件使用离线插件覆盖，因此已发布包的验证不依赖 live ClawHub 可用性。可选的 Telegram 流程会在 `NPM Telegram Beta E2E` 工作流中复用 `package-under-test` 产物，而已发布 npm 规范路径仍保留给独立派发使用。 -## Package Acceptance +## 包验收 -当问题是“这个可安装的 OpenClaw 软件包作为产品是否可用？”时，请使用 `Package Acceptance`。它不同于常规 CI：常规 CI 验证的是源代码树，而软件包验收验证的是单个 tarball，通过与用户在安装或更新后实际经历相同的 Docker E2E harness 进行测试。 +当问题是“这个可安装的 OpenClaw 包作为产品是否可用？”时，请使用 `Package Acceptance`。它与常规 CI 不同：常规 CI 验证源码树，而包验收则通过用户在安装或更新后实际经历的同一套 Docker E2E harness 来验证单个 tarball。 -该工作流包含四个作业： +该工作流有四个作业： -1. `resolve_package` 检出 `workflow_ref`，解析一个软件包候选项，写入 `.artifacts/docker-e2e-package/openclaw-current.tgz`，写入 `.artifacts/docker-e2e-package/package-candidate.json`，将两者一起作为 `package-under-test` 工件上传，并在 GitHub 步骤摘要中输出来源、工作流引用、软件包引用、版本、SHA-256 和配置文件。 -2. `docker_acceptance` 调用 `openclaw-live-and-e2e-checks-reusable.yml`，并传入 `ref=workflow_ref` 和 `package_artifact_name=package-under-test`。这个可复用工作流会下载该工件，验证 tarball 清单，按需准备 package-digest Docker 镜像，并针对这个软件包运行所选 Docker 流水线，而不是打包工作流检出的内容。 -3. `package_telegram` 会按需调用 `NPM Telegram Beta E2E`。当 `telegram_mode` 不为 `none` 时，它会运行；如果 Package Acceptance 已解析出一个软件包，它会安装同一个 `package-under-test` 工件；独立的 Telegram 触发仍然可以安装已发布的 npm 规范。 -4. `summary` 会在软件包解析、Docker 验收或可选 Telegram 流水线失败时，使整个工作流失败。 +1. `resolve_package` 检出 `workflow_ref`，解析单个包候选项，写入 `.artifacts/docker-e2e-package/openclaw-current.tgz`，写入 `.artifacts/docker-e2e-package/package-candidate.json`，将二者作为 `package-under-test` 产物上传，并在 GitHub 步骤摘要中打印来源、工作流 ref、包 ref、版本、SHA-256 和配置文件。 +2. `docker_acceptance` 使用 `ref=workflow_ref` 和 `package_artifact_name=package-under-test` 调用 `openclaw-live-and-e2e-checks-reusable.yml`。该可复用工作流会下载该产物，验证 tarball 清单，按需准备 package-digest Docker 镜像，并针对该包运行所选 Docker 流程，而不是打包工作流检出内容。 +3. `package_telegram` 可选调用 `NPM Telegram Beta E2E`。当 `telegram_mode` 不为 `none` 时它会运行；如果 Package Acceptance 已解析出包，它会安装相同的 `package-under-test` 产物；独立的 Telegram 派发仍然可以安装已发布的 npm 规范。 +4. `summary` 会在包解析、Docker 验收或可选的 Telegram 流程失败时使整个工作流失败。 候选来源： -- `source=npm`：仅接受 `openclaw@beta`、`openclaw@latest`，或精确的 OpenClaw 发布版本，例如 `openclaw@2026.4.27-beta.2`。用于已发布 beta / stable 版本的验收。 -- `source=ref`：打包一个可信的 `package_ref` 分支、标签或完整提交 SHA。解析器会抓取 OpenClaw 分支 / 标签，验证所选提交可从仓库分支历史或发布标签到达，在分离工作树中安装依赖，并使用 `scripts/package-openclaw-for-docker.mjs` 打包。 -- `source=url`：下载一个 HTTPS `.tgz`；必须提供 `package_sha256`。 -- `source=artifact`：从 `artifact_run_id` 和 `artifact_name` 下载一个 `.tgz`。`package_sha256` 是可选的，但对于外部共享工件应当提供。 +- `source=npm`：仅接受 `openclaw@beta`、`openclaw@latest` 或精确的 OpenClaw 发布版本，例如 `openclaw@2026.4.27-beta.2`。用于已发布 beta / stable 的验收。 +- `source=ref`：打包可信的 `package_ref` 分支、标签或完整提交 SHA。解析器会获取 OpenClaw 分支 / 标签，验证所选提交可从仓库分支历史或发布标签到达，在分离工作树中安装依赖，并使用 `scripts/package-openclaw-for-docker.mjs` 进行打包。 +- `source=url`：下载 HTTPS `.tgz`；必须提供 `package_sha256`。 +- `source=artifact`：从 `artifact_run_id` 和 `artifact_name` 下载一个 `.tgz`；`package_sha256` 可选，但对于外部共享产物应当提供。 -请将 `workflow_ref` 和 `package_ref` 分开。`workflow_ref` 是运行测试的可信工作流 / harness 代码。`package_ref` 是在 `source=ref` 时被打包的源提交。这样，当前测试 harness 就可以验证较旧但可信的源提交，而无需运行旧的工作流逻辑。 +请将 `workflow_ref` 和 `package_ref` 分开理解。`workflow_ref` 是运行测试的可信工作流 / harness 代码。`package_ref` 是在 `source=ref` 时要被打包的源提交。这样可以让当前测试 harness 验证较旧但可信的源提交，而不必运行旧的工作流逻辑。 配置文件映射到 Docker 覆盖范围： - `smoke`：`npm-onboard-channel-agent`、`gateway-network`、`config-reload` - `package`：`npm-onboard-channel-agent`、`doctor-switch`、`update-channel-switch`、`bundled-channel-deps-compat`、`plugins-offline`、`plugin-update` -- `product`：`package`，外加 `mcp-channels`、`cron-mcp-cleanup`、`openai-web-search-minimal`、`openwebui` +- `product`：在 `package` 基础上增加 `mcp-channels`、`cron-mcp-cleanup`、`openai-web-search-minimal`、`openwebui` - `full`：带 OpenWebUI 的完整 Docker 发布路径分片 -- `custom`：精确的 `docker_lanes`；当 `suite_profile=custom` 时必填 +- `custom`：精确的 `docker_lanes`；当 `suite_profile=custom` 时为必填 -发布检查会以 `source=ref`、`package_ref=`、`workflow_ref=`、`suite_profile=package` 和 `telegram_mode=mock-openai` 调用 Package Acceptance。该配置文件是大多数 Parallels 软件包 / 更新验证的 GitHub 原生替代方案，其中 Telegram 会通过 QA 实时传输证明同一个软件包工件。跨 OS 发布检查仍然覆盖特定 OS 的新手引导、安装器和平台行为；软件包 / 更新的产品验证应当从 Package Acceptance 开始。 +发布检查会以 `source=ref`、`package_ref=`、`workflow_ref=`、`suite_profile=package` 和 `telegram_mode=mock-openai` 调用 Package Acceptance。该配置文件是大多数 Parallels 包 / 更新验证的 GitHub 原生替代方案，而 Telegram 会通过 QA live 传输证明同一个包产物。跨 OS 的发布检查仍覆盖 OS 特定的新手引导、安装器和平台行为；包 / 更新产品验证应从 Package Acceptance 开始。 -Package Acceptance 为已经发布的软件包提供一个有界的旧版兼容窗口，覆盖到 `2026.4.25`，包括 `2026.4.25-beta.*`。这些例外在这里记录，是为了防止它们变成永久性的静默跳过：如果 tarball 省略了这些文件，`dist/postinstall-inventory.json` 中已知的私有 QA 条目可能会发出警告；当软件包未暴露该标志时，`doctor-switch` 可能会跳过 `gateway install --wrapper` 持久化子场景；`update-channel-switch` 可能会从 tarball 派生的伪 git fixture 中裁剪缺失的 `pnpm.patchedDependencies`，并可能记录缺失的持久化 `update.channel`；插件冒烟测试可能会读取旧版安装记录位置，或接受缺失的 marketplace 安装记录持久化；而 `plugin-update` 可能允许配置元数据迁移，同时仍要求安装记录和无重新安装行为保持不变。`2026.4.25` 之后的软件包必须满足现代契约；相同条件将直接失败，而不是警告或跳过。 +Package Acceptance 为已发布且截至 `2026.4.25` 的包提供了一个有边界的旧版兼容窗口，包括 `2026.4.25-beta.*`。这些宽限规则在此记录，以避免它们变成永久性的静默跳过：如果 tarball 省略了已知的私有 QA 文件，`dist/postinstall-inventory.json` 中已知的私有 QA 条目可能会发出警告；当包未暴露该标志时，`doctor-switch` 可能会跳过 `gateway install --wrapper` 持久化子场景；`update-channel-switch` 可能会从 tarball 派生的伪 git fixture 中裁剪缺失的 `pnpm.patchedDependencies`，并且可能记录缺失的持久化 `update.channel`；插件冒烟测试可能会读取旧版安装记录位置，或接受缺失的 marketplace 安装记录持久化；而 `plugin-update` 可能允许配置元数据迁移，同时仍要求安装记录及无重复安装行为保持不变。`2026.4.25` 之后的包必须满足现代契约；相同条件将不再警告或跳过，而是直接失败。 示例： ```bash -# 验证当前 beta 软件包，并使用产品级覆盖。 +# Validate the current beta package with product-level coverage. gh workflow run package-acceptance.yml \ --ref main \ -f workflow_ref=main \ @@ -63,7 +63,7 @@ gh workflow run package-acceptance.yml \ -f suite_profile=product \ -f telegram_mode=mock-openai -# 使用当前 harness 打包并验证一个发布分支。 +# Pack and validate a release branch with the current harness. gh workflow run package-acceptance.yml \ --ref main \ -f workflow_ref=main \ @@ -72,7 +72,7 @@ gh workflow run package-acceptance.yml \ -f suite_profile=package \ -f telegram_mode=mock-openai -# 验证一个 tarball URL。对于 source=url，SHA-256 是必填项。 +# Validate a tarball URL. SHA-256 is mandatory for source=url. gh workflow run package-acceptance.yml \ --ref main \ -f workflow_ref=main \ @@ -81,7 +81,7 @@ gh workflow run package-acceptance.yml \ -f package_sha256=<64-char-sha256> \ -f suite_profile=smoke -# 复用由另一个 Actions 运行上传的 tarball。 +# Reuse a tarball uploaded by another Actions run. gh workflow run package-acceptance.yml \ --ref main \ -f workflow_ref=main \ @@ -92,15 +92,15 @@ gh workflow run package-acceptance.yml \ -f docker_lanes='install-e2e plugin-update' ``` -调试失败的软件包验收运行时，先查看 `resolve_package` 摘要，以确认软件包来源、版本和 SHA-256。然后检查 `docker_acceptance` 子运行及其 Docker 工件：`.artifacts/docker-tests/**/summary.json`、`failures.json`、流水线日志、阶段耗时和重跑命令。优先重跑失败的软件包配置文件或精确的 Docker 流水线，而不是重跑完整发布验证。 +在调试失败的包验收运行时，先查看 `resolve_package` 摘要，以确认包来源、版本和 SHA-256。然后检查 `docker_acceptance` 子运行及其 Docker 产物：`.artifacts/docker-tests/**/summary.json`、`failures.json`、流程日志、阶段耗时以及重跑命令。优先重跑失败的包配置文件或精确的 Docker 流程，而不是重跑完整发布验证。 -QA Lab 在主智能范围控制工作流之外有专用的 CI 流水线。`Parity gate` 工作流会在匹配的 PR 变更和手动触发时运行；它会构建私有 QA 运行时，并比较 mock GPT-5.5 和 Opus 4.6 agentic 包。`QA-Lab - All Lanes` 工作流会在 `main` 上每晚运行，也可手动触发；它会将 mock parity gate、live Matrix 流水线，以及 live Telegram 和 Discord 流水线作为并行作业展开。实时作业使用 `qa-live-shared` 环境，Telegram / Discord 使用 Convex 租约。Matrix 在定时和发布门控中使用 `--profile fast --fail-fast`，而 CLI 默认值和手动工作流输入仍然是 `all`；手动触发 `matrix_profile=all` 时，总是会将完整 Matrix 覆盖拆分为 `transport`、`media`、`e2ee-smoke`、`e2ee-deep` 和 `e2ee-cli` 作业。`OpenClaw Release Checks` 也会在发布批准前运行发布关键的 QA Lab 流水线。 +QA Lab 在主智能范围工作流之外有专门的 CI 流程。`Parity gate` 工作流会在匹配的 PR 更改和手动派发时运行；它会构建私有 QA 运行时，并比较 mock GPT-5.5 和 Opus 4.6 agentic packs。`QA-Lab - All Lanes` 工作流会在 `main` 上每晚运行，并支持手动派发；它会将 mock parity gate、live Matrix 流程以及 live Telegram 和 Discord 流程作为并行作业展开。live 作业使用 `qa-live-shared` 环境，而 Telegram / Discord 使用 Convex leases。对于定时和发布门禁，Matrix 使用 `--profile fast --fail-fast`；而 CLI 默认值和手动工作流输入仍为 `all`；手动 `matrix_profile=all` 派发总是会将完整 Matrix 覆盖拆分为 `transport`、`media`、`e2ee-smoke`、`e2ee-deep` 和 `e2ee-cli` 作业。`OpenClaw Release Checks` 也会在发布批准前运行关键发布所需的 QA Lab 流程。 -`Duplicate PRs After Merge` 工作流是一个手动维护者工作流，用于在合并后清理重复 PR。它默认是 dry-run，只有在 `apply=true` 时才会关闭明确列出的 PR。在修改 GitHub 之前，它会验证已合并 PR 确实已合并，并验证每个重复 PR 都具有共享的被引用 issue，或存在重叠的变更 hunk。 +`Duplicate PRs After Merge` 工作流是一个供维护者使用的手动工作流，用于落地后的重复 PR 清理。它默认以 dry-run 方式运行，只有在 `apply=true` 时才会关闭明确列出的 PR。在修改 GitHub 之前，它会验证已落地 PR 已被合并，并验证每个重复 PR 都具有共享的引用 issue，或存在重叠的已修改代码块。 -`Docs Agent` 工作流是一个事件驱动的 Codex 维护流水线，用于让现有文档与最近已合并的更改保持一致。它没有纯定时调度：`main` 上一次成功的、非机器人触发的 push CI 运行可以触发它，手动触发也可以直接运行它。工作流运行触发的调用会在 `main` 已继续前进，或者过去一小时内已创建了另一个未被跳过的 Docs Agent 运行时被跳过。实际运行时，它会审查从上一个未被跳过的 Docs Agent 源 SHA 到当前 `main` 的提交范围，因此每小时一次的运行可以覆盖自上次文档处理以来在 main 上累积的全部更改。 +`Docs Agent` 工作流是一个事件驱动的 Codex 维护流程，用于让现有文档与最近已落地的更改保持一致。它没有纯定时调度：`main` 上成功的、非机器人推送 CI 运行可以触发它，也可以通过手动派发直接运行。工作流运行触发的调用会在 `main` 已继续前进，或最近一小时内已创建另一个未被跳过的 Docs Agent 运行时跳过。实际运行时，它会审查从上一个未被跳过的 Docs Agent 源 SHA 到当前 `main` 的提交范围，因此每小时一次的运行可以覆盖自上次文档处理以来累积在 `main` 上的所有更改。 -`Test Performance Agent` 工作流是一个事件驱动的 Codex 维护流水线，用于处理慢测试。它没有纯定时调度：`main` 上一次成功的、非机器人触发的 push CI 运行可以触发它，但如果当天 UTC 已经有另一个基于 workflow-run 的调用正在运行或已运行，它就会跳过。手动触发会绕过这个按天计的活跃门控。该流水线会构建完整测试套件的分组 Vitest 性能报告，让 Codex 只进行小范围、保持覆盖率的测试性能修复，而不是大范围重构，然后重新运行完整测试套件报告，并拒绝任何降低通过基线测试数量的更改。如果基线存在失败测试，Codex 只能修复明显的失败，并且变更提交前，agent 之后的完整测试套件报告必须全部通过。当 `main` 在机器人推送落地前继续前进时，该流水线会对已验证补丁执行 rebase，重新运行 `pnpm check:changed`，并重试推送；存在冲突的过时补丁会被跳过。它使用 GitHub 托管的 Ubuntu，这样 Codex action 就可以与 docs agent 保持相同的 drop-sudo 安全姿态。 +`Test Performance Agent` 工作流是一个事件驱动的 Codex 维护流程，用于处理慢测试。它没有纯定时调度：`main` 上成功的、非机器人推送 CI 运行可以触发它，但如果同一 UTC 日期已有另一个由工作流运行触发的调用已运行或正在运行，它会跳过。手动派发会绕过这一按日活动门禁。该流程会构建完整测试套件的分组 Vitest 性能报告，让 Codex 只进行小范围、保持覆盖率的测试性能修复，而不是大范围重构；随后重跑完整测试套件报告，并拒绝任何会降低基线通过测试数的更改。如果基线存在失败测试，Codex 只能修复明显的失败项，且 agent 处理后的完整测试套件报告必须通过，之后才会提交任何内容。当 `main` 在机器人推送落地前继续前进时，该流程会对已验证补丁执行 rebase、重跑 `pnpm check:changed` 并重试推送；有冲突的过期补丁会被跳过。它使用 GitHub 托管的 Ubuntu，因此 Codex action 可以与 docs agent 保持相同的 drop-sudo 安全姿态。 ```bash gh workflow run duplicate-after-merge.yml \ @@ -113,29 +113,29 @@ gh workflow run duplicate-after-merge.yml \ | 作业 | 用途 | 运行时机 | | -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- | -| `preflight` | 检测是否仅改动文档、已变更范围、已变更扩展，并构建 CI 清单 | 在所有非草稿 push 和 PR 上始终运行 | -| `security-scm-fast` | 通过 `zizmor` 进行私钥检测和工作流审计 | 在所有非草稿 push 和 PR 上始终运行 | -| `security-dependency-audit` | 针对 npm 通告执行无依赖的生产 lockfile 审计 | 在所有非草稿 push 和 PR 上始终运行 | -| `security-fast` | 快速安全作业的必需聚合作业 | 在所有非草稿 push 和 PR 上始终运行 | -| `build-artifacts` | 构建 `dist/`、Control UI、构建产物检查以及可复用的下游工件 | 与 Node 相关的变更 | -| `checks-fast-core` | 快速 Linux 正确性流水线，例如 bundled / plugin-contract / protocol 检查 | 与 Node 相关的变更 | -| `checks-fast-contracts-channels` | 分片的渠道契约检查，并提供稳定的聚合检查结果 | 与 Node 相关的变更 | -| `checks-node-extensions` | 针对扩展套件执行完整 bundled-plugin 测试分片 | 与 Node 相关的变更 | -| `checks-node-core-test` | Core Node 测试分片，不含渠道、bundled、contract 和扩展流水线 | 与 Node 相关的变更 | -| `check` | 分片后的主本地门控等效项：生产类型、lint、guard、测试类型和严格 smoke | 与 Node 相关的变更 | -| `check-additional` | 架构、边界、扩展表面 guard、package-boundary 和 gateway-watch 分片 | 与 Node 相关的变更 | -| `build-smoke` | 已构建 CLI 的 smoke 测试和启动内存 smoke 测试 | 与 Node 相关的变更 | -| `checks` | 已构建工件渠道测试的验证器 | 与 Node 相关的变更 | -| `checks-node-compat-node22` | Node 22 兼容性构建和 smoke 流水线 | 用于发布的手动 CI 触发 | -| `check-docs` | 文档格式化、lint 和断链检查 | 文档有变更时 | -| `skills-python` | 面向 Python 支持的 Skills 的 Ruff + pytest | 与 Python Skills 相关的变更 | -| `checks-windows` | Windows 特定测试流水线 | 与 Windows 相关的变更 | -| `macos-node` | 使用共享构建工件的 macOS TypeScript 测试流水线 | 与 macOS 相关的变更 | -| `macos-swift` | macOS 应用的 Swift lint、构建和测试 | 与 macOS 相关的变更 | -| `android` | 两种 flavor 的 Android 单元测试，以及一个 debug APK 构建 | 与 Android 相关的变更 | -| `test-performance-agent` | 在可信活动之后每日执行的 Codex 慢测试优化 | main CI 成功后或手动触发 | +| `preflight` | 检测是否仅为文档更改、已更改范围、已更改扩展，并构建 CI 清单 | 在所有非草稿推送和 PR 上始终运行 | +| `security-scm-fast` | 通过 `zizmor` 进行私钥检测和工作流审计 | 在所有非草稿推送和 PR 上始终运行 | +| `security-dependency-audit` | 针对 npm advisories 执行无依赖的生产 lockfile 审计 | 在所有非草稿推送和 PR 上始终运行 | +| `security-fast` | 快速安全作业所需的聚合作业 | 在所有非草稿推送和 PR 上始终运行 | +| `build-artifacts` | 构建 `dist/`、Control UI、构建产物检查以及可复用的下游产物 | 与 Node 相关的更改 | +| `checks-fast-core` | 快速 Linux 正确性流程，例如 bundled / plugin-contract / protocol 检查 | 与 Node 相关的更改 | +| `checks-fast-contracts-channels` | 分片的渠道契约检查，并提供稳定的聚合检查结果 | 与 Node 相关的更改 | +| `checks-node-extensions` | 覆盖整个扩展套件的完整内置插件测试分片 | 与 Node 相关的更改 | +| `checks-node-core-test` | Core Node 测试分片，不包括渠道、内置、契约和扩展流程 | 与 Node 相关的更改 | +| `check` | 分片后的主要本地门禁对应项：生产类型、lint、防护检查、测试类型和严格冒烟测试 | 与 Node 相关的更改 | +| `check-additional` | 架构、边界、扩展表面防护、包边界和 gateway-watch 分片 | 与 Node 相关的更改 | +| `build-smoke` | 已构建 CLI 冒烟测试和启动内存冒烟测试 | 与 Node 相关的更改 | +| `checks` | 已构建产物渠道测试的验证作业 | 与 Node 相关的更改 | +| `checks-node-compat-node22` | Node 22 兼容性构建和冒烟流程 | 用于发布的手动 CI 派发 | +| `check-docs` | 文档格式、lint 和断链检查 | 文档发生更改时 | +| `skills-python` | 面向 Python 支持的 Skills 的 Ruff + pytest | 与 Python Skills 相关的更改 | +| `checks-windows` | Windows 特定测试流程 | 与 Windows 相关的更改 | +| `macos-node` | 使用共享构建产物的 macOS TypeScript 测试流程 | 与 macOS 相关的更改 | +| `macos-swift` | macOS 应用的 Swift lint、构建和测试 | 与 macOS 相关的更改 | +| `android` | 两个 flavor 的 Android 单元测试，以及一个 debug APK 构建 | 与 Android 相关的更改 | +| `test-performance-agent` | 在可信活动之后进行每日 Codex 慢测试优化 | `main` 上的 CI 成功后或手动派发 | -手动 CI 触发会运行与常规 CI 相同的作业图，但会强制开启所有范围控制流水线：Linux Node 分片、bundled-plugin 分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建 smoke、文档检查、Python Skills、Windows、macOS、Android，以及 Control UI i18n。手动运行使用唯一的并发组，因此同一 ref 上的另一次 push 或 PR 运行不会取消一个发布候选版本的完整测试套件。可选的 `target_ref` 输入允许可信调用方在分支、标签或完整提交 SHA 上运行该作业图，同时使用所选触发 ref 的工作流文件。 +手动 CI 派发运行的作业图与常规 CI 相同，但会强制开启所有范围流程：Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟、文档检查、Python Skills、Windows、macOS、Android 和 Control UI i18n。手动运行使用唯一的并发组，因此发布候选版本的完整测试套件不会因同一 ref 上的另一次推送或 PR 运行而被取消。可选的 `target_ref` 输入允许可信调用者在使用所选派发 ref 的工作流文件的同时，针对某个分支、标签或完整提交 SHA 运行该作业图。 ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -145,76 +145,68 @@ gh workflow run full-release-validation.yml --ref main -f ref= ## 快速失败顺序 -作业按顺序排列，以便让廉价检查先失败，再运行昂贵作业： +作业的排序方式是让低成本检查先失败，再决定是否运行高成本作业： -1. `preflight` 决定究竟存在哪些流水线。`docs-scope` 和 `changed-scope` 逻辑是此作业内部的步骤，而不是独立作业。 -2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs` 和 `skills-python` 会快速失败，而无需等待更重的工件和平台矩阵作业。 -3. `build-artifacts` 会与快速 Linux 流水线并行运行，这样下游消费者就可以在共享构建就绪后立即开始。 -4. 更重的平台和运行时流水线会在之后展开：`checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-extensions`、`checks-node-core-test`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 和 `android`。 +1. `preflight` 决定哪些流程实际存在。`docs-scope` 和 `changed-scope` 逻辑是这个作业中的步骤，不是独立作业。 +2. `security-scm-fast`、`security-dependency-audit`、`security-fast`、`check`、`check-additional`、`check-docs` 和 `skills-python` 会快速失败，而不会等待更重的构建产物和平台矩阵作业。 +3. `build-artifacts` 会与快速 Linux 流程并行进行，这样下游消费者就能在共享构建准备好后立即开始。 +4. 更重的平台和运行时流程会在之后展开：`checks-fast-core`、`checks-fast-contracts-channels`、`checks-node-extensions`、`checks-node-core-test`、`checks`、`checks-windows`、`macos-node`、`macos-swift` 和 `android`。 -范围控制逻辑位于 `scripts/ci-changed-scope.mjs`，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。 -手动触发会跳过 changed-scope 检测，并让 preflight 清单表现得像所有受范围控制的区域都发生了变化。 +范围逻辑位于 `scripts/ci-changed-scope.mjs`，并由 `src/scripts/ci-changed-scope.test.ts` 中的单元测试覆盖。 +手动派发会跳过 changed-scope 检测，并让 preflight 清单表现得像所有有范围限制的区域都发生了更改。 -CI 工作流编辑会验证 Node CI 作业图以及工作流 lint，但不会仅因这些改动就强制运行 Windows、Android 或 macOS 原生构建；这些平台流水线仍然只由对应平台源代码变更触发。 +CI 工作流编辑会验证 Node CI 作业图以及工作流 lint，但不会仅因自身更改就强制运行 Windows、Android 或 macOS 原生构建；这些平台流程仍然只针对对应平台源码更改运行。 -仅涉及 CI 路由的编辑、选定的廉价 core-test fixture 编辑，以及狭窄的插件契约辅助工具 / 测试路由编辑，会走快速的仅 Node 清单路径：preflight、安全检查，以及单个 `checks-fast-core` 任务。当变更文件仅限于该快速任务可直接覆盖的路由或辅助表面时，这条路径会跳过构建工件、Node 22 兼容性、渠道契约、完整 core 分片、bundled-plugin 分片和额外 guard 矩阵。 +仅涉及 CI 路由的编辑、特定的低成本 core-test fixture 编辑，以及范围很窄的插件契约辅助函数 / 测试路由编辑，会使用快速的仅 Node 清单路径：preflight、安全检查，以及单个 `checks-fast-core` 任务。当更改文件仅限于快速任务可直接覆盖的路由或辅助函数表面时，这一路径会避免运行 build artifacts、Node 22 兼容性、渠道契约、完整 core 分片、内置插件分片以及额外的防护矩阵。 -Windows Node 检查的范围仅限于 Windows 特定的进程 / 路径包装器、npm / pnpm / UI 运行器辅助工具、包管理器配置，以及执行该流水线的 CI 工作流表面；不相关的源代码、插件、install-smoke 和仅测试类改动会保留在 Linux Node 流水线上，这样就不会为已由常规测试分片覆盖的内容占用一个 16-vCPU 的 Windows worker。 +Windows Node 检查的范围仅限于 Windows 特定的进程 / 路径包装器、npm / pnpm / UI 运行器辅助函数、包管理器配置，以及执行该流程的 CI 工作流表面；不相关的源码、插件、install-smoke 和仅测试更改仍会留在 Linux Node 流程上，这样就不会为了已经由常规测试分片覆盖的内容去占用一个 16 vCPU 的 Windows worker。 -独立的 `install-smoke` 工作流会通过它自己的 `preflight` 作业复用同一个范围脚本。它将 smoke 覆盖拆分为 `run_fast_install_smoke` 和 `run_full_install_smoke`。对于拉取请求，Docker / package 表面、bundled 插件 package / manifest 变更，以及 Docker smoke 作业所覆盖的 core 插件 / 渠道 / Gateway 网关 / 插件 SDK 表面，会走快速路径。仅源代码的 bundled 插件变更、仅测试类编辑，以及仅文档类编辑，不会占用 Docker worker。快速路径会构建一次根 Dockerfile 镜像，检查 CLI，运行 agents delete shared-workspace CLI smoke，运行容器 `gateway-network` e2e，验证一个 bundled 扩展 build arg，并在 240 秒的聚合命令超时下运行有边界的 bundled-plugin Docker 配置文件，同时每个场景的 Docker run 还各自有独立上限。完整路径则保留 QR package install 以及 installer Docker / update 覆盖，用于夜间定时运行、手动触发、workflow-call 发布检查，以及真正触及 installer / package / Docker 表面的拉取请求。推送到 `main`，包括合并提交，不会强制走完整路径；当 changed-scope 逻辑会在 push 上请求完整覆盖时，该工作流仍只保留快速 Docker smoke，并把完整 install smoke 留给夜间运行或发布验证。较慢的 Bun 全局安装 image-provider smoke 由 `run_bun_global_install_smoke` 单独控制；它会在夜间调度和发布检查工作流中运行，手动触发 `install-smoke` 时也可选择启用，但拉取请求和 `main` 推送不会运行它。QR 和 installer Docker 测试保留它们各自专用的 install 导向 Dockerfile。 +独立的 `install-smoke` 工作流通过其自身的 `preflight` 作业复用同一个范围脚本。它将冒烟覆盖拆分为 `run_fast_install_smoke` 和 `run_full_install_smoke`。对于拉取请求，Docker / package 表面、内置插件 package / manifest 更改，以及 Docker 冒烟作业所覆盖的 core 插件 / 渠道 / Gateway 网关 / Plugin SDK 表面，会运行快速路径。仅源码的内置插件更改、仅测试编辑以及仅文档编辑不会占用 Docker workers。快速路径会构建一次根 Dockerfile 镜像，检查 CLI，运行 agents delete shared-workspace CLI 冒烟测试，运行容器 `gateway-network` e2e，验证一个内置扩展 build arg，并在总命令超时 240 秒的限制下运行有边界的内置插件 Docker 配置文件，同时每个场景的 Docker 运行也分别受限。完整路径则保留 QR 包安装以及 installer Docker / update 覆盖，用于每晚定时运行、手动派发、工作流调用的发布检查，以及确实触及 installer / package / Docker 表面的拉取请求。推送到 `main`，包括合并提交，不会强制完整路径；当 changed-scope 逻辑在推送时请求完整覆盖，该工作流仍会保留快速 Docker 冒烟，而将完整 install smoke 留给每晚运行或发布验证。较慢的 Bun 全局安装 image-provider 冒烟由 `run_bun_global_install_smoke` 单独控制；它会在每晚调度以及发布检查工作流中运行，手动 `install-smoke` 派发也可以选择启用它，但拉取请求和 `main` 推送不会运行它。QR 和 installer Docker 测试保留各自面向安装的 Dockerfile。本地 `test:docker:all` 会预构建一个共享的 live-test 镜像，将 OpenClaw 仅打包一次为 npm tarball，并构建两个共享的 `scripts/e2e/Dockerfile` 镜像：一个是用于 installer / update / plugin-dependency 流程的裸 Node / Git 运行器，另一个是功能镜像，会将相同 tarball 安装到 `/app` 中，供常规功能流程使用。Docker 流程定义位于 `scripts/lib/docker-e2e-scenarios.mjs`，规划器逻辑位于 `scripts/lib/docker-e2e-plan.mjs`，运行器只执行所选计划。调度器会通过 `OPENCLAW_DOCKER_E2E_BARE_IMAGE` 和 `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` 为每个流程选择镜像，然后以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行流程；可用 `OPENCLAW_DOCKER_ALL_PARALLELISM` 调整默认 main-pool 槽位数 10，用 `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` 调整 provider 敏感的 tail-pool 槽位数 10。重型流程上限默认分别为 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`，这样 npm 安装和多服务流程就不会让 Docker 过度提交，而较轻流程仍能填满可用槽位。单个比实际限制更重的流程仍然可以从空池启动，然后在释放容量前独占运行。默认会将流程启动错开 2 秒，以避免本地 Docker daemon 出现 create storm；可通过 `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` 或其他毫秒值覆盖。本地聚合流程会预检 Docker、移除过期的 OpenClaw E2E 容器、输出活跃流程状态、持久化流程耗时用于最长优先排序，并支持 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 以检查调度器。默认情况下，它会在首次失败后停止调度新的池化流程，并且每个流程都有一个 120 分钟的后备超时，可通过 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖；选定的 live / tail 流程使用更严格的逐流程上限。`OPENCLAW_DOCKER_ALL_LANES=` 会运行精确的调度器流程，包括仅发布使用的流程如 `install-e2e`，以及拆分后的内置更新流程如 `bundled-channel-update-acpx`，同时跳过 cleanup smoke，以便智能体复现单个失败流程。可复用的 live / E2E 工作流会调用 `scripts/test-docker-all.mjs --plan-json`，以确定所需的 package、镜像类型、live 镜像、流程和凭证覆盖，然后由 `scripts/docker-e2e.mjs` 将该计划转换为 GitHub 输出和摘要。它会通过 `scripts/package-openclaw-for-docker.mjs` 打包 OpenClaw、下载当前运行的包产物，或从 `package_artifact_run_id` 下载包产物；验证 tarball 清单；当计划需要包安装型流程时，通过 Blacksmith 的 Docker layer cache 构建并推送带 package-digest 标签的 bare / functional GHCR Docker E2E 镜像；并复用提供的 `docker_e2e_bare_image` / `docker_e2e_functional_image` 输入或已有的 package-digest 镜像，而不是重新构建。`Package Acceptance` 工作流是高层级的包门禁：它从 npm、可信 `package_ref`、附带 SHA-256 的 HTTPS tarball，或之前的工作流产物中解析一个候选项，然后将这个单独的 `package-under-test` 产物传入可复用的 Docker E2E 工作流。它将 `workflow_ref` 与 `package_ref` 分开，以便当前验收逻辑可以验证较旧但可信的提交，而不必检出旧工作流代码。发布检查会针对目标 ref 运行 `package` 验收配置文件；该配置文件覆盖 package / update / plugin 契约，是大多数 Parallels package / update 覆盖的默认 GitHub 原生替代方案。发布路径 Docker 套件最多运行三个分块作业，并设置 `OPENCLAW_SKIP_DOCKER_BUILD=1`，这样每个分块只拉取自己所需的镜像类型，并通过同一个带权重的调度器执行多个流程（`OPENCLAW_DOCKER_ALL_PROFILE=release-path`、`OPENCLAW_DOCKER_ALL_CHUNK=core|package-update|plugins-integrations`）。当请求完整发布路径覆盖时，OpenWebUI 会并入 `plugins-integrations`，只有在仅派发 OpenWebUI 时才保留独立的 `openwebui` 分块。`plugins-integrations` 分块运行拆分后的 `bundled-channel-*` 和 `bundled-channel-update-*` 流程，而不是串行的一体化 `bundled-channel-deps` 流程。每个分块都会上传 `.artifacts/docker-tests/`，其中包含流程日志、耗时、`summary.json`、`failures.json`、阶段耗时、调度器计划 JSON、慢流程表，以及逐流程重跑命令。工作流的 `docker_lanes` 输入会针对准备好的镜像运行所选流程，而不是运行分块作业，这样失败流程的调试就被限制在一个有针对性的 Docker 作业内，并会为该次运行准备、下载或复用包产物；如果所选流程是 live Docker 流程，有针对性的作业会在本地为该次重跑构建 live-test 镜像。生成的每流程 GitHub 重跑命令在相关值存在时会包含 `package_artifact_run_id`、`package_artifact_name` 和准备好的镜像输入，因此失败流程可以复用失败运行中的完全相同的包和镜像。使用 `pnpm test:docker:rerun ` 可从 GitHub 运行下载 Docker 产物，并打印组合 / 每流程的定向重跑命令；使用 `pnpm test:docker:timings ` 可查看慢流程和阶段关键路径摘要。定时的 live / E2E 工作流每天运行完整的发布路径 Docker 套件。内置更新矩阵按更新目标拆分，以便重复的 npm update 和 Doctor 修复过程可以与其他内置检查一起分片运行。 -本地 `test:docker:all` 会预先构建一个共享 live-test 镜像，将 OpenClaw 打包一次为 npm tarball，并构建两个共享的 `scripts/e2e/Dockerfile` 镜像：一个是裸 Node / Git 运行器，用于 installer / update / plugin-dependency 流水线；另一个是功能镜像，会把同一个 tarball 安装到 `/app` 中，用于常规功能性流水线。Docker 流水线定义位于 `scripts/lib/docker-e2e-scenarios.mjs`，规划逻辑位于 `scripts/lib/docker-e2e-plan.mjs`，而运行器只执行选中的计划。调度器会通过 `OPENCLAW_DOCKER_E2E_BARE_IMAGE` 和 `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` 为每条流水线选择镜像，然后以 `OPENCLAW_SKIP_DOCKER_BUILD=1` 运行各流水线；默认 main-pool 槽位数为 10，可通过 `OPENCLAW_DOCKER_ALL_PARALLELISM` 调整；provider 敏感的 tail-pool 槽位数也默认为 10，可通过 `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` 调整。重型流水线上限默认分别为 `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`、`OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` 和 `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`，以避免 npm install 和多服务流水线对 Docker 过度争抢，同时让较轻流水线仍能填满可用槽位。单条比有效上限更重的流水线仍然可以从空池启动，但会独占运行直到释放容量。为避免本地 Docker daemon 在创建阶段出现风暴，流水线启动默认错开 2 秒；可通过 `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` 或其他毫秒值覆盖。本地聚合运行会先对 Docker 做 preflight，移除陈旧的 OpenClaw E2E 容器，输出活动流水线状态，持久化流水线耗时以便按最长优先排序，并支持 `OPENCLAW_DOCKER_ALL_DRY_RUN=1` 用于检查调度器。默认在首次失败后停止调度新的池化流水线，并且每条流水线都有 120 分钟的后备超时，可通过 `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` 覆盖；选定的 live / tail 流水线使用更紧的逐流水线上限。`OPENCLAW_DOCKER_ALL_LANES=` 会运行精确的调度器流水线，包括仅用于发布的流水线如 `install-e2e`，以及拆分后的 bundled 更新流水线如 `bundled-channel-update-acpx`，同时跳过清理 smoke，以便智能体复现某一条失败流水线。 +本地 changed-lane 逻辑位于 `scripts/changed-lanes.mjs`，由 `scripts/check-changed.mjs` 执行。这个本地检查门禁在架构边界方面比宽泛的 CI 平台范围更严格：core 生产更改会运行 core prod 和 core test typecheck，以及 core lint / guards；core 仅测试更改只运行 core test typecheck 和 core lint；扩展生产更改会运行 extension prod 和 extension test typecheck，以及 extension lint；扩展仅测试更改会运行 extension test typecheck 和 extension lint。公共 Plugin SDK 或插件契约更改会扩展到 extension typecheck，因为扩展依赖这些 core 契约，但 Vitest 扩展全量测试仍然是显式的测试工作。仅发布元数据的版本提升会运行有针对性的版本 / 配置 / 根依赖检查。未知的根目录 / 配置更改会安全地回退到所有检查流程。 -可复用的 live / E2E 工作流会调用 `scripts/test-docker-all.mjs --plan-json`，以确定需要哪些 package、镜像类型、live 镜像、流水线和凭证覆盖，然后由 `scripts/docker-e2e.mjs` 将该计划转换为 GitHub 输出和摘要。它可以通过 `scripts/package-openclaw-for-docker.mjs` 打包 OpenClaw，下载当前运行的软件包工件，或从 `package_artifact_run_id` 下载软件包工件；验证 tarball 清单；当计划需要 package-installed 流水线时，通过 Blacksmith 的 Docker 层缓存构建并推送按 package digest 标记的 bare / functional GHCR Docker E2E 镜像；并在提供了 `docker_e2e_bare_image` / `docker_e2e_functional_image` 输入，或已存在 package-digest 镜像时，直接复用这些镜像而不是重新构建。 +手动 CI 派发会运行 `checks-node-compat-node22` 作为发布候选版本的兼容性覆盖。常规拉取请求和 `main` 推送会跳过该流程，并让矩阵继续聚焦于 Node 24 测试 / 渠道流程。 -`Package Acceptance` 工作流是高层级的软件包门控：它会从 npm、可信的 `package_ref`、带 SHA-256 的 HTTPS tarball，或先前工作流工件中解析出一个候选项，然后将这个单一的 `package-under-test` 工件传入可复用的 Docker E2E 工作流。它会将 `workflow_ref` 与 `package_ref` 分离，以便当前的验收逻辑可以验证较旧但可信的提交，而无需检出旧的工作流代码。发布检查会针对目标 ref 运行 `package` 验收配置文件；该配置文件覆盖 package / update / 插件契约，是大多数 Parallels package / update 覆盖的默认 GitHub 原生替代方案。 +最慢的 Node 测试族已被拆分或重新平衡，以便每个作业都保持较小规模，同时不至于过度预留 runners：渠道契约以三个带权重的分片运行，内置插件测试在六个扩展 workers 之间做负载均衡，小型 core 单元流程被成对组合，auto-reply 作为四个平衡 worker 运行，并将 reply 子树拆分为 agent-runner、dispatch 以及 commands / state-routing 分片，而 agentic Gateway 网关 / 插件配置则分布到现有的仅源码 agentic Node 作业中，而不是等待构建产物。广泛的浏览器、QA、媒体和杂项插件测试使用各自专用的 Vitest 配置，而不是共享的插件兜底配置。扩展分片作业一次最多运行两个插件配置组，每组使用一个 Vitest worker，并配备更大的 Node heap，这样导入密集型的插件批次就不会产生额外的 CI 作业。广泛的 agents 流程使用共享的 Vitest 文件并行调度器，因为它主要受导入 / 调度限制，而不是由某个单独的慢测试文件主导。`runtime-config` 与 infra core-runtime 分片一起运行，以避免共享运行时分片承担尾部负载。包含模式分片会使用 CI 分片名称记录耗时条目，因此 `.artifacts/vitest-shard-timings.json` 可以区分整个配置和过滤后的分片。`check-additional` 将 package-boundary 的 compile / canary 工作保持在一起，并将运行时拓扑架构与 gateway watch 覆盖分开；边界防护分片会在一个作业内部并发运行其规模较小且彼此独立的防护检查。Gateway 网关 watch、渠道测试和 core support-boundary 分片会在 `dist/` 和 `dist-runtime/` 已构建完成后，于 `build-artifacts` 内部并发运行，保留它们原有的检查名称作为轻量验证作业，同时避免额外占用两个 Blacksmith workers 和第二条产物消费者队列。 -发布路径 Docker 套件最多运行三个分块作业，并使用 `OPENCLAW_SKIP_DOCKER_BUILD=1`，这样每个分块只会拉取它所需的镜像类型，并通过同一个加权调度器执行多条流水线（`OPENCLAW_DOCKER_ALL_PROFILE=release-path`、`OPENCLAW_DOCKER_ALL_CHUNK=core|package-update|plugins-integrations`）。当完整发布路径覆盖请求 OpenWebUI 时，它会被折叠进 `plugins-integrations`；只有在仅 OpenWebUI 的触发场景中，才会保留独立的 `openwebui` 分块。`plugins-integrations` 分块运行拆分后的 `bundled-channel-*` 和 `bundled-channel-update-*` 流水线，而不是串行的一体化 `bundled-channel-deps` 流水线。每个分块都会上传 `.artifacts/docker-tests/`，其中包含流水线日志、耗时、`summary.json`、`failures.json`、阶段耗时、调度器计划 JSON、慢流水线表，以及逐流水线重跑命令。工作流的 `docker_lanes` 输入会针对已准备好的镜像运行选定流水线，而不是运行整块作业；这使失败流水线的调试可以被限制在一个有针对性的 Docker 作业内，并为该次运行准备、下载或复用软件包工件；如果选中的流水线是 live Docker 流水线，该目标作业会为这次重跑在本地构建 live-test 镜像。生成的逐流水线 GitHub 重跑命令在这些值存在时会包含 `package_artifact_run_id`、`package_artifact_name` 以及已准备镜像输入，因此失败流水线可以复用失败运行中的完全相同的软件包和镜像。使用 `pnpm test:docker:rerun ` 可以从某个 GitHub 运行下载 Docker 工件，并输出组合式 / 逐流水线的定向重跑命令；使用 `pnpm test:docker:timings ` 可以查看慢流水线和阶段关键路径摘要。定时的 live / E2E 工作流每天运行完整的发布路径 Docker 套件。bundled 更新矩阵按更新目标拆分，因此重复的 npm update 和 doctor 修复过程可以与其他 bundled 检查一起分片。 +Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。第三方 flavor 没有单独的源码集或 manifest；它的单元测试流程仍会在启用 SMS / call-log BuildConfig 标志的情况下编译该 flavor，同时避免在每次与 Android 相关的推送中重复打包 debug APK 作业。 -本地 changed-lane 逻辑位于 `scripts/changed-lanes.mjs`，并由 `scripts/check-changed.mjs` 执行。这个本地检查门控在架构边界方面比宽泛的 CI 平台范围更严格：core 生产变更会运行 core prod 和 core test 类型检查，以及 core lint / guards；core 仅测试类变更只运行 core test 类型检查和 core lint；扩展生产变更会运行扩展 prod 和扩展 test 类型检查，以及扩展 lint；扩展仅测试类变更会运行扩展 test 类型检查和扩展 lint。公共插件 SDK 或插件契约变更会扩展到扩展类型检查，因为扩展依赖这些核心契约，但 Vitest 扩展扫测仍属于显式测试工作。仅发布元数据的版本号提升会运行有针对性的版本 / 配置 / 根依赖检查。未知的根级 / 配置变更会以安全优先方式退回到所有检查流水线。 +当同一个 PR 或 `main` ref 上有新的推送到达时，GitHub 可能会将被取代的作业标记为 `cancelled`。除非同一 ref 的最新运行也失败，否则应将其视为 CI 噪声。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会报告正常的分片失败，但不会在整个工作流已被取代后继续排队。 -手动 CI 触发会运行 `checks-node-compat-node22`，作为发布候选版本的兼容性覆盖。常规拉取请求和 `main` 推送会跳过这条流水线，并让矩阵继续聚焦于 Node 24 测试 / 渠道流水线。 - -最慢的 Node 测试族已被拆分或平衡，因此每个作业都能保持较小规模，同时不会过度预留运行器：渠道契约会作为三个加权分片运行，bundled 插件测试会在六个扩展 worker 之间平衡分配，小型 core 单元流水线会成对组合，auto-reply 会作为四个平衡 worker 运行，并将 reply 子树拆分为 agent-runner、dispatch 和 commands / state-routing 分片，而 agentic Gateway 网关 / 插件配置则分散到现有的仅源代码 agentic Node 作业中，而不是等待构建工件。宽泛的浏览器、QA、媒体和杂项插件测试使用它们各自专用的 Vitest 配置，而不是共享的插件兜底配置。扩展分片作业一次最多运行两个插件配置组，每组使用一个 Vitest worker，并配备更大的 Node 堆，因此导入密集的插件批次不会产生额外的 CI 作业。宽泛的 agents 流水线使用共享的 Vitest 文件并行调度器，因为它的瓶颈在于导入 / 调度，而不是由某个单独的慢测试文件主导。`runtime-config` 与 infra core-runtime 分片一起运行，以避免共享运行时分片独自承担尾部耗时。包含模式分片会使用 CI 分片名称记录耗时条目，因此 `.artifacts/vitest-shard-timings.json` 可以区分完整配置与筛选后的分片。`check-additional` 会把 package-boundary 的 compile / canary 工作保留在一起，并将运行时拓扑架构与 gateway watch 覆盖分离；boundary guard 分片会在一个作业内并发运行其小型独立 guard。Gateway watch、渠道测试以及 core support-boundary 分片会在 `dist/` 和 `dist-runtime/` 已构建完成后，于 `build-artifacts` 内并发运行；这样既保留了它们旧的检查名称作为轻量验证作业，又避免额外占用两个 Blacksmith worker 和第二条工件消费者队列。 - -Android CI 会同时运行 `testPlayDebugUnitTest` 和 `testThirdPartyDebugUnitTest`，然后构建 Play debug APK。third-party flavor 没有单独的源代码集或 manifest；它的单元测试流水线仍会在启用 SMS / call-log BuildConfig 标志的情况下编译该 flavor，同时避免在每次与 Android 相关的 push 上重复执行 debug APK 打包作业。 - -当同一个 PR 或 `main` ref 上有更新的 push 到来时，GitHub 可能会将被取代的作业标记为 `cancelled`。除非同一 ref 的最新运行也失败，否则应将其视为 CI 噪音。聚合分片检查使用 `!cancelled() && always()`，因此它们仍会报告正常的分片失败，但不会在整个工作流已经被更新运行取代后继续排队。 - -自动 CI 并发键带有版本号（`CI-v7-*`），这样 GitHub 端旧队列组中的僵尸任务就不会无限期阻塞较新的 main 运行。手动完整测试套件运行使用 `CI-manual-v1-*`，并且不会取消正在进行的运行。 +自动 CI 并发键已做版本化处理（`CI-v7-*`），这样 GitHub 端旧队列组中的僵尸任务就不会无限期阻塞较新的 main 运行。手动完整测试套件运行使用 `CI-manual-v1-*`，并且不会取消进行中的运行。 ## 运行器 | 运行器 | 作业 | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`、快速安全作业及其聚合项（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、快速 protocol / contract / bundled 检查、分片渠道契约检查、除 lint 以外的 `check` 分片、`check-additional` 分片及聚合项、Node 测试聚合验证器、文档检查、Python Skills、workflow-sanity、labeler、auto-response；install-smoke preflight 也使用 GitHub 托管的 Ubuntu，这样 Blacksmith 矩阵可以更早开始排队 | -| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`、build-smoke、Linux Node 测试分片、bundled 插件测试分片、`android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`，它对 CPU 仍然足够敏感，以至于 8 vCPU 节省的成本不如带来的损耗；install-smoke Docker 构建也是如此，其中 32 vCPU 的排队时间成本高于其收益 | +| `ubuntu-24.04` | `preflight`、快速安全作业及其聚合（`security-scm-fast`、`security-dependency-audit`、`security-fast`）、快速 protocol / contract / bundled 检查、分片渠道契约检查、除 lint 外的 `check` 分片、`check-additional` 分片及聚合、Node 测试聚合验证作业、文档检查、Python Skills、workflow-sanity、labeler、auto-response；install-smoke 的 preflight 也使用 GitHub 托管 Ubuntu，这样 Blacksmith 矩阵就能更早排队 | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`、build-smoke、Linux Node 测试分片、内置插件测试分片、`android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`，它对 CPU 的敏感度仍然高到让 8 vCPU 得不偿失；install-smoke Docker 构建，此处 32 vCPU 的排队时间得不偿失 | | `blacksmith-16vcpu-windows-2025` | `checks-windows` | | `blacksmith-6vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-node`；fork 会回退到 `macos-latest` | | `blacksmith-12vcpu-macos-latest` | `openclaw/openclaw` 上的 `macos-swift`；fork 会回退到 `macos-latest` | -## 本地等效命令 +## 本地对应命令 ```bash -pnpm changed:lanes # 检查针对 origin/main...HEAD 的本地 changed-lane 分类器 -pnpm check:changed # 智能本地检查门控：按边界流水线执行变更相关的类型检查 / lint / guards -pnpm check # 快速本地门控：生产 tsgo + 分片 lint + 并行快速 guards +pnpm changed:lanes # 检查 origin/main...HEAD 的本地 changed-lane 分类器 +pnpm check:changed # 智能本地检查门禁：按边界流程运行 changed typecheck/lint/guards +pnpm check # 快速本地门禁：production tsgo + 分片 lint + 并行快速 guards pnpm check:test-types -pnpm check:timed # 相同门控，但附带每阶段耗时 +pnpm check:timed # 同一门禁，但带各阶段耗时 pnpm build:strict-smoke pnpm check:architecture pnpm test:gateway:watch-regression pnpm test # Vitest 测试 -pnpm test:changed # 廉价的智能 changed Vitest 目标 +pnpm test:changed # 低成本的智能 changed Vitest 目标 pnpm test:channels pnpm test:contracts:channels -pnpm check:docs # 文档格式化 + lint + 断链检查 -pnpm build # 当 CI 工件 / build-smoke 流水线相关时，构建 dist -pnpm ci:timings # 汇总最新一次 origin/main push CI 运行 +pnpm check:docs # 文档格式 + lint + 断链检查 +pnpm build # 当 CI 的 artifact / build-smoke 流程相关时，构建 dist +pnpm ci:timings # 汇总最近一次 origin/main 推送 CI 运行 pnpm ci:timings:recent # 比较最近成功的 main CI 运行 -node scripts/ci-run-timings.mjs # 汇总总耗时、排队耗时和最慢作业 -node scripts/ci-run-timings.mjs --latest-main # 忽略 issue / comment 噪音，并选择 origin/main push CI +node scripts/ci-run-timings.mjs # 汇总总耗时、排队时间和最慢作业 +node scripts/ci-run-timings.mjs --latest-main # 忽略 issue / comment 噪声并选择 origin/main 推送 CI node scripts/ci-run-timings.mjs --recent 10 # 比较最近成功的 main CI 运行 pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json diff --git a/docs/zh-CN/cli/crestodian.md b/docs/zh-CN/cli/crestodian.md index 90ea83b76..20604a83f 100644 --- a/docs/zh-CN/cli/crestodian.md +++ b/docs/zh-CN/cli/crestodian.md @@ -1,42 +1,40 @@ --- read_when: - - 你在不带任何命令的情况下运行 `openclaw`，并且想了解 Crestodian + - 你在不带任何命令的情况下运行 openclaw，并且想了解 Crestodian - 你需要一种无配置且安全的方式来检查或修复 OpenClaw - 你正在设计或启用消息渠道救援模式 -summary: Crestodian 的 CLI 参考和安全模型，这是一个无配置且安全的设置与修复辅助工具 +summary: Crestodian 的 CLI 参考和安全模型，这个用于无配置且安全的设置与修复辅助工具 title: Crestodian x-i18n: - generated_at: "2026-04-26T07:48:33Z" + generated_at: "2026-04-27T07:11:16Z" model: gpt-5.4 provider: openai - source_hash: aafa46de3c2df2ec4b0b16a0955bb9afc76df92d5ebb928077bb5007118e037c + source_hash: e09331a5303120e9044ae147426ad17caeed35f092b316506ca8e4e3a1c55157 source_path: cli/crestodian.md workflow: 15 --- # `openclaw crestodian` -Crestodian 是 OpenClaw 的本地设置、修复和配置辅助工具。它被设计为在正常智能体路径损坏时仍可访问。 +Crestodian 是 OpenClaw 的本地设置、修复和配置辅助工具。它的设计目标是在正常智能体路径损坏时仍然可达。 -在不带任何命令的情况下运行 `openclaw` 会在交互式终端中启动 Crestodian。 -运行 `openclaw crestodian` 会显式启动同一个辅助工具。 +在不带任何命令的情况下运行 `openclaw`，会在交互式终端中启动 Crestodian。运行 `openclaw crestodian` 则会显式启动同一个辅助工具。 ## Crestodian 会显示什么 -启动时，交互式 Crestodian 会打开与 `openclaw tui` 相同的 TUI shell，但使用 Crestodian 聊天后端。聊天日志会以简短的问候开始： +启动时，交互式 Crestodian 会打开与 `openclaw tui` 相同的 TUI shell，但使用 Crestodian 聊天后端。聊天日志会以简短问候开头： -- 何时启动 Crestodian +- 何时应启动 Crestodian - Crestodian 实际使用的模型或确定性规划器路径 - 配置有效性和默认智能体 -- 来自首次启动探测的 Gateway 网关 可达性 -- Crestodian 接下来可以执行的调试操作 +- 首次启动探测得到的 Gateway 网关可达性 +- Crestodian 可执行的下一步调试操作 -它不会为了启动而转储密钥，也不会加载插件 CLI 命令。TUI 仍然提供常规的页眉、聊天日志、状态行、页脚、自动补全和编辑器控件。 +它不会为了启动而转储密钥或加载插件 CLI 命令。TUI 仍然提供常规的页眉、聊天日志、状态行、页脚、自动补全和编辑器控件。 -使用 `status` 可查看详细清单，其中包括配置路径、文档/源码路径、本地 CLI 探测、API 密钥存在情况、智能体、模型以及 Gateway 网关 详情。 +使用 `status` 可查看详细清单，其中包括配置路径、文档/源码路径、本地 CLI 探测、API 密钥存在情况、智能体、模型以及 Gateway 网关详情。 -Crestodian 使用与常规智能体相同的 OpenClaw 参考发现机制。在 Git 检出中，它会将自己指向本地 `docs/` 和本地源码树。在 npm 包安装中，它会使用打包附带的文档，并链接到 -[https://github.com/openclaw/openclaw](https://github.com/openclaw/openclaw)，同时明确提示在文档不足时查看源码。 +Crestodian 与常规智能体使用相同的 OpenClaw 参考发现机制。在 Git 检出中，它会将自己指向本地 `docs/` 和本地源码树。在 npm 软件包安装中，它会使用随包提供的文档，并链接到 [https://github.com/openclaw/openclaw](https://github.com/openclaw/openclaw)，同时明确提示你在文档不足时查阅源码。 ## 示例 @@ -51,7 +49,7 @@ openclaw crestodian --message "set default model openai/gpt-5.5" --yes openclaw onboard --modern ``` -在 Crestodian TUI 内： +在 Crestodian TUI 中： ```text status @@ -79,14 +77,14 @@ quit Crestodian 的启动路径被刻意保持得很小。它可以在以下情况下运行： -- 缺少 `openclaw.json` +- `openclaw.json` 缺失 - `openclaw.json` 无效 -- Gateway 网关 已关闭 +- Gateway 网关已停止 - 插件命令注册不可用 - 尚未配置任何智能体 `openclaw --help` 和 `openclaw --version` 仍然使用常规快速路径。 -非交互式 `openclaw` 会用一条简短消息退出，而不是打印根帮助，因为无命令产品就是 Crestodian。 +非交互式 `openclaw` 会以简短消息退出，而不是打印根帮助信息，因为不带命令时对应的产品就是 Crestodian。 ## 操作与批准 @@ -97,22 +95,22 @@ Crestodian 使用类型化操作，而不是临时编辑配置。 - 显示概览 - 列出智能体 - 显示模型/后端状态 -- 运行 status 或健康检查 -- 检查 Gateway 网关 可达性 -- 在不进行交互式修复的情况下运行 doctor +- 运行状态或健康检查 +- 检查 Gateway 网关可达性 +- 运行 Doctor，但不进行交互式修复 - 验证配置 - 显示审计日志路径 -持久化操作在交互模式下需要会话式批准，除非你为直接命令传递 `--yes`： +持久化操作在交互模式下需要通过对话批准，除非你为直接命令传入 `--yes`： - 写入配置 - 运行 `config set` -- 通过 `config set-ref` 设置受支持的 `SecretRef` 值 -- 运行 setup/新手引导 bootstrap +- 通过 `config set-ref` 设置受支持的 SecretRef 值 +- 运行设置/新手引导初始化 - 更改默认模型 - 启动、停止或重启 Gateway 网关 - 创建智能体 -- 运行会重写配置或状态的 doctor 修复 +- 运行会重写配置或状态的 Doctor 修复 已应用的写入会记录到： @@ -120,14 +118,14 @@ Crestodian 使用类型化操作，而不是临时编辑配置。 ~/.openclaw/audit/crestodian.jsonl ``` -设备发现不会被审计。只有已应用的操作和写入会被记录。 +发现过程不会被审计。只有已应用的操作和写入会被记录。 `openclaw onboard --modern` 会将 Crestodian 作为现代新手引导预览启动。 -普通的 `openclaw onboard` 仍然运行经典新手引导。 +普通的 `openclaw onboard` 仍会运行经典新手引导。 -## Setup Bootstrap +## 设置引导 -`setup` 是一种以聊天优先的新手引导 bootstrap。它只通过类型化配置操作进行写入，并且会先请求批准。 +`setup` 是聊天优先的新手引导初始化流程。它只通过类型化配置操作进行写入，并且会先请求批准。 ```text setup @@ -135,28 +133,27 @@ setup workspace ~/Projects/work setup workspace ~/Projects/work model openai/gpt-5.5 ``` -当未配置模型时，setup 会按以下顺序选择第一个可用后端，并告诉你它选择了什么： +当尚未配置模型时，setup 会按以下顺序选择第一个可用后端，并告诉你它选择了什么： -- 已有显式模型（如果已配置） +- 已存在的显式模型（如果已配置） - `OPENAI_API_KEY` -> `openai/gpt-5.5` - `ANTHROPIC_API_KEY` -> `anthropic/claude-opus-4-7` - Claude Code CLI -> `claude-cli/claude-opus-4-7` - Codex CLI -> `codex-cli/gpt-5.5` -如果这些都不可用，setup 仍会写入默认工作区，并将模型保持为未设置。安装或登录 Codex/Claude Code，或暴露 -`OPENAI_API_KEY`/`ANTHROPIC_API_KEY`，然后再次运行 setup。 +如果这些都不可用，setup 仍会写入默认工作区，但保持模型未设置。安装或登录 Codex/Claude Code，或暴露 `OPENAI_API_KEY`/`ANTHROPIC_API_KEY`，然后再次运行 setup。 ## 模型辅助规划器 -Crestodian 始终以确定性模式启动。对于确定性解析器无法理解的模糊命令，本地 Crestodian 可以通过 OpenClaw 的常规运行时路径执行一次受限的规划器轮次。它会先使用已配置的 OpenClaw 模型。如果尚无可用的已配置模型，它可以回退到机器上已存在的本地运行时： +Crestodian 始终以确定性模式启动。对于确定性解析器无法理解的模糊命令，本地 Crestodian 可以通过 OpenClaw 的常规运行时路径执行一次受限的规划器轮次。它会优先使用已配置的 OpenClaw 模型。如果尚无可用的已配置模型，它可以回退到机器上已存在的本地运行时： - Claude Code CLI：`claude-cli/claude-opus-4-7` - Codex app-server harness：`openai/gpt-5.5`，带 `agentRuntime.id: "codex"` - Codex CLI：`codex-cli/gpt-5.5` -模型辅助规划器不能直接更改配置。它必须将请求转换为 Crestodian 的某个类型化命令，然后再应用常规的批准和审计规则。Crestodian 会在执行任何操作之前打印它所使用的模型和解释后的命令。无配置的回退规划器轮次是临时的，在运行时支持的情况下会禁用工具，并使用临时工作区/会话。 +模型辅助规划器不能直接修改配置。它必须先将请求转换为 Crestodian 的某个类型化命令，然后才会应用常规的批准和审计规则。Crestodian 会在执行任何操作之前打印它使用的模型以及解释后的命令。无配置的回退规划器轮次是临时的，在运行时支持的情况下会禁用工具，并使用临时工作区/会话。 -消息渠道救援模式不会使用模型辅助规划器。远程救援保持确定性，这样损坏或被攻陷的正常智能体路径就不能被用作配置编辑器。 +消息渠道救援模式不使用模型辅助规划器。远程救援保持确定性，这样损坏或被入侵的正常智能体路径就不能被用作配置编辑器。 ## 切换到智能体 @@ -170,19 +167,19 @@ switch to main agent `openclaw tui`、`openclaw chat` 和 `openclaw terminal` 仍会直接打开常规智能体 TUI。它们不会启动 Crestodian。 -切换到常规 TUI 后，使用 `/crestodian` 返回 Crestodian。 -你可以附带后续请求： +切换到常规 TUI 后，使用 `/crestodian` 可返回 Crestodian。 +你还可以附带后续请求： ```text /crestodian /crestodian restart gateway ``` -TUI 内的智能体切换会留下一个提示，说明 `/crestodian` 可用。 +TUI 内部的智能体切换会留下一个提示痕迹，表明 `/crestodian` 可用。 ## 消息救援模式 -消息救援模式是 Crestodian 的消息渠道入口。它适用于你的正常智能体已失效，但像 WhatsApp 这样的受信任渠道仍然可以接收命令的情况。 +消息救援模式是 Crestodian 的消息渠道入口点。它适用于这样的场景：你的常规智能体已失效，但受信任的渠道（如 WhatsApp）仍然可以接收命令。 支持的文本命令： @@ -199,28 +196,28 @@ You: /crestodian yes OpenClaw: Applied. Audit entry written. ``` -也可以通过本地提示或救援模式排队创建智能体： +也可以从本地提示符或救援模式排队创建智能体： ```text create agent work workspace ~/Projects/work model openai/gpt-5.5 /crestodian create agent work workspace ~/Projects/work ``` -远程救援模式是一个管理员界面。必须将其视为远程配置修复，而不是普通聊天。 +远程救援模式是一个管理员界面。必须像对待远程配置修复一样对待它，而不能像普通聊天那样对待。 远程救援的安全约定： -- 当沙箱隔离处于激活状态时禁用。如果某个智能体/会话已被沙箱隔离，Crestodian 必须拒绝远程救援，并说明需要本地 CLI 修复。 -- 默认有效状态是 `auto`：仅在受信任的 YOLO 操作中允许远程救援，此时运行时已经具有未沙箱隔离的本地权限。 -- 要求明确的所有者身份。救援不得接受通配发送者规则、开放群组策略、未认证的 webhook 或匿名渠道。 -- 默认仅限所有者私信。群组/渠道救援需要显式选择启用。 -- 远程救援不能打开本地 TUI，也不能切换到交互式智能体会话。智能体交接请使用本地 `openclaw`。 +- 当沙箱隔离处于激活状态时禁用。如果某个智能体/会话处于沙箱隔离中，Crestodian 必须拒绝远程救援，并说明需要本地 CLI 修复。 +- 默认生效状态为 `auto`：仅在受信任的 YOLO 操作中允许远程救援，此时运行时已经具有未沙箱隔离的本地权限。 +- 需要显式的所有者身份。救援不得接受通配符发送者规则、开放群组策略、未经身份验证的 webhook 或匿名渠道。 +- 默认仅允许所有者私信。群组/渠道救援需要显式选择启用。 +- 远程救援不能打开本地 TUI，也不能切换到交互式智能体会话。智能体切换请使用本地 `openclaw`。 - 即使在救援模式下，持久化写入仍然需要批准。 -- 审计每个已应用的救援操作。消息渠道救援会记录渠道、账号、发送者和源地址元数据。更改配置的操作还会记录变更前后的配置哈希。 -- 绝不回显密钥。`SecretRef` 检查应报告可用性，而不是值。 -- 如果 Gateway 网关 存活，优先使用 Gateway 网关 类型化操作。如果 Gateway 网关 已失效，只使用不依赖常规 Agent loop 的最小本地修复界面。 +- 审计每一个已应用的救援操作。消息渠道救援会记录渠道、账户、发送者和源地址元数据。修改配置的操作还会记录修改前后的配置哈希。 +- 绝不回显密钥。SecretRef 检查应报告可用性，而不是值。 +- 如果 Gateway 网关存活，优先使用 Gateway 网关类型化操作。如果 Gateway 网关已失效，则只使用不依赖正常智能体循环的最小本地修复界面。 -配置形状： +配置结构： ```jsonc { @@ -235,41 +232,41 @@ create agent work workspace ~/Projects/work model openai/gpt-5.5 `enabled` 应接受： -- `"auto"`：默认值。仅当有效运行时是 YOLO 且沙箱隔离关闭时允许。 -- `false`：绝不允许消息渠道救援。 -- `true`：当所有者/渠道检查通过时显式允许救援。但这仍然不能绕过沙箱隔离拒绝。 +- `"auto"`：默认值。仅当生效运行时为 YOLO 且沙箱隔离关闭时允许。 +- `false`：永不允许消息渠道救援。 +- `true`：当所有者/渠道检查通过时显式允许救援。但这仍不得绕过沙箱隔离拒绝。 -默认的 `"auto"` YOLO 姿态是： +默认的 `"auto"` YOLO 姿态为： -- 沙箱模式解析为 `off` +- sandbox 模式解析为 `off` - `tools.exec.security` 解析为 `full` - `tools.exec.ask` 解析为 `off` -远程救援由 Docker lane 覆盖： +远程救援由以下 Docker lane 覆盖： ```bash pnpm test:docker:crestodian-rescue ``` -无配置的本地规划器回退由以下内容覆盖： +无配置的本地规划器回退由以下命令覆盖： ```bash pnpm test:docker:crestodian-planner ``` -一个可选启用的实时渠道命令界面冒烟测试会检查 `/crestodian status`，以及通过救援处理器完成一次持久化批准往返： +一个选择启用的实时渠道命令界面冒烟测试会检查 `/crestodian status`，以及通过救援处理器完成一次持久化批准往返： ```bash pnpm test:live:crestodian-rescue-channel ``` -通过 Crestodian 进行的全新无配置 setup 由以下内容覆盖： +通过 Crestodian 进行的全新无配置设置由以下命令覆盖： ```bash pnpm test:docker:crestodian-first-run ``` -该 lane 从一个空状态目录开始，将裸 `openclaw` 路由到 Crestodian，设置默认模型，创建一个额外智能体，通过插件启用加 token `SecretRef` 配置 Discord，验证配置，并检查审计日志。QA Lab 还为相同的 Ring 0 流程提供了一个基于仓库的场景： +该 lane 从空状态目录开始，将裸 `openclaw` 路由到 Crestodian，设置默认模型，创建额外智能体，通过插件启用和令牌 SecretRef 配置 Discord，验证配置，并检查审计日志。QA Lab 还为相同的 Ring 0 流程提供了一个基于仓库的场景： ```bash pnpm openclaw qa suite --scenario crestodian-ring-zero-setup @@ -281,4 +278,4 @@ pnpm openclaw qa suite --scenario crestodian-ring-zero-setup - [Doctor](/zh-CN/cli/doctor) - [TUI](/zh-CN/cli/tui) - [沙箱](/zh-CN/cli/sandbox) -- [安全性](/zh-CN/cli/security) +- [安全](/zh-CN/cli/security) diff --git a/docs/zh-CN/concepts/model-providers.md b/docs/zh-CN/concepts/model-providers.md index 8f9a273e4..e5e87718c 100644 --- a/docs/zh-CN/concepts/model-providers.md +++ b/docs/zh-CN/concepts/model-providers.md @@ -1,87 +1,87 @@ --- read_when: - - 你需要一份按提供商逐一说明的模型设置参考 + - 你需要一份按提供商分别整理的模型设置参考文档 - 你想要模型提供商的示例配置或 CLI 新手引导命令 sidebarTitle: Model providers summary: 模型提供商概览，包含示例配置和 CLI 流程 title: 模型提供商 x-i18n: - generated_at: "2026-04-27T06:03:49Z" + generated_at: "2026-04-27T07:11:16Z" model: gpt-5.4 provider: openai - source_hash: d588d4a77998c7582236ef3d38b7f974a6293572c4c9cf5b4e2f2ab78e3bd36e + source_hash: 65d4d7cfdac9a641c9746077b3352597faefe342e1d55bd9faf5f0fab5b36d3a source_path: concepts/model-providers.md workflow: 15 --- -**LLM/模型提供商**参考（不是像 WhatsApp/Telegram 这样的聊天渠道）。有关模型选择规则，请参见 [Models](/zh-CN/concepts/models)。 +**LLM/模型提供商**参考文档（不是像 WhatsApp/Telegram 这样的聊天渠道）。有关模型选择规则，请参阅 [Models](/zh-CN/concepts/models)。 ## 快速规则 - + - 模型引用使用 `provider/model`（示例：`opencode/claude-opus-4-6`）。 - 设置后，`agents.defaults.models` 会作为允许列表。 - - CLI 辅助工具：`openclaw onboard`、`openclaw models list`、`openclaw models set `。 - - `models.providers.*.contextWindow` / `contextTokens` / `maxTokens` 设置提供商级默认值；`models.providers.*.models[].contextWindow` / `contextTokens` / `maxTokens` 则按模型覆盖这些值。 - - 回退规则、冷却探测和会话覆盖持久化：[模型故障切换](/zh-CN/concepts/model-failover)。 + - CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set `。 + - `models.providers.*.contextWindow` / `contextTokens` / `maxTokens` 设置提供商级默认值；`models.providers.*.models[].contextWindow` / `contextTokens` / `maxTokens` 会按模型覆盖这些值。 + - 回退规则、冷却探测和会话覆盖持久化： [模型故障转移](/zh-CN/concepts/model-failover)。 OpenAI 系列路由按前缀区分： - - `openai/` 在 Pi 中使用直接 OpenAI API key 提供商。 - - `openai-codex/` 在 Pi 中使用 Codex OAuth。 - - `openai/` 加上 `agents.defaults.agentRuntime.id: "codex"` 时，使用原生 Codex app-server harness。 + - `openai/` 在 PI 中使用直接的 OpenAI API 密钥提供商。 + - `openai-codex/` 在 PI 中使用 Codex OAuth。 + - `openai/` 加上 `agents.defaults.agentRuntime.id: "codex"` 则使用原生 Codex 应用服务器 Codex harness。 - 请参见 [OpenAI](/zh-CN/providers/openai) 和 [Codex harness](/zh-CN/plugins/codex-harness)。如果你对 provider/运行时拆分感到困惑，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。 + 请参阅 [OpenAI](/zh-CN/providers/openai) 和 [Codex harness](/zh-CN/plugins/codex-harness)。如果你对提供商/运行时拆分感到困惑，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。 - 插件自动启用遵循相同边界：`openai-codex/` 属于 OpenAI 插件，而 Codex 插件则通过 `agentRuntime.id: "codex"` 或旧版 `codex/` 引用启用。 + 插件自动启用遵循相同边界：`openai-codex/` 属于 OpenAI 插件，而 Codex 插件由 `agentRuntime.id: "codex"` 或旧版 `codex/` 引用启用。 - GPT-5.5 可通过 `openai/gpt-5.5` 用于直接 API key 流量，通过 Pi 中的 `openai-codex/gpt-5.5` 用于 Codex OAuth，以及在设置 `agentRuntime.id: "codex"` 时通过原生 Codex app-server harness 使用。 + GPT-5.5 可通过 `openai/gpt-5.5` 用于直接 API 密钥流量，通过 `openai-codex/gpt-5.5` 在 PI 中用于 Codex OAuth，并且在设置 `agentRuntime.id: "codex"` 时可通过原生 Codex 应用服务器 Codex harness 使用。 - CLI 运行时使用相同的拆分方式：选择规范模型引用，例如 `anthropic/claude-*`、`google/gemini-*` 或 `openai/gpt-*`，然后在需要本地 CLI 后端时，将 `agents.defaults.agentRuntime.id` 设置为 `claude-cli`、`google-gemini-cli` 或 `codex-cli`。 + CLI 运行时使用相同的拆分方式：选择规范模型引用，例如 `anthropic/claude-*`、`google/gemini-*` 或 `openai/gpt-*`，然后在你想使用本地 CLI 后端时，将 `agents.defaults.agentRuntime.id` 设置为 `claude-cli`、`google-gemini-cli` 或 `codex-cli`。 旧版 `claude-cli/*`、`google-gemini-cli/*` 和 `codex-cli/*` 引用会迁移回规范提供商引用，并将运行时单独记录。 -## 由插件拥有的提供商行为 +## 插件拥有的提供商行为 -大多数提供商特定逻辑都位于提供商插件（`registerProvider(...)`）中，而 OpenClaw 保留通用推理循环。插件负责新手引导、模型目录、认证环境变量映射、传输/配置规范化、工具模式清理、故障切换分类、OAuth 刷新、使用情况报告、thinking/reasoning 配置等。 +大多数提供商特定逻辑都位于提供商插件（`registerProvider(...)`）中，而 OpenClaw 保留通用推理循环。插件负责新手引导、模型目录、身份验证环境变量映射、传输/配置规范化、工具模式清理、故障转移分类、OAuth 刷新、使用情况报告、thinking/reasoning 配置等。 -提供商 SDK 钩子和内置插件示例的完整列表位于[提供商插件](/zh-CN/plugins/sdk-provider-plugins)。如果某个提供商需要完全自定义的请求执行器，则属于另一个更深层的扩展面。 +提供商 SDK 钩子和内置插件示例的完整列表位于 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)。如果某个提供商需要完全自定义的请求执行器，那将属于另一个更深层的扩展接口。 -提供商运行时 `capabilities` 是共享运行器元数据（提供商家族、transcript/工具怪癖、传输/缓存提示）。它不同于[公共能力模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是插件注册了什么（文本推理、语音等）。 +提供商运行时 `capabilities` 是共享运行器元数据（提供商家族、转录/工具行为差异、传输/缓存提示）。它不同于[公共能力模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是插件注册了什么能力（文本推理、语音等）。 -## API key 轮换 +## API 密钥轮换 - - 通过以下方式配置多个 key： + + 通过以下方式配置多个密钥： - `OPENCLAW_LIVE__KEY`（单个实时覆盖，最高优先级） - `_API_KEYS`（逗号或分号分隔的列表） - - `_API_KEY`（主 key） + - `_API_KEY`（主密钥） - `_API_KEY_*`（编号列表，例如 `_API_KEY_1`） - 对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退项纳入。key 选择顺序会保留优先级并去重值。 + 对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退包含在内。密钥选择顺序会保留优先级并去重值。 - - 仅当收到限流响应时，请求才会使用下一个 key 重试（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性使用限制消息）。 - - 非限流失败会立即失败；不会尝试 key 轮换。 - - 当所有候选 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 @@ -89,17 +89,17 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** `models.provide - 认证：`OPENAI_API_KEY` - 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单一覆盖） - 示例模型：`openai/gpt-5.5`、`openai/gpt-5.4-mini` -- 如果某个特定安装或 API key 的行为不同，可使用 `openclaw models list --provider openai` 验证账户/模型可用性。 +- 如果特定安装或 API 密钥的行为不同，请使用 `openclaw models list --provider openai` 验证账户/模型可用性。 - CLI：`openclaw onboard --auth-choice openai-api-key` -- 默认传输方式为 `auto`（优先 WebSocket，回退 SSE） -- 可按模型通过 `agents.defaults.models["openai/"].params.transport` 覆盖（`"sse"`、`"websocket"` 或 `"auto"`） +- 默认传输为 `auto`（优先 WebSocket，回退到 SSE） +- 可通过 `agents.defaults.models["openai/"].params.transport` 按模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） - 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`、提示缓存提示以及 OpenAI reasoning 兼容的负载整形；代理路由则不会 -- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中会被有意抑制，因为实时 OpenAI API 请求会拒绝它，而当前 Codex 目录也未暴露它 +- 可通过 `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`、提示缓存提示以及 OpenAI reasoning 兼容载荷整形；代理路由不会 +- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意隐藏，因为实时 OpenAI API 请求会拒绝它，而且当前 Codex 目录也未暴露它 ```json5 { @@ -114,14 +114,14 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要** `models.provide - 可选轮换：`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 key 和 OAuth 认证流量；OpenClaw 会将其映射到 Anthropic `service_tier`（`auto` 或 `standard_only`） +- 直接的公开 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API 密钥和 OAuth 认证流量；OpenClaw 会将其映射为 Anthropic `service_tier`（`auto` 或 `standard_only`） - 推荐的 Claude CLI 配置会保持模型引用为规范形式，并单独选择 CLI - 后端：`anthropic/claude-opus-4-7` 配合 + 后端：`anthropic/claude-opus-4-7` 搭配 `agents.defaults.agentRuntime.id: "claude-cli"`。旧版 - `claude-cli/claude-opus-4-7` 引用仍可用于兼容。 + `claude-cli/claude-opus-4-7` 引用仍可用于兼容性场景。 -Anthropic 员工告知我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 会将 Claude CLI 复用和 `claude -p` 用法视为该集成的获准方式。Anthropic setup-token 仍作为受支持的 OpenClaw token 路径保留，但在可用时，OpenClaw 现在更偏好 Claude CLI 复用和 `claude -p`。 +Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 使用方式现已再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 将 Claude CLI 复用和 `claude -p` 用法视为此集成的受支持方式。Anthropic setup-token 仍可作为受支持的 OpenClaw 令牌路径使用，但现在 OpenClaw 在可用时更倾向于 Claude CLI 复用和 `claude -p`。 ```json5 @@ -135,19 +135,19 @@ Anthropic 员工告知我们，OpenClaw 风格的 Claude CLI 用法再次被允 - 提供商：`openai-codex` - 认证：OAuth（ChatGPT） - PI 模型引用：`openai-codex/gpt-5.5` -- 原生 Codex app-server harness 引用：`openai/gpt-5.5` 配合 `agents.defaults.agentRuntime.id: "codex"` -- 原生 Codex app-server harness 文档：[Codex harness](/zh-CN/plugins/codex-harness) +- 原生 Codex 应用服务器 Codex harness 引用：`openai/gpt-5.5` 配合 `agents.defaults.agentRuntime.id: "codex"` +- 原生 Codex 应用服务器 Codex harness 文档： [Codex harness](/zh-CN/plugins/codex-harness) - 旧版模型引用：`codex/gpt-*` -- 插件边界：`openai-codex/*` 加载 OpenAI 插件；原生 Codex app-server 插件仅通过 Codex harness 运行时或旧版 `codex/*` 引用来选择。 +- 插件边界：`openai-codex/*` 会加载 OpenAI 插件；原生 Codex 应用服务器插件仅由 Codex harness 运行时或旧版 `codex/*` 引用选择。 - CLI：`openclaw onboard --auth-choice openai-codex` 或 `openclaw models auth login --provider openai-codex` -- 默认传输方式为 `auto`（优先 WebSocket，回退 SSE） -- 可按 PI 模型通过 `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` +- 默认传输为 `auto`（优先 WebSocket，回退到 SSE） +- 可通过 `agents.defaults.models["openai-codex/"].params.transport` 按 PI 模型覆盖（`"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` - `openai-codex/gpt-5.5` 使用 Codex 目录原生的 `contextWindow = 400000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限 -- 政策说明：OpenAI Codex OAuth 明确支持用于 OpenClaw 这样的外部工具/工作流。 -- 当你想使用 Codex OAuth/订阅路线时，使用 `openai-codex/gpt-5.5`；当你的 API key 设置和本地目录暴露了公共 API 路线时，使用 `openai/gpt-5.5`。 +- 策略说明：OpenAI Codex OAuth 明确支持用于 OpenClaw 这类外部工具/工作流。 +- 当你想使用 Codex OAuth/订阅路线时，请使用 `openai-codex/gpt-5.5`；当你的 API 密钥设置和本地目录暴露了公开 API 路线时，请使用 `openai/gpt-5.5`。 ```json5 { @@ -174,7 +174,7 @@ Anthropic 员工告知我们，OpenClaw 风格的 Claude CLI 用法再次被允 Z.AI Coding Plan 或通用 API 端点。 - MiniMax Coding Plan OAuth 或 API key 访问。 + MiniMax Coding Plan OAuth 或 API 密钥访问。 Qwen Cloud 提供商接口，以及 Alibaba DashScope 和 Coding Plan 端点映射。 @@ -195,16 +195,16 @@ Anthropic 员工告知我们，OpenClaw 风格的 Claude CLI 用法再次被允 } ``` -### Google Gemini（API key） +### 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_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` - 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被规范化为 `google/gemini-3-flash-preview` - CLI：`openclaw onboard --auth-choice gemini-api-key` -- Thinking：`/think adaptive` 使用 Google 动态 thinking。Gemini 3/3.1 省略固定的 `thinkingLevel`；Gemini 2.5 则发送 `thinkingBudget: -1`。 -- 直接 Gemini 运行还接受 `agents.defaults.models["google/"].params.cachedContent`（或旧版 `cached_content`），以转发提供商原生的 `cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead` +- Thinking：`/think adaptive` 使用 Google 动态 thinking。Gemini 3/3.1 不包含固定的 `thinkingLevel`；Gemini 2.5 会发送 `thinkingBudget: -1`。 +- 直接 Gemini 运行也接受 `agents.defaults.models["google/"].params.cachedContent`（或旧版 `cached_content`），以转发提供商原生的 `cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead` ### Google Vertex 和 Gemini CLI @@ -212,7 +212,7 @@ Anthropic 员工告知我们，OpenClaw 风格的 Claude CLI 用法再次被允 - 认证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程 -OpenClaw 中的 Gemini CLI OAuth 是非官方集成。有些用户报告在使用第三方客户端后 Google 账户受限。如果你选择继续，请先查看 Google 条款，并使用非关键账户。 +OpenClaw 中的 Gemini CLI OAuth 是非官方集成。有些用户报告称，在使用第三方客户端后，其 Google 账户受到限制。如果你选择继续，请先查看 Google 条款并使用非关键账户。 Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。 @@ -242,15 +242,15 @@ Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。 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 主机上的认证配置文件中。 + 默认模型：`google-gemini-cli/gemini-3-flash-preview`。你**不需要**将 client id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储在 Gateway 网关主机上的认证配置文件中。 - 如果登录后请求失败，请在 gateway 主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`。 + 如果登录后请求失败，请在 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） @@ -275,68 +275,68 @@ Gemini CLI JSON 回复从 `response` 中解析；使用量会回退到 `stats` - 示例模型：`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` 发现还可以进一步扩展运行时目录。 -- `kilocode/kilo/auto` 背后的精确上游路由由 Kilo Gateway 拥有，并非在 OpenClaw 中硬编码。 +- 静态回退目录内置 `kilocode/kilo/auto`；实时 `https://api.kilo.ai/api/gateway/models` 发现可进一步扩展运行时目录。 +- `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` | -| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` | -| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — | -| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek/deepseek-v4-flash` | -| 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` | -| 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` | -| Moonshot | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` | -| NVIDIA | `nvidia` | `NVIDIA_API_KEY` | `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` | -| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | `openrouter/auto` | -| Qianfan | `qianfan` | `QIANFAN_API_KEY` | `qianfan/deepseek-v3.2` | -| Qwen Cloud | `qwen` | `QWEN_API_KEY` / `MODELSTUDIO_API_KEY` / `DASHSCOPE_API_KEY` | `qwen/qwen3.5-plus` | -| 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` | -| 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` | +| 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` | — | +| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek/deepseek-v4-flash` | +| 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` | +| 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` | +| Moonshot | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` | +| NVIDIA | `nvidia` | `NVIDIA_API_KEY` | `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` | +| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | `openrouter/auto` | +| Qianfan | `qianfan` | `QIANFAN_API_KEY` | `qianfan/deepseek-v3.2` | +| Qwen Cloud | `qwen` | `QWEN_API_KEY` / `MODELSTUDIO_API_KEY` / `DASHSCOPE_API_KEY` | `qwen/qwen3.5-plus` | +| 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` | +| 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.ai` 路由上应用其应用归因请求头和 Anthropic `cache_control` 标记。DeepSeek、Moonshot 和 ZAI 引用可用于 OpenRouter 管理的提示缓存 TTL，但不会收到 Anthropic 缓存标记。作为代理风格的 OpenAI 兼容路径，它会跳过仅适用于原生 OpenAI 的整形（`serviceTier`、Responses `store`、提示缓存提示、OpenAI reasoning 兼容性）。基于 Gemini 的引用仅保留代理 Gemini thought-signature 清理。 + 仅在已验证的 `openrouter.ai` 路由上应用其应用归因请求头和 Anthropic `cache_control` 标记。DeepSeek、Moonshot 和 ZAI 引用符合 OpenRouter 管理的提示缓存的缓存 TTL 条件，但不会收到 Anthropic 缓存标记。作为代理式 OpenAI 兼容路径，它会跳过仅适用于原生 OpenAI 的整形逻辑（`serviceTier`、Responses `store`、提示缓存提示、OpenAI reasoning 兼容性）。基于 Gemini 的引用仅保留代理 Gemini thought-signature 清理。 基于 Gemini 的引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理 reasoning 的引用会跳过代理 reasoning 注入。 - API key 新手引导会写入显式的纯文本 M2.7 聊天模型定义；图像理解仍保留在插件拥有的 `MiniMax-VL-01` 媒体提供商上。 + API 密钥新手引导会写入显式的纯文本 M2.7 聊天模型定义；图像理解仍保留在由插件拥有的 `MiniMax-VL-01` 媒体提供商上。 - 使用 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` 禁用。 + 使用 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` 禁用。 GLM 模型使用 `zai-glm-4.7` / `zai-glm-4.6`；OpenAI 兼容基础 URL 为 `https://api.cerebras.ai/v1`。 -## 通过 `models.providers` 使用提供商（自定义/base URL） +## 通过 `models.providers` 使用提供商（自定义/基础 URL） -使用 `models.providers`（或 `models.json`）来添加**自定义**提供商或 OpenAI/Anthropic 兼容代理。 +使用 `models.providers`（或 `models.json`）添加**自定义**提供商或兼容 OpenAI/Anthropic 的代理。 -下面许多内置提供商插件已经发布了默认目录。仅当你想覆盖默认基础 URL、请求头或模型列表时，才使用显式的 `models.providers.` 条目。 +下方许多内置提供商插件已经发布了默认目录。只有当你想覆盖默认基础 URL、请求头或模型列表时，才需要显式使用 `models.providers.` 条目。 ### Moonshot AI（Kimi） -Moonshot 作为内置提供商插件提供。默认请使用内置提供商，仅当你需要覆盖基础 URL 或模型元数据时，才添加显式 `models.providers.moonshot` 条目： +Moonshot 作为内置提供商插件提供。默认使用内置提供商；只有在你需要覆盖基础 URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目： - 提供商：`moonshot` - 认证：`MOONSHOT_API_KEY` @@ -391,13 +391,13 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点： } ``` -旧版 `kimi/k2p5` 仍作为兼容模型 id 被接受。 +旧版 `kimi/k2p5` 仍然接受作为兼容性模型 id。 ### Volcano Engine（Doubao） -Volcano Engine（火山引擎）为中国用户提供对 Doubao 和其他模型的访问。 +Volcano Engine（火山引擎）为中国用户提供 Doubao 和其他模型的访问。 -- 提供商：`volcengine`（编码：`volcengine-plan`） +- 提供商：`volcengine`（编码版：`volcengine-plan`） - 认证：`VOLCANO_ENGINE_API_KEY` - 示例模型：`volcengine-plan/ark-code-latest` - CLI：`openclaw onboard --auth-choice volcengine-api-key` @@ -410,9 +410,9 @@ Volcano Engine（火山引擎）为中国用户提供对 Doubao 和其他模型 } ``` -新手引导默认使用 coding 接口，但通用 `volcengine/*` 目录也会同时注册。 +新手引导默认使用编码接口，但通用 `volcengine/*` 目录也会同时注册。 -在 onboarding/configure 模型选择器中，Volcengine 认证选项会同时优先显示 `volcengine/*` 和 `volcengine-plan/*` 行。如果这些模型尚未加载，OpenClaw 会回退到未过滤目录，而不是显示空的提供商范围选择器。 +在新手引导/配置模型选择器中，Volcengine 认证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未筛选目录，而不是显示一个空的按提供商筛选的选择器。 @@ -422,7 +422,7 @@ Volcano Engine（火山引擎）为中国用户提供对 Doubao 和其他模型 - `volcengine/glm-4-7-251222`（GLM 4.7） - `volcengine/deepseek-v3-2-251201`（DeepSeek V3.2 128K） - + - `volcengine-plan/ark-code-latest` - `volcengine-plan/doubao-seed-code` - `volcengine-plan/kimi-k2.5` @@ -435,7 +435,7 @@ Volcano Engine（火山引擎）为中国用户提供对 Doubao 和其他模型 BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。 -- 提供商：`byteplus`（编码：`byteplus-plan`） +- 提供商：`byteplus`（编码版：`byteplus-plan`） - 认证：`BYTEPLUS_API_KEY` - 示例模型：`byteplus-plan/ark-code-latest` - CLI：`openclaw onboard --auth-choice byteplus-api-key` @@ -448,9 +448,9 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。 } ``` -新手引导默认使用 coding 接口，但通用 `byteplus/*` 目录也会同时注册。 +新手引导默认使用编码接口，但通用 `byteplus/*` 目录也会同时注册。 -在 onboarding/configure 模型选择器中，BytePlus（国际版）认证选项会同时优先显示 `byteplus/*` 和 `byteplus-plan/*` 行。如果这些模型尚未加载，OpenClaw 会回退到未过滤目录，而不是显示空的提供商范围选择器。 +在新手引导/配置模型选择器中，BytePlus（国际版）认证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未筛选目录，而不是显示一个空的按提供商筛选的选择器。 @@ -458,7 +458,7 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。 - `byteplus/kimi-k2-5-260127`（Kimi K2.5） - `byteplus/glm-4-7-251222`（GLM 4.7） - + - `byteplus-plan/ark-code-latest` - `byteplus-plan/doubao-seed-code` - `byteplus-plan/kimi-k2.5` @@ -469,7 +469,7 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。 ### Synthetic -Synthetic 通过 `synthetic` 提供商提供 Anthropic 兼容模型： +Synthetic 通过 `synthetic` 提供商提供兼容 Anthropic 的模型： - 提供商：`synthetic` - 认证：`SYNTHETIC_API_KEY` @@ -497,26 +497,26 @@ 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 key（Global）：`--auth-choice minimax-global-api` -- MiniMax API key（CN）：`--auth-choice minimax-cn-api` +- MiniMax OAuth（全球）：`--auth-choice minimax-global-oauth` +- MiniMax OAuth（中国）：`--auth-choice minimax-cn-oauth` +- MiniMax API 密钥（全球）：`--auth-choice minimax-global-api` +- MiniMax API 密钥（中国）：`--auth-choice minimax-cn-api` - 认证：`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` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 +在 MiniMax 的 Anthropic 兼容流式传输路径上，除非你显式设置，否则 OpenClaw 默认禁用 thinking，并且 `/fast on` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 由插件拥有的能力拆分： -- 文本/聊天默认保留在 `minimax/MiniMax-M2.7` +- 文本/聊天默认使用 `minimax/MiniMax-M2.7` - 图像生成使用 `minimax/image-01` 或 `minimax-portal/image-01` -- 图像理解在两种 MiniMax 认证路径上都使用插件拥有的 `MiniMax-VL-01` -- Web 搜索仍使用提供商 id `minimax` +- 图像理解在两种 MiniMax 认证路径上都使用由插件拥有的 `MiniMax-VL-01` +- Web 搜索保持在提供商 id `minimax` ### LM Studio @@ -526,7 +526,7 @@ LM Studio 作为内置提供商插件提供，并使用原生 API： - 认证：`LM_API_TOKEN` - 默认推理基础 URL：`http://localhost:1234/v1` -然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）： +然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 id）： ```json5 { @@ -536,16 +536,16 @@ LM Studio 作为内置提供商插件提供，并使用原生 API： } ``` -OpenClaw 使用 LM Studio 原生的 `/api/v1/models` 和 `/api/v1/models/load` 进行发现和自动加载，默认使用 `/v1/chat/completions` 进行推理。设置和故障排除请参见 [/providers/lmstudio](/zh-CN/providers/lmstudio)。 +OpenClaw 使用 LM Studio 原生的 `/api/v1/models` 和 `/api/v1/models/load` 进行发现和自动加载，默认使用 `/v1/chat/completions` 进行推理。有关设置和故障排除，请参阅 [/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) +- 安装： [https://ollama.com/download](https://ollama.com/download) ```bash # 安装 Ollama，然后拉取一个模型： @@ -560,23 +560,23 @@ 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 { @@ -586,23 +586,23 @@ export VLLM_API_KEY="vllm-local" } ``` -详情请参见 [/providers/vllm](/zh-CN/providers/vllm)。 +详情请参阅 [/providers/vllm](/zh-CN/providers/vllm)。 ### SGLang -SGLang 作为内置提供商插件提供，适用于快速自托管的 OpenAI 兼容服务器： +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 { @@ -612,18 +612,18 @@ export SGLANG_API_KEY="sglang-local" } ``` -详情请参见 [/providers/sglang](/zh-CN/providers/sglang)。 +详情请参阅 [/providers/sglang](/zh-CN/providers/sglang)。 ### 本地代理（LM Studio、vLLM、LiteLLM 等） -示例（OpenAI 兼容）： +示例（兼容 OpenAI）： ```json5 { agents: { defaults: { model: { primary: "lmstudio/my-local-model" }, - models: { "lmstudio/my-local-model": { alias: "Local" } }, + models: { "lmstudio/my-local-model": { alias: "本地" } }, }, }, models: { @@ -636,7 +636,7 @@ export SGLANG_API_KEY="sglang-local" models: [ { id: "my-local-model", - name: "Local Model", + name: "本地模型", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, @@ -652,7 +652,7 @@ export SGLANG_API_KEY="sglang-local" - 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选的。省略时，OpenClaw 默认使用： + 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选的。省略时，OpenClaw 默认值为： - `reasoning: false` - `input: ["text"]` @@ -664,13 +664,13 @@ export SGLANG_API_KEY="sglang-local" - - 对于非原生端点上的 `api: "openai-completions"`（任何主机不是 `api.openai.com` 的非空 `baseUrl`），OpenClaw 会强制 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。 - - 代理风格的 OpenAI 兼容路由也会跳过仅适用于原生 OpenAI 的请求整形：不使用 `service_tier`，不使用 Responses `store`，不使用 Completions `store`，不使用提示缓存提示，不使用 OpenAI reasoning 兼容负载整形，也不使用隐藏的 OpenClaw 归因请求头。 - - 对于需要厂商特定字段的 OpenAI 兼容 Completions 代理，可设置 `agents.defaults.models["provider/model"].params.extra_body`（或 `extraBody`），以将额外 JSON 合并到出站请求体中。 - - 对于 vLLM chat template 控制，可设置 `agents.defaults.models["provider/model"].params.chat_template_kwargs`。当会话 thinking 级别为 off 时，OpenClaw 会自动为 `vllm/nemotron-3-*` 发送 `enable_thinking: false` 和 `force_nonempty_content: true`。 - - 对于较慢的本地模型或远程 LAN/tailnet 主机，请设置 `models.providers..timeoutSeconds`。这会延长提供商模型 HTTP 请求处理时间，包括连接、请求头、正文流式传输以及总的受保护获取超时，而不会增加整个智能体运行时超时。 - - 如果 `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`、没有 Completions `store`、没有提示缓存提示、没有 OpenAI reasoning 兼容载荷整形，也没有隐藏的 OpenClaw 归因请求头。 + - 对于需要厂商特定字段的 OpenAI 兼容 Completions 代理，请设置 `agents.defaults.models["provider/model"].params.extra_body`（或 `extraBody`），以将额外 JSON 合并到出站请求体中。 + - 对于 vLLM chat-template 控制，请设置 `agents.defaults.models["provider/model"].params.chat_template_kwargs`。当会话 thinking 级别关闭时，OpenClaw 会自动为 `vllm/nemotron-3-*` 发送 `enable_thinking: false` 和 `force_nonempty_content: true`。 + - 对于较慢的本地模型或远程 LAN/tailnet 主机，请设置 `models.providers..timeoutSeconds`。这会延长提供商模型 HTTP 请求处理时间，包括连接、请求头、正文流式传输以及整个受保护抓取的中止时间，但不会增加整个智能体运行时超时。 + - 如果 `baseUrl` 为空或省略，OpenClaw 会保留默认的 OpenAI 行为（解析到 `api.openai.com`）。 + - 出于安全考虑，即使显式设置了 `compat.supportsDeveloperRole: true`，在非原生 `openai-completions` 端点上仍会被覆盖。 @@ -682,11 +682,11 @@ openclaw models set opencode/claude-opus-4-6 openclaw models list ``` -另请参见：[配置](/zh-CN/gateway/configuration) 了解完整配置示例。 +另请参阅： [配置](/zh-CN/gateway/configuration)，了解完整配置示例。 ## 相关内容 - [配置参考](/zh-CN/gateway/config-agents#agent-defaults) — 模型配置键 -- [模型故障切换](/zh-CN/concepts/model-failover) — 回退链和重试行为 +- [模型故障转移](/zh-CN/concepts/model-failover) — 回退链和重试行为 - [Models](/zh-CN/concepts/models) — 模型配置和别名 -- [提供商](/zh-CN/providers) — 各提供商设置指南 +- [提供商](/zh-CN/providers) — 按提供商分类的设置指南 diff --git a/docs/zh-CN/gateway/multiple-gateways.md b/docs/zh-CN/gateway/multiple-gateways.md index 3567ebfbb..b8f2dfac0 100644 --- a/docs/zh-CN/gateway/multiple-gateways.md +++ b/docs/zh-CN/gateway/multiple-gateways.md @@ -1,30 +1,30 @@ --- read_when: - 在同一台机器上运行多个 Gateway 网关 - - 你需要为每个 Gateway 网关隔离配置 / 状态 / 端口 -summary: 在一台主机上运行多个 OpenClaw Gateway 网关（隔离、端口和配置文件） + - 你需要为每个 Gateway 网关提供独立隔离的配置、状态和端口 +summary: 在一台主机上运行多个 OpenClaw Gateway 网关（隔离、端口和配置档案） title: 多个 Gateway 网关 x-i18n: - generated_at: "2026-04-24T18:08:21Z" + generated_at: "2026-04-27T07:11:15Z" model: gpt-5.4 provider: openai - source_hash: 6477a16dc55b694cb73ad6b5140e94529071bad8fc2100ecca88daaa31f9c3c0 + source_hash: 655f9ea5100813d5836f24eb47a5646443f83d70953efa64122633a5a1341002 source_path: gateway/multiple-gateways.md workflow: 15 --- -大多数设置都应只使用一个 Gateway 网关，因为单个 Gateway 网关可以处理多个消息连接和智能体。如果你需要更强的隔离或冗余（例如一个救援机器人），请使用隔离的配置文件 / 端口运行多个独立的 Gateway 网关。 +大多数配置只需要一个 Gateway 网关，因为单个 Gateway 网关就可以处理多个消息连接和智能体。如果你需要更强的隔离性或冗余能力（例如救援机器人），请使用隔离的配置档案和端口运行独立的 Gateway 网关。 -## 最佳推荐设置 +## 最佳推荐配置 -对于大多数用户，最简单的救援机器人设置是： +对大多数用户来说，最简单的救援机器人配置是： -- 主机器人保留在默认配置文件上 -- 救援机器人使用 `--profile rescue` 运行 -- 为救援账号使用一个完全独立的 Telegram 机器人 -- 为救援机器人使用不同的基础端口，例如 `19789` +- 将主机器人保留在默认配置档案上 +- 使用 `--profile rescue` 运行救援机器人 +- 为救援账户使用一个完全独立的 Telegram 机器人 +- 将救援机器人放在不同的基础端口上，例如 `19789` -这样可以让救援机器人与主机器人隔离，因此当主机器人宕机时，它仍可用于调试或应用配置更改。基础端口之间至少保留 20 个端口的间隔，以确保派生的 browser/canvas/CDP 端口永不冲突。 +这样可以让救援机器人与主机器人隔离，因此当主机器人宕机时，它仍然可以调试或应用配置更改。基础端口之间至少保留 20 个端口的间隔，这样派生出的浏览器 / canvas / CDP 端口就永远不会冲突。 ## 救援机器人快速开始 @@ -36,52 +36,52 @@ openclaw --profile rescue onboard openclaw --profile rescue gateway install --port 19789 ``` -如果你的主机器人已经在运行，这通常就是你所需要的全部。 +如果你的主机器人已经在运行，通常这就是你所需要的全部操作。 在执行 `openclaw --profile rescue onboard` 期间： - 使用独立的 Telegram 机器人令牌 -- 保持 `rescue` 配置文件 +- 保持使用 `rescue` 配置档案 - 使用比主机器人至少高 20 的基础端口 -- 接受默认的救援工作区，除非你已经自己管理了一个 +- 接受默认的救援工作区，除非你已经自行管理了一个 -如果新手引导已经为你安装了救援服务，则最后的 `gateway install` 就不需要了。 +如果新手引导已经为你安装了救援服务，那么最后这条 `gateway install` 就不需要了。 ## 为什么这样可行 -救援机器人保持独立，因为它拥有自己的： +救援机器人能够保持独立，是因为它拥有自己独立的： -- 配置文件 / 配置 +- 配置档案 / 配置 - 状态目录 - 工作区 - 基础端口（以及派生端口） - Telegram 机器人令牌 -对于大多数设置，建议为救援配置文件使用一个完全独立的 Telegram 机器人： +对于大多数配置，建议为救援配置档案使用一个完全独立的 Telegram 机器人： -- 易于保持仅限操作员使用 -- 单独的机器人令牌和身份 +- 易于保持为仅限操作员使用 +- 具有独立的机器人令牌和身份 - 独立于主机器人的渠道 / 应用安装 -- 当主机器人损坏时，提供简单的基于私信的恢复路径 +- 当主机器人出现故障时，提供简单的基于私信的恢复路径 ## `--profile rescue onboard` 会更改什么 -`openclaw --profile rescue onboard` 使用普通的新手引导流程，但会将所有内容写入一个独立的配置文件中。 +`openclaw --profile rescue onboard` 使用正常的新手引导流程，但会将所有内容写入一个独立的配置档案。 -实际上，这意味着救援机器人会拥有自己的： +在实际效果上，这意味着救援机器人会拥有自己独立的： - 配置文件 - 状态目录 - 工作区（默认是 `~/.openclaw/workspace-rescue`） - 托管服务名称 -除此之外，提示与普通新手引导相同。 +除此之外，其提示内容与普通新手引导相同。 -## 通用多 Gateway 网关设置 +## 通用多 Gateway 网关配置 -上面的救援机器人布局是最简单的默认方案，但相同的隔离模式也适用于在一台主机上运行任意一对或一组 Gateway 网关。 +上面的救援机器人布局是最简单的默认方案，但同样的隔离模式也适用于在一台主机上运行任意一对或一组 Gateway 网关。 -对于更通用的设置，请为每个额外的 Gateway 网关分配自己的命名配置文件和自己的基础端口： +对于更通用的配置，请为每个额外的 Gateway 网关分配它自己的命名配置档案以及它自己的基础端口： ```bash # main (default profile) @@ -93,7 +93,7 @@ openclaw --profile ops setup openclaw --profile ops gateway --port 19789 ``` -如果你希望两个 Gateway 网关都使用命名配置文件，也完全可行： +如果你希望两个 Gateway 网关都使用命名配置档案，也完全可行： ```bash openclaw --profile main setup @@ -103,43 +103,43 @@ openclaw --profile ops setup openclaw --profile ops gateway --port 19789 ``` -服务也遵循相同模式： +服务也遵循相同的模式： ```bash openclaw gateway install openclaw --profile ops gateway install --port 19789 ``` -如果你想要一个备用操作员通道，请使用救援机器人快速开始。如果你想为不同渠道、租户、工作区或运维角色运行多个长期存在的 Gateway 网关，请使用通用配置文件模式。 +当你想要一个后备的操作员通道时，请使用救援机器人快速开始。当你想为不同的渠道、租户、工作区或运维角色运行多个长期存在的 Gateway 网关时，请使用通用配置档案模式。 ## 隔离检查清单 -为每个 Gateway 网关实例保持以下项唯一： +请确保每个 Gateway 网关实例以下项目都是唯一的： -- `OPENCLAW_CONFIG_PATH` — 每个实例单独的配置文件 -- `OPENCLAW_STATE_DIR` — 每个实例单独的会话、凭证、缓存 -- `agents.defaults.workspace` — 每个实例单独的工作区根目录 +- `OPENCLAW_CONFIG_PATH` — 每个实例各自的配置文件 +- `OPENCLAW_STATE_DIR` — 每个实例各自的会话、凭证、缓存 +- `agents.defaults.workspace` — 每个实例各自的工作区根目录 - `gateway.port`（或 `--port`）— 每个实例唯一 -- 派生的 browser/canvas/CDP 端口 +- 派生出的浏览器 / canvas / CDP 端口 -如果这些是共享的，你将遇到配置竞争和端口冲突。 +如果这些内容被共享，你将遇到配置竞争和端口冲突。 ## 端口映射（派生） 基础端口 = `gateway.port`（或 `OPENCLAW_GATEWAY_PORT` / `--port`）。 -- browser 控制服务端口 = 基础端口 + 2（仅限 local loopback） -- canvas host 由 Gateway 网关 HTTP 服务器提供服务（与 `gateway.port` 相同端口） -- Browser 配置文件的 CDP 端口会从 `browser.controlPort + 9 .. + 108` 自动分配 +- 浏览器控制服务端口 = 基础端口 + 2（仅限 loopback） +- canvas host 由 Gateway 网关 HTTP 服务器提供（与 `gateway.port` 使用同一个端口） +- 浏览器配置档案 CDP 端口会从 `browser.controlPort + 9 .. + 108` 自动分配 -如果你在配置或环境变量中覆盖了这些值，必须确保每个实例都保持唯一。 +如果你在配置或环境变量中覆盖其中任何项，必须确保它们在每个实例之间保持唯一。 -## Browser/CDP 说明（常见陷阱） +## 浏览器 / CDP 说明（常见陷阱） - **不要** 在多个实例上将 `browser.cdpUrl` 固定为相同的值。 -- 每个实例都需要自己的 browser 控制端口和 CDP 范围（从其 gateway 端口派生）。 +- 每个实例都需要它自己的浏览器控制端口和 CDP 范围（从其 Gateway 网关端口派生）。 - 如果你需要显式的 CDP 端口，请为每个实例设置 `browser.profiles..cdpPort`。 -- 远程 Chrome：使用 `browser.profiles..cdpUrl`（按配置文件、按实例设置）。 +- 远程 Chrome：使用 `browser.profiles..cdpUrl`（按配置档案、按实例分别设置）。 ## 手动环境变量示例 @@ -166,11 +166,11 @@ openclaw --profile rescue browser status 说明： -- `gateway status --deep` 有助于发现来自旧安装的陈旧 launchd/systemd/schtasks 服务。 -- 只有在你有意运行多个隔离的 Gateway 网关时，`gateway probe` 中像 `multiple reachable gateways detected` 这样的警告文本才是预期现象。 +- `gateway status --deep` 有助于发现旧安装遗留下来的过时 launchd/systemd/schtasks 服务。 +- 当你有意运行多个隔离的 Gateway 网关时，`gateway probe` 中出现诸如 `multiple reachable gateways detected` 之类的警告文本是预期行为。 ## 相关内容 -- [Gateway runbook](/zh-CN/gateway) -- [Gateway lock](/zh-CN/gateway/gateway-lock) -- [Configuration](/zh-CN/gateway/configuration) +- [Gateway 网关操作手册](/zh-CN/gateway) +- [Gateway 网关锁](/zh-CN/gateway/gateway-lock) +- [配置](/zh-CN/gateway/configuration) diff --git a/docs/zh-CN/gateway/remote-gateway-readme.md b/docs/zh-CN/gateway/remote-gateway-readme.md index 4b5b8fd29..ae9f45bca 100644 --- a/docs/zh-CN/gateway/remote-gateway-readme.md +++ b/docs/zh-CN/gateway/remote-gateway-readme.md @@ -1,12 +1,12 @@ --- read_when: Connecting the macOS app to a remote gateway over SSH -summary: OpenClaw.app 连接远程 Gateway 网关的 SSH 隧道设置 +summary: 用于 OpenClaw.app 连接远程 Gateway 网关的 SSH 隧道设置 title: 远程 Gateway 网关设置 x-i18n: - generated_at: "2026-04-24T04:02:25Z" + generated_at: "2026-04-27T07:11:15Z" model: gpt-5.4 provider: openai - source_hash: cc5df551839db87a36be7c1b29023c687c418d13337075490436335a8bb1635d + source_hash: fccc75e672bf3295c335fc4d2f610e9cbb3f1882edd12ffb9d009120291bd2d9 source_path: gateway/remote-gateway-readme.md workflow: 15 --- @@ -15,7 +15,7 @@ x-i18n: # 使用远程 Gateway 网关运行 OpenClaw.app -OpenClaw.app 使用 SSH 隧道连接到远程 gateway。本指南将向你展示如何进行设置。 +OpenClaw.app 使用 SSH 隧道连接到远程 Gateway 网关。本指南将向你展示如何进行设置。 ## 概览 @@ -40,7 +40,7 @@ flowchart TB T --> C ``` -## 快速设置 +## 快速开始 ### 第 1 步：添加 SSH 配置 @@ -58,7 +58,7 @@ Host remote-gateway ### 第 2 步：复制 SSH 密钥 -将你的公钥复制到远程机器上（输入一次密码）： +将你的公钥复制到远程机器（输入一次密码）： ```bash ssh-copy-id -i ~/.ssh/id_rsa @ @@ -70,9 +70,8 @@ ssh-copy-id -i ~/.ssh/id_rsa @ openclaw config set gateway.remote.token "" ``` -如果你的远程 gateway 使用密码认证，请改用 `gateway.remote.password`。 -`OPENCLAW_GATEWAY_TOKEN` 仍然可作为 shell 层级的覆盖项使用，但持久化的 -远程客户端设置应使用 `gateway.remote.token` / `gateway.remote.password`。 +如果你的远程 Gateway 网关使用密码认证，请改用 `gateway.remote.password`。 +`OPENCLAW_GATEWAY_TOKEN` 仍然可作为 shell 级覆盖使用，但持久化的远程客户端设置应使用 `gateway.remote.token` / `gateway.remote.password`。 ### 第 4 步：启动 SSH 隧道 @@ -87,13 +86,13 @@ ssh -N remote-gateway & open /path/to/OpenClaw.app ``` -应用现在将通过 SSH 隧道连接到远程 gateway。 +应用现在将通过 SSH 隧道连接到远程 Gateway 网关。 --- ## 登录时自动启动隧道 -如果你希望 SSH 隧道在登录时自动启动，请创建一个 Launch Agent。 +如果你希望 SSH 隧道在登录时自动启动，可以创建一个 Launch Agent。 ### 创建 PLIST 文件 @@ -130,7 +129,7 @@ launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist - 在你登录时自动启动 - 如果崩溃会自动重启 -- 持续在后台运行 +- 在后台持续运行 旧版说明：如果存在残留的 `com.openclaw.ssh-tunnel` LaunchAgent，请将其移除。 @@ -164,11 +163,11 @@ launchctl bootout gui/$UID/ai.openclaw.ssh-tunnel | 组件 | 作用 | | ------------------------------------ | ------------------------------------------------------------ | | `LocalForward 18789 127.0.0.1:18789` | 将本地端口 18789 转发到远程端口 18789 | -| `ssh -N` | 运行 SSH 但不执行远程命令（仅进行端口转发） | -| `KeepAlive` | 如果隧道崩溃则自动重启 | -| `RunAtLoad` | 在 agent 加载时启动隧道 | +| `ssh -N` | SSH 连接但不执行远程命令（仅进行端口转发） | +| `KeepAlive` | 如果隧道崩溃则自动重启 | +| `RunAtLoad` | 在代理加载时启动隧道 | -OpenClaw.app 会连接到你客户端机器上的 `ws://127.0.0.1:18789`。SSH 隧道会将该连接转发到远程机器上的 18789 端口，也就是 Gateway 网关正在运行的位置。 +OpenClaw.app 会连接到你客户端机器上的 `ws://127.0.0.1:18789`。SSH 隧道会将该连接转发到远程机器上的 18789 端口，也就是 Gateway 网关运行的端口。 ## 相关内容 diff --git a/docs/zh-CN/install/bun.md b/docs/zh-CN/install/bun.md index 49f305029..0fee2d766 100644 --- a/docs/zh-CN/install/bun.md +++ b/docs/zh-CN/install/bun.md @@ -1,14 +1,14 @@ --- read_when: - 你想要最快的本地开发循环（bun + watch） - - 你遇到了 Bun 安装 / patch / 生命周期脚本问题 -summary: Bun 工作流（实验性）：与 pnpm 相比的安装方式和注意事项 + - 你遇到了 Bun 安装、补丁或生命周期脚本问题 +summary: Bun 工作流（实验性）：安装方式以及与 pnpm 相比的注意事项 title: Bun（实验性） x-i18n: - generated_at: "2026-04-24T03:16:57Z" + generated_at: "2026-04-27T07:11:31Z" model: gpt-5.4 provider: openai - source_hash: 5637f64fe272faf74915e8de115f21fdf9c9dd0406e5c471932323b2c1d4c0bd + source_hash: d596c8fa9cc585e23184e7b983ec3842361eac807a1f3c12a0529631876db486 source_path: install/bun.md workflow: 15 --- @@ -17,7 +17,7 @@ x-i18n: 不建议将 Bun **用于 Gateway 网关运行时**（已知会与 WhatsApp 和 Telegram 出现问题）。生产环境请使用 Node。 -Bun 是一个可选的本地运行时，可用于直接运行 TypeScript（`bun run ...`、`bun --watch ...`）。默认的包管理器仍然是 `pnpm`，它是完全受支持的，并被文档工具链使用。Bun 不能使用 `pnpm-lock.yaml`，并且会忽略它。 +Bun 是一种可选的本地运行时，可用于直接运行 TypeScript（`bun run ...`、`bun --watch ...`）。默认的包管理器仍然是 `pnpm`，它受到完整支持，并被文档工具链使用。Bun 无法使用 `pnpm-lock.yaml`，并且会忽略它。 ## 安装 @@ -27,14 +27,14 @@ Bun 是一个可选的本地运行时，可用于直接运行 TypeScript（`bun bun install ``` - `bun.lock` / `bun.lockb` 已被加入 gitignore，因此不会造成仓库变更。如果你想完全跳过 lockfile 写入： + `bun.lock` / `bun.lockb` 已被 gitignore 忽略，因此不会给仓库带来额外变更。如果你想完全跳过 lockfile 写入： ```sh bun install --no-save ``` - + ```sh bun run build bun run vitest run @@ -44,12 +44,12 @@ Bun 是一个可选的本地运行时，可用于直接运行 TypeScript（`bun ## 生命周期脚本 -除非被显式信任，否则 Bun 会阻止依赖的生命周期脚本。对于这个仓库，常见被阻止的脚本并非必需： +除非被显式信任，否则 Bun 会阻止依赖项的生命周期脚本。对于这个仓库，常见被阻止的脚本并不是必需的： -- `@whiskeysockets/baileys` 的 `preinstall` —— 检查 Node 主版本是否 >= 20（OpenClaw 默认使用 Node 24，也仍支持 Node 22 LTS，目前为 `22.14+`） -- `protobufjs` 的 `postinstall` —— 输出关于不兼容版本方案的警告（不会生成构建产物） +- `@whiskeysockets/baileys` `preinstall` -- 检查 Node 主版本是否 >= 20（OpenClaw 默认使用 Node 24，并且仍然支持 Node 22 LTS，目前为 `22.14+`） +- `protobufjs` `postinstall` -- 发出关于版本方案不兼容的警告（不会生成构建产物） -如果你遇到需要这些脚本的运行时问题，请显式信任它们： +如果你遇到了需要这些脚本才能解决的运行时问题，请显式信任它们： ```sh bun pm trust @whiskeysockets/baileys protobufjs @@ -57,10 +57,10 @@ bun pm trust @whiskeysockets/baileys protobufjs ## 注意事项 -某些脚本仍然硬编码为 pnpm（例如 `docs:build`、`ui:*`、`protocol:check`）。目前请仍通过 pnpm 运行这些脚本。 +有些脚本仍然将 pnpm 硬编码进去（例如 `docs:build`、`ui:*`、`protocol:check`）。目前请继续通过 pnpm 运行这些脚本。 ## 相关内容 -- [Install overview](/zh-CN/install) +- [安装概览](/zh-CN/install) - [Node.js](/zh-CN/install/node) -- [Updating](/zh-CN/install/updating) +- [更新](/zh-CN/install/updating) diff --git a/docs/zh-CN/install/docker.md b/docs/zh-CN/install/docker.md index a7c5f9289..63e06d267 100644 --- a/docs/zh-CN/install/docker.md +++ b/docs/zh-CN/install/docker.md @@ -2,13 +2,13 @@ read_when: - 你想使用容器化的 Gateway 网关，而不是本地安装 - 你正在验证 Docker 流程 -summary: 可选的基于 Docker 的 OpenClaw 设置和新手引导 +summary: OpenClaw 的可选 Docker 安装与新手引导 title: Docker x-i18n: - generated_at: "2026-04-26T21:53:15Z" + generated_at: "2026-04-27T07:11:35Z" model: gpt-5.4 provider: openai - source_hash: 66e79a53377c394ed581b856ee65946bc2a08a6fe66a85ed4f46fd4c7635e5e0 + source_hash: 56766c90b2751d186b0e9a7b55241fb45f05a37c2e8d7c0d0155b41eefc2177a source_path: install/docker.md workflow: 15 --- @@ -17,16 +17,16 @@ Docker **是可选的**。仅当你想使用容器化的 Gateway 网关，或验 ## Docker 适合我吗？ -- **是**：你想要一个隔离的、可随时丢弃的 Gateway 网关环境，或者想在没有本地安装环境的主机上运行 OpenClaw。 -- **否**：你是在自己的机器上运行，只想要最快的开发迭代流程。请改用常规安装流程。 -- **沙箱注意事项**：启用沙箱隔离时，默认沙箱后端会使用 Docker，但沙箱隔离默认是关闭的，并且**不**要求整个 Gateway 网关都运行在 Docker 中。也提供 SSH 和 OpenShell 沙箱后端。参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 +- **是**：你想要一个隔离的、可随时丢弃的 Gateway 网关环境，或者想在没有本地安装的主机上运行 OpenClaw。 +- **否**：你是在自己的机器上运行，只想获得最快的开发循环。请改用常规安装流程。 +- **沙箱注意事项**：启用沙箱隔离时，默认的沙箱后端会使用 Docker，但沙箱隔离默认是关闭的，并且**不**要求整个 Gateway 网关都运行在 Docker 中。也可以使用 SSH 和 OpenShell 沙箱后端。参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 ## 前置条件 - Docker Desktop（或 Docker Engine）+ Docker Compose v2 -- 镜像构建至少需要 2 GB 内存（在 1 GB 主机上，`pnpm install` 可能因 OOM 被杀掉并以 137 退出） +- 至少 2 GB 内存用于构建镜像（在 1 GB 主机上，`pnpm install` 可能因 OOM 被杀死并以 137 退出） - 足够的磁盘空间用于镜像和日志 -- 如果在 VPS / 公网主机上运行，请查看 +- 如果在 VPS/公网主机上运行，请查看 [网络暴露的安全加固](/zh-CN/gateway/security)， 尤其是 Docker `DOCKER-USER` 防火墙策略。 @@ -40,7 +40,7 @@ Docker **是可选的**。仅当你想使用容器化的 Gateway 网关，或验 ./scripts/docker/setup.sh ``` - 这会在本地构建 Gateway 网关镜像。如果要改用预构建镜像： + 这会在本地构建 Gateway 网关镜像。若要改用预构建镜像，请使用： ```bash export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest" @@ -49,28 +49,27 @@ Docker **是可选的**。仅当你想使用容器化的 Gateway 网关，或验 预构建镜像发布在 [GitHub Container Registry](https://github.com/openclaw/openclaw/pkgs/container/openclaw)。 - 常用标签：`main`、`latest`、``（例如 `2026.2.26`）。 + 常见标签：`main`、`latest`、``（例如 `2026.2.26`）。 设置脚本会自动运行新手引导。它将会： - - 提示输入提供商 API 密钥 - - 生成 Gateway 网关令牌并将其写入 `.env` + - 提示你输入提供商 API 密钥 + - 生成一个 Gateway 网关令牌并写入 `.env` - 通过 Docker Compose 启动 Gateway 网关 在设置过程中，启动前的新手引导和配置写入会直接通过 - `openclaw-gateway` 运行。`openclaw-cli` 用于在 - Gateway 网关容器已经存在之后执行的命令。 + `openclaw-gateway` 完成。`openclaw-cli` 用于在 + Gateway 网关容器已经存在之后再运行的命令。 - - 在浏览器中打开 `http://127.0.0.1:18789/`，并将已配置的 - 共享密钥粘贴到设置中。设置脚本默认会将令牌写入 `.env`；如果你将容器配置切换为密码认证，请改用该密码。 + + 在浏览器中打开 `http://127.0.0.1:18789/`，然后将已配置的共享密钥粘贴到设置中。设置脚本默认会将令牌写入 `.env`；如果你把容器配置切换为密码认证，请改用该密码。 - 需要再次获取 URL？ + 需要再次获取 URL 吗？ ```bash docker compose run --rm openclaw-cli dashboard --no-open @@ -92,14 +91,14 @@ Docker **是可选的**。仅当你想使用容器化的 Gateway 网关，或验 docker compose run --rm openclaw-cli channels add --channel discord --token "" ``` - 文档：[WhatsApp](/zh-CN/channels/whatsapp)、[Telegram](/zh-CN/channels/telegram)、[Discord](/zh-CN/channels/discord) + 文档： [WhatsApp](/zh-CN/channels/whatsapp)、[Telegram](/zh-CN/channels/telegram)、[Discord](/zh-CN/channels/discord) ### 手动流程 -如果你更喜欢自己逐步运行每一步，而不是使用设置脚本： +如果你更喜欢自己逐步执行每一步，而不是使用设置脚本： ```bash docker build -t openclaw:local -f Dockerfile . @@ -113,47 +112,45 @@ docker compose up -d openclaw-gateway 请从仓库根目录运行 `docker compose`。如果你启用了 `OPENCLAW_EXTRA_MOUNTS` 或 `OPENCLAW_HOME_VOLUME`，设置脚本会写入 `docker-compose.extra.yml`； -请使用 `-f docker-compose.yml -f docker-compose.extra.yml` 将其包含进来。 +请通过 `-f docker-compose.yml -f docker-compose.extra.yml` 一并包含它。 -由于 `openclaw-cli` 与 `openclaw-gateway` 共享网络命名空间，它是一个 -启动后的工具。在运行 `docker compose up -d openclaw-gateway` 之前，请通过 -`openclaw-gateway` 并配合 -`--no-deps --entrypoint node` 来执行新手引导和设置阶段的配置写入。 +由于 `openclaw-cli` 与 `openclaw-gateway` 共享网络命名空间，它是一个启动后的工具。在 `docker compose up -d openclaw-gateway` 之前，请通过带有 +`--no-deps --entrypoint node` 的 `openclaw-gateway` 运行新手引导和设置期间的配置写入。 ### 环境变量 -设置脚本接受以下可选环境变量： +设置脚本支持以下可选环境变量： -| Variable | Purpose | +| Variable | Purpose | | ------------------------------------------ | --------------------------------------------------------------- | -| `OPENCLAW_IMAGE` | 使用远程镜像而不是在本地构建 | -| `OPENCLAW_DOCKER_APT_PACKAGES` | 在构建期间安装额外的 apt 软件包（以空格分隔） | -| `OPENCLAW_EXTENSIONS` | 在构建时预安装插件依赖（以空格分隔的名称） | -| `OPENCLAW_EXTRA_MOUNTS` | 额外的主机 bind mount（以逗号分隔的 `source:target[:opts]`） | -| `OPENCLAW_HOME_VOLUME` | 将 `/home/node` 持久化到一个命名的 Docker volume | -| `OPENCLAW_SANDBOX` | 选择启用沙箱引导（`1`、`true`、`yes`、`on`） | -| `OPENCLAW_DOCKER_SOCKET` | 覆盖 Docker socket 路径 | -| `OPENCLAW_DISABLE_BONJOUR` | 禁用 Bonjour / mDNS 广播（Docker 默认值为 `1`） | -| `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS` | 禁用内置插件源码 bind-mount 覆盖层 | -| `OTEL_EXPORTER_OTLP_ENDPOINT` | 用于 OpenTelemetry 导出的共享 OTLP/HTTP 收集器端点 | -| `OTEL_EXPORTER_OTLP_*_ENDPOINT` | 用于 traces、metrics 或 logs 的按信号划分的 OTLP 端点 | -| `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP 协议覆盖。目前仅支持 `http/protobuf` | -| `OTEL_SERVICE_NAME` | 用于 OpenTelemetry 资源的服务名称 | -| `OTEL_SEMCONV_STABILITY_OPT_IN` | 选择启用最新的实验性 GenAI 语义属性 | -| `OPENCLAW_OTEL_PRELOADED` | 当已有 OpenTelemetry SDK 预加载时，跳过启动第二个 SDK | +| `OPENCLAW_IMAGE` | 使用远程镜像而不是在本地构建 | +| `OPENCLAW_DOCKER_APT_PACKAGES` | 在构建期间安装额外的 apt 软件包（以空格分隔） | +| `OPENCLAW_EXTENSIONS` | 在构建时预安装插件依赖（以空格分隔名称） | +| `OPENCLAW_EXTRA_MOUNTS` | 额外的主机绑定挂载（以逗号分隔的 `source:target[:opts]`） | +| `OPENCLAW_HOME_VOLUME` | 在具名 Docker 卷中持久化 `/home/node` | +| `OPENCLAW_SANDBOX` | 选择启用沙箱引导（`1`、`true`、`yes`、`on`） | +| `OPENCLAW_DOCKER_SOCKET` | 覆盖 Docker socket 路径 | +| `OPENCLAW_DISABLE_BONJOUR` | 禁用 Bonjour/mDNS 广播（Docker 默认值为 `1`） | +| `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS` | 禁用内置插件源码绑定挂载覆盖 | +| `OTEL_EXPORTER_OTLP_ENDPOINT` | 用于 OpenTelemetry 导出的共享 OTLP/HTTP 收集器端点 | +| `OTEL_EXPORTER_OTLP_*_ENDPOINT` | 用于 traces、metrics 或 logs 的各信号专用 OTLP 端点 | +| `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP 协议覆盖。当前仅支持 `http/protobuf` | +| `OTEL_SERVICE_NAME` | 用于 OpenTelemetry 资源的服务名称 | +| `OTEL_SEMCONV_STABILITY_OPT_IN` | 选择启用最新的实验性 GenAI 语义属性 | +| `OPENCLAW_OTEL_PRELOADED` | 当已预加载一个 OpenTelemetry SDK 时，跳过启动第二个 | -维护者可以通过将某个插件源码目录挂载到其打包后的源码路径上，来针对打包镜像测试内置插件源码，例如 +维护者可以通过把某个插件源码目录挂载到其打包后的源码路径之上，来针对打包镜像测试内置插件源码，例如 `OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro`。 -该挂载的源码目录会覆盖同一插件 id 对应的已编译 -`/app/dist/extensions/synology-chat` bundle。 +该已挂载的源码目录会覆盖相同插件 id 对应的已编译 +`/app/dist/extensions/synology-chat` 包。 ### 可观测性 OpenTelemetry 导出是从 Gateway 网关容器向你的 OTLP -收集器发出的出站连接。它不需要发布 Docker 端口。如果你在本地构建镜像，并希望镜像内可用内置的 OpenTelemetry 导出器，请包含其运行时依赖： +collector 发起的出站连接。它不需要发布 Docker 端口。如果你在本地构建镜像，并希望镜像中包含可用的内置 OpenTelemetry exporter，请加入其运行时依赖： ```bash export OPENCLAW_EXTENSIONS="diagnostics-otel" @@ -163,21 +160,19 @@ export OTEL_SERVICE_NAME="openclaw-gateway" ``` 官方 OpenClaw Docker 发布镜像包含内置的 -`diagnostics-otel` 插件源码。根据镜像和缓存状态不同， -Gateway 网关在首次启用该插件时，仍可能需要准备插件本地的 OpenTelemetry 运行时依赖，因此请确保首次启动时可以访问软件包注册表，或者在你的发布流程中预热镜像。要启用导出，请在配置中允许并启用 -`diagnostics-otel` 插件，然后设置 +`diagnostics-otel` 插件源码。根据镜像和缓存状态，Gateway 网关在首次启用该插件时，可能仍需暂存插件本地的 OpenTelemetry 运行时依赖，因此请确保首次启动时可以访问软件包注册表，或在你的发布流程中预热镜像。要启用导出，请在配置中允许并启用 `diagnostics-otel` 插件，然后设置 `diagnostics.otel.enabled=true`，或使用 -[OpenTelemetry 导出](/zh-CN/gateway/opentelemetry) 中的配置示例。收集器认证头通过 +[OpenTelemetry 导出](/zh-CN/gateway/opentelemetry) 中的配置示例。collector 认证头通过 `diagnostics.otel.headers` 配置，而不是通过 Docker 环境变量配置。 Prometheus 指标使用已经发布的 Gateway 网关端口。启用 -`diagnostics-prometheus` 插件，然后抓取： +`diagnostics-prometheus` 插件后，抓取： ```text http://:18789/api/diagnostics/prometheus ``` -该路由受 Gateway 网关认证保护。不要暴露单独的公网 `/metrics` 端口，也不要暴露未认证的反向代理路径。参见 +该路由受 Gateway 网关认证保护。不要暴露单独的公共 `/metrics` 端口，也不要暴露未认证的反向代理路径。参见 [Prometheus 指标](/zh-CN/gateway/prometheus)。 ### 健康检查 @@ -189,11 +184,11 @@ curl -fsS http://127.0.0.1:18789/healthz # 存活检查 curl -fsS http://127.0.0.1:18789/readyz # 就绪检查 ``` -Docker 镜像内置了一个 `HEALTHCHECK`，会 ping `/healthz`。 +Docker 镜像内置了一个 `HEALTHCHECK`，会探测 `/healthz`。 如果检查持续失败，Docker 会将容器标记为 `unhealthy`， -编排系统即可重启或替换该容器。 +编排系统即可重启或替换它。 -需要认证的深度健康快照： +需要认证的深度健康状态快照： ```bash docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN" @@ -205,56 +200,55 @@ docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLA `http://127.0.0.1:18789`。 - `lan`（默认）：主机浏览器和主机 CLI 都可以访问已发布的 Gateway 网关端口。 -- `loopback`：只有容器网络命名空间内的进程才能直接访问 +- `loopback`：只有容器网络命名空间内的进程可以直接访问 Gateway 网关。 -请在 `gateway.bind` 中使用 bind 模式值（`lan` / `loopback` / `custom` / +请在 `gateway.bind` 中使用绑定模式值（`lan` / `loopback` / `custom` / `tailnet` / `auto`），不要使用主机别名，例如 `0.0.0.0` 或 `127.0.0.1`。 ### Bonjour / mDNS -Docker bridge 网络通常无法可靠地转发 Bonjour / mDNS 组播 +Docker bridge 网络通常无法可靠地转发 Bonjour/mDNS 多播 （`224.0.0.251:5353`）。因此，内置的 Compose 设置默认使用 -`OPENCLAW_DISABLE_BONJOUR=1`，以避免 Gateway 网关在 bridge 丢弃组播流量时发生崩溃循环或反复重启广播。 +`OPENCLAW_DISABLE_BONJOUR=1`，以避免 Gateway 网关因桥接网络丢弃多播流量而崩溃循环或反复重启广播。 -对于 Docker 主机，请使用已发布的 Gateway 网关 URL、Tailscale，或广域 DNS-SD。只有在使用 host networking、macvlan -或其他已知支持 mDNS 组播的网络时，才应将 `OPENCLAW_DISABLE_BONJOUR=0`。 +对于 Docker 主机，请使用已发布的 Gateway 网关 URL、Tailscale 或广域 DNS-SD。仅当你运行在 host networking、macvlan 或其他已知支持 mDNS 多播的网络中时，才将 `OPENCLAW_DISABLE_BONJOUR=0`。 -有关常见问题和故障排除，请参见 [Bonjour 设备发现](/zh-CN/gateway/bonjour)。 +有关注意事项和故障排除，请参见 [Bonjour 设备发现](/zh-CN/gateway/bonjour)。 ### 存储与持久化 -Docker Compose 会将 `OPENCLAW_CONFIG_DIR` bind mount 到 `/home/node/.openclaw`，并将 -`OPENCLAW_WORKSPACE_DIR` bind mount 到 `/home/node/.openclaw/workspace`，因此这些路径在容器被替换后仍会保留。 +Docker Compose 会将 `OPENCLAW_CONFIG_DIR` 绑定挂载到 `/home/node/.openclaw`，并将 +`OPENCLAW_WORKSPACE_DIR` 绑定挂载到 `/home/node/.openclaw/workspace`，因此这些路径在容器被替换后仍会保留。 -这个挂载的配置目录就是 OpenClaw 存放以下内容的位置： +这个已挂载的配置目录是 OpenClaw 存储以下内容的位置： - 用于行为配置的 `openclaw.json` -- 用于存储提供商 OAuth/API-key 认证信息的 `agents//agent/auth-profiles.json` -- 用于存放基于环境变量的运行时密钥（例如 `OPENCLAW_GATEWAY_TOKEN`）的 `.env` +- 用于已存储提供商 OAuth/API 密钥认证的 `agents//agent/auth-profiles.json` +- 用于基于环境变量的运行时密钥（例如 `OPENCLAW_GATEWAY_TOKEN`）的 `.env` 关于 VM 部署中持久化细节的完整说明，请参见 -[Docker VM Runtime - 持久化内容及位置](/zh-CN/install/docker-vm-runtime#what-persists-where)。 +[Docker VM Runtime - What persists where](/zh-CN/install/docker-vm-runtime#what-persists-where)。 **磁盘增长热点：** 请关注 `media/`、会话 JSONL 文件、`cron/runs/*.jsonl`， 以及 `/tmp/openclaw/` 下的滚动文件日志。 -### Shell 辅助工具（可选） +### Shell 助手（可选） -为了更方便地进行日常 Docker 管理，请安装 `ClawDock`： +为了更轻松地进行日常 Docker 管理，请安装 `ClawDock`： ```bash mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc ``` -如果你之前是通过旧的 `scripts/shell-helpers/clawdock-helpers.sh` 原始路径安装的 ClawDock，请重新运行上面的安装命令，以便让你的本地辅助脚本文件跟踪新的位置。 +如果你之前是通过旧的 `scripts/shell-helpers/clawdock-helpers.sh` 原始路径安装 ClawDock 的，请重新运行上面的安装命令，以便你的本地 helper 文件跟踪新位置。 -然后你可以使用 `clawdock-start`、`clawdock-stop`、`clawdock-dashboard` 等命令。运行 -`clawdock-help` 可查看全部命令。 -完整辅助指南请参见 [ClawDock](/zh-CN/install/clawdock)。 +然后你就可以使用 `clawdock-start`、`clawdock-stop`、`clawdock-dashboard` 等命令。 +运行 `clawdock-help` 查看全部命令。 +完整 helper 指南请参见 [ClawDock](/zh-CN/install/clawdock)。 @@ -271,8 +265,7 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc ./scripts/docker/setup.sh ``` - 只有在沙箱前置条件通过后，脚本才会挂载 `docker.sock`。如果 - 沙箱设置无法完成，脚本会将 `agents.defaults.sandbox.mode` + 只有在沙箱前置条件检查通过后，脚本才会挂载 `docker.sock`。如果沙箱设置无法完成，脚本会将 `agents.defaults.sandbox.mode` 重置为 `off`。 @@ -288,14 +281,14 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc - `openclaw-cli` 使用 `network_mode: "service:openclaw-gateway"`，因此 CLI - 命令可以通过 `127.0.0.1` 访问 Gateway 网关。请将其视为共享信任边界。Compose 配置会为 `openclaw-cli` 移除 `NET_RAW`/`NET_ADMIN`，并启用 + `openclaw-cli` 使用 `network_mode: "service:openclaw-gateway"`，这样 CLI + 命令就可以通过 `127.0.0.1` 访问 Gateway 网关。请将其视为一个共享信任边界。Compose 配置在 `openclaw-cli` 上移除了 `NET_RAW`/`NET_ADMIN`，并启用了 `no-new-privileges`。 - + 该镜像以 `node`（uid 1000）身份运行。如果你在 - `/home/node/.openclaw` 上看到权限错误，请确保你的主机 bind mount 归 uid 1000 所有： + `/home/node/.openclaw` 上看到权限错误，请确保你的主机绑定挂载归 uid 1000 所有： ```bash sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace @@ -304,7 +297,7 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc - 请按依赖层可缓存的方式组织你的 Dockerfile。这样可以避免在 lockfile 未变更时重复运行 + 请按依赖层可缓存的方式组织你的 Dockerfile。这样可以避免在 lockfile 未变化时重复运行 `pnpm install`： ```dockerfile @@ -328,7 +321,7 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc - 默认镜像以安全优先为目标，并以非 root 的 `node` 用户运行。如果你想要功能更完整的容器： + 默认镜像以安全优先为目标，并以非 root 的 `node` 用户运行。若要获得功能更完整的容器： 1. **持久化 `/home/node`**：`export OPENCLAW_HOME_VOLUME="openclaw_home"` 2. **预装系统依赖**：`export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"` @@ -338,7 +331,7 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc node /app/node_modules/playwright-core/cli.js install chromium ``` 4. **持久化浏览器下载内容**：设置 - `PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright`，并使用 + `PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright` 并使用 `OPENCLAW_HOME_VOLUME` 或 `OPENCLAW_EXTRA_MOUNTS`。 @@ -351,32 +344,29 @@ echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc 主 Docker 运行时镜像使用 `node:24-bookworm-slim`，并发布 OCI 基础镜像注解，包括 `org.opencontainers.image.base.name`、 - `org.opencontainers.image.source` 等。Node 基础镜像摘要会通过 Dependabot 的 Docker 基础镜像 PR 刷新；发布构建不会运行 - distro upgrade 层。参见 - [OCI 镜像注解](https://github.com/opencontainers/image-spec/blob/main/annotations.md)。 + `org.opencontainers.image.source` 等。Node 基础镜像摘要会通过 Dependabot 的 Docker 基础镜像 PR 刷新；发布构建不会运行发行版升级层。参见 + [OCI image annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md)。 ### 在 VPS 上运行？ -有关共享 VM 部署步骤，包括二进制预构建、持久化和更新，请参见 +共享 VM 部署步骤（包括二进制预置、持久化和更新）请参见 [Hetzner（Docker VPS）](/zh-CN/install/hetzner) 和 [Docker VM Runtime](/zh-CN/install/docker-vm-runtime)。 ## 智能体沙箱 -当启用带有 Docker 后端的 `agents.defaults.sandbox` 时，Gateway 网关会在隔离的 Docker -容器中运行智能体工具执行（shell、文件读写等），而 Gateway 网关自身仍保留在主机上。这样你就能为不受信任或多租户的智能体会话建立一道坚固的隔离墙，而无需将整个 -Gateway 网关容器化。 +当使用 Docker 后端启用 `agents.defaults.sandbox` 时，Gateway 网关会在隔离的 Docker +容器中运行智能体工具执行（shell、文件读写等），而 Gateway 网关本身仍保留在主机上运行。这能在不将整个 Gateway 网关容器化的情况下，为不受信任或多租户智能体会话提供一道强隔离边界。 -沙箱范围可以按智能体（默认）、按会话，或共享。每种范围都会获得各自挂载到 `/workspace` 的工作区。你还可以配置 -allow/deny 工具策略、网络隔离、资源限制和浏览器容器。 +沙箱作用域可以是每个智能体（默认）、每个会话，或共享。每种作用域都会获得其自己的工作区，并挂载到 `/workspace`。你还可以配置工具允许/拒绝策略、网络隔离、资源限制和浏览器容器。 有关完整配置、镜像、安全说明和多智能体配置文件，请参见： -- [沙箱隔离](/zh-CN/gateway/sandboxing) -- 完整沙箱参考 +- [沙箱隔离](/zh-CN/gateway/sandboxing) -- 完整的沙箱参考 - [OpenShell](/zh-CN/gateway/openshell) -- 对沙箱容器的交互式 shell 访问 -- [多智能体沙箱与工具](/zh-CN/tools/multi-agent-sandbox-tools) -- 按智能体覆盖配置 +- [Multi-Agent Sandbox and Tools](/zh-CN/tools/multi-agent-sandbox-tools) -- 每个智能体的覆盖配置 ### 快速启用 @@ -402,8 +392,8 @@ scripts/sandbox-setup.sh ## 故障排除 - - 请使用 + + 使用 [`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh) 构建沙箱镜像，或将 `agents.defaults.sandbox.docker.image` 设置为你的自定义镜像。 容器会按需为每个会话自动创建。 @@ -411,20 +401,20 @@ scripts/sandbox-setup.sh 将 `docker.user` 设置为与你挂载工作区所有权匹配的 UID:GID， - 或者对工作区文件夹执行 chown。 + 或对工作区文件夹执行 chown。 - OpenClaw 使用 `sh -lc`（login shell）运行命令，这会读取 - `/etc/profile`，并且可能重置 PATH。请设置 `docker.env.PATH` 以预置你的自定义工具路径，或在 Dockerfile 中向 `/etc/profile.d/` 下添加脚本。 + OpenClaw 使用 `sh -lc`（登录 shell）运行命令，这会加载 + `/etc/profile` 并且可能重置 PATH。请设置 `docker.env.PATH` 以预先添加你的自定义工具路径，或在你的 Dockerfile 中向 `/etc/profile.d/` 添加脚本。 - - VM 至少需要 2 GB 内存。请使用更大规格的机器后重试。 + + VM 至少需要 2 GB 内存。请使用更大的机器规格后重试。 - - 获取一个新的仪表盘链接，并批准浏览器设备： + + 获取新的 dashboard 链接并批准浏览器设备： ```bash docker compose run --rm openclaw-cli dashboard --no-open @@ -436,8 +426,8 @@ scripts/sandbox-setup.sh - - 重置 Gateway 网关模式和 bind： + + 重置 Gateway 网关模式和绑定： ```bash docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]' @@ -451,6 +441,6 @@ scripts/sandbox-setup.sh - [安装概览](/zh-CN/install) — 所有安装方式 - [Podman](/zh-CN/install/podman) — Docker 的 Podman 替代方案 -- [ClawDock](/zh-CN/install/clawdock) — Docker Compose 社区设置 +- [ClawDock](/zh-CN/install/clawdock) — Docker Compose 社区方案 - [更新](/zh-CN/install/updating) — 让 OpenClaw 保持最新 - [配置](/zh-CN/gateway/configuration) — 安装后的 Gateway 网关配置 diff --git a/docs/zh-CN/install/exe-dev.md b/docs/zh-CN/install/exe-dev.md index 5e7e260f0..d80c603fa 100644 --- a/docs/zh-CN/install/exe-dev.md +++ b/docs/zh-CN/install/exe-dev.md @@ -1,39 +1,38 @@ --- read_when: - - 你想为 Gateway 网关使用一台低成本、始终在线的 Linux 主机 - - 你希望获得远程 Control UI 访问，而无需自己运行 VPS + - 你希望为 Gateway 网关使用一台低成本、始终在线的 Linux 主机 + - 你希望获得远程 Control UI 访问能力，而无需自行运行 VPS summary: 在 exe.dev 上运行 OpenClaw Gateway 网关（VM + HTTPS 代理）以实现远程访问 title: exe.dev x-i18n: - generated_at: "2026-04-27T06:04:58Z" + generated_at: "2026-04-27T07:11:38Z" model: gpt-5.4 provider: openai - source_hash: 4ef0b961a1153357aa32dd061791f5c94ae5008a99a800456d592ffce3a643f2 + source_hash: 98bc90ff26ce1773bd0e05f975fcc3427039e90ce50eca21bb2e8232f7ac730f source_path: install/exe-dev.md workflow: 15 --- -目标：让 OpenClaw Gateway 网关运行在 exe.dev VM 上，并可从你的笔记本通过以下地址访问：`https://.exe.xyz` +目标：让 OpenClaw Gateway 网关运行在 exe.dev VM 上，并可通过你的笔记本访问：`https://.exe.xyz` -本页假定你使用 exe.dev 默认的 **exeuntu** 镜像。如果你选择了其他发行版，请相应调整软件包名称。 +本页假设你使用的是 exe.dev 默认的 **exeuntu** 镜像。如果你选择了其他发行版，请相应调整软件包。 -## 面向新手的快速路径 +## 面向初学者的快速路径 1. [https://exe.new/openclaw](https://exe.new/openclaw) 2. 根据需要填写你的认证密钥 / 令牌 -3. 点击 VM 旁边的 “Agent”，等待 Shelley 完成配置 -4. 打开 `https://.exe.xyz/`，并使用已配置的共享密钥进行认证（本指南默认使用令牌认证，但如果你切换 `gateway.auth.mode`，密码认证也可以） -5. 使用 `openclaw devices approve ` 批准所有待处理的设备配对请求 +3. 点击你 VM 旁边的 “Agent”，然后等待 Shelley 完成配置 +4. 打开 `https://.exe.xyz/`，并使用已配置的共享密钥进行身份验证（本指南默认使用令牌认证，但如果你切换 `gateway.auth.mode`，密码认证也可以使用） +5. 使用 `openclaw devices approve ` 批准任何待处理的设备配对请求 -## 你需要准备 +## 你需要准备的内容 -- exe.dev 账号 -- 通过 `ssh exe.dev` 访问 [exe.dev](https://exe.dev) 虚拟机的权限（可选） +- exe.dev 账户 +- 对 [exe.dev](https://exe.dev) 虚拟机的 `ssh exe.dev` 访问权限（可选） ## 使用 Shelley 自动安装 -Shelley 是 [exe.dev](https://exe.dev) 的智能体，它可以通过我们的 -提示词立即安装 OpenClaw。使用的提示词如下： +Shelley 是 [exe.dev](https://exe.dev) 的智能体，可以通过我们的提示词立即安装 OpenClaw。使用的提示词如下： ``` Set up OpenClaw (https://docs.openclaw.ai/install) on this VM. Use the non-interactive and accept-risk flags for openclaw onboarding. Add the supplied auth or token as needed. Configure nginx to forward from the default port 18789 to the root location on the default enabled site config, making sure to enable Websocket support. Pairing is done by "openclaw devices list" and "openclaw devices approve ". Make sure the dashboard shows that OpenClaw's health is OK. exe.dev handles forwarding from port 8000 to port 80/443 and HTTPS for us, so the final "reachable" should be .exe.xyz, without port specification. @@ -56,7 +55,7 @@ ssh .exe.xyz ``` -请保持此 VM **有状态**。OpenClaw 会将 `openclaw.json`、每个智能体的 `auth-profiles.json`、会话以及渠道 / 提供商状态存储在 `~/.openclaw/` 下，并将工作区存储在 `~/.openclaw/workspace/` 下。 +请保持此 VM 为**有状态**。OpenClaw 会将 `openclaw.json`、每个智能体的 `auth-profiles.json`、会话以及渠道 / 提供商状态存储在 `~/.openclaw/` 下，并将工作区存储在 `~/.openclaw/workspace/` 下。 ## 2）安装前置依赖（在 VM 上） @@ -74,7 +73,7 @@ sudo apt-get install -y git curl jq ca-certificates openssl curl -fsSL https://openclaw.ai/install.sh | bash ``` -## 4）配置 nginx，将 OpenClaw 代理到 8000 端口 +## 4）设置 nginx，将 OpenClaw 代理到端口 8000 编辑 `/etc/nginx/sites-enabled/default`，内容如下： @@ -108,23 +107,15 @@ server { } ``` -请覆盖转发标头，而不是保留客户端提供的链。 -OpenClaw 仅信任来自显式配置代理的转发 IP 元数据， -而追加式 `X-Forwarded-For` 链会被视为一种加固风险。 +请覆盖转发头，而不是保留客户端提供的链式值。OpenClaw 只信任来自明确配置代理的转发 IP 元数据，而追加式的 `X-Forwarded-For` 链会被视为一种加固风险。 ## 5）访问 OpenClaw 并授予权限 -访问 `https://.exe.xyz/`（参见新手引导期间的 Control UI 输出）。如果系统提示认证，请粘贴来自 -VM 的已配置共享密钥。本指南使用令牌认证，因此请使用 `openclaw config get gateway.auth.token` -获取 `gateway.auth.token`（或使用 `openclaw doctor --generate-gateway-token` 生成一个）。 -如果你将 gateway 切换为密码认证，请改用 `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`。 -使用 `openclaw devices list` 和 `openclaw devices approve ` 批准设备。如有疑问，请直接在浏览器中使用 Shelley！ +访问 `https://.exe.xyz/`（参见新手引导期间的 Control UI 输出）。如果提示认证，请粘贴来自 VM 的已配置共享密钥。本指南使用令牌认证，因此可通过 `openclaw config get gateway.auth.token` 获取 `gateway.auth.token`（或使用 `openclaw doctor --generate-gateway-token` 生成一个）。如果你已将 Gateway 网关改为密码认证，请改用 `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`。使用 `openclaw devices list` 和 `openclaw devices approve ` 批准设备。不确定时，可以直接在浏览器中使用 Shelley！ ## 远程访问 -远程访问由 [exe.dev](https://exe.dev) 的认证机制处理。默认情况下， -来自 8000 端口的 HTTP 流量会被转发到 `https://.exe.xyz`， -并使用电子邮件认证。 +远程访问由 [exe.dev](https://exe.dev) 的认证机制处理。默认情况下，来自端口 8000 的 HTTP 流量会转发到 `https://.exe.xyz`，并使用邮箱认证。 ## 更新 @@ -135,9 +126,9 @@ openclaw gateway restart openclaw health ``` -指南： [Updating](/zh-CN/install/updating) +指南：[更新](/zh-CN/install/updating) ## 相关内容 -- [Remote gateway](/zh-CN/gateway/remote) -- [Install overview](/zh-CN/install) +- [远程 Gateway 网关](/zh-CN/gateway/remote) +- [安装概览](/zh-CN/install) diff --git a/docs/zh-CN/install/fly.md b/docs/zh-CN/install/fly.md index 6079ecca6..bee9a9a0c 100644 --- a/docs/zh-CN/install/fly.md +++ b/docs/zh-CN/install/fly.md @@ -5,31 +5,31 @@ read_when: summary: OpenClaw 在 Fly.io 上部署的分步指南，包含持久化存储和 HTTPS title: Fly.io x-i18n: - generated_at: "2026-04-26T00:39:24Z" + generated_at: "2026-04-27T07:11:41Z" model: gpt-5.4 provider: openai - source_hash: 1fe13cb60aff6ee2159e1008d2af660b689d819d38893e9758c23e1edaf32e22 + source_hash: 195a77c4cec439dc2b5030f5ee618274df76b16d878b8d16e65a754e4bd8072c source_path: install/fly.md workflow: 15 --- # Fly.io 部署 -**目标：** 让 OpenClaw Gateway 网关运行在 [Fly.io](https://fly.io) 的机器上，并具备持久化存储、自动 HTTPS，以及 Discord/渠道访问能力。 +**目标：** 让 OpenClaw Gateway 网关运行在 [Fly.io](https://fly.io) 机器上，并具备持久化存储、自动 HTTPS 和 Discord/渠道访问能力。 ## 你需要准备 - 已安装 [flyctl CLI](https://fly.io/docs/hands-on/install-flyctl/) -- Fly.io 账号（免费层即可） -- 模型凭证：你所选模型提供商的 API 密钥 +- Fly.io 账号（免费套餐可用） +- 模型认证：你所选模型提供商的 API 密钥 - 渠道凭证：Discord 机器人令牌、Telegram 令牌等 ## 面向初学者的快速路径 1. 克隆仓库 → 自定义 `fly.toml` -2. 创建应用 + 卷 → 设置密钥 +2. 创建应用和卷 → 设置密钥 3. 使用 `fly deploy` 部署 -4. SSH 登录后创建配置，或使用 Control UI +4. SSH 进入以创建配置，或使用 Control UI @@ -38,21 +38,21 @@ x-i18n: git clone https://github.com/openclaw/openclaw.git cd openclaw - # 创建一个新的 Fly 应用（自己选择名称） + # 创建一个新的 Fly 应用（请自行选择名称） fly apps create my-openclaw - # 创建一个持久卷（通常 1GB 就够） + # 创建一个持久化卷（通常 1 GB 就足够） fly volumes create openclaw_data --size 1 --region iad ``` - **提示：** 选择离你较近的区域。常见选项：`lhr`（伦敦）、`iad`（弗吉尼亚）、`sjc`（圣何塞）。 + **提示：** 请选择离你较近的区域。常见选项：`lhr`（伦敦）、`iad`（弗吉尼亚）、`sjc`（圣何塞）。 编辑 `fly.toml`，使其与你的应用名称和需求匹配。 - **安全说明：** 默认配置会暴露一个公开 URL。如需无公网 IP 的加固部署，请参见 [私有部署](#private-deployment-hardened)，或使用 `fly.private.toml`。 + **安全说明：** 默认配置会暴露一个公开 URL。若要进行无公网 IP 的加固部署，请参阅 [私有部署](#private-deployment-hardened) 或使用 `fly.private.toml`。 ```toml app = "my-openclaw" # 你的应用名称 @@ -91,11 +91,11 @@ x-i18n: | 设置 | 原因 | | ------------------------------ | --------------------------------------------------------------------------- | - | `--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"` | 将状态持久化到卷上 | + | `--bind lan` | 绑定到 `0.0.0.0`，这样 Fly 的代理才能访问 Gateway 网关 | + | `--allow-unconfigured` | 允许在没有配置文件的情况下启动（之后你会创建配置文件） | + | `internal_port = 3000` | 必须与 `--port 3000`（或 `OPENCLAW_GATEWAY_PORT`）匹配，以便 Fly 健康检查 | + | `memory = "2048mb"` | 512 MB 太小；建议使用 2 GB | + | `OPENCLAW_STATE_DIR = "/data"` | 将状态持久化到卷中 | @@ -117,9 +117,9 @@ x-i18n: **说明：** - - 非 loopback 绑定（`--bind lan`）要求存在有效的 Gateway 网关认证路径。这个 Fly.io 示例使用 `OPENCLAW_GATEWAY_TOKEN`，但 `gateway.auth.password` 或配置正确的非 loopback `trusted-proxy` 部署也能满足该要求。 + - 非 loopback 绑定（`--bind lan`）需要有效的 Gateway 网关认证路径。这个 Fly.io 示例使用 `OPENCLAW_GATEWAY_TOKEN`，但 `gateway.auth.password` 或正确配置的非 loopback `trusted-proxy` 部署同样满足要求。 - 请像对待密码一样保护这些令牌。 - - 对所有 API 密钥和令牌，**优先使用环境变量而不是配置文件**。这样可以避免密钥出现在 `openclaw.json` 中，从而减少意外暴露或被记录到日志中的风险。 + - **对于所有 API 密钥和令牌，优先使用环境变量而不是配置文件。** 这样可以避免将密钥写入 `openclaw.json`，从而降低意外暴露或被记录到日志中的风险。 @@ -130,14 +130,14 @@ x-i18n: 首次部署会构建 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 @@ -214,18 +214,18 @@ x-i18n: EOF ``` - **注意：** 设置 `OPENCLAW_STATE_DIR=/data` 后，配置路径就是 `/data/openclaw.json`。 + **注意：** 使用 `OPENCLAW_STATE_DIR=/data` 时，配置路径为 `/data/openclaw.json`。 - **注意：** 请将 `https://my-openclaw.fly.dev` 替换为你真实的 Fly 应用来源地址。Gateway 网关启动时会根据运行时的 `--bind` 和 `--port` 值预填充本地 Control UI 来源，因此首次启动可以在配置尚不存在时继续进行；但通过 Fly 在浏览器中访问时，仍然需要在 `gateway.controlUi.allowedOrigins` 中列出准确的 HTTPS 来源。 + **注意：** 请将 `https://my-openclaw.fly.dev` 替换为你的实际 Fly 应用源地址。Gateway 网关启动时会根据运行时的 `--bind` 和 `--port` 值预填充本地 Control UI 源地址，因此即使配置尚不存在，首次启动也可以继续；但要通过 Fly 在浏览器中访问，仍然需要在 `gateway.controlUi.allowedOrigins` 中列出准确的 HTTPS 源地址。 **注意：** Discord 令牌可以来自以下任一位置： - 环境变量：`DISCORD_BOT_TOKEN`（推荐用于密钥） - 配置文件：`channels.discord.token` - 如果使用环境变量，则无需把令牌加入配置。Gateway 网关会自动读取 `DISCORD_BOT_TOKEN`。 + 如果使用环境变量，则无需将令牌添加到配置中。Gateway 网关会自动读取 `DISCORD_BOT_TOKEN`。 - 重启以应用配置： + 重启以应用更改： ```bash exit @@ -245,7 +245,7 @@ x-i18n: 或访问 `https://my-openclaw.fly.dev/` - 使用你配置的共享密钥进行认证。本指南使用的是来自 `OPENCLAW_GATEWAY_TOKEN` 的 Gateway 网关令牌；如果你改用了密码认证，请改用对应密码。 + 使用已配置的共享密钥进行认证。本指南使用的是 `OPENCLAW_GATEWAY_TOKEN` 中的 Gateway 网关令牌；如果你改用了密码认证，请改用对应密码。 ### 日志 @@ -271,17 +271,17 @@ Gateway 网关绑定到了 `127.0.0.1`，而不是 `0.0.0.0`。 **修复方法：** 在 `fly.toml` 的进程命令中添加 `--bind lan`。 -### 健康检查失败 / connection refused +### 健康检查失败 / 连接被拒绝 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]] @@ -294,13 +294,13 @@ Fly 无法通过配置的端口访问 Gateway 网关。 fly machine update --vm-memory 2048 -y ``` -**注意：** 512MB 太小。1GB 可能可用，但在有负载或日志较多时仍可能 OOM。**推荐使用 2GB。** +**注意：** 512 MB 太小。1 GB 可能可以运行，但在负载较高或日志较详细时可能发生 OOM。**建议使用 2 GB。** ### Gateway 网关锁文件问题 -Gateway 网关启动时报 “already running” 错误并拒绝启动。 +Gateway 网关拒绝启动，并提示 “already running” 错误。 -这通常发生在容器重启后，PID 锁文件仍保留在卷中。 +这种情况通常发生在容器重启后，PID 锁文件仍保留在卷中。 **修复方法：** 删除锁文件： @@ -313,7 +313,7 @@ fly machine restart ### 未读取配置 -`--allow-unconfigured` 只会跳过启动保护，不会创建或修复 `/data/openclaw.json`，因此请确保你的正式配置文件已存在，并且在你希望以普通本地 Gateway 网关方式启动时，包含 `gateway.mode="local"`。 +`--allow-unconfigured` 只会绕过启动保护，不会创建或修复 `/data/openclaw.json`，因此请确保你的真实配置文件存在，并且在你希望正常启动本地 Gateway 网关时包含 `gateway.mode="local"`。 验证配置是否存在： @@ -326,7 +326,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 @@ -334,7 +334,7 @@ fly sftp shell > put /local/path/config.json /data/openclaw.json ``` -**注意：** 如果目标文件已存在，`fly sftp` 可能会失败。请先删除： +**注意：** 如果文件已存在，`fly sftp` 可能会失败。请先删除： ```bash fly ssh console --command "rm /data/openclaw.json" @@ -342,7 +342,7 @@ fly ssh console --command "rm /data/openclaw.json" ### 状态未持久化 -如果你在重启后丢失了 auth 配置、渠道/提供商状态或会话，说明状态目录被写到了容器文件系统中。 +如果你在重启后丢失认证配置文件、渠道/提供商状态或会话，说明状态目录写入到了容器文件系统。 **修复方法：** 确保在 `fly.toml` 中设置了 `OPENCLAW_STATE_DIR=/data`，然后重新部署。 @@ -362,7 +362,7 @@ fly logs ### 更新机器命令 -如果你需要在不完整重新部署的情况下修改启动命令： +如果你需要在不完整重新部署的情况下更改启动命令： ```bash # 获取机器 ID @@ -371,28 +371,28 @@ fly machines list # 更新命令 fly machine update --command "node dist/index.js gateway --port 3000 --bind lan" -y -# 或同时增加内存 +# 或连同内存增加一起更新 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） - 你使用 **ngrok 或 Tailscale** 隧道处理 webhook 回调 - 你通过 **SSH、代理或 WireGuard** 访问 Gateway 网关，而不是浏览器 -- 你希望部署**不被互联网扫描器发现** +- 你希望部署**对互联网扫描器隐藏** ### 设置 -使用 `fly.private.toml` 代替标准配置： +使用 `fly.private.toml`，而不是标准配置： ```bash # 使用私有配置部署 @@ -409,15 +409,15 @@ fly ips list -a my-openclaw 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 fly ips allocate-v6 --private -a my-openclaw ``` -完成后，`fly ips list` 应只显示 `private` 类型的 IP： +完成后，`fly ips list` 应只显示一个 `private` 类型的 IP： ``` VERSION IP TYPE REGION @@ -444,22 +444,22 @@ fly proxy 3000:3000 -a my-openclaw fly wireguard create # 导入到 WireGuard 客户端，然后通过内部 IPv6 访问 -# 示例：http://[fdaa:x:x:x:x::x]:3000 +# 例如：http://[fdaa:x:x:x:x::x]:3000 ``` -**选项 3：仅 SSH** +**选项 3：仅使用 SSH** ```bash fly ssh console -a my-openclaw ``` -### 使用私有部署处理 webhook +### 私有部署中的 webhook -如果你需要 webhook 回调（Twilio、Telnyx 等），但又不想对公网暴露： +如果你需要 webhook 回调（Twilio、Telnyx 等），但又不希望对公网暴露： -1. **ngrok 隧道** - 在容器内运行 ngrok，或作为 sidecar 运行 -2. **Tailscale Funnel** - 通过 Tailscale 暴露特定路径 -3. **仅出站** - 某些提供商（如 Twilio）即使没有 webhook 也能正常处理出站呼叫 +1. **ngrok 隧道** —— 在容器内运行 ngrok，或作为 sidecar 运行 +2. **Tailscale Funnel** —— 通过 Tailscale 暴露特定路径 +3. **仅出站** —— 某些提供商（Twilio）在没有 webhook 的情况下也能正常进行出站呼叫 使用 ngrok 的语音通话配置示例： @@ -482,37 +482,37 @@ fly ssh console -a my-openclaw } ``` -ngrok 隧道在容器内运行，可提供一个公开的 webhook URL，而无需暴露 Fly 应用本身。请将 `webhookSecurity.allowedHosts` 设置为公开隧道的主机名，这样转发过来的 Host 头才会被接受。 +ngrok 隧道在容器内运行，并提供一个公开的 webhook URL，而无需暴露 Fly 应用本身。请将 `webhookSecurity.allowedHosts` 设置为公开隧道的主机名，以便接受转发后的 host 标头。 ### 安全收益 -| 方面 | 公开部署 | 私有部署 | -| ---------------- | -------- | ------------ | -| 互联网扫描器发现 | 可发现 | 隐藏 | -| 直接攻击 | 可能 | 被阻止 | -| Control UI 访问 | 浏览器 | 代理 / VPN | -| webhook 投递 | 直接 | 通过隧道 | +| 方面 | 公开 | 私有 | +| ----------------- | ------------ | ---------- | +| 互联网扫描器 | 可被发现 | 隐藏 | +| 直接攻击 | 可能 | 被阻止 | +| Control UI 访问 | 浏览器 | 代理/VPN | +| webhook 投递 | 直接 | 通过隧道 | ## 说明 -- Fly.io 使用 **x86 架构**（不是 ARM） +- Fly.io 使用的是 **x86 架构**（不是 ARM） - Dockerfile 同时兼容这两种架构 -- 对于 WhatsApp/Telegram 新手引导，请使用 `fly ssh console` -- 持久化数据存放在卷上的 `/data` -- Signal 需要 Java + `signal-cli`；请使用自定义镜像，并将内存保持在 2GB 以上。 +- 如需进行 WhatsApp/Telegram 新手引导，请使用 `fly ssh console` +- 持久化数据存储在卷上的 `/data` +- Signal 需要 Java + signal-cli；请使用自定义镜像，并将内存保持在 2 GB 以上。 ## 费用 -使用推荐配置（`shared-cpu-2x`，2GB RAM）时： +使用推荐配置（`shared-cpu-2x`，2 GB RAM）时： -- 约 $10–15/月，具体取决于使用情况 -- 免费层包含一定额度 +- 费用大约为每月 10–15 美元，具体取决于使用情况 +- 免费套餐包含一定额度 -详情请参见 [Fly.io 定价](https://fly.io/docs/about/pricing/)。 +详情请参阅 [Fly.io 定价](https://fly.io/docs/about/pricing/)。 -## 下一步 +## 后续步骤 -- 设置消息渠道：[Channels](/zh-CN/channels) +- 设置消息渠道：[渠道](/zh-CN/channels) - 配置 Gateway 网关：[Gateway 网关配置](/zh-CN/gateway/configuration) - 保持 OpenClaw 为最新版本：[更新](/zh-CN/install/updating) diff --git a/docs/zh-CN/nodes/audio.md b/docs/zh-CN/nodes/audio.md index d74587be7..5dd53667e 100644 --- a/docs/zh-CN/nodes/audio.md +++ b/docs/zh-CN/nodes/audio.md @@ -1,52 +1,52 @@ --- read_when: - - 更改音频转录或媒体处理 -summary: 入站音频 / 语音消息如何被下载、转录并注入到回复中 -title: 音频和语音消息 + - 更改音频转录或媒体处理方式 +summary: 入站音频/语音消息如何被下载、转录并注入到回复中 +title: 音频与语音消息 x-i18n: - generated_at: "2026-04-25T11:16:01Z" + generated_at: "2026-04-27T07:11:46Z" model: gpt-5.4 provider: openai - source_hash: cc48787be480fbd19d26f18ac42a15108be89104e6aa56e60a94bd62b1b0cba0 + source_hash: d2795f306a0095e2355b39cb600698d02076aba5a64ad5ba2a22f7752adbe5db source_path: nodes/audio.md workflow: 15 --- # 音频 / 语音消息（2026-01-17） -## 有效功能 +## 已支持的功能 -- **媒体理解（音频）**：如果启用了音频理解功能（或自动检测到可用），OpenClaw 会： +- **媒体理解（音频）**：如果启用了音频理解（或自动检测到可用能力），OpenClaw 会： 1. 定位第一个音频附件（本地路径或 URL），并在需要时下载它。 - 2. 在发送到每个模型条目之前强制执行 `maxBytes`。 - 3. 按顺序运行第一个符合条件的模型条目（provider 或 CLI）。 + 2. 在发送到每个模型条目前先强制执行 `maxBytes` 限制。 + 3. 按顺序运行第一个符合条件的模型条目（提供商或 CLI）。 4. 如果失败或跳过（大小 / 超时），则尝试下一个条目。 - 5. 成功后，将 `Body` 替换为一个 `[Audio]` 块，并设置 `{{Transcript}}`。 + 5. 成功后，它会用一个 `[Audio]` 块替换 `Body`，并设置 `{{Transcript}}`。 - **命令解析**：当转录成功时，`CommandBody` / `RawBody` 会被设置为转录文本，因此斜杠命令仍然可以工作。 -- **详细日志记录**：在 `--verbose` 模式下，我们会记录何时运行转录，以及何时替换正文。 +- **详细日志**：在 `--verbose` 模式下，我们会记录何时运行转录，以及何时替换消息正文。 ## 自动检测（默认） -如果你**没有配置模型**，并且 `tools.media.audio.enabled` **未**设置为 `false`， +如果你**没有配置模型**，并且 `tools.media.audio.enabled` **没有**被设置为 `false`， OpenClaw 会按以下顺序自动检测，并在找到第一个可用选项后停止： -1. **当前活动的回复模型**，前提是其 provider 支持音频理解。 +1. **当前活动的回复模型**，前提是它的提供商支持音频理解。 2. **本地 CLI**（如果已安装） - `sherpa-onnx-offline`（需要 `SHERPA_ONNX_MODEL_DIR`，其中包含 encoder / decoder / joiner / tokens） - `whisper-cli`（来自 `whisper-cpp`；使用 `WHISPER_CPP_MODEL` 或内置的 tiny 模型） - `whisper`（Python CLI；会自动下载模型） 3. **Gemini CLI**（`gemini`），使用 `read_many_files` -4. **provider 凭证** - - 已配置且支持音频的 `models.providers.*` 条目会优先尝试 +4. **提供商凭证** + - 已配置的 `models.providers.*` 条目中，支持音频的会优先尝试 - 内置回退顺序：OpenAI → Groq → xAI → Deepgram → Google → SenseAudio → ElevenLabs → Mistral 要禁用自动检测，请设置 `tools.media.audio.enabled: false`。 要自定义，请设置 `tools.media.audio.models`。 -注意：在 macOS / Linux / Windows 上，对二进制文件的检测都属于尽力而为；请确保 CLI 位于 `PATH` 中（我们会展开 `~`），或者设置带有完整命令路径的显式 CLI 模型。 +注意：在 macOS / Linux / Windows 上，二进制检测都是尽力而为；请确保 CLI 在 `PATH` 中（我们会展开 `~`），或者设置一个带有完整命令路径的显式 CLI 模型。 ## 配置示例 -### provider + CLI 回退（OpenAI + Whisper CLI） +### 提供商 + CLI 回退（OpenAI + Whisper CLI） ```json5 { @@ -70,7 +70,7 @@ OpenClaw 会按以下顺序自动检测，并在找到第一个可用选项后 } ``` -### 仅 provider，并带有范围控制 +### 仅提供商，并带有范围控制 ```json5 { @@ -89,7 +89,7 @@ OpenClaw 会按以下顺序自动检测，并在找到第一个可用选项后 } ``` -### 仅 provider（Deepgram） +### 仅提供商（Deepgram） ```json5 { @@ -104,7 +104,7 @@ OpenClaw 会按以下顺序自动检测，并在找到第一个可用选项后 } ``` -### 仅 provider（Mistral Voxtral） +### 仅提供商（Mistral Voxtral） ```json5 { @@ -119,7 +119,7 @@ OpenClaw 会按以下顺序自动检测，并在找到第一个可用选项后 } ``` -### 仅 provider（SenseAudio） +### 仅提供商（SenseAudio） ```json5 { @@ -151,71 +151,71 @@ OpenClaw 会按以下顺序自动检测，并在找到第一个可用选项后 } ``` -## 注意事项与限制 +## 说明与限制 -- provider 凭证遵循标准模型凭证顺序（auth profiles、环境变量、`models.providers.*.apiKey`）。 -- Groq 设置详情： [Groq](/zh-CN/providers/groq)。 -- 使用 `provider: "deepgram"` 时，Deepgram 会读取 `DEEPGRAM_API_KEY`。 -- Deepgram 设置详情： [Deepgram（音频转录）](/zh-CN/providers/deepgram)。 -- Mistral 设置详情： [Mistral](/zh-CN/providers/mistral)。 -- 使用 `provider: "senseaudio"` 时，SenseAudio 会读取 `SENSEAUDIO_API_KEY`。 -- SenseAudio 设置详情： [SenseAudio](/zh-CN/providers/senseaudio)。 -- 音频 provider 可以通过 `tools.media.audio` 覆盖 `baseUrl`、`headers` 和 `providerOptions`。 -- 默认大小上限为 20 MB（`tools.media.audio.maxBytes`）。超出大小限制的音频会针对该模型被跳过，并尝试下一个条目。 -- 小于 1024 字节的极小 / 空音频文件会在 provider / CLI 转录之前被跳过。 -- 音频的默认 `maxChars` 为**未设置**（完整转录文本）。设置 `tools.media.audio.maxChars` 或每个条目的 `maxChars` 可裁剪输出。 +- 提供商凭证遵循标准模型凭证顺序（凭证配置文件、环境变量、`models.providers.*.apiKey`）。 +- Groq 的设置详情： [Groq](/zh-CN/providers/groq)。 +- 当使用 `provider: "deepgram"` 时，Deepgram 会读取 `DEEPGRAM_API_KEY`。 +- Deepgram 的设置详情： [Deepgram（音频转录）](/zh-CN/providers/deepgram)。 +- Mistral 的设置详情： [Mistral](/zh-CN/providers/mistral)。 +- 当使用 `provider: "senseaudio"` 时，SenseAudio 会读取 `SENSEAUDIO_API_KEY`。 +- SenseAudio 的设置详情： [SenseAudio](/zh-CN/providers/senseaudio)。 +- 音频提供商可以通过 `tools.media.audio` 覆盖 `baseUrl`、`headers` 和 `providerOptions`。 +- 默认大小上限为 20 MB（`tools.media.audio.maxBytes`）。超出大小限制的音频会被该模型跳过，并尝试下一个条目。 +- 小型 / 空音频文件如果小于 1024 字节，会在提供商 / CLI 转录前被跳过。 +- 音频的默认 `maxChars` 为**未设置**（完整转录文本）。设置 `tools.media.audio.maxChars` 或按条目设置 `maxChars` 可裁剪输出。 - OpenAI 的自动默认模型是 `gpt-4o-mini-transcribe`；如需更高准确率，请设置 `model: "gpt-4o-transcribe"`。 -- 使用 `tools.media.audio.attachments` 可处理多条语音消息（`mode: "all"` + `maxAttachments`）。 +- 使用 `tools.media.audio.attachments` 处理多个语音消息（`mode: "all"` + `maxAttachments`）。 - 转录文本可在模板中通过 `{{Transcript}}` 使用。 -- `tools.media.audio.echoTranscript` 默认关闭；启用后，会在智能体处理前先将转录确认消息发送回原始聊天。 +- `tools.media.audio.echoTranscript` 默认关闭；启用后，会在智能体处理前将转录确认消息发送回原始聊天。 - `tools.media.audio.echoFormat` 用于自定义回显文本（占位符：`{transcript}`）。 - CLI 标准输出有上限（5 MB）；请保持 CLI 输出简洁。 ### 代理环境支持 -基于 provider 的音频转录支持标准出站代理环境变量： +基于提供商的音频转录支持标准的出站代理环境变量： - `HTTPS_PROXY` - `HTTP_PROXY` - `https_proxy` - `http_proxy` -如果未设置代理环境变量，则使用直连出站。如果代理配置格式错误，OpenClaw 会记录一条警告，并回退到直接抓取。 +如果未设置代理环境变量，则使用直接出站连接。如果代理配置格式错误，OpenClaw 会记录一条警告，并回退为直接抓取。 ## 群组中的提及检测 -当群聊设置了 `requireMention: true` 时，OpenClaw 现在会在检查提及之前**先**转录音频。这样即使语音消息中包含提及，也能够被处理。 +当为群聊设置 `requireMention: true` 时，OpenClaw 现在会在检查提及之前**先**转录音频。这样即使语音消息中包含提及，也能被正确处理。 **工作方式：** 1. 如果语音消息没有文本正文，且群组要求提及，OpenClaw 会执行一次“预检”转录。 -2. 系统会检查转录文本中是否包含提及模式（例如 `@BotName`、emoji 触发词）。 -3. 如果发现提及，消息将继续进入完整的回复流水线。 -4. 提及检测会使用转录文本，因此语音消息可以通过提及门槛。 +2. 系统会检查转录文本中是否存在提及模式（例如 `@BotName`、表情触发器）。 +3. 如果发现提及，消息会继续进入完整的回复流水线。 +4. 转录文本会用于提及检测，从而让语音消息能够通过提及关卡。 **回退行为：** -- 如果预检期间转录失败（超时、API 错误等），消息将根据仅文本的提及检测结果进行处理。 -- 这可以确保混合消息（文本 + 音频）永远不会被错误丢弃。 +- 如果预检期间转录失败（超时、API 错误等），消息会基于仅文本的提及检测继续处理。 +- 这样可以确保混合消息（文本 + 音频）不会被错误丢弃。 **按 Telegram 群组 / 话题选择退出：** -- 设置 `channels.telegram.groups..disableAudioPreflight: true` 可跳过该群组的预检转录提及检查。 -- 设置 `channels.telegram.groups..topics..disableAudioPreflight` 可按话题覆盖（`true` 表示跳过，`false` 表示强制启用）。 -- 默认值为 `false`（在满足提及门控条件时启用预检）。 +- 设置 `channels.telegram.groups..disableAudioPreflight: true`，即可跳过该群组的预检转录提及检查。 +- 设置 `channels.telegram.groups..topics..disableAudioPreflight`，即可按话题覆盖（`true` 表示跳过，`false` 表示强制启用）。 +- 默认值为 `false`（当提及门控条件匹配时启用预检）。 -**示例：** 用户在一个设置了 `requireMention: true` 的 Telegram 群组中发送一条语音消息，说“Hey @Claude，今天天气怎么样？”。该语音消息会先被转录，检测到提及，然后智能体进行回复。 +**示例：** 用户在一个设置了 `requireMention: true` 的 Telegram 群组中发送一条语音消息，说“Hey @Claude, what's the weather?”。该语音消息会先被转录，随后检测到提及，智能体就会进行回复。 -## 易踩坑点 +## 注意事项 -- 范围规则采用首次匹配优先。`chatType` 会被标准化为 `direct`、`group` 或 `room`。 +- 范围规则遵循首个匹配优先。`chatType` 会被规范化为 `direct`、`group` 或 `room`。 - 请确保你的 CLI 以 0 退出并输出纯文本；如果输出 JSON，需要通过 `jq -r .text` 进行处理。 -- 对于 `parakeet-mlx`，如果你传入 `--output-dir`，当 `--output-format` 为 `txt`（或省略）时，OpenClaw 会读取 `/.txt`；非 `txt` 输出格式会回退到解析标准输出。 +- 对于 `parakeet-mlx`，如果你传入 `--output-dir`，当 `--output-format` 为 `txt`（或省略）时，OpenClaw 会读取 `/.txt`；非 `txt` 输出格式会回退为解析标准输出。 - 请将超时设置保持在合理范围内（`timeoutSeconds`，默认 60 秒），以避免阻塞回复队列。 -- 预检转录仅处理**第一个**音频附件用于提及检测。其余音频会在主媒体理解阶段处理。 +- 预检转录仅处理**第一个**音频附件用于提及检测。其他音频会在主媒体理解阶段处理中。 ## 相关内容 - [媒体理解](/zh-CN/nodes/media-understanding) -- [Talk 模式](/zh-CN/nodes/talk) +- [Talk mode](/zh-CN/nodes/talk) - [语音唤醒](/zh-CN/nodes/voicewake) diff --git a/docs/zh-CN/nodes/images.md b/docs/zh-CN/nodes/images.md index 97abc6761..eb0fc1c27 100644 --- a/docs/zh-CN/nodes/images.md +++ b/docs/zh-CN/nodes/images.md @@ -1,86 +1,86 @@ --- read_when: - - 修改媒体管线或附件处理 -summary: 发送、Gateway 网关和智能体回复中的图像与媒体处理规则 + - 修改媒体管道或附件 +summary: 发送、Gateway 网关和智能体回复的图像与媒体处理规则 title: 图像与媒体支持 x-i18n: - generated_at: "2026-04-23T22:58:52Z" + generated_at: "2026-04-27T07:11:49Z" model: gpt-5.4 provider: openai - source_hash: 26fa460f7dcdac9f15c9d79c3c3370adbce526da5cfa9a6825a8ed20b41e0a29 + source_hash: 1eb07bc638a755be5597e78c07041a52cfc0297b00d70c5adbfe5f3ad8c1a372 source_path: nodes/images.md workflow: 15 --- # 图像与媒体支持（2025-12-05） -WhatsApp 渠道通过 **Baileys Web** 运行。本文档记录当前发送、Gateway 网关和智能体回复中的媒体处理规则。 +WhatsApp 渠道通过 **Baileys Web** 运行。本文档记录了当前针对发送、Gateway 网关和智能体回复的媒体处理规则。 ## 目标 -- 通过 `openclaw message send --media` 发送带可选说明文字的媒体。 -- 允许来自 web 收件箱的自动回复在文本之外附带媒体。 -- 保持按类型划分的限制合理且可预测。 +- 通过 `openclaw message send --media` 发送媒体，并可选附带说明文字。 +- 允许来自 Web 收件箱的自动回复在文本之外附带媒体。 +- 让按类型划分的限制保持合理且可预测。 -## CLI 能力面 +## CLI 界面 - `openclaw message send --media [--message ]` - - `--media` 为可选；对于仅发送媒体的情况，说明文字可以为空。 - - `--dry-run` 会打印解析后的负载；`--json` 会输出 `{ channel, to, messageId, mediaUrl, caption }`。 + - `--media` 为可选项；说明文字可以为空，以便仅发送媒体。 + - `--dry-run` 会打印解析后的载荷；`--json` 会输出 `{ channel, to, messageId, mediaUrl, caption }`。 ## WhatsApp Web 渠道行为 -- 输入：本地文件路径**或** HTTP(S) URL。 -- 流程：加载为 Buffer，检测媒体类型，并构建正确的负载： +- 输入：本地文件路径 **或** HTTP(S) URL。 +- 流程：加载到 Buffer 中，检测媒体类型，并构建正确的载荷： - **图像：** 调整大小并重新压缩为 JPEG（最长边 2048 px），目标为 `channels.whatsapp.mediaMaxMb`（默认：50 MB）。 - - **音频/语音/视频：** 16 MB 以内直接透传；音频会作为语音消息发送（`ptt: true`）。 - - **文档：** 其他所有内容，最大 100 MB，并在可用时保留文件名。 -- WhatsApp GIF 式播放：发送一个带 `gifPlayback: true` 的 MP4（CLI：`--gif-playback`），以便移动端客户端内联循环播放。 -- MIME 检测优先使用魔数字节，其次是 headers，最后是文件扩展名。 -- 说明文字来自 `--message` 或 `reply.text`；允许为空说明文字。 -- 日志：非详细模式显示 `↩️`/`✅`；详细模式会包含大小和源路径/URL。 + - **音频/语音/视频：** 直接透传，最大 16 MB；音频会作为语音便笺发送（`ptt: true`）。 + - **文档：** 其他所有类型，最大 100 MB，并在可用时保留文件名。 +- WhatsApp GIF 式播放：发送一个带 `gifPlayback: true` 的 MP4（CLI：`--gif-playback`），这样移动客户端会内联循环播放。 +- MIME 检测优先使用魔数字节，其次是头部，最后是文件扩展名。 +- 说明文字来自 `--message` 或 `reply.text`；允许空说明文字。 +- 日志记录：非详细模式显示 `↩️`/`✅`；详细模式包含大小和源路径/URL。 -## 自动回复管线 +## 自动回复管道 - `getReplyFromConfig` 返回 `{ text?, mediaUrl?, mediaUrls? }`。 -- 当存在媒体时，web 发送器会使用与 `openclaw message send` 相同的管线解析本地路径或 URL。 -- 如果提供了多个媒体条目，它们会按顺序发送。 +- 当存在媒体时，Web 发送器会使用与 `openclaw message send` 相同的管道解析本地路径或 URL。 +- 如果提供了多个媒体条目，它们会按顺序逐个发送。 -## 传入命令的入站媒体（Pi） +## 传入媒体到命令（Pi） -- 当入站 web 消息包含媒体时，OpenClaw 会将其下载到临时文件，并暴露模板变量： - - `{{MediaUrl}}`：入站媒体的伪 URL。 - - `{{MediaPath}}`：运行命令前写入的本地临时路径。 -- 当启用了按会话划分的 Docker 沙箱时，入站媒体会被复制到沙箱工作区中，且 `MediaPath`/`MediaUrl` 会被重写为类似 `media/inbound/` 的相对路径。 -- 媒体理解（如果通过 `tools.media.*` 或共享的 `tools.media.models` 配置）会在模板处理之前运行，并可将 `[Image]`、`[Audio]` 和 `[Video]` 块插入到 `Body` 中。 - - 音频会设置 `{{Transcript}}`，并使用转录文本进行命令解析，因此斜杠命令仍然有效。 - - 视频和图像描述会保留所有说明文字文本，用于命令解析。 - - 如果当前活动的主图像模型原生已支持视觉能力，OpenClaw 会跳过 `[Image]` 摘要块，转而将原始图像直接传给模型。 -- 默认情况下，只处理第一个匹配的图像/音频/视频附件；设置 `tools.media..attachments` 可处理多个附件。 +- 当传入的 Web 消息包含媒体时，OpenClaw 会下载到临时文件，并公开模板变量： + - 传入媒体的伪 URL：`{{MediaUrl}}`。 + - 在运行命令前写入的本地临时路径：`{{MediaPath}}`。 +- 当启用了按会话划分的 Docker 沙箱时，传入媒体会被复制到沙箱工作区中，`MediaPath`/`MediaUrl` 会被改写为相对路径，例如 `media/inbound/`。 +- 媒体理解（如果通过 `tools.media.*` 或共享的 `tools.media.models` 进行配置）会在模板处理之前运行，并可将 `[Image]`、`[Audio]` 和 `[Video]` 代码块插入到 `Body` 中。 + - 音频会设置 `{{Transcript}}`，并使用转录内容进行命令解析，这样斜杠命令仍可工作。 + - 视频和图像描述会保留任何说明文字，以便用于命令解析。 + - 如果当前激活的主图像模型已经原生支持视觉能力，OpenClaw 会跳过 `[Image]` 摘要代码块，改为直接将原始图像传给模型。 +- 默认情况下，只会处理第一个匹配的图像/音频/视频附件；设置 `tools.media..attachments` 可处理多个附件。 ## 限制与错误 -**出站发送上限（WhatsApp web 发送）** +**出站发送上限（WhatsApp Web 发送）** -- 图像：重新压缩后最大为 `channels.whatsapp.mediaMaxMb`（默认：50 MB）。 -- 音频/语音/视频：上限 16 MB；文档：100 MB。 -- 过大或无法读取的媒体 → 日志中显示清晰错误，且跳过该回复。 +- 图像：重新压缩后最多为 `channels.whatsapp.mediaMaxMb`（默认：50 MB）。 +- 音频/语音/视频：上限 16 MB；文档：上限 100 MB。 +- 媒体过大或无法读取 → 日志中会显示清晰错误，并跳过该回复。 **媒体理解上限（转录/描述）** - 图像默认：10 MB（`tools.media.image.maxBytes`）。 - 音频默认：20 MB（`tools.media.audio.maxBytes`）。 - 视频默认：50 MB（`tools.media.video.maxBytes`）。 -- 过大的媒体会跳过理解，但回复仍会携带原始正文继续进行。 +- 过大的媒体会跳过理解，但回复仍会使用原始正文继续处理。 ## 测试说明 - 覆盖图像/音频/文档场景下的发送 + 回复流程。 -- 验证图像重新压缩（大小边界）以及音频的语音消息标志。 -- 确保多媒体回复会按顺序拆分发送。 +- 验证图像的重新压缩（大小上限）以及音频的语音便笺标志。 +- 确保多媒体回复会扇出为顺序发送。 -## 相关 +## 相关内容 -- [相机捕获](/zh-CN/nodes/camera) +- [相机采集](/zh-CN/nodes/camera) - [媒体理解](/zh-CN/nodes/media-understanding) -- [音频和语音消息](/zh-CN/nodes/audio) +- [音频与语音便笺](/zh-CN/nodes/audio) diff --git a/docs/zh-CN/pi-dev.md b/docs/zh-CN/pi-dev.md index aa1f044f8..3877f92ad 100644 --- a/docs/zh-CN/pi-dev.md +++ b/docs/zh-CN/pi-dev.md @@ -5,25 +5,25 @@ read_when: summary: Pi 集成的开发者工作流：构建、测试和实时验证 title: Pi 开发工作流 x-i18n: - generated_at: "2026-04-24T04:04:39Z" + generated_at: "2026-04-27T07:11:56Z" model: gpt-5.4 provider: openai - source_hash: fb626bf21bc731b8ca7bb2a48692e17c8b93f2b6ffa471ed9e70d9c91cd57149 + source_hash: 9c4025c8ed1a4dff0d8116440fd48f375264eb4cac06f71afebf8c05f3470ab4 source_path: pi-dev.md workflow: 15 --- -本指南总结了在 OpenClaw 中处理 Pi 集成时，一套合理的开发工作流。 +在 OpenClaw 中处理 Pi 集成时，一套合理的开发工作流。 -## 类型检查和 Lint +## 类型检查和 lint - 默认本地门禁：`pnpm check` -- 构建门禁：当更改可能影响构建产物、打包或懒加载/模块边界时，运行 `pnpm build` -- Pi 相关重度更改的完整落地门禁：`pnpm check && pnpm test` +- 构建门禁：当变更可能影响构建输出、打包或懒加载 / 模块边界时，运行 `pnpm build` +- 面向 Pi 重度变更的完整提交流水线门禁：`pnpm check && pnpm test` ## 运行 Pi 测试 -直接使用 Vitest 运行以 Pi 为重点的测试集： +直接使用 Vitest 运行聚焦于 Pi 的测试集： ```bash pnpm test \ @@ -35,13 +35,13 @@ pnpm test \ "src/agents/pi-hooks/**/*.test.ts" ``` -若要包含实时 provider 验证： +如需包含实时 provider 演练： ```bash OPENCLAW_LIVE_TEST=1 pnpm test src/agents/pi-embedded-runner-extraparams.live.test.ts ``` -这覆盖了主要的 Pi 单元测试套件： +这涵盖了主要的 Pi 单元测试套件： - `src/agents/pi-*.test.ts` - `src/agents/pi-embedded-*.test.ts` @@ -54,30 +54,30 @@ OPENCLAW_LIVE_TEST=1 pnpm test src/agents/pi-embedded-runner-extraparams.live.te 推荐流程： -- 以 dev 模式运行 gateway： +- 以开发模式运行 Gateway 网关： - `pnpm gateway:dev` - 直接触发智能体： - `pnpm openclaw agent --message "Hello" --thinking low` -- 使用终端 UI 进行交互式调试： +- 使用 TUI 进行交互式调试： - `pnpm tui` -对于工具调用行为，请提示执行 `read` 或 `exec` 操作，以便你观察工具流式传输和负载处理。 +对于工具调用行为，可提示执行 `read` 或 `exec` 操作，这样你就能看到工具流式传输和负载处理。 -## 全量重置 +## 清空重置 -状态保存在 OpenClaw 状态目录下。默认是 `~/.openclaw`。如果设置了 `OPENCLAW_STATE_DIR`，则改用该目录。 +状态保存在 OpenClaw 状态目录下。默认是 `~/.openclaw`。如果设置了 `OPENCLAW_STATE_DIR`，请改用该目录。 -如需重置所有内容： +要重置所有内容： -- 配置文件 `openclaw.json` -- 模型 auth profile 的 `agents//agent/auth-profiles.json`（API 密钥 + OAuth） -- `credentials/`，用于仍保存在 auth profile store 之外的 provider/channel 状态 -- `agents//sessions/`，用于智能体会话历史 -- `agents//sessions/sessions.json`，用于会话索引 -- 如果存在旧路径，则删除 `sessions/` -- 如果你希望得到一个空白工作区，则删除 `workspace/` +- 用于配置的 `openclaw.json` +- 用于模型认证配置档案（API 密钥 + OAuth）的 `agents//agent/auth-profiles.json` +- 用于仍存放在认证配置档案存储之外的 provider / 渠道状态的 `credentials/` +- 用于智能体会话历史的 `agents//sessions/` +- 用于会话索引的 `agents//sessions/sessions.json` +- 如果存在旧版路径，则删除 `sessions/` +- 如果你想要一个空白工作区，则删除 `workspace/` -如果你只想重置会话，请删除该智能体的 `agents//sessions/`。如果你想保留认证信息，请保留 `agents//agent/auth-profiles.json` 以及 `credentials/` 下的任何 provider 状态。 +如果你只想重置会话，请删除该智能体的 `agents//sessions/`。如果你想保留认证，请保留 `agents//agent/auth-profiles.json` 以及 `credentials/` 下的任何 provider 状态。 ## 参考 diff --git a/docs/zh-CN/platforms/android.md b/docs/zh-CN/platforms/android.md index 561603994..1438d9fca 100644 --- a/docs/zh-CN/platforms/android.md +++ b/docs/zh-CN/platforms/android.md @@ -1,76 +1,76 @@ --- read_when: - 配对或重新连接 Android 节点 - - 调试 Android Gateway 网关发现或认证 - - 验证各客户端之间的聊天历史一致性 -summary: Android 应用（node）：连接操作手册 + Connect/Chat/Voice/Canvas 命令界面 + - 调试 Android Gateway 网关发现或认证 խնդիր + - 验证各客户端之间的聊天记录一致性 +summary: Android 应用（节点）：连接操作手册 + Connect/Chat/Voice/Canvas 命令界面 title: Android 应用 x-i18n: - generated_at: "2026-04-27T06:05:44Z" + generated_at: "2026-04-27T07:12:06Z" model: gpt-5.4 provider: openai - source_hash: 8ab1d9defd4606fe1408164f7f393367d01f3431a85e485dbe03b23e8ab69b14 + source_hash: cb25041d877df32f1a92e6ac9efa95e8f7e2a63368a88e1b9b6dce57353fc0ca source_path: platforms/android.md workflow: 15 --- -Android 应用尚未公开发布。源代码可在 [OpenClaw repository](https://github.com/openclaw/openclaw) 的 `apps/android` 下获取。你可以使用 Java 17 和 Android SDK 自行构建（`./gradlew :app:assemblePlayDebug`）。构建说明请参见 [apps/android/README.md](https://github.com/openclaw/openclaw/blob/main/apps/android/README.md)。 +Android 应用尚未公开发布。源代码可在 [OpenClaw 仓库](https://github.com/openclaw/openclaw) 的 `apps/android` 下获取。你可以使用 Java 17 和 Android SDK 自行构建（`./gradlew :app:assemblePlayDebug`）。构建说明见 [apps/android/README.md](https://github.com/openclaw/openclaw/blob/main/apps/android/README.md)。 ## 支持概览 -- 角色：配套应用节点（Android 不托管 Gateway 网关）。 -- 需要 Gateway 网关：是（在 macOS、Linux 或通过 WSL2 的 Windows 上运行）。 +- 角色：配套节点应用（Android 不托管 Gateway 网关）。 +- 是否需要 Gateway 网关：是（请在 macOS、Linux 或通过 WSL2 的 Windows 上运行）。 - 安装：[入门指南](/zh-CN/start/getting-started) + [配对](/zh-CN/channels/pairing)。 - Gateway 网关：[操作手册](/zh-CN/gateway) + [配置](/zh-CN/gateway/configuration)。 - 协议：[Gateway 网关协议](/zh-CN/gateway/protocol)（节点 + 控制平面）。 ## 系统控制 -系统控制（launchd/systemd）位于 Gateway 网关主机上。请参见 [Gateway 网关](/zh-CN/gateway)。 +系统控制（launchd/systemd）位于 Gateway 网关主机上。请参阅 [Gateway 网关](/zh-CN/gateway)。 ## 连接操作手册 Android 节点应用 ⇄（mDNS/NSD + WebSocket）⇄ **Gateway 网关** -Android 直接连接到 Gateway 网关 WebSocket，并使用设备配对（`role: node`）。 +Android 会直接连接到 Gateway 网关 WebSocket，并使用设备配对（`role: node`）。 对于 Tailscale 或公网主机，Android 需要安全端点： -- 首选：带 `https://` / `wss://` 的 Tailscale Serve / Funnel -- 也支持：任何其他具有真实 TLS 端点的 `wss://` Gateway 网关 URL -- 明文 `ws://` 仍支持私有局域网地址 / `.local` 主机，以及 `localhost`、`127.0.0.1` 和 Android 模拟器桥接地址（`10.0.2.2`） +- 首选：Tailscale Serve / Funnel，使用 `https://` / `wss://` +- 同样支持：任何其他带真实 TLS 端点的 `wss://` Gateway 网关 URL +- 明文 `ws://` 仍支持私有 LAN 地址 / `.local` 主机，以及 `localhost`、`127.0.0.1` 和 Android 模拟器桥接地址（`10.0.2.2`） ### 前提条件 - 你可以在“主”机器上运行 Gateway 网关。 - Android 设备/模拟器可以访问 gateway WebSocket： - - 位于同一局域网并使用 mDNS/NSD，**或** - - 位于同一个 Tailscale tailnet 并使用 Wide-Area Bonjour / 单播 DNS-SD（见下文），**或** - - 手动指定 gateway 主机/端口（兜底方案） -- tailnet/公网移动端配对**不会**使用原始 tailnet IP `ws://` 端点。请改用 Tailscale Serve 或其他 `wss://` URL。 -- 你可以在 gateway 机器上运行 CLI（`openclaw`）（或通过 SSH）。 + - 通过带 mDNS/NSD 的同一 LAN，**或者** + - 通过同一 Tailscale tailnet，并使用 Wide-Area Bonjour / 单播 DNS-SD（见下文），**或者** + - 手动指定 gateway 主机/端口（回退方式） +- 通过 tailnet/公网进行移动设备配对 **不** 使用原始 tailnet IP `ws://` 端点。请改用 Tailscale Serve 或其他 `wss://` URL。 +- 你可以在 gateway 机器上运行 CLI（`openclaw`）（或通过 SSH 运行）。 -### 1) 启动 Gateway 网关 +### 1）启动 Gateway 网关 ```bash openclaw gateway --port 18789 --verbose ``` -在日志中确认你能看到类似如下内容： +请在日志中确认你看到了类似以下内容： - `listening on ws://0.0.0.0:18789` -对于通过 Tailscale 进行远程 Android 访问，优先使用 Serve/Funnel，而不是原始 tailnet 绑定： +若要通过 Tailscale 供远程 Android 访问，优先使用 Serve/Funnel，而不是原始 tailnet 绑定： ```bash openclaw gateway --tailscale serve ``` -这会为 Android 提供一个安全的 `wss://` / `https://` 端点。普通的 `gateway.bind: "tailnet"` 设置不足以完成首次远程 Android 配对，除非你还单独终止了 TLS。 +这会为 Android 提供一个安全的 `wss://` / `https://` 端点。仅设置普通的 `gateway.bind: "tailnet"` 并不足以完成首次远程 Android 配对，除非你还额外终止了 TLS。 -### 2) 验证发现（可选） +### 2）验证设备发现（可选） 在 gateway 机器上运行： @@ -78,43 +78,43 @@ openclaw gateway --tailscale serve dns-sd -B _openclaw-gw._tcp local. ``` -更多调试说明： [Bonjour](/zh-CN/gateway/bonjour)。 +更多调试说明见：[Bonjour](/zh-CN/gateway/bonjour)。 -如果你还配置了广域发现域，请对比运行： +如果你还配置了 Wide-Area 发现域，请对照运行： ```bash openclaw gateway discover --json ``` -这会一次性显示 `local.` 和已配置的广域域名，并使用解析后的 -服务端点，而不是仅依赖 TXT 提示。 +这会一次性显示 `local.` 和已配置的 Wide-Area 域，并使用已解析的 +服务端点，而不是仅使用 TXT 提示。 -#### 通过单播 DNS-SD 进行 tailnet（Vienna ⇄ London）发现 +#### 通过单播 DNS-SD 在 tailnet 上发现（维也纳 ⇄ 伦敦） -Android NSD/mDNS 发现无法跨网络工作。如果你的 Android 节点和 gateway 位于不同网络，但通过 Tailscale 相连，请改用 Wide-Area Bonjour / 单播 DNS-SD。 +Android 的 NSD/mDNS 发现无法跨网络工作。如果你的 Android 节点和 gateway 位于不同网络，但通过 Tailscale 相连，请改用 Wide-Area Bonjour / 单播 DNS-SD。 -仅有发现并不足以完成 tailnet/公网 Android 配对。发现出的路由仍需要一个安全端点（`wss://` 或 Tailscale Serve）： +仅有设备发现并不足以完成 tailnet/公网 Android 配对。发现到的路由仍然需要安全端点（`wss://` 或 Tailscale Serve）： 1. 在 gateway 主机上设置一个 DNS-SD 区域（例如 `openclaw.internal.`），并发布 `_openclaw-gw._tcp` 记录。 -2. 为所选域配置 Tailscale split DNS，使其指向该 DNS 服务器。 +2. 为你选择的域配置 Tailscale split DNS，并将其指向该 DNS 服务器。 -详细信息和 CoreDNS 配置示例： [Bonjour](/zh-CN/gateway/bonjour)。 +详细信息和 CoreDNS 配置示例见：[Bonjour](/zh-CN/gateway/bonjour)。 -### 3) 从 Android 连接 +### 3）从 Android 连接 在 Android 应用中： -- 应用通过**前台服务**（持久通知）保持其 gateway 连接存活。 +- 应用通过**前台服务**（持久通知）保持与 gateway 的连接存活。 - 打开 **Connect** 标签页。 - 使用 **Setup Code** 或 **Manual** 模式。 -- 如果发现受阻，请在 **Advanced controls** 中使用手动主机/端口。对于私有局域网主机，`ws://` 仍然可用。对于 Tailscale/公网主机，请启用 TLS 并使用 `wss://` / Tailscale Serve 端点。 +- 如果设备发现被阻止，请在 **Advanced controls** 中手动填写主机/端口。对于私有 LAN 主机，`ws://` 仍然可用。对于 Tailscale/公网主机，请开启 TLS，并使用 `wss://` / Tailscale Serve 端点。 首次成功配对后，Android 会在启动时自动重连： -- 手动端点（如果已启用），否则 +- 手动端点（若已启用），否则 - 上次发现的 gateway（尽力而为）。 -### 4) 批准配对（CLI） +### 4）批准配对（CLI） 在 gateway 机器上： @@ -124,10 +124,10 @@ openclaw devices approve openclaw devices reject ``` -配对详情： [配对](/zh-CN/channels/pairing)。 +配对详情见：[配对](/zh-CN/channels/pairing)。 -可选：如果 Android 节点始终从严格受控的子网连接， -你可以选择通过显式 CIDR 或精确 IP 启用首次节点自动批准： +可选：如果 Android 节点总是从严格受控的子网连接， +你可以显式选择启用首次节点自动批准，并指定 CIDR 或精确 IP： ```json5 { @@ -141,11 +141,11 @@ openclaw devices reject } ``` -此功能默认禁用。它仅适用于全新的 `role: node` 配对，且 -没有请求作用域。操作员/浏览器配对以及任何角色、作用域、元数据或 -公钥变更仍然需要手动批准。 +此功能默认关闭。它仅适用于全新的 `role: node` 配对，且 +没有请求任何作用域。操作员/浏览器配对，以及任何角色、作用域、元数据或 +公钥变更，仍然需要手动批准。 -### 5) 验证节点已连接 +### 5）验证节点已连接 - 通过节点状态： @@ -159,64 +159,58 @@ openclaw devices reject openclaw gateway call node.list --params "{}" ``` -### 6) 聊天 + 历史记录 +### 6）聊天 + 历史记录 -Android Chat 标签页支持选择会话（默认 `main`，以及其他现有会话）： +Android Chat 标签页支持会话选择（默认 `main`，以及其他现有会话）： -- 历史记录：`chat.history`（已按显示进行规范化；可见文本中的内联指令标签会被 - 移除，纯文本工具调用 XML 负载（包括 - `...`、`...`、 - `...`、`...`，以及 - 被截断的工具调用块）和泄漏的 ASCII/全角模型控制 token - 会被移除，纯静默 token 助手行，例如完全等于 `NO_REPLY` / - `no_reply` 的内容会被省略，过大的行可能会被占位符替换） +- 历史记录：`chat.history`（按显示规范化；内联指令标签会从可见文本中移除，纯文本工具调用 XML 载荷（包括 `...`、`...`、`...`、`...` 以及被截断的工具调用代码块）和泄漏的 ASCII/全角模型控制令牌会被移除，纯静默令牌的助手行（例如精确匹配的 `NO_REPLY` / `no_reply`）会被省略，超大行则可能被占位符替换） - 发送：`chat.send` - 推送更新（尽力而为）：`chat.subscribe` → `event:"chat"` -### 7) Canvas + 相机 +### 7）Canvas + 相机 #### Gateway 网关 Canvas Host（推荐用于 Web 内容） 如果你希望节点显示智能体可以在磁盘上编辑的真实 HTML/CSS/JS，请将节点指向 Gateway 网关 canvas host。 -节点从 Gateway 网关 HTTP 服务器加载 canvas（与 `gateway.port` 相同端口，默认 `18789`）。 +节点从 Gateway 网关 HTTP 服务器加载 canvas（与 `gateway.port` 使用相同端口，默认 `18789`）。 1. 在 gateway 主机上创建 `~/.openclaw/workspace/canvas/index.html`。 -2. 让节点导航到该地址（局域网）： +2. 将节点导航到该地址（LAN）： ```bash openclaw nodes invoke --node "" --command canvas.navigate --params '{"url":"http://.local:18789/__openclaw__/canvas/"}' ``` -tailnet（可选）：如果两台设备都在 Tailscale 上，请使用 MagicDNS 名称或 tailnet IP 替代 `.local`，例如 `http://:18789/__openclaw__/canvas/`。 +Tailnet（可选）：如果两台设备都在 Tailscale 上，请使用 MagicDNS 名称或 tailnet IP 代替 `.local`，例如 `http://:18789/__openclaw__/canvas/`。 -该服务器会将 live-reload 客户端注入到 HTML 中，并在文件更改时重新加载。 +该服务器会将实时重载客户端注入到 HTML 中，并在文件变更时重新加载。 A2UI host 位于 `http://:18789/__openclaw__/a2ui/`。 Canvas 命令（仅前台）： - `canvas.eval`、`canvas.snapshot`、`canvas.navigate`（使用 `{"url":""}` 或 `{"url":"/"}` 返回默认脚手架）。`canvas.snapshot` 返回 `{ format, base64 }`（默认 `format="jpeg"`）。 -- A2UI：`canvas.a2ui.push`、`canvas.a2ui.reset`（`canvas.a2ui.pushJSONL` 旧版别名） +- A2UI：`canvas.a2ui.push`、`canvas.a2ui.reset`（`canvas.a2ui.pushJSONL` 为旧版别名） 相机命令（仅前台；受权限控制）： - `camera.snap`（jpg） - `camera.clip`（mp4） -参数和 CLI 辅助工具请参见[相机节点](/zh-CN/nodes/camera)。 +参数和 CLI 辅助工具见 [相机节点](/zh-CN/nodes/camera)。 -### 8) Voice + 扩展的 Android 命令界面 +### 8）语音 + 扩展 Android 命令界面 -- Voice 标签页：Android 有两种明确的捕获模式。**Mic** 是手动的 Voice 标签页会话，会将每次停顿作为一个聊天轮次发送，并在应用离开前台或用户离开 Voice 标签页时停止。**Talk** 是连续 Talk 模式，会持续监听，直到被关闭或节点断开连接。 -- Talk 模式会在开始捕获前，将现有前台服务从 `dataSync` 提升为 `dataSync|microphone`，并在 Talk 模式停止时再降回。Android 14+ 要求声明 `FOREGROUND_SERVICE_MICROPHONE`、授予 `RECORD_AUDIO` 运行时权限，并在运行时设置麦克风服务类型。 -- 语音回复通过已配置 gateway Talk 提供商的 `talk.speak` 播放。只有当 `talk.speak` 不可用时，才会使用本地系统 TTS。 -- Android UX/运行时中仍禁用语音唤醒。 +- Voice 标签页：Android 有两种显式采集模式。**Mic** 是一个手动的 Voice 标签页会话，会将每次停顿作为聊天轮次发送，并在应用离开前台或用户离开 Voice 标签页时停止。**Talk** 是连续的 Talk 模式，会持续监听，直到被关闭或节点断开连接。 +- Talk 模式会在开始采集前，将现有前台服务从 `dataSync` 提升为 `dataSync|microphone`，并在 Talk 模式停止时降级。Android 14+ 要求声明 `FOREGROUND_SERVICE_MICROPHONE`、授予 `RECORD_AUDIO` 运行时权限，并在运行时设置麦克风服务类型。 +- 语音回复通过已配置的 gateway Talk 提供商使用 `talk.speak`。仅当 `talk.speak` 不可用时才会使用本地系统 TTS。 +- Android UX/运行时中仍禁用了语音唤醒。 - 其他 Android 命令族（可用性取决于设备 + 权限）： - `device.status`、`device.info`、`device.permissions`、`device.health` - - `notifications.list`、`notifications.actions`（见下方[通知转发](#notification-forwarding)） + - `notifications.list`、`notifications.actions`（见下方 [通知转发](#notification-forwarding)） - `photos.latest` - `contacts.search`、`contacts.add` - `calendar.events`、`calendar.add` @@ -227,31 +221,30 @@ Canvas 命令（仅前台）： ## 助手入口点 Android 支持通过系统助手触发器启动 OpenClaw（Google -Assistant）。配置完成后，长按主页键或说“Hey Google, ask -OpenClaw...”会打开应用，并将提示词传入聊天输入框。 +Assistant）。配置完成后，长按主屏按钮或说出 “Hey Google, ask +OpenClaw...” 会打开应用，并将提示词传入聊天输入框。 -这是通过应用清单中声明的 Android **App Actions** 元数据实现的。Gateway 网关侧无需额外配置——助手 intent 完全由 Android 应用处理，并作为普通聊天消息转发。 +这使用的是在应用清单中声明的 Android **App Actions** 元数据。Gateway 网关侧无需额外配置——该助手意图完全由 Android 应用处理，并作为普通聊天消息转发。 -App Actions 的可用性取决于设备、Google Play Services 版本， -以及用户是否将 OpenClaw 设置为默认助手应用。 +App Actions 的可用性取决于设备、Google Play Services 版本，以及用户是否已将 OpenClaw 设为默认助手应用。 ## 通知转发 -Android 可以将设备通知作为事件转发到 gateway。你可以通过多个控制项来限定转发哪些通知以及何时转发。 +Android 可以将设备通知作为事件转发到 gateway。你可以使用多个控制项来限定转发哪些通知以及在何时转发。 -| 键 | 类型 | 说明 | -| -------------------------------- | -------------- | -------------------------------------------------------------------------------------- | -| `notifications.allowPackages` | string[] | 仅转发来自这些包名的通知。设置后，其他所有包都会被忽略。 | -| `notifications.denyPackages` | string[] | 永不转发来自这些包名的通知。在 `allowPackages` 之后应用。 | -| `notifications.quietHours.start` | string (HH:mm) | 静默时段窗口的开始时间（设备本地时间）。在该窗口期间会抑制通知。 | -| `notifications.quietHours.end` | string (HH:mm) | 静默时段窗口的结束时间。 | -| `notifications.rateLimit` | number | 每个包每分钟允许转发的最大通知数。超出的通知会被丢弃。 | +| Key | Type | 描述 | +| -------------------------------- | -------------- | ---- | +| `notifications.allowPackages` | string[] | 仅转发来自这些包名的通知。如果设置了该项，其他所有包都会被忽略。 | +| `notifications.denyPackages` | string[] | 永不转发来自这些包名的通知。该规则会在 `allowPackages` 之后应用。 | +| `notifications.quietHours.start` | string (HH:mm) | 免打扰时段开始时间（设备本地时间）。在此时间窗口内通知会被抑制。 | +| `notifications.quietHours.end` | string (HH:mm) | 免打扰时段结束时间。 | +| `notifications.rateLimit` | number | 每个包每分钟允许转发的通知上限。超出的通知会被丢弃。 | -通知选择器对转发的通知事件也采用了更安全的行为，以防止意外转发敏感系统通知。 +通知选择器还对转发的通知事件采用了更安全的行为，以防止敏感系统通知被意外转发。 -示例配置： +配置示例： ```json5 { diff --git a/docs/zh-CN/platforms/digitalocean.md b/docs/zh-CN/platforms/digitalocean.md index 02ff165bb..6e495da16 100644 --- a/docs/zh-CN/platforms/digitalocean.md +++ b/docs/zh-CN/platforms/digitalocean.md @@ -1,63 +1,63 @@ --- read_when: - 在 DigitalOcean 上设置 OpenClaw - - 正在寻找适合 OpenClaw 的低价 VPS 托管方案 -summary: 在 DigitalOcean 上运行 OpenClaw（简单的付费 VPS 方案） + - 为 OpenClaw 寻找低成本 VPS 托管 +summary: DigitalOcean 上的 OpenClaw（简单的付费 VPS 选项） title: DigitalOcean（平台） x-i18n: - generated_at: "2026-04-24T03:41:11Z" + generated_at: "2026-04-27T07:12:09Z" model: gpt-5.4 provider: openai - source_hash: c9d286f243f38ed910a3229f195be724f9f96481036380d8c8194ff298d39c87 + source_hash: 13df486b81590d6350f4b33f5460069fee21881631970d5f4ae34f6ce956407e source_path: platforms/digitalocean.md workflow: 15 --- -# 在 DigitalOcean 上运行 OpenClaw +# DigitalOcean 上的 OpenClaw ## 目标 -在 DigitalOcean 上以 **6 美元 / 月**（或使用预留定价时 4 美元 / 月）的成本运行一个持久化的 OpenClaw Gateway 网关。 +在 DigitalOcean 上运行一个持久化的 OpenClaw Gateway 网关，费用为 **6 美元 / 月**（或使用预留定价时为 4 美元 / 月）。 -如果你想要一个 0 美元 / 月的方案，并且不介意 ARM + 提供商特定的设置，请参见 [Oracle Cloud 指南](/zh-CN/install/oracle)。 +如果你想要一个 0 美元 / 月的选项，并且不介意 ARM + 特定 provider 的设置，请参阅 [Oracle Cloud 指南](/zh-CN/install/oracle)。 ## 成本对比（2026） -| 提供商 | 套餐 | 规格 | 月费 | 说明 | -| ------------ | --------------- | ---------------------- | ------------ | ------------------------------------ | -| Oracle Cloud | Always Free ARM | 最多 4 OCPU，24 GB RAM | $0 | ARM，容量有限 / 注册有些坑 | -| Hetzner | CX22 | 2 vCPU，4 GB RAM | €3.79（约 $4） | 最便宜的付费选项 | -| DigitalOcean | Basic | 1 vCPU，1 GB RAM | $6 | UI 简单，文档完善 | -| Vultr | Cloud Compute | 1 vCPU，1 GB RAM | $6 | 机房位置多 | -| Linode | Nanode | 1 vCPU，1 GB RAM | $5 | 现已成为 Akamai 的一部分 | +| 提供商 | 套餐 | 规格 | 月费 | 说明 | +| ------------ | --------------- | ---------------------- | ----------- | ------------------------------------- | +| Oracle Cloud | Always Free ARM | 最多 4 OCPU，24 GB RAM | $0 | ARM，容量有限 / 注册有些麻烦 | +| Hetzner | CX22 | 2 vCPU，4 GB RAM | €3.79（约 $4） | 最便宜的付费选项 | +| DigitalOcean | Basic | 1 vCPU，1 GB RAM | $6 | UI 简单，文档完善 | +| Vultr | Cloud Compute | 1 vCPU，1 GB RAM | $6 | 机房位置多 | +| Linode | Nanode | 1 vCPU，1 GB RAM | $5 | 现已并入 Akamai | **如何选择提供商：** -- DigitalOcean：最简单的 UX + 可预测的设置流程（本指南） +- DigitalOcean：最简单的用户体验 + 可预测的配置方式（本指南） - Hetzner：价格 / 性能比优秀（参见 [Hetzner 指南](/zh-CN/install/hetzner)） -- Oracle Cloud：可做到 0 美元 / 月，但更容易出问题且仅支持 ARM（参见 [Oracle 指南](/zh-CN/install/oracle)） +- Oracle Cloud：可以做到 0 美元 / 月，但更挑环境且仅支持 ARM（参见 [Oracle 指南](/zh-CN/install/oracle)） --- -## 前提条件 +## 前置条件 - DigitalOcean 账户（[注册可获 200 美元免费额度](https://m.do.co/c/signup)） -- SSH 密钥对（或愿意使用密码认证） -- 约 20 分钟 +- SSH 密钥对（或者愿意使用密码认证） +- 大约 20 分钟 ## 1）创建 Droplet -请使用干净的基础镜像（Ubuntu 24.04 LTS）。除非你已经审查过其启动脚本和防火墙默认值，否则请避免使用第三方 Marketplace 一键镜像。 +请使用干净的基础镜像（Ubuntu 24.04 LTS）。除非你已经审查过其启动脚本和防火墙默认设置，否则请避免使用第三方 Marketplace 一键镜像。 1. 登录 [DigitalOcean](https://cloud.digitalocean.com/) 2. 点击 **Create → Droplets** 3. 选择： - - **Region：** 离你（或你的用户）最近 + - **Region：** 离你最近的区域（或离你的用户最近） - **Image：** Ubuntu 24.04 LTS - **Size：** Basic → Regular → **6 美元 / 月**（1 vCPU，1 GB RAM，25 GB SSD） - - **Authentication：** SSH key（推荐）或 password + - **Authentication：** SSH 密钥（推荐）或密码 4. 点击 **Create Droplet** 5. 记下 IP 地址 @@ -70,17 +70,17 @@ ssh root@YOUR_DROPLET_IP ## 3）安装 OpenClaw ```bash -# 更新系统 +# Update system apt update && apt upgrade -y -# 安装 Node.js 24 +# Install Node.js 24 curl -fsSL https://deb.nodesource.com/setup_24.x | bash - apt install -y nodejs -# 安装 OpenClaw +# Install OpenClaw curl -fsSL https://openclaw.ai/install.sh | bash -# 验证 +# Verify openclaw --version ``` @@ -92,45 +92,45 @@ openclaw onboard --install-daemon 向导会引导你完成以下内容： -- 模型认证（API key 或 OAuth） +- 模型认证（API 密钥或 OAuth） - 渠道设置（Telegram、WhatsApp、Discord 等） -- Gateway 网关 token（自动生成） +- Gateway 网关令牌（自动生成） - 守护进程安装（systemd） ## 5）验证 Gateway 网关 ```bash -# 检查状态 +# Check status openclaw status -# 检查服务 +# Check service systemctl --user status openclaw-gateway.service -# 查看日志 +# View logs journalctl --user -u openclaw-gateway.service -f ``` -## 6）访问 Dashboard +## 6）访问仪表板 Gateway 网关默认绑定到 loopback。要访问 Control UI： **选项 A：SSH 隧道（推荐）** ```bash -# 在你的本地机器上 +# From your local machine ssh -L 18789:localhost:18789 root@YOUR_DROPLET_IP -# 然后打开：http://localhost:18789 +# Then open: http://localhost:18789 ``` **选项 B：Tailscale Serve（HTTPS，仅 loopback）** ```bash -# 在 droplet 上 +# On the droplet curl -fsSL https://tailscale.com/install.sh | sh tailscale up -# 配置 Gateway 网关使用 Tailscale Serve +# Configure Gateway to use Tailscale Serve openclaw config set gateway.tailscale.mode serve openclaw gateway restart ``` @@ -139,17 +139,17 @@ openclaw gateway restart 说明： -- Serve 会让 Gateway 网关保持仅 loopback，并通过 Tailscale 身份头为 Control UI / WebSocket 流量提供认证（无 token 认证假设 Gateway 网关主机可信；HTTP API 不会使用这些 Tailscale 头，而是遵循 Gateway 网关的常规 HTTP 认证模式）。 -- 如果你希望改为要求显式共享密钥凭证，请设置 `gateway.auth.allowTailscale: false`，并使用 `gateway.auth.mode: "token"` 或 `"password"`。 +- Serve 会让 Gateway 网关仅绑定 loopback，并通过 Tailscale 身份标头对 Control UI / WebSocket 流量进行认证（无令牌认证假定 Gateway 网关主机可信；HTTP API 不使用这些 Tailscale 标头，而是遵循 Gateway 网关的常规 HTTP 认证模式）。 +- 如果你想要求显式的共享密钥凭证，请设置 `gateway.auth.allowTailscale: false`，并使用 `gateway.auth.mode: "token"` 或 `"password"`。 -**选项 C：Tailnet 绑定（不使用 Serve）** +**选项 C：tailnet 绑定（不使用 Serve）** ```bash openclaw config set gateway.bind tailnet openclaw gateway restart ``` -打开：`http://:18789`（需要 token）。 +打开：`http://:18789`（需要令牌）。 ## 7）连接你的渠道 @@ -164,16 +164,16 @@ openclaw pairing approve telegram ```bash openclaw channels login whatsapp -# 扫描二维码 +# Scan QR code ``` -其他提供商请参见 [Channels](/zh-CN/channels)。 +其他提供商请参阅 [Channels](/zh-CN/channels)。 --- ## 针对 1 GB RAM 的优化 -6 美元的 droplet 只有 1 GB RAM。为了保持运行流畅： +这个 6 美元的 droplet 只有 1 GB RAM。为了保持运行顺畅： ### 添加 swap（推荐） @@ -203,12 +203,12 @@ htop ## 持久化 -所有状态都位于： +所有状态都保存在： -- `~/.openclaw/` — `openclaw.json`、每个智能体的 `auth-profiles.json`、渠道 / 提供商状态，以及会话数据 +- `~/.openclaw/` — `openclaw.json`、每个智能体的 `auth-profiles.json`、渠道 / provider 状态以及会话数据 - `~/.openclaw/workspace/` — 工作区（`SOUL.md`、记忆等） -这些内容在重启后仍会保留。请定期备份： +这些内容在重启后会保留。请定期备份： ```bash openclaw backup create @@ -218,21 +218,21 @@ openclaw backup create ## Oracle Cloud 免费替代方案 -Oracle Cloud 提供 **Always Free** ARM 实例，其性能明显强于这里列出的任何付费选项——而且费用是 0 美元 / 月。 +Oracle Cloud 提供 **Always Free** ARM 实例，性能显著强于这里列出的任何付费选项——而且费用是 0 美元 / 月。 -| 你将获得 | 规格 | -| -------------- | ---------------------- | -| **4 OCPU** | ARM Ampere A1 | -| **24 GB RAM** | 远远够用 | -| **200 GB 存储** | 块存储 | -| **永久免费** | 不会产生信用卡扣费 | +| 你将获得 | 规格 | +| ----------------- | ---------------------- | +| **4 OCPU** | ARM Ampere A1 | +| **24 GB RAM** | 远远足够 | +| **200 GB 存储** | 块存储卷 | +| **永久免费** | 不会产生信用卡扣费 | **注意事项：** -- 注册流程可能比较折腾（如果失败就重试） -- ARM 架构——大多数东西都能运行，但有些二进制程序需要 ARM 构建版本 +- 注册过程可能有些麻烦（如果失败请重试） +- ARM 架构——大多数内容都能正常工作，但某些二进制文件需要 ARM 构建版本 -完整设置指南请参见 [Oracle Cloud](/zh-CN/install/oracle)。有关注册技巧和注册流程故障排除，请参见这篇[社区指南](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd)。 +完整设置指南请参阅 [Oracle Cloud](/zh-CN/install/oracle)。关于注册技巧和注册流程故障排除，请参阅这份[社区指南](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd)。 --- @@ -256,11 +256,11 @@ kill ### 内存不足 ```bash -# 检查内存 +# Check memory free -h -# 添加更多 swap -# 或升级到 12 美元 / 月的 droplet（2 GB RAM） +# Add more swap +# Or upgrade to $12/mo droplet (2GB RAM) ``` --- diff --git a/docs/zh-CN/platforms/mac/dev-setup.md b/docs/zh-CN/platforms/mac/dev-setup.md index 3d8cc136e..10f0aef36 100644 --- a/docs/zh-CN/platforms/mac/dev-setup.md +++ b/docs/zh-CN/platforms/mac/dev-setup.md @@ -2,30 +2,30 @@ read_when: - 设置 macOS 开发环境 summary: 面向开发 OpenClaw macOS 应用的开发者设置指南 -title: macOS 开发设置 +title: macOS 开发环境设置 x-i18n: - generated_at: "2026-04-27T06:05:44Z" + generated_at: "2026-04-27T07:12:13Z" model: gpt-5.4 provider: openai - source_hash: f936c25513cf04de2c97c07e50a20b2797157ec52ef848d143722bf51a045100 + source_hash: d0c494b7a214b6db2880ba02c512653c35dbcdf80805bee9777ec946412668e1 source_path: platforms/mac/dev-setup.md workflow: 15 --- # macOS 开发者设置 -从源码构建并运行 OpenClaw macOS 应用。 +从源代码构建并运行 OpenClaw macOS 应用。 -## 前提条件 +## 前置要求 在构建应用之前，请确保你已安装以下内容： 1. **Xcode 26.2+**：Swift 开发所必需。 -2. **Node.js 24 和 pnpm**：推荐用于 Gateway 网关、CLI 和打包脚本。为兼容性起见，仍支持 Node 22 LTS，目前为 `22.14+`。 +2. **Node.js 24 和 pnpm**：推荐用于 Gateway 网关、CLI 和打包脚本。Node 22 LTS（当前为 `22.14+`）仍受支持，以保持兼容性。 ## 1. 安装依赖 -安装整个项目范围的依赖： +安装整个项目所需的依赖： ```bash pnpm install @@ -33,7 +33,7 @@ pnpm install ## 2. 构建并打包应用 -要构建 macOS 应用并将其打包到 `dist/OpenClaw.app`，运行： +要构建 macOS 应用并将其打包到 `dist/OpenClaw.app`，请运行： ```bash ./scripts/package-mac-app.sh @@ -41,53 +41,53 @@ pnpm install 如果你没有 Apple Developer ID 证书，脚本会自动使用**临时签名**（`-`）。 -有关开发运行模式、签名标志和 Team ID 故障排除，请参见 macOS 应用 README： +关于开发运行模式、签名标志以及 Team ID 故障排除，请参阅 macOS 应用 README： [https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md](https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md) -> **注意**：使用临时签名的应用可能会触发安全提示。如果应用立即以 “Abort trap 6” 崩溃，请参见[故障排除](#troubleshooting)部分。 +> **注意**：使用临时签名的应用可能会触发安全提示。如果应用立即崩溃并显示 “Abort trap 6”，请参阅[故障排除](#troubleshooting)部分。 ## 3. 安装 CLI -macOS 应用需要全局安装的 `openclaw` CLI 来管理后台任务。 +macOS 应用需要全局安装 `openclaw` CLI 来管理后台任务。 -**安装方式（推荐）：** +**安装方法（推荐）：** 1. 打开 OpenClaw 应用。 2. 前往 **General** 设置标签页。 3. 点击 **“Install CLI”**。 -或者手动安装： +你也可以手动安装： ```bash npm install -g openclaw@ ``` -`pnpm add -g openclaw@` 和 `bun add -g openclaw@` 也可以。 -对于 Gateway 网关 运行时，仍然推荐使用 Node。 +`pnpm add -g openclaw@` 和 `bun add -g openclaw@` 也可以使用。 +对于 Gateway 网关运行时，仍推荐使用 Node。 ## 故障排除 ### 构建失败：工具链或 SDK 不匹配 -macOS 应用构建要求使用最新的 macOS SDK 和 Swift 6.2 工具链。 +macOS 应用构建需要最新的 macOS SDK 和 Swift 6.2 工具链。 **系统依赖（必需）：** -- **Software Update 中可用的最新 macOS 版本**（Xcode 26.2 SDK 所需） +- **Software Update 中可用的最新 macOS 版本**（Xcode 26.2 SDK 所必需） - **Xcode 26.2**（Swift 6.2 工具链） -**检查：** +**检查命令：** ```bash xcodebuild -version xcrun swift --version ``` -如果版本不匹配，请更新 macOS/Xcode 并重新运行构建。 +如果版本不匹配，请更新 macOS / Xcode 后重新构建。 ### 授予权限时应用崩溃 -如果你在允许**语音识别**或**麦克风**访问时应用崩溃，可能是由于损坏的 TCC 缓存或签名不匹配导致的。 +如果你在允许**语音识别**或**麦克风**访问时应用崩溃，可能是由于损坏的 TCC 缓存或签名不匹配导致。 **修复方法：** @@ -97,11 +97,11 @@ xcrun swift --version tccutil reset All ai.openclaw.mac.debug ``` -2. 如果仍然失败，请临时修改 [`scripts/package-mac-app.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-app.sh) 中的 `BUNDLE_ID`，以强制 macOS 使用“全新状态”。 +2. 如果仍然无效，请临时修改 [`scripts/package-mac-app.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-app.sh) 中的 `BUNDLE_ID`，以强制 macOS 生成一个“全新状态”。 -### Gateway 网关 一直显示 “Starting...” +### Gateway 网关一直显示 “Starting...” -如果 Gateway 网关 状态始终停留在 “Starting...”，请检查是否有僵尸进程占用了端口： +如果 Gateway 网关状态一直停留在 “Starting...”，请检查是否有僵尸进程占用了端口： ```bash openclaw gateway status @@ -111,9 +111,9 @@ openclaw gateway stop lsof -nP -iTCP:18789 -sTCP:LISTEN ``` -如果是手动运行占用了端口，请停止该进程（Ctrl+C）。作为最后手段，终止你上面找到的 PID。 +如果是手动运行的进程占用了端口，请停止该进程（Ctrl+C）。作为最后手段，可以杀掉上面查到的 PID。 -## 相关 +## 相关内容 - [macOS 应用](/zh-CN/platforms/macos) - [安装概览](/zh-CN/install) diff --git a/docs/zh-CN/platforms/oracle.md b/docs/zh-CN/platforms/oracle.md index c23db42dc..68339ee61 100644 --- a/docs/zh-CN/platforms/oracle.md +++ b/docs/zh-CN/platforms/oracle.md @@ -1,64 +1,64 @@ --- read_when: - 在 Oracle Cloud 上设置 OpenClaw - - 为 OpenClaw 寻找低成本 VPS 托管方案 - - 想在一台小型服务器上让 OpenClaw 24/7 运行 -summary: Oracle Cloud（Always Free ARM）上的 OpenClaw + - 想为 OpenClaw 寻找低成本 VPS 托管方案 + - 想在小型服务器上 24/7 运行 OpenClaw +summary: 在 Oracle Cloud（Always Free ARM）上运行 OpenClaw title: Oracle Cloud（平台） x-i18n: - generated_at: "2026-04-24T03:41:48Z" + generated_at: "2026-04-27T07:12:28Z" model: gpt-5.4 provider: openai - source_hash: 18b2e55d330457e18bc94f1e7d7744a3cc3b0c0ce99654a61e9871c21e2c3e35 + source_hash: d86af91bd924ad08535a21fa481ce551e8c19f1a6cd82b61c335da7a068a09f0 source_path: platforms/oracle.md workflow: 15 --- -# Oracle Cloud（OCI）上的 OpenClaw +# 在 Oracle Cloud（OCI）上运行 OpenClaw ## 目标 -在 Oracle Cloud 的 **Always Free** ARM 套餐上运行一个持久化的 OpenClaw Gateway 网关。 +在 Oracle Cloud 的 **Always Free** ARM 套餐上运行一个持续在线的 OpenClaw Gateway 网关。 -Oracle 的免费套餐可能非常适合 OpenClaw（尤其是如果你已经有 OCI 账户），但它也有一些权衡： +Oracle 的免费套餐很适合运行 OpenClaw（尤其是如果你已经有 OCI 账号），但也有一些权衡： -- ARM 架构（大多数内容都能运行，但某些二进制文件可能仅支持 x86） -- 容量和注册流程可能比较挑剔 +- ARM 架构（大多数东西都能运行，但某些二进制程序可能仅支持 x86） +- 容量和注册流程可能不太稳定 -## 费用对比（2026） +## 价格对比（2026） -| 提供商 | 套餐 | 配置 | 月费 | 说明 | +| 提供商 | 套餐 | 配置 | 每月价格 | 说明 | | ------------ | --------------- | ---------------------- | -------- | --------------------- | -| Oracle Cloud | Always Free ARM | 最多 4 OCPU，24 GB RAM | $0 | ARM，容量有限 | -| Hetzner | CX22 | 2 vCPU，4 GB RAM | ~ $4 | 最便宜的付费选项 | -| DigitalOcean | Basic | 1 vCPU，1 GB RAM | $6 | UI 简单，文档完善 | -| Vultr | Cloud Compute | 1 vCPU，1 GB RAM | $6 | 机房位置多 | -| Linode | Nanode | 1 vCPU，1 GB RAM | $5 | 现已并入 Akamai | +| Oracle Cloud | Always Free ARM | 最多 4 OCPU、24 GB RAM | $0 | ARM，容量有限 | +| Hetzner | CX22 | 2 vCPU、4 GB RAM | ~ $4 | 最便宜的付费选项 | +| DigitalOcean | Basic | 1 vCPU、1 GB RAM | $6 | UI 易用，文档完善 | +| Vultr | Cloud Compute | 1 vCPU、1 GB RAM | $6 | 机房位置多 | +| Linode | Nanode | 1 vCPU、1 GB RAM | $5 | 现已归属 Akamai | --- -## 前提条件 +## 前置要求 -- Oracle Cloud 账户（[注册](https://www.oracle.com/cloud/free/)）—— 如果遇到问题，可参考[社区注册指南](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd) -- Tailscale 账户（可在 [tailscale.com](https://tailscale.com) 免费注册） -- 约 30 分钟 +- Oracle Cloud 账号（[注册](https://www.oracle.com/cloud/free/)）——如果遇到问题，请参考[社区注册指南](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd) +- Tailscale 账号（可在 [tailscale.com](https://tailscale.com) 免费注册） +- 大约 30 分钟 ## 1）创建 OCI 实例 1. 登录 [Oracle Cloud Console](https://cloud.oracle.com/) -2. 导航到 **Compute → Instances → Create Instance** -3. 配置： - - **Name：** `openclaw` - - **Image：** Ubuntu 24.04（aarch64） - - **Shape：** `VM.Standard.A1.Flex`（Ampere ARM） - - **OCPUs：** 2（或最多 4） - - **Memory：** 12 GB（或最多 24 GB） - - **Boot volume：** 50 GB（最多可免费使用 200 GB） - - **SSH key：** 添加你的公钥 +2. 进入 **Compute → Instances → Create Instance** +3. 配置如下： + - **Name:** `openclaw` + - **Image:** Ubuntu 24.04（aarch64） + - **Shape:** `VM.Standard.A1.Flex`（Ampere ARM） + - **OCPUs:** 2（或最多 4） + - **Memory:** 12 GB（或最多 24 GB） + - **Boot volume:** 50 GB（最多可免费使用 200 GB） + - **SSH key:** 添加你的公钥 4. 点击 **Create** 5. 记下公网 IP 地址 -**提示：** 如果实例创建因 “Out of capacity” 失败，请尝试其他可用性域，或稍后重试。免费套餐容量有限。 +**提示：** 如果创建实例时报错 “Out of capacity”，请尝试更换可用性域，或稍后重试。免费套餐容量有限。 ## 2）连接并更新系统 @@ -71,7 +71,7 @@ sudo apt update && sudo apt upgrade -y sudo apt install -y build-essential ``` -**注意：** 某些依赖在 ARM 上编译时需要 `build-essential`。 +**注意：** `build-essential` 是某些依赖在 ARM 上编译所必需的。 ## 3）配置用户和主机名 @@ -93,7 +93,7 @@ curl -fsSL https://tailscale.com/install.sh | sh sudo tailscale up --ssh --hostname=openclaw ``` -这会启用 Tailscale SSH，因此你可以从 tailnet 上的任意设备通过 `ssh openclaw` 连接 —— 不需要公网 IP。 +这样会启用 Tailscale SSH，因此你可以从 tailnet 中的任意设备使用 `ssh openclaw` 进行连接——无需公网 IP。 验证： @@ -110,19 +110,19 @@ curl -fsSL https://openclaw.ai/install.sh | bash source ~/.bashrc ``` -当提示 “How do you want to hatch your bot?” 时，选择 **“Do this later”**。 +当系统提示 “How do you want to hatch your bot?” 时，选择 **“Do this later”**。 -> 注意：如果遇到 ARM 原生构建问题，请先安装系统包（例如 `sudo apt install -y build-essential`），再考虑使用 Homebrew。 +> 注意：如果你遇到 ARM 原生构建问题，请先安装系统软件包（例如 `sudo apt install -y build-essential`），再考虑使用 Homebrew。 -## 6）配置 Gateway 网关（loopback + token 认证）并启用 Tailscale Serve +## 6）配置 Gateway 网关（loopback + token auth）并启用 Tailscale Serve -默认使用 token 认证。这样更可预测，也避免了需要在 Control UI 中启用任何 “insecure auth” 标志。 +默认使用 token auth。它更可预测，也避免了需要启用任何“不安全认证”的 Control UI 标志。 ```bash -# 让 Gateway 网关仅在虚拟机内保持私有 +# 让 Gateway 网关仅在 VM 内部可访问 openclaw config set gateway.bind loopback -# 为 Gateway 网关 + Control UI 要求认证 +# 为 Gateway 网关 + Control UI 启用认证 openclaw config set gateway.auth.mode token openclaw doctor --generate-gateway-token @@ -133,7 +133,7 @@ openclaw config set gateway.trustedProxies '["127.0.0.1"]' systemctl --user restart openclaw-gateway.service ``` -这里的 `gateway.trustedProxies=["127.0.0.1"]` 仅用于本地 Tailscale Serve 代理的转发 IP/本地客户端处理。它**不是** `gateway.auth.mode: "trusted-proxy"`。在此设置下，Diff 查看器路由仍保持默认拒绝行为：没有转发代理头的原始 `127.0.0.1` 查看器请求可能返回 `Diff not found`。如果你需要附件，请使用 `mode=file` / `mode=both`；如果你需要可分享的查看器链接，请有意启用远程查看器并设置 `plugins.entries.diffs.config.viewerBaseUrl`（或传入代理 `baseUrl`）。 +这里的 `gateway.trustedProxies=["127.0.0.1"]` 仅用于本地 Tailscale Serve 代理的转发 IP / 本地客户端处理。它**不是** `gateway.auth.mode: "trusted-proxy"`。在这种配置下，Diff 查看器路由仍保持失败即关闭的行为：如果直接从 `127.0.0.1` 发起、且没有转发代理头的查看器请求，可能会返回 `Diff not found`。如果你需要可共享的查看器链接，请对附件使用 `mode=file` / `mode=both`，或者有意启用远程查看器，并设置 `plugins.entries.diffs.config.viewerBaseUrl`（或传入代理 `baseUrl`）。 ## 7）验证 @@ -151,63 +151,63 @@ tailscale serve status curl http://localhost:18789 ``` -## 8）锁定 VCN 安全规则 +## 8）收紧 VCN 安全设置 -现在一切都已正常运行，可以锁定 VCN，仅允许 Tailscale 流量。OCI 的 Virtual Cloud Network 会在网络边缘充当防火墙 —— 流量会在到达实例之前被拦截。 +现在一切都已正常运行，请收紧 VCN，仅允许 Tailscale 流量。OCI 的 Virtual Cloud Network 会在网络边界充当防火墙——流量会在到达实例之前被拦截。 -1. 在 OCI Console 中进入 **Networking → Virtual Cloud Networks** +1. 在 OCI Console 中前往 **Networking → Virtual Cloud Networks** 2. 点击你的 VCN → **Security Lists** → Default Security List -3. **删除**除以下规则外的所有入站规则： +3. **删除**所有入站规则，仅保留： - `0.0.0.0/0 UDP 41641`（Tailscale） -4. 保留默认出站规则（允许所有出站流量） +4. 保留默认出站规则（允许所有出站） -这样会在网络边缘阻止 22 端口 SSH、HTTP、HTTPS 以及其他所有流量。从现在起，你只能通过 Tailscale 连接。 +这样会在网络边界阻止 22 端口 SSH、HTTP、HTTPS 以及其他所有流量。从现在开始，你只能通过 Tailscale 连接。 --- ## 访问 Control UI -在你 Tailscale 网络中的任意设备上访问： +在你的 Tailscale 网络中的任意设备上访问： -``` +```text https://openclaw..ts.net/ ``` -将 `` 替换为你的 tailnet 名称（可在 `tailscale status` 中看到）。 +将 `` 替换为你的 tailnet 名称（可在 `tailscale status` 中查看）。 -不需要 SSH 隧道。Tailscale 提供： +无需 SSH 隧道。Tailscale 提供： - HTTPS 加密（自动证书） - 基于 Tailscale 身份的认证 -- 从你的 tailnet 中任意设备访问（笔记本、手机等） +- 从 tailnet 中任意设备访问（笔记本、手机等） --- ## 安全性：VCN + Tailscale（推荐基线） -在 VCN 已锁定（仅开放 UDP 41641）且 Gateway 网关绑定到 loopback 的情况下，你会获得很强的纵深防御：公网流量会在网络边缘被阻止，而管理访问则通过你的 tailnet 进行。 +在 VCN 收紧（仅开放 UDP 41641）且 Gateway 网关绑定到 loopback 的前提下，你将获得强有力的纵深防御：公网流量会在网络边界被拦截，而管理访问则通过你的 tailnet 进行。 -这种设置通常可以消除单纯为了阻止互联网范围 SSH 暴力破解而额外配置主机防火墙规则的_必要性_ —— 但你仍应保持系统更新、运行 `openclaw security audit`，并确认自己没有意外监听公网接口。 +这种配置通常可以消除额外使用主机防火墙规则来阻止互联网 SSH 暴力破解的**必要性**——但你仍应保持操作系统为最新状态，运行 `openclaw security audit`，并确认没有意外监听公网接口。 -### 已经受到保护的项目 +### 已经受到保护的部分 -| 传统步骤 | 需要吗？ | 原因 | +| 传统步骤 | 需要吗？ | 原因 | | ------------------ | ----------- | ---------------------------------------------------------------------------- | -| UFW 防火墙 | 否 | VCN 会在流量到达实例前先行阻止 | -| fail2ban | 否 | 如果 VCN 已屏蔽 22 端口，就不存在暴力破解 | -| sshd 加固 | 否 | Tailscale SSH 不使用 sshd | -| 禁用 root 登录 | 否 | Tailscale 使用的是 Tailscale 身份，而不是系统用户 | -| 仅 SSH 密钥认证 | 否 | Tailscale 通过你的 tailnet 进行认证 | -| IPv6 加固 | 通常不需要 | 取决于你的 VCN/子网设置；请核实实际分配/暴露了什么 | +| UFW 防火墙 | 不需要 | VCN 会在流量到达实例前进行拦截 | +| fail2ban | 不需要 | 如果 VCN 已封锁 22 端口，就不存在暴力破解 | +| sshd 加固 | 不需要 | Tailscale SSH 不使用 sshd | +| 禁用 root 登录 | 不需要 | Tailscale 使用 Tailscale 身份，而不是系统用户 | +| 仅允许 SSH 密钥认证 | 不需要 | Tailscale 通过你的 tailnet 进行认证 | +| IPv6 加固 | 通常不需要 | 取决于你的 VCN / 子网设置；请核实实际分配和暴露情况 | -### 仍然推荐 +### 仍然建议执行 - **凭证权限：** `chmod 700 ~/.openclaw` - **安全审计：** `openclaw security audit` - **系统更新：** 定期运行 `sudo apt update && sudo apt upgrade` -- **监控 Tailscale：** 在 [Tailscale 管理控制台](https://login.tailscale.com/admin)中检查设备 +- **监控 Tailscale：** 在 [Tailscale 管理控制台](https://login.tailscale.com/admin)查看设备 -### 验证安全态势 +### 验证安全状态 ```bash # 确认没有监听公网端口 @@ -216,7 +216,7 @@ sudo ss -tlnp | grep -v '127.0.0.1\|::1' # 验证 Tailscale SSH 已启用 tailscale status | grep -q 'offers: ssh' && echo "Tailscale SSH active" -# 可选：完全禁用 sshd +# 可选：彻底禁用 sshd sudo systemctl disable --now ssh ``` @@ -224,10 +224,10 @@ sudo systemctl disable --now ssh ## 回退方案：SSH 隧道 -如果 Tailscale Serve 无法工作，请使用 SSH 隧道： +如果 Tailscale Serve 无法正常工作，请使用 SSH 隧道： ```bash -# 在你的本地机器上（通过 Tailscale） +# 在你的本地机器上执行（通过 Tailscale） ssh -L 18789:127.0.0.1:18789 ubuntu@openclaw ``` @@ -239,11 +239,11 @@ ssh -L 18789:127.0.0.1:18789 ubuntu@openclaw ### 实例创建失败（“Out of capacity”） -免费套餐 ARM 实例很抢手。可以尝试： +免费 ARM 实例很热门。你可以尝试： - 更换可用性域 -- 在非高峰时段重试（清晨） -- 选择实例规格时使用 “Always Free” 筛选器 +- 在低峰时段重试（清晨） +- 在选择实例规格时使用 “Always Free” 筛选器 ### Tailscale 无法连接 @@ -269,31 +269,31 @@ journalctl --user -u openclaw-gateway.service -n 50 # 验证 Tailscale Serve 正在运行 tailscale serve status -# 检查 gateway 是否在监听 +# 检查 gateway 是否正在监听 curl http://localhost:18789 -# 如有需要，重启 +# 如有需要则重启 systemctl --user restart openclaw-gateway.service ``` ### ARM 二进制问题 -某些工具可能没有 ARM 构建版本。请检查： +有些工具可能没有 ARM 构建版本。请检查： ```bash uname -m # 应显示 aarch64 ``` -大多数 npm 包都能正常工作。对于二进制文件，请寻找 `linux-arm64` 或 `aarch64` 版本。 +大多数 npm 包都可以正常工作。对于二进制程序，请查找 `linux-arm64` 或 `aarch64` 版本。 --- ## 持久化 -所有状态都保存在： +所有状态都保存在以下位置： -- `~/.openclaw/` — `openclaw.json`、每个智能体的 `auth-profiles.json`、渠道/提供商状态以及会话数据 -- `~/.openclaw/workspace/` — 工作区（`SOUL.md`、memory、artifacts） +- `~/.openclaw/` — `openclaw.json`、每个智能体的 `auth-profiles.json`、渠道 / 提供商状态以及会话数据 +- `~/.openclaw/workspace/` — 工作区（`SOUL.md`、memory、制品） 请定期备份： @@ -305,8 +305,8 @@ openclaw backup create ## 相关内容 -- [Gateway 远程访问](/zh-CN/gateway/remote) — 其他远程访问模式 +- [Gateway 网关远程访问](/zh-CN/gateway/remote) — 其他远程访问方式 - [Tailscale 集成](/zh-CN/gateway/tailscale) — 完整的 Tailscale 文档 - [Gateway 网关配置](/zh-CN/gateway/configuration) — 所有配置选项 -- [DigitalOcean 指南](/zh-CN/install/digitalocean) — 如果你想要付费但更容易注册的方案 +- [DigitalOcean 指南](/zh-CN/install/digitalocean) — 如果你希望使用付费服务并获得更轻松的注册体验 - [Hetzner 指南](/zh-CN/install/hetzner) — 基于 Docker 的替代方案 diff --git a/docs/zh-CN/platforms/raspberry-pi.md b/docs/zh-CN/platforms/raspberry-pi.md index 564a81913..1e439bdd7 100644 --- a/docs/zh-CN/platforms/raspberry-pi.md +++ b/docs/zh-CN/platforms/raspberry-pi.md @@ -3,13 +3,13 @@ read_when: - 在 Raspberry Pi 上设置 OpenClaw - 在 ARM 设备上运行 OpenClaw - 搭建一个低成本、始终在线的个人 AI -summary: 在 Raspberry Pi 上运行 OpenClaw（低预算自托管设置） +summary: 在 Raspberry Pi 上运行 OpenClaw（低成本自托管方案） title: Raspberry Pi（平台） x-i18n: - generated_at: "2026-04-24T03:41:55Z" + generated_at: "2026-04-27T07:12:35Z" model: gpt-5.4 provider: openai - source_hash: 79a2e8edf3c2853deddece8d52dc87b9a5800643b4d866acd80db3a83ca9b270 + source_hash: f5a277499ee8759f766984b3fd2097dbd55f2f34ba6169fdfc2eb9dd53d6bb7c source_path: platforms/raspberry-pi.md workflow: 15 --- @@ -18,35 +18,35 @@ x-i18n: ## 目标 -在 Raspberry Pi 上运行一个持久、始终在线的 OpenClaw Gateway 网关，一次性成本约为 **35–80 美元**（无月费）。 +在 Raspberry Pi 上运行一个持久、始终在线的 OpenClaw Gateway 网关，一次性成本约 **35–80 美元**（无月费）。 非常适合： - 24/7 个人 AI 助手 -- 家庭自动化中枢 +- 家庭自动化中心 - 低功耗、始终可用的 Telegram/WhatsApp 机器人 ## 硬件要求 -| Pi 型号 | RAM | 可用？ | 说明 | -| --------------- | ------- | -------- | ---------------------------------- | -| **Pi 5** | 4GB/8GB | ✅ 最佳 | 最快，推荐 | -| **Pi 4** | 4GB | ✅ 良好 | 大多数用户的最佳平衡点 | -| **Pi 4** | 2GB | ✅ 可用 | 可以运行，建议增加 swap | -| **Pi 4** | 1GB | ⚠️ 紧张 | 配合 swap 和最小配置可以运行 | -| **Pi 3B+** | 1GB | ⚠️ 较慢 | 可以运行，但会比较卡顿 | -| **Pi Zero 2 W** | 512MB | ❌ | 不推荐 | +| Pi 型号 | RAM | 可用？ | 说明 | +| --------------- | ------- | -------- | -------------------------- | +| **Pi 5** | 4 GB/8 GB | ✅ 最佳 | 最快，推荐 | +| **Pi 4** | 4 GB | ✅ 良好 | 大多数用户的甜点配置 | +| **Pi 4** | 2 GB | ✅ 可以 | 可用，建议增加 swap | +| **Pi 4** | 1 GB | ⚠️ 紧张 | 配合 swap 和最小配置可用 | +| **Pi 3B+** | 1 GB | ⚠️ 较慢 | 能运行，但响应较迟缓 | +| **Pi Zero 2 W** | 512 MB | ❌ | 不推荐 | -**最低规格：** 1GB RAM、1 个核心、500MB 磁盘 -**推荐规格：** 2GB 以上 RAM、64 位操作系统、16GB 以上 SD 卡（或 USB SSD） +**最低配置：** 1 GB RAM、1 核、500 MB 磁盘 +**推荐配置：** 2 GB 以上 RAM、64 位操作系统、16 GB 以上 SD 卡（或 USB SSD） ## 你需要准备 -- Raspberry Pi 4 或 5（推荐 2GB 以上） -- MicroSD 卡（16GB 以上）或 USB SSD（性能更好） -- 电源适配器（推荐官方 Pi 电源） -- 网络连接（以太网或 WiFi） -- 约 30 分钟 +- Raspberry Pi 4 或 5（推荐 2 GB 以上） +- MicroSD 卡（16 GB 以上）或 USB SSD（性能更好） +- 电源适配器（推荐使用官方 Pi 电源） +- 网络连接（以太网或 Wi‑Fi） +- 大约 30 分钟 ## 1）刷写操作系统 @@ -58,8 +58,8 @@ x-i18n: - 设置主机名：`gateway-host` - 启用 SSH - 设置用户名/密码 - - 配置 WiFi（如果不使用以太网） -4. 将镜像刷写到 SD 卡 / USB 驱动器 + - 配置 Wi‑Fi（如果不使用以太网） +4. 刷写到你的 SD 卡 / USB 驱动器 5. 插入并启动 Pi ## 2）通过 SSH 连接 @@ -76,7 +76,7 @@ ssh user@192.168.x.x # 更新系统 sudo apt update && sudo apt upgrade -y -# 安装必要软件包 +# 安装基础软件包 sudo apt install -y git curl build-essential # 设置时区（对 cron/提醒很重要） @@ -95,18 +95,18 @@ node --version # 应显示 v24.x.x npm --version ``` -## 5）添加 Swap（对 2GB 或更低内存非常重要） +## 5）添加 swap（对 2 GB 及以下内存很重要） -Swap 可防止因内存不足而崩溃： +swap 可以防止因内存不足而崩溃： ```bash -# 创建 2GB swap 文件 +# 创建 2 GB swap 文件 sudo fallocate -l 2G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile -# 设为永久生效 +# 持久化 echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab # 为低内存优化（降低 swappiness） @@ -122,7 +122,7 @@ sudo sysctl -p curl -fsSL https://openclaw.ai/install.sh | bash ``` -### 选项 B：可修改安装（适合折腾） +### 选项 B：可修改安装（适合折腾和调试） ```bash git clone https://github.com/openclaw/openclaw.git @@ -132,7 +132,7 @@ npm run build npm link ``` -可修改安装会让你直接访问日志和代码——这对调试 ARM 特定问题很有帮助。 +可修改安装让你可以直接访问日志和代码——这对于调试 ARM 专属问题很有帮助。 ## 7）运行新手引导 @@ -140,10 +140,10 @@ npm link openclaw onboard --install-daemon ``` -按照向导进行操作： +按照向导操作： 1. **Gateway 网关模式：** Local -2. **认证：** 推荐使用 API key（OAuth 在无头 Pi 上可能不太稳定） +2. **认证：** 推荐 API 密钥（在无头 Pi 上，OAuth 可能比较难处理） 3. **渠道：** 最容易开始的是 Telegram 4. **守护进程：** 是（systemd） @@ -160,19 +160,18 @@ systemctl --user status openclaw-gateway.service journalctl --user -u openclaw-gateway.service -f ``` -## 9）访问 OpenClaw 仪表板 +## 9）访问 OpenClaw 仪表盘 将 `user@gateway-host` 替换为你的 Pi 用户名，以及主机名或 IP 地址。 -在你的电脑上，让 Pi 打印一个新的仪表板 URL： +在你的电脑上，让 Pi 打印一个新的仪表盘 URL： ```bash ssh user@gateway-host 'openclaw dashboard --no-open' ``` -该命令会输出 `Dashboard URL:`。根据 `gateway.auth.token` -的配置方式，URL 可能是普通的 `http://127.0.0.1:18789/` 链接，也可能 -包含 `#token=...`。 +该命令会打印 `Dashboard URL:`。根据 `gateway.auth.token` +的配置方式，这个 URL 可能是一个普通的 `http://127.0.0.1:18789/` 链接，也可能包含 `#token=...`。 在你电脑上的另一个终端中，创建 SSH 隧道： @@ -180,11 +179,9 @@ ssh user@gateway-host 'openclaw dashboard --no-open' ssh -N -L 18789:127.0.0.1:18789 user@gateway-host ``` -然后在本地浏览器中打开刚刚输出的 Dashboard URL。 +然后在本地浏览器中打开打印出的 Dashboard URL。 -如果 UI 要求输入共享 secret 认证，请将已配置的 token 或密码 -粘贴到 Control UI 设置中。对于 token 认证，请使用 `gateway.auth.token`（或 -`OPENCLAW_GATEWAY_TOKEN`）。 +如果 UI 要求共享密钥认证，请将已配置的令牌或密码粘贴到 Control UI 设置中。对于令牌认证，请使用 `gateway.auth.token`（或 `OPENCLAW_GATEWAY_TOKEN`）。 如需始终在线的远程访问，请参阅 [Tailscale](/zh-CN/gateway/tailscale)。 @@ -194,7 +191,7 @@ ssh -N -L 18789:127.0.0.1:18789 user@gateway-host ### 使用 USB SSD（提升巨大） -SD 卡较慢且容易磨损。USB SSD 可显著提升性能： +SD 卡速度较慢，而且容易磨损。USB SSD 可以显著提升性能： ```bash # 检查是否从 USB 启动 @@ -203,9 +200,9 @@ lsblk 设置方法请参阅 [Pi USB 启动指南](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#usb-mass-storage-boot)。 -### 加快 CLI 启动（模块编译缓存） +### 加快 CLI 启动速度（模块编译缓存） -在低功耗 Pi 主机上，启用 Node 的模块编译缓存可加快重复运行 CLI 的速度： +在性能较弱的 Pi 主机上，启用 Node 的模块编译缓存可以让重复运行 CLI 更快： ```bash grep -q 'NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF' # pragma: allowlist secret @@ -218,15 +215,14 @@ source ~/.bashrc 说明： -- `NODE_COMPILE_CACHE` 可加快后续运行（`status`、`health`、`--help`）。 +- `NODE_COMPILE_CACHE` 可以加速后续运行（`status`、`health`、`--help`）。 - `/var/tmp` 比 `/tmp` 更能在重启后保留内容。 -- `OPENCLAW_NO_RESPAWN=1` 可避免 CLI 自我重启带来的额外启动开销。 -- 第一次运行会预热缓存；后续运行收益最大。 +- `OPENCLAW_NO_RESPAWN=1` 可以避免 CLI 自我重启带来的额外启动开销。 +- 首次运行会预热缓存；后续运行受益最大。 ### systemd 启动调优（可选） -如果这台 Pi 主要用于运行 OpenClaw，可添加一个服务 drop-in，以减少重启 -抖动并保持启动环境稳定： +如果这台 Pi 主要就是运行 OpenClaw，可以添加一个服务 drop-in，以减少重启抖动并保持启动环境稳定： ```bash systemctl --user edit openclaw-gateway.service @@ -241,32 +237,31 @@ RestartSec=2 TimeoutStartSec=90 ``` -然后应用： +然后应用更改： ```bash systemctl --user daemon-reload systemctl --user restart openclaw-gateway.service ``` -如果可能，请将 OpenClaw 状态/缓存保存在 SSD 支持的存储上，以避免冷启动期间 -SD 卡随机 I/O 成为瓶颈。 +如果可能，请将 OpenClaw 的状态/缓存保存在 SSD 支持的存储上，以避免冷启动时 SD 卡随机 I/O 成为瓶颈。 -如果这是一台无头 Pi，请启用 lingering 一次，以便用户服务在注销后仍然继续运行： +如果这是一个无头 Pi，请执行一次 lingering 设置，以便用户服务在退出登录后仍能继续运行： ```bash sudo loginctl enable-linger "$(whoami)" ``` -有关 `Restart=` 策略如何帮助自动恢复： -[systemd 可以自动执行服务恢复](https://www.redhat.com/en/blog/systemd-automate-recovery)。 +关于 `Restart=` 策略如何帮助自动恢复，请参阅： +[systemd can automate service recovery](https://www.redhat.com/en/blog/systemd-automate-recovery)。 ### 降低内存占用 ```bash -# 禁用 GPU 内存分配（无头环境） +# 禁用 GPU 内存分配（无头模式） echo 'gpu_mem=16' | sudo tee -a /boot/config.txt -# 如果不需要则禁用蓝牙 +# 如果不需要，禁用蓝牙 sudo systemctl disable bluetooth ``` @@ -285,25 +280,25 @@ htop --- -## ARM 特定说明 +## ARM 专属说明 ### 二进制兼容性 -大多数 OpenClaw 功能都能在 ARM64 上运行，但某些外部二进制可能需要 ARM 版本： +大多数 OpenClaw 功能都能在 ARM64 上运行，但某些外部二进制文件可能需要 ARM 版本： -| 工具 | ARM64 状态 | 说明 | -| ------------------ | ------------ | ----------------------------------- | -| Node.js | ✅ | 运行良好 | -| WhatsApp（Baileys） | ✅ | 纯 JS，无问题 | -| Telegram | ✅ | 纯 JS，无问题 | -| gog（Gmail CLI） | ⚠️ | 需检查是否有 ARM 发行版 | -| Chromium（浏览器） | ✅ | `sudo apt install chromium-browser` | +| 工具 | ARM64 状态 | 说明 | +| ------------------ | ---------- | --------------------------------- | +| Node.js | ✅ | 运行良好 | +| WhatsApp (Baileys) | ✅ | 纯 JS，无问题 | +| Telegram | ✅ | 纯 JS，无问题 | +| gog (Gmail CLI) | ⚠️ | 请检查是否有 ARM 版本发布 | +| Chromium (browser) | ✅ | `sudo apt install chromium-browser` | -如果某个 Skills 失败，请检查它的二进制是否有 ARM 构建。许多 Go/Rust 工具有；有些没有。 +如果某个 Skills 失败，请检查其二进制文件是否有 ARM 版本。许多 Go/Rust 工具都有，但也有一些没有。 ### 32 位与 64 位 -**始终使用 64 位操作系统。** Node.js 和许多现代工具都需要它。可通过以下命令检查： +**务必使用 64 位操作系统。** Node.js 和许多现代工具都需要它。使用以下命令检查： ```bash uname -m @@ -312,9 +307,9 @@ uname -m --- -## 推荐模型设置 +## 推荐的模型设置 -由于 Pi 仅作为 Gateway 网关使用（模型在云端运行），请使用基于 API 的模型： +由于 Pi 只是 Gateway 网关（模型运行在云端），请使用基于 API 的模型： ```json { @@ -329,19 +324,19 @@ uname -m } ``` -**不要尝试在 Pi 上运行本地 LLM** —— 即使是小模型也太慢。让 Claude/GPT 来承担主要计算工作。 +**不要尝试在 Pi 上运行本地 LLM。** 即使是小模型也会太慢。让 Claude/GPT 去承担重负载更合适。 --- -## 开机自启动 +## 开机自启 -新手引导会自动设置这一点，但你也可以验证： +新手引导会自动设置好这一点，但你可以这样验证： ```bash # 检查服务是否已启用 systemctl --user is-enabled openclaw-gateway.service -# 如果未启用则启用 +# 如果没有启用，则启用 systemctl --user enable openclaw-gateway.service # 开机启动 @@ -355,7 +350,7 @@ systemctl --user start openclaw-gateway.service ### 内存不足（OOM） ```bash -# 查看内存 +# 检查内存 free -h # 增加更多 swap（见步骤 5） @@ -364,9 +359,9 @@ free -h ### 性能缓慢 -- 使用 USB SSD 而不是 SD 卡 +- 使用 USB SSD，而不是 SD 卡 - 禁用未使用的服务：`sudo systemctl disable cups bluetooth avahi-daemon` -- 检查 CPU 是否降频：`vcgencmd get_throttled`（应返回 `0x0`） +- 检查 CPU 是否被限频：`vcgencmd get_throttled`（应返回 `0x0`） ### 服务无法启动 @@ -374,8 +369,8 @@ free -h # 查看日志 journalctl --user -u openclaw-gateway.service --no-pager -n 100 -# 常见修复：重新构建 -cd ~/openclaw # 如果使用可修改安装 +# 常见修复方式：重新构建 +cd ~/openclaw # 如果你使用的是可修改安装 npm run build systemctl --user restart openclaw-gateway.service ``` @@ -384,19 +379,19 @@ systemctl --user restart openclaw-gateway.service 如果某个 Skills 因 “exec format error” 失败： -1. 检查该二进制是否有 ARM64 构建 +1. 检查该二进制文件是否有 ARM64 版本 2. 尝试从源码构建 3. 或使用支持 ARM 的 Docker 容器 -### WiFi 掉线 +### Wi‑Fi 掉线 -对于通过 WiFi 运行的无头 Pi： +对于通过 Wi‑Fi 运行的无头 Pi： ```bash -# 禁用 WiFi 省电管理 +# 禁用 Wi‑Fi 省电 sudo iwconfig wlan0 power off -# 设为永久生效 +# 持久化 echo 'wireless-power off' | sudo tee -a /etc/network/interfaces ``` @@ -404,23 +399,23 @@ echo 'wireless-power off' | sudo tee -a /etc/network/interfaces ## 成本对比 -| 方案 | 一次性成本 | 月成本 | 说明 | -| -------------- | ------------- | ------------ | ------------------------- | -| **Pi 4（2GB）** | ~$45 | $0 | + 电费（约 $5/年） | -| **Pi 4（4GB）** | ~$55 | $0 | 推荐 | -| **Pi 5（4GB）** | ~$60 | $0 | 最佳性能 | -| **Pi 5（8GB）** | ~$80 | $0 | 有些超配，但更面向未来 | -| DigitalOcean | $0 | $6/月 | $72/年 | -| Hetzner | $0 | €3.79/月 | 约 $50/年 | +| 配置 | 一次性成本 | 月成本 | 说明 | +| ---------------- | ---------- | ------ | ------------------------- | +| **Pi 4（2 GB）** | ~$45 | $0 | 加上电费（约 $5/年） | +| **Pi 4（4 GB）** | ~$55 | $0 | 推荐 | +| **Pi 5（4 GB）** | ~$60 | $0 | 最佳性能 | +| **Pi 5（8 GB）** | ~$80 | $0 | 略显过剩，但更面向未来 | +| DigitalOcean | $0 | $6/月 | 每年 $72 | +| Hetzner | $0 | €3.79/月 | 每年约 $50 | -**回本周期：** 与云 VPS 相比，Pi 大约 6–12 个月即可回本。 +**回本周期：** 与云 VPS 相比，Pi 大约在 6–12 个月内可以回本。 --- ## 相关内容 -- [Linux 指南](/zh-CN/platforms/linux) —— 通用 Linux 设置 -- [DigitalOcean 指南](/zh-CN/install/digitalocean) —— 云端替代方案 -- [Hetzner 指南](/zh-CN/install/hetzner) —— Docker 设置 -- [Tailscale](/zh-CN/gateway/tailscale) —— 远程访问 -- [Nodes](/zh-CN/nodes) —— 将你的笔记本电脑/手机与 Pi Gateway 网关配对 +- [Linux 指南](/zh-CN/platforms/linux) — 通用 Linux 设置 +- [DigitalOcean 指南](/zh-CN/install/digitalocean) — 云端替代方案 +- [Hetzner](/zh-CN/install/hetzner) — Docker 设置 +- [Tailscale](/zh-CN/gateway/tailscale) — 远程访问 +- [Nodes](/zh-CN/nodes) — 将你的笔记本电脑/手机与 Pi Gateway 网关配对 diff --git a/docs/zh-CN/plugins/building-plugins.md b/docs/zh-CN/plugins/building-plugins.md index 3f2fc1444..4955aad0b 100644 --- a/docs/zh-CN/plugins/building-plugins.md +++ b/docs/zh-CN/plugins/building-plugins.md @@ -1,41 +1,35 @@ --- read_when: - 你想创建一个新的 OpenClaw 插件 - - 你需要一个插件开发的快速开始指南 - - 你正在为 OpenClaw 添加新的渠道、提供商、工具或其他能力 + - 你需要一个插件开发快速开始指南 + - 你正在向 OpenClaw 添加新的渠道、提供商、工具或其他能力 sidebarTitle: Getting Started -summary: 在几分钟内创建你的第一个 OpenClaw 插件 +summary: 几分钟内创建你的第一个 OpenClaw 插件 title: 构建插件 x-i18n: - generated_at: "2026-04-25T00:41:40Z" + generated_at: "2026-04-27T07:12:36Z" model: gpt-5.4 provider: openai - source_hash: 69c7ffb65750fd0c1fa786600c55a371dace790b8b1034fa42f4b80f5f7146df + source_hash: 11c92fe91a4365e5774c0da9e70991a119217c517cd419a7f1307b50dea53378 source_path: plugins/building-plugins.md workflow: 15 --- -插件可为 OpenClaw 扩展新能力：渠道、模型提供商、 -语音、实时转录、实时语音、媒体理解、图像生成、 -视频生成、网页抓取、网页搜索、智能体工具，或这些能力的任意 -组合。 +插件可为 OpenClaw 扩展新能力：渠道、模型 provider、语音、实时转写、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索、智能体工具，或这些能力的任意组合。 -你不需要将插件添加到 OpenClaw 仓库。可发布到 -[ClawHub](/zh-CN/tools/clawhub) 或 npm，用户可通过 -`openclaw plugins install ` 安装。 -OpenClaw 会先尝试 ClawHub，并自动回退到 npm。 +你不需要将插件添加到 OpenClaw 仓库中。发布到 [ClawHub](/zh-CN/tools/clawhub) 或 npm，然后用户使用 `openclaw plugins install ` 安装即可。OpenClaw 会先尝试 ClawHub，再自动回退到 npm。 -## 前提条件 +## 前置条件 -- Node >= 22 和一个包管理器（npm 或 pnpm） +- Node >= 22，以及一个包管理器（npm 或 pnpm） - 熟悉 TypeScript（ESM） - 对于仓库内插件：已克隆仓库并完成 `pnpm install` -## 这是哪种插件？ +## 你要构建哪种插件？ - 将 OpenClaw 连接到消息平台（Discord、IRC 等） + 将 OpenClaw 连接到某个消息平台（Discord、IRC 等） 添加一个模型提供商（LLM、代理或自定义端点） @@ -45,17 +39,11 @@ OpenClaw 会先尝试 ClawHub，并自动回退到 npm。 -对于在新手引导 / 设置运行时不保证已安装的渠道插件， -请使用来自 -`openclaw/plugin-sdk/channel-setup` 的 `createOptionalChannelSetupSurface(...)`。 -它会生成一个设置适配器 + 向导配对， -用于告知安装要求，并在插件安装完成前， -对真实配置写入采取失败即关闭的行为。 +对于在新手引导 / 设置运行时不保证已安装的渠道插件，请使用 `openclaw/plugin-sdk/channel-setup` 中的 `createOptionalChannelSetupSurface(...)`。它会生成一个设置适配器 + 向导组合，用于提示安装要求，并在插件安装前对真实配置写入采取封闭失败策略。 ## 快速开始：工具插件 -本演练会创建一个注册智能体工具的最小插件。渠道 -和提供商插件请参见上方链接的专门指南。 +本演练将创建一个注册智能体工具的最小插件。渠道插件和提供商插件请参阅上方链接的专门指南。 @@ -83,7 +71,7 @@ OpenClaw 会先尝试 ClawHub，并自动回退到 npm。 { "id": "my-plugin", "name": "My Plugin", - "description": "为 OpenClaw 添加一个自定义工具", + "description": "Adds a custom tool to OpenClaw", "configSchema": { "type": "object", "additionalProperties": false @@ -92,10 +80,7 @@ OpenClaw 会先尝试 ClawHub，并自动回退到 npm。 ``` - 每个插件都需要一个清单，即使没有配置也一样。完整 - schema 请参见 - [清单](/zh-CN/plugins/manifest)。规范的 ClawHub - 发布片段位于 `docs/snippets/plugin-publish/`。 + 每个插件都需要一个清单，即使没有配置也是如此。完整 schema 请参阅 [Manifest](/zh-CN/plugins/manifest)。标准的 ClawHub 发布片段位于 `docs/snippets/plugin-publish/`。 @@ -123,9 +108,7 @@ OpenClaw 会先尝试 ClawHub，并自动回退到 npm。 }); ``` - `definePluginEntry` 用于非渠道插件。对于渠道，请使用 - `defineChannelPluginEntry` —— 参见 [渠道插件](/zh-CN/plugins/sdk-channel-plugins)。 - 完整的入口点选项请参见 [入口点](/zh-CN/plugins/sdk-entrypoints)。 + `definePluginEntry` 用于非渠道插件。对于渠道，请使用 `defineChannelPluginEntry` —— 参见 [Channel Plugins](/zh-CN/plugins/sdk-channel-plugins)。完整入口点选项请参阅 [Entry Points](/zh-CN/plugins/sdk-entrypoints)。 @@ -139,10 +122,9 @@ OpenClaw 会先尝试 ClawHub，并自动回退到 npm。 openclaw plugins install clawhub:@myorg/openclaw-my-plugin ``` - 对于像 - `@myorg/openclaw-my-plugin` 这样的裸包说明符，OpenClaw 也会在 npm 之前先检查 ClawHub。 + 对于像 `@myorg/openclaw-my-plugin` 这样的裸包说明符，OpenClaw 也会在 npm 之前先检查 ClawHub。 - **仓库内插件：** 放置到内置插件工作区树下 —— 会自动发现。 + **仓库内插件：** 放到内置插件工作区树下 —— 会被自动发现。 ```bash pnpm test -- /my-plugin/ @@ -157,68 +139,57 @@ OpenClaw 会先尝试 ClawHub，并自动回退到 npm。 | 能力 | 注册方法 | 详细指南 | | ---------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- | -| 文本推理（LLM） | `api.registerProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins) | -| CLI 推理后端 | `api.registerCliBackend(...)` | [CLI 后端](/zh-CN/gateway/cli-backends) | -| 渠道 / 消息 | `api.registerChannel(...)` | [渠道插件](/zh-CN/plugins/sdk-channel-plugins) | -| 语音（TTS / STT） | `api.registerSpeechProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| 实时转录 | `api.registerRealtimeTranscriptionProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| 实时语音 | `api.registerRealtimeVoiceProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| 媒体理解 | `api.registerMediaUnderstandingProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| 图像生成 | `api.registerImageGenerationProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| 音乐生成 | `api.registerMusicGenerationProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| 视频生成 | `api.registerVideoGenerationProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| 网页抓取 | `api.registerWebFetchProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| 网页搜索 | `api.registerWebSearchProvider(...)` | [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| 文本推理（LLM） | `api.registerProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins) | +| CLI 推理后端 | `api.registerCliBackend(...)` | [CLI Backends](/zh-CN/gateway/cli-backends) | +| 渠道 / 消息 | `api.registerChannel(...)` | [Channel Plugins](/zh-CN/plugins/sdk-channel-plugins) | +| 语音（TTS / STT） | `api.registerSpeechProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| 实时转写 | `api.registerRealtimeTranscriptionProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| 实时语音 | `api.registerRealtimeVoiceProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| 媒体理解 | `api.registerMediaUnderstandingProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| 图像生成 | `api.registerImageGenerationProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| 音乐生成 | `api.registerMusicGenerationProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| 视频生成 | `api.registerVideoGenerationProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| 网页抓取 | `api.registerWebFetchProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| 网页搜索 | `api.registerWebSearchProvider(...)` | [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | | 工具结果中间件 | `api.registerAgentToolResultMiddleware(...)` | [SDK 概览](/zh-CN/plugins/sdk-overview#registration-api) | -| 智能体工具 | `api.registerTool(...)` | 见下文 | +| 智能体工具 | `api.registerTool(...)` | 下文 | | 自定义命令 | `api.registerCommand(...)` | [入口点](/zh-CN/plugins/sdk-entrypoints) | | 插件钩子 | `api.on(...)` | [插件钩子](/zh-CN/plugins/hooks) | | 内部事件钩子 | `api.registerHook(...)` | [入口点](/zh-CN/plugins/sdk-entrypoints) | | HTTP 路由 | `api.registerHttpRoute(...)` | [内部机制](/zh-CN/plugins/architecture-internals#gateway-http-routes) | | CLI 子命令 | `api.registerCli(...)` | [入口点](/zh-CN/plugins/sdk-entrypoints) | -完整注册 API 请参见 [SDK 概览](/zh-CN/plugins/sdk-overview#registration-api)。 +完整注册 API 请参阅 [插件 SDK 概览](/zh-CN/plugins/sdk-overview#registration-api)。 -内置插件在需要在模型看到输出之前进行异步工具结果重写时， -可以使用 `api.registerAgentToolResultMiddleware(...)`。 -请在 `contracts.agentToolResultMiddleware` 中声明目标运行时，例如 -`["pi", "codex"]`。这是一个面向可信内置插件的扩展点；外部 -插件应优先使用常规 OpenClaw 插件钩子，除非 OpenClaw 为该能力 -引入明确的信任策略。 +内置插件在需要模型看到输出前对工具结果进行异步重写时，可以使用 `api.registerAgentToolResultMiddleware(...)`。请在 `contracts.agentToolResultMiddleware` 中声明目标运行时，例如 `["pi", "codex"]`。这是一个可信的内置插件扩展接口；外部插件应优先使用常规 OpenClaw 插件钩子，除非 OpenClaw 后续为这一能力提供明确的信任策略。 -如果你的插件注册了自定义 Gateway 网关 RPC 方法，请将它们保持在 -插件专属前缀下。核心管理命名空间（`config.*`、 -`exec.approvals.*`、`wizard.*`、`update.*`）仍然保留，并始终解析为 -`operator.admin`，即使插件请求了更窄的作用域也是如此。 +如果你的插件注册了自定义 Gateway 网关 RPC 方法，请将它们放在插件专属前缀下。核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保留，并且总是解析到 `operator.admin`，即使插件请求了更窄的作用域也是如此。 -需要注意的钩子保护语义： +需要记住的钩子守卫语义： -- `before_tool_call`：`{ block: true }` 是终止性结果，并会阻止较低优先级处理器。 -- `before_tool_call`：`{ block: false }` 被视为未作出决定。 -- `before_tool_call`：`{ requireApproval: true }` 会暂停智能体执行，并通过 exec 审批覆盖层、Telegram 按钮、Discord 交互，或任意渠道上的 `/approve` 命令提示用户审批。 -- `before_install`：`{ block: true }` 是终止性结果，并会阻止较低优先级处理器。 -- `before_install`：`{ block: false }` 被视为未作出决定。 -- `message_sending`：`{ cancel: true }` 是终止性结果，并会阻止较低优先级处理器。 -- `message_sending`：`{ cancel: false }` 被视为未作出决定。 -- `message_received`：当你需要入站线程 / 话题路由时，优先使用类型化的 `threadId` 字段。`metadata` 保留给渠道专属附加信息。 -- `message_sending`：优先使用类型化的 `replyToId` / `threadId` 路由字段，而不是渠道专属 metadata 键。 +- `before_tool_call`：`{ block: true }` 是终止性的，会阻止更低优先级的处理器继续执行。 +- `before_tool_call`：`{ block: false }` 会被视为未做决定。 +- `before_tool_call`：`{ requireApproval: true }` 会暂停智能体执行，并通过 exec 审批覆盖层、Telegram 按钮、Discord 交互，或任意渠道上的 `/approve` 命令提示用户批准。 +- `before_install`：`{ block: true }` 是终止性的，会阻止更低优先级的处理器继续执行。 +- `before_install`：`{ block: false }` 会被视为未做决定。 +- `message_sending`：`{ cancel: true }` 是终止性的，会阻止更低优先级的处理器继续执行。 +- `message_sending`：`{ cancel: false }` 会被视为未做决定。 +- `message_received`：当你需要入站线程 / 话题路由时，优先使用有类型的 `threadId` 字段。`metadata` 应保留给渠道特定的附加信息。 +- `message_sending`：优先使用有类型的 `replyToId` / `threadId` 路由字段，而不是渠道特定的 metadata 键。 -`/approve` 命令同时处理 exec 和插件审批，并带有有界回退：当找不到 exec 审批 id 时，OpenClaw 会用相同 id 重新通过插件审批进行尝试。插件审批转发可以通过配置中的 `approvals.plugin` 独立配置。 +`/approve` 命令同时处理 exec 和插件审批，并带有有界回退：当找不到 exec 审批 id 时，OpenClaw 会使用同一个 id 重试插件审批。可通过配置中的 `approvals.plugin` 独立配置插件审批转发。 -如果自定义审批流程需要检测同样的有界回退情况， -请优先使用来自 `openclaw/plugin-sdk/error-runtime` -的 `isApprovalNotFoundError`，而不是手动匹配审批过期字符串。 +如果自定义审批逻辑需要检测这种相同的有界回退场景，请优先使用 `openclaw/plugin-sdk/error-runtime` 中的 `isApprovalNotFoundError`，而不是手动匹配审批过期字符串。 -示例和钩子参考请参见 [插件钩子](/zh-CN/plugins/hooks)。 +示例和钩子参考请参阅 [插件钩子](/zh-CN/plugins/hooks)。 ## 注册智能体工具 -工具是 LLM 可调用的类型化函数。它们可以是必需的（始终 -可用），也可以是可选的（用户选择启用）： +工具是 LLM 可调用的强类型函数。它们可以是必需的（始终可用）或可选的（由用户选择启用）： ```typescript register(api) { - // 必需工具 —— 始终可用 + // Required tool — always available api.registerTool({ name: "my_tool", description: "Do a thing", @@ -228,7 +199,7 @@ register(api) { }, }); - // 可选工具 —— 用户必须添加到允许列表 + // Optional tool — user must add to allowlist api.registerTool( { name: "workflow_tool", @@ -252,7 +223,7 @@ register(api) { ``` - 工具名称不得与核心工具冲突（冲突项会被跳过） -- 对于有副作用或需要额外二进制依赖的工具，请使用 `optional: true` +- 对于具有副作用或需要额外二进制依赖的工具，请使用 `optional: true` - 用户可以通过将插件 id 添加到 `tools.allow` 来启用某个插件的全部工具 ## 导入约定 @@ -263,29 +234,23 @@ register(api) { import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; -// 错误：单体根路径（已弃用，将被移除） +// Wrong: monolithic root (deprecated, will be removed) import { ... } from "openclaw/plugin-sdk"; ``` -完整子路径参考请参见 [SDK 概览](/zh-CN/plugins/sdk-overview)。 +完整子路径参考请参阅 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。 -在你的插件内部，请使用本地 barrel 文件（`api.ts`、`runtime-api.ts`）进行 -内部导入 —— 绝不要通过其 SDK 路径导入你自己的插件。 +在你的插件内部，请使用本地 barrel 文件（`api.ts`、`runtime-api.ts`）进行内部导入 —— 不要通过它自己的 SDK 路径导入你自己的插件。 -对于提供商插件，请将提供商专属辅助工具保留在这些包根 -barrel 中，除非该扩展点确实是通用的。当前内置示例： +对于 provider 插件，请将 provider 专用辅助函数保留在这些包根级 barrel 中，除非该扩展接口确实是通用的。当前内置示例： -- Anthropic：Claude 流包装器以及 `service_tier` / beta 辅助工具 -- OpenAI：提供商构建器、默认模型辅助工具、实时提供商 -- OpenRouter：提供商构建器以及新手引导 / 配置辅助工具 +- Anthropic：Claude 流封装，以及 `service_tier` / beta 辅助函数 +- OpenAI：provider 构建器、默认模型辅助函数、实时 provider +- OpenRouter：provider 构建器，以及新手引导 / 配置辅助函数 -如果某个辅助工具只在一个内置提供商包内部有用，请将它保留在该 -包根扩展点上，而不是将其提升到 `openclaw/plugin-sdk/*` 中。 +如果某个辅助函数只在一个内置 provider 包内部有用，请将它保留在该包根级扩展接口上，而不是将其提升到 `openclaw/plugin-sdk/*` 中。 -一些生成的 `openclaw/plugin-sdk/` 辅助扩展点仍然存在， -用于内置插件维护和兼容性，例如 -`plugin-sdk/feishu-setup` 或 `plugin-sdk/zalo-setup`。请将这些视为保留 -接口，而不是新第三方插件的默认模式。 +某些生成的 `openclaw/plugin-sdk/` 辅助扩展接口仍然存在，用于内置插件维护和兼容性，例如 `plugin-sdk/feishu-setup` 或 `plugin-sdk/zalo-setup`。请将这些视为保留接口，而不是新第三方插件的默认模式。 ## 提交前检查清单 @@ -297,28 +262,28 @@ barrel 中，除非该扩展点确实是通用的。当前内置示例： 测试通过（`pnpm test -- /my-plugin/`） `pnpm check` 通过（仓库内插件） -## Beta 版本测试 +## beta 发布测试 -1. 关注 [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) 上的 GitHub 发布标签，并通过 `Watch` > `Releases` 订阅。Beta 标签类似 `v2026.3.N-beta.1`。你也可以为官方 OpenClaw X 账号 [@openclaw](https://x.com/openclaw) 开启通知，以获取发布公告。 -2. Beta 标签一出现，就尽快使用它测试你的插件。稳定版发布前的窗口通常只有几个小时。 -3. 测试后，在 `plugin-forum` Discord 渠道中你插件对应的讨论串里发布 `all good` 或说明出了什么问题。如果你还没有讨论串，请创建一个。 -4. 如果出现问题，请创建或更新一个标题为 `Beta blocker: - ` 的 issue，并添加 `beta-blocker` 标签。将该 issue 链接放到你的讨论串中。 -5. 向 `main` 提交一个标题为 `fix(): beta blocker - ` 的 PR，并在 PR 和你的 Discord 讨论串中都链接该 issue。贡献者无法给 PR 添加标签，因此标题是提供给维护者和自动化系统的 PR 侧信号。有 PR 的阻塞问题会被合并；没有 PR 的阻塞问题也可能照常发布。维护者会在 beta 测试期间关注这些讨论串。 -6. 没有消息就表示一切正常。如果你错过了这个窗口，你的修复很可能会在下一个周期落地。 +1. 关注 [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) 上的 GitHub 发布标签，并通过 `Watch` > `Releases` 订阅。beta 标签通常类似 `v2026.3.N-beta.1`。你也可以为 OpenClaw 官方 X 账号 [@openclaw](https://x.com/openclaw) 开启通知，以获取发布公告。 +2. beta 标签一出现，就尽快针对该 beta 标签测试你的插件。稳定版发布前的窗口期通常只有几个小时。 +3. 测试完成后，在 Discord 频道 `plugin-forum` 中你插件对应的话题里发帖，说明是 `all good` 还是哪里出了问题。如果你还没有话题，就创建一个。 +4. 如果有问题，请新建或更新一个标题为 `Beta blocker: - ` 的 issue，并添加 `beta-blocker` 标签。将该 issue 链接发到你的话题中。 +5. 向 `main` 提交一个标题为 `fix(): beta blocker - ` 的 PR，并在 PR 和你的 Discord 话题中都链接该 issue。贡献者不能给 PR 打标签，因此标题就是给维护者和自动化流程的 PR 侧信号。有 PR 的阻塞问题会被合并；没有 PR 的阻塞问题也可能仍然随版本发布。维护者会在 beta 测试期间关注这些话题。 +6. 没有消息就表示一切正常。如果你错过了窗口期，你的修复很可能会在下一个周期落地。 ## 后续步骤 - 构建一个消息渠道插件 + 构建消息渠道插件 - 构建一个模型提供商插件 + 构建模型提供商插件 - + 导入映射和注册 API 参考 - + 通过 api.runtime 使用 TTS、搜索、子智能体 @@ -331,8 +296,8 @@ barrel 中，除非该扩展点确实是通用的。当前内置示例： ## 相关内容 -- [插件架构](/zh-CN/plugins/architecture) — 内部架构深入解析 -- [SDK 概览](/zh-CN/plugins/sdk-overview) — 插件 SDK 参考 -- [清单](/zh-CN/plugins/manifest) — 插件清单格式 +- [插件架构](/zh-CN/plugins/architecture) — 内部架构深度解析 +- [插件 SDK 概览](/zh-CN/plugins/sdk-overview) — 插件 SDK 参考 +- [Manifest](/zh-CN/plugins/manifest) — 插件清单格式 - [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件 - [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建提供商插件 diff --git a/docs/zh-CN/plugins/codex-harness.md b/docs/zh-CN/plugins/codex-harness.md index 027b18ffc..c03644e7b 100644 --- a/docs/zh-CN/plugins/codex-harness.md +++ b/docs/zh-CN/plugins/codex-harness.md @@ -2,163 +2,146 @@ read_when: - 你想使用内置的 Codex app-server harness - 你需要 Codex harness 配置示例 - - 你希望仅使用 Codex 的部署在无法使用时直接失败，而不是回退到 Pi -summary: 通过内置的 Codex app-server harness 运行 OpenClaw 嵌入式智能体轮次 + - 你希望仅使用 Codex 的部署在无法使用时直接失败，而不是回退到 PI +summary: 通过内置的 Codex app-server harness 运行 OpenClaw 内嵌智能体轮次 title: Codex harness x-i18n: - generated_at: "2026-04-26T20:28:02Z" + generated_at: "2026-04-27T07:12:49Z" model: gpt-5.4 provider: openai - source_hash: 57c0d66c3ce0cdb26ffd2e6637c1494908c563f4c9750b20a9b33b6bc7810e1b + source_hash: 8176ab6de65bf3a1167b4816a5f0f6400c66bd9716da91a5e14038d3a852886c source_path: plugins/codex-harness.md workflow: 15 --- -内置的 `codex` 插件可让 OpenClaw 通过 Codex app-server，而不是内置的 Pi harness，运行嵌入式智能体轮次。 +内置的 `codex` 插件让 OpenClaw 可以通过 Codex app-server 运行内嵌智能体轮次，而不是使用内置的 PI harness。 -当你希望 Codex 接管底层智能体会话时，可使用此功能：模型发现、原生线程恢复、原生压缩，以及 app-server 执行。OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、审批、媒体传递，以及可见的转录镜像。 +当你希望由 Codex 接管底层智能体会话时，请使用它：模型发现、原生线程恢复、原生压缩，以及 app-server 执行。OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、批准、媒体投递以及可见的转录镜像。 -如果你正在梳理整体结构，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。简短来说： -`openai/gpt-5.5` 是模型引用，`codex` 是运行时，而 Telegram、Discord、Slack 或其他渠道仍然是通信界面。 +如果你正在熟悉相关概念，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。简短来说： +`openai/gpt-5.5` 是模型引用，`codex` 是运行时，而 Telegram、 +Discord、Slack 或其他渠道仍然是通信界面。 ## 这个插件会改变什么 内置的 `codex` 插件提供了几项彼此独立的能力： -| 能力 | 使用方式 | 作用 | -| --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- | -| 原生嵌入式运行时 | `agentRuntime.id: "codex"` | 通过 Codex app-server 运行 OpenClaw 嵌入式智能体轮次。 | -| 原生聊天控制命令 | `/codex bind`, `/codex resume`, `/codex steer`, ... | 从消息会话中绑定并控制 Codex app-server 线程。 | -| Codex app-server 提供商/目录 | `codex` 内部机制，通过 harness 暴露 | 让运行时发现并校验 app-server 模型。 | -| Codex 媒体理解路径 | `codex/*` 图像模型兼容路径 | 为受支持的图像理解模型运行受限的 Codex app-server 轮次。 | -| 原生钩子转发 | 围绕 Codex 原生命令事件的插件钩子 | 让 OpenClaw 观察/阻止受支持的 Codex 原生工具/终结事件。 | +| 能力 | 你的使用方式 | 它的作用 | +| --- | --- | --- | +| 原生内嵌运行时 | `agentRuntime.id: "codex"` | 通过 Codex app-server 运行 OpenClaw 内嵌智能体轮次。 | +| 原生聊天控制命令 | `/codex bind`、`/codex resume`、`/codex steer`、... | 在消息会话中绑定并控制 Codex app-server 线程。 | +| Codex app-server 提供商/目录 | `codex` 内部机制，通过 harness 暴露 | 让运行时可以发现并验证 app-server 模型。 | +| Codex 媒体理解路径 | `codex/*` 图像模型兼容路径 | 为受支持的图像理解模型运行受限的 Codex app-server 轮次。 | +| 原生钩子中继 | 围绕 Codex 原生事件的插件钩子 | 让 OpenClaw 可以观察/阻止受支持的 Codex 原生工具/终结事件。 | -启用该插件会让这些能力可用。它**不会**： +启用该插件会使这些能力可用。它**不会**： - 为每个 OpenAI 模型都开始使用 Codex - 将 `openai-codex/*` 模型引用转换为原生运行时 - 让 ACP/acpx 成为默认的 Codex 路径 -- 热切换那些已经记录了 Pi 运行时的现有会话 +- 对已经记录了 PI 运行时的现有会话进行热切换 - 替换 OpenClaw 的渠道投递、会话文件、auth-profile 存储或消息路由 -同一个插件也负责原生 `/codex` 聊天控制命令界面。如果 -插件已启用，且用户要求从聊天中绑定、恢复、引导、停止或检查 -Codex 线程，智能体应优先使用 `/codex ...`，而不是 ACP。当用户明确要求 ACP/acpx，或正在测试 ACP -Codex 适配器时，ACP 仍然是显式回退选项。 +同一个插件也负责原生 `/codex` 聊天控制命令界面。如果插件已启用，并且用户要求从聊天中绑定、恢复、引导、停止或检查 Codex 线程，智能体应优先使用 `/codex ...`，而不是 ACP。当用户明确要求 ACP/acpx，或正在测试 ACP Codex 适配器时，ACP 仍然是显式回退方案。 -原生 Codex 轮次仍然将 OpenClaw 插件钩子作为公共兼容层。 -这些是 OpenClaw 进程内钩子，而不是 Codex `hooks.json` 命令钩子： +原生 Codex 轮次保留 OpenClaw 插件钩子作为公共兼容层。这些是进程内的 OpenClaw 钩子，而不是 Codex `hooks.json` 命令钩子： - `before_prompt_build` -- `before_compaction`, `after_compaction` -- `llm_input`, `llm_output` -- `before_tool_call`, `after_tool_call` -- `before_message_write`，用于镜像的转录记录 -- 通过 Codex `Stop` 转发的 `before_agent_finalize` +- `before_compaction`、`after_compaction` +- `llm_input`、`llm_output` +- `before_tool_call`、`after_tool_call` +- 用于镜像转录记录的 `before_message_write` +- 通过 Codex `Stop` 中继的 `before_agent_finalize` - `agent_end` -插件也可以注册与运行时无关的工具结果中间件，在 OpenClaw 执行工具之后、结果返回给 Codex 之前，重写 OpenClaw 动态工具结果。这与公共的 -`tool_result_persist` 插件钩子是分开的；后者会转换由 OpenClaw 管理的转录工具结果写入。 +插件也可以注册运行时中立的工具结果中间件，在 OpenClaw 执行工具之后、结果返回给 Codex 之前重写 OpenClaw 的动态工具结果。这与公共 `tool_result_persist` 插件钩子不同，后者会转换由 OpenClaw 持有的转录工具结果写入。 -有关插件钩子语义本身，请参阅 [Plugin hooks](/zh-CN/plugins/hooks) +关于插件钩子语义本身，请参阅 [Plugin hooks](/zh-CN/plugins/hooks) 和 [Plugin guard behavior](/zh-CN/tools/plugin)。 -该 harness 默认关闭。新配置应保持 OpenAI 模型引用 -使用规范形式 `openai/gpt-*`，并在需要原生 app-server 执行时，显式强制设置 -`agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。旧版 `codex/*` 模型引用出于兼容性仍会自动选择该 harness，但由运行时支持的旧版提供商前缀不会作为常规模型/提供商选项显示。 +该 harness 默认关闭。新配置应保持 OpenAI 模型引用的规范形式为 `openai/gpt-*`，并在需要原生 app-server 执行时显式强制设置 +`agentRuntime.id: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。为兼容性起见，旧版 `codex/*` 模型引用仍会自动选择该 harness，但由运行时支持的旧版 provider 前缀不会作为普通模型/提供商选项显示。 -如果已启用 `codex` 插件，但主模型仍然是 -`openai-codex/*`，`openclaw doctor` 会发出警告，而不是修改路由。这是有意为之：`openai-codex/*` 仍然是 Pi Codex OAuth/订阅路径，而原生 app-server 执行仍然是一个显式运行时选择。 +如果已启用 `codex` 插件，但主模型仍是 +`openai-codex/*`，`openclaw doctor` 会给出警告，而不是修改路由。这是有意为之：`openai-codex/*` 仍然是 PI Codex OAuth/订阅路径，而原生 app-server 执行始终是显式的运行时选择。 ## 路由映射 -在更改配置之前，请先查看此表： +在修改配置前，请先使用此表： -| 期望行为 | 模型引用 | 运行时配置 | 插件要求 | 预期 Status 标签 | -| ----------------------------------------- | -------------------------- | -------------------------------------- | --------------------------- | ------------------------------ | -| 通过普通 OpenClaw 运行器使用 OpenAI API | `openai/gpt-*` | 省略或 `runtime: "pi"` | OpenAI provider | `Runtime: OpenClaw Pi Default` | -| 通过 Pi 使用 Codex OAuth/订阅 | `openai-codex/gpt-*` | 省略或 `runtime: "pi"` | OpenAI Codex OAuth provider | `Runtime: OpenClaw Pi Default` | -| 原生 Codex app-server 嵌入式轮次 | `openai/gpt-*` | `agentRuntime.id: "codex"` | `codex` 插件 | `Runtime: OpenAI Codex` | -| 使用保守自动模式的混合提供商 | 提供商特定引用 | `agentRuntime.id: "auto"` | 可选插件运行时 | 取决于所选运行时 | -| 显式 Codex ACP 适配器会话 | 取决于 ACP 提示词/模型 | `sessions_spawn` 配合 `runtime: "acp"` | 健康的 `acpx` 后端 | ACP 任务/会话状态 | +| 期望行为 | 模型引用 | 运行时配置 | 插件要求 | 预期状态标签 | +| --- | --- | --- | --- | --- | +| 通过常规 OpenClaw 运行器使用 OpenAI API | `openai/gpt-*` | 省略或 `runtime: "pi"` | OpenAI provider | `Runtime: OpenClaw Pi Default` | +| 通过 PI 使用 Codex OAuth/订阅 | `openai-codex/gpt-*` | 省略或 `runtime: "pi"` | OpenAI Codex OAuth provider | `Runtime: OpenClaw Pi Default` | +| 原生 Codex app-server 内嵌轮次 | `openai/gpt-*` | `agentRuntime.id: "codex"` | `codex` 插件 | `Runtime: OpenAI Codex` | +| 使用保守自动模式的混合提供商 | provider 特定引用 | `agentRuntime.id: "auto"` | 可选插件运行时 | 取决于选定运行时 | +| 显式 Codex ACP 适配器会话 | ACP prompt/model 依赖 | `sessions_spawn` 搭配 `runtime: "acp"` | 健康的 `acpx` 后端 | ACP 任务/会话状态 | -这里的重要区分是提供商与运行时： +重要的划分在于 provider 与运行时： -- `openai-codex/*` 回答的是“Pi 应该使用哪条提供商/认证路径？” -- `agentRuntime.id: "codex"` 回答的是“哪个循环应执行这个 - 嵌入式轮次？” -- `/codex ...` 回答的是“这个聊天应该绑定或控制哪个原生 Codex 会话？” -- ACP 回答的是“acpx 应启动哪个外部 harness 进程？” +- `openai-codex/*` 回答的是“PI 应该使用哪条 provider/auth 路径？” +- `agentRuntime.id: "codex"` 回答的是“哪一个循环应执行这个内嵌轮次？” +- `/codex ...` 回答的是“这段聊天应绑定或控制哪一个原生 Codex 会话？” +- ACP 回答的是“acpx 应启动哪一个外部 harness 进程？” ## 选择正确的模型前缀 -OpenAI 系列路由依赖具体前缀。想通过 Pi 使用 Codex OAuth 时，请用 `openai-codex/*`；想直接使用 OpenAI API，或 -想强制使用原生 Codex app-server harness 时，请用 `openai/*`： +OpenAI 家族路由依赖前缀。需要通过 PI 使用 Codex OAuth 时，请使用 `openai-codex/*`；需要直接使用 OpenAI API，或强制使用原生 Codex app-server harness 时，请使用 `openai/*`： -| 模型引用 | 运行时路径 | 适用场景 | -| --------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------- | -| `openai/gpt-5.4` | 通过 OpenClaw/Pi 管道的 OpenAI provider | 你希望通过 `OPENAI_API_KEY` 使用当前的 OpenAI Platform API 直接访问。 | -| `openai-codex/gpt-5.5` | 通过 OpenClaw/Pi 的 OpenAI Codex OAuth | 你希望在默认 Pi 运行器中使用 ChatGPT/Codex 订阅认证。 | -| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Codex app-server harness | 你希望对嵌入式智能体轮次使用原生 Codex app-server 执行。 | +| 模型引用 | 运行时路径 | 适用场景 | +| --- | --- | --- | +| `openai/gpt-5.4` | 通过 OpenClaw/PI 管线的 OpenAI provider | 你希望通过 `OPENAI_API_KEY` 使用当前的 OpenAI Platform API 直接访问。 | +| `openai-codex/gpt-5.5` | 通过 OpenClaw/PI 的 OpenAI Codex OAuth | 你希望通过默认 PI 运行器使用 ChatGPT/Codex 订阅认证。 | +| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Codex app-server harness | 你希望对内嵌智能体轮次使用原生 Codex app-server 执行。 | -GPT-5.5 当前在 OpenClaw 中仅支持订阅/OAuth。Pi OAuth 请使用 -`openai-codex/gpt-5.5`，或将 `openai/gpt-5.5` 与 Codex -app-server harness 搭配使用。一旦 OpenAI 在公共 API 上启用 GPT-5.5， -就会支持通过 API key 直接访问 `openai/gpt-5.5`。 +GPT-5.5 目前在 OpenClaw 中仅支持订阅/OAuth。PI OAuth 请使用 +`openai-codex/gpt-5.5`，或者将 `openai/gpt-5.5` 与 Codex +app-server harness 搭配使用。一旦 OpenAI 在公共 API 上启用 GPT-5.5，就支持对 `openai/gpt-5.5` 使用直接 API key 访问。 -旧版 `codex/gpt-*` 引用仍然接受为兼容别名。Doctor -兼容性迁移会将旧版主运行时引用重写为规范模型引用，并单独记录运行时策略，而仅用作回退的旧版引用则保持不变，因为运行时是为整个智能体容器配置的。新的 Pi Codex OAuth 配置应使用 `openai-codex/gpt-*`；新的原生 -app-server harness 配置应使用 `openai/gpt-*`，并配合 +旧版 `codex/gpt-*` 引用仍作为兼容别名被接受。Doctor 兼容迁移会将旧版主运行时引用重写为规范模型引用，并单独记录运行时策略；而仅用于回退的旧版引用保持不变，因为运行时是针对整个智能体容器配置的。新的 PI Codex OAuth 配置应使用 `openai-codex/gpt-*`；新的原生 app-server harness 配置应使用 `openai/gpt-*` 并配合 `agentRuntime.id: "codex"`。 -`agents.defaults.imageModel` 遵循同样的前缀划分。若图像理解应通过 OpenAI -Codex OAuth provider 路径运行，请使用 `openai-codex/gpt-*`。若图像理解应通过受限的 Codex app-server 轮次运行，请使用 -`codex/gpt-*`。Codex app-server 模型必须声明支持图像输入；纯文本 Codex 模型会在媒体轮次开始前失败。 +`agents.defaults.imageModel` 也遵循相同的前缀划分。当图像理解应通过 OpenAI Codex OAuth provider 路径运行时，请使用 +`openai-codex/gpt-*`。当图像理解应通过受限的 Codex app-server 轮次运行时，请使用 `codex/gpt-*`。Codex app-server 模型必须声明支持图像输入；纯文本 Codex 模型会在媒体轮次开始之前失败。 -使用 `/status` 确认当前会话实际使用的 harness。如果结果出乎意料，请为 `agents/harness` 子系统启用调试日志，并检查 Gateway 网关结构化的 `agent harness selected` 记录。它包含所选 harness id、选择原因、运行时/回退策略，以及在 `auto` 模式下每个插件候选项的支持结果。 +使用 `/status` 确认当前会话的生效 harness。如果选择结果出乎意料，请为 `agents/harness` 子系统启用调试日志，并检查 gateway 的结构化 `agent harness selected` 记录。它包含所选 harness id、选择原因、运行时/回退策略，以及在 `auto` 模式下每个插件候选项的支持结果。 -### doctor 警告是什么意思 +### Doctor 警告的含义 当以下条件全部为真时，`openclaw doctor` 会发出警告： -- 内置的 `codex` 插件已启用或被允许 +- 内置 `codex` 插件已启用或被允许 - 某个智能体的主模型是 `openai-codex/*` -- 该智能体的实际运行时不是 `codex` +- 该智能体的生效运行时不是 `codex` -之所以有这个警告，是因为用户通常会以为“已启用 Codex 插件”意味着 -“原生 Codex app-server 运行时”。OpenClaw 不会自动做出这个跳转。这个警告的含义是： +之所以发出这个警告，是因为用户经常会认为“已启用 Codex 插件”意味着“使用原生 Codex app-server 运行时”。OpenClaw 不会自动做出这种跳转。该警告的含义是： -- 如果你本来就打算通过 Pi 使用 ChatGPT/Codex OAuth，**则无需更改**。 -- 如果你本来打算使用原生 app-server - 执行，请将模型改为 `openai/`，并设置 +- 如果你本来就打算通过 PI 使用 ChatGPT/Codex OAuth，**则无需更改**。 +- 如果你本来打算使用原生 app-server 执行，请把模型改为 `openai/`，并设置 `agentRuntime.id: "codex"`。 -- 运行时变更后，现有会话仍需要执行 `/new` 或 `/reset`， - 因为会话运行时固定是粘性的。 +- 运行时变更后，现有会话仍然需要执行 `/new` 或 `/reset`， + 因为会话运行时绑定具有粘性。 -Harness 选择不是实时会话控制。当嵌入式轮次运行时， -OpenClaw 会在该会话上记录所选 harness id，并在同一会话 id 的后续轮次中继续使用它。当你希望未来会话使用其他 harness 时，请更改 `agentRuntime` 配置或 -`OPENCLAW_AGENT_RUNTIME`；在现有会话于 Pi 与 Codex 之间切换之前，请使用 `/new` 或 `/reset` 启动一个新会话。这可以避免让同一份转录在两个不兼容的原生会话系统之间重放。 +Harness 选择不是实时会话控制。当某个内嵌轮次运行时，OpenClaw 会在该会话上记录所选 harness id，并在同一会话 id 的后续轮次中继续使用它。当你希望未来会话使用其他 harness 时，请更改 `agentRuntime` 配置或 +`OPENCLAW_AGENT_RUNTIME`；在现有会话于 PI 与 Codex 之间切换之前，请使用 `/new` 或 `/reset` 启动新会话。这样可以避免将同一份转录在两个不兼容的原生会话系统之间重放。 -在 harness 固定功能引入之前创建的旧会话，一旦有转录历史，就会被视为固定到 Pi。更改配置后，请使用 `/new` 或 `/reset` 将该会话切换到 Codex。 +在引入 harness pin 之前创建的旧会话，一旦已有转录历史，就会被视为绑定到 PI。更改配置后，如需让该对话切换到 Codex，请使用 `/new` 或 `/reset`。 -`/status` 会显示实际模型运行时。默认的 Pi harness 显示为 -`Runtime: OpenClaw Pi Default`，而 Codex app-server harness 显示为 +`/status` 会显示生效的模型运行时。默认 PI harness 显示为 +`Runtime: OpenClaw Pi Default`，Codex app-server harness 显示为 `Runtime: OpenAI Codex`。 ## 要求 -- 已安装可用内置 `codex` 插件的 OpenClaw。 -- Codex app-server `0.125.0` 或更高版本。内置插件默认会管理兼容的 - Codex app-server 二进制文件，因此 `PATH` 上本地的 `codex` 命令 - 不会影响正常的 harness 启动。 -- app-server 进程可用的 Codex 认证信息。 +- OpenClaw，且内置 `codex` 插件可用。 +- Codex app-server `0.125.0` 或更高版本。内置插件默认会管理一个兼容的 Codex app-server 二进制文件，因此 `PATH` 中本地的 `codex` 命令不会影响正常 harness 启动。 +- app-server 进程可用的 Codex 认证。 -该插件会阻止较旧或无版本号的 app-server 握手。这可以确保 -OpenClaw 始终运行在其已测试过的协议接口上。 +该插件会阻止较旧或无版本的 app-server 握手。这可以确保 +OpenClaw 只运行在它已经测试过的协议界面上。 -对于实时与 Docker 冒烟测试，认证通常来自 `OPENAI_API_KEY`，以及可选的 Codex CLI 文件，例如 `~/.codex/auth.json` 和 -`~/.codex/config.toml`。请使用与你本地 Codex app-server -相同的认证材料。 +对于实时和 Docker 冒烟测试，认证通常来自 `OPENAI_API_KEY`，以及可选的 Codex CLI 文件，如 `~/.codex/auth.json` 和 +`~/.codex/config.toml`。请使用与你本地 Codex app-server 相同的认证材料。 ## 最小配置 @@ -184,7 +167,7 @@ OpenClaw 始终运行在其已测试过的协议接口上。 } ``` -如果你的配置使用 `plugins.allow`，也请将 `codex` 包含在其中： +如果你的配置使用 `plugins.allow`，也要将 `codex` 包含在内： ```json5 { @@ -199,24 +182,22 @@ OpenClaw 始终运行在其已测试过的协议接口上。 } ``` -如果旧配置将 `agents.defaults.model` 或某个智能体模型设置为 -`codex/`，仍会自动启用内置 `codex` 插件。新配置应优先使用 -`openai/`，并配合上面显式的 `agentRuntime` 条目。 +如果旧版配置将 `agents.defaults.model` 或某个智能体模型设置为 +`codex/`，仍会自动启用内置 `codex` 插件。新配置应优先使用 `openai/`，并配合上面的显式 `agentRuntime` 条目。 ## 将 Codex 与其他模型一起使用 -如果同一个智能体需要在 Codex 和非 Codex 提供商模型之间自由切换，请不要全局设置 `agentRuntime.id: "codex"`。强制运行时会应用到该智能体或会话的每一个嵌入式轮次。如果你在该运行时被强制启用时选择 Anthropic 模型，OpenClaw 仍会尝试使用 Codex harness，并以失败关闭，而不是悄悄通过 Pi 路由该轮次。 +如果同一个智能体应在 Codex 和非 Codex provider 模型之间自由切换，请不要全局设置 `agentRuntime.id: "codex"`。强制运行时会应用到该智能体或会话的每一个内嵌轮次。如果你在强制该运行时的情况下选择 Anthropic 模型，OpenClaw 仍会尝试 Codex harness，并以封闭失败的方式终止，而不是悄悄通过 PI 路由该轮次。 -请改用以下其中一种配置方式： +请改用以下其中一种结构： -- 将 Codex 放在一个专用智能体上，并设置 `agentRuntime.id: "codex"`。 -- 将默认智能体保持为 `agentRuntime.id: "auto"`，并为正常的混合 - 提供商使用保留 Pi 回退。 +- 将 Codex 放在专用智能体上，并设置 `agentRuntime.id: "codex"`。 +- 对于普通的混合 provider 使用，让默认智能体保持 `agentRuntime.id: "auto"` 和 PI 回退。 - 仅将旧版 `codex/*` 引用用于兼容性。新配置应优先使用 `openai/*`，并配合显式的 Codex 运行时策略。 -例如，下面的配置会让默认智能体继续使用常规自动选择，并 -额外添加一个独立的 Codex 智能体： +例如，下面的配置会让默认智能体保持普通自动选择， +并额外添加一个独立的 Codex 智能体： ```json5 { @@ -253,37 +234,35 @@ OpenClaw 始终运行在其已测试过的协议接口上。 } ``` -采用这种配置方式后： +采用这种结构时： -- 默认的 `main` 智能体使用常规提供商路径和 Pi 兼容性回退。 +- 默认的 `main` 智能体使用普通 provider 路径和 PI 兼容回退。 - `codex` 智能体使用 Codex app-server harness。 -- 如果 `codex` 智能体缺少 Codex 或当前不受支持，该轮次会直接失败， - 而不是悄悄改用 Pi。 +- 如果 `codex` 智能体缺少 Codex，或 Codex 对其不受支持，该轮次会直接失败， + 而不是悄悄改用 PI。 ## 智能体命令路由 -智能体应根据用户意图来路由请求，而不是仅凭 “Codex” 这个词： +智能体应根据用户意图路由请求，而不应仅仅因为出现了 “Codex” 这个词： -| 用户要求…… | 智能体应使用…… | -| -------------------------------------------------------- | ------------------------------------------------ | -| “将这个聊天绑定到 Codex” | `/codex bind` | -| “在这里恢复 Codex 线程 ``” | `/codex resume ` | -| “显示 Codex 线程” | `/codex threads` | -| “将 Codex 用作这个智能体的运行时” | 将配置更改为 `agentRuntime.id` | -| “用我的 ChatGPT/Codex 订阅配合普通 OpenClaw” | `openai-codex/*` 模型引用 | -| “通过 ACP/acpx 运行 Codex” | ACP `sessions_spawn({ runtime: "acp", ... })` | -| “在线程中启动 Claude Code/Gemini/OpenCode/Cursor” | ACP/acpx，而不是 `/codex`，也不是原生子智能体 | +| 用户请求的是... | 智能体应使用... | +| --- | --- | +| “将这段聊天绑定到 Codex” | `/codex bind` | +| “在这里恢复 Codex 线程 ``” | `/codex resume ` | +| “显示 Codex 线程” | `/codex threads` | +| “将 Codex 用作这个智能体的运行时” | 将 `agentRuntime.id` 改为相应配置 | +| “用我的 ChatGPT/Codex 订阅配合普通 OpenClaw” | `openai-codex/*` 模型引用 | +| “通过 ACP/acpx 运行 Codex” | ACP `sessions_spawn({ runtime: "acp", ... })` | +| “在线程中启动 Claude Code/Gemini/OpenCode/Cursor” | ACP/acpx，而不是 `/codex`，也不是原生子智能体 | -只有在 ACP 已启用、可分发，并且由已加载的运行时后端支持时， -OpenClaw 才会向智能体公布 ACP 启动指引。如果 ACP 不可用， -系统提示词和插件 Skills 不应向智能体传授 ACP -路由方式。 +只有在 ACP 已启用、可分派，并且背后有已加载的运行时后端时， +OpenClaw 才会向智能体展示 ACP 启动指南。如果 ACP 不可用， +系统提示和插件 Skills 就不应向智能体传授 ACP 路由方式。 -## 仅 Codex 部署 +## 仅使用 Codex 的部署 -当你需要证明每个嵌入式智能体轮次都 -使用 Codex 时，请强制使用 Codex harness。显式插件运行时默认不使用 Pi 回退，因此 -`fallback: "none"` 是可选的，但通常有助于作为文档说明： +当你需要证明每一个内嵌智能体轮次都使用 Codex 时，请强制使用 Codex harness。显式插件运行时默认不使用 PI 回退，因此 +`fallback: "none"` 是可选的，但通常作为文档说明很有帮助： ```json5 { @@ -299,20 +278,18 @@ OpenClaw 才会向智能体公布 ACP 启动指引。如果 ACP 不可用， } ``` -环境覆盖： +环境变量覆盖： ```bash OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run ``` -当强制使用 Codex 时，如果 Codex 插件被禁用、app-server 版本过旧，或 -app-server 无法启动，OpenClaw 会提前失败。仅当你确实希望由 Pi 处理缺失的 harness 选择时，才设置 +在强制使用 Codex 的情况下，如果 Codex 插件被禁用、app-server 版本过旧，或 app-server 无法启动，OpenClaw 会尽早失败。只有在你明确希望由 PI 处理缺失的 harness 选择时，才设置 `OPENCLAW_AGENT_HARNESS_FALLBACK=pi`。 ## 按智能体使用 Codex -你可以让某个智能体仅使用 Codex，同时让默认智能体保持正常的 -自动选择： +你可以让某一个智能体仅使用 Codex，而默认智能体保持普通自动选择： ```json5 { @@ -343,15 +320,14 @@ app-server 无法启动，OpenClaw 会提前失败。仅当你确实希望由 Pi } ``` -使用常规会话命令来切换智能体和模型。`/new` 会创建一个新的 -OpenClaw 会话，而 Codex harness 会根据需要创建或恢复其旁挂的 app-server -线程。`/reset` 会清除该线程的 OpenClaw 会话绑定， -并让下一轮再次根据当前配置解析 harness。 +使用常规会话命令切换智能体和模型。`/new` 会创建一个全新的 +OpenClaw 会话，而 Codex harness 会按需创建或恢复其 sidecar +app-server 线程。`/reset` 会清除该线程的 OpenClaw 会话绑定， +并让下一个轮次再次根据当前配置解析 harness。 ## 模型发现 -默认情况下，Codex 插件会向 app-server 请求可用模型。如果 -发现失败或超时，它会使用内置的回退目录，包含： +默认情况下，Codex 插件会向 app-server 请求可用模型。如果发现失败或超时，它会使用内置回退目录，包含： - GPT-5.5 - GPT-5.4 mini @@ -377,8 +353,7 @@ OpenClaw 会话，而 Codex harness 会根据需要创建或恢复其旁挂的 a } ``` -如果你希望启动时避免探测 Codex，并固定使用 -回退目录，可以禁用发现： +当你希望启动时避免探测 Codex，并固定使用回退目录时，请禁用发现： ```json5 { @@ -399,21 +374,19 @@ OpenClaw 会话，而 Codex harness 会根据需要创建或恢复其旁挂的 a ## App-server 连接与策略 -默认情况下，插件会在本地使用以下命令启动 OpenClaw 管理的 Codex 二进制文件： +默认情况下，插件会在本地启动 OpenClaw 管理的 Codex 二进制，并使用： ```bash codex app-server --listen stdio:// ``` -该托管二进制文件被声明为内置插件运行时依赖项，并与 -`codex` 插件的其余依赖一起分阶段部署。这样可以让 app-server 版本绑定到内置插件，而不是绑定到本地恰好安装的某个独立 Codex CLI。 -仅当你明确想运行其他可执行文件时，才设置 `appServer.command`。 +托管二进制被声明为内置插件运行时依赖，并与其他 `codex` 插件依赖一起分阶段部署。这样可以让 app-server 版本与内置插件保持绑定，而不是跟随本地恰好安装的某个独立 Codex CLI。只有当你明确希望运行其他可执行文件时，才设置 `appServer.command`。 默认情况下，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 @@ -434,12 +407,11 @@ codex app-server --listen stdio:// } ``` -Guardian 模式使用 Codex 原生的自动审核审批路径。当 Codex 请求 -离开沙箱、在工作区之外写入，或添加网络访问等权限时，Codex 会将该审批请求路由给原生审核器，而不是人类提示。审核器会应用 Codex 的风险框架，并批准或拒绝该具体请求。当你希望比 YOLO 模式有更多护栏，但又仍然需要无人值守的智能体继续推进时，请使用 Guardian。 +Guardian 模式使用 Codex 的原生自动审核批准路径。当 Codex 请求离开沙箱、写入工作区之外的位置，或添加诸如网络访问之类的权限时，Codex 会将该批准请求路由到原生审核器，而不是人工提示。审核器会应用 Codex 的风险框架，并批准或拒绝具体请求。当你希望比 YOLO 模式有更多护栏，但仍需要无人值守的智能体持续推进时，请使用 Guardian。 `guardian` 预设会展开为 `approvalPolicy: "on-request"`、 `approvalsReviewer: "auto_review"` 和 `sandbox: "workspace-write"`。 -单独的策略字段仍然会覆盖 `mode`，因此高级部署可以将该预设与显式选择混合使用。较旧的 `guardian_subagent` 审核器值仍被接受作为兼容别名，但新配置应使用 +各个策略字段仍然可以覆盖 `mode`，因此高级部署可以将该预设与显式选择混合使用。较旧的 `guardian_subagent` 审核器值仍作为兼容别名被接受，但新配置应使用 `auto_review`。 对于已经在运行的 app-server，请使用 WebSocket 传输： @@ -464,24 +436,24 @@ Guardian 模式使用 Codex 原生的自动审核审批路径。当 Codex 请求 } ``` -支持的 `appServer` 字段： +受支持的 `appServer` 字段： -| 字段 | 默认值 | 含义 | -| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -| `transport` | `"stdio"` | `"stdio"` 会启动 Codex；`"websocket"` 会连接到 `url`。 | -| `command` | 托管的 Codex 二进制文件 | 用于 stdio 传输的可执行文件。留空则使用托管二进制文件；仅在明确覆盖时设置。 | -| `args` | `["app-server", "--listen", "stdio://"]` | 用于 stdio 传输的参数。 | -| `url` | 未设置 | WebSocket app-server URL。 | -| `authToken` | 未设置 | 用于 WebSocket 传输的 Bearer token。 | -| `headers` | `{}` | 额外的 WebSocket 标头。 | -| `requestTimeoutMs` | `60000` | app-server 控制平面调用的超时时间。 | -| `mode` | `"yolo"` | YOLO 或 guardian 审核执行的预设。 | -| `approvalPolicy` | `"never"` | 发送到线程启动/恢复/轮次的原生 Codex 审批策略。 | -| `sandbox` | `"danger-full-access"` | 发送到线程启动/恢复的原生 Codex 沙箱模式。 | -| `approvalsReviewer` | `"user"` | 使用 `"auto_review"` 让 Codex 审核原生审批提示。`guardian_subagent` 仍保留为旧版别名。 | -| `serviceTier` | 未设置 | 可选的 Codex app-server 服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧版值会被忽略。 | +| Field | Default | 含义 | +| --- | --- | --- | +| `transport` | `"stdio"` | `"stdio"` 会启动 Codex；`"websocket"` 会连接到 `url`。 | +| `command` | 托管 Codex 二进制 | 用于 stdio 传输的可执行文件。保持未设置以使用托管二进制；仅在需要显式覆盖时设置。 | +| `args` | `["app-server", "--listen", "stdio://"]` | stdio 传输的参数。 | +| `url` | unset | WebSocket app-server URL。 | +| `authToken` | unset | WebSocket 传输的 Bearer token。 | +| `headers` | `{}` | 额外的 WebSocket 头。 | +| `requestTimeoutMs` | `60000` | app-server 控制平面调用的超时时间。 | +| `mode` | `"yolo"` | YOLO 或 guardian 审核执行的预设。 | +| `approvalPolicy` | `"never"` | 发送到线程 start/resume/turn 的原生 Codex 批准策略。 | +| `sandbox` | `"danger-full-access"` | 发送到线程 start/resume 的原生 Codex 沙箱模式。 | +| `approvalsReviewer` | `"user"` | 使用 `"auto_review"` 可让 Codex 审核原生批准提示。`guardian_subagent` 仍是旧版别名。 | +| `serviceTier` | unset | 可选的 Codex app-server 服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧值会被忽略。 | -环境覆盖仍可用于本地测试： +本地测试仍可使用环境变量覆盖： - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -490,22 +462,16 @@ Guardian 模式使用 Codex 原生的自动审核审批路径。当 Codex 请求 - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` 当 `appServer.command` 未设置时， -`OPENCLAW_CODEX_APP_SERVER_BIN` 会绕过托管二进制文件。 +`OPENCLAW_CODEX_APP_SERVER_BIN` 会绕过托管二进制。 -`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` 已被移除。请改用 -`plugins.entries.codex.config.appServer.mode: "guardian"`，或在一次性本地测试时使用 -`OPENCLAW_CODEX_APP_SERVER_MODE=guardian`。对于可重复部署，优先使用配置， -因为这样可以将插件行为与 Codex harness 设置的其余部分一起保存在同一个已审查文件中。 +`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` 已移除。请改用 +`plugins.entries.codex.config.appServer.mode: "guardian"`，或者在一次性本地测试中使用 `OPENCLAW_CODEX_APP_SERVER_MODE=guardian`。对于可重复部署，更推荐使用配置方式，因为它能将插件行为与 Codex harness 其余设置保存在同一个经过审查的文件中。 ## Computer Use -Computer Use 是一个 Codex 原生 MCP 插件。OpenClaw 不会内置桌面 -控制应用，也不会自行执行桌面操作；它会启用 Codex app-server -插件，在请求时安装配置好的 Codex marketplace 插件，检查 -`computer-use` MCP 服务器是否可用，然后在 Codex 模式轮次期间让 Codex -处理原生 MCP 工具调用。 +Computer Use 是一个 Codex 原生 MCP 插件。OpenClaw 不会内置桌面控制应用，也不会自行执行桌面操作；它会在请求时启用 Codex app-server 插件、安装已配置的 Codex marketplace 插件、检查 `computer-use` MCP 服务器是否可用，然后在 Codex 模式轮次中让 Codex 自行处理原生 MCP 工具调用。 -当你希望 Codex 模式轮次必须使用 Computer Use 时，请设置 +当你希望 Codex 模式轮次强制要求 Computer Use 时，请设置 `plugins.entries.codex.config.computerUse`： ```json5 @@ -533,31 +499,23 @@ Computer Use 是一个 Codex 原生 MCP 插件。OpenClaw 不会内置桌面 } ``` -如果未设置 marketplace 字段，OpenClaw 会请求 Codex app-server 使用其已发现的 -marketplace。在全新的 Codex 主目录中，app-server 会预置官方精选 -marketplace，而 OpenClaw 会遵循与 Codex 相同的加载方式：它会在安装期间轮询 -`plugin/list`，然后才将 Computer Use 视为不可用。默认的发现等待时间为 60 秒，可通过 -`marketplaceDiscoveryTimeoutMs` 调整。如果多个已知的 Codex marketplaces 都包含 -Computer Use，OpenClaw 会先使用 Codex 的 marketplace 优先顺序， -若仍然出现未知的歧义匹配，则会以失败关闭。 +如果未提供 marketplace 字段，OpenClaw 会请求 Codex app-server 使用其发现到的 marketplaces。在全新的 Codex 主目录中，app-server 会预置官方精选 marketplace，而 OpenClaw 会遵循与 Codex 相同的加载方式：它会在安装期间轮询 `plugin/list`，然后才将 Computer Use 视为不可用。默认发现等待时间为 60 秒，可通过 +`marketplaceDiscoveryTimeoutMs` 调整。如果多个已知 Codex marketplaces 都包含 Computer Use，OpenClaw 会先使用 Codex marketplace 的优先级顺序；如果仍出现未知的歧义匹配，则会以封闭失败的方式终止。 -对于 app-server 可添加的非默认 Codex marketplace 来源，请使用 `marketplaceSource`；对于机器上已经存在的本地 marketplace 文件，请使用 `marketplacePath`。如果该 marketplace 已经注册到 -Codex app-server，请改用 `marketplaceName`。默认值为 +对于非默认的、app-server 可添加的 Codex marketplace 来源，请使用 `marketplaceSource`；对于机器上已经存在的本地 marketplace 文件，请使用 `marketplacePath`。如果该 marketplace 已经在 Codex app-server 中注册，请改用 `marketplaceName`。默认值为 `pluginName: "computer-use"` 和 `mcpServerName: "computer-use"`。 -出于安全考虑，轮次开始时的自动安装只会使用 app-server -已经发现的 marketplaces。若要从已配置的 `marketplaceSource` 或 `marketplacePath` 显式安装，请使用 `/codex computer-use install`。 +出于安全考虑，轮次开始时的自动安装只会使用 app-server 已发现的 marketplaces。若要从已配置的 `marketplaceSource` 或 `marketplacePath` 显式安装，请使用 `/codex computer-use install`。 -同样的设置也可以通过命令界面检查或安装： +也可以通过命令界面检查或安装同一套配置： - `/codex computer-use status` - `/codex computer-use install` - `/codex computer-use install --source ` - `/codex computer-use install --marketplace-path ` -Computer Use 仅适用于 macOS，在 Codex MCP 服务器能够控制应用之前，可能需要本地操作系统权限。如果 `computerUse.enabled` 为 true 且 -MCP 服务器不可用，则 Codex 模式轮次会在线程启动前直接失败，而不是静默地在没有原生 Computer Use 工具的情况下继续运行。 +Computer Use 仅支持 macOS，并且在 Codex MCP 服务器控制应用之前，可能需要本地操作系统权限。如果 `computerUse.enabled` 为 true 且 MCP 服务器不可用，Codex 模式轮次会在线程启动前直接失败，而不是悄悄在没有原生 Computer Use 工具的情况下继续运行。 -## 常见示例 +## 常见配方 使用默认 stdio 传输的本地 Codex： @@ -573,7 +531,7 @@ MCP 服务器不可用，则 Codex 模式轮次会在线程启动前直接失败 } ``` -仅 Codex harness 验证： +仅使用 Codex 的 harness 验证： ```json5 { @@ -595,7 +553,7 @@ MCP 服务器不可用，则 Codex 模式轮次会在线程启动前直接失败 } ``` -由 Guardian 审核的 Codex 审批： +由 Guardian 审核的 Codex 批准： ```json5 { @@ -617,7 +575,7 @@ MCP 服务器不可用，则 Codex 模式轮次会在线程启动前直接失败 } ``` -带显式标头的远程 app-server： +带显式头部的远程 app-server： ```json5 { @@ -640,160 +598,134 @@ MCP 服务器不可用，则 Codex 模式轮次会在线程启动前直接失败 } ``` -模型切换仍由 OpenClaw 控制。当某个 OpenClaw 会话已附加到现有 Codex 线程时，下一轮会再次将当前选中的 -OpenAI 模型、提供商、审批策略、沙箱和服务层级发送给 -app-server。从 `openai/gpt-5.5` 切换到 `openai/gpt-5.2` 会保留线程绑定，但会要求 Codex 使用新选定的模型继续运行。 +模型切换仍由 OpenClaw 控制。当某个 OpenClaw 会话附加到现有 Codex 线程时，下一个轮次会再次向 app-server 发送当前选定的 +OpenAI 模型、provider、批准策略、沙箱和服务层级。从 `openai/gpt-5.5` 切换到 `openai/gpt-5.2` 会保留线程绑定，但会要求 Codex 使用新选定的模型继续运行。 ## Codex 命令 -内置插件将 `/codex` 注册为授权的斜杠命令。它是通用的，可在任何支持 OpenClaw 文本命令的渠道中使用。 +内置插件将 `/codex` 注册为已授权的斜杠命令。它是通用的，适用于任何支持 OpenClaw 文本命令的渠道。 常见形式： -- `/codex status` 显示实时 app-server 连接状态、模型、账户、速率限制、MCP 服务器和 Skills。 -- `/codex models` 列出实时 Codex app-server 模型。 +- `/codex status` 显示实时的 app-server 连接性、模型、账户、速率限制、MCP 服务器和 Skills。 +- `/codex models` 列出实时的 Codex app-server 模型。 - `/codex threads [filter]` 列出最近的 Codex 线程。 - `/codex resume ` 将当前 OpenClaw 会话附加到现有 Codex 线程。 -- `/codex compact` 请求 Codex app-server 压缩已附加线程。 -- `/codex review` 为已附加线程启动 Codex 原生审查。 +- `/codex compact` 请求 Codex app-server 压缩当前附加的线程。 +- `/codex review` 为当前附加的线程启动 Codex 原生审查。 - `/codex computer-use status` 检查已配置的 Computer Use 插件和 MCP 服务器。 - `/codex computer-use install` 安装已配置的 Computer Use 插件并重新加载 MCP 服务器。 - `/codex account` 显示账户和速率限制状态。 - `/codex mcp` 列出 Codex app-server MCP 服务器状态。 - `/codex skills` 列出 Codex app-server Skills。 -`/codex resume` 会写入与 harness 在正常轮次中使用的相同旁挂绑定文件。下一条消息到来时，OpenClaw 会恢复该 Codex 线程，将当前选中的 OpenClaw 模型传入 app-server，并保持扩展历史启用。 +`/codex resume` 会写入与 harness 用于正常轮次相同的 sidecar 绑定文件。在下一条消息中，OpenClaw 会恢复该 Codex 线程，将当前选定的 OpenClaw 模型传入 app-server，并保持扩展历史记录处于启用状态。 -该命令界面要求 Codex app-server `0.125.0` 或更高版本。如果未来版本或自定义 app-server 未暴露某个 JSON-RPC 方法，则各个控制方法会显示为 `unsupported by this Codex app-server`。 +该命令界面要求 Codex app-server `0.125.0` 或更高版本。如果未来版本或自定义 app-server 未暴露对应 JSON-RPC 方法，各个控制方法会显示为 `unsupported by this Codex app-server`。 ## 钩子边界 Codex harness 有三层钩子： -| 层级 | 所有者 | 目的 | -| ------------------------------------- | ------------------------ | ------------------------------------------------------------------- | -| OpenClaw 插件钩子 | OpenClaw | 在 Pi 和 Codex harness 之间提供产品/插件兼容性。 | -| Codex app-server 扩展中间件 | OpenClaw 内置插件 | 围绕 OpenClaw 动态工具的每轮适配器行为。 | -| Codex 原生钩子 | Codex | 来自 Codex 配置的底层 Codex 生命周期和原生工具策略。 | +| 层 | 所有者 | 目的 | +| --- | --- | --- | +| OpenClaw 插件钩子 | OpenClaw | 在 PI 和 Codex harness 之间提供产品/插件兼容性。 | +| Codex app-server 扩展中间件 | OpenClaw 内置插件 | 围绕 OpenClaw 动态工具的逐轮适配器行为。 | +| Codex 原生钩子 | Codex | 来自 Codex 配置的底层 Codex 生命周期和原生工具策略。 | -OpenClaw 不会使用项目级或全局的 Codex `hooks.json` 文件来路由 +OpenClaw 不会使用项目级或全局 Codex `hooks.json` 文件来路由 OpenClaw 插件行为。对于受支持的原生工具和权限桥接， -OpenClaw 会为每个线程注入 Codex 配置，用于 `PreToolUse`、`PostToolUse`、 -`PermissionRequest` 和 `Stop`。其他 Codex 钩子，如 `SessionStart` 和 -`UserPromptSubmit`，仍然是 Codex 级控制；它们不会在 v1 合约中作为 OpenClaw 插件钩子暴露。 +OpenClaw 会为每个线程注入 Codex 配置，以处理 `PreToolUse`、`PostToolUse`、 +`PermissionRequest` 和 `Stop`。其他 Codex 钩子，例如 `SessionStart` 和 +`UserPromptSubmit`，仍然属于 Codex 级控制；在 v1 合约中，它们不会作为 +OpenClaw 插件钩子暴露。 -对于 OpenClaw 动态工具，Codex 发出调用请求后由 OpenClaw 执行该工具，因此 -OpenClaw 会在 harness 适配器中触发其拥有的插件与中间件行为。对于 Codex 原生工具，Codex 拥有规范的工具记录。OpenClaw 可以镜像选定事件，但除非 Codex 通过 app-server 或原生钩子回调暴露该操作，否则 OpenClaw 无法重写原生 Codex 线程。 +对于 OpenClaw 动态工具，Codex 发出调用请求后，OpenClaw 才执行工具，因此 +OpenClaw 会在 harness 适配器中触发其自有的插件和中间件行为。对于 Codex 原生工具，Codex 持有规范工具记录。OpenClaw 可以镜像选定事件，但除非 Codex 通过 app-server 或原生钩子回调暴露该操作，否则它无法重写原生 Codex 线程。 -压缩和 LLM 生命周期投影来自 Codex app-server -通知以及 OpenClaw 适配器状态，而不是原生 Codex 钩子命令。 -OpenClaw 的 `before_compaction`、`after_compaction`、`llm_input` 和 -`llm_output` 事件是适配器级观察结果，而不是对 Codex 内部请求或压缩负载的逐字节捕获。 +压缩和 LLM 生命周期投影来自 Codex app-server 通知以及 OpenClaw 适配器状态，而不是原生 Codex 钩子命令。OpenClaw 的 +`before_compaction`、`after_compaction`、`llm_input` 和 +`llm_output` 事件是适配器级观察结果，并不是对 Codex 内部请求或压缩载荷的逐字节捕获。 -Codex 原生 `hook/started` 和 `hook/completed` app-server 通知 -会被投影为用于轨迹与调试的 `codex_app_server.hook` 智能体事件。 -它们不会调用 OpenClaw 插件钩子。 +Codex 原生 `hook/started` 和 `hook/completed` app-server 通知会被投影为 `codex_app_server.hook` 智能体事件，用于轨迹和调试。它们不会调用 OpenClaw 插件钩子。 ## V1 支持合约 -Codex 模式并不是“底层换了一个模型调用的 Pi”。Codex 接管了更多 -原生模型循环，而 OpenClaw 会围绕这个边界适配其插件和会话界面。 +Codex 模式并不是“底层换了一个模型调用的 PI”。Codex 接管了更多原生模型循环，而 OpenClaw 会围绕这一边界适配其插件和会话界面。 -在 Codex 运行时 v1 中受支持的内容： +Codex 运行时 v1 中支持的内容： -| 界面 | 支持情况 | 原因 | -| --------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 通过 Codex 的 OpenAI 模型循环 | 支持 | Codex app-server 接管 OpenAI 轮次、原生线程恢复和原生工具续接。 | -| OpenClaw 渠道路由与投递 | 支持 | Telegram、Discord、Slack、WhatsApp、iMessage 和其他渠道仍然位于模型运行时之外。 | -| OpenClaw 动态工具 | 支持 | Codex 会请求 OpenClaw 执行这些工具，因此 OpenClaw 仍然处于执行路径中。 | -| 提示词与上下文插件 | 支持 | OpenClaw 会在启动或恢复线程之前构建提示词覆盖层，并将上下文投影到 Codex 轮次中。 | -| 上下文引擎生命周期 | 支持 | Assemble、ingest 或轮次后维护，以及上下文引擎压缩协调都会在 Codex 轮次中运行。 | -| 动态工具钩子 | 支持 | `before_tool_call`、`after_tool_call` 和工具结果中间件会围绕由 OpenClaw 管理的动态工具运行。 | -| 生命周期钩子 | 作为适配器观察结果受支持 | `llm_input`、`llm_output`、`agent_end`、`before_compaction` 和 `after_compaction` 会以真实的 Codex 模式负载触发。 | -| 最终答案修订门控 | 通过原生钩子转发受支持 | Codex `Stop` 会转发到 `before_agent_finalize`；`revise` 会在最终完成前请求 Codex 再进行一次模型处理。 | -| 原生 shell、patch 和 MCP 的阻止或观察 | 通过原生钩子转发受支持 | Codex `PreToolUse` 和 `PostToolUse` 会针对已提交的原生工具界面进行转发，包括 Codex app-server `0.125.0` 或更高版本上的 MCP 负载。支持阻止；不支持参数重写。 | -| 原生权限策略 | 通过原生钩子转发受支持 | 当运行时暴露该能力时，Codex `PermissionRequest` 可以通过 OpenClaw 策略路由。如果 OpenClaw 未返回决定，Codex 会继续走其正常的 guardian 或用户审批路径。 | -| App-server 轨迹捕获 | 支持 | OpenClaw 会记录它发送给 app-server 的请求以及收到的 app-server 通知。 | +| 界面 | 支持情况 | 原因 | +| --- | --- | --- | +| 通过 Codex 运行 OpenAI 模型循环 | 支持 | Codex app-server 持有 OpenAI 轮次、原生线程恢复和原生工具续接。 | +| OpenClaw 渠道路由与投递 | 支持 | Telegram、Discord、Slack、WhatsApp、iMessage 和其他渠道仍位于模型运行时之外。 | +| OpenClaw 动态工具 | 支持 | Codex 请求 OpenClaw 执行这些工具，因此 OpenClaw 仍在执行路径中。 | +| 提示词和上下文插件 | 支持 | OpenClaw 会在启动或恢复线程之前构建提示词覆盖层，并将上下文投影到 Codex 轮次中。 | +| Context engine 生命周期 | 支持 | 汇编、摄取或轮次后维护，以及 context engine 压缩协调都会对 Codex 轮次运行。 | +| 动态工具钩子 | 支持 | `before_tool_call`、`after_tool_call` 和工具结果中间件会围绕 OpenClaw 持有的动态工具运行。 | +| 生命周期钩子 | 作为适配器观察结果支持 | `llm_input`、`llm_output`、`agent_end`、`before_compaction` 和 `after_compaction` 会携带真实的 Codex 模式载荷触发。 | +| 最终答案修订门 | 通过原生钩子中继支持 | Codex `Stop` 会被中继到 `before_agent_finalize`；`revise` 会要求 Codex 在终结前再执行一次模型轮次。 | +| 原生 shell、patch 和 MCP 的阻止或观察 | 通过原生钩子中继支持 | Codex `PreToolUse` 和 `PostToolUse` 会对已提交的原生工具界面进行中继，包括 Codex app-server `0.125.0` 或更新版本中的 MCP 载荷。支持阻止；不支持参数重写。 | +| 原生权限策略 | 通过原生钩子中继支持 | 在运行时暴露该能力的情况下，Codex `PermissionRequest` 可以通过 OpenClaw 策略进行路由。如果 OpenClaw 未返回决定，Codex 会继续使用其正常的 guardian 或用户批准路径。 | +| App-server 轨迹捕获 | 支持 | OpenClaw 会记录它发送给 app-server 的请求以及收到的 app-server 通知。 | -在 Codex 运行时 v1 中不受支持： +Codex 运行时 v1 中不支持的内容： -| 界面 | V1 边界 | 未来路径 | -| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | -| 原生工具参数变更 | Codex 原生预工具钩子可以阻止调用，但 OpenClaw 不会重写 Codex 原生工具参数。 | 需要 Codex 钩子/模式支持替换工具输入。 | -| 可编辑的 Codex 原生转录历史 | Codex 拥有规范的原生线程历史。OpenClaw 拥有一个镜像，并可投影未来上下文，但不应修改不受支持的内部实现。 | 如果需要原生线程手术式修改，则需添加显式的 Codex app-server API。 | -| 用于 Codex 原生工具记录的 `tool_result_persist` | 该钩子转换的是由 OpenClaw 管理的转录写入，而不是 Codex 原生工具记录。 | 可以镜像转换后的记录，但规范性重写仍需要 Codex 支持。 | -| 丰富的原生压缩元数据 | OpenClaw 可以观察压缩开始与完成，但不会收到稳定的保留/丢弃列表、token 差值或摘要负载。 | 需要更丰富的 Codex 压缩事件。 | -| 压缩干预 | 当前 OpenClaw 的压缩钩子在 Codex 模式下仅为通知级。 | 如果插件需要否决或重写原生压缩，则需添加 Codex 压缩前/后钩子。 | -| 逐字节的模型 API 请求捕获 | OpenClaw 可以捕获 app-server 请求与通知，但最终的 OpenAI API 请求由 Codex core 在内部构建。 | 需要 Codex 模型请求跟踪事件或调试 API。 | +| 界面 | V1 边界 | 未来路径 | +| --- | --- | --- | +| 原生工具参数变更 | Codex 原生预工具钩子可以阻止执行，但 OpenClaw 不会重写 Codex 原生工具参数。 | 需要 Codex 钩子/模式支持替换后的工具输入。 | +| 可编辑的 Codex 原生转录历史 | Codex 持有规范的原生线程历史。OpenClaw 持有镜像并可以投影未来上下文，但不应修改不受支持的内部结构。 | 如果需要对原生线程进行编辑，应添加显式的 Codex app-server API。 | +| 用于 Codex 原生工具记录的 `tool_result_persist` | 该钩子会转换由 OpenClaw 持有的转录写入，而不是 Codex 原生工具记录。 | 可以镜像转换后的记录，但要进行规范重写仍需要 Codex 支持。 | +| 丰富的原生压缩元数据 | OpenClaw 可以观察到压缩开始和完成，但不会收到稳定的保留/丢弃列表、token 增量或摘要载荷。 | 需要更丰富的 Codex 压缩事件。 | +| 压缩干预 | 当前 OpenClaw 的压缩钩子在 Codex 模式下仅处于通知级别。 | 如果插件需要否决或重写原生压缩，则需要添加 Codex 压缩前/后钩子。 | +| 逐字节的模型 API 请求捕获 | OpenClaw 可以捕获 app-server 请求和通知，但最终的 OpenAI API 请求由 Codex core 在内部构建。 | 需要 Codex 模型请求跟踪事件或调试 API。 | ## 工具、媒体和压缩 -Codex harness 只会改变底层的嵌入式智能体执行器。 +Codex harness 只改变底层的内嵌智能体执行器。 -OpenClaw 仍然构建工具列表，并从 -harness 接收动态工具结果。文本、图像、视频、音乐、TTS、审批以及消息工具输出 -仍然通过常规 OpenClaw 投递路径处理。 +OpenClaw 仍然会构建工具列表，并从 harness 接收动态工具结果。文本、图像、视频、音乐、TTS、批准以及消息工具输出，仍然继续通过常规 OpenClaw 投递路径传递。 -原生钩子转发被有意设计为通用机制，但 v1 支持合约仅限于 OpenClaw 已测试的 Codex 原生工具与权限路径。在 -Codex 运行时中，这包括 shell、patch 和 MCP 的 `PreToolUse`、 -`PostToolUse` 以及 `PermissionRequest` 负载。除非运行时合约明确命名，否则不要假设未来每个 -Codex 钩子事件都会成为 OpenClaw 插件界面。 +原生钩子中继被刻意设计为通用机制，但 v1 支持合约仅限于 OpenClaw 已测试的 Codex 原生工具和权限路径。在 Codex 运行时中，这包括 shell、patch 和 MCP 的 `PreToolUse`、`PostToolUse` 以及 `PermissionRequest` 载荷。不要假设未来的每个 Codex 钩子事件都属于 OpenClaw 插件界面，除非运行时合约已明确命名。 -对于 `PermissionRequest`，只有在策略做出决定时，OpenClaw 才会返回显式的允许或拒绝结果。无决定结果并不等于允许。Codex 会将其视为没有 -钩子决定，并回退到它自己的 guardian 或用户审批路径。 +对于 `PermissionRequest`，只有当策略作出决定时，OpenClaw 才会返回显式的允许或拒绝结果。无决定结果并不等于允许。Codex 会将其视为无钩子决定，并回退到自己的 guardian 或用户批准路径。 当 Codex 将 `_meta.codex_approval_kind` 标记为 -`"mcp_tool_call"` 时，Codex MCP 工具审批征询会通过 OpenClaw 的插件 -审批流程路由。Codex 的 `request_user_input` 提示会被发送回原始聊天， -而下一条排队的后续消息会用于回答该原生服务器请求，而不是作为额外上下文进行引导。其他 MCP 征询请求仍然会以失败关闭。 +`"mcp_tool_call"` 时，Codex MCP 工具批准征求会通过 OpenClaw 的插件批准流程进行路由。Codex 的 `request_user_input` 提示会被发送回原始聊天，而下一条排队的后续消息会回答该原生服务器请求，而不是作为额外上下文进行引导。其他 MCP 征求请求仍会以封闭失败方式处理。 -当所选模型使用 Codex harness 时，原生线程压缩会委托给 Codex app-server。OpenClaw 会保留一个转录镜像，用于渠道历史、搜索、`/new`、`/reset`，以及未来的模型或 harness 切换。该镜像包括用户提示词、最终助手文本，以及在 app-server 发出时提供的轻量 Codex 推理或计划记录。目前，OpenClaw 仅记录原生压缩的开始和完成信号。它尚未公开可供人阅读的压缩摘要，也不提供 Codex 压缩后保留了哪些条目的可审计列表。 +当所选模型使用 Codex harness 时，原生线程压缩会委托给 Codex +app-server。OpenClaw 会保留一个转录镜像，用于渠道历史、搜索、`/new`、`/reset` 以及未来的模型或 harness 切换。该镜像包含用户提示词、最终助手文本，以及当 app-server 发出这些内容时的轻量级 Codex 推理或计划记录。目前，OpenClaw 只记录原生压缩开始和完成信号。它还不会公开人类可读的压缩摘要，也不会提供 Codex 在压缩后保留了哪些条目的可审计列表。 -由于 Codex 拥有规范的原生线程，`tool_result_persist` 当前 -不会重写 Codex 原生工具结果记录。它仅适用于 -OpenClaw 正在写入由 OpenClaw 管理的会话转录工具结果时。 +由于 Codex 持有规范的原生线程，`tool_result_persist` 当前不会重写 Codex 原生工具结果记录。它只在 OpenClaw 正在写入由 OpenClaw 持有的会话转录工具结果时适用。 -媒体生成不需要 Pi。图像、视频、音乐、PDF、TTS 和媒体 -理解仍会继续使用对应的提供商/模型设置，例如 -`agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和 -`messages.tts`。 +媒体生成不依赖 PI。图像、视频、音乐、PDF、TTS 和媒体理解会继续使用匹配的 provider/模型设置，例如 +`agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和 `messages.tts`。 ## 故障排除 -**Codex 没有显示为常规 `/model` 提供商：** 对于 -新配置，这是预期行为。请选择一个 `openai/gpt-*` 模型，并设置 +**Codex 没有作为普通 `/model` provider 出现：** 这对新配置来说是预期行为。请选择一个 `openai/gpt-*` 模型，并设置 `agentRuntime.id: "codex"`（或使用旧版 `codex/*` 引用），启用 `plugins.entries.codex.enabled`，并检查 `plugins.allow` 是否排除了 `codex`。 -**OpenClaw 使用的是 Pi 而不是 Codex：** 当没有 Codex harness 声明接管运行时，`agentRuntime.id: "auto"` 仍然可以使用 Pi 作为 -兼容性后端。测试时请设置 -`agentRuntime.id: "codex"` 以强制选择 Codex。现在，强制的 Codex 运行时会直接失败，而不是回退到 Pi，除非你 -显式设置 `agentRuntime.fallback: "pi"`。一旦选择了 Codex app-server， -其失败会直接暴露出来，不会再经过额外的回退配置。 +**OpenClaw 使用了 PI 而不是 Codex：** `agentRuntime.id: "auto"` 在没有任何 Codex harness 声明接管该运行时，仍可能使用 PI 作为兼容后端。测试时请设置 `agentRuntime.id: "codex"` 以强制选择 Codex。现在，强制的 Codex 运行时会直接失败，而不是回退到 PI，除非你显式设置了 `agentRuntime.fallback: "pi"`。一旦选定了 Codex app-server，其故障会直接暴露出来，而不会再经过额外的回退配置。 -**app-server 被拒绝：** 请升级 Codex，使 app-server 握手 -报告版本 `0.125.0` 或更高。相同版本号的预发布版本或带构建后缀的 -版本，例如 `0.125.0-alpha.2` 或 `0.125.0+custom`，都会被拒绝，因为 -OpenClaw 测试的是稳定版 `0.125.0` 协议下限。 +**app-server 被拒绝：** 请升级 Codex，使 app-server 握手报告的版本为 `0.125.0` 或更高。相同版本号的预发布版或带构建后缀的版本，例如 `0.125.0-alpha.2` 或 `0.125.0+custom`，都会被拒绝，因为 OpenClaw 测试的稳定协议下限是 `0.125.0`。 -**模型发现很慢：** 请降低 `plugins.entries.codex.config.discovery.timeoutMs` -或禁用发现。 +**模型发现速度很慢：** 调低 +`plugins.entries.codex.config.discovery.timeoutMs`，或禁用发现。 -**WebSocket 传输立即失败：** 请检查 `appServer.url`、`authToken`， -以及远程 app-server 是否使用相同版本的 Codex app-server 协议。 +**WebSocket 传输立即失败：** 请检查 `appServer.url`、`authToken`，以及远程 app-server 是否使用相同的 Codex app-server 协议版本。 -**非 Codex 模型使用了 Pi：** 除非你为该智能体强制设置了 -`agentRuntime.id: "codex"`，或选择了旧版 -`codex/*` 引用，否则这是预期行为。普通 `openai/gpt-*` 和其他提供商引用在 `auto` 模式下会继续走其正常的 -提供商路径。如果你强制设置 `agentRuntime.id: "codex"`，则该智能体的每个嵌入式 -轮次都必须是 Codex 支持的 OpenAI 模型。 +**非 Codex 模型使用了 PI：** 这是预期行为，除非你为该智能体强制设置了 `agentRuntime.id: "codex"`，或选择了旧版 +`codex/*` 引用。普通的 `openai/gpt-*` 和其他 provider 引用在 `auto` 模式下仍会走它们的常规 provider 路径。如果你强制设置了 +`agentRuntime.id: "codex"`，则该智能体的每一个内嵌轮次都必须是 Codex 支持的 OpenAI 模型。 ## 相关内容 - [Agent harness plugins](/zh-CN/plugins/sdk-agent-harness) - [Agent Runtimes](/zh-CN/concepts/agent-runtimes) -- [Model providers](/zh-CN/concepts/model-providers) +- [模型提供商](/zh-CN/concepts/model-providers) - [OpenAI provider](/zh-CN/providers/openai) - [Status](/zh-CN/cli/status) - [Plugin hooks](/zh-CN/plugins/hooks) diff --git a/docs/zh-CN/reference/AGENTS.default.md b/docs/zh-CN/reference/AGENTS.default.md index 73c857453..c66c73124 100644 --- a/docs/zh-CN/reference/AGENTS.default.md +++ b/docs/zh-CN/reference/AGENTS.default.md @@ -2,13 +2,13 @@ read_when: - 开始新的 OpenClaw 智能体会话 - 启用或审计默认 Skills -summary: 个人助理设置的默认 OpenClaw 智能体指令与 Skills 清单 +summary: 个人助理设置的默认 OpenClaw 智能体指令和 Skills 名单 title: 默认 AGENTS.md x-i18n: - generated_at: "2026-04-24T04:06:28Z" + generated_at: "2026-04-27T07:12:59Z" model: gpt-5.4 provider: openai - source_hash: ce1ce4e8bd84ca8913dc30112fd2d7ec81782c1f84f62eb8cc5c1032e9b060da + source_hash: 839368a09c60ac6b7cd403e6ecd86dd0cafd01de8c8b70a1d919cf7daf6d51af source_path: reference/AGENTS.default.md workflow: 15 --- @@ -33,7 +33,7 @@ cp docs/reference/templates/SOUL.md ~/.openclaw/workspace/SOUL.md cp docs/reference/templates/TOOLS.md ~/.openclaw/workspace/TOOLS.md ``` -3. 可选：如果你想使用个人助理 Skills 清单，请用此文件替换 AGENTS.md： +3. 可选：如果你想使用个人助理的 Skills 名单，请用此文件替换 AGENTS.md： ```bash cp docs/reference/AGENTS.default.md ~/.openclaw/workspace/AGENTS.md @@ -47,90 +47,90 @@ cp docs/reference/AGENTS.default.md ~/.openclaw/workspace/AGENTS.md } ``` -## 安全默认值 +## 默认安全设置 -- 不要将目录或密钥转储到聊天中。 +- 不要将目录内容或密钥转储到聊天中。 - 除非被明确要求，否则不要运行破坏性命令。 -- 不要向外部消息表面发送部分/流式回复（只发送最终回复）。 +- 不要向外部消息渠道发送部分 / 流式回复（只发送最终回复）。 ## 会话开始（必需） - 读取 `SOUL.md`、`USER.md`，以及 `memory/` 中今天和昨天的内容。 -- 如果存在，也读取 `MEMORY.md`。 -- 在回复前完成这些操作。 +- 如果存在，也要读取 `MEMORY.md`。 +- 在回复之前完成这些操作。 ## Soul（必需） -- `SOUL.md` 定义身份、语气和边界。请保持其最新。 -- 如果你更改了 `SOUL.md`，告诉用户。 -- 你在每个会话中都是一个全新实例；连续性存储在这些文件中。 +- `SOUL.md` 定义身份、语气和边界。请保持其为最新状态。 +- 如果你更改了 `SOUL.md`，请告诉用户。 +- 你在每次会话中都是一个全新的实例；连续性保存在这些文件中。 ## 共享空间（推荐） -- 你不是用户的代言人；在群聊或公共渠道中要谨慎。 -- 不要分享私人数据、联系信息或内部笔记。 +- 你不是用户本人的声音；在群聊或公共渠道中要谨慎。 +- 不要分享私密数据、联系信息或内部笔记。 ## 记忆系统（推荐） - 每日日志：`memory/YYYY-MM-DD.md`（如有需要请创建 `memory/`）。 -- 长期记忆：`MEMORY.md` 用于保存持久事实、偏好和决策。 -- 小写的 `memory.md` 仅用于旧版修复输入；不要有意同时保留这两个根文件。 +- 长期记忆：`MEMORY.md`，用于保存持久事实、偏好和决定。 +- 小写的 `memory.md` 仅用于旧版修复输入；不要有意同时保留这两个根目录文件。 - 在会话开始时，读取今天 + 昨天 + `MEMORY.md`（如果存在）。 -- 记录内容：决策、偏好、约束、未完成事项。 +- 记录：决定、偏好、约束、未完成事项。 - 除非被明确要求，否则避免记录密钥。 ## 工具与 Skills -- 工具存在于 Skills 中；当你需要某个 skill 时，请遵循其 `SKILL.md`。 -- 将环境相关说明保存在 `TOOLS.md` 中（Notes for Skills）。 +- 工具存在于 Skills 中；当你需要时，请遵循每个 skill 的 `SKILL.md`。 +- 将特定于环境的说明保存在 `TOOLS.md` 中（Skills 说明）。 ## 备份提示（推荐） -如果你将此工作区视为 Clawd 的“记忆”，请将其设为 git 仓库（最好为私有），这样 `AGENTS.md` 和你的记忆文件就能备份。 +如果你将此工作区视为 Clawd 的“记忆”，请将其设为一个 git 仓库（最好是私有仓库），以便备份 `AGENTS.md` 和你的记忆文件。 ```bash cd ~/.openclaw/workspace git init git add AGENTS.md git commit -m "Add Clawd workspace" -# 可选：添加私有远程仓库并推送 +# Optional: add a private remote + push ``` ## OpenClaw 的作用 -- 运行 WhatsApp Gateway 网关 + Pi 编码智能体，使助理能够读取/写入聊天、获取上下文，并通过宿主 Mac 运行 Skills。 -- macOS 应用负责管理权限（屏幕录制、通知、麦克风），并通过其内置二进制文件暴露 `openclaw` CLI。 -- 默认情况下，私聊会折叠到智能体的 `main` 会话中；群组会保持隔离为 `agent:::group:`（房间/渠道：`agent:::channel:`）；心跳会让后台任务保持存活。 +- 运行 WhatsApp Gateway 网关 + Pi 编码智能体，使助手能够读写聊天、获取上下文，并通过主机 Mac 运行 Skills。 +- macOS 应用负责管理权限（屏幕录制、通知、麦克风），并通过其内置二进制文件提供 `openclaw` CLI。 +- 默认情况下，私聊会合并到智能体的 `main` 会话中；群组会保持隔离，作为 `agent:::group:`（房间 / 渠道：`agent:::channel:`）；心跳会保持后台任务存活。 -## 核心 Skills（在设置 → Skills 中启用） +## 核心 Skills（在 设置 → Skills 中启用） -- **mcporter** — 用于管理外部 skill 后端的工具服务器运行时/CLI。 -- **Peekaboo** — 快速 macOS 截图，可选 AI 视觉分析。 -- **camsnap** — 从 RTSP/ONVIF 安防摄像头采集帧、片段或运动提醒。 -- **oracle** — 兼容 OpenAI 的智能体 CLI，支持会话重放和浏览器控制。 -- **eightctl** — 通过终端控制你的睡眠。 -- **imsg** — 发送、读取、流式处理 iMessage 与短信。 +- **mcporter** — 用于管理外部技能后端的工具服务器运行时 / CLI。 +- **Peekaboo** — 快速进行 macOS 截图，并可选使用 AI 视觉分析。 +- **camsnap** — 从 RTSP / ONVIF 安防摄像头捕获帧、片段或运动提醒。 +- **oracle** — 兼容 OpenAI 的智能体 CLI，支持会话回放和浏览器控制。 +- **eightctl** — 从终端控制你的睡眠。 +- **imsg** — 发送、读取、流式处理 iMessage 和短信。 - **wacli** — WhatsApp CLI：同步、搜索、发送。 -- **discord** — Discord 操作：反应、贴纸、投票。使用 `user:` 或 `channel:` 目标（裸数字 id 含义不明确）。 +- **discord** — Discord 操作：回应、贴纸、投票。使用 `user:` 或 `channel:` 作为目标（裸数字 id 有歧义）。 - **gog** — Google Suite CLI：Gmail、Calendar、Drive、Contacts。 -- **spotify-player** — 终端 Spotify 客户端，用于搜索/加入队列/控制播放。 -- **sag** — ElevenLabs 语音，提供 mac 风格的 say 体验；默认流式输出到扬声器。 -- **Sonos CLI** — 通过脚本控制 Sonos 扬声器（发现/状态/播放/音量/分组）。 -- **blucli** — 通过脚本播放、分组和自动化 BluOS 播放器。 -- **OpenHue CLI** — 用于场景和自动化的 Philips Hue 灯光控制。 -- **OpenAI Whisper** — 用于快速听写和语音信箱转录的本地语音转文本。 -- **Gemini CLI** — 通过终端使用 Google Gemini 模型进行快速问答。 -- **agent-tools** — 用于自动化和辅助脚本的实用工具包。 +- **spotify-player** — 终端 Spotify 客户端，用于搜索 / 加入队列 / 控制播放。 +- **sag** — ElevenLabs 语音，具有 mac 风格的 say 体验；默认流式输出到扬声器。 +- **Sonos CLI** — 从脚本中控制 Sonos 扬声器（发现 / 状态 / 播放 / 音量 / 分组）。 +- **blucli** — 从脚本中播放、分组和自动化 BluOS 播放器。 +- **OpenHue CLI** — Philips Hue 灯光控制，用于场景和自动化。 +- **OpenAI Whisper** — 本地语音转文本，用于快速听写和语音信箱转录。 +- **Gemini CLI** — 在终端中使用 Google Gemini 模型进行快速问答。 +- **agent-tools** — 用于自动化和辅助脚本的工具集。 ## 使用说明 -- 优先使用 `openclaw` CLI 进行脚本编写；mac 应用负责处理权限。 -- 从 Skills 标签页运行安装；如果二进制文件已存在，它会隐藏按钮。 -- 保持启用心跳，这样助理才能安排提醒、监控收件箱并触发摄像头采集。 -- Canvas UI 以全屏模式运行并带有原生覆盖层。避免将关键控件放在左上/右上/底部边缘；在布局中添加明确的边距，不要依赖安全区域 inset。 -- 对于浏览器驱动的验证，请使用 `openclaw browser`（tabs/status/screenshot），并配合 OpenClaw 管理的 Chrome profile。 -- 对于 DOM 检查，请使用 `openclaw browser eval|query|dom|snapshot`（在需要机器输出时加上 `--json`/`--out`）。 -- 对于交互，请使用 `openclaw browser click|type|hover|drag|select|upload|press|wait|navigate|back|evaluate|run`（click/type 需要 snapshot 引用；对 CSS 选择器请使用 `evaluate`）。 +- 优先使用 `openclaw` CLI 进行脚本编写；mac 应用会处理权限。 +- 从 Skills 标签页运行安装；如果二进制文件已存在，它会隐藏该按钮。 +- 保持心跳启用，以便助手可以安排提醒、监控收件箱并触发摄像头捕获。 +- Canvas UI 以全屏方式运行，并带有原生覆盖层。避免将关键控件放在左上 / 右上 / 底部边缘；请在布局中添加明确边距，不要依赖安全区域内边距。 +- 对于浏览器驱动的验证，请使用 `openclaw browser`（tabs / status / screenshot），并配合 OpenClaw 管理的 Chrome 配置文件。 +- 对于 DOM 检查，请使用 `openclaw browser eval|query|dom|snapshot`（当你需要机器可读输出时使用 `--json` / `--out`）。 +- 对于交互，请使用 `openclaw browser click|type|hover|drag|select|upload|press|wait|navigate|back|evaluate|run`（click / type 需要 snapshot refs；CSS 选择器请使用 `evaluate`）。 ## 相关内容 diff --git a/docs/zh-CN/security/CONTRIBUTING-THREAT-MODEL.md b/docs/zh-CN/security/CONTRIBUTING-THREAT-MODEL.md index 6cb394360..aca8b8dcf 100644 --- a/docs/zh-CN/security/CONTRIBUTING-THREAT-MODEL.md +++ b/docs/zh-CN/security/CONTRIBUTING-THREAT-MODEL.md @@ -1,108 +1,108 @@ --- read_when: - - 你想贡献安全发现或威胁场景 - - 审查或更新威胁模型时 -summary: 如何为 OpenClaw 威胁模型做出贡献 + - 你想要贡献安全发现或威胁场景 + - 审查或更新威胁模型 +summary: 如何为 OpenClaw 威胁模型做贡献 title: 为威胁模型做贡献 x-i18n: - generated_at: "2026-04-24T04:07:42Z" + generated_at: "2026-04-27T07:13:03Z" model: gpt-5.4 provider: openai - source_hash: 21cf130c2d8641b66b87de86a3ea718cd7c751c29ed9bf5e0bd76b43d65d0964 + source_hash: 75cf2b408a78fce5134d24a3f115490da2dacc4ba8a1a24415425c3e4420ca55 source_path: security/CONTRIBUTING-THREAT-MODEL.md workflow: 15 --- -# 为 OpenClaw 威胁模型做出贡献 +# 为 OpenClaw 威胁模型做贡献 -感谢你帮助 OpenClaw 变得更安全。这个威胁模型是一份持续演进的文档，我们欢迎任何人参与贡献——你不需要是安全专家。 +感谢你帮助提升 OpenClaw 的安全性。这个威胁模型是一份持续演进的文档，我们欢迎任何人贡献内容——你不需要是安全专家。 ## 贡献方式 ### 添加威胁 -发现了我们尚未覆盖的攻击向量或风险？请在 [openclaw/trust](https://github.com/openclaw/trust/issues) 上创建 issue，并用你自己的话描述它。你不需要了解任何框架，也不需要填写每个字段——只需描述该场景即可。 +发现了我们尚未覆盖的攻击向量或风险？请在 [openclaw/trust](https://github.com/openclaw/trust/issues) 上创建 issue，并用你自己的话描述它。你不需要了解任何框架，也不需要填写每个字段——只需描述这个场景即可。 -**建议包含（但不是必需）：** +**建议包含的内容（但不是必需）：** - 攻击场景以及它可能如何被利用 - OpenClaw 的哪些部分受到影响（CLI、Gateway 网关、渠道、ClawHub、MCP 服务器等） -- 你认为它的严重程度（低 / 中 / 高 / 严重） +- 你认为它有多严重（低 / 中 / 高 / 严重） - 任何相关研究、CVE 或真实案例的链接 -我们会在审查过程中处理 ATLAS 映射、威胁 ID 和风险评估。如果你想附带这些细节，当然很好——但不是预期要求。 +我们会在审查期间处理 ATLAS 映射、威胁 ID 和风险评估。如果你想包含这些细节，也很好——但并不要求。 -> **这里用于向威胁模型添加内容，而不是报告正在发生的漏洞。** 如果你发现了可被利用的漏洞，请参阅我们的 [Trust 页面](https://trust.openclaw.ai) 了解负责任披露说明。 +> **这里用于向威胁模型补充内容，而不是报告正在发生的漏洞。** 如果你发现了一个可被利用的漏洞，请查看我们的 [Trust 页面](https://trust.openclaw.ai) 了解负责任披露说明。 -### 提出缓解措施 +### 建议缓解措施 -对如何应对现有威胁有想法？请创建 issue 或 PR，并引用该威胁。有效的缓解措施应当具体且可执行——例如，“在 Gateway 网关按发送者进行每分钟 10 条消息的速率限制” 就比 “实现速率限制” 更好。 +如果你对如何应对现有威胁有想法，请创建引用该威胁的 issue 或 PR。有效的缓解措施应具体且可执行——例如，“在 Gateway 网关按发送者实施每分钟 10 条消息的速率限制” 比 “实现速率限制” 更好。 ### 提出攻击链 -攻击链展示了多个威胁如何组合成一个现实攻击场景。如果你发现了某种危险组合，请描述其步骤，以及攻击者将如何把它们串联起来。与正式模板相比，一段关于攻击在实践中如何展开的简短叙述更有价值。 +攻击链展示了多个威胁如何组合成现实中的攻击场景。如果你发现某种危险组合，请描述各个步骤，以及攻击者会如何将它们串联起来。相比正式模板，一段简短的攻击实际展开过程叙述更有价值。 ### 修复或改进现有内容 -错字、澄清、过时信息、更好的示例——欢迎提交 PR，无需先开 issue。 +错字、澄清说明、过时信息、更好的示例——欢迎提交 PR，无需先开 issue。 -## 我们使用的内容 +## 我们使用什么 ### MITRE ATLAS -该威胁模型基于 [MITRE ATLAS](https://atlas.mitre.org/)（Adversarial Threat Landscape for AI Systems），这是一个专为 AI/ML 威胁设计的框架，例如提示注入、工具滥用和智能体利用。你无需了解 ATLAS 也可以参与贡献——我们会在审查期间将提交内容映射到该框架。 +这个威胁模型基于 [MITRE ATLAS](https://atlas.mitre.org/)（面向 AI 系统的对抗性威胁态势，Adversarial Threat Landscape for AI Systems）构建，这是一个专为 AI/ML 威胁设计的框架，例如提示注入、工具滥用和智能体利用。你不需要了解 ATLAS 才能贡献——我们会在审查时将提交内容映射到该框架。 ### 威胁 ID 每个威胁都会获得一个类似 `T-EXEC-003` 的 ID。分类如下： -| Code | Category | +| 代码 | 类别 | | ------- | ------------------------------------------ | -| RECON | 侦察——信息收集 | -| ACCESS | 初始访问——获取进入权限 | -| EXEC | 执行——运行恶意操作 | -| PERSIST | 持久化——维持访问权限 | -| EVADE | 防御规避——避免检测 | -| DISC | 发现——了解环境 | -| EXFIL | 数据外传——窃取数据 | -| IMPACT | 影响——造成损害或中断 | +| RECON | 侦察——信息收集 | +| ACCESS | 初始访问——获得入口 | +| EXEC | 执行——运行恶意操作 | +| PERSIST | 持久化——维持访问 | +| EVADE | 防御规避——避免被检测 | +| DISC | 发现——了解环境 | +| EXFIL | 数据外传——窃取数据 | +| IMPACT | 影响——破坏或中断 | -ID 由维护者在审查期间分配。你无需自己选择。 +ID 由维护者在审查期间分配。你不需要自己挑选。 ### 风险等级 -| Level | Meaning | +| 等级 | 含义 | | ------------ | ----------------------------------------------------------------- | -| **严重** | 整个系统被完全攻破，或高可能性 + 严重影响 | -| **高** | 很可能造成重大损害，或中等可能性 + 严重影响 | -| **中** | 中等风险，或低可能性 + 高影响 | -| **低** | 可能性低且影响有限 | +| **严重** | 完整系统失陷，或高概率 + 严重影响 | +| **高** | 很可能造成重大损害，或中等概率 + 严重影响 | +| **中** | 中等风险，或低概率 + 高影响 | +| **低** | 发生可能性低且影响有限 | -如果你不确定风险等级，只需描述其影响，我们会进行评估。 +如果你不确定风险等级，只需描述影响，我们会进行评估。 ## 审查流程 -1. **分流** —— 我们会在 48 小时内审查新的提交 -2. **评估** —— 我们验证可行性，分配 ATLAS 映射和威胁 ID，并验证风险等级 -3. **文档化** —— 我们确保所有内容格式正确且完整 -4. **合并** —— 添加到威胁模型和可视化中 +1. **分流**——我们会在 48 小时内审查新的提交 +2. **评估**——我们验证其可行性，分配 ATLAS 映射和威胁 ID，并确认风险等级 +3. **文档整理**——我们确保所有内容格式正确且信息完整 +4. **合并**——添加到威胁模型和可视化中 ## 资源 -- [ATLAS 网站](https://atlas.mitre.org/) -- [ATLAS 技术](https://atlas.mitre.org/techniques/) -- [ATLAS 案例研究](https://atlas.mitre.org/studies/) +- [ATLAS Website](https://atlas.mitre.org/) +- [ATLAS Techniques](https://atlas.mitre.org/techniques/) +- [ATLAS Case Studies](https://atlas.mitre.org/studies/) - [OpenClaw 威胁模型](/zh-CN/security/THREAT-MODEL-ATLAS) ## 联系方式 -- **安全漏洞：** 请参阅我们的 [Trust 页面](https://trust.openclaw.ai) 获取报告说明 +- **安全漏洞：** 请查看我们的 [Trust 页面](https://trust.openclaw.ai) 获取报告说明 - **威胁模型问题：** 在 [openclaw/trust](https://github.com/openclaw/trust/issues) 上创建 issue -- **一般讨论：** Discord `#security` 频道 +- **一般讨论：** Discord `#security` 渠道 ## 致谢 -对威胁模型做出贡献的人员，将因重大贡献而在威胁模型致谢、发布说明和 OpenClaw 安全名人堂中获得认可。 +对威胁模型作出贡献的人员，将在威胁模型致谢、发布说明以及 OpenClaw 安全名人堂中获得认可，尤其是作出重大贡献时。 ## 相关内容 diff --git a/docs/zh-CN/security/THREAT-MODEL-ATLAS.md b/docs/zh-CN/security/THREAT-MODEL-ATLAS.md index 9b34aedb1..62dd621f7 100644 --- a/docs/zh-CN/security/THREAT-MODEL-ATLAS.md +++ b/docs/zh-CN/security/THREAT-MODEL-ATLAS.md @@ -1,14 +1,14 @@ --- read_when: - 审查安全态势或威胁场景 - - 处理安全功能或审计响应 + - 开发安全功能或处理审计响应 summary: 映射到 MITRE ATLAS 框架的 OpenClaw 威胁模型 title: 威胁模型（MITRE ATLAS） x-i18n: - generated_at: "2026-04-24T04:07:36Z" + generated_at: "2026-04-27T07:13:04Z" model: gpt-5.4 provider: openai - source_hash: e628bf60015a76d3015a7aab7b51649bdcfd2e99db148368e580839db16d2342 + source_hash: d929addb829b92d650ef6caecb267fb154f6f9f7d28be7aa87851569931f5228 source_path: security/THREAT-MODEL-ATLAS.md workflow: 15 --- @@ -17,26 +17,26 @@ x-i18n: ## MITRE ATLAS 框架 -**版本：**1.0-draft -**最后更新：**2026-02-04 -**方法论：**MITRE ATLAS + 数据流图 -**框架：**[MITRE ATLAS](https://atlas.mitre.org/)（AI 系统对抗性威胁版图，Adversarial Threat Landscape for AI Systems） +**版本：** 1.0-draft +**最后更新：** 2026-02-04 +**方法论：** MITRE ATLAS + 数据流图 +**框架：** [MITRE ATLAS](https://atlas.mitre.org/)（面向 AI 系统的对抗性威胁态势，Adversarial Threat Landscape for AI Systems） -### 框架归属 +### 框架归属说明 -此威胁模型基于 [MITRE ATLAS](https://atlas.mitre.org/)，这是业界标准的框架，用于记录 AI/ML 系统面临的对抗性威胁。ATLAS 由 [MITRE](https://www.mitre.org/) 与 AI 安全社区共同维护。 +本威胁模型基于 [MITRE ATLAS](https://atlas.mitre.org/)，这是用于记录 AI / ML 系统对抗性威胁的行业标准框架。ATLAS 由 [MITRE](https://www.mitre.org/) 与 AI 安全社区协作维护。 **ATLAS 关键资源：** -- [ATLAS 技术](https://atlas.mitre.org/techniques/) -- [ATLAS 战术](https://atlas.mitre.org/tactics/) -- [ATLAS 案例研究](https://atlas.mitre.org/studies/) +- [ATLAS Techniques](https://atlas.mitre.org/techniques/) +- [ATLAS Tactics](https://atlas.mitre.org/tactics/) +- [ATLAS Case Studies](https://atlas.mitre.org/studies/) - [ATLAS GitHub](https://github.com/mitre-atlas/atlas-data) -- [为 ATLAS 做贡献](https://atlas.mitre.org/resources/contribute) +- [Contributing to ATLAS](https://atlas.mitre.org/resources/contribute) -### 为此威胁模型做贡献 +### 为本威胁模型做贡献 -这是一份由 OpenClaw 社区维护的动态文档。有关贡献指南，请参阅 [CONTRIBUTING-THREAT-MODEL.md](/zh-CN/security/CONTRIBUTING-THREAT-MODEL)： +这是一份由 OpenClaw 社区维护的持续演进文档。有关贡献指南，请参阅 [CONTRIBUTING-THREAT-MODEL.md](/zh-CN/security/CONTRIBUTING-THREAT-MODEL)： - 报告新威胁 - 更新现有威胁 @@ -49,22 +49,22 @@ x-i18n: ### 1.1 目的 -本威胁模型使用专为 AI/ML 系统设计的 MITRE ATLAS 框架，记录 OpenClaw AI 智能体平台和 ClawHub Skills 市场面临的对抗性威胁。 +本威胁模型使用专为 AI / ML 系统设计的 MITRE ATLAS 框架，记录 OpenClaw AI 智能体平台和 ClawHub Skills 市场面临的对抗性威胁。 ### 1.2 范围 -| 组件 | 是否包含 | 说明 | -| ---- | -------- | ---- | +| 组件 | 包含 | 说明 | +| ---------------------- | -------- | ------------------------------------------------ | | OpenClaw Agent Runtime | 是 | 核心智能体执行、工具调用、会话 | -| Gateway 网关 | 是 | 身份验证、路由、渠道集成 | +| Gateway 网关 | 是 | 认证、路由、渠道集成 | | 渠道集成 | 是 | WhatsApp、Telegram、Discord、Signal、Slack 等 | | ClawHub 市场 | 是 | Skills 发布、审核、分发 | | MCP 服务器 | 是 | 外部工具提供商 | | 用户设备 | 部分 | 移动应用、桌面客户端 | -### 1.3 不在范围内 +### 1.3 不在范围内的内容 -此威胁模型没有明确排除的范围。 +本威胁模型没有明确排除任何内容。 --- @@ -72,9 +72,9 @@ x-i18n: ### 2.1 信任边界 -``` +```text ┌─────────────────────────────────────────────────────────────────┐ -│ 不受信任区域 │ +│ 不可信区域 │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ WhatsApp │ │ Telegram │ │ Discord │ ... │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ @@ -86,9 +86,9 @@ x-i18n: │ 信任边界 1：渠道访问 │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ GATEWAY 网关 │ │ -│ │ • 设备配对（私信 1 小时 / 节点 5 分钟宽限期） │ │ -│ │ • AllowFrom / AllowList 验证 │ │ -│ │ • Token/Password/Tailscale 身份验证 │ │ +│ │ • 设备配对（私信 1 小时 / 节点 5 分钟宽限期） │ │ +│ │ • AllowFrom / AllowList 校验 │ │ +│ │ • Token / Password / Tailscale 认证 │ │ │ └──────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ @@ -97,8 +97,8 @@ x-i18n: │ 信任边界 2：会话隔离 │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ 智能体会话 │ │ -│ │ • 会话键 = agent:channel:peer │ │ -│ │ • 每个智能体的工具策略 │ │ +│ │ • 会话键 = agent:channel:peer │ │ +│ │ • 按智能体划分的工具策略 │ │ │ │ • 转录日志记录 │ │ │ └──────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ @@ -107,10 +107,10 @@ x-i18n: ┌─────────────────────────────────────────────────────────────────┐ │ 信任边界 3：工具执行 │ │ ┌──────────────────────────────────────────────────────────┐ │ -│ │ 执行沙箱 │ │ +│ │ 执行沙箱 │ │ │ │ • Docker 沙箱或主机（exec-approvals） │ │ -│ │ • 节点远程执行 │ │ -│ │ • SSRF 防护（DNS pinning + IP blocking） │ │ +│ │ • Node 远程执行 │ │ +│ │ • SSRF 保护（DNS 固定 + IP 阻止） │ │ │ └──────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ @@ -118,7 +118,7 @@ x-i18n: ┌─────────────────────────────────────────────────────────────────┐ │ 信任边界 4：外部内容 │ │ ┌──────────────────────────────────────────────────────────┐ │ -│ │ 获取的 URL / 邮件 / Webhooks │ │ +│ │ 抓取的 URL / 邮件 / Webhooks │ │ │ │ • 外部内容包装（XML 标签） │ │ │ │ • 安全提示注入 │ │ │ └──────────────────────────────────────────────────────────┘ │ @@ -129,42 +129,42 @@ x-i18n: │ 信任边界 5：供应链 │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ CLAWHUB │ │ -│ │ • Skills 发布（semver，要求 SKILL.md） │ │ -│ │ • 基于模式的审核标记 │ │ -│ │ • VirusTotal 扫描（即将推出） │ │ -│ │ • GitHub 账号年龄验证 │ │ +│ │ • Skills 发布（需要 semver 和 SKILL.md） │ │ +│ │ • 基于模式的审核标记 │ │ +│ │ • VirusTotal 扫描（即将推出） │ │ +│ │ • GitHub 账号年龄验证 │ │ │ └──────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 2.2 数据流 -| 流 | 来源 | 目标 | 数据 | 保护措施 | +| 流程 | 来源 | 目标 | 数据 | 保护措施 | | ---- | ------- | ----------- | ------------------ | -------------------- | -| F1 | 渠道 | Gateway 网关 | 用户消息 | TLS, AllowFrom | -| F2 | Gateway 网关 | 智能体 | 路由后的消息 | 会话隔离 | -| F3 | 智能体 | 工具 | 工具调用 | 策略执行 | -| F4 | 智能体 | 外部 | `web_fetch` 请求 | SSRF 阻断 | -| F5 | ClawHub | 智能体 | Skill 代码 | 审核、扫描 | +| F1 | 渠道 | Gateway 网关 | 用户消息 | TLS、AllowFrom | +| F2 | Gateway 网关 | 智能体 | 路由消息 | 会话隔离 | +| F3 | 智能体 | 工具 | 工具调用 | 策略强制执行 | +| F4 | 智能体 | 外部 | `web_fetch` 请求 | SSRF 阻止 | +| F5 | ClawHub | 智能体 | Skills 代码 | 审核、扫描 | | F6 | 智能体 | 渠道 | 响应 | 输出过滤 | --- ## 3. 按 ATLAS 战术划分的威胁分析 -### 3.1 Reconnaissance（AML.TA0002） +### 3.1 侦察（AML.TA0002） #### T-RECON-001：智能体端点发现 | 属性 | 值 | | ----------------------- | -------------------------------------------------------------------- | | **ATLAS ID** | AML.T0006 - 主动扫描 | -| **描述** | 攻击者扫描暴露的 OpenClaw gateway 端点 | +| **描述** | 攻击者扫描暴露的 OpenClaw Gateway 网关端点 | | **攻击向量** | 网络扫描、Shodan 查询、DNS 枚举 | | **受影响组件** | Gateway 网关、暴露的 API 端点 | -| **当前缓解措施** | Tailscale 身份验证选项，默认绑定到 loopback | -| **残余风险** | 中 - 公共 gateway 可被发现 | -| **建议** | 记录安全部署方式，为发现端点添加速率限制 | +| **当前缓解措施** | Tailscale 认证选项、默认绑定到 loopback | +| **残余风险** | 中等——公网 Gateway 网关可被发现 | +| **建议** | 记录安全部署方式，并在发现类端点上增加速率限制 | #### T-RECON-002：渠道集成探测 @@ -175,12 +175,12 @@ x-i18n: | **攻击向量** | 发送测试消息，观察响应模式 | | **受影响组件** | 所有渠道集成 | | **当前缓解措施** | 无特定措施 | -| **残余风险** | 低 - 单纯发现的价值有限 | -| **建议** | 考虑对响应时机进行随机化 | +| **残余风险** | 低——仅凭发现本身价值有限 | +| **建议** | 可考虑对响应时间进行随机化 | --- -### 3.2 Initial Access（AML.TA0004） +### 3.2 初始访问（AML.TA0004） #### T-ACCESS-001：配对码拦截 @@ -190,140 +190,140 @@ x-i18n: | **描述** | 攻击者在配对宽限期内拦截配对码（私信渠道配对为 1 小时，节点配对为 5 分钟） | | **攻击向量** | 肩窥、网络嗅探、社会工程 | | **受影响组件** | 设备配对系统 | -| **当前缓解措施** | 1 小时过期（私信配对）/ 5 分钟过期（节点配对），通过现有渠道发送代码 | -| **残余风险** | 中 - 宽限期可被利用 | +| **当前缓解措施** | 1 小时过期时间（私信配对）/ 5 分钟过期时间（节点配对），验证码通过现有渠道发送 | +| **残余风险** | 中等——宽限期存在可利用空间 | | **建议** | 缩短宽限期，增加确认步骤 | -#### T-ACCESS-002：AllowFrom 冒充 +#### T-ACCESS-002：AllowFrom 伪造 | 属性 | 值 | | ----------------------- | ------------------------------------------------------------------------------ | | **ATLAS ID** | AML.T0040 - AI 模型推理 API 访问 | -| **描述** | 攻击者在渠道中冒充被允许的发送者身份 | -| **攻击向量** | 取决于渠道——电话号码冒充、用户名冒充 | -| **受影响组件** | 每个渠道的 AllowFrom 验证 | +| **描述** | 攻击者在渠道中伪造允许的发送方身份 | +| **攻击向量** | 取决于渠道——电话号码伪造、用户名冒充 | +| **受影响组件** | 各渠道的 AllowFrom 校验 | | **当前缓解措施** | 渠道特定的身份验证 | -| **残余风险** | 中 - 某些渠道容易受到冒充攻击 | -| **建议** | 记录渠道特定风险，并在可能时增加加密验证 | +| **残余风险** | 中等——某些渠道容易受到伪造攻击 | +| **建议** | 记录各渠道的特定风险，并在可能时加入密码学验证 | -#### T-ACCESS-003：token 窃取 +#### T-ACCESS-003：令牌窃取 | 属性 | 值 | | ----------------------- | ----------------------------------------------------------- | | **ATLAS ID** | AML.T0040 - AI 模型推理 API 访问 | -| **描述** | 攻击者从配置文件中窃取身份验证 token | +| **描述** | 攻击者从配置文件中窃取认证令牌 | | **攻击向量** | 恶意软件、未授权设备访问、配置备份泄露 | | **受影响组件** | `~/.openclaw/credentials/`、配置存储 | | **当前缓解措施** | 文件权限 | -| **残余风险** | 高 - Token 以明文存储 | -| **建议** | 实现静态 token 加密，增加 token 轮换 | +| **残余风险** | 高——令牌以明文存储 | +| **建议** | 实现静态令牌加密，并增加令牌轮换机制 | --- -### 3.3 Execution（AML.TA0005） +### 3.3 执行（AML.TA0005） -#### T-EXEC-001：直接 Prompt Injection +#### T-EXEC-001：直接提示注入 | 属性 | 值 | | ----------------------- | ----------------------------------------------------------------------------------------- | -| **ATLAS ID** | AML.T0051.000 - LLM Prompt Injection：直接 | -| **描述** | 攻击者发送精心构造的提示以操纵智能体行为 | +| **ATLAS ID** | AML.T0051.000 - LLM 提示注入：直接 | +| **描述** | 攻击者发送精心构造的提示，以操纵智能体行为 | | **攻击向量** | 包含对抗性指令的渠道消息 | -| **受影响组件** | 智能体 LLM、所有输入表面 | +| **受影响组件** | 智能体 LLM、所有输入面 | | **当前缓解措施** | 模式检测、外部内容包装 | -| **残余风险** | 严重 - 仅做检测，没有阻断；复杂攻击可绕过 | -| **建议** | 实现多层防御、输出验证、对敏感操作进行用户确认 | +| **残余风险** | 严重——仅检测、不阻止；复杂攻击可绕过 | +| **建议** | 实现多层防御、输出校验，以及对敏感操作的用户确认 | -#### T-EXEC-002：间接 Prompt Injection +#### T-EXEC-002：间接提示注入 | 属性 | 值 | | ----------------------- | ----------------------------------------------------------- | -| **ATLAS ID** | AML.T0051.001 - LLM Prompt Injection：间接 | -| **描述** | 攻击者在获取的内容中嵌入恶意指令 | -| **攻击向量** | 恶意 URL、被污染的邮件、被攻陷的 webhook | +| **ATLAS ID** | AML.T0051.001 - LLM 提示注入：间接 | +| **描述** | 攻击者在抓取的内容中嵌入恶意指令 | +| **攻击向量** | 恶意 URL、被投毒的电子邮件、被攻陷的 Webhooks | | **受影响组件** | `web_fetch`、邮件摄取、外部数据源 | -| **当前缓解措施** | 使用 XML 标签和安全提示进行内容包装 | -| **残余风险** | 高 - LLM 可能忽略包装指令 | -| **建议** | 实现内容净化、分离执行上下文 | +| **当前缓解措施** | 使用 XML 标签进行内容包装并注入安全提示 | +| **残余风险** | 高——LLM 可能忽略包装指令 | +| **建议** | 实现内容净化，并分离执行上下文 | #### T-EXEC-003：工具参数注入 | 属性 | 值 | | ----------------------- | ------------------------------------------------------------ | -| **ATLAS ID** | AML.T0051.000 - LLM Prompt Injection：直接 | -| **描述** | 攻击者通过 prompt injection 操纵工具参数 | +| **ATLAS ID** | AML.T0051.000 - LLM 提示注入：直接 | +| **描述** | 攻击者通过提示注入操纵工具参数 | | **攻击向量** | 影响工具参数值的精心构造提示 | | **受影响组件** | 所有工具调用 | -| **当前缓解措施** | 对危险命令启用 exec 审批 | -| **残余风险** | 高 - 依赖用户判断 | -| **建议** | 实现参数验证、参数化工具调用 | +| **当前缓解措施** | 对危险命令使用执行审批 | +| **残余风险** | 高——依赖用户判断 | +| **建议** | 实现参数校验和参数化工具调用 | -#### T-EXEC-004：Exec 审批绕过 +#### T-EXEC-004：绕过执行审批 | 属性 | 值 | | ----------------------- | ---------------------------------------------------------- | | **ATLAS ID** | AML.T0043 - 构造对抗性数据 | -| **描述** | 攻击者构造命令以绕过审批 allowlist | +| **描述** | 攻击者构造可绕过审批允许列表的命令 | | **攻击向量** | 命令混淆、别名利用、路径操纵 | -| **受影响组件** | `exec-approvals.ts`、命令 allowlist | -| **当前缓解措施** | Allowlist + 询问模式 | -| **残余风险** | 高 - 没有命令净化 | -| **建议** | 实现命令规范化、扩展 blocklist | +| **受影响组件** | `exec-approvals.ts`、命令允许列表 | +| **当前缓解措施** | 允许列表 + 询问模式 | +| **残余风险** | 高——没有命令净化 | +| **建议** | 实现命令规范化，并扩展阻止列表 | --- -### 3.4 Persistence（AML.TA0006） +### 3.4 持久化（AML.TA0006） -#### T-PERSIST-001：恶意 Skill 安装 +#### T-PERSIST-001：恶意 Skills 安装 | 属性 | 值 | | ----------------------- | ------------------------------------------------------------------------ | -| **ATLAS ID** | AML.T0010.001 - 供应链攻陷：AI 软件 | -| **描述** | 攻击者向 ClawHub 发布恶意 Skill | -| **攻击向量** | 创建账号，发布包含隐藏恶意代码的 Skill | -| **受影响组件** | ClawHub、Skill 加载、智能体执行 | +| **ATLAS ID** | AML.T0010.001 - 供应链破坏：AI 软件 | +| **描述** | 攻击者向 ClawHub 发布恶意 Skills | +| **攻击向量** | 创建账号并发布带有隐藏恶意代码的 Skills | +| **受影响组件** | ClawHub、Skills 加载、智能体执行 | | **当前缓解措施** | GitHub 账号年龄验证、基于模式的审核标记 | -| **残余风险** | 严重 - 没有沙箱隔离，审查有限 | -| **建议** | VirusTotal 集成（进行中）、Skill 沙箱隔离、社区审查 | +| **残余风险** | 严重——没有沙箱隔离，审核有限 | +| **建议** | VirusTotal 集成（进行中）、Skills 沙箱隔离、社区审核 | -#### T-PERSIST-002：Skill 更新投毒 +#### T-PERSIST-002：Skills 更新投毒 | 属性 | 值 | | ----------------------- | -------------------------------------------------------------- | -| **ATLAS ID** | AML.T0010.001 - 供应链攻陷：AI 软件 | -| **描述** | 攻击者攻陷热门 Skill 并推送恶意更新 | -| **攻击向量** | 账号被攻陷、对 Skill 所有者进行社会工程 | -| **受影响组件** | ClawHub 版本控制、自动更新流程 | -| **当前缓解措施** | 版本指纹 | -| **残余风险** | 高 - 自动更新可能拉取恶意版本 | -| **建议** | 实现更新签名、回滚能力、版本锁定 | +| **ATLAS ID** | AML.T0010.001 - 供应链破坏：AI 软件 | +| **描述** | 攻击者攻陷热门 Skills 并推送恶意更新 | +| **攻击向量** | 账号被攻陷、对 Skills 所有者的社会工程 | +| **受影响组件** | ClawHub 版本管理、自动更新流程 | +| **当前缓解措施** | 版本指纹校验 | +| **残余风险** | 高——自动更新可能拉取恶意版本 | +| **建议** | 实现更新签名、回滚能力和版本固定 | #### T-PERSIST-003：智能体配置篡改 | 属性 | 值 | | ----------------------- | --------------------------------------------------------------- | -| **ATLAS ID** | AML.T0010.002 - 供应链攻陷：数据 | -| **描述** | 攻击者修改智能体配置以持久化访问权限 | +| **ATLAS ID** | AML.T0010.002 - 供应链破坏：数据 | +| **描述** | 攻击者修改智能体配置以维持持久访问 | | **攻击向量** | 配置文件修改、设置注入 | | **受影响组件** | 智能体配置、工具策略 | | **当前缓解措施** | 文件权限 | -| **残余风险** | 中 - 需要本地访问 | -| **建议** | 配置完整性验证、为配置变更增加审计日志 | +| **残余风险** | 中等——需要本地访问权限 | +| **建议** | 配置完整性校验，并为配置更改增加审计日志 | --- -### 3.5 Defense Evasion（AML.TA0007） +### 3.5 防御规避（AML.TA0007） -#### T-EVADE-001：审核模式绕过 +#### T-EVADE-001：绕过审核模式 | 属性 | 值 | | ----------------------- | ---------------------------------------------------------------------- | | **ATLAS ID** | AML.T0043 - 构造对抗性数据 | -| **描述** | 攻击者构造 Skill 内容以绕过审核模式 | -| **攻击向量** | Unicode 同形异义字、编码技巧、动态加载 | -| **受影响组件** | `ClawHub moderation.ts` | +| **描述** | 攻击者构造 Skills 内容以绕过审核模式 | +| **攻击向量** | Unicode 同形异义字符、编码技巧、动态加载 | +| **受影响组件** | ClawHub `moderation.ts` | | **当前缓解措施** | 基于模式的 `FLAG_RULES` | -| **残余风险** | 高 - 简单 regex 很容易绕过 | +| **残余风险** | 高——简单正则很容易被绕过 | | **建议** | 增加行为分析（VirusTotal Code Insight）、基于 AST 的检测 | #### T-EVADE-002：内容包装逃逸 @@ -335,12 +335,12 @@ x-i18n: | **攻击向量** | 标签操纵、上下文混淆、指令覆盖 | | **受影响组件** | 外部内容包装 | | **当前缓解措施** | XML 标签 + 安全提示 | -| **残余风险** | 中 - 新型逃逸方式不断被发现 | -| **建议** | 多层包装、输出侧验证 | +| **残余风险** | 中等——新的逃逸方式会被持续发现 | +| **建议** | 使用多层包装，并加入输出侧校验 | --- -### 3.6 Discovery（AML.TA0008） +### 3.6 发现（AML.TA0008） #### T-DISC-001：工具枚举 @@ -348,11 +348,11 @@ x-i18n: | ----------------------- | ----------------------------------------------------- | | **ATLAS ID** | AML.T0040 - AI 模型推理 API 访问 | | **描述** | 攻击者通过提示枚举可用工具 | -| **攻击向量** | “你有哪些工具？”之类的查询 | +| **攻击向量** | 类似 “What tools do you have?” 的查询 | | **受影响组件** | 智能体工具注册表 | | **当前缓解措施** | 无特定措施 | -| **残余风险** | 低 - 工具通常已有文档 | -| **建议** | 考虑加入工具可见性控制 | +| **残余风险** | 低——工具通常已有文档说明 | +| **建议** | 可考虑增加工具可见性控制 | #### T-DISC-002：会话数据提取 @@ -360,55 +360,55 @@ x-i18n: | ----------------------- | ----------------------------------------------------- | | **ATLAS ID** | AML.T0040 - AI 模型推理 API 访问 | | **描述** | 攻击者从会话上下文中提取敏感数据 | -| **攻击向量** | “我们讨论过什么？”之类的查询、上下文探测 | +| **攻击向量** | 类似 “What did we discuss?” 的查询、上下文探测 | | **受影响组件** | 会话转录、上下文窗口 | -| **当前缓解措施** | 按发送者进行会话隔离 | -| **残余风险** | 中 - 会话内数据可被访问 | +| **当前缓解措施** | 按发送方进行会话隔离 | +| **残余风险** | 中等——会话内数据可被访问 | | **建议** | 在上下文中实现敏感数据脱敏 | --- -### 3.7 Collection & Exfiltration（AML.TA0009, AML.TA0010） +### 3.7 收集与外泄（AML.TA0009、AML.TA0010） -#### T-EXFIL-001：通过 `web_fetch` 进行数据窃取 +#### T-EXFIL-001：通过 `web_fetch` 窃取数据 | 属性 | 值 | | ----------------------- | ---------------------------------------------------------------------- | | **ATLAS ID** | AML.T0009 - 收集 | -| **描述** | 攻击者通过指示智能体向外部 URL 发送数据来窃取数据 | -| **攻击向量** | Prompt injection 导致智能体向攻击者服务器 POST 数据 | +| **描述** | 攻击者指示智能体将数据发送到外部 URL，从而实现数据外泄 | +| **攻击向量** | 通过提示注入使智能体向攻击者服务器 POST 数据 | | **受影响组件** | `web_fetch` 工具 | -| **当前缓解措施** | 对内部网络的 SSRF 阻断 | -| **残余风险** | 高 - 外部 URL 仍被允许 | -| **建议** | 实现 URL allowlist、数据分类感知 | +| **当前缓解措施** | 对内部网络进行 SSRF 阻止 | +| **残余风险** | 高——外部 URL 仍被允许 | +| **建议** | 实现 URL 允许列表，并增强数据分类感知 | #### T-EXFIL-002：未授权消息发送 | 属性 | 值 | | ----------------------- | ---------------------------------------------------------------- | | **ATLAS ID** | AML.T0009 - 收集 | -| **描述** | 攻击者让智能体发送包含敏感数据的消息 | -| **攻击向量** | Prompt injection 导致智能体给攻击者发消息 | +| **描述** | 攻击者使智能体发送包含敏感数据的消息 | +| **攻击向量** | 通过提示注入让智能体向攻击者发送消息 | | **受影响组件** | 消息工具、渠道集成 | | **当前缓解措施** | 出站消息门控 | -| **残余风险** | 中 - 门控可能被绕过 | -| **建议** | 对新收件人要求显式确认 | +| **残余风险** | 中等——门控机制可能被绕过 | +| **建议** | 对新收件人强制要求显式确认 | -#### T-EXFIL-003：凭据收集 +#### T-EXFIL-003：凭证收集 | 属性 | 值 | | ----------------------- | ------------------------------------------------------- | | **ATLAS ID** | AML.T0009 - 收集 | -| **描述** | 恶意 Skill 从智能体上下文中收集凭据 | -| **攻击向量** | Skill 代码读取环境变量、配置文件 | -| **受影响组件** | Skill 执行环境 | -| **当前缓解措施** | 对 Skills 无专门措施 | -| **残余风险** | 严重 - Skills 以智能体权限运行 | -| **建议** | Skill 沙箱隔离、凭据隔离 | +| **描述** | 恶意 Skills 从智能体上下文中收集凭证 | +| **攻击向量** | Skills 代码读取环境变量和配置文件 | +| **受影响组件** | Skills 执行环境 | +| **当前缓解措施** | 没有专门针对 Skills 的措施 | +| **残余风险** | 严重——Skills 以智能体权限运行 | +| **建议** | Skills 沙箱隔离、凭证隔离 | --- -### 3.8 Impact（AML.TA0011） +### 3.8 影响（AML.TA0011） #### T-IMPACT-001：未授权命令执行 @@ -416,35 +416,35 @@ x-i18n: | ----------------------- | --------------------------------------------------- | | **ATLAS ID** | AML.T0031 - 削弱 AI 模型完整性 | | **描述** | 攻击者在用户系统上执行任意命令 | -| **攻击向量** | Prompt injection 与 exec 审批绕过相结合 | +| **攻击向量** | 提示注入结合执行审批绕过 | | **受影响组件** | Bash 工具、命令执行 | -| **当前缓解措施** | Exec 审批、Docker 沙箱选项 | -| **残余风险** | 严重 - 未在沙箱中执行主机命令 | -| **建议** | 默认使用沙箱，改进审批 UX | +| **当前缓解措施** | 执行审批、Docker 沙箱选项 | +| **残余风险** | 严重——未启用沙箱时会在主机上执行 | +| **建议** | 默认启用沙箱，并改进审批 UX | #### T-IMPACT-002：资源耗尽（DoS） | 属性 | 值 | | ----------------------- | -------------------------------------------------- | | **ATLAS ID** | AML.T0031 - 削弱 AI 模型完整性 | -| **描述** | 攻击者耗尽 API 积分或计算资源 | +| **描述** | 攻击者耗尽 API 额度或计算资源 | | **攻击向量** | 自动化消息洪泛、高成本工具调用 | -| **受影响组件** | Gateway 网关、智能体会话、API provider | +| **受影响组件** | Gateway 网关、智能体会话、API 提供商 | | **当前缓解措施** | 无 | -| **残余风险** | 高 - 没有速率限制 | -| **建议** | 实现按发送者限速、成本预算 | +| **残余风险** | 高——没有速率限制 | +| **建议** | 实现按发送方的速率限制和成本预算 | #### T-IMPACT-003：声誉损害 | 属性 | 值 | | ----------------------- | ------------------------------------------------------- | | **ATLAS ID** | AML.T0031 - 削弱 AI 模型完整性 | -| **描述** | 攻击者导致智能体发送有害/冒犯性内容 | -| **攻击向量** | Prompt injection 导致不恰当响应 | +| **描述** | 攻击者使智能体发送有害或冒犯性内容 | +| **攻击向量** | 通过提示注入诱导不当回复 | | **受影响组件** | 输出生成、渠道消息发送 | -| **当前缓解措施** | LLM provider 内容策略 | -| **残余风险** | 中 - Provider 过滤并不完美 | -| **建议** | 增加输出过滤层、用户控制 | +| **当前缓解措施** | LLM 提供商的内容策略 | +| **残余风险** | 中等——提供商过滤并不完美 | +| **建议** | 增加输出过滤层和用户控制 | --- @@ -454,17 +454,17 @@ x-i18n: | 控制项 | 实现方式 | 有效性 | | -------------------- | --------------------------- | ---------------------------------------------------- | -| GitHub 账号年龄 | `requireGitHubAccountAge()` | 中 - 提高了新攻击者的门槛 | -| 路径净化 | `sanitizePath()` | 高 - 防止路径遍历 | -| 文件类型验证 | `isTextFile()` | 中 - 仅限文本文件，但仍可能是恶意内容 | -| 大小限制 | 50MB 总 bundle | 高 - 防止资源耗尽 | -| 必需的 `SKILL.md` | 强制 readme | 安全价值低 - 仅提供信息 | -| 模式审核 | `moderation.ts` 中的 `FLAG_RULES` | 低 - 很容易绕过 | -| 审核状态 | `moderationStatus` 字段 | 中 - 可进行人工审核 | +| GitHub 账号年龄 | `requireGitHubAccountAge()` | 中等——提高了新攻击者的门槛 | +| 路径净化 | `sanitizePath()` | 高——防止路径遍历 | +| 文件类型校验 | `isTextFile()` | 中等——仅允许文本文件，但仍可能包含恶意内容 | +| 大小限制 | 50 MB 总 bundle | 高——防止资源耗尽 | +| 必需的 `SKILL.md` | 必填 readme | 安全价值低——仅提供信息说明 | +| 模式审核 | `moderation.ts` 中的 `FLAG_RULES` | 低——容易被绕过 | +| 审核状态 | `moderationStatus` 字段 | 中等——可进行人工审核 | ### 4.2 审核标记模式 -`moderation.ts` 中的当前模式： +`moderation.ts` 中当前的模式： ```javascript // Known-bad identifiers @@ -481,19 +481,19 @@ x-i18n: **局限性：** -- 只检查 slug、displayName、summary、frontmatter、metadata、文件路径 -- 不分析实际的 Skill 代码内容 -- 简单 regex 很容易通过混淆绕过 +- 仅检查 slug、displayName、summary、frontmatter、metadata、文件路径 +- 不分析实际的 Skills 代码内容 +- 简单正则很容易通过混淆绕过 - 没有行为分析 ### 4.3 计划中的改进 | 改进项 | 状态 | 影响 | | ---------------------- | ------------------------------------- | --------------------------------------------------------------------- | -| VirusTotal 集成 | 进行中 | 高 - Code Insight 行为分析 | -| 社区举报 | 部分（`skillReports` 表已存在） | 中 | -| 审计日志 | 部分（`auditLogs` 表已存在） | 中 | -| 徽章系统 | 已实现 | 中 - `highlighted`、`official`、`deprecated`、`redactionApproved` | +| VirusTotal 集成 | 进行中 | 高——提供 Code Insight 行为分析 | +| 社区举报 | 部分实现（已存在 `skillReports` 表） | 中等 | +| 审计日志 | 部分实现（已存在 `auditLogs` 表） | 中等 | +| 徽章系统 | 已实现 | 中等——`highlighted`、`official`、`deprecated`、`redactionApproved` | --- @@ -501,73 +501,73 @@ x-i18n: ### 5.1 可能性与影响 -| 威胁 ID | 可能性 | 影响 | 风险级别 | 优先级 | +| 威胁 ID | 可能性 | 影响 | 风险等级 | 优先级 | | ------------- | ---------- | -------- | ------------ | -------- | | T-EXEC-001 | 高 | 严重 | **严重** | P0 | | T-PERSIST-001 | 高 | 严重 | **严重** | P0 | -| T-EXFIL-003 | 中 | 严重 | **严重** | P0 | -| T-IMPACT-001 | 中 | 严重 | **高** | P1 | +| T-EXFIL-003 | 中等 | 严重 | **严重** | P0 | +| T-IMPACT-001 | 中等 | 严重 | **高** | P1 | | T-EXEC-002 | 高 | 高 | **高** | P1 | -| T-EXEC-004 | 中 | 高 | **高** | P1 | -| T-ACCESS-003 | 中 | 高 | **高** | P1 | -| T-EXFIL-001 | 中 | 高 | **高** | P1 | -| T-IMPACT-002 | 高 | 中 | **高** | P1 | -| T-EVADE-001 | 高 | 中 | **中** | P2 | -| T-ACCESS-001 | 低 | 高 | **中** | P2 | -| T-ACCESS-002 | 低 | 高 | **中** | P2 | -| T-PERSIST-002 | 低 | 高 | **中** | P2 | +| T-EXEC-004 | 中等 | 高 | **高** | P1 | +| T-ACCESS-003 | 中等 | 高 | **高** | P1 | +| T-EXFIL-001 | 中等 | 高 | **高** | P1 | +| T-IMPACT-002 | 高 | 中等 | **高** | P1 | +| T-EVADE-001 | 高 | 中等 | **中等** | P2 | +| T-ACCESS-001 | 低 | 高 | **中等** | P2 | +| T-ACCESS-002 | 低 | 高 | **中等** | P2 | +| T-PERSIST-002 | 低 | 高 | **中等** | P2 | ### 5.2 关键路径攻击链 -**攻击链 1：基于 Skill 的数据窃取** +**攻击链 1：基于 Skills 的数据窃取** -``` +```text T-PERSIST-001 → T-EVADE-001 → T-EXFIL-003 -（发布恶意 Skill）→（绕过审核）→（收集凭据） +（发布恶意 Skills）→（绕过审核）→（收集凭证） ``` -**攻击链 2：从 Prompt Injection 到 RCE** +**攻击链 2：提示注入到远程代码执行** -``` +```text T-EXEC-001 → T-EXEC-004 → T-IMPACT-001 -（注入提示）→（绕过 exec 审批）→（执行命令） +（注入提示）→（绕过执行审批）→（执行命令） ``` -**攻击链 3：通过获取内容进行间接注入** +**攻击链 3：通过抓取内容进行间接注入** -``` +```text T-EXEC-002 → T-EXFIL-001 → 外部数据外泄 -（污染 URL 内容）→（智能体抓取并遵循指令）→（将数据发送给攻击者） +（投毒 URL 内容）→（智能体抓取并遵循指令）→（数据发送给攻击者） ``` --- ## 6. 建议摘要 -### 6.1 立即（P0） +### 6.1 立即执行（P0） | ID | 建议 | 解决的问题 | | ----- | ------------------------------------------- | -------------------------- | -| R-001 | 完成 VirusTotal 集成 | T-PERSIST-001, T-EVADE-001 | -| R-002 | 实现 Skill 沙箱隔离 | T-PERSIST-001, T-EXFIL-003 | -| R-003 | 为敏感操作添加输出验证 | T-EXEC-001, T-EXEC-002 | +| R-001 | 完成 VirusTotal 集成 | T-PERSIST-001、T-EVADE-001 | +| R-002 | 实现 Skills 沙箱隔离 | T-PERSIST-001、T-EXFIL-003 | +| R-003 | 为敏感操作增加输出校验 | T-EXEC-001、T-EXEC-002 | ### 6.2 短期（P1） | ID | 建议 | 解决的问题 | | ----- | ---------------------------------------- | ------------ | | R-004 | 实现速率限制 | T-IMPACT-002 | -| R-005 | 为静态 token 添加加密 | T-ACCESS-003 | -| R-006 | 改进 exec 审批 UX 和验证 | T-EXEC-004 | -| R-007 | 为 `web_fetch` 实现 URL allowlisting | T-EXFIL-001 | +| R-005 | 增加静态令牌加密 | T-ACCESS-003 | +| R-006 | 改进执行审批 UX 和校验 | T-EXEC-004 | +| R-007 | 为 `web_fetch` 实现 URL 允许列表 | T-EXFIL-001 | ### 6.3 中期（P2） | ID | 建议 | 解决的问题 | | ----- | ----------------------------------------------------- | ------------- | -| R-008 | 在可能的情况下添加加密渠道验证 | T-ACCESS-002 | -| R-009 | 实现配置完整性验证 | T-PERSIST-003 | -| R-010 | 添加更新签名和版本锁定 | T-PERSIST-002 | +| R-008 | 在可能的情况下增加密码学渠道验证 | T-ACCESS-002 | +| R-009 | 实现配置完整性校验 | T-PERSIST-003 | +| R-010 | 增加更新签名和版本固定 | T-PERSIST-002 | --- @@ -577,44 +577,44 @@ T-EXEC-002 → T-EXFIL-001 → 外部数据外泄 | ATLAS ID | 技术名称 | OpenClaw 威胁 | | ------------- | ------------------------------ | ---------------------------------------------------------------- | -| AML.T0006 | 主动扫描 | T-RECON-001, T-RECON-002 | -| AML.T0009 | 收集 | T-EXFIL-001, T-EXFIL-002, T-EXFIL-003 | -| AML.T0010.001 | 供应链：AI 软件 | T-PERSIST-001, T-PERSIST-002 | +| AML.T0006 | 主动扫描 | T-RECON-001、T-RECON-002 | +| AML.T0009 | 收集 | T-EXFIL-001、T-EXFIL-002、T-EXFIL-003 | +| AML.T0010.001 | 供应链：AI 软件 | T-PERSIST-001、T-PERSIST-002 | | AML.T0010.002 | 供应链：数据 | T-PERSIST-003 | -| AML.T0031 | 削弱 AI 模型完整性 | T-IMPACT-001, T-IMPACT-002, T-IMPACT-003 | -| AML.T0040 | AI 模型推理 API 访问 | T-ACCESS-001, T-ACCESS-002, T-ACCESS-003, T-DISC-001, T-DISC-002 | -| AML.T0043 | 构造对抗性数据 | T-EXEC-004, T-EVADE-001, T-EVADE-002 | -| AML.T0051.000 | LLM Prompt Injection：直接 | T-EXEC-001, T-EXEC-003 | -| AML.T0051.001 | LLM Prompt Injection：间接 | T-EXEC-002 | +| AML.T0031 | 削弱 AI 模型完整性 | T-IMPACT-001、T-IMPACT-002、T-IMPACT-003 | +| AML.T0040 | AI 模型推理 API 访问 | T-ACCESS-001、T-ACCESS-002、T-ACCESS-003、T-DISC-001、T-DISC-002 | +| AML.T0043 | 构造对抗性数据 | T-EXEC-004、T-EVADE-001、T-EVADE-002 | +| AML.T0051.000 | LLM 提示注入：直接 | T-EXEC-001、T-EXEC-003 | +| AML.T0051.001 | LLM 提示注入：间接 | T-EXEC-002 | ### 7.2 关键安全文件 -| 路径 | 用途 | 风险级别 | +| 路径 | 用途 | 风险等级 | | ----------------------------------- | --------------------------- | ------------ | -| `src/infra/exec-approvals.ts` | 命令审批逻辑 | **Critical** | -| `src/gateway/auth.ts` | Gateway 网关身份验证 | **Critical** | -| `src/infra/net/ssrf.ts` | SSRF 防护 | **Critical** | -| `src/security/external-content.ts` | Prompt injection 缓解 | **Critical** | -| `src/agents/sandbox/tool-policy.ts` | 工具策略执行 | **Critical** | -| `src/routing/resolve-route.ts` | 会话隔离 | **Medium** | +| `src/infra/exec-approvals.ts` | 命令审批逻辑 | **严重** | +| `src/gateway/auth.ts` | Gateway 网关认证 | **严重** | +| `src/infra/net/ssrf.ts` | SSRF 保护 | **严重** | +| `src/security/external-content.ts` | 提示注入缓解 | **严重** | +| `src/agents/sandbox/tool-policy.ts` | 工具策略强制执行 | **严重** | +| `src/routing/resolve-route.ts` | 会话隔离 | **中等** | ### 7.3 术语表 | 术语 | 定义 | | -------------------- | --------------------------------------------------------- | -| **ATLAS** | MITRE 的 AI 系统对抗性威胁版图 | +| **ATLAS** | MITRE 的面向 AI 系统的对抗性威胁态势框架 | | **ClawHub** | OpenClaw 的 Skills 市场 | -| **Gateway 网关** | OpenClaw 的消息路由和身份验证层 | -| **MCP** | Model Context Protocol —— 工具 provider 接口 | +| **Gateway 网关** | OpenClaw 的消息路由与认证层 | +| **MCP** | Model Context Protocol——工具提供商接口 | | **Prompt Injection** | 将恶意指令嵌入输入中的攻击 | -| **Skill** | OpenClaw 智能体的可下载扩展 | +| **Skill** | OpenClaw 智能体可下载的扩展 | | **SSRF** | 服务器端请求伪造 | --- -_此威胁模型是一份动态文档。请将安全问题报告至 security@openclaw.ai_ +_本威胁模型是一份持续演进的文档。如发现安全问题，请发送至 security@openclaw.ai_ ## 相关内容 -- [Formal verification](/zh-CN/security/formal-verification) -- [Contributing to the threat model](/zh-CN/security/CONTRIBUTING-THREAT-MODEL) +- [形式化验证](/zh-CN/security/formal-verification) +- [为威胁模型做贡献](/zh-CN/security/CONTRIBUTING-THREAT-MODEL) diff --git a/docs/zh-CN/tools/browser-linux-troubleshooting.md b/docs/zh-CN/tools/browser-linux-troubleshooting.md index f623410b5..bb628a45d 100644 --- a/docs/zh-CN/tools/browser-linux-troubleshooting.md +++ b/docs/zh-CN/tools/browser-linux-troubleshooting.md @@ -3,48 +3,48 @@ read_when: Browser control fails on Linux, especially with snap Chromium summary: 修复 Linux 上 OpenClaw 浏览器控制中 Chrome/Brave/Edge/Chromium 的 CDP 启动问题 title: 浏览器故障排除 x-i18n: - generated_at: "2026-04-25T19:10:41Z" + generated_at: "2026-04-27T07:13:16Z" model: gpt-5.4 provider: openai - source_hash: 69e5b42532af002af3d6a3ab21df7f82d2d62ce9f23b57a94cdb97e8ac65df3b + source_hash: d9a91ea42a8a600163bcf66ad398677175bd0c5186d3e1dddb629a55c2ea66ed source_path: tools/browser-linux-troubleshooting.md workflow: 15 --- -## 问题：“无法在端口 18800 上启动 Chrome CDP” +## 问题：“Failed to start Chrome CDP on port 18800” -OpenClaw 的浏览器控制服务器在启动 Chrome/Brave/Edge/Chromium 时失败，并显示以下错误： +OpenClaw 的浏览器控制服务器无法启动 Chrome/Brave/Edge/Chromium，并报错： -```json +``` {"error":"Error: Failed to start Chrome CDP on port 18800 for profile \"openclaw\"."} ``` ### 根本原因 -在 Ubuntu（以及许多 Linux 发行版）上，默认的 Chromium 安装是一个 **snap 软件包**。Snap 的 AppArmor 沙箱隔离会干扰 OpenClaw 启动和监控浏览器进程的方式。 +在 Ubuntu（以及许多 Linux 发行版）上，默认的 Chromium 安装是 **snap 包**。Snap 的 AppArmor 限制会干扰 OpenClaw 启动和监控浏览器进程的方式。 -`apt install chromium` 命令安装的是一个重定向到 snap 的存根软件包： +`apt install chromium` 命令安装的是一个会重定向到 snap 的占位包： -```bash +``` Note, selecting 'chromium-browser' instead of 'chromium' chromium-browser is already the newest version (2:1snap1-0ubuntu2). ``` 这**不是真正的浏览器**——它只是一个包装器。 -其他常见的 Linux 启动失败原因： +其他常见的 Linux 启动失败情况： -- `The profile appears to be in use by another Chromium process` 表示 Chrome 在受管配置目录中发现了过期的 `Singleton*` 锁文件。当锁指向一个已经退出的进程或不同主机上的进程时，OpenClaw 会移除这些锁并重试一次。 -- `Missing X server or $DISPLAY` 表示你在没有桌面会话的主机上明确请求启动可见浏览器。默认情况下，如果 `DISPLAY` 和 `WAYLAND_DISPLAY` 都未设置，本地受管配置现在会在 Linux 上回退为无头模式。如果你设置了 `OPENCLAW_BROWSER_HEADLESS=0`、`browser.headless: false` 或 `browser.profiles..headless: false`，请移除这个有头模式覆盖，设置 `OPENCLAW_BROWSER_HEADLESS=1`，启动 `Xvfb`，运行 `openclaw browser start --headless` 进行一次性受管启动，或在真实桌面会话中运行 OpenClaw。 +- `The profile appears to be in use by another Chromium process` 表示 Chrome 在受管配置目录中发现了残留的 `Singleton*` 锁文件。当该锁指向一个已退出或位于其他主机的进程时，OpenClaw 会移除这些锁并重试一次。 +- `Missing X server or $DISPLAY` 表示你在没有桌面会话的主机上显式请求了可见浏览器。默认情况下，在 Linux 上，如果 `DISPLAY` 和 `WAYLAND_DISPLAY` 都未设置，本地受管配置现在会回退为无头模式。如果你设置了 `OPENCLAW_BROWSER_HEADLESS=0`、`browser.headless: false` 或 `browser.profiles..headless: false`，请移除该有头模式覆盖，设置 `OPENCLAW_BROWSER_HEADLESS=1`，启动 `Xvfb`，使用 `openclaw browser start --headless` 执行一次性受管启动，或在真实桌面会话中运行 OpenClaw。 ### 解决方案 1：安装 Google Chrome（推荐） -安装官方的 Google Chrome `.deb` 软件包，它不会受到 snap 的沙箱限制： +安装官方的 Google Chrome `.deb` 包，它不受 snap 沙箱限制： ```bash wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb sudo dpkg -i google-chrome-stable_current_amd64.deb -sudo apt --fix-broken install -y # 如果有依赖错误 +sudo apt --fix-broken install -y # 如果出现依赖错误 ``` 然后更新你的 OpenClaw 配置（`~/.openclaw/openclaw.json`）： @@ -60,9 +60,9 @@ sudo apt --fix-broken install -y # 如果有依赖错误 } ``` -### 解决方案 2：对 Snap Chromium 使用仅附加模式 +### 解决方案 2：使用 Snap Chromium 的仅附加模式 -如果你必须使用 snap 版 Chromium，请将 OpenClaw 配置为附加到手动启动的浏览器： +如果你必须使用 snap Chromium，请将 OpenClaw 配置为附加到手动启动的浏览器： 1. 更新配置： @@ -86,7 +86,7 @@ chromium-browser --headless --no-sandbox --disable-gpu \ about:blank & ``` -3. 可选：创建一个 systemd 用户服务来自动启动 Chrome： +3. 可选：创建一个 systemd 用户服务，以便自动启动 Chrome： ```ini # ~/.config/systemd/user/openclaw-browser.service @@ -103,7 +103,7 @@ RestartSec=5 WantedBy=default.target ``` -启用方式：`systemctl --user enable --now openclaw-browser.service` +使用以下命令启用：`systemctl --user enable --now openclaw-browser.service` ### 验证浏览器是否正常工作 @@ -122,40 +122,40 @@ curl -s http://127.0.0.1:18791/tabs ### 配置参考 -| 选项 | 说明 | 默认值 | +| 选项 | 说明 | 默认值 | | -------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------- | -| `browser.enabled` | 启用浏览器控制 | `true` | -| `browser.executablePath` | Chromium 内核浏览器二进制文件的路径（Chrome/Brave/Edge/Chromium） | 自动检测（如果默认浏览器基于 Chromium，则优先使用它） | -| `browser.headless` | 以无 GUI 模式运行 | `false` | -| `OPENCLAW_BROWSER_HEADLESS` | 针对本地受管浏览器无头模式的每进程覆盖 | 未设置 | -| `browser.noSandbox` | 添加 `--no-sandbox` 标志（某些 Linux 环境需要） | `false` | -| `browser.attachOnly` | 不启动浏览器，只附加到现有实例 | `false` | -| `browser.cdpPort` | Chrome DevTools Protocol 端口 | `18800` | -| `browser.localLaunchTimeoutMs` | 本地受管 Chrome 发现超时时间 | `15000` | -| `browser.localCdpReadyTimeoutMs` | 本地受管浏览器启动后 CDP 就绪超时时间 | `8000` | +| `browser.enabled` | 启用浏览器控制 | `true` | +| `browser.executablePath` | 基于 Chromium 的浏览器二进制路径（Chrome/Brave/Edge/Chromium） | 自动检测（优先选择默认浏览器，前提是其基于 Chromium） | +| `browser.headless` | 以无 GUI 模式运行 | `false` | +| `OPENCLAW_BROWSER_HEADLESS` | 针对本地受管浏览器无头模式的按进程覆盖 | 未设置 | +| `browser.noSandbox` | 添加 `--no-sandbox` 标志（某些 Linux 环境需要） | `false` | +| `browser.attachOnly` | 不启动浏览器，仅附加到现有浏览器 | `false` | +| `browser.cdpPort` | Chrome DevTools Protocol 端口 | `18800` | +| `browser.localLaunchTimeoutMs` | 本地受管 Chrome 发现超时时间 | `15000` | +| `browser.localCdpReadyTimeoutMs` | 本地受管启动后 CDP 就绪超时时间 | `8000` | -在 Raspberry Pi、较旧的 VPS 主机或较慢的存储环境中，如果 Chrome 需要更多时间来暴露其 CDP HTTP 端点，请提高 `browser.localLaunchTimeoutMs`。如果启动成功但 `openclaw browser start` 仍报告 `not reachable after start`，请提高 `browser.localCdpReadyTimeoutMs`。这些值必须是最大不超过 `120000` 毫秒的正整数；无效的配置值会被拒绝。 +在 Raspberry Pi、较老的 VPS 主机或存储较慢的环境中，如果 Chrome 需要更多时间来暴露其 CDP HTTP 端点，请提高 `browser.localLaunchTimeoutMs`。如果启动成功，但 `openclaw browser start` 仍然报告 `not reachable after start`，请提高 `browser.localCdpReadyTimeoutMs`。这些值必须是最大不超过 `120000` 毫秒的正整数；无效的配置值会被拒绝。 -### 问题：“未找到 profile=\"user\" 的 Chrome 标签页” +### 问题：“No Chrome tabs found for profile="user"” -你正在使用 `existing-session` / Chrome MCP 配置。OpenClaw 可以看到本地 Chrome，但没有可供附加的已打开标签页。 +你正在使用 `existing-session` / Chrome MCP 配置。OpenClaw 能看到本地 Chrome，但没有可供附加的已打开标签页。 -修复选项： +修复方式： 1. **使用受管浏览器：** `openclaw browser start --browser-profile openclaw` （或设置 `browser.defaultProfile: "openclaw"`）。 -2. **使用 Chrome MCP：** 确保本地 Chrome 正在运行，并且至少有一个打开的标签页，然后使用 `--browser-profile user` 重试。 +2. **使用 Chrome MCP：** 确保本地 Chrome 正在运行，并且至少打开了一个标签页，然后使用 `--browser-profile user` 重试。 说明： -- `user` 仅适用于主机本地。对于 Linux 服务器、容器或远程主机，优先使用 CDP 配置。 -- `user` / 其他 `existing-session` 配置会保留当前的 Chrome MCP 限制：基于 ref 的操作、单文件上传钩子、不支持对话框超时覆盖、不支持 `wait --load networkidle`，也不支持 `responsebody`、PDF 导出、下载拦截或批量操作。 -- 本地 `openclaw` 配置会自动分配 `cdpPort`/`cdpUrl`；只有远程 CDP 才需要手动设置这些值。 +- `user` 仅适用于宿主机。对于 Linux 服务器、容器或远程主机，请优先使用 CDP 配置。 +- `user` / 其他 `existing-session` 配置会保留当前 Chrome MCP 的限制：基于 ref 的操作、单文件上传钩子、不支持对话框超时覆盖、不支持 `wait --load networkidle`，以及不支持 `responsebody`、PDF 导出、下载拦截或批量操作。 +- 本地 `openclaw` 配置会自动分配 `cdpPort`/`cdpUrl`；只有远程 CDP 才需要设置这些值。 - 远程 CDP 配置接受 `http://`、`https://`、`ws://` 和 `wss://`。 - 对 `/json/version` 发现使用 HTTP(S)，或者在浏览器服务直接提供 DevTools socket URL 时使用 WS(S)。 + 当使用 `/json/version` 发现时请使用 HTTP(S)，如果你的浏览器服务直接提供 DevTools 套接字 URL，则使用 WS(S)。 ## 相关内容 - [浏览器](/zh-CN/tools/browser) - [浏览器登录](/zh-CN/tools/browser-login) -- [浏览器 WSL2 故障排除](/zh-CN/tools/browser-wsl2-windows-remote-cdp-troubleshooting) +- [Browser WSL2 故障排除](/zh-CN/tools/browser-wsl2-windows-remote-cdp-troubleshooting) diff --git a/docs/zh-CN/tools/browser.md b/docs/zh-CN/tools/browser.md index 35032ba52..f68f9bcef 100644 --- a/docs/zh-CN/tools/browser.md +++ b/docs/zh-CN/tools/browser.md @@ -1,38 +1,42 @@ --- read_when: - 添加由智能体控制的浏览器自动化 - - 排查为什么 openclaw 会干扰你自己的 Chrome + - 排查 openclaw 为什么会干扰你自己的 Chrome - 在 macOS 应用中实现浏览器设置和生命周期 summary: 集成式浏览器控制服务 + 操作命令 title: 浏览器（由 OpenClaw 管理） x-i18n: - generated_at: "2026-04-26T03:54:50Z" + generated_at: "2026-04-27T07:13:25Z" model: gpt-5.4 provider: openai - source_hash: aba4c06f351296145b7a282bb692c2d10dba0668f90aabf1d981fb18199c3d74 + source_hash: 0e576b013e49917b6d5b118c22d7b91a65e1f1997dc86eb51881ed30806dafe9 source_path: tools/browser.md workflow: 15 --- -OpenClaw 可以运行一个**专用的 Chrome / Brave / Edge / Chromium 配置文件**，由智能体控制。 -它与你的个人浏览器隔离，并通过 Gateway 网关内部的一个小型本地控制服务进行管理（仅限 loopback）。 +OpenClaw 可以运行一个由**专用 Chrome/Brave/Edge/Chromium 配置文件**组成的环境，并由智能体控制。 +它与你的个人浏览器隔离，并通过 Gateway 网关内部的一个小型本地 +控制服务进行管理（仅限 loopback）。 -面向初学者的理解： +新手视角： -- 可以把它看作一个**独立的、仅供智能体使用的浏览器**。 +- 可以把它理解为一个**单独的、仅供智能体使用的浏览器**。 - `openclaw` 配置文件**不会**触碰你的个人浏览器配置文件。 -- 智能体可以在一个安全通道中**打开标签页、读取页面、点击和输入**。 -- 内置的 `user` 配置文件会通过 Chrome MCP 附加到你真实的、已登录的 Chrome 会话。 +- 智能体可以在一条安全通道中**打开标签页、读取页面、点击和输入**。 +- 内置的 `user` 配置文件会通过 Chrome MCP 连接到你真实、已登录的 Chrome 会话。 ## 你将获得什么 - 一个名为 **openclaw** 的独立浏览器配置文件（默认使用橙色强调色）。 -- 可预测的标签页控制（列出 / 打开 / 聚焦 / 关闭）。 -- 智能体操作（点击 / 输入 / 拖动 / 选择）、快照、截图、PDF。 -- 一个内置的 `browser-automation` Skills，在启用浏览器插件时，它会教会智能体使用 snapshot、stable-tab、stale-ref 和 manual-blocker 恢复循环。 +- 可预测的标签页控制（列出/打开/聚焦/关闭）。 +- 智能体操作（点击/输入/拖动/选择）、快照、截图、PDF。 +- 一个内置的 `browser-automation` Skills，当浏览器 + 插件启用时，它会教智能体使用 snapshot、 + stable-tab、stale-ref 和 manual-blocker 恢复循环。 - 可选的多配置文件支持（`openclaw`、`work`、`remote` 等）。 -这个浏览器**不是**你的日常主浏览器。它是一个安全、隔离的表面，用于智能体自动化和验证。 +这个浏览器**不是**你的日常主力浏览器。它是一个安全、隔离的表面，用于 +智能体自动化和验证。 ## 快速开始 @@ -45,13 +49,15 @@ openclaw browser --browser-profile openclaw open https://example.com openclaw browser --browser-profile openclaw snapshot ``` -如果你看到“Browser disabled”，请在配置中启用它（见下文），然后重启 Gateway 网关。 +如果你看到“Browser disabled”，请在配置中启用它（见下文），然后重启 +Gateway 网关。 -如果根本没有 `openclaw browser`，或者智能体提示浏览器工具不可用，请跳转到 [缺少浏览器命令或工具](/zh-CN/tools/browser#missing-browser-command-or-tool)。 +如果根本没有 `openclaw browser`，或者智能体提示浏览器工具 +不可用，请跳转到 [缺少浏览器命令或工具](/zh-CN/tools/browser#missing-browser-command-or-tool)。 ## 插件控制 -默认的 `browser` 工具是一个内置插件。若要用另一个注册相同 `browser` 工具名的插件来替换它，请将其禁用： +默认的 `browser` 工具是一个内置插件。禁用它即可用另一个注册相同 `browser` 工具名称的插件来替换它： ```json5 { @@ -65,13 +71,16 @@ openclaw browser --browser-profile openclaw snapshot } ``` -默认情况下，需要同时设置 `plugins.entries.browser.enabled` **以及** `browser.enabled=true`。仅禁用插件会把 `openclaw browser` CLI、`browser.request` Gateway 网关方法、智能体工具和控制服务作为一个整体一并移除；你的 `browser.*` 配置会保持不变，以供替代实现使用。 +默认设置需要同时启用 `plugins.entries.browser.enabled` **和** `browser.enabled=true`。如果只禁用插件，会一次性移除 `openclaw browser` CLI、`browser.request` Gateway 网关方法、智能体工具和控制服务；你的 `browser.*` 配置会保持不变，以供替代方案使用。 -浏览器配置变更需要重启 Gateway 网关，以便插件重新注册其服务。 +浏览器配置变更需要重启 Gateway 网关，这样插件才能重新注册其服务。 ## 智能体指引 -工具配置文件说明：`tools.profile: "coding"` 包含 `web_search` 和 `web_fetch`，但不包含完整的 `browser` 工具。如果智能体或其生成的子智能体需要使用浏览器自动化，请在配置文件阶段加入 browser： +工具配置说明：`tools.profile: "coding"` 包含 `web_search` 和 +`web_fetch`，但不包含完整的 `browser` 工具。如果智能体或某个 +派生的子智能体需要使用浏览器自动化，请在 profile +阶段添加 browser： ```json5 { @@ -82,19 +91,26 @@ openclaw browser --browser-profile openclaw snapshot } ``` -对于单个智能体，使用 `agents.list[].tools.alsoAllow: ["browser"]`。 -仅设置 `tools.subagents.tools.allow: ["browser"]` 还不够，因为子智能体策略是在配置文件过滤之后才应用的。 +对于单个智能体，请使用 `agents.list[].tools.alsoAllow: ["browser"]`。 +仅设置 `tools.subagents.tools.allow: ["browser"]` 还不够，因为子智能体 +策略会在 profile 过滤之后才应用。 浏览器插件提供两层智能体指引： -- `browser` 工具描述中携带了始终启用的精简契约：选择正确的配置文件、在同一标签页中保持 refs、使用 `tabId` / 标签来定位标签页，以及在多步骤任务中加载浏览器 skill。 -- 内置的 `browser-automation` Skills 则提供更长的操作循环：先检查 status / tabs、给任务标签页打标签、在操作前创建 snapshot、在 UI 变化后重新创建快照、对 stale refs 恢复一次，并将登录 / 2FA / captcha 或 camera / microphone 阻塞报告为需要手动操作，而不是猜测。 +- `browser` 工具描述携带始终启用的精简契约：选择 + 正确的配置文件，在同一标签页上保留引用，使用 `tabId`/标签进行标签页 + 定位，并在多步骤工作时加载浏览器 skill。 +- 内置的 `browser-automation` skill 携带更长的操作循环： + 先检查状态/标签页，给任务标签页加标签，操作前先做快照，在 UI 变化后重新快照， + 过期引用恢复一次，并将登录/2FA/captcha 或 + 摄像头/麦克风阻塞报告为需要人工操作，而不是猜测。 -插件内置的 Skills 会在插件启用时列在智能体的可用 Skills 中。完整的 skill 指令按需加载，因此常规轮次不会承担全部 token 成本。 +当插件启用时，由插件内置的 Skills 会列在智能体的可用 Skills 中。 +完整的 skill 说明按需加载，因此日常轮次不会承担全部 token 成本。 ## 缺少浏览器命令或工具 -如果升级后 `openclaw browser` 变成未知命令、`browser.request` 缺失，或智能体报告浏览器工具不可用，通常原因是 `plugins.allow` 列表里没有包含 `browser`。把它加上： +如果升级后 `openclaw browser` 未知，`browser.request` 缺失，或者智能体报告浏览器工具不可用，通常原因是 `plugins.allow` 列表中未包含 `browser`。请添加它： ```json5 { @@ -104,20 +120,22 @@ openclaw browser --browser-profile openclaw snapshot } ``` -`browser.enabled=true`、`plugins.entries.browser.enabled=true` 和 `tools.alsoAllow: ["browser"]` 都不能替代 allowlist 成员资格——allowlist 控制插件加载，而工具策略只有在加载之后才会运行。完全移除 `plugins.allow` 也会恢复默认行为。 +`browser.enabled=true`、`plugins.entries.browser.enabled=true` 和 `tools.alsoAllow: ["browser"]` 不能替代允许列表成员资格——允许列表控制插件加载，而工具策略只会在加载后运行。完全移除 `plugins.allow` 也会恢复默认行为。 ## 配置文件：`openclaw` 与 `user` -- `openclaw`：受管理、隔离的浏览器（无需扩展）。 -- `user`：内置的 Chrome MCP 附加配置文件，用于连接你**真实已登录的 Chrome** 会话。 +- `openclaw`：受管、隔离的浏览器（无需扩展）。 +- `user`：内置的 Chrome MCP 附加配置文件，用于连接你**真实、已登录的 Chrome** + 会话。 对于智能体浏览器工具调用： - 默认：使用隔离的 `openclaw` 浏览器。 -- 当现有登录会话很重要，并且用户就在电脑前可以点击 / 批准任何附加提示时，优先使用 `profile="user"`。 -- 当你希望使用某个特定浏览器模式时，`profile` 是显式覆盖项。 +- 当现有登录会话很重要，并且用户 + 正在电脑前可以点击/批准任何附加提示时，优先使用 `profile="user"`。 +- 当你想指定某种浏览器模式时，`profile` 是显式覆盖项。 -如果你希望默认使用受管理模式，请设置 `browser.defaultProfile: "openclaw"`。 +如果你希望默认使用受管模式，请设置 `browser.defaultProfile: "openclaw"`。 ## 配置 @@ -126,23 +144,23 @@ openclaw browser --browser-profile openclaw snapshot ```json5 { browser: { - enabled: true, // default: true + enabled: true, // 默认：true 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"], }, - // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override - remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms) - remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms) - localLaunchTimeoutMs: 15000, // local managed Chrome discovery timeout (ms) - localCdpReadyTimeoutMs: 8000, // local managed post-launch CDP readiness timeout (ms) - actionTimeoutMs: 60000, // default browser act timeout (ms) + // cdpUrl: "http://127.0.0.1:18792", // 旧版单配置文件覆盖 + remoteCdpTimeoutMs: 1500, // 远程 CDP HTTP 超时（毫秒） + remoteCdpHandshakeTimeoutMs: 3000, // 远程 CDP WebSocket 握手超时（毫秒） + localLaunchTimeoutMs: 15000, // 本地受管 Chrome 发现超时（毫秒） + localCdpReadyTimeoutMs: 8000, // 本地受管启动后 CDP 就绪超时（毫秒） + actionTimeoutMs: 60000, // 默认浏览器 act 超时（毫秒） tabCleanup: { - enabled: true, // default: true - idleMinutes: 120, // set 0 to disable idle cleanup - maxTabsPerSession: 8, // set 0 to disable the per-session cap + enabled: true, // 默认：true + idleMinutes: 120, // 设为 0 以禁用空闲清理 + maxTabsPerSession: 8, // 设为 0 以禁用每会话上限 sweepMinutes: 5, }, defaultProfile: "openclaw", @@ -178,24 +196,31 @@ openclaw browser --browser-profile openclaw snapshot - + -- 控制服务绑定到 loopback，端口由 `gateway.port` 派生而来（默认 `18791` = gateway + 2）。覆盖 `gateway.port` 或 `OPENCLAW_GATEWAY_PORT` 会同步移动同一组派生端口。 -- 本地 `openclaw` 配置文件会自动分配 `cdpPort` / `cdpUrl`；只有远程 CDP 才需要设置这些。未设置时，`cdpUrl` 默认指向受管理的本地 CDP 端口。 -- `remoteCdpTimeoutMs` 适用于远程和 `attachOnly` CDP HTTP 可达性检查，以及打开标签页的 HTTP 请求；`remoteCdpHandshakeTimeoutMs` 适用于它们的 CDP WebSocket 握手。 -- `localLaunchTimeoutMs` 是本地启动的受管理 Chrome 进程暴露其 CDP HTTP 端点的时间预算。`localCdpReadyTimeoutMs` 是在发现该进程后，为 CDP websocket 就绪预留的后续时间预算。在 Raspberry Pi、低配 VPS 或较老硬件上，如果 Chromium 启动较慢，请提高这些值。取值必须是最大不超过 `120000` ms 的正整数；无效配置值会被拒绝。 -- `actionTimeoutMs` 是浏览器 `act` 请求在调用方未传入 `timeoutMs` 时的默认时间预算。客户端传输层会额外加上一个小的缓冲窗口，以便长时间等待能够完成，而不是在 HTTP 边界超时。 -- `tabCleanup` 是对主智能体浏览器会话所打开标签页的尽力清理。子智能体、cron 和 ACP 生命周期清理仍会在会话结束时关闭其显式跟踪的标签页；主会话会保留活跃标签页以供复用，然后在后台关闭空闲或超出上限的已跟踪标签页。 +- 控制服务绑定到 loopback，端口从 `gateway.port` 派生（默认 `18791` = gateway + 2）。覆盖 `gateway.port` 或 `OPENCLAW_GATEWAY_PORT` 会使同一族中的派生端口一起偏移。 +- 本地 `openclaw` 配置文件会自动分配 `cdpPort`/`cdpUrl`；只有远程 CDP 才需要设置这些值。未设置时，`cdpUrl` 默认使用受管本地 CDP 端口。 +- `remoteCdpTimeoutMs` 适用于远程和 `attachOnly` CDP HTTP 可达性 + 检查，以及打开标签页的 HTTP 请求；`remoteCdpHandshakeTimeoutMs` 适用于 + 它们的 CDP WebSocket 握手。 +- `localLaunchTimeoutMs` 是本地启动的受管 Chrome + 进程暴露其 CDP HTTP 端点的时间预算。`localCdpReadyTimeoutMs` 是 + 进程被发现后，CDP websocket 就绪的后续时间预算。 + 在 Raspberry Pi、低配 VPS 或较旧硬件上，如 Chromium + 启动较慢，请提高这些值。数值必须是正整数，且不超过 `120000` 毫秒；无效 + 配置值会被拒绝。 +- `actionTimeoutMs` 是浏览器 `act` 请求的默认时间预算，当调用方未传递 `timeoutMs` 时使用。客户端传输层会增加一个小的宽限窗口，以便长时间等待可以完成，而不是在 HTTP 边界处超时。 +- `tabCleanup` 是对主智能体浏览器会话所打开标签页的尽力清理。子智能体、cron 和 ACP 生命周期清理仍会在会话结束时关闭它们显式跟踪的标签页；主会话则会保留活动标签页以供复用，然后在后台关闭空闲或超额的已跟踪标签页。 -- 浏览器导航和打开标签页在导航前会经过 SSRF 防护，并在导航结束后的最终 `http(s)` URL 上尽力再次检查。 +- 浏览器导航和打开标签页会在导航前经过 SSRF 防护，并在最终 `http(s)` URL 上尽力再次检查。 - 在严格 SSRF 模式下，远程 CDP 端点发现和 `/json/version` 探测（`cdpUrl`）也会被检查。 -- Gateway 网关 / 提供商的 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 和 `NO_PROXY` 环境变量不会自动为 OpenClaw 管理的浏览器启用代理。默认情况下，受管理的 Chrome 直接启动，因此提供商代理设置不会削弱浏览器的 SSRF 检查。 -- 若要为受管理浏览器本身设置代理，请通过 `browser.extraArgs` 传入显式的 Chrome 代理参数，例如 `--proxy-server=...` 或 `--proxy-pac-url=...`。严格 SSRF 模式会阻止显式的浏览器代理路由，除非你有意启用了私有网络浏览器访问。 -- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认关闭；仅在你明确可信任私有网络浏览器访问时启用。 +- Gateway 网关/提供商的 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 和 `NO_PROXY` 环境变量不会自动为 OpenClaw 管理的浏览器设置代理。默认情况下，受管 Chrome 直接启动，因此提供商代理设置不会削弱浏览器 SSRF 检查。 +- 如需为受管浏览器本身设置代理，请通过 `browser.extraArgs` 传入显式的 Chrome 代理标志，例如 `--proxy-server=...` 或 `--proxy-pac-url=...`。除非你有意启用私有网络浏览器访问，否则严格 SSRF 模式会阻止显式浏览器代理路由。 +- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 默认关闭；仅当你明确信任私有网络浏览器访问时才启用。 - `browser.ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。 @@ -203,24 +228,30 @@ openclaw browser --browser-profile openclaw snapshot - `attachOnly: true` 表示绝不启动本地浏览器；仅在浏览器已运行时附加。 -- `headless` 可以在全局或每个本地受管理配置文件上设置。每配置文件的值会覆盖 `browser.headless`，因此一个本地启动的配置文件可以保持 headless，而另一个保持可见。 -- `POST /start?headless=true` 和 `openclaw browser start --headless` 会请求对本地受管理配置文件执行一次性的 headless 启动，而不会改写 `browser.headless` 或配置文件配置。现有会话、仅附加和远程 CDP 配置文件会拒绝该覆盖，因为 OpenClaw 不会启动这些浏览器进程。 -- 在没有 `DISPLAY` 或 `WAYLAND_DISPLAY` 的 Linux 主机上，如果环境或配置文件 / 全局配置都没有显式选择有界面模式，本地受管理配置文件会默认自动使用 headless。`openclaw browser status --json` 会将 `headlessSource` 报告为 `env`、`profile`、`config`、`request`、`linux-display-fallback` 或 `default`。 -- `OPENCLAW_BROWSER_HEADLESS=1` 会为当前进程强制本地受管理启动使用 headless。`OPENCLAW_BROWSER_HEADLESS=0` 会为普通启动强制使用有界面模式，并在 Linux 主机没有显示服务器时返回可操作的错误；显式的 `start --headless` 请求仍会在那一次启动中优先生效。 -- `executablePath` 可以在全局或每个本地受管理配置文件上设置。每配置文件的值会覆盖 `browser.executablePath`，因此不同的受管理配置文件可以启动不同的基于 Chromium 的浏览器。这两种形式都支持使用 `~` 表示你的操作系统主目录。 -- `color`（顶层和每配置文件）会为浏览器 UI 着色，便于你识别当前激活的是哪个配置文件。 -- 默认配置文件是 `openclaw`（受管理的独立模式）。使用 `defaultProfile: "user"` 可以切换为默认使用已登录的用户浏览器。 -- 自动检测顺序：若系统默认浏览器是基于 Chromium 的则优先使用它；否则按 Chrome → Brave → Edge → Chromium → Chrome Canary 的顺序检测。 -- `driver: "existing-session"` 使用 Chrome DevTools MCP，而不是原始 CDP。不要为该驱动设置 `cdpUrl`。 -- 当某个 existing-session 配置文件需要附加到非默认的 Chromium 用户配置文件（Brave、Edge 等）时，请设置 `browser.profiles..userDataDir`。该路径同样支持使用 `~` 表示你的操作系统主目录。 +- `headless` 可以全局设置，也可以按本地受管配置文件设置。按配置文件设置的值会覆盖 `browser.headless`，因此一个本地启动的配置文件可以保持 headless，而另一个仍然可见。 +- `POST /start?headless=true` 和 `openclaw browser start --headless` 会请求对本地受管配置文件进行一次性 headless 启动，而不会改写 `browser.headless` 或配置文件设置。existing-session、attach-only 和远程 CDP 配置文件会拒绝此覆盖，因为 OpenClaw 不会启动这些浏览器进程。 +- 在没有 `DISPLAY` 或 `WAYLAND_DISPLAY` 的 Linux 主机上，如果环境、配置文件或全局 + 配置都未显式选择有界面模式，则本地受管配置文件会自动默认使用 headless。`openclaw browser status --json` + 会将 `headlessSource` 报告为 `env`、`profile`、`config`、 + `request`、`linux-display-fallback` 或 `default`。 +- `OPENCLAW_BROWSER_HEADLESS=1` 会为当前进程强制本地受管启动使用 headless。`OPENCLAW_BROWSER_HEADLESS=0` 会为普通启动强制使用有界面模式，并在 Linux 主机没有显示服务器时返回可执行的错误；显式的 `start --headless` 请求在该次启动中仍然优先。 +- `executablePath` 可以全局设置，也可以按本地受管配置文件设置。按配置文件设置的值会覆盖 `browser.executablePath`，因此不同的受管配置文件可以启动不同的 Chromium 系浏览器。这两种形式都接受 `~` 作为你的操作系统主目录。 +- `color`（顶层和按配置文件）会为浏览器 UI 着色，以便你看到哪个配置文件处于活动状态。 +- 默认配置文件是 `openclaw`（受管独立模式）。使用 `defaultProfile: "user"` 可选择加入已登录用户浏览器。 +- 自动检测顺序：如果系统默认浏览器是 Chromium 系，则优先使用它；否则按 Chrome → Brave → Edge → Chromium → Chrome Canary 的顺序检测。 +- `driver: "existing-session"` 使用 Chrome DevTools MCP，而不是原始 CDP。不要为该 driver 设置 `cdpUrl`。 +- 当某个 existing-session 配置文件需要附加到非默认的 Chromium 用户配置文件（Brave、Edge 等）时，请设置 `browser.profiles..userDataDir`。该路径也接受 `~` 作为你的操作系统主目录。 -## 使用 Brave（或其他基于 Chromium 的浏览器） +## 使用 Brave 或其他基于 Chromium 的浏览器 -如果你的**系统默认**浏览器是基于 Chromium 的（Chrome / Brave / Edge 等），OpenClaw 会自动使用它。设置 `browser.executablePath` 可以覆盖自动检测。顶层和每配置文件的 `executablePath` 值都支持使用 `~` 表示你的操作系统主目录： +如果你的**系统默认**浏览器是基于 Chromium 的（Chrome/Brave/Edge 等）， +OpenClaw 会自动使用它。设置 `browser.executablePath` 可覆盖 +自动检测。顶层和按配置文件的 `executablePath` 值都接受 `~` +作为你的操作系统主目录： ```bash openclaw config set browser.executablePath "/usr/bin/google-chrome" @@ -259,46 +290,59 @@ openclaw config set browser.profiles.work.executablePath "/Applications/Google C -每个配置文件的 `executablePath` 只会影响由 OpenClaw 启动的本地受管理配置文件。`existing-session` 配置文件会附加到一个已经在运行的浏览器，而远程 CDP 配置文件则使用 `cdpUrl` 背后的浏览器。 +按配置文件设置的 `executablePath` 仅影响 OpenClaw +启动的本地受管配置文件。`existing-session` 配置文件会附加到已在运行的浏览器， +而远程 CDP 配置文件则使用 `cdpUrl` 背后的浏览器。 ## 本地控制与远程控制 -- **本地控制（默认）：** Gateway 网关会启动 loopback 控制服务，并且可以启动本地浏览器。 -- **远程控制（节点主机）：** 在拥有浏览器的机器上运行节点主机；Gateway 网关会将浏览器操作代理到该节点主机。 -- **远程 CDP：** 设置 `browser.profiles..cdpUrl`（或 `browser.cdpUrl`）以附加到远程的基于 Chromium 的浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。 -- 对于运行在 loopback 上、由外部管理的 CDP 服务（例如在 Docker 中运行并发布到 `127.0.0.1` 的 Browserless），还需要设置 `attachOnly: true`。如果 loopback CDP 没有设置 `attachOnly`，它会被视为本地由 OpenClaw 管理的浏览器配置文件。 -- `headless` 只影响由 OpenClaw 启动的本地受管理配置文件。它不会重启或更改 existing-session 或远程 CDP 浏览器。 -- `executablePath` 也遵循相同的本地受管理配置文件规则。在一个正在运行的本地受管理配置文件上更改它时，该配置文件会被标记为需要重启 / 协调，以便下次启动时使用新的二进制文件。 +- **本地控制（默认）：** Gateway 网关启动 loopback 控制服务，并可启动本地浏览器。 +- **远程控制（节点主机）：** 在安装浏览器的机器上运行节点主机；Gateway 网关将浏览器操作代理到该节点主机。 +- **远程 CDP：** 设置 `browser.profiles..cdpUrl`（或 `browser.cdpUrl`）以 + 附加到远程的 Chromium 系浏览器。在这种情况下，OpenClaw 不会启动本地浏览器。 +- 对于运行在 loopback 上的外部托管 CDP 服务（例如在 Docker 中发布到 `127.0.0.1` 的 Browserless），还应设置 `attachOnly: true`。没有 `attachOnly` 的 loopback CDP 会被视为本地 OpenClaw 受管浏览器配置文件。 +- `headless` 仅影响 OpenClaw 启动的本地受管配置文件。它不会重启或更改 existing-session 或远程 CDP 浏览器。 +- `executablePath` 也遵循相同的本地受管配置文件规则。对运行中的本地受管配置文件修改该值时，会将该配置文件标记为需要重启/协调，以便下次启动时使用新的二进制文件。 -停止行为会因配置文件模式而异： +不同配置文件模式的停止行为不同： -- 本地受管理配置文件：`openclaw browser stop` 会停止由 OpenClaw 启动的浏览器进程 -- 仅附加和远程 CDP 配置文件：`openclaw browser stop` 会关闭当前控制会话，并释放 Playwright / CDP 模拟覆盖项（viewport、color scheme、locale、timezone、offline mode 及类似状态），即使并没有由 OpenClaw 启动任何浏览器进程 +- 本地受管配置文件：`openclaw browser stop` 会停止 + 由 OpenClaw 启动的浏览器进程 +- attach-only 和远程 CDP 配置文件：`openclaw browser stop` 会关闭活动的 + 控制会话，并释放 Playwright/CDP 仿真覆盖（视口、 + 配色方案、区域设置、时区、离线模式及类似状态），即使 + 没有由 OpenClaw 启动任何浏览器进程 远程 CDP URL 可以包含认证信息： -- 查询参数 token（例如 `https://provider.example?token=`） -- HTTP Basic auth（例如 `https://user:pass@provider.example`） +- 查询参数令牌（例如 `https://provider.example?token=`） +- HTTP Basic 认证（例如 `https://user:pass@provider.example`） -OpenClaw 会在调用 `/json/*` 端点以及连接到 CDP WebSocket 时保留这些认证信息。对于 token，优先使用环境变量或 secrets manager，而不是将其提交到配置文件中。 +OpenClaw 在调用 `/json/*` 端点以及连接 +CDP WebSocket 时会保留这些认证信息。对于 +令牌，优先使用环境变量或密钥管理器，而不是将它们提交到配置文件中。 ## 节点浏览器代理（默认零配置） -如果你在拥有浏览器的机器上运行**节点主机**，OpenClaw 可以在无需任何额外浏览器配置的情况下，自动将浏览器工具调用路由到该节点。这是远程 Gateway 网关的默认路径。 +如果你在安装有浏览器的机器上运行**节点主机**，OpenClaw 可以 +自动将浏览器工具调用路由到该节点，而无需任何额外浏览器配置。 +这是远程 Gateway 网关的默认路径。 说明： -- 节点主机会通过一个**代理命令**暴露其本地浏览器控制服务器。 +- 节点主机会通过一个**代理命令**公开其本地浏览器控制服务器。 - 配置文件来自节点自身的 `browser.profiles` 配置（与本地相同）。 -- `nodeHost.browserProxy.allowProfiles` 是可选的。将其留空可保留旧版 / 默认行为：所有已配置的配置文件都可通过代理访问，包括配置文件创建 / 删除路由。 -- 如果你设置了 `nodeHost.browserProxy.allowProfiles`，OpenClaw 会将其视为最小权限边界：只有 allowlist 中的配置文件可以被指定，并且持久化配置文件的创建 / 删除路由会在代理表面被阻止。 -- 如果你不想启用它，可以禁用： +- `nodeHost.browserProxy.allowProfiles` 是可选的。留空可保持旧版/默认行为：所有已配置的配置文件都可通过代理访问，包括配置文件创建/删除路由。 +- 如果你设置了 `nodeHost.browserProxy.allowProfiles`，OpenClaw 会将其视为最小权限边界：只有允许列表中的配置文件可被定位，持久化配置文件的创建/删除路由会在代理接口上被阻止。 +- 如果你不想启用它，可将其禁用： - 在节点上：`nodeHost.browserProxy.enabled=false` - 在 gateway 上：`gateway.nodes.browser.mode="off"` ## Browserless（托管远程 CDP） -[Browserless](https://browserless.io) 是一个托管的 Chromium 服务，通过 HTTPS 和 WebSocket 暴露 CDP 连接 URL。OpenClaw 可以使用任一种形式，但对于远程浏览器配置文件来说，最简单的选项通常是 Browserless 连接文档中给出的直接 WebSocket URL。 +[Browserless](https://browserless.io) 是一个托管的 Chromium 服务，通过 HTTPS 和 WebSocket 公开 +CDP 连接 URL。OpenClaw 可以使用任一形式，但对于远程浏览器配置文件， +最简单的选项是使用 Browserless 连接文档中的直接 WebSocket URL。 示例： @@ -321,13 +365,16 @@ OpenClaw 会在调用 `/json/*` 端点以及连接到 CDP WebSocket 时保留这 说明： -- 将 `` 替换为你真实的 Browserless token。 -- 选择与你的 Browserless 账户匹配的区域端点（见其文档）。 -- 如果 Browserless 给你的是 HTTPS 基础 URL，你可以将其转换为 `wss://` 来建立直接 CDP 连接，或者保留该 HTTPS URL，让 OpenClaw 去发现 `/json/version`。 +- 将 `` 替换为你真实的 Browserless 令牌。 +- 选择与你的 Browserless 账户匹配的区域端点（参见其文档）。 +- 如果 Browserless 提供给你的是 HTTPS 基础 URL，你可以将其转换为 + `wss://` 用于直接 CDP 连接，也可以保留 HTTPS URL 并让 OpenClaw + 发现 `/json/version`。 ### 同一主机上的 Browserless Docker -当 Browserless 以 Docker 方式自托管，而 OpenClaw 运行在宿主机上时，应将 Browserless 视为外部管理的 CDP 服务： +当 Browserless 在 Docker 中自托管，而 OpenClaw 运行在宿主机上时，请将 +Browserless 视为外部托管的 CDP 服务： ```json5 { @@ -345,23 +392,47 @@ OpenClaw 会在调用 `/json/*` 端点以及连接到 CDP WebSocket 时保留这 } ``` -`browser.profiles.browserless.cdpUrl` 中的地址必须对 OpenClaw 进程可达。Browserless 还必须广播一个匹配且可达的端点；将 Browserless 的 `EXTERNAL` 设置为同一个对 OpenClaw 可达的 WebSocket 基地址，例如 `ws://127.0.0.1:3000`、`ws://browserless:3000`，或稳定的私有 Docker 网络地址。如果 `/json/version` 返回的 `webSocketDebuggerUrl` 指向的是 OpenClaw 无法访问的地址，那么即使 CDP HTTP 看起来健康，WebSocket 附加仍会失败。 +`browser.profiles.browserless.cdpUrl` 中的地址必须能从 +OpenClaw 进程访问。Browserless 还必须公布一个与之匹配的可达端点； +请将 Browserless `EXTERNAL` 设置为同一个 OpenClaw 可访问的公共 WebSocket 基址，例如 +`ws://127.0.0.1:3000`、`ws://browserless:3000` 或稳定的私有 Docker +网络地址。如果 `/json/version` 返回的 `webSocketDebuggerUrl` 指向 +OpenClaw 无法访问的地址，那么 CDP HTTP 看起来可能是正常的，但 WebSocket +附加仍然会失败。 -不要对 loopback Browserless 配置文件省略 `attachOnly`。如果没有 `attachOnly`，OpenClaw 会将该 loopback 端口视为本地受管理浏览器配置文件，并可能报告该端口已被占用但不归 OpenClaw 所有。 +对于 loopback 上的 Browserless 配置文件，不要让 `attachOnly` 保持未设置。没有 +`attachOnly` 时，OpenClaw 会将该 loopback 端口视为本地受管浏览器 +配置文件，并可能报告该端口正在使用但不属于 OpenClaw。 ## 直接 WebSocket CDP 提供商 -有些托管浏览器服务暴露的是**直接 WebSocket** 端点，而不是标准的基于 HTTP 的 CDP 发现（`/json/version`）。OpenClaw 接受三种 CDP URL 形式，并会自动选择正确的连接策略： +某些托管浏览器服务暴露的是**直接 WebSocket** 端点，而不是 +标准的基于 HTTP 的 CDP 发现（`/json/version`）。OpenClaw 接受三种 +CDP URL 形式，并会自动选择正确的连接策略： -- **HTTP(S) 发现** — `http://host[:port]` 或 `https://host[:port]`。 - OpenClaw 会调用 `/json/version` 以发现 WebSocket 调试器 URL，然后连接。不会回退到 WebSocket。 +- **HTTP(S) 发现** — `http://host[:port]` 或 `https://host[:port]`。 + OpenClaw 调用 `/json/version` 以发现 WebSocket 调试器 URL，然后 + 建立连接。没有 WebSocket 回退。 - **直接 WebSocket 端点** — `ws://host[:port]/devtools//` 或 - `wss://...`，路径形式为 `/devtools/browser|page|worker|shared_worker|service_worker/`。OpenClaw 会直接通过 WebSocket 握手连接，并完全跳过 `/json/version`。 -- **裸 WebSocket 根路径** — `ws://host[:port]` 或 `wss://host[:port]`，且没有 `/devtools/...` 路径（例如 [Browserless](https://browserless.io)、[Browserbase](https://www.browserbase.com)）。OpenClaw 会先尝试 HTTP `/json/version` 发现（将协议规范化为 `http` / `https`）；如果发现返回了 `webSocketDebuggerUrl`，则使用它；否则 OpenClaw 会回退到在裸根路径上执行直接 WebSocket 握手。如果广播的 WebSocket 端点拒绝 CDP 握手，而已配置的裸根路径接受，则 OpenClaw 也会回退到该根路径。这样一来，指向本地 Chrome 的裸 `ws://` 仍然可以连接，因为 Chrome 只接受 `/json/version` 返回的特定每目标路径上的 WebSocket 升级；而托管提供商在其发现端点广播了一个不适合 Playwright CDP 的短期 URL 时，仍可以使用其根 WebSocket 端点。 + `wss://...`，其中路径为 `/devtools/browser|page|worker|shared_worker|service_worker/`。 + OpenClaw 通过 WebSocket 握手直接连接，并完全跳过 + `/json/version`。 +- **裸 WebSocket 根路径** — `ws://host[:port]` 或 `wss://host[:port]`，没有 + `/devtools/...` 路径（例如 [Browserless](https://browserless.io)、 + [Browserbase](https://www.browserbase.com)）。OpenClaw 会先尝试 HTTP + `/json/version` 发现（将协议规范化为 `http`/`https`）； + 如果发现返回了 `webSocketDebuggerUrl`，则使用它，否则 OpenClaw + 会回退为在裸根路径上直接进行 WebSocket 握手。如果公布的 + WebSocket 端点拒绝 CDP 握手，但配置的裸根路径 + 可以接受，OpenClaw 也会回退到该根路径。这使得指向本地 Chrome 的裸 `ws://` + 仍可连接，因为 Chrome 只接受来自 `/json/version` 的特定按目标路径的 WebSocket + 升级；而托管 + 提供商在其发现端点公布了不适合 Playwright CDP 的短期 URL 时，仍可以使用其根 WebSocket 端点。 ### Browserbase -[Browserbase](https://www.browserbase.com) 是一个云平台，用于运行 headless 浏览器，内置 CAPTCHA 求解、隐身模式和住宅代理。 +[Browserbase](https://www.browserbase.com) 是一个用于运行 +headless 浏览器的云平台，内置 CAPTCHA 求解、隐身模式和住宅代理。 ```json5 { @@ -382,67 +453,78 @@ OpenClaw 会在调用 `/json/*` 端点以及连接到 CDP WebSocket 时保留这 说明： -- [注册](https://www.browserbase.com/sign-up)，然后从 [Overview dashboard](https://www.browserbase.com/overview) 复制你的 **API Key**。 -- 将 `` 替换为你真实的 Browserbase API key。 -- Browserbase 会在 WebSocket 连接时自动创建浏览器会话，因此无需手动创建会话。 -- 免费套餐每月允许一个并发会话和一个浏览器小时。付费套餐限制见 [pricing](https://www.browserbase.com/pricing)。 -- 完整的 API 参考、SDK 指南和集成示例见 [Browserbase docs](https://docs.browserbase.com)。 +- [注册](https://www.browserbase.com/sign-up)，然后从 [Overview 仪表板](https://www.browserbase.com/overview) 复制你的 **API Key**。 +- 将 `` 替换为你真实的 Browserbase API 密钥。 +- Browserbase 会在 WebSocket 连接时自动创建浏览器会话，因此 + 不需要手动创建会话步骤。 +- 免费层每月允许一个并发会话和一个浏览器小时。 + 付费计划限制请参阅 [定价](https://www.browserbase.com/pricing)。 +- 完整 API + 参考、SDK 指南和集成示例请参阅 [Browserbase 文档](https://docs.browserbase.com)。 ## 安全性 关键概念： - 浏览器控制仅限 loopback；访问通过 Gateway 网关的认证或节点配对进行。 -- 独立的 loopback 浏览器 HTTP API **仅使用共享密钥认证**：gateway token bearer auth、`x-openclaw-password`，或携带已配置 gateway 密码的 HTTP Basic auth。 -- Tailscale Serve 身份头和 `gateway.auth.mode: "trusted-proxy"` **不会**为这个独立的 loopback 浏览器 API 提供认证。 -- 如果启用了浏览器控制，但没有配置共享密钥认证，OpenClaw 会在启动时自动生成 `gateway.auth.token`，并将其持久化到配置中。 -- 当 `gateway.auth.mode` 已经是 `password`、`none` 或 `trusted-proxy` 时，OpenClaw **不会**自动生成该 token。 -- 将 Gateway 网关和任何节点主机保持在私有网络中（Tailscale）；避免暴露到公网。 -- 将远程 CDP URL / token 视为密钥；优先使用环境变量或 secrets manager。 +- 独立的 loopback 浏览器 HTTP API **仅**使用共享密钥认证： + gateway token Bearer 认证、`x-openclaw-password`，或使用 + 已配置 gateway 密码的 HTTP Basic 认证。 +- Tailscale Serve 身份请求头和 `gateway.auth.mode: "trusted-proxy"` + **不能**用于认证这个独立的 loopback 浏览器 API。 +- 如果启用了浏览器控制但未配置共享密钥认证，OpenClaw + 会在启动时自动生成 `gateway.auth.token` 并将其持久化到配置中。 +- 当 `gateway.auth.mode` 已经是 + `password`、`none` 或 `trusted-proxy` 时，OpenClaw **不会**自动生成该令牌。 +- 将 Gateway 网关和任何节点主机保持在私有网络中（Tailscale）；避免公开暴露。 +- 将远程 CDP URL/令牌视为密钥；优先使用环境变量或密钥管理器。 远程 CDP 提示： -- 尽可能优先使用加密端点（HTTPS 或 WSS）和短期 token。 -- 避免将长期 token 直接嵌入配置文件。 +- 尽可能优先使用加密端点（HTTPS 或 WSS）和短期令牌。 +- 避免将长期令牌直接嵌入配置文件中。 ## 配置文件（多浏览器） OpenClaw 支持多个命名配置文件（路由配置）。配置文件可以是： -- **由 OpenClaw 管理**：一个专用的基于 Chromium 的浏览器实例，拥有自己的用户数据目录和 CDP 端口 -- **远程**：一个显式的 CDP URL（运行在其他地方的基于 Chromium 的浏览器） +- **由 OpenClaw 管理**：具有独立用户数据目录 + CDP 端口的专用 Chromium 系浏览器实例 +- **远程**：显式 CDP URL（运行在其他地方的 Chromium 系浏览器） - **现有会话**：通过 Chrome DevTools MCP 自动连接到你现有的 Chrome 配置文件 默认值： -- 如果缺失，`openclaw` 配置文件会被自动创建。 -- `user` 配置文件是内置的，用于 Chrome MCP existing-session 附加。 -- 除 `user` 之外，existing-session 配置文件需要显式启用；使用 `--driver existing-session` 创建它们。 -- 本地 CDP 端口默认从 **18800–18899** 范围内分配。 -- 删除配置文件时，会将其本地数据目录移到废纸篓。 +- 如果缺失，会自动创建 `openclaw` 配置文件。 +- `user` 配置文件内置用于 Chrome MCP existing-session 附加。 +- 除 `user` 外，existing-session 配置文件需要显式启用；请使用 `--driver existing-session` 创建。 +- 本地 CDP 端口默认从 **18800–18899** 分配。 +- 删除配置文件会将其本地数据目录移到废纸篓。 所有控制端点都接受 `?profile=`；CLI 使用 `--browser-profile`。 -## 通过 Chrome DevTools MCP 使用现有会话 +## 通过 Chrome DevTools MCP 连接现有会话 -OpenClaw 还可以通过官方的 Chrome DevTools MCP 服务器附加到一个正在运行的基于 Chromium 的浏览器配置文件。这会复用该浏览器配置文件中已经打开的标签页和登录状态。 +OpenClaw 还可以通过官方 Chrome DevTools MCP 服务器附加到正在运行的 Chromium 系浏览器配置文件。 +这样会复用该浏览器配置文件中已经打开的标签页和登录状态。 -官方背景与设置参考： +官方背景和设置参考： -- [Chrome for Developers: 使用 Chrome DevTools MCP 连接你的浏览器会话](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session) +- [Chrome for Developers：使用 Chrome DevTools MCP 与你的浏览器会话协作](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session) - [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp) 内置配置文件： - `user` -可选：如果你想要不同的名称、颜色或浏览器数据目录，可以创建你自己的自定义 existing-session 配置文件。 +可选：如果你想使用不同的名称、颜色或浏览器数据目录， +可以创建自己的自定义 existing-session 配置文件。 默认行为： -- 内置的 `user` 配置文件使用 Chrome MCP 自动连接，目标是默认的本地 Google Chrome 配置文件。 +- 内置的 `user` 配置文件使用 Chrome MCP 自动连接，目标是 + 默认的本地 Google Chrome 配置文件。 -对于 Brave、Edge、Chromium 或非默认的 Chrome 配置文件，请使用 `userDataDir`。 +对于 Brave、Edge、Chromium 或非默认 Chrome 配置文件，请使用 `userDataDir`。 `~` 会展开为你的操作系统主目录： ```json5 @@ -466,13 +548,13 @@ OpenClaw 还可以通过官方的 Chrome DevTools MCP 服务器附加到一个 2. 启用远程调试。 3. 保持浏览器运行，并在 OpenClaw 附加时批准连接提示。 -常见的 inspect 页面： +常见 inspect 页面： - Chrome：`chrome://inspect/#remote-debugging` - Brave：`brave://inspect/#remote-debugging` - Edge：`edge://inspect/#remote-debugging` -实时附加 smoke 测试： +实时附加冒烟测试： ```bash openclaw browser --browser-profile user start @@ -481,72 +563,85 @@ openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot --format ai ``` -成功时应表现为： +成功时应看到的结果： - `status` 显示 `driver: existing-session` - `status` 显示 `transport: chrome-mcp` - `status` 显示 `running: true` - `tabs` 列出你已经打开的浏览器标签页 -- `snapshot` 返回所选实时标签页中的 refs +- `snapshot` 从所选的实时标签页返回 refs 如果附加失败，请检查： -- 目标的基于 Chromium 的浏览器版本是否为 `144+` -- 该浏览器的 inspect 页面中是否启用了远程调试 -- 浏览器是否弹出了附加同意提示，并且你已接受 +- 目标 Chromium 系浏览器版本是否为 `144+` +- 该浏览器的 inspect 页面中是否已启用远程调试 +- 浏览器是否显示了附加同意提示，并且你已接受 - `openclaw doctor` 会迁移旧的基于扩展的浏览器配置，并检查默认自动连接配置文件所需的 Chrome 是否已在本地安装，但它不能替你在浏览器端启用远程调试 智能体使用方式： - 当你需要用户已登录的浏览器状态时，使用 `profile="user"`。 -- 如果你使用自定义的 existing-session 配置文件，请传入该显式配置文件名。 -- 只有当用户就在电脑前、能够批准附加提示时，才选择这种模式。 +- 如果你使用自定义 existing-session 配置文件，请传入该显式配置文件名称。 +- 仅在用户就在电脑前可以批准附加 + 提示时，才选择此模式。 - Gateway 网关或节点主机可以启动 `npx chrome-devtools-mcp@latest --autoConnect` 说明： -- 与隔离的 `openclaw` 配置文件相比，这条路径风险更高，因为它可以在你已登录的浏览器会话中执行操作。 -- 对于这个驱动，OpenClaw 不会启动浏览器；它只会附加。 -- OpenClaw 在这里使用官方的 Chrome DevTools MCP `--autoConnect` 流程。如果设置了 `userDataDir`，它会被透传，以定位该用户数据目录。 -- existing-session 可以附加到选定主机上，或通过已连接的浏览器节点进行附加。如果 Chrome 位于其他地方，而又没有连接浏览器节点，请改用远程 CDP 或节点主机。 +- 这条路径比隔离的 `openclaw` 配置文件风险更高，因为它可以 + 在你已登录的浏览器会话中执行操作。 +- 对于此 driver，OpenClaw 不会启动浏览器；它只会附加。 +- OpenClaw 在此使用官方 Chrome DevTools MCP `--autoConnect` 流程。如果 + 设置了 `userDataDir`，它会被透传以定位该用户数据目录。 +- Existing-session 可以附加到所选主机上，或通过已连接的 + 浏览器节点附加。如果 Chrome 位于其他地方且没有连接任何浏览器节点，请改用 + 远程 CDP 或节点主机。 ### 自定义 Chrome MCP 启动 -当默认的 `npx chrome-devtools-mcp@latest` 流程不是你想要的方式时（例如离线主机、固定版本、供应商自带二进制），可以按配置文件覆盖所启动的 Chrome DevTools MCP 服务器： +当默认的 +`npx chrome-devtools-mcp@latest` 流程不符合你的需求时（离线主机、 +固定版本、内置二进制文件），可以按配置文件覆盖启动的 Chrome DevTools MCP 服务器： | 字段 | 作用 | | ------------ | -------------------------------------------------------------------------------------------------------------------------- | -| `mcpCommand` | 要启动的可执行文件，用来替代 `npx`。按原样解析；绝对路径会被直接使用。 | -| `mcpArgs` | 逐字传递给 `mcpCommand` 的参数数组。会替代默认的 `chrome-devtools-mcp@latest --autoConnect` 参数。 | +| `mcpCommand` | 要启动的可执行文件，用于替代 `npx`。按原样解析；绝对路径会被保留。 | +| `mcpArgs` | 原样传递给 `mcpCommand` 的参数数组。会替换默认的 `chrome-devtools-mcp@latest --autoConnect` 参数。 | -当在 existing-session 配置文件上设置了 `cdpUrl` 时，OpenClaw 会跳过 +当在 existing-session 配置文件上设置 `cdpUrl` 时，OpenClaw 会跳过 `--autoConnect`，并自动将该端点转发给 Chrome MCP： - `http(s)://...` → `--browserUrl `（DevTools HTTP 发现端点）。 - `ws(s)://...` → `--wsEndpoint `（直接 CDP WebSocket）。 -端点参数与 `userDataDir` 不能同时使用：当设置了 `cdpUrl` 时，Chrome MCP 启动会忽略 `userDataDir`，因为 Chrome MCP 会附加到该端点背后的运行中浏览器，而不是打开某个配置文件目录。 +端点标志和 `userDataDir` 不能同时组合使用：当设置了 `cdpUrl` 时， +`userDataDir` 会在 Chrome MCP 启动时被忽略，因为 Chrome MCP 会附加到 +端点背后正在运行的浏览器，而不是打开一个配置文件 +目录。 - + -与受管理的 `openclaw` 配置文件相比，existing-session 驱动限制更多： +与受管的 `openclaw` 配置文件相比，existing-session driver 的限制更多： -- **截图** —— 支持页面截图和 `--ref` 元素截图；不支持 CSS `--element` 选择器。`--full-page` 不能与 `--ref` 或 `--element` 组合使用。页面或基于 ref 的元素截图不需要 Playwright。 -- **操作** —— `click`、`type`、`hover`、`scrollIntoView`、`drag` 和 `select` 需要 snapshot refs（不支持 CSS 选择器）。`click-coords` 点击可见视口坐标，不需要 snapshot ref。`click` 仅支持左键。`type` 不支持 `slowly=true`；请使用 `fill` 或 `press`。`press` 不支持 `delayMs`。`type`、`hover`、`scrollIntoView`、`drag`、`select`、`fill` 和 `evaluate` 不支持按调用单独设置超时。`select` 仅接受单个值。 -- **等待 / 上传 / 对话框** —— `wait --url` 支持精确、子串和 glob 模式；不支持 `wait --load networkidle`。上传钩子需要 `ref` 或 `inputRef`，一次只能传一个文件，不支持 CSS `element`。对话框钩子不支持超时覆盖。 -- **仅受管理模式支持的功能** —— 批量操作、PDF 导出、下载拦截和 `responsebody` 仍然需要受管理浏览器路径。 +- **截图** — 支持整页截图和 `--ref` 元素截图；不支持 CSS `--element` 选择器。`--full-page` 不能与 `--ref` 或 `--element` 组合。页面截图或基于 ref 的元素截图不需要 Playwright。 +- **操作** — `click`、`type`、`hover`、`scrollIntoView`、`drag` 和 `select` 需要 snapshot refs（不支持 CSS 选择器）。`click-coords` 会点击可见视口坐标，不需要 snapshot ref。`click` 仅支持鼠标左键。`type` 不支持 `slowly=true`；请改用 `fill` 或 `press`。`press` 不支持 `delayMs`。`type`、`hover`、`scrollIntoView`、`drag`、`select`、`fill` 和 `evaluate` 不支持按调用单独设置超时。`select` 只接受单个值。 +- **等待 / 上传 / 对话框** — `wait --url` 支持精确匹配、子串匹配和 glob 模式；不支持 `wait --load networkidle`。上传钩子需要 `ref` 或 `inputRef`，一次只能上传一个文件，不支持 CSS `element`。对话框钩子不支持超时覆盖。 +- **仅受管模式功能** — 批量操作、PDF 导出、下载拦截和 `responsebody` 仍然需要受管浏览器路径。 ## 隔离保证 - **专用用户数据目录**：绝不会触碰你的个人浏览器配置文件。 -- **专用端口**：避免使用 `9222`，防止与你的开发工作流冲突。 -- **可预测的标签页控制**：`tabs` 会优先返回 `suggestedTargetId`，然后是稳定的 `tabId` 句柄（如 `t1`）、可选标签以及原始的 `targetId`。智能体应复用 `suggestedTargetId`；原始 ID 仍保留用于调试和兼容性场景。 +- **专用端口**：避免使用 `9222`，以防与开发工作流冲突。 +- **可预测的标签页控制**：`tabs` 会先返回 `suggestedTargetId`，然后是 + 稳定的 `tabId` 句柄，例如 `t1`、可选标签以及原始 `targetId`。 + 智能体应复用 `suggestedTargetId`；原始 id 仍保留供 + 调试和兼容性使用。 ## 浏览器选择 -在本地启动时，OpenClaw 会选择第一个可用的浏览器： +在本地启动时，OpenClaw 会选择第一个可用项： 1. Chrome 2. Brave @@ -554,43 +649,49 @@ openclaw browser --browser-profile user snapshot --format ai 4. Chromium 5. Chrome Canary -你可以通过 `browser.executablePath` 进行覆盖。 +你可以使用 `browser.executablePath` 覆盖。 平台说明： - macOS：检查 `/Applications` 和 `~/Applications`。 -- Linux：检查 `/usr/bin`、`/snap/bin`、`/opt/google`、`/opt/brave.com`、`/usr/lib/chromium` 和 `/usr/lib/chromium-browser` 下常见的 Chrome / Brave / Edge / Chromium 路径。 +- Linux：检查 `/usr/bin`、 + `/snap/bin`、`/opt/google`、`/opt/brave.com`、`/usr/lib/chromium` 和 + `/usr/lib/chromium-browser` 下常见的 Chrome/Brave/Edge/Chromium 位置。 - Windows：检查常见安装位置。 ## 控制 API（可选） -为了便于脚本编写和调试，Gateway 网关暴露了一个小型的**仅限 loopback 的 HTTP 控制 API**，以及配套的 `openclaw browser` CLI（快照、refs、wait 增强功能、JSON 输出、调试工作流）。完整参考见 [Browser 控制 API](/zh-CN/tools/browser-control)。 +用于脚本和调试时，Gateway 网关会暴露一个小型的**仅限 loopback 的 HTTP +控制 API**，以及与之匹配的 `openclaw browser` CLI（快照、refs、wait +增强功能、JSON 输出、调试工作流）。完整参考请参阅 +[浏览器控制 API](/zh-CN/tools/browser-control)。 ## 故障排除 -对于 Linux 特有问题（尤其是 snap Chromium），请参见 +对于 Linux 特有问题（尤其是 snap Chromium），请参阅 [浏览器故障排除](/zh-CN/tools/browser-linux-troubleshooting)。 -对于 WSL2 Gateway 网关 + Windows Chrome 分离主机配置，请参见 +对于 WSL2 Gateway 网关 + Windows Chrome 分离主机设置，请参阅 [WSL2 + Windows + 远程 Chrome CDP 故障排除](/zh-CN/tools/browser-wsl2-windows-remote-cdp-troubleshooting)。 ### CDP 启动失败与导航 SSRF 阻止 -这两者属于不同的失败类型，对应不同的代码路径。 +这是两类不同的失败，它们指向不同的代码路径。 - **CDP 启动或就绪失败** 表示 OpenClaw 无法确认浏览器控制平面处于健康状态。 -- **导航 SSRF 阻止** 表示浏览器控制平面是健康的，但某个页面导航目标因策略被拒绝。 +- **导航 SSRF 阻止** 表示浏览器控制平面是健康的，但页面导航目标因策略被拒绝。 常见示例： - CDP 启动或就绪失败： - `Chrome CDP websocket for profile "openclaw" is not reachable after start` - `Remote CDP for profile "" is not reachable at ` - - 当 loopback 外部 CDP 服务未设置 `attachOnly: true` 时，出现 `Port is in use for profile "" but not by openclaw` + - `Port is in use for profile "" but not by openclaw`，当 + 配置了 loopback 外部 CDP 服务却未设置 `attachOnly: true` 时 - 导航 SSRF 阻止： - - 当 `start` 和 `tabs` 仍然可用时，`open`、`navigate`、snapshot 或打开标签页流程因浏览器 / 网络策略错误而失败 + - 当 `start` 和 `tabs` 仍可用时，`open`、`navigate`、snapshot 或标签页打开流程因浏览器/网络策略错误而失败 -使用以下最小流程来区分这两类问题： +使用以下最小序列来区分这两类问题： ```bash openclaw browser --browser-profile openclaw start @@ -600,46 +701,46 @@ openclaw browser --browser-profile openclaw open https://example.com 结果解读方式： -- 如果 `start` 因 `not reachable after start` 失败，先排查 CDP 就绪性。 -- 如果 `start` 成功但 `tabs` 失败，则控制平面仍然不健康。应将其视为 CDP 可达性问题，而不是页面导航问题。 -- 如果 `start` 和 `tabs` 成功，但 `open` 或 `navigate` 失败，则说明浏览器控制平面已经就绪，失败点在导航策略或目标页面。 -- 如果 `start`、`tabs` 和 `open` 全部成功，则说明基础的受管理浏览器控制路径是健康的。 +- 如果 `start` 失败并显示 `not reachable after start`，先排查 CDP 就绪问题。 +- 如果 `start` 成功但 `tabs` 失败，说明控制平面仍然不健康。应将其视为 CDP 可达性问题，而不是页面导航问题。 +- 如果 `start` 和 `tabs` 成功，但 `open` 或 `navigate` 失败，说明浏览器控制平面已启动，失败点在导航策略或目标页面。 +- 如果 `start`、`tabs` 和 `open` 全部成功，则基础受管浏览器控制路径是健康的。 重要行为细节： -- 即使你没有配置 `browser.ssrfPolicy`，浏览器配置默认也会使用失败即关闭的 SSRF 策略对象。 -- 对于本地 loopback 的 `openclaw` 受管理配置文件，CDP 健康检查会有意跳过浏览器 SSRF 可达性强制，以便 OpenClaw 自身的本地控制平面可以工作。 -- 导航保护是独立的。`start` 或 `tabs` 成功，并不意味着后续的 `open` 或 `navigate` 目标一定被允许。 +- 即使你没有配置 `browser.ssrfPolicy`，浏览器配置默认也会使用一个默认拒绝的 SSRF 策略对象。 +- 对于本地 loopback 的 `openclaw` 受管配置文件，CDP 健康检查会有意跳过对 OpenClaw 自身本地控制平面的浏览器 SSRF 可达性强制检查。 +- 导航保护是独立的。`start` 或 `tabs` 成功并不意味着后续的 `open` 或 `navigate` 目标一定被允许。 -安全建议： +安全指引： -- 默认情况下**不要**放宽浏览器 SSRF 策略。 -- 相比于宽泛的私有网络访问，优先使用 `hostnameAllowlist` 或 `allowedHostnames` 这类更窄的主机例外。 -- 仅在明确受信任、确实需要并经过审查的私有网络浏览器访问环境中，才使用 `dangerouslyAllowPrivateNetwork: true`。 +- **不要**默认放宽浏览器 SSRF 策略。 +- 优先使用精确的主机例外，例如 `hostnameAllowlist` 或 `allowedHostnames`，而不是宽泛的私有网络访问。 +- 仅在明确受信任且已审查、并且确实需要私有网络浏览器访问的环境中，才使用 `dangerouslyAllowPrivateNetwork: true`。 -## 智能体工具以及控制方式 +## 智能体工具 + 控制方式 -智能体只会获得**一个工具**用于浏览器自动化： +智能体获得**一个工具**用于浏览器自动化： -- `browser` — doctor / status / start / stop / tabs / open / focus / close / snapshot / screenshot / navigate / act +- `browser` — doctor/status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act -其映射关系如下： +其映射方式如下： - `browser snapshot` 返回稳定的 UI 树（AI 或 ARIA）。 -- `browser act` 使用 snapshot `ref` ID 来执行 click / type / drag / select。 -- `browser screenshot` 捕获像素内容（整页、元素或带标签的 refs）。 -- `browser doctor` 检查 Gateway 网关、插件、配置文件、浏览器和标签页就绪情况。 +- `browser act` 使用 snapshot `ref` ID 来点击/输入/拖动/选择。 +- `browser screenshot` 捕获像素（整页、元素或带标签的 refs）。 +- `browser doctor` 检查 Gateway 网关、插件、配置文件、浏览器和标签页就绪状态。 - `browser` 接受： - - `profile`，用于选择命名浏览器配置文件（openclaw、chrome 或远程 CDP）。 - - `target`（`sandbox` | `host` | `node`），用于选择浏览器所在位置。 + - `profile` 用于选择命名的浏览器配置文件（openclaw、chrome 或远程 CDP）。 + - `target`（`sandbox` | `host` | `node`）用于选择浏览器所在位置。 - 在沙箱隔离会话中，`target: "host"` 需要 `agents.defaults.sandbox.browser.allowHostControl=true`。 - 如果省略 `target`：沙箱隔离会话默认使用 `sandbox`，非沙箱隔离会话默认使用 `host`。 - - 如果已连接支持浏览器的节点，该工具可能会自动路由到该节点，除非你显式固定 `target="host"` 或 `target="node"`。 + - 如果连接了具备浏览器能力的节点，除非你固定使用 `target="host"` 或 `target="node"`，否则该工具可能会自动路由到该节点。 -这样可以让智能体保持可预测，并避免脆弱的选择器。 +这让智能体保持可预测，并避免使用脆弱的选择器。 ## 相关内容 -- [Tools Overview](/zh-CN/tools) —— 所有可用的智能体工具 -- [沙箱隔离](/zh-CN/gateway/sandboxing) —— 沙箱隔离环境中的浏览器控制 -- [安全性](/zh-CN/gateway/security) —— 浏览器控制的风险与加固 +- [工具概览](/zh-CN/tools) — 所有可用的智能体工具 +- [沙箱隔离](/zh-CN/gateway/sandboxing) — 沙箱隔离环境中的浏览器控制 +- [安全性](/zh-CN/gateway/security) — 浏览器控制的风险与加固 diff --git a/docs/zh-CN/tools/code-execution.md b/docs/zh-CN/tools/code-execution.md index ffa1e72a8..14112768c 100644 --- a/docs/zh-CN/tools/code-execution.md +++ b/docs/zh-CN/tools/code-execution.md @@ -1,39 +1,38 @@ --- read_when: - - 你想启用或配置 code_execution - - 你想在没有本地 shell 访问权限的情况下进行远程分析 - - 你想将 x_search 或 web_search 与远程 Python 分析结合使用 + - 你想要启用或配置代码执行 + - 你想要在没有本地 shell 访问权限的情况下进行远程分析 + - 你想将 `x_search` 或 `web_search` 与远程 Python 分析结合使用 summary: code_execution —— 使用 xAI 运行沙箱隔离的远程 Python 分析 title: 代码执行 x-i18n: - generated_at: "2026-04-24T03:43:41Z" + generated_at: "2026-04-27T07:13:27Z" model: gpt-5.4 provider: openai - source_hash: 332afbbef15eaa832d87f263eb095eff680e8f941b9e123add9b37f9b4fa5e00 + source_hash: fe635ec65aaf593a5bd63c139fbfc69e1ba3ea7c58c2bba639ec1ebd70dba1a9 source_path: tools/code-execution.md workflow: 15 --- -`code_execution` 会在 xAI 的 Responses API 上运行沙箱隔离的远程 Python 分析。 -这与本地的 [`exec`](/zh-CN/tools/exec) 不同： +`code_execution` 在 xAI 的 Responses API 上运行沙箱隔离的远程 Python 分析。 +这与本地 [`exec`](/zh-CN/tools/exec) 不同： -- `exec` 在你的机器或 node 上运行 shell 命令 +- `exec` 在你的机器或节点上运行 shell 命令 - `code_execution` 在 xAI 的远程沙箱中运行 Python -适合在以下场景使用 `code_execution`： +在以下场景中使用 `code_execution`： - 计算 - 制表 - 快速统计 -- 图表风格分析 +- 图表式分析 - 分析由 `x_search` 或 `web_search` 返回的数据 -如果你需要本地文件、你的 shell、你的仓库或已配对的 -设备，**不要**使用它。这种情况请使用 [`exec`](/zh-CN/tools/exec)。 +当你需要本地文件、你的 shell、你的仓库或已配对设备时，**不要**使用它。此类情况请使用 [`exec`](/zh-CN/tools/exec)。 ## 设置 -你需要一个 xAI API key。以下任意一种都可以： +你需要一个 xAI API 密钥。以下任一方式都可以： - `XAI_API_KEY` - `plugins.entries.xai.config.webSearch.apiKey` @@ -62,9 +61,9 @@ x-i18n: } ``` -## 使用方式 +## 如何使用 -自然地提问，并明确表达分析意图： +自然地提出请求，并明确说明分析意图： ```text Use code_execution to calculate the 7-day moving average for these numbers: ... @@ -78,15 +77,14 @@ Use x_search to find posts mentioning OpenClaw this week, then use code_executio Use web_search to gather the latest AI benchmark numbers, then use code_execution to compare percent changes. ``` -该工具在内部只接收一个 `task` 参数，因此智能体应在一个提示中发送 -完整的分析请求以及任何内联数据。 +该工具在内部只接受一个 `task` 参数，因此智能体应在一个提示中发送完整的分析请求以及所有内联数据。 ## 限制 - 这是远程 xAI 执行，不是本地进程执行。 -- 应将其视为一次性的临时分析，而不是持久化笔记本。 -- 不要假设它能访问本地文件或你的工作区。 -- 如果你需要最新的 X 数据，请先使用 [`x_search`](/zh-CN/tools/web#x_search)。 +- 它应被视为临时分析，而不是持久化笔记本。 +- 不要假设它可以访问本地文件或你的工作区。 +- 对于最新的 X 数据，请先使用 [`x_search`](/zh-CN/tools/web#x_search)。 ## 相关内容 diff --git a/docs/zh-CN/tools/plugin.md b/docs/zh-CN/tools/plugin.md index 1d7315415..1a2dc04a9 100644 --- a/docs/zh-CN/tools/plugin.md +++ b/docs/zh-CN/tools/plugin.md @@ -1,26 +1,26 @@ --- read_when: - 安装或配置插件 - - 了解插件发现和加载规则 - - 使用与 Codex/Claude 兼容的插件包 + - 了解插件发现与加载规则 + - 使用与 Codex / Claude 兼容的插件包 sidebarTitle: Install and Configure summary: 安装、配置和管理 OpenClaw 插件 title: 插件 x-i18n: - generated_at: "2026-04-26T10:36:01Z" + generated_at: "2026-04-27T07:13:27Z" model: gpt-5.4 provider: openai - source_hash: b36ac0e71c95a1f5e3cf9edb1aa7175c04482c25dca72bbf12ad10bef17699c1 + source_hash: 46e96d9f0a01bc18076bfe3e5d599eb5531da9b84f8c921d6570d6d140b1567d source_path: tools/plugin.md workflow: 15 --- -插件通过新增能力来扩展 OpenClaw：渠道、模型提供商、智能体 harness、工具、Skills、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等。有些插件是**核心**插件（随 OpenClaw 一起发布），另一些是**外部**插件（由社区发布到 npm）。 +插件为 OpenClaw 扩展新能力：渠道、模型 provider、Agent harnesses、工具、Skills、语音、实时转写、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等。有些插件是**核心**插件（随 OpenClaw 一起发布），另一些是**外部**插件（由社区发布到 npm）。 ## 快速开始 - + ```bash openclaw plugins list ``` @@ -28,10 +28,10 @@ x-i18n: ```bash - # 从 npm + # From npm openclaw plugins install @openclaw/voice-call - # 从本地目录或归档文件 + # From a local directory or archive openclaw plugins install ./my-plugin openclaw plugins install ./my-plugin.tgz ``` @@ -43,12 +43,12 @@ x-i18n: openclaw gateway restart ``` - 然后在你的配置文件中的 `plugins.entries.\.config` 下进行配置。 + 然后在你的配置文件中通过 `plugins.entries.\.config` 进行配置。 -如果你更喜欢原生聊天控制方式，启用 `commands.plugins: true` 并使用： +如果你更喜欢原生聊天控制方式，请启用 `commands.plugins: true`，然后使用： ```text /plugin install clawhub:@openclaw/voice-call @@ -56,12 +56,12 @@ x-i18n: /plugin enable voice-call ``` -安装路径使用与 CLI 相同的解析器：本地路径/归档文件、显式 `clawhub:`，或裸包规范（优先 ClawHub，然后回退到 npm）。 +安装路径使用与 CLI 相同的解析器：本地路径 / 压缩包、显式 `clawhub:`，或裸包说明符（先查找 ClawHub，再回退到 npm）。 -如果配置无效，安装通常会以关闭失败方式终止，并指引你使用 `openclaw doctor --fix`。唯一的恢复例外是一个针对选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件的狭窄内置插件重装路径。 +如果配置无效，安装通常会以封闭失败方式终止，并提示你运行 `openclaw doctor --fix`。唯一的恢复例外，是针对选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件所提供的一条狭窄的内置插件重装路径。 -打包的 OpenClaw 安装不会急切安装每个内置插件的运行时依赖树。当某个 OpenClaw 自有的内置插件因插件配置、旧版渠道配置或默认启用的清单而处于激活状态时，启动过程只会在导入该插件前修复该插件声明的运行时依赖。仅持久化的渠道认证状态本身不会为 Gateway 网关启动时的运行时依赖修复激活某个内置渠道。 -显式禁用仍然具有最高优先级：`plugins.entries..enabled: false`、`plugins.deny`、`plugins.enabled: false` 和 `channels..enabled: false` 会阻止该插件/渠道的自动内置运行时依赖修复。 +打包版 OpenClaw 安装不会急切安装每个内置插件的整套运行时依赖树。当某个 OpenClaw 自有的内置插件因插件配置、旧版渠道配置或默认启用的清单而处于激活状态时，启动修复只会在导入它之前修复该插件声明的运行时依赖。仅有持久化的渠道认证状态，并不会激活某个内置渠道来执行 Gateway 网关启动时的运行时依赖修复。 +显式禁用仍然优先：`plugins.entries..enabled: false`、`plugins.deny`、`plugins.enabled: false` 和 `channels..enabled: false` 都会阻止该插件 / 渠道的自动内置运行时依赖修复。 非空的 `plugins.allow` 也会限制默认启用的内置运行时依赖修复；显式启用内置渠道（`channels..enabled: true`）仍然可以修复该渠道的插件依赖。 外部插件和自定义加载路径仍然必须通过 `openclaw plugins install` 安装。 @@ -72,18 +72,23 @@ OpenClaw 识别两种插件格式： | 格式 | 工作方式 | 示例 | | ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ | | **原生** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 | -| **Bundle** | 与 Codex/Claude/Cursor 兼容的布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` | +| **Bundle** | 与 Codex / Claude / Cursor 兼容的布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` | -这两种格式都会显示在 `openclaw plugins list` 中。有关 bundle 的详细信息，请参见 [Plugin Bundles](/zh-CN/plugins/bundles)。 +这两种格式都会显示在 `openclaw plugins list` 中。Bundle 详情请参阅 [插件包](/zh-CN/plugins/bundles)。 -如果你要编写原生插件，请从 [构建插件](/zh-CN/plugins/building-plugins) 和 [插件 SDK 概览](/zh-CN/plugins/sdk-overview) 开始。 +如果你要编写原生插件，请从 [构建插件](/zh-CN/plugins/building-plugins) +和 [插件 SDK 概览](/zh-CN/plugins/sdk-overview) 开始。 ## 包入口点 原生插件 npm 包必须在 `package.json` 中声明 `openclaw.extensions`。 -每个条目都必须位于包目录内，并解析到可读取的运行时文件，或解析到带有推断出的已构建 JavaScript 对应文件的 TypeScript 源文件，例如 `src/index.ts` 对应 `dist/index.js`。 +每个条目都必须位于包目录内部，并解析到一个可读的 +运行时文件，或者解析到一个 TypeScript 源文件，且可推断出其对应的已构建 JavaScript +文件，例如 `src/index.ts` 对应 `dist/index.js`。 -当发布的运行时文件与源入口不在相同路径时，请使用 `openclaw.runtimeExtensions`。如果存在，`runtimeExtensions` 必须为每个 `extensions` 条目精确包含一个对应条目。列表不匹配会导致安装和插件发现失败，而不会静默回退到源路径。 +当发布的运行时文件与源入口不在相同路径时，请使用 `openclaw.runtimeExtensions`。 +如果存在 `runtimeExtensions`，则它必须为每个 `extensions` 条目精确提供一个对应条目。列表不匹配会导致安装和 +插件发现失败，而不是静默回退到源路径。 ```json { @@ -99,7 +104,7 @@ OpenClaw 识别两种插件格式： ### 可安装（npm） -| 插件 | 包 | 文档 | +| 插件 | 包名 | 文档 | | --------------- | ---------------------- | ------------------------------------ | | Matrix | `@openclaw/matrix` | [Matrix](/zh-CN/channels/matrix) | | Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/zh-CN/channels/msteams) | @@ -111,7 +116,7 @@ OpenClaw 识别两种插件格式： ### 核心（随 OpenClaw 一起发布） - + `anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`, `huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`, `moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`, @@ -120,21 +125,21 @@ OpenClaw 识别两种插件格式： - - `memory-core` — 内置 Memory 搜索（通过 `plugins.slots.memory` 默认启用） - - `memory-lancedb` — 按需安装的长期 Memory，支持自动召回/捕获（设置 `plugins.slots.memory = "memory-lancedb"`） + - `memory-core` — 内置 memory 搜索（默认通过 `plugins.slots.memory` 使用） + - `memory-lancedb` — 按需安装的长期 memory，支持自动召回 / 捕获（设置 `plugins.slots.memory = "memory-lancedb"`） - + `elevenlabs`, `microsoft` - - `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` gateway 方法、浏览器运行时以及默认浏览器控制服务的内置浏览器插件（默认启用；替换前请先禁用） - - `copilot-proxy` — VS Code Copilot Proxy 桥接器（默认禁用） + - `browser` — 内置浏览器插件，用于浏览器工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、浏览器运行时以及默认浏览器控制服务（默认启用；替换它之前请先禁用） + - `copilot-proxy` — VS Code Copilot Proxy 桥接（默认禁用） -在找第三方插件？请参见 [Community Plugins](/zh-CN/plugins/community)。 +在寻找第三方插件？请参阅 [社区插件](/zh-CN/plugins/community)。 ## 配置 @@ -152,33 +157,39 @@ OpenClaw 识别两种插件格式： } ``` -| 字段 | 说明 | +| 字段 | 描述 | | ---------------- | --------------------------------------------------------- | -| `enabled` | 总开关（默认：`true`） | +| `enabled` | 主开关（默认：`true`） | | `allow` | 插件允许列表（可选） | | `deny` | 插件拒绝列表（可选；拒绝优先） | -| `load.paths` | 额外的插件文件/目录 | +| `load.paths` | 额外插件文件 / 目录 | | `slots` | 独占槽位选择器（例如 `memory`、`contextEngine`） | | `entries.\` | 每个插件的开关 + 配置 | -配置更改**需要重启 Gateway 网关**。如果 Gateway 网关在启用了配置监视 + 进程内重启的情况下运行（默认的 `openclaw gateway` 路径），那么配置写入完成后通常会在短时间内自动执行该重启。 -对于原生插件运行时代码或生命周期钩子，没有受支持的热重载路径；在期望更新后的 `register(api)` 代码、`api.on(...)` 钩子、工具、服务或提供商/运行时钩子生效前，请重启为实时渠道提供服务的 Gateway 网关进程。 +配置更改**需要重启 Gateway 网关**。如果 Gateway 网关正在使用配置监视 + 进程内重启（默认的 `openclaw gateway` 路径），则配置写入落地后通常会自动在稍后执行该重启。 +原生插件运行时代码或生命周期钩子没有受支持的热重载路径；在期待更新后的 `register(api)` 代码、`api.on(...)` 钩子、工具、服务或 +provider / 运行时钩子生效之前，请重启为实时渠道提供服务的 Gateway 网关进程。 -`openclaw plugins list` 是本地插件注册表/配置快照。其中某个插件显示为 `enabled`，表示持久化注册表和当前配置允许该插件参与运行。这并不能证明某个已经在运行的远程 Gateway 网关子进程已经重启并加载了相同的插件代码。在带有包装进程的 VPS/容器部署中，请将重启发送到实际的 `openclaw gateway run` 进程，或者针对正在运行的 Gateway 网关使用 `openclaw gateway restart`。 +`openclaw plugins list` 是一个本地插件注册表 / 配置快照。其中标记为 +`enabled` 的插件意味着持久化注册表和当前配置允许该 +插件参与运行。但这并不能证明某个已经在运行的远程 Gateway 网关子进程 +已经重启并加载了相同的插件代码。在 VPS / 容器配置中，如果有包装进程，请将重启信号发送到真正的 `openclaw gateway run` 进程， +或者对正在运行的 Gateway 网关使用 `openclaw gateway restart`。 - - - **Disabled**：插件存在，但启用规则将其关闭。配置会被保留。 - - **Missing**：配置引用了某个插件 ID，但插件发现过程没有找到它。 - - **Invalid**：插件存在，但其配置不符合声明的 schema。 + + - **已禁用**：插件存在，但启用规则将其关闭。配置会被保留。 + - **缺失**：配置引用了某个插件 id，但插件发现未找到它。 + - **无效**：插件存在，但其配置不符合声明的 schema。 -## 设备发现和优先级 +## 发现顺序与优先级 OpenClaw 按以下顺序扫描插件（先匹配者优先）： - `plugins.load.paths` — 显式文件或目录路径。指回 OpenClaw 自身打包内置插件目录的路径会被忽略；请运行 `openclaw doctor --fix` 以移除这些过时别名。 + `plugins.load.paths` —— 显式文件或目录路径。若路径指回 OpenClaw 自身打包的内置插件目录，则会被忽略； + 请运行 `openclaw doctor --fix` 以移除这些陈旧别名。 @@ -190,37 +201,57 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）： - 随 OpenClaw 一起发布。很多默认启用（模型提供商、语音）。 - 其他插件则需要显式启用。 + 随 OpenClaw 一起发布。许多默认启用（模型 provider、语音）。 + 其他则需要显式启用。 -打包安装和 Docker 镜像通常会从编译后的 `dist/extensions` 树解析内置插件。如果某个内置插件源目录被 bind mount 覆盖到对应的打包源路径上，例如 `/app/extensions/synology-chat`，OpenClaw 会将该挂载的源目录视为内置源码覆盖层，并在打包的 `/app/dist/extensions/synology-chat` bundle 之前发现它。这样可以在不把每个内置插件都切回 TypeScript 源码的情况下，保持维护者容器循环正常工作。 -设置 `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` 即可在存在源码覆盖挂载时仍强制使用打包的 dist bundle。 +打包安装和 Docker 镜像通常从已编译的 +`dist/extensions` 树中解析内置插件。如果某个内置插件源码目录被 +bind mount 覆盖到对应的打包源码路径上，例如 +`/app/extensions/synology-chat`，OpenClaw 会将该挂载的源码目录 +视为内置源码覆盖层，并在打包的 +`/app/dist/extensions/synology-chat` bundle 之前发现它。这样无需把每个内置插件都切回 TypeScript 源码， +也能保持维护者的容器开发循环正常工作。 +设置 `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` 可强制使用打包 dist bundle， +即使存在源码覆盖挂载也是如此。 ### 启用规则 - `plugins.enabled: false` 会禁用所有插件 -- `plugins.deny` 的优先级始终高于 allow +- `plugins.deny` 始终优先于 allow - `plugins.entries.\.enabled: false` 会禁用该插件 -- 来源于工作区的插件**默认禁用**（必须显式启用） -- 内置插件遵循内建的默认启用集合，除非被覆盖 -- 独占槽位可以强制启用该槽位所选中的插件 -- 某些内置的选择加入型插件会在配置命名了某个插件自有表面时自动启用，例如提供商模型引用、渠道配置或 harness 运行时 -- OpenAI 系列 Codex 路由保持独立的插件边界： - `openai-codex/*` 属于 OpenAI 插件，而内置的 Codex app-server 插件则通过 `agentRuntime.id: "codex"` 或旧版 `codex/*` 模型引用选择 +- 来自工作区的插件**默认禁用**（必须显式启用） +- 内置插件遵循内建默认开启集合，除非被覆盖 +- 独占槽位可以强制启用该槽位中被选中的插件 +- 某些内置可选插件会在配置命名某个 + 由插件拥有的表面时自动启用，例如 provider 模型引用、渠道配置或 harness + 运行时 +- OpenAI 系列的 Codex 路由保持独立的插件边界： + `openai-codex/*` 属于 OpenAI 插件，而内置 Codex + app-server 插件则由 `agentRuntime.id: "codex"` 或旧版 + `codex/*` 模型引用选择 ## 运行时钩子故障排除 -如果某个插件出现在 `plugins list` 中，但 `register(api)` 的副作用或钩子没有在实时聊天流量中运行，请先检查以下内容： +如果某个插件出现在 `plugins list` 中，但 `register(api)` 副作用或钩子 +在实时聊天流量中没有运行，请先检查以下内容： -- 运行 `openclaw gateway status --deep --require-rpc`，确认活动的 Gateway 网关 URL、配置文件、配置路径和进程就是你正在编辑的那些。 -- 在插件安装/配置/代码更改后重启正在运行的 Gateway 网关。在包装容器中，PID 1 可能只是一个监督进程；请重启或发送信号给子进程 `openclaw gateway run`。 -- 使用 `openclaw plugins inspect --json` 确认钩子注册和诊断信息。像 `llm_input`、`llm_output`、`before_agent_finalize` 和 `agent_end` 这样的非内置对话钩子，需要设置 `plugins.entries..hooks.allowConversationAccess=true`。 -- 对于模型切换，优先使用 `before_model_resolve`。它会在智能体轮次的模型解析之前运行；而 `llm_output` 只有在某次模型尝试产生助手输出后才会运行。 -- 若要证明会话实际使用的模型，请使用 `openclaw sessions` 或 Gateway 网关的会话/状态表面；在调试提供商负载时，请使用 `--raw-stream --raw-stream-path ` 启动 Gateway 网关。 +- 运行 `openclaw gateway status --deep --require-rpc`，并确认当前活动的 + Gateway 网关 URL、配置档案、配置路径和进程就是你正在编辑的那个。 +- 在插件安装 / 配置 / 代码更改之后重启实时 Gateway 网关。在包装器 + 容器中，PID 1 可能只是一个监督进程；请重启或向子进程 + `openclaw gateway run` 发送信号。 +- 使用 `openclaw plugins inspect --json` 确认钩子注册和 + 诊断信息。像 `llm_input`、 + `llm_output`、`before_agent_finalize` 和 `agent_end` 这样的非内置会话钩子需要 + `plugins.entries..hooks.allowConversationAccess=true`。 +- 对于模型切换，优先使用 `before_model_resolve`。它会在智能体轮次的模型解析之前运行；`llm_output` 只会在某次模型尝试产出助手输出之后才运行。 +- 若要证明实际会话模型，请使用 `openclaw sessions` 或 + Gateway 网关会话 / 状态表面；在调试 provider 负载时，请使用 + `--raw-stream --raw-stream-path ` 启动 Gateway 网关。 -### 重复的渠道或工具归属 +### 重复的渠道或工具所有权 症状： @@ -228,20 +259,20 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）： - `channel setup already registered: ()` - `plugin tool name conflict (): ` -这些都表示有多个已启用插件正在尝试拥有同一个渠道、设置流程或工具名称。最常见的原因是：某个外部渠道插件与现在已提供相同渠道 ID 的内置插件一起安装了。 +这表示有多个已启用插件正尝试拥有同一个渠道、设置流程或工具名称。最常见的原因是某个外部渠道插件与现在已提供相同渠道 id 的内置插件同时安装了。 -调试步骤： +排查步骤： -- 运行 `openclaw plugins list --enabled --verbose` 查看每个已启用插件及其来源。 +- 运行 `openclaw plugins list --enabled --verbose`，查看每个已启用插件及其来源。 - 对每个可疑插件运行 `openclaw plugins inspect --json`，并比较 `channels`、`channelConfigs`、`tools` 和诊断信息。 -- 在安装或移除插件包后运行 `openclaw plugins registry --refresh`，使持久化元数据反映当前安装状态。 -- 在安装、注册表或配置更改后重启 Gateway 网关。 +- 在安装或移除插件包之后运行 `openclaw plugins registry --refresh`，让持久化元数据反映当前安装状态。 +- 在安装、注册表或配置变更后重启 Gateway 网关。 修复选项： -- 如果某个插件是有意替换另一个相同渠道 ID 的插件，则首选插件应声明 `channelConfigs..preferOver`，其值为较低优先级的插件 ID。参见 [/plugins/manifest#replacing-another-channel-plugin](/zh-CN/plugins/manifest#replacing-another-channel-plugin)。 -- 如果重复是意外造成的，请通过 `plugins.entries..enabled: false` 禁用其中一方，或移除过时的插件安装。 -- 如果你显式启用了这两个插件，OpenClaw 会保留该请求并报告冲突。请为该渠道选择一个拥有者，或重命名插件自有工具，以确保运行时表面没有歧义。 +- 如果一个插件有意替换另一个插件来处理相同的渠道 id，则首选插件应声明 `channelConfigs..preferOver`，并填入优先级较低的插件 id。参见 [/plugins/manifest#replacing-another-channel-plugin](/zh-CN/plugins/manifest#replacing-another-channel-plugin)。 +- 如果重复是意外造成的，请使用 `plugins.entries..enabled: false` 禁用其中一方，或移除陈旧的插件安装。 +- 如果你显式启用了两个插件，OpenClaw 会保留该请求并报告冲突。请为该渠道选择一个唯一拥有者，或重命名插件拥有的工具，以确保运行时表面不含歧义。 ## 插件槽位（独占类别） @@ -251,8 +282,8 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）： { plugins: { slots: { - memory: "memory-core", // 或 "none" 以禁用 - contextEngine: "legacy", // 或某个插件 ID + memory: "memory-core", // or "none" to disable + contextEngine: "legacy", // or a plugin id }, }, } @@ -260,38 +291,38 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）： | 槽位 | 控制内容 | 默认值 | | --------------- | --------------------- | ------------------- | -| `memory` | 活动 Memory 插件 | `memory-core` | -| `contextEngine` | 活动上下文引擎 | `legacy`（内置） | +| `memory` | 当前激活的 memory 插件 | `memory-core` | +| `contextEngine` | 当前激活的上下文引擎 | `legacy`（内建） | ## CLI 参考 ```bash -openclaw plugins list # 精简清单 -openclaw plugins list --enabled # 仅显示已启用插件 -openclaw plugins list --verbose # 每个插件的详细信息行 -openclaw plugins list --json # 机器可读清单 -openclaw plugins inspect # 深度详情 -openclaw plugins inspect --json # 机器可读 -openclaw plugins inspect --all # 全量表格 -openclaw plugins info # inspect 别名 -openclaw plugins doctor # 诊断 -openclaw plugins registry # 查看持久化注册表状态 -openclaw plugins registry --refresh # 重建持久化注册表 -openclaw doctor --fix # 修复插件注册表状态 +openclaw plugins list # compact inventory +openclaw plugins list --enabled # only enabled plugins +openclaw plugins list --verbose # per-plugin detail lines +openclaw plugins list --json # machine-readable inventory +openclaw plugins inspect # deep detail +openclaw plugins inspect --json # machine-readable +openclaw plugins inspect --all # fleet-wide table +openclaw plugins info # inspect alias +openclaw plugins doctor # diagnostics +openclaw plugins registry # inspect persisted registry state +openclaw plugins registry --refresh # rebuild persisted registry +openclaw doctor --fix # repair plugin registry state -openclaw plugins install # 安装（优先 ClawHub，然后 npm） -openclaw plugins install clawhub: # 仅从 ClawHub 安装 -openclaw plugins install --force # 覆盖现有安装 -openclaw plugins install # 从本地路径安装 -openclaw plugins install -l # 链接（不复制），用于开发 +openclaw plugins install # install (ClawHub first, then npm) +openclaw plugins install clawhub: # install from ClawHub only +openclaw plugins install --force # overwrite existing install +openclaw plugins install # install from local path +openclaw plugins install -l # link (no copy) for dev openclaw plugins install --marketplace openclaw plugins install --marketplace https://github.com// -openclaw plugins install --pin # 记录精确解析后的 npm 规范 +openclaw plugins install --pin # record exact resolved npm spec openclaw plugins install --dangerously-force-unsafe-install -openclaw plugins update # 更新单个插件 +openclaw plugins update # update one plugin openclaw plugins update --dangerously-force-unsafe-install -openclaw plugins update --all # 更新全部 -openclaw plugins uninstall # 移除配置和插件索引记录 +openclaw plugins update --all # update all +openclaw plugins uninstall # remove config and plugin index records openclaw plugins uninstall --keep-files openclaw plugins marketplace list openclaw plugins marketplace list --json @@ -300,32 +331,32 @@ openclaw plugins enable openclaw plugins disable ``` -内置插件随 OpenClaw 一起发布。很多默认启用（例如内置模型提供商、内置语音提供商以及内置浏览器插件）。其他内置插件仍然需要 `openclaw plugins enable `。 +内置插件随 OpenClaw 一起发布。许多默认启用（例如内置模型 provider、内置语音 provider，以及内置浏览器插件）。其他内置插件仍然需要执行 `openclaw plugins enable `。 -`--force` 会原地覆盖已安装的插件或 hook 包。对于受跟踪的 npm 插件的常规升级，请使用 `openclaw plugins update `。它不支持与 `--link` 一起使用，因为后者会复用源路径，而不是复制到受管理的安装目标中。 +`--force` 会就地覆盖现有已安装插件或 hook 包。对于受跟踪的 npm 插件的常规升级，请使用 `openclaw plugins update `。该选项不支持与 `--link` 一起使用，因为 `--link` 会复用源路径，而不是复制到受管理的安装目标中。 -当 `plugins.allow` 已经设置时，`openclaw plugins install` 会在启用插件前将已安装插件 ID 添加到该允许列表。如果相同的插件 ID 存在于 `plugins.deny` 中，安装过程会移除这个过时的拒绝条目，这样在重启后显式安装的插件就能立即加载。 +当已设置 `plugins.allow` 时，`openclaw plugins install` 会在启用插件前先将已安装插件 id 添加到该允许列表中。如果同一个插件 id 同时存在于 `plugins.deny` 中，安装时会移除这个陈旧的拒绝条目，以便在重启后显式安装的插件可以立即加载。 -OpenClaw 会保留一个持久化的本地插件注册表，作为插件清单、贡献归属和启动规划的冷读取模型。安装、更新、卸载、启用和禁用流程在更改插件状态后都会刷新该注册表。同一个 `plugins/installs.json` 文件会在顶层 `installRecords` 中保存持久安装元数据，并在 `plugins` 中保存可重建的清单元数据。如果注册表缺失、过时或无效，`openclaw plugins registry --refresh` 会根据安装记录、配置策略以及清单/包元数据重建其清单视图，而不会加载插件运行时模块。 -`openclaw plugins update ` 适用于受跟踪的安装。传入带有 dist-tag 或精确版本的 npm 包规范时，会将包名解析回受跟踪的插件记录，并为后续更新记录新的规范。传入不带版本的包名时，会将精确固定的安装移回注册表默认发布线。如果已安装的 npm 插件已经匹配解析后的版本和记录的制品标识，OpenClaw 会跳过更新，不会下载、重装或重写配置。 +OpenClaw 会维护一个持久化的本地插件注册表，作为插件清单、贡献归属和启动规划的冷读模型。安装、更新、卸载、启用和禁用流程会在更改插件状态后刷新该注册表。同一个 `plugins/installs.json` 文件会在顶层 `installRecords` 中保留持久安装元数据，并在 `plugins` 中保留可重建的清单元数据。如果注册表缺失、过期或无效，`openclaw plugins registry --refresh` 会基于安装记录、配置策略和清单 / 包元数据重建其清单视图，而无需加载插件运行时模块。 +`openclaw plugins update ` 适用于受跟踪安装。传入带 dist-tag 或精确版本的 npm 包说明符时，会把包名解析回受跟踪的插件记录，并为后续更新记录新的说明符。传入不带版本的包名时，会把精确固定版本的安装恢复到注册表的默认发布线。如果已安装的 npm 插件已匹配解析出的版本和已记录的制品标识，OpenClaw 会跳过更新，而不会下载、重装或重写配置。 -`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm 规范。 +`--pin` 仅适用于 npm。不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm 说明符。 -`--dangerously-force-unsafe-install` 是针对内置危险代码扫描器误报的紧急覆盖选项。它允许插件安装和插件更新在内置 `critical` 级别发现后继续进行，但仍不会绕过插件 `before_install` 策略拦截或扫描失败拦截。 +`--dangerously-force-unsafe-install` 是内置危险代码扫描器出现误报时使用的破玻璃覆盖选项。它允许插件安装和插件更新在内置 `critical` 级发现之后继续进行，但仍然不会绕过插件 `before_install` 策略阻止或扫描失败阻止。 -这个 CLI 标志仅适用于插件安装/更新流程。由 Gateway 网关支持的 Skills 依赖安装则使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍然是独立的 ClawHub Skills 下载/安装流程。 +此 CLI 标志仅适用于插件安装 / 更新流程。由 Gateway 网关驱动的 Skills 依赖安装则使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍然是独立的 ClawHub Skills 下载 / 安装流程。 -兼容的 bundle 会参与相同的插件 list/inspect/enable/disable 流程。当前运行时支持包括 bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和清单声明的 `lspServers` 默认值、Cursor command-skills 以及兼容的 Codex hook 目录。 +兼容的 bundle 会参与同一套插件 list / inspect / enable / disable 流程。当前运行时支持包括 bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。 -`openclaw plugins inspect ` 还会报告检测到的 bundle 能力，以及由 bundle 支持的或不支持的 MCP 和 LSP 服务器条目。 +`openclaw plugins inspect ` 还会报告已检测到的 bundle 能力，以及对基于 bundle 的插件支持或不支持的 MCP 和 LSP 服务器条目。 -Marketplace 来源可以是 `~/.claude/plugins/known_marketplaces.json` 中的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplace，插件条目必须保持在克隆的 marketplace 仓库内部，并且只能使用相对路径来源。 +Marketplace 来源可以是 `~/.claude/plugins/known_marketplaces.json` 中的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplace，插件条目必须保持在克隆下来的 marketplace 仓库内部，并且只能使用相对路径来源。 -有关完整详情，请参见 [`openclaw plugins` CLI 参考](/zh-CN/cli/plugins)。 +完整详情请参阅 [`openclaw plugins` CLI 参考](/zh-CN/cli/plugins)。 ## 插件 API 概览 -原生插件会导出一个入口对象，并暴露 `register(api)`。较旧的插件可能仍使用 `activate(api)` 作为旧版别名，但新插件应使用 `register`。 +原生插件会导出一个暴露 `register(api)` 的入口对象。较旧的插件仍可能使用 `activate(api)` 作为旧版别名，但新插件应使用 `register`。 ```typescript export default definePluginEntry({ @@ -345,60 +376,60 @@ export default definePluginEntry({ }); ``` -OpenClaw 会加载该入口对象，并在插件激活期间调用 `register(api)`。加载器仍会为旧插件回退到 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公开契约。 +OpenClaw 会加载入口对象，并在插件激活期间调用 `register(api)`。加载器仍会为旧插件回退到 `activate(api)`，但内置插件和新的外部插件应将 `register` 视为公开契约。 -`api.registrationMode` 会告诉插件其入口为何被加载： +`api.registrationMode` 会告诉插件，它的入口为何会被加载： | 模式 | 含义 | | --------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `full` | 运行时激活。注册工具、钩子、服务、命令、路由和其他实时副作用。 | -| `discovery` | 只读能力发现。注册提供商和元数据；可信插件入口代码可能会被加载，但应跳过实时副作用。 | -| `setup-only` | 通过轻量级设置入口加载渠道设置元数据。 | +| `full` | 运行时激活。注册工具、钩子、服务、命令、路由及其他实时副作用。 | +| `discovery` | 只读能力发现。注册 provider 和元数据；可信插件入口代码可能会被加载，但要跳过实时副作用。 | +| `setup-only` | 通过轻量设置入口加载渠道设置元数据。 | | `setup-runtime` | 加载渠道设置，同时也需要运行时入口。 | | `cli-metadata` | 仅收集 CLI 命令元数据。 | -对于会打开套接字、数据库、后台工作线程或长生命周期客户端的插件入口，应使用 `api.registrationMode === "full"` 来保护这些副作用。发现加载会与激活加载分别缓存，不会替换正在运行的 Gateway 网关注册表。发现是非激活式的，而不是免导入的：OpenClaw 可能会执行可信插件入口或渠道插件模块，以构建快照。请保持模块顶层轻量且无副作用，并将网络客户端、子进程、监听器、凭证读取和服务启动放在完整运行时路径之后。 +如果插件入口会打开 socket、数据库、后台 worker 或长生命周期客户端，则应使用 `api.registrationMode === "full"` 来守卫这些副作用。发现加载与激活加载分别缓存，且不会替换正在运行的 Gateway 网关注册表。发现是非激活式的，而不是免导入：OpenClaw 可能会求值可信插件入口或渠道插件模块，以构建快照。请保持模块顶层轻量且无副作用，并将网络客户端、子进程、监听器、凭证读取和服务启动移动到完整运行时路径之后。 常见注册方法： | 方法 | 注册内容 | | --------------------------------------- | --------------------------- | -| `registerProvider` | 模型提供商（LLM） | +| `registerProvider` | 模型 provider（LLM） | | `registerChannel` | 聊天渠道 | | `registerTool` | 智能体工具 | | `registerHook` / `on(...)` | 生命周期钩子 | | `registerSpeechProvider` | 文本转语音 / STT | | `registerRealtimeTranscriptionProvider` | 流式 STT | | `registerRealtimeVoiceProvider` | 双工实时语音 | -| `registerMediaUnderstandingProvider` | 图像/音频分析 | +| `registerMediaUnderstandingProvider` | 图像 / 音频分析 | | `registerImageGenerationProvider` | 图像生成 | | `registerMusicGenerationProvider` | 音乐生成 | | `registerVideoGenerationProvider` | 视频生成 | -| `registerWebFetchProvider` | 网页抓取 / 抓取提供商 | +| `registerWebFetchProvider` | 网页抓取 / 抓取 provider | | `registerWebSearchProvider` | 网页搜索 | | `registerHttpRoute` | HTTP 端点 | | `registerCommand` / `registerCli` | CLI 命令 | | `registerContextEngine` | 上下文引擎 | | `registerService` | 后台服务 | -类型化生命周期钩子的守卫行为： +强类型生命周期钩子的守卫行为： -- `before_tool_call`：`{ block: true }` 是终止性的；会跳过更低优先级的处理器。 -- `before_tool_call`：`{ block: false }` 是无操作，不会清除更早的拦截。 -- `before_install`：`{ block: true }` 是终止性的；会跳过更低优先级的处理器。 -- `before_install`：`{ block: false }` 是无操作，不会清除更早的拦截。 -- `message_sending`：`{ cancel: true }` 是终止性的；会跳过更低优先级的处理器。 -- `message_sending`：`{ cancel: false }` 是无操作，不会清除更早的取消。 +- `before_tool_call`：`{ block: true }` 是终止性的；会跳过低优先级处理器。 +- `before_tool_call`：`{ block: false }` 是空操作，不会清除先前的阻止。 +- `before_install`：`{ block: true }` 是终止性的；会跳过低优先级处理器。 +- `before_install`：`{ block: false }` 是空操作，不会清除先前的阻止。 +- `message_sending`：`{ cancel: true }` 是终止性的；会跳过低优先级处理器。 +- `message_sending`：`{ cancel: false }` 是空操作，不会清除先前的取消。 原生 Codex app-server 会将桥接的 Codex 原生工具事件回传到这个钩子表面。插件可以通过 `before_tool_call` 阻止原生 Codex 工具，通过 `after_tool_call` 观察结果，并参与 Codex `PermissionRequest` 审批。该桥接目前还不会重写 Codex 原生工具参数。准确的 Codex 运行时支持边界定义在 [Codex harness v1 支持契约](/zh-CN/plugins/codex-harness#v1-support-contract) 中。 -有关完整的类型化钩子行为，请参见 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。 +完整的强类型钩子行为请参阅 [插件 SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。 ## 相关内容 - [构建插件](/zh-CN/plugins/building-plugins) — 创建你自己的插件 -- [Plugin Bundles](/zh-CN/plugins/bundles) — 与 Codex/Claude/Cursor bundle 的兼容性 +- [插件包](/zh-CN/plugins/bundles) — Codex / Claude / Cursor bundle 兼容性 - [插件清单](/zh-CN/plugins/manifest) — 清单 schema - [注册工具](/zh-CN/plugins/building-plugins#registering-agent-tools) — 在插件中添加智能体工具 -- [插件内部机制](/zh-CN/plugins/architecture) — 能力模型和加载流水线 -- [Community Plugins](/zh-CN/plugins/community) — 第三方列表 +- [插件内部机制](/zh-CN/plugins/architecture) — 能力模型与加载流水线 +- [社区插件](/zh-CN/plugins/community) — 第三方列表 diff --git a/docs/zh-CN/web/control-ui.md b/docs/zh-CN/web/control-ui.md index 6dc655aff..6d00319a4 100644 --- a/docs/zh-CN/web/control-ui.md +++ b/docs/zh-CN/web/control-ui.md @@ -1,15 +1,15 @@ --- read_when: - - 你想通过浏览器操作 Gateway 网关 - - 你希望在不使用 SSH 隧道的情况下获得 Tailnet 访问能力 + - 你希望通过浏览器操作 Gateway 网关 + - 你希望无需 SSH 隧道即可获得 Tailnet 访问能力 sidebarTitle: Control UI -summary: 用于 Gateway 网关的基于浏览器的控制 UI（聊天、节点、配置） +summary: Gateway 网关 的基于浏览器的控制 UI（聊天、节点、配置） title: 控制 UI x-i18n: - generated_at: "2026-04-26T18:01:45Z" + generated_at: "2026-04-27T07:13:26Z" model: gpt-5.4 provider: openai - source_hash: a1021dbac736269d04a08639f484289ccd387676525011de4e54f03ed3a747ad + source_hash: e0960e5030a26d24035e26e44c1cd35f17c43eeba92e4e98e803aab5d8b51ca9 source_path: web/control-ui.md workflow: 15 --- @@ -19,30 +19,30 @@ Control UI 是一个由 Gateway 网关提供服务的小型 **Vite + Lit** 单 - 默认：`http://:18789/` - 可选前缀：设置 `gateway.controlUi.basePath`（例如 `/openclaw`） -它会在同一端口上**直接连接到 Gateway WebSocket**。 +它会在同一端口上**直接连接到 Gateway 网关 WebSocket**。 ## 快速打开（本地） -如果 Gateway 网关运行在同一台电脑上，请打开： +如果 Gateway 网关 运行在同一台计算机上，请打开： - [http://127.0.0.1:18789/](http://127.0.0.1:18789/)（或 [http://localhost:18789/](http://localhost:18789/)） -如果页面加载失败，请先启动 Gateway 网关：`openclaw gateway`。 +如果页面无法加载，请先启动 Gateway 网关：`openclaw gateway`。 认证会在 WebSocket 握手期间通过以下方式提供： - `connect.params.auth.token` - `connect.params.auth.password` - 当 `gateway.auth.allowTailscale: true` 时，使用 Tailscale Serve 身份标头 -- 当 `gateway.auth.mode: "trusted-proxy"` 时，使用受信任代理身份标头 +- 当 `gateway.auth.mode: "trusted-proxy"` 时，使用 trusted-proxy 身份标头 -仪表板设置面板会为当前浏览器标签页会话和所选 Gateway 网关 URL 保存一个 token；密码不会被持久化。新手引导通常会在首次连接时为共享密钥认证生成一个 gateway token，但当 `gateway.auth.mode` 为 `"password"` 时，密码认证也可以使用。 +仪表板设置面板会为当前浏览器标签页会话和所选 Gateway 网关 URL 保存一个令牌；不会持久保存密码。新手引导通常会在首次连接时为共享密钥认证生成一个 Gateway 网关 令牌，但当 `gateway.auth.mode` 为 `"password"` 时，也可以使用密码认证。 ## 设备配对（首次连接） -当你从新的浏览器或设备连接到 Control UI 时，Gateway 网关通常会要求进行**一次性配对批准**。这是一项安全措施，用于防止未授权访问。 +当你从新的浏览器或设备连接到 Control UI 时，Gateway 网关 通常会要求进行**一次性配对批准**。这是一项安全措施，用于防止未授权访问。 -**你会看到：** “已断开连接（1008）：需要配对” +**你会看到：** “disconnected (1008): pairing required” @@ -57,81 +57,81 @@ Control UI 是一个由 Gateway 网关提供服务的小型 **Vite + Lit** 单 -如果浏览器在认证详情发生变化后重试配对（角色 / 作用域 / 公钥），之前待处理的请求会被新请求取代，并创建新的 `requestId`。请在批准前重新运行 `openclaw devices list`。 +如果浏览器在配对重试时更改了认证详情（角色/作用域/公钥），先前的待处理请求会被替代，并创建新的 `requestId`。批准前请重新运行 `openclaw devices list`。 -如果浏览器已经完成配对，而你将其权限从只读改为写入 / 管理员权限，这会被视为批准升级，而不是静默重新连接。OpenClaw 会保持旧批准有效，阻止更高权限的重新连接，并要求你显式批准新的作用域集合。 +如果浏览器已经配对，而你将其从只读权限更改为写入/管理员权限，这会被视为一次权限升级批准，而不是静默重连。OpenClaw 会保留旧的批准状态，阻止更高权限的重连，并要求你显式批准新的作用域集合。 -一旦获得批准，该设备就会被记住，除非你使用 `openclaw devices revoke --device --role ` 撤销它，否则无需再次批准。有关 token 轮换和撤销的信息，请参阅 [Devices CLI](/zh-CN/cli/devices)。 +一旦获批，该设备会被记住，除非你使用 `openclaw devices revoke --device --role ` 撤销，否则无需再次批准。有关令牌轮换和撤销，参见 [Devices CLI](/zh-CN/cli/devices)。 -- 直接的本地 local loopback 浏览器连接（`127.0.0.1` / `localhost`）会被自动批准。 -- 当 `gateway.auth.allowTailscale: true`、Tailscale 身份校验通过且浏览器提供其设备身份时，Tailscale Serve 可以跳过 Control UI 操作员会话的配对往返过程。 -- 直接 Tailnet 绑定、LAN 浏览器连接以及不带设备身份的浏览器配置文件仍然需要显式批准。 +- 直接使用 local loopback 浏览器连接（`127.0.0.1` / `localhost`）会被自动批准。 +- 当 `gateway.auth.allowTailscale: true`、Tailscale 身份验证通过且浏览器提供其设备身份时，Tailscale Serve 可跳过 Control UI 操作员会话的配对往返流程。 +- 直接绑定 Tailnet、LAN 浏览器连接，以及没有设备身份的浏览器配置文件，仍然需要显式批准。 - 每个浏览器配置文件都会生成唯一的设备 ID，因此切换浏览器或清除浏览器数据都需要重新配对。 ## 个人身份（浏览器本地） -Control UI 支持按浏览器设置个人身份（显示名称和头像），并将其附加到发出的消息中，以便在共享会话中标注归属。它保存在浏览器存储中，仅限当前浏览器配置文件使用，不会同步到其他设备，也不会在服务端持久化，除了你实际发送消息上的常规消息作者元数据之外。清除站点数据或切换浏览器会将其重置为空。 +Control UI 支持每个浏览器一个个人身份（显示名称和头像），它会附加到传出消息中，用于在共享会话中标注归属。它存储在浏览器本地，限定于当前浏览器配置文件，不会同步到其他设备，也不会在服务器端持久保存，除了你实际发送的消息中常规的转录作者元数据。清除站点数据或切换浏览器后，它会重置为空。 -同样的浏览器本地模式也适用于助手头像覆盖。上传的助手头像只会在本地浏览器中覆盖 gateway 解析出的身份，绝不会通过 `config.patch` 往返。共享的 `ui.assistant.avatar` 配置字段仍然可供直接写入该字段的非 UI 客户端使用（例如脚本化的 gateways 或自定义仪表板）。 +同样的浏览器本地模式也适用于助手头像覆盖。上传的助手头像只会在本地浏览器中覆盖 Gateway 网关 解析出的身份，绝不会通过 `config.patch` 往返传输。共享的 `ui.assistant.avatar` 配置字段仍然可供直接写入该字段的非 UI 客户端使用（例如脚本化 Gateway 网关 或自定义仪表板）。 ## 运行时配置端点 -Control UI 会从 `/__openclaw/control-ui-config.json` 获取其运行时设置。该端点受与其余 HTTP 表面相同的 gateway 认证保护：未认证的浏览器无法获取它，成功获取要求已具备有效的 gateway token / 密码、Tailscale Serve 身份或受信任代理身份之一。 +Control UI 会从 `/__openclaw/control-ui-config.json` 获取其运行时设置。该端点受与其他 HTTP 接口相同的 gateway 认证保护：未认证浏览器无法获取；成功获取需要已有效的 Gateway 网关 令牌/密码、Tailscale Serve 身份或 trusted-proxy 身份之一。 ## 语言支持 -Control UI 可以在首次加载时根据你的浏览器语言环境进行本地化。若要稍后覆盖它，请打开 **Overview -> Gateway Access -> Language**。语言选择器位于 Gateway Access 卡片中，而不在 Appearance 下。 +Control UI 可以在首次加载时根据你的浏览器语言环境进行本地化。如需之后覆盖，请打开 **Overview -> Gateway Access -> Language**。语言选择器位于 Gateway Access 卡片中，而不在外观设置下。 - 支持的语言环境：`en`、`zh-CN`、`zh-TW`、`pt-BR`、`de`、`es`、`ja-JP`、`ko`、`fr`、`tr`、`uk`、`id`、`pl`、`th` -- 非英语翻译会在浏览器中按需延迟加载。 -- 所选语言环境会保存在浏览器存储中，并在未来访问时复用。 +- 非英语翻译会在浏览器中按需懒加载。 +- 所选语言环境会保存在浏览器存储中，并在后续访问时复用。 - 缺失的翻译键会回退为英语。 ## 它目前能做什么 - - - 通过 Gateway WS 与模型聊天（`chat.history`、`chat.send`、`chat.abort`、`chat.inject`）。 - - 通过 WebRTC 直接从浏览器与 OpenAI Realtime 通话。Gateway 网关通过 `talk.realtime.session` 铸造一个短期有效的 Realtime 客户端密钥；浏览器将麦克风音频直接发送给 OpenAI，并通过 `chat.send` 将 `openclaw_agent_consult` 工具调用中继回去，以供更大且已配置的 OpenClaw 模型使用。 + + - 通过 Gateway 网关 WS 与模型聊天（`chat.history`、`chat.send`、`chat.abort`、`chat.inject`）。 + - 通过 WebRTC 直接从浏览器连接到 OpenAI Realtime 进行语音交流。Gateway 网关 通过 `talk.realtime.session` 签发短期有效的 Realtime 客户端密钥；浏览器将麦克风音频直接发送给 OpenAI，并通过 `chat.send` 将 `openclaw_agent_consult` 工具调用中继回去，以调用已配置的更大 OpenClaw 模型。 - 在聊天中流式显示工具调用 + 实时工具输出卡片（智能体事件）。 - - 渠道：内置以及内置 / 外部渠道插件的状态、二维码登录和按渠道配置（`channels.status`、`web.login.*`、`config.patch`）。 - - 实例：在线状态列表 + 刷新（`system-presence`）。 - - 会话：列表 + 按会话设置模型 / thinking / fast / verbose / trace / reasoning 覆盖（`sessions.list`、`sessions.patch`）。 - - Dreaming：Dreaming 状态、启用 / 禁用切换和 Dream Diary 读取器（`doctor.memory.status`、`doctor.memory.dreamDiary`、`config.patch`）。 + - 渠道：内置渠道以及内置/外部插件渠道的 Status、二维码登录和按渠道配置（`channels.status`、`web.login.*`、`config.patch`）。 + - 实例：在线列表 + 刷新（`system-presence`）。 + - 会话：列表 + 按会话的模型/思考/快速/详细/追踪/推理覆盖（`sessions.list`、`sessions.patch`）。 + - Dreaming：Dreaming 状态、启用/禁用切换和 Dream Diary 阅读器（`doctor.memory.status`、`doctor.memory.dreamDiary`、`config.patch`）。 - - Cron 作业：列出 / 添加 / 编辑 / 运行 / 启用 / 禁用 + 运行历史（`cron.*`）。 - - Skills：状态、启用 / 禁用、安装、API 密钥更新（`skills.*`）。 - - 节点：列表 + 能力上限（`node.list`）。 - - Exec 批准：编辑 gateway 或节点 allowlist + 为 `exec host=gateway/node` 询问策略（`exec.approvals.*`）。 + - Cron 作业：列出/添加/编辑/运行/启用/禁用 + 运行历史（`cron.*`）。 + - Skills：Status、启用/禁用、安装、API 密钥更新（`skills.*`）。 + - 节点：列表 + 能力（`node.list`）。 + - exec 批准：编辑 gateway 或节点允许列表 + 针对 `exec host=gateway/node` 的询问策略（`exec.approvals.*`）。 - - 查看 / 编辑 `~/.openclaw/openclaw.json`（`config.get`、`config.set`）。 - - 带验证地应用 + 重启（`config.apply`），并唤醒上次活动的会话。 - - 写入操作包含 base-hash 防护，以防覆盖并发编辑。 - - 写入（`config.set` / `config.apply` / `config.patch`）会对提交的配置负载中的 SecretRef 引用预先执行活动解析；未解析的活动提交引用会在写入前被拒绝。 - - Schema + 表单渲染（`config.schema` / `config.schema.lookup`，包括字段 `title` / `description`、匹配的 UI 提示、直接子项摘要、嵌套对象 / 通配符 / 数组 / 组合节点上的文档元数据，以及可用时的插件 + 渠道 schema）；仅当快照可以安全进行原始往返时，才提供原始 JSON 编辑器。 - - 如果某个快照无法安全进行原始往返，Control UI 会强制使用表单模式，并为该快照禁用原始模式。 - - 原始 JSON 编辑器中的“重置为已保存”会保留原始编写形态（格式、注释、`$include` 布局），而不是重新渲染扁平化快照，因此在快照可安全往返时，外部编辑在重置后仍会保留。 - - 结构化 SecretRef 对象值会在表单文本输入中以只读方式呈现，以防止意外将对象破坏为字符串。 + - 查看/编辑 `~/.openclaw/openclaw.json`（`config.get`、`config.set`）。 + - 应用 + 重启并进行验证（`config.apply`），并唤醒最近活跃的会话。 + - 写入包含 base-hash 保护，以防覆盖并发编辑。 + - 写入（`config.set`/`config.apply`/`config.patch`）会在提交配置 payload 中，对活动 `SecretRef` 解析进行预检；若提交的活动引用无法解析，则会在写入前被拒绝。 + - schema + 表单渲染（`config.schema` / `config.schema.lookup`，包括字段 `title` / `description`、匹配的 UI 提示、直接子项摘要、嵌套对象/通配符/数组/组合节点上的文档元数据，以及可用时的插件 + 渠道 schema）；仅当快照可安全进行原始往返时，才提供原始 JSON 编辑器。 + - 如果某个快照无法安全地进行原始往返，Control UI 会强制使用表单模式，并为该快照禁用原始模式。 + - 原始 JSON 编辑器的“Reset to saved”会保留原始编写形状（格式、注释、`$include` 布局），而不是重新渲染扁平化快照，因此只要快照可以安全往返，外部编辑在重置后也能保留。 + - 结构化 `SecretRef` 对象值会在表单文本输入中以只读方式渲染，以防意外把对象损坏成字符串。 - - 调试：状态 / 健康 / 模型快照 + 事件日志 + 手动 RPC 调用（`status`、`health`、`models.list`）。 - - 日志：带过滤 / 导出的 gateway 文件日志实时尾部查看（`logs.tail`）。 - - 更新：运行 package / git 更新 + 重启（`update.run`），并生成重启报告。 + - 调试：status/health/models 快照 + 事件日志 + 手动 RPC 调用（`status`、`health`、`models.list`）。 + - 日志：带筛选/导出的 gateway 文件日志实时 tail（`logs.tail`）。 + - 更新：运行 package/git 更新 + 重启（`update.run`），并附带重启报告。 - - 对于隔离作业，投递默认值为公告摘要。如果你只想进行内部运行，可以切换为 none。 - - 选择 announce 时会显示渠道 / 目标字段。 - - Webhook 模式使用 `delivery.mode = "webhook"`，并将 `delivery.to` 设置为有效的 HTTP(S) webhook URL。 - - 对于主会话作业，支持 webhook 和 none 投递模式。 - - 高级编辑控件包括：运行后删除、清除智能体覆盖、cron 精确 / 错开选项、智能体模型 / thinking 覆盖，以及尽力投递切换。 + - 对于隔离作业，投递方式默认是公告摘要。若你只想内部运行，可以切换为 none。 + - 选择公告时，会显示渠道/目标字段。 + - webhook 模式使用 `delivery.mode = "webhook"`，并将 `delivery.to` 设置为有效的 HTTP(S) webhook URL。 + - 对于主会话作业，可使用 webhook 和 none 投递模式。 + - 高级编辑控件包括运行后删除、清除智能体覆盖、cron 精确/错峰选项、智能体模型/思考覆盖以及尽力投递切换。 - 表单验证为内联字段级错误；在修复前，无效值会禁用保存按钮。 - - 设置 `cron.webhookToken` 以发送专用 bearer token；如果省略，则 webhook 会在不带认证标头的情况下发送。 + - 设置 `cron.webhookToken` 可发送专用 bearer token；如果省略，webhook 将在无认证标头的情况下发送。 - 已弃用的回退：存储的旧版作业若带有 `notify: true`，在迁移前仍可使用 `cron.webhook`。 @@ -140,77 +140,77 @@ Control UI 可以在首次加载时根据你的浏览器语言环境进行本地 - - `chat.send` 是**非阻塞**的：它会立即以 `{ runId, status: "started" }` 确认，随后响应通过 `chat` 事件流式传输。 - - 聊天上传支持图片以及非视频文件。图片保留原生图片路径；其他文件会存储为受管媒体，并在历史中显示为附件链接。 - - 使用相同的 `idempotencyKey` 重新发送时，运行中会返回 `{ status: "in_flight" }`，完成后会返回 `{ status: "ok" }`。 - - 出于 UI 安全考虑，`chat.history` 响应有大小限制。当转录条目过大时，Gateway 网关可能会截断长文本字段、省略较重的元数据块，并用占位符替换超大消息（`[chat.history omitted: message too large]`）。 - - 助手 / 生成的图片会作为受管媒体引用持久化，并通过经认证的 Gateway 网关媒体 URL 返回，因此重新加载时不依赖原始 base64 图片负载仍保留在 `chat.history` 响应中。 - - `chat.history` 还会从可见的助手文本中移除仅用于显示的内联指令标签（例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`）、纯文本工具调用 XML 负载（包括 `...`、`...`、`...`、`...` 以及被截断的工具调用块）、以及泄漏的 ASCII / 全角模型控制 token，并省略那些整个可见文本仅为精确静默 token `NO_REPLY` / `no_reply` 的助手条目。 - - 在主动发送期间以及最终历史刷新时，如果 `chat.history` 短暂返回较旧快照，聊天视图会保持本地乐观用户 / 助手消息可见；一旦 Gateway 网关历史追上，规范转录就会替换这些本地消息。 - - `chat.inject` 会向会话转录追加一条助手备注，并广播一个 `chat` 事件用于仅 UI 更新（不运行智能体，不进行渠道投递）。 - - 聊天头部中的模型和 thinking 选择器会立即通过 `sessions.patch` 修补当前活动会话；它们是持久的会话覆盖，而不是仅单轮发送选项。 - - 当新的 Gateway 网关会话用量报告显示上下文压力较高时，聊天输入区域会显示上下文提示，并在建议压缩级别下显示一个压缩按钮，以运行正常的会话压缩路径。在 Gateway 网关再次报告新的用量之前，过期的 token 快照会被隐藏。 + - `chat.send` 是**非阻塞**的：它会立即确认并返回 `{ runId, status: "started" }`，响应会通过 `chat` 事件流式传输。 + - 聊天上传支持图片和非视频文件。图片保留原生图片路径；其他文件存储为托管媒体，并在历史记录中显示为附件链接。 + - 使用相同 `idempotencyKey` 重新发送时，运行中返回 `{ status: "in_flight" }`，完成后返回 `{ status: "ok" }`。 + - `chat.history` 响应有大小限制，以确保 UI 安全。当转录条目过大时，Gateway 网关 可能会截断长文本字段、省略较重的元数据块，并用占位符替换超大消息（`[chat.history omitted: message too large]`）。 + - 助手/生成的图片会作为托管媒体引用持久保存，并通过已认证的 Gateway 网关 媒体 URL 返回，因此重新加载时不依赖聊天历史响应中保留原始 base64 图片 payload。 + - `chat.history` 还会从可见的助手文本中剥离仅用于显示的内联指令标签（例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`）、纯文本工具调用 XML payload（包括 `...`、`...`、`...`、`...` 以及被截断的工具调用块），并去除泄露的 ASCII/全角模型控制令牌；如果某条助手条目的全部可见文本仅为精确的静默令牌 `NO_REPLY` / `no_reply`，则会被省略。 + - 在活跃发送期间以及最终历史刷新期间，如果 `chat.history` 短暂返回较旧快照，聊天视图会保持本地乐观用户/助手消息可见；一旦 Gateway 网关 历史追上，规范转录就会替换这些本地消息。 + - `chat.inject` 会向会话转录追加一条助手备注，并广播 `chat` 事件用于仅 UI 更新（不触发智能体运行，也不投递到渠道）。 + - 聊天头部中的模型和思考选择器会通过 `sessions.patch` 立即修改活跃会话；它们是持久性的会话覆盖，而不是单轮发送选项。 + - 当新的 Gateway 网关 会话用量报告显示上下文压力较高时，聊天输入区域会显示上下文提示，并在建议压缩级别时显示一个 compact 按钮，以运行常规会话压缩路径。在 Gateway 网关 再次报告新鲜用量前，陈旧的令牌快照会被隐藏。 - - 通话模式使用已注册的实时语音提供商，该提供商支持浏览器 WebRTC 会话。请配置 OpenAI，设置 `talk.provider: "openai"` 以及 `talk.providers.openai.apiKey`，或复用 Voice Call 实时提供商配置。浏览器永远不会接收到标准 OpenAI API 密钥；它只会接收临时的 Realtime 客户端密钥。Google Live 实时语音支持后端 Voice Call 和 Google Meet 桥接，但尚不支持此浏览器 WebRTC 路径。Realtime 会话提示词由 Gateway 网关组装；`talk.realtime.session` 不接受调用方提供的指令覆盖。 + + 语音模式使用已注册、支持浏览器 WebRTC 会话的实时语音提供商。请配置 OpenAI：`talk.provider: "openai"` 加上 `talk.providers.openai.apiKey`，或复用 Voice Call 的实时 provider 配置。浏览器永远不会收到标准 OpenAI API 密钥；它只会收到临时 Realtime 客户端密钥。Google Live 实时语音支持后端 Voice Call 和 Google Meet 桥接，但暂不支持这个浏览器 WebRTC 路径。Realtime 会话提示由 Gateway 网关 组装；`talk.realtime.session` 不接受调用方提供的指令覆盖。 - 在聊天输入框中，Talk 控件是麦克风听写按钮旁边的波形按钮。当 Talk 启动时，输入框状态行会显示 `Connecting Talk...`，音频连接后显示 `Talk live`，而当实时工具调用通过 `chat.send` 向已配置的更大 OpenClaw 模型发起咨询时，则显示 `Asking OpenClaw...`。 + 在聊天输入框中，Talk 控件是麦克风听写按钮旁边的波形按钮。当 Talk 启动时，输入框状态行会显示 `Connecting Talk...`，音频连接后显示 `Talk live`，或者在实时工具调用通过 `chat.send` 咨询已配置的更大 OpenClaw 模型时显示 `Asking OpenClaw...`。 - 点击 **Stop**（调用 `chat.abort`）。 - - 当某次运行处于活动状态时，普通后续消息会排队。点击已排队消息上的 **Steer** 可将该后续内容注入到正在运行的当前轮次中。 - - 输入 `/stop`（或单独的中止短语，例如 `stop`、`stop action`、`stop run`、`stop openclaw`、`please stop`）即可进行带外中止。 - - `chat.abort` 支持 `{ sessionKey }`（无需 `runId`）以中止该会话的所有活动运行。 + - 当某次运行处于活跃状态时，普通后续消息会进入队列。点击队列消息上的 **Steer**，可将该后续消息注入到当前运行中的轮次。 + - 输入 `/stop`（或独立的中止短语，例如 `stop`、`stop action`、`stop run`、`stop openclaw`、`please stop`）可进行带外中止。 + - `chat.abort` 支持 `{ sessionKey }`（不带 `runId`），用于中止该会话的所有活跃运行。 - - 当某次运行被中止时，UI 中仍可能显示部分助手文本。 - - 当存在缓冲输出时，Gateway 网关会将中止时的部分助手文本持久化到转录历史中。 - - 持久化条目会包含中止元数据，以便转录消费者区分“中止的部分内容”和正常完成输出。 + - 当某次运行被中止时，部分助手文本仍可能显示在 UI 中。 + - 当存在缓冲输出时，Gateway 网关 会将中止时的部分助手文本持久保存到转录历史中。 + - 持久化条目包含中止元数据，因此转录消费者可以区分中止的部分内容与正常完成输出。 ## PWA 安装与 Web Push -Control UI 提供了 `manifest.webmanifest` 和 service worker，因此现代浏览器可以将其安装为独立的 PWA。Web Push 允许 Gateway 网关通过通知唤醒已安装的 PWA，即使标签页或浏览器窗口未打开也是如此。 +Control UI 附带了一个 `manifest.webmanifest` 和一个 service worker，因此现代浏览器可以将其安装为独立的 PWA。Web Push 允许 Gateway 网关 通过通知唤醒已安装的 PWA，即使标签页或浏览器窗口未打开也是如此。 -| 表面 | 作用 | +| 界面 | 作用 | | ----------------------------------------------------- | ------------------------------------------------------------------ | -| `ui/public/manifest.webmanifest` | PWA 清单。一旦可访问，浏览器就会提供“安装应用”选项。 | -| `ui/public/sw.js` | 处理 `push` 事件和通知点击的 service worker。 | -| `push/vapid-keys.json`（位于 OpenClaw 状态目录下） | 自动生成的 VAPID 密钥对，用于签名 Web Push 负载。 | -| `push/web-push-subscriptions.json` | 持久化的浏览器订阅端点。 | +| `ui/public/manifest.webmanifest` | PWA manifest。浏览器在它可访问后会提供“安装应用”。 | +| `ui/public/sw.js` | 处理 `push` 事件和通知点击的 service worker。 | +| `push/vapid-keys.json`（位于 OpenClaw 状态目录下） | 自动生成的 VAPID 密钥对，用于签名 Web Push payload。 | +| `push/web-push-subscriptions.json` | 持久化保存的浏览器订阅端点。 | -如果你希望固定密钥（用于多主机部署、密钥轮换或测试），可以通过 Gateway 网关进程上的环境变量覆盖 VAPID 密钥对： +当你希望固定密钥对时（例如多主机部署、密钥轮换或测试），可通过 Gateway 网关 进程上的环境变量覆盖 VAPID 密钥对： - `OPENCLAW_VAPID_PUBLIC_KEY` - `OPENCLAW_VAPID_PRIVATE_KEY` -- `OPENCLAW_VAPID_SUBJECT`（默认为 `mailto:openclaw@localhost`） +- `OPENCLAW_VAPID_SUBJECT`（默认值为 `mailto:openclaw@localhost`） -Control UI 使用以下受作用域限制的 Gateway 网关方法来注册和测试浏览器订阅： +Control UI 使用以下带作用域控制的 Gateway 网关 方法来注册和测试浏览器订阅： -- `push.web.vapidPublicKey` — 获取当前激活的 VAPID 公钥。 +- `push.web.vapidPublicKey` — 获取当前启用的 VAPID 公钥。 - `push.web.subscribe` — 注册 `endpoint` 以及 `keys.p256dh` / `keys.auth`。 -- `push.web.unsubscribe` — 移除已注册的端点。 -- `push.web.test` — 向调用者的订阅发送测试通知。 +- `push.web.unsubscribe` — 移除已注册端点。 +- `push.web.test` — 向调用方的订阅发送一条测试通知。 -Web Push 独立于 iOS APNS 中继路径（有关基于中继的推送，请参阅 [Configuration](/zh-CN/gateway/configuration)）以及现有的 `push.test` 方法，后两者针对的是原生移动端配对。 +Web Push 独立于 iOS APNS 中继路径（中继支持的推送参见[配置](/zh-CN/gateway/configuration)）以及现有的 `push.test` 方法，后者面向原生移动端配对。 ## 托管嵌入 -助手消息可以使用 `[embed ...]` shortcode 内联渲染托管网页内容。iframe 的 sandbox 策略由 `gateway.controlUi.embedSandbox` 控制： +助手消息可以使用 `[embed ...]` 短代码内联渲染托管网页内容。iframe 的沙箱策略由 `gateway.controlUi.embedSandbox` 控制： - 禁止在托管嵌入内容中执行脚本。 + 禁止在托管嵌入中执行脚本。 - 允许交互式嵌入，同时保持源隔离；这是默认值，通常足以支持自包含的浏览器游戏 / 小组件。 + 允许交互式嵌入，同时保持源隔离；这是默认值，通常足以支持自包含的浏览器游戏/小组件。 - 在 `allow-scripts` 之上额外添加 `allow-same-origin`，用于那些有意需要更高权限的同站点文档。 + 在 `allow-scripts` 的基础上额外添加 `allow-same-origin`，用于有意需要更强权限的同站点文档。 @@ -227,16 +227,16 @@ Web Push 独立于 iOS APNS 中继路径（有关基于中继的推送，请参 ``` -只有当被嵌入文档确实需要 same-origin 行为时才使用 `trusted`。对于大多数由智能体生成的游戏和交互式画布，`scripts` 是更安全的选择。 +仅当嵌入文档确实需要 same-origin 行为时才使用 `trusted`。对于大多数由智能体生成的游戏和交互式画布，`scripts` 是更安全的选择。 -绝对外部 `http(s)` 嵌入 URL 默认仍会被阻止。如果你确实希望 `[embed url="https://..."]` 加载第三方页面，请设置 `gateway.controlUi.allowExternalEmbedUrls: true`。 +绝对外部 `http(s)` 嵌入 URL 默认仍会被阻止。如果你有意让 `[embed url="https://..."]` 加载第三方页面，请设置 `gateway.controlUi.allowExternalEmbedUrls: true`。 ## Tailnet 访问（推荐） - - 将 Gateway 网关保持在 loopback 上，并让 Tailscale Serve 通过 HTTPS 代理它： + + 让 Gateway 网关 保持绑定在 loopback 上，并通过 Tailscale Serve 使用 HTTPS 进行代理： ```bash openclaw gateway --tailscale serve @@ -246,12 +246,12 @@ Web Push 独立于 iOS APNS 中继路径（有关基于中继的推送，请参 - `https:///`（或你配置的 `gateway.controlUi.basePath`） - 默认情况下，当 `gateway.auth.allowTailscale` 为 `true` 时，Control UI / WebSocket Serve 请求可以通过 Tailscale 身份标头（`tailscale-user-login`）进行认证。OpenClaw 会通过 `tailscale whois` 解析 `x-forwarded-for` 地址并与该标头进行匹配来验证身份，而且只有当请求命中 loopback 且带有 Tailscale 的 `x-forwarded-*` 标头时才会接受这些信息。对于带有浏览器设备身份的 Control UI 操作员会话，这条经过验证的 Serve 路径还会跳过设备配对往返过程；不带设备身份的浏览器以及 node 角色连接仍然遵循正常的设备检查。如果你希望即使对 Serve 流量也要求显式共享密钥凭证，请将 `gateway.auth.allowTailscale: false`。然后使用 `gateway.auth.mode: "token"` 或 `"password"`。 + 默认情况下，当 `gateway.auth.allowTailscale` 为 `true` 时，Control UI/WebSocket 的 Serve 请求可以通过 Tailscale 身份标头（`tailscale-user-login`）进行认证。OpenClaw 会通过 `tailscale whois` 解析 `x-forwarded-for` 地址并将其与该标头匹配来验证身份，并且只有当请求到达 loopback 且带有 Tailscale 的 `x-forwarded-*` 标头时才接受这些请求。对于带有浏览器设备身份的 Control UI 操作员会话，这条经过验证的 Serve 路径还会跳过设备配对往返；没有设备身份的浏览器以及 node 角色连接仍遵循正常设备检查。如果你希望即使对 Serve 流量也要求显式共享密钥凭证，请设置 `gateway.auth.allowTailscale: false`。然后使用 `gateway.auth.mode: "token"` 或 `"password"`。 - 对于该异步 Serve 身份路径，来自同一客户端 IP 和认证作用域的失败认证尝试会在写入限速记录前进行串行化。因此，同一浏览器的并发错误重试在第二个请求上可能显示 `retry later`，而不是两个普通不匹配并行竞争。 + 对于该异步 Serve 身份路径，相同客户端 IP 和认证范围下的失败认证尝试会在写入限速前串行处理。因此，同一浏览器的并发错误重试在第二个请求上可能会显示 `retry later`，而不是两个普通不匹配并行竞争。 - 无 token 的 Serve 认证假定 gateway 主机是可信的。如果该主机上可能运行不受信任的本地代码，请要求使用 token / password 认证。 + 无令牌的 Serve 认证假定 gateway 主机是可信的。如果该主机上可能运行不可信的本地代码，请要求 token/password 认证。 @@ -264,7 +264,7 @@ Web Push 独立于 iOS APNS 中继路径（有关基于中继的推送，请参 - `http://:18789/`（或你配置的 `gateway.controlUi.basePath`） - 将匹配的共享密钥粘贴到 UI 设置中（作为 `connect.params.auth.token` 或 `connect.params.auth.password` 发送）。 + 将对应的共享密钥粘贴到 UI 设置中（作为 `connect.params.auth.token` 或 `connect.params.auth.password` 发送）。 @@ -273,11 +273,11 @@ Web Push 独立于 iOS APNS 中继路径（有关基于中继的推送，请参 如果你通过纯 HTTP 打开仪表板（`http://` 或 `http://`），浏览器会运行在**非安全上下文**中，并阻止 WebCrypto。默认情况下，OpenClaw 会**阻止**没有设备身份的 Control UI 连接。 -已记录的例外情况： +文档说明的例外情况： - 使用 `gateway.controlUi.allowInsecureAuth=true` 的仅 localhost 不安全 HTTP 兼容模式 - 通过 `gateway.auth.mode: "trusted-proxy"` 成功完成的操作员 Control UI 认证 -- 紧急兜底用法 `gateway.controlUi.dangerouslyDisableDeviceAuth=true` +- 紧急开关 `gateway.controlUi.dangerouslyDisableDeviceAuth=true` **推荐修复方式：** 使用 HTTPS（Tailscale Serve）或在本地打开 UI： @@ -296,14 +296,14 @@ Web Push 独立于 iOS APNS 中继路径（有关基于中继的推送，请参 } ``` - `allowInsecureAuth` 仅是本地兼容性开关： + `allowInsecureAuth` 只是一个本地兼容性开关： - - 它允许 localhost 上的 Control UI 会话在非安全 HTTP 上下文中无设备身份继续进行。 + - 它允许 localhost 的 Control UI 会话在非安全 HTTP 上下文中无设备身份继续运行。 - 它不会绕过配对检查。 - 它不会放宽远程（非 localhost）设备身份要求。 - + ```json5 { gateway: { @@ -315,70 +315,70 @@ Web Push 独立于 iOS APNS 中继路径（有关基于中继的推送，请参 ``` - `dangerouslyDisableDeviceAuth` 会禁用 Control UI 设备身份检查，是严重的安全降级。紧急使用后请尽快恢复。 + `dangerouslyDisableDeviceAuth` 会禁用 Control UI 设备身份检查，这是严重的安全降级。紧急使用后请尽快恢复。 - - - 成功的受信任代理认证可以允许**操作员** Control UI 会话在没有设备身份的情况下接入。 - - 这**不**适用于 node 角色的 Control UI 会话。 - - 同主机 loopback 反向代理仍不能满足受信任代理认证；请参阅 [Trusted proxy auth](/zh-CN/gateway/trusted-proxy-auth)。 + + - 成功的 trusted-proxy 认证可以允许**操作员** Control UI 会话在无设备身份的情况下接入。 + - 这**不适用于** node 角色的 Control UI 会话。 + - 同主机 loopback 反向代理仍然不能满足 trusted-proxy 认证要求；参见[Trusted proxy auth](/zh-CN/gateway/trusted-proxy-auth)。 -有关 HTTPS 设置指导，请参阅 [Tailscale](/zh-CN/gateway/tailscale)。 +有关 HTTPS 设置指南，参见 [Tailscale](/zh-CN/gateway/tailscale)。 ## 内容安全策略 -Control UI 采用了严格的 `img-src` 策略：只允许**同源**资源、`data:` URL 和本地生成的 `blob:` URL。远程 `http(s)` 和协议相对图片 URL 会被浏览器拒绝，并且不会发起网络请求。 +Control UI 附带严格的 `img-src` 策略：仅允许**同源**资源、`data:` URL 和本地生成的 `blob:` URL。远程 `http(s)` 和协议相对图片 URL 会被浏览器拒绝，且不会发起网络请求。 -这在实际中意味着： +这在实践中的含义： -- 通过相对路径提供的头像和图片（例如 `/avatars/`）仍然会显示，包括那些 UI 获取后转换为本地 `blob:` URL 的、需要认证的头像路由。 -- 内联 `data:image/...` URL 仍然会显示（适用于协议内负载）。 -- 由 Control UI 创建的本地 `blob:` URL 仍然会显示。 -- 由渠道元数据输出的远程头像 URL 会在 Control UI 的头像辅助函数中被剥离，并替换为内置 logo / badge，因此即使渠道被攻陷或是恶意的，也无法强制操作员浏览器任意抓取远程图片。 +- 通过相对路径提供的头像和图片（例如 `/avatars/`）仍可渲染，包括 UI 获取后转换为本地 `blob:` URL 的需要认证的头像路由。 +- 内联 `data:image/...` URL 仍可渲染（这对协议内 payload 很有用）。 +- Control UI 创建的本地 `blob:` URL 仍可渲染。 +- 渠道元数据输出的远程头像 URL 会在 Control UI 的头像辅助层中被剥离，并替换为内置 logo/badge，因此受损或恶意渠道无法强制操作员浏览器发起任意远程图片请求。 你无需做任何修改即可获得此行为——它始终启用且不可配置。 ## 头像路由认证 -当配置了 gateway 认证后，Control UI 头像端点要求与其余 API 相同的 gateway token： +当配置了 gateway 认证时，Control UI 头像端点要求与其余 API 相同的 gateway token： -- `GET /avatar/` 仅向已认证调用者返回头像图片。`GET /avatar/?meta=1` 在同样规则下返回头像元数据。 -- 对任一路由的未认证请求都会被拒绝（与相邻的 assistant-media 路由保持一致）。这可防止头像路由在其他部分已受保护的主机上泄露智能体身份。 -- Control UI 自身在获取头像时会以 bearer 标头转发 gateway token，并使用已认证的 blob URL，因此图片仍可在仪表板中显示。 +- `GET /avatar/` 仅向已认证调用方返回头像图片。`GET /avatar/?meta=1` 在相同规则下返回头像元数据。 +- 对任一路由的未认证请求都会被拒绝（与相邻的助手媒体路由一致）。这可防止头像路由在原本受保护的主机上泄露智能体身份。 +- Control UI 自身在获取头像时，会将 gateway token 作为 bearer 标头转发，并使用经认证的 blob URL，因此图片仍能在仪表板中渲染。 -如果你禁用了 gateway 认证（不建议在共享主机上这样做），头像路由也会随之变为未认证状态，与 gateway 的其余部分保持一致。 +如果你禁用了 gateway 认证（不建议在共享主机上这样做），头像路由也会像 gateway 其余部分一样变为未认证。 ## 构建 UI -Gateway 网关从 `dist/control-ui` 提供静态文件。使用以下命令构建： +Gateway 网关 从 `dist/control-ui` 提供静态文件。使用以下命令构建： ```bash pnpm ui:build ``` -可选的绝对 base（当你希望使用固定资源 URL 时）： +可选的绝对 base（当你希望固定资源 URL 时）： ```bash OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build ``` -用于本地开发（单独的开发服务器）： +用于本地开发（独立 dev server）： ```bash pnpm ui:dev ``` -然后将 UI 指向你的 Gateway WS URL（例如 `ws://127.0.0.1:18789`）。 +然后将 UI 指向你的 Gateway 网关 WS URL（例如 `ws://127.0.0.1:18789`）。 -## 调试 / 测试：开发服务器 + 远程 Gateway +## 调试/测试：dev server + 远程 Gateway -Control UI 是静态文件；WebSocket 目标是可配置的，并且可以与 HTTP 源不同。当你希望在本地运行 Vite 开发服务器，而 Gateway 网关运行在其他地方时，这非常方便。 +Control UI 是静态文件；WebSocket 目标可配置，并且可以不同于 HTTP 源。这在你希望本地运行 Vite dev server、但 Gateway 网关 运行在其他地方时非常有用。 - + ```bash pnpm ui:dev ``` @@ -398,17 +398,17 @@ Control UI 是静态文件；WebSocket 目标是可配置的，并且可以与 H - - - `gatewayUrl` 会在加载后存储到 `localStorage` 中，并从 URL 里移除。 - - `token` 应尽可能通过 URL 片段传递（`#token=...`）。片段不会发送到服务器，这样可以避免请求日志和 Referer 泄露。为了兼容性，旧版 `?token=` 查询参数仍会被一次性导入，但仅作为后备方式，并会在引导完成后立即移除。 + + - `gatewayUrl` 会在加载后存储到 `localStorage` 中，并从 URL 中移除。 + - 应尽可能通过 URL 片段（`#token=...`）传递 `token`。片段不会发送到服务器，因此可避免请求日志和 Referer 泄露。出于兼容性，旧版 `?token=` 查询参数仍会被一次性导入，但仅作为回退方案，并会在启动后立即移除。 - `password` 仅保存在内存中。 - - 当设置了 `gatewayUrl` 时，UI 不会回退到配置或环境变量凭证。请显式提供 `token`（或 `password`）。缺少显式凭证会报错。 - - 当 Gateway 网关位于 TLS 后面时（Tailscale Serve、HTTPS 代理等），请使用 `wss://`。 - - `gatewayUrl` 仅在顶层窗口中接受（非嵌入式），以防止点击劫持。 + - 设置 `gatewayUrl` 后，UI 不会回退到配置或环境变量凭证。请显式提供 `token`（或 `password`）。如果缺少显式凭证，将报错。 + - 当 Gateway 网关 位于 TLS 之后时（Tailscale Serve、HTTPS 代理等），请使用 `wss://`。 + - `gatewayUrl` 仅在顶层窗口中接受（不接受嵌入式场景），以防止点击劫持。 - 非 loopback 的 Control UI 部署必须显式设置 `gateway.controlUi.allowedOrigins`（完整 origin）。这也包括远程开发设置。 - - Gateway 网关启动时可能会根据实际运行时绑定和端口，预填充本地 origins，例如 `http://localhost:` 和 `http://127.0.0.1:`，但远程浏览器 origin 仍然需要显式条目。 - - 除非是严格受控的本地测试，否则不要使用 `gateway.controlUi.allowedOrigins: ["*"]`。它的含义是允许任意浏览器 origin，而不是“匹配我正在使用的任意主机”。 - - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 会启用 Host 标头 origin 回退模式，但这是一种危险的安全模式。 + - Gateway 网关 启动时，可能会根据实际运行时绑定地址和端口预填充本地 origin，例如 `http://localhost:` 和 `http://127.0.0.1:`，但远程浏览器 origin 仍需要显式条目。 + - 除非是在严格受控的本地测试环境中，否则不要使用 `gateway.controlUi.allowedOrigins: ["*"]`。它表示允许任意浏览器 origin，而不是“匹配我当前使用的任何主机”。 + - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 会启用 Host 标头 origin 回退模式，但这是危险的安全模式。 @@ -424,11 +424,11 @@ Control UI 是静态文件；WebSocket 目标是可配置的，并且可以与 H } ``` -远程访问设置详情： [Remote access](/zh-CN/gateway/remote)。 +远程访问设置详情： [远程访问](/zh-CN/gateway/remote)。 ## 相关内容 -- [Dashboard](/zh-CN/web/dashboard) — gateway 仪表板 -- [Health Checks](/zh-CN/gateway/health) — gateway 健康监控 +- [Dashboard](/zh-CN/web/dashboard) — Gateway 网关 仪表板 +- [Health Checks](/zh-CN/gateway/health) — Gateway 网关 健康监控 - [TUI](/zh-CN/web/tui) — 终端用户界面 - [WebChat](/zh-CN/web/webchat) — 基于浏览器的聊天界面