openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-25 03:27:44 +00:00
parent 695093c29c
commit ad95ce9322
9 changed files with 1157 additions and 1164 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

116
docs/zh-CN/cli/config.md
View File

@ -4,23 +4,23 @@ read_when:
summary: '`openclaw config` 的 CLI 参考（get/set/unset/file/schema/validate）'
title: 配置
x-i18n:
generated_at: "2026-04-24T03:14:44Z"
generated_at: "2026-04-25T03:24:47Z"
model: gpt-5.4
provider: openai
source_hash: 15e2eb75cc415df52ddcd104d8e5295d8d7b84baca65b4368deb3f06259f6bcd
source_hash: 1b8d5466d875967b6c9d5bf451f6affbe969d0ba5a48b98ee282612be67128db
source_path: cli/config.md
workflow: 15
---
# `openclaw config`
用于在 `openclaw.json` 中进行非交互式编辑的配置辅助工具：按路径 get/set/unset/file/schema/validate 值，并打印当前正在使用的配置文件。不带子命令运行时，会打开配置向导（与 `openclaw configure` 相同）。
用于在 `openclaw.json` 中进行非交互式编辑的配置辅助命令：按路径获取/设置/取消设置/输出文件/输出 schema/校验值，并打印当前生效的配置文件。不带子命令运行时，会打开配置向导（与 `openclaw configure` 相同）。
根选项：
- `--section <section>`：当你在不带子命令的情况下运行 `openclaw config` 时，可重复使用的引导式设置分区过滤器
- `--section <section>`：当你运行不带子命令的 `openclaw config` 时，可重复使用的引导式设置分区过滤器
支持的引导式分区：
支持的引导分区：
- `workspace`
- `model`
@ -54,26 +54,26 @@ openclaw config validate --json
### `config schema`
以 JSON 格式将为 `openclaw.json` 生成的 JSON schema 打印到标准输出。
将 `openclaw.json` 的生成式 JSON schema 以 JSON 形式打印到 stdout。
它包含的内容：
包含内容：
- 当前的根配置 schema，以及供编辑器工具使用的根 `$schema` 字符串字段
- 当前的根配置 schema，以及一个用于编辑器工具的根级 `$schema` 字符串字段
- Control UI 使用的字段 `title` 和 `description` 文档元数据
- 当存在匹配的字段文档时，嵌套对象、通配符（`*`）和数组项（`[]`）节点会继承相同的 `title` / `description` 元数据
- 当存在匹配的字段文档时，`anyOf` / `oneOf` / `allOf` 分支也会继承相同的文档元数据
- 当可以加载运行时清单时，尽力提供实时的插件 + 渠道 schema 元数据
- 即使当前配置无效，也会提供一个干净的回退 schema
- 当存在匹配字段文档时，嵌套对象、通配符（`*`）和数组项（`[]`）节点会继承相同的 `title` / `description` 元数据
- 当存在匹配字段文档时，`anyOf` / `oneOf` / `allOf` 分支也会继承相同的文档元数据
- 当能够加载运行时清单时，尽力提供实时的插件 + 渠道 schema 元数据
- 即使当前配置无效，也会提供一个干净的后备 schema
相关的运行时 RPC：
相关运行时 RPC：
- `config.schema.lookup` 会返回一个标准化的配置路径，以及一个浅层 schema 节点（`title`、`description`、`type`、`enum`、`const`、常见边界）、匹配的 UI 提示元数据和直接子项摘要。可将其用于 Control UI 或自定义客户端中的路径范围逐级查看。
- `config.schema.lookup` 会返回一个规范化的配置路径，以及一个浅层 schema 节点（`title`、`description`、`type`、`enum`、`const`、常见边界）、匹配的 UI 提示元数据和直接子项摘要。可将其用于 Control UI 或自定义客户端中的路径范围下钻。
```bash
openclaw config schema
```
当你想使用其他工具检查或验证它时，可以将其输出到文件：
当你想用其他工具检查或校验它时，可将其输出到文件：
```bash
openclaw config schema > openclaw.schema.json
@ -97,7 +97,7 @@ openclaw config set agents.list[1].tools.exec.node "node-id-or-name"
## 值
值会尽可能按 JSON5 解析；否则会被视为字符串。使用 `--strict-json` 可强制要求进行 JSON5 解析。`--json` 仍然作为旧版别名受支持。
值会尽可能按 JSON5 解析；否则会被视为字符串。使用 `--strict-json` 可强制要求进行 JSON5 解析。`--json` 仍然支持作为旧版别名。
```bash
openclaw config set agents.defaults.heartbeat.every "0m"
@ -105,18 +105,18 @@ openclaw config set gateway.port 19001 --strict-json
openclaw config set channels.whatsapp.groups '["*"]' --strict-json
```
`config get <path> --json` 会以 JSON 形式打印原始值，而不是终端格式化文本。
`config get <path> --json` 会将原始值以 JSON 形式打印，而不是终端格式化文本。
默认情况下，对象赋值会替换目标路径。对于那些通常保存用户新增条目的受保护 map/list 路径，例如 `agents.defaults.models`、`models.providers`、`models.providers.<id>.models`、`plugins.entries` 和 `auth.profiles`，如果替换会移除现有条目，则会拒绝该操作，除非你传入 `--replace`。
对象赋值默认会替换目标路径。对于通常存放用户新增条目的受保护映射/列表路径，例如 `agents.defaults.models`、`models.providers`、`models.providers.<id>.models`、`plugins.entries` 和 `auth.profiles`，如果替换会移除现有条目，则会拒绝，除非你传入 `--replace`。
当你向这些 map 添加条目时，请使用 `--merge`：
向这些映射中添加条目时，请使用 `--merge`：
```bash
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge
```
只有当你明确希望所提供的值成为完整目标值时，才使用 `--replace`。
仅当你明确希望提供的值成为完整目标值时，才使用 `--replace`。
## `config set` 模式
@ -143,7 +143,7 @@ openclaw config set secrets.providers.vault \
--provider-timeout-ms 5000
```
4. 批处理模式（`--batch-json` 或 `--batch-file`）：
4. 批量模式（`--batch-json` 或 `--batch-file`）：
```bash
openclaw config set --batch-json '[
@ -164,12 +164,12 @@ openclaw config set --batch-file ./config-set.batch.json --dry-run
策略说明：
- 对于不支持运行时可变的表面，SecretRef 赋值会被拒绝（例如 `hooks.token`、`commands.ownerDisplaySecret`、Discord 线程绑定 webhook token，以及 WhatsApp 凭证 JSON）。参见 [SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface)。
- 在不支持运行时可变的目标面上，SecretRef 赋值会被拒绝（例如 `hooks.token`、`commands.ownerDisplaySecret`、Discord 线程绑定 webhook token，以及 WhatsApp creds JSON）。参见 [SecretRef 凭证目标面](/zh-CN/reference/secretref-credential-surface)。
批处理解析始终以批处理负载（`--batch-json`/`--batch-file`）作为唯一真实来源。
`--strict-json` / `--json` 不会改变批处理解析行为。
批量解析始终将批量负载（`--batch-json`/`--batch-file`）作为事实来源。
`--strict-json` / `--json` 不会改变批量解析行为。
JSON 路径/值模式对 SecretRef 和提供商同样受支持：
JSON 路径/值模式同样支持 SecretRef 和提供商：
```bash
openclaw config set channels.discord.token \
@ -185,7 +185,7 @@ openclaw config set secrets.providers.vaultfile \
提供商构建器目标路径必须使用 `secrets.providers.<alias>`。
常用标志：
通用标志：
- `--provider-source <env|file|exec>`
- `--provider-timeout-ms <ms>`（`file`、`exec`）
@ -214,7 +214,7 @@ Exec 提供商（`--provider-source exec`）：
- `--provider-allow-insecure-path`
- `--provider-allow-symlink-command`
加固后的 Exec 提供商示例：
强化型 Exec 提供商示例：
```bash
openclaw config set secrets.providers.vault \
@ -230,7 +230,7 @@ openclaw config set secrets.providers.vault \
## Dry run
使用 `--dry-run` 可以在不写入 `openclaw.json` 的情况下验证更改。
使用 `--dry-run` 可在不写入 `openclaw.json` 的情况下校验变更。
```bash
openclaw config set channels.discord.token \
@ -256,22 +256,22 @@ openclaw config set channels.discord.token \
Dry-run 行为：
- 构建器模式：对已更改的 ref/provider 运行 SecretRef 可解析性检查。
- JSON 模式（`--strict-json`、`--json` 或批处理模式）：运行 schema 验证以及 SecretRef 可解析性检查。
- 已知不受支持的 SecretRef 目标表面也会运行策略验证。
- 策略检查会评估更改后的完整配置，因此父对象写入（例如将 `hooks` 设置为对象）不能绕过不受支持表面的验证。
- 为避免命令副作用，dry-run 默认会跳过 Exec SecretRef 检查。
- 将 `--allow-exec` 与 `--dry-run` 一起使用，可选择启用 Exec SecretRef 检查（这可能会执行提供商命令）。
- `--allow-exec` 仅适用于 dry-run；如果未与 `--dry-run` 一起使用会报错。
- 构建器模式：会对变更后的 ref/提供商运行 SecretRef 可解析性检查。
- JSON 模式（`--strict-json`、`--json` 或批量模式）：会运行 schema 校验以及 SecretRef 可解析性检查。
- 对于已知不支持的 SecretRef 目标面，也会运行策略校验。
- 策略检查会评估变更后的完整配置，因此父对象写入（例如将 `hooks` 设为对象）无法绕过不支持目标面的校验。
- 为避免命令副作用，dry-run 期间默认会跳过 Exec SecretRef 检查。
- 使用 `--allow-exec` 配合 `--dry-run` 可选择启用 Exec SecretRef 检查（这可能会执行提供商命令）。
- `--allow-exec` 仅用于 dry-run；如果不带 `--dry-run` 使用会报错。
`--dry-run --json` 会打印机器可读报告：
- `ok`：dry-run 是否通过
- `operations`：已评估的赋值操作数量
- `operations`：已评估的赋值数量
- `checks`：是否运行了 schema/可解析性检查
- `checks.resolvabilityComplete`：可解析性检查是否完整运行（当跳过 Exec ref 时为 false）
- `checks.resolvabilityComplete`：可解析性检查是否完整运行结束（当跳过 exec ref 时为 false）
- `refsChecked`：dry-run 期间实际解析的 ref 数量
- `skippedExecRefs`：由于未设置 `--allow-exec` 而被跳过的 Exec ref 数量
- `skippedExecRefs`：因未设置 `--allow-exec` 而跳过的 exec ref 数量
- `errors`：当 `ok=false` 时的结构化 schema/可解析性失败信息
### JSON 输出结构
@ -293,7 +293,7 @@ Dry-run 行为：
{
kind: "schema" | "resolvability",
message: string,
ref?: string, // 仅在可解析性错误时出现
ref?: string, // 用于可解析性错误时会出现
},
],
}
@ -344,16 +344,16 @@ Dry-run 行为：
如果 dry-run 失败：
- `config schema validation failed`：更改后的配置结构无效；请修复路径/值或 provider/ref 对象结构。
- `Config policy validation failed: unsupported SecretRef usage`：请将该凭证移回纯文本/字符串输入，并仅在受支持的表面上使用 SecretRefs。
- `SecretRef assignment(s) could not be resolved`：当前无法解析所引用的 provider/ref（缺少环境变量、文件指针无效、Exec 提供商失败，或 provider/source 不匹配）。
- `Dry run note: skipped <n> exec SecretRef resolvability check(s)`：dry-run 跳过了 Exec ref；如果你需要验证 Exec 可解析性，请使用 `--allow-exec` 重新运行。
- 对于批处理模式，请修复失败的条目，并在写入前重新运行 `--dry-run`。
- `config schema validation failed`：变更后的配置结构无效；请修正路径/值或提供商/ref 对象结构。
- `Config policy validation failed: unsupported SecretRef usage`：请将该凭证移回明文/字符串输入，并仅在受支持的目标面上使用 SecretRef。
- `SecretRef assignment(s) could not be resolved`：被引用的提供商/ref 当前无法解析（缺少环境变量、文件指针无效、Exec 提供商失败，或提供商/source 不匹配）。
- `Dry run note: skipped <n> exec SecretRef resolvability check(s)`：dry-run 跳过了 exec ref；如果你需要验证 exec 可解析性，请使用 `--allow-exec` 重新运行。
- 对于批量模式，请修复失败的条目，并在写入前重新运行 `--dry-run`。
## 写入安全
`openclaw config set` 和其他由 OpenClaw 拥有的配置写入器，会在提交到磁盘前验证更改后完整配置。如果新负载未通过 schema 验证，或看起来像是具有破坏性的覆盖，当前生效的配置将保持不变，而被拒绝的负载会保存到旁边，文件名为 `openclaw.json.rejected.*`。
当前生效的配置路径必须是常规文件。写入不支持使用符号链接的 `openclaw.json` 布局；请改用 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。
`openclaw config set` 和其他由 OpenClaw 管理的配置写入器，会在提交到磁盘之前校验变更后的完整配置。如果新负载未通过 schema 校验，或看起来像是破坏性覆盖，当前生效配置将保持不变，被拒绝的负载会以 `openclaw.json.rejected.*` 的形式保存在其旁边。
当前生效的配置路径必须是普通文件。写入时不支持符号链接形式的 `openclaw.json` 布局；请改用 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。
对于小改动，优先使用 CLI 写入：
@ -363,7 +363,7 @@ openclaw config set gateway.reload.mode hybrid
openclaw config validate
```
如果写入被拒绝，请检查保存的负载并修复完整配置结构：
如果写入被拒绝，请检查保存下来的负载，并修复完整配置结构：
```bash
CONFIG="$(openclaw config file)"
@ -371,32 +371,34 @@ ls -lt "$CONFIG".rejected.* 2>/dev/null | head
openclaw config validate
```
仍然允许直接通过编辑器写入，但正在运行的 Gateway 网关 会在这些更改通过验证之前将其视为不受信任。无效的直接编辑可在启动或热重载期间从最后一次已知有效备份中恢复。参见 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。
仍然允许直接通过编辑器写入，但正在运行的 Gateway 网关会在通过校验前将这些更改视为不可信。无效的直接编辑可能会在启动或热重载期间，通过上一次已知有效的备份进行恢复。参见 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。
整文件恢复仅用于全局损坏的配置，例如解析错误、根级 schema 校验失败、旧版迁移失败，或插件与根配置混合失败。如果校验仅在 `plugins.entries.<id>...` 下失败，OpenClaw 会保留当前生效的 `openclaw.json`，并报告该插件的局部问题，而不是恢复 `.last-good`。这样可以防止插件 schema 变更或 `minHostVersion` 偏差回滚与你无关的用户设置，例如模型、提供商、auth 配置档、渠道、Gateway 网关暴露方式、工具、内存、浏览器或 cron 配置。
## 子命令
- `config file`：打印当前生效的配置文件路径（从 `OPENCLAW_CONFIG_PATH` 或默认位置解析）。该路径应指向常规文件，而不是符号链接。
- `config file`：打印当前生效的配置文件路径（从 `OPENCLAW_CONFIG_PATH` 或默认位置解析）。该路径应指向普通文件，而不是符号链接。
编辑后请重启 Gateway 网关。
## 验证
## 校验
在不启动 Gateway 网关 的情况下，根据当前生效的 schema 验证当前配置。
在不启动 Gateway 网关的情况下，使用当前生效的 schema 校验当前配置。
```bash
openclaw config validate
openclaw config validate --json
```
在 `openclaw config validate` 通过后，你可以使用本地 TUI，让一个内嵌智能体在你从同一终端验证每项更改时，对照文档比较当前生效的配置：
当 `openclaw config validate` 通过后，你可以使用本地 TUI，让内嵌智能体在同一个终端中，一边校验每项更改，一边将当前生效配置与文档进行比较：
如果验证已经失败，请先使用 `openclaw configure` 或 `openclaw doctor --fix`。`openclaw chat` 不会绕过无效配置保护。
如果当前校验已经失败，请先运行 `openclaw configure` 或 `openclaw doctor --fix`。`openclaw chat` 不会绕过无效配置保护。
```bash
openclaw chat
```
然后在 TUI 内运行：
然后在 TUI 中执行：
```text
!openclaw config file
@ -405,12 +407,12 @@ openclaw chat
!openclaw doctor
```
典型的修复流程：
典型修复循环：
- 让智能体将你当前的配置与相关文档页面进行比较，并建议最小修复方案。
- 使用 `openclaw config set` 或 `openclaw configure` 应用有针对性的修改。
- 每次更改后重新运行 `openclaw config validate`。
- 如果验证通过，但运行时仍然不健康，请运行 `openclaw doctor` 或 `openclaw doctor --fix` 以获取迁移和修复帮助。
- 每次修改后重新运行 `openclaw config validate`。
- 如果校验通过但运行时状态仍不健康，请运行 `openclaw doctor` 或 `openclaw doctor --fix` 获取迁移和修复帮助。
## 相关内容

496
docs/zh-CN/gateway/config-agents.md
View File

@ -3,22 +3,20 @@ read_when:
- 调整智能体默认设置（模型、思考、工作区、心跳、媒体、Skills）
- 配置多智能体路由和绑定
- 调整会话、消息传递和 talk 模式行为
summary: 智能体默认值、多智能体路由、会话、消息和 talk 配置
summary: 智能体默认设置、多智能体路由、会话、消息以及 talk 配置
title: 配置 — 智能体
x-i18n:
generated_at: "2026-04-25T03:06:21Z"
generated_at: "2026-04-25T03:24:34Z"
model: gpt-5.4
provider: openai
source_hash: 055b8f114f277684c3c8bbfcf7165f7e7e4f645b5440dc60f0003bdb3639bc96
source_hash: 20cf1d6c2d491da51db3f383784a0ef1cc2622d25290987d0a3406147e92f462
source_path: gateway/config-agents.md
workflow: 15
---
`agents.*`、`multiAgent.*`、`session.*`、
`messages.*` 和 `talk.*` 下按智能体作用域划分的配置键。对于渠道、工具、Gateway 网关运行时以及其他
顶层键，请参阅 [配置参考](/zh-CN/gateway/configuration-reference)。
在 `agents.*`、`multiAgent.*`、`session.*`、`messages.*` 和 `talk.*` 下按智能体作用域划分的配置键。对于渠道、工具、Gateway 网关运行时以及其他顶层键，请参见 [配置参考](/zh-CN/gateway/configuration-reference)。
## 智能体默认值
## 智能体默认设置
### `agents.defaults.workspace`
@ -32,7 +30,7 @@ x-i18n:
### `agents.defaults.repoRoot`
可选的仓库根目录，会显示在系统提示词的 Runtime 行中。如果未设置，OpenClaw 会从工作区向上遍历并自动检测。
可选的仓库根目录，会显示在系统提示词的 Runtime 行中。如果未设置，OpenClaw 会从工作区开始向上遍历并自动检测。
```json5
{
@ -42,8 +40,7 @@ x-i18n:
### `agents.defaults.skills`
为未设置
`agents.list[].skills` 的智能体提供可选的默认 Skills 允许列表。
为未设置 `agents.list[].skills` 的智能体提供可选的默认 Skills 允许列表。
```json5
{
@ -52,21 +49,20 @@ x-i18n:
list: [
{ id: "writer" }, // 继承 github、weather
{ id: "docs", skills: ["docs-search"] }, // 替换默认值
{ id: "locked-down", skills: [] }, // 无 Skills
{ id: "locked-down", skills: [] }, // 不启用任何 Skills
],
},
}
```
- 省略 `agents.defaults.skills`，则默认 Skills 不受限制。
- 省略 `agents.defaults.skills`，则默认不限制 Skills。
- 省略 `agents.list[].skills`，则继承默认值。
- 设置 `agents.list[].skills: []` 表示没有 Skills。
- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它
不会与默认值合并。
- 设置 `agents.list[].skills: []` 表示不启用任何 Skills。
- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它不会与默认值合并。
### `agents.defaults.skipBootstrap`
禁用自动创建工作区引导文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。
禁用工作区引导文件的自动创建（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。
```json5
{
@ -78,7 +74,7 @@ x-i18n:
控制何时将工作区引导文件注入系统提示词。默认值：`"always"`。
- `"continuation-skip"`：安全的续接轮次（在一次已完成的助手响应之后）会跳过重新注入工作区引导内容，从而减小提示词大小。心跳运行和压缩后重试仍会重建上下文。
- `"continuation-skip"`：对于安全的续接轮次（在助手已完成响应之后），跳过重新注入工作区引导内容，以减少提示词大小。Heartbeat 运行和压缩后重试仍会重建上下文。
```json5
{
@ -88,7 +84,7 @@ x-i18n:
### `agents.defaults.bootstrapMaxChars`
单个工作区引导文件在截断前允许的最大字符数。默认值：`12000`。
单个工作区引导文件在被截断前允许的最大字符数。默认值：`12000`。
```json5
{
@ -108,12 +104,11 @@ x-i18n:
### `agents.defaults.bootstrapPromptTruncationWarning`
控制在引导上下文被截断时，是否向智能体可见地显示警告文本。
默认值：`"once"`。
控制在引导上下文被截断时，对智能体可见的警告文本。默认值：`"once"`。
- `"off"`：绝不将警告文本注入系统提示词。
- `"once"`：对每个唯一的截断特征只注入一次警告（推荐）。
- `"always"`：只要存在截断，每次运行都注入警告。
- `"once"`：对每个唯一的截断签名仅注入一次警告（推荐）。
- `"always"`：只要存在截断，就在每次运行时都注入警告。
```json5
{
@ -123,22 +118,20 @@ x-i18n:
### 上下文预算归属映射
OpenClaw 具有多个高容量的提示词/上下文预算，它们会
按子系统有意拆分，而不是全部通过一个通用
开关来控制。
OpenClaw 有多个高容量的提示词/上下文预算，这些预算被有意按子系统拆分，而不是全部通过一个通用旋钮统一控制。
- `agents.defaults.bootstrapMaxChars` /
`agents.defaults.bootstrapTotalMaxChars`：
常规工作区引导注入。
常规工作区引导内容注入。
- `agents.defaults.startupContext.*`：
一次性的 `/new` 和 `/reset` 启动前导内容，其中包括最近的每日
一次性的 `/new` 和 `/reset` 启动前导内容，包括最近的每日
`memory/*.md` 文件。
- `skills.limits.*`：
注入系统提示词中的精简 Skills 列表。
- `agents.defaults.contextLimits.*`：
有界的运行时摘录和由运行时拥有的注入内容块。
有界的运行时摘录和由运行时拥有的注入块。
- `memory.qmd.limits.*`：
已索引的内存搜索片段及注入大小控制。
已索引的 memory 搜索片段及注入大小控制。
仅当某个智能体需要不同预算时，才使用对应的按智能体覆盖项：
@ -147,8 +140,7 @@ OpenClaw 具有多个高容量的提示词/上下文预算，它们会
#### `agents.defaults.startupContext`
控制在直接执行 `/new` 和 `/reset`
时注入的首轮启动前导内容。
控制在裸 `/new` 和 `/reset` 运行时注入的首轮启动前导内容。
```json5
{
@ -169,7 +161,7 @@ OpenClaw 具有多个高容量的提示词/上下文预算，它们会
#### `agents.defaults.contextLimits`
有界运行时上下文表面的共享默认值。
用于有界运行时上下文表面的共享默认值。
```json5
{
@ -186,19 +178,14 @@ OpenClaw 具有多个高容量的提示词/上下文预算，它们会
}
```
- `memoryGetMaxChars`：`memory_get` 摘录在添加截断
元数据和续接提示之前的默认上限。
- `memoryGetDefaultLines`：当省略 `lines` 时，
`memory_get` 的默认行窗口。
- `toolResultMaxChars`：用于持久化结果和
溢出恢复的实时工具结果上限。
- `postCompactionMaxChars`：压缩后刷新注入期间使用的 AGENTS.md
摘录上限。
- `memoryGetMaxChars`：`memory_get` 摘录在添加截断元数据和续接提示之前的默认上限。
- `memoryGetDefaultLines`：当省略 `lines` 时，`memory_get` 的默认行窗口。
- `toolResultMaxChars`：用于持久化结果和溢出恢复的实时工具结果上限。
- `postCompactionMaxChars`：在压缩后刷新注入期间使用的 `AGENTS.md` 摘录上限。
#### `agents.list[].contextLimits`
用于共享 `contextLimits` 开关的按智能体覆盖项。未填写的字段会从
`agents.defaults.contextLimits` 继承。
共享 `contextLimits` 控件的按智能体覆盖项。省略的字段会继承自 `agents.defaults.contextLimits`。
```json5
{
@ -224,8 +211,7 @@ OpenClaw 具有多个高容量的提示词/上下文预算，它们会
#### `skills.limits.maxSkillsPromptChars`
注入系统提示词中的精简 Skills 列表的全局上限。此设置
不会影响按需读取 `SKILL.md` 文件。
注入系统提示词中的精简 Skills 列表的全局上限。这不会影响按需读取 `SKILL.md` 文件。
```json5
{
@ -239,7 +225,7 @@ OpenClaw 具有多个高容量的提示词/上下文预算，它们会
#### `agents.list[].skillsLimits.maxSkillsPromptChars`
用于 Skills 提示词预算的按智能体覆盖项。
Skills 提示词预算的按智能体覆盖项。
```json5
{
@ -258,11 +244,10 @@ OpenClaw 具有多个高容量的提示词/上下文预算，它们会
### `agents.defaults.imageMaxDimensionPx`
在调用提供商之前，转录内容/工具图像块中图像最长边的最大像素尺寸。
默认值：`1200`。
在调用提供商之前，转录内容/工具图像块中图片最长边的最大像素尺寸。默认值：`1200`。
较低的值通常会减少视觉 token 用量以及截图密集型运行的请求负载大小。
较高的值则会保留更多视觉细节。
较低的值通常会减少视觉 token 使用量和以截图为主的运行请求负载大小。
较高的值会保留更多视觉细节。
```json5
{
@ -272,7 +257,7 @@ OpenClaw 具有多个高容量的提示词/上下文预算，它们会
### `agents.defaults.userTimezone`
用于系统提示词上下文的时区（不影响消息时间戳）。如未设置，则回退到主机时区。
系统提示词上下文使用的时区（不影响消息时间戳）。会回退到主机时区。
```json5
{
@ -339,53 +324,53 @@ OpenClaw 具有多个高容量的提示词/上下文预算，它们会
}
```
- `model`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- 字符串形式只设置主模型。
- 对象形式设置主模型以及按顺序排列的故障转移模型。
- `imageModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- `model`：既可接受字符串（`"provider/model"`），也可接受对象（`{ primary, fallbacks }`）。
- 字符串形式仅设置主模型。
- 对象形式会设置主模型以及按顺序排列的故障转移模型。
- `imageModel`：既可接受字符串（`"provider/model"`），也可接受对象（`{ primary, fallbacks }`）。
- 作为 `image` 工具路径的视觉模型配置使用。
- 当选定/默认模型无法接受图像输入时，也会用作回退路由。
- `imageGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- 当选定/默认模型无法接受图像输入时，也用作回退路由。
- `imageGenerationModel`：既可接受字符串（`"provider/model"`），也可接受对象（`{ primary, fallbacks }`）。
- 用于共享的图像生成能力，以及任何未来会生成图像的工具/插件表面。
- 典型值：`google/gemini-3.1-flash-image-preview` 用于原生 Gemini 图像生成，`fal/fal-ai/flux/dev` 用于 fal，或 `openai/gpt-image-2` 用于 OpenAI Images。
- 如果你直接选择某个提供商/模型，也要配置对应的提供商认证（例如，`google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` 使用 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 使用 `FAL_KEY`）。
- 如果省略，`image_generate` 仍可推断出一个有认证支持的默认提供商。它会先尝试当前默认提供商，然后再按提供商 id 顺序尝试其余已注册的图像生成提供商。
- `musicGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- 用于共享的音乐生成能力以及内置的 `music_generate` 工具。
- 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。
- 如果省略，`music_generate` 仍可推断出一个有认证支持的默认提供商。它会先尝试当前默认提供商，然后再按提供商 id 顺序尝试其余已注册的音乐生成提供商。
- 如果你直接选择某个提供商/模型，也要配置对应的提供商认证/API 密钥。
- `videoGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- 用于共享的视频生成能力以及内置的 `video_generate` 工具。
- 典型值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。
- 如果省略，`video_generate` 仍可推断出一个有认证支持的默认提供商。它会先尝试当前默认提供商，然后再按提供商 id 顺序尝试其余已注册的视频生成提供商。
- 如果你直接选择某个提供商/模型，也要配置对应的提供商认证/API 密钥。
- 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 个输入图像、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。
- `pdfModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
- 常见值：`google/gemini-3.1-flash-image-preview` 用于原生 Gemini 图像生成，`fal/fal-ai/flux/dev` 用于 fal，或 `openai/gpt-image-2` 用于 OpenAI Images。
- 如果你直接选择某个提供商/模型，也要配置匹配的提供商凭证，例如：`google/*` 需要 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` 需要 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 需要 `FAL_KEY`。
- 如果省略，`image_generate` 仍可推断出带有认证的默认提供商。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的图像生成提供商。
- `musicGenerationModel`：既可接受字符串（`"provider/model"`），也可接受对象（`{ primary, fallbacks }`）。
- 用于共享的音乐生成能力和内置的 `music_generate` 工具。
- 常见值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。
- 如果省略，`music_generate` 仍可推断出带有认证的默认提供商。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的音乐生成提供商。
- 如果你直接选择某个提供商/模型，也要配置匹配的提供商认证/API key。
- `videoGenerationModel`：既可接受字符串（`"provider/model"`），也可接受对象（`{ primary, fallbacks }`）。
- 用于共享的视频生成能力和内置的 `video_generate` 工具。
- 常见值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。
- 如果省略，`video_generate` 仍可推断出带有认证的默认提供商。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的视频生成提供商。
- 如果你直接选择某个提供商/模型，也要配置匹配的提供商认证/API key。
- 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图片、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。
- `pdfModel`：既可接受字符串（`"provider/model"`），也可接受对象（`{ primary, fallbacks }`）。
- 用于 `pdf` 工具的模型路由。
- 如果省略，PDF 工具会先回退到 `imageModel`，再回退到解析后的会话/默认模型。
- 如果省略，PDF 工具会回退到 `imageModel`，再回退到解析后的会话/默认模型。
- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具使用的默认 PDF 大小限制。
- `pdfMaxPages`：`pdf` 工具中提取回退模式默认考虑的最大页数。
- `pdfMaxPages`：`pdf` 工具在提取回退模式下默认考虑的最大页数。
- `verboseDefault`：智能体的默认详细级别。取值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。
- `elevatedDefault`：智能体的默认增强输出级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。
- `model.primary`：格式为 `provider/model`（例如，API 密钥访问使用 `openai/gpt-5.4`，Codex OAuth 使用 `openai-codex/gpt-5.5`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试已配置提供商中与该模型 id 完全匹配的唯一项，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此建议优先使用显式的 `provider/model`）。如果该提供商不再公开配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露一个已移除提供商的陈旧默认值。
- `models`：用于 `/model` 的已配置模型目录和允许列表。每个条目都可以包含 `alias`（快捷别名）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`、`extra_body`/`extraBody`）。
- 安全编辑：使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 添加条目。除非你传入 `--replace`，否则 `config set` 会拒绝会移除现有允许列表条目的替换操作。
- 提供商作用域的配置/新手引导流程会把所选提供商模型合并到此映射中，并保留已配置的其他无关提供商。
- 对于直接使用的 OpenAI Responses 模型，会自动启用服务端压缩。使用 `params.responsesServerCompaction: false` 可停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆盖阈值。参见 [OpenAI 服务端压缩](/zh-CN/providers/openai#server-side-compaction-responses-api)。
- `params`：应用到所有模型的全局默认提供商参数。在 `agents.defaults.params` 设置（例如 `{ cacheRetention: "long" }`）。
- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础值）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后再由 `agents.list[].params`（匹配的智能体 id）按键覆盖。详见 [Prompt Caching](/zh-CN/reference/prompt-caching)。
- `params.extra_body`/`params.extraBody`：高级透传 JSON，会合并到 OpenAI 兼容代理的 `api: "openai-completions"` 请求体中。如果它与自动生成的请求键冲突，以额外请求体为准；非原生 completions 路由在此之后仍会去除 OpenAI 专有的 `store`。
- `embeddedHarness`：默认的底层嵌入式智能体运行时策略。省略时，运行时默认为 OpenClaw Pi。使用 `runtime: "pi"` 可强制使用内置的 PI harness，使用 `runtime: "auto"` 可让已注册插件 harness 接管其支持的模型，或使用已注册的 harness id，例如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动 PI 回退。显式的插件运行时（如 `codex`）默认采用失败即停止，除非你在同一覆盖作用域中设置 `fallback: "pi"`。请将模型引用保持为标准格式 `provider/model`；通过运行时配置选择 Codex、Claude CLI、Gemini CLI 及其他执行后端，而不要使用旧版运行时提供商前缀。关于它与提供商/模型选择的区别，请参阅 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及 fallback add/remove 命令）会保存为标准对象形式，并尽可能保留现有的回退列表。
- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话内部仍是串行）。默认值：4。
- `elevatedDefault`：智能体的默认高权限输出级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。
- `model.primary`：格式为 `provider/model`（例如：使用 API key 访问时为 `openai/gpt-5.4`，使用 Codex OAuth 时为 `openai-codex/gpt-5.5`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该精确模型 id 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此建议优先使用明确的 `provider/model`）。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露一个陈旧的、已移除提供商默认值。
- `models`：为 `/model` 配置的模型目录和允许列表。每个条目都可以包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`、`extra_body`/`extraBody`）。
- 安全编辑方式：使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 添加条目。除非传入 `--replace`，否则 `config set` 会拒绝会移除现有允许列表条目的替换操作。
- 按提供商范围的 configure/新手引导 流程会将所选提供商模型合并到此映射中，并保留已配置的其他无关提供商。
- 对于直接使用的 OpenAI Responses 模型，会自动启用服务器端压缩。可使用 `params.responsesServerCompaction: false` 停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆盖阈值。参见 [OpenAI 服务器端压缩](/zh-CN/providers/openai#server-side-compaction-responses-api)。
- `params`：应用于所有模型的全局默认提供商参数。在 `agents.defaults.params` 下设置（例如 `{ cacheRetention: "long" }`）。
- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配智能体 id）再按键覆盖。详情参见 [Prompt Caching](/zh-CN/reference/prompt-caching)。
- `params.extra_body`/`params.extraBody`：高级透传 JSON，会合并到面向 OpenAI 兼容代理的 `api: "openai-completions"` 请求体中。如果它与生成的请求键冲突，则以额外请求体为准；非原生 completions 路由之后仍会剥离仅属于 OpenAI 的 `store`。
- `embeddedHarness`：默认的低层嵌入式智能体运行时策略。省略 `runtime` 时默认使用 OpenClaw Pi。使用 `runtime: "pi"` 可强制使用内置 PI harness，使用 `runtime: "auto"` 可让已注册的插件 harness 接管受支持模型，或使用已注册的 harness id，例如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动回退到 PI。像 `codex` 这样的显式插件运行时默认会在关闭状态下失败，除非你在同一覆盖范围内设置 `fallback: "pi"`。请将模型引用保持为规范形式 `provider/model`；应通过运行时配置而不是旧式运行时提供商前缀来选择 Codex、Claude CLI、Gemini CLI 及其他执行后端。关于这与提供商/模型选择的区别，请参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及回退项 add/remove 命令）会保存为规范对象形式，并在可能时保留现有回退列表。
- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话仍然是串行的）。默认值：4。
### `agents.defaults.embeddedHarness`
`embeddedHarness` 控制由哪个底层执行器运行嵌入式智能体轮次。
`embeddedHarness` 控制哪个低层执行器负责运行嵌入式智能体轮次。
大多数部署应保持默认的 OpenClaw Pi 运行时。
当某个受信任插件提供原生 harness 时，可使用此项，例如内置的
Codex 应用服务器 harness。关于概念模型，请参阅
当受信任的插件提供原生 harness 时可使用它，例如内置的
Codex 应用服务器 harness。关于其心智模型，请参见
[Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
```json5
@ -403,15 +388,15 @@ Codex 应用服务器 harness。关于概念模型，请参阅
```
- `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness id。内置的 Codex 插件会注册 `codex`。
- `fallback`：`"pi"` 或 `"none"`。在 `runtime: "auto"` 中，若省略 `fallback`，默认值为 `"pi"`，这样旧配置在没有插件 harness 接管运行时仍可继续使用 PI。在显式插件运行时模式下，例如 `runtime: "codex"`，若省略 `fallback`，默认值为 `"none"`，这样缺失 harness 时会直接失败，而不是静默使用 PI。运行时覆盖不会从更宽泛的作用域继承 fallback；如果你确实希望这种兼容性回退，请在显式运行时旁边一并设置 `fallback: "pi"`。所选插件 harness 的失败始终会直接暴露出来。
- 环境变量覆盖：`OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` 会覆盖 `runtime`；`OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` 会覆盖该进程的 fallback。
- 对于仅使用 Codex 的部署，请设置 `model: "openai/gpt-5.5"` 和 `embeddedHarness.runtime: "codex"`。你也可以为提高可读性显式设置 `embeddedHarness.fallback: "none"`；这是显式插件运行时的默认值。
- 在首次嵌入式运行之后，harness 选择会按每个会话 id 固定。配置/环境变量变更会影响新的或已重置的会话，不会影响现有转录。对于有转录历史但未记录固定值的旧会话，会视为已固定到 PI。`/status` 会在 `Fast` 旁显示非 PI 的 harness id，例如 `codex`。
- 此项只控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的提供商/模型设置。
- `fallback`：`"pi"` 或 `"none"`。在 `runtime: "auto"` 中，省略的回退值默认是 `"pi"`，这样旧配置在没有插件 harness 接管运行时仍可继续使用 PI。在显式插件运行时模式下，例如 `runtime: "codex"`，省略的回退值默认是 `"none"`，这样在缺少 harness 时会直接失败，而不会静默使用 PI。运行时覆盖项不会从更宽范围继承回退值；如果你有意需要这种兼容性回退，请在显式运行时旁边一并设置 `fallback: "pi"`。所选插件 harness 的失败总是会直接显示出来。
- 环境变量覆盖：`OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` 会覆盖 `runtime`；`OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` 会覆盖该进程的回退值。
- 对于仅使用 Codex 的部署，设置 `model: "openai/gpt-5.5"` 和 `embeddedHarness.runtime: "codex"`。你也可以显式设置 `embeddedHarness.fallback: "none"` 以增强可读性；这本就是显式插件运行时的默认值。
- 在第一次嵌入式运行之后，harness 选择会按 `session` id 固定。配置/环境变量变更只影响新的或已重置的会话，不影响现有转录。对于有转录历史但没有记录固定值的旧会话，会按固定到 PI 处理。`/status` 会在 `Fast` 旁显示非 PI 的 harness id，例如 `codex`。
- 这只控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍然使用各自的提供商/模型设置。
**内置别名简写**（仅在模型存在于 `agents.defaults.models` 中时适用）：
**内置别名简写**（仅在模型位于 `agents.defaults.models` 中时生效）：
| 别名 | 模型 |
| Alias | 模型 |
| ------------------- | -------------------------------------------------- |
| `opus` | `anthropic/claude-opus-4-6` |
| `sonnet` | `anthropic/claude-sonnet-4-6` |
@ -424,13 +409,13 @@ Codex 应用服务器 harness。关于概念模型，请参阅
你配置的别名始终优先于默认值。
Z.AI 的 GLM-4.x 模型会自动启用思考模式，除非你设置 `--thinking off`，或自行定义 `agents.defaults.models["zai/<model>"].params.thinking`。
Z.AI 模型默认启用 `tool_stream` 以支持工具调用流式传输。将 `agents.defaults.models["zai/<model>"].params.tool_stream` 设为 `false` 可禁用它。
Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `adaptive` 思考。
Z.AI GLM-4.x 模型会自动启用思考模式，除非你设置 `--thinking off`，或自行定义 `agents.defaults.models["zai/<model>"].params.thinking`。
Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/<model>"].params.tool_stream` 设置为 `false` 可禁用它。
当未设置显式思考级别时，Anthropic Claude 4.6 模型默认使用 `adaptive` 思考。
### `agents.defaults.cliBackends`
用于纯文本回退运行（无工具调用）的可选 CLI 后端。当 API 提供商失败时，可作为备用方案。
用于纯文本回退运行（无工具调用）的可选 CLI 后端。当 API 提供商失败时，可将其作为备用方案。
```json5
{
@ -459,12 +444,12 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
```
- CLI 后端以文本为主；工具始终禁用。
- 设置了 `sessionArg` 时支持会话。
- 当 `imageArg` 可接受文件路径时，支持图像透传。
- 当设置了 `sessionArg` 时支持会话。
- 当 `imageArg` 接受文件路径时，支持图像透传。
### `agents.defaults.systemPromptOverride`
用固定字符串替换整个由 OpenClaw 组装的系统提示词。可在默认级别设置（`agents.defaults.systemPromptOverride`），也可按智能体设置（`agents.list[].systemPromptOverride`）。按智能体的值优先；空字符串或仅包含空白字符的值会被忽略。适用于受控的提示词实验。
用固定字符串替换整个由 OpenClaw 组装的系统提示词。可在默认级别（`agents.defaults.systemPromptOverride`）设置，也可按智能体设置（`agents.list[].systemPromptOverride`）。按智能体设置的值优先；空值或仅包含空白字符的值会被忽略。适合用于受控的提示词实验。
```json5
{
@ -478,7 +463,7 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
### `agents.defaults.promptOverlays`
按模型家族应用的、与提供商无关的提示词叠加层。GPT-5 系列模型 id 会在各提供商之间接收共享的行为契约；`personality` 仅控制友好的交互风格层。
按模型家族应用、与提供商无关的提示词叠加层。GPT-5 系列模型 id 会在不同提供商之间接收共享的行为契约；`personality` 仅控制友好交互风格这一层。
```json5
{
@ -495,24 +480,24 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
```
- `"friendly"`（默认）和 `"on"` 会启用友好交互风格层。
- `"off"` 只禁用友好层；带标签的 GPT-5 行为契约仍保持启用。
- `"off"` 只会禁用友好层；带标签的 GPT-5 行为契约仍会保持启用。
- 当这个共享设置未设置时，仍会读取旧版的 `plugins.entries.openai.config.personality`。
### `agents.defaults.heartbeat`
周期性心跳运行。
周期性 Heartbeat 运行。
```json5
{
agents: {
defaults: {
heartbeat: {
every: "30m", // 0m 表示禁用
every: "30m", // 0m 禁用
model: "openai/gpt-5.4-mini",
includeReasoning: false,
includeSystemPromptSection: true, // 默认：true；false 表示从系统提示词中省略 Heartbeat 部分
lightContext: false, // 默认：false；true 表示仅保留工作区引导文件中的 HEARTBEAT.md
isolatedSession: false, // 默认：false；true 表示每次心跳都在全新会话中运行（无对话历史）
includeSystemPromptSection: true, // 默认：true；false 会从系统提示词中省略 Heartbeat 部分
lightContext: false, // 默认：false；true 仅保留工作区引导文件中的 HEARTBEAT.md
isolatedSession: false, // 默认：false；true 会让每次 heartbeat 都在全新会话中运行（无对话历史）
session: "main",
to: "+15555550123",
directPolicy: "allow", // allow（默认）| block
@ -527,15 +512,15 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
}
```
- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API 密钥认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。
- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。
- `includeSystemPromptSection`：设为 false 时，会从系统提示词中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入引导上下文。默认值：`true`。
- `suppressToolErrorWarnings`：设为 true 时，会在心跳运行期间抑制工具错误警告负载。
- `timeoutSeconds`：在心跳智能体轮次被中止前允许的最长秒数。若未设置，则使用 `agents.defaults.timeoutSeconds`。
- `directPolicy`：直发/私信投递策略。`allow`（默认）允许向直接目标投递。`block` 会阻止向直接目标投递，并发出 `reason=dm-blocked`。
- `lightContext`：设为 true 时，心跳运行会使用轻量级引导上下文，并且仅保留工作区引导文件中的 `HEARTBEAT.md`。
- `isolatedSession`：设为 true 时，每次心跳都会在一个全新会话中运行，不带任何先前对话历史。隔离模式与 cron 的 `sessionTarget: "isolated"` 相同。可将每次心跳的 token 成本从约 100K 降至约 2-5K token。
- 按智能体设置：使用 `agents.list[].heartbeat`。如果任一智能体定义了 `heartbeat`，**则只有这些智能体**会运行心跳。
- 心跳会运行完整的智能体轮次——间隔越短，消耗的 token 越多。
- `suppressToolErrorWarnings`：设为 true 时，会在 Heartbeat 运行期间抑制工具错误警告负载。
- `timeoutSeconds`：在 Heartbeat 智能体轮次被中止前，允许的最长秒数。若未设置，则使用 `agents.defaults.timeoutSeconds`。
- `directPolicy`：直接/私信 传递策略。`allow`（默认）允许直接目标传递。`block` 会抑制直接目标传递，并发出 `reason=dm-blocked`。
- `lightContext`：设为 true 时，Heartbeat 运行会使用轻量级引导上下文，并且仅保留工作区引导文件中的 `HEARTBEAT.md`。
- `isolatedSession`：设为 true 时，每次 Heartbeat 运行都会在一个没有先前对话历史的全新会话中执行。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次 Heartbeat 的 token 成本从约 100K 降到约 2-5K token。
- 按智能体设置：使用 `agents.list[].heartbeat`。当任意智能体定义了 `heartbeat` 时，**只有这些智能体** 会运行 Heartbeat。
- Heartbeat 会运行完整的智能体轮次 —— 间隔越短，消耗的 token 越多。
### `agents.defaults.compaction`
@ -545,16 +530,16 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
defaults: {
compaction: {
mode: "safeguard", // default | safeguard
provider: "my-provider", // 已注册的 compaction 提供商插件 id（可选）
provider: "my-provider", // 已注册 compaction 提供商插件的 id（可选）
timeoutSeconds: 900,
reserveTokensFloor: 24000,
keepRecentTokens: 50000,
identifierPolicy: "strict", // strict | off | custom
identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // 当 identifierPolicy=custom 时使用
qualityGuard: { enabled: true, maxRetries: 1 },
postCompactionSections: ["Session Startup", "Red Lines"], // [] 表示禁用重新注入
postCompactionSections: ["Session Startup", "Red Lines"], // [] 禁用重新注入
model: "openrouter/anthropic/claude-sonnet-4-6", // 可选，仅用于 compaction 的模型覆盖
notifyUser: true, // 在 compaction 开始和完成时发送简短通知（默认：false）
notifyUser: true, // 在 compaction 开始和完成时向用户发送简短通知（默认：false）
memoryFlush: {
enabled: true,
softThresholdTokens: 6000,
@ -567,21 +552,21 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
}
```
- `mode`：`default` 或 `safeguard`（针对长历史的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。
- `provider`：已注册的 compaction 提供商插件 id。设置后，会调用该提供商的 `summarize()`，而不是使用内置的 LLM 摘要。失败时会回退到内置方式。设置提供商会强制启用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。
- `timeoutSeconds`：OpenClaw 中止单次 compaction 操作前允许的最长秒数。默认值：`900`。
- `keepRecentTokens`：Pi 截断点预算，用于按原样保留最近的转录尾部。手动 `/compact` 会在显式设置时遵循此值；否则手动 compaction 是一个硬检查点。
- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预置内置的不透明标识符保留指引。
- `mode`：`default` 或 `safeguard`（用于长历史记录的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。
- `provider`：已注册 compaction 提供商插件的 id。设置后，将调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。失败时会回退到内置方案。设置提供商会强制使用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。
- `timeoutSeconds`：OpenClaw 中止单次 compaction 操作前允许的最大秒数。默认值：`900`。
- `keepRecentTokens`：Pi 截断点预算，用于将最近的转录尾部原样保留。手动 `/compact` 在显式设置时会遵循该值；否则手动 compaction 是一个硬检查点。
- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预置内置的“不透明标识符保留”指导。
- `identifierInstructions`：可选的自定义标识符保留文本，在 `identifierPolicy=custom` 时使用。
- `qualityGuard`：对 safeguard 摘要执行输出格式异常时重试的检查。在 safeguard 模式下默认启用；设为 `enabled: false` 可跳过审计。
- `postCompactionSections`：可选的 AGENTS.md H2/H3 章节名称，在 compaction 后重新注入。默认值为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。若未设置，或显式设为该默认组合，也会接受较旧的 `Every Session`/`Safety` 标题作为旧版回退。
- `model`：可选的 `provider/model-id` 覆盖，仅用于 compaction 摘要。当主会话需要保留一个模型，而 compaction 摘要应使用另一个模型时，可使用此项；未设置时，compaction 会使用会话的主模型。
- `notifyUser`：设为 `true` 时，会在 compaction 开始和完成时向用户发送简短通知（例如 “Compacting context...” 和 “Compaction complete”）。默认关闭，以保持 compaction 静默进行。
- `memoryFlush`：在自动 compaction 之前执行静默的智能体轮次，用于存储持久记忆。当工作区为只读时会跳过。
- `qualityGuard`：用于 safeguard 摘要的“输出格式异常时重试”检查。在 safeguard 模式下默认启用；设置 `enabled: false` 可跳过审计。
- `postCompactionSections`：可选，在 compaction 后重新注入的 `AGENTS.md` H2/H3 章节名。默认值为 `["Session Startup", "Red Lines"]`；设置为 `[]` 可禁用重新注入。未设置或显式设置为这对默认值时，也会接受旧版 `Every Session`/`Safety` 标题作为兼容回退。
- `model`：可选的 `provider/model-id` 覆盖值，仅用于 compaction 摘要。适用于主会话保持一个模型、但 compaction 摘要使用另一个模型的场景；未设置时，compaction 会使用会话的主模型。
- `notifyUser`：设为 `true` 时，会在 compaction 开始和完成时向用户发送简短通知（例如 “Compacting context...” 和 “Compaction complete”）。默认禁用，以保持 compaction 静默。
- `memoryFlush`：在自动 compaction 之前进行静默的智能体轮次，用于存储持久记忆。当工作区为只读时会跳过。
### `agents.defaults.contextPruning`
在将内容发送给 LLM 之前，从内存上下文中清理**旧工具结果**。**不会**修改磁盘上的会话历史。
在发送给 LLM 之前，从内存中的上下文里修剪**旧的工具结果**。**不会** 修改磁盘上的会话历史。
```json5
{
@ -603,25 +588,25 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
}
```
<Accordion title="cache-ttl 模式行为">
<Accordion title="`cache-ttl` 模式行为">
- `mode: "cache-ttl"` 会启用清理流程。
- `ttl` 控制距离上次缓存触达后，多久才允许再次运行清理。
- 清理会先对过大的工具结果执行软裁剪，如仍有需要，再对更旧的工具结果执行硬清除。
- `mode: "cache-ttl"` 会启用修剪流程。
- `ttl` 控制再次运行修剪前所需的间隔（从上次缓存触碰后开始计算）。
- 修剪会先对过大的工具结果进行软裁剪，如仍有需要，再对更早的工具结果进行硬清除。
**软裁剪**会保留开头和结尾，并在中间插入 `...`。
**软裁剪** 会保留开头和结尾，并在中间插入 `...`。
**硬清除**会用占位符替换整个工具结果。
**硬清除** 会用占位符替换整个工具结果。
说明：
- 图像块永远不会被裁剪/清除。
- 各比例基于字符数（近似），不是精确的 token 计数。
- 如果助手消息少于 `keepLastAssistants` 条，则会跳过清理。
- 比例基于字符数（近似），不是精确 token 数。
- 如果助手消息少于 `keepLastAssistants` 条，则会跳过修剪。
</Accordion>
行为详情请参阅 [会话清理](/zh-CN/concepts/session-pruning)。
行为细节请参见 [Session Pruning](/zh-CN/concepts/session-pruning)。
### 分块流式传输
@ -640,10 +625,10 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
```
- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才会启用分块回复。
- 渠道覆盖：`channels.<channel>.blockStreamingCoalesce`（以及按账号的变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。
- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。按智能体覆盖：`agents.list[].humanDelay`。
- 渠道覆盖：`channels.<channel>.blockStreamingCoalesce`（以及按账号变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。
- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500 ms。按智能体覆盖：`agents.list[].humanDelay`。
行为和分块细节请参阅 [流式传输](/zh-CN/concepts/streaming)。
行为和分块细节请参见 [Streaming](/zh-CN/concepts/streaming)。
### 输入中指示器
@ -658,16 +643,16 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
}
```
- 默认值：直接聊天/提及时为 `instant`，未被提及的群聊为 `message`。
- 默认值：对于直接聊天/提及为 `instant`，对于未被提及的群聊为 `message`。
- 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。
参见 [输入中指示器](/zh-CN/concepts/typing-indicators)。
参见 [Typing Indicators](/zh-CN/concepts/typing-indicators)。
<a id="agentsdefaultssandbox"></a>
### `agents.defaults.sandbox`
嵌入式智能体的可选沙箱隔离。完整指南请参阅 [沙箱隔离](/zh-CN/gateway/sandboxing)。
嵌入式智能体的可选沙箱隔离。完整指南请参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。
```json5
{
@ -767,7 +752,7 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
**后端：**
- `docker`：本地 Docker 运行时（默认）
- `ssh`：通用 SSH 远程运行时
- `ssh`：通用 SSH 支持的远程运行时
- `openshell`：OpenShell 运行时
选择 `backend: "openshell"` 时，运行时特定设置会移动到
@ -777,29 +762,29 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
- `target`：`user@host[:port]` 形式的 SSH 目标
- `command`：SSH 客户端命令（默认：`ssh`）
- `workspaceRoot`：用于按作用域划分工作区的远程绝对根路径
- `workspaceRoot`：用于按作用域工作区的远程绝对根路径
- `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件
- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRefs，OpenClaw 会在运行时将其实体化为临时文件
- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关
- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略控件
**SSH 认证优先级：**
- `identityData` 优先于 `identityFile`
- `certificateData` 优先于 `certificateFile`
- `knownHostsData` 优先于 `knownHostsFile`
- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前，从当前活动的 secrets 运行时快照中解析
- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前，从当前激活的 secrets 运行时快照中解析
**SSH 后端行为：**
- 在创建或重建后，会先对远程工作区执行一次初始化
- 之后将远程 SSH 工作区保持为标准工作区
- 在创建或重新创建后，会先为远程工作区执行一次初始化
- 此后保持远程 SSH 工作区为规范副本
- 通过 SSH 路由 `exec`、文件工具和媒体路径
- 不会自动将远程变更同步回主机
- 不会自动将远程更改同步回主机
- 不支持沙箱浏览器容器
**工作区访问：**
- `none`：按作用域划分的沙箱工作区，位于 `~/.openclaw/sandboxes`
- `none`：位于 `~/.openclaw/sandboxes` 下、按作用域划分的沙箱工作区
- `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent`
- `rw`：智能体工作区以读写方式挂载到 `/workspace`
@ -824,7 +809,7 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
remoteAgentWorkspaceDir: "/agent",
gateway: "lab", // 可选
gatewayEndpoint: "https://lab.example", // 可选
policy: "strict", // 可选的 OpenShell 策略 id
policy: "strict", // 可选的 OpenShell policy id
providers: ["openai"], // 可选
autoProviders: true,
timeoutSeconds: 120,
@ -837,30 +822,30 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
**OpenShell 模式：**
- `mirror`：在执行前先将本地内容初始化到远程，执行后再同步回来；本地工作区保持为标准工作区
- `remote`：在创建沙箱时仅向远程初始化一次，之后将远程工作区保持为标准工作区
- `mirror`：在执行前将本地内容同步到远程，执行后再同步回本地；本地工作区保持为规范副本
- `remote`：在创建沙箱时仅向远程初始化一次，此后保持远程工作区为规范副本
在 `remote` 模式下，于 OpenClaw 之外在主机本地所做的编辑，在初始化步骤之后不会自动同步到沙箱中。
在 `remote` 模式下，初始化步骤之后，在 OpenClaw 外部对主机本地所做的编辑不会自动同步到沙箱中。
传输方式是通过 SSH 进入 OpenShell 沙箱，但插件负责沙箱生命周期以及可选的镜像同步。
**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。
**`setupCommand`** 会在容器创建后执行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统以及 root 用户。
**容器默认使用 `network: "none"`**——如果智能体需要出站访问，请设置为 `"bridge"`（或自定义桥接网络）。
`"host"` 会被阻止。默认情况下，`"container:<id>"` 也会被阻止，除非你显式设置
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急放行）。
**容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。
默认会阻止 `"host"`。默认也会阻止 `"container:<id>"`，除非你显式设置
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（破窗处理）。
**入站附件** 会被暂存到活动工作区中的 `media/inbound/*`。
**入站附件** 会被暂存到当前活动工作区中的 `media/inbound/*`。
**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的绑定会合并。
**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的绑定会被合并。
**沙箱隔离浏览器**（`sandbox.browser.enabled`）：在容器中运行 Chromium + CDP。noVNC URL 会被注入系统提示词。不需要在 `openclaw.json` 中启用 `browser.enabled`。
noVNC 观察者访问默认使用 VNC 认证，并且 OpenClaw 会发出一个短时有效的 token URL（而不是在共享 URL 中暴露密码）。
**沙箱隔离浏览器**（`sandbox.browser.enabled`）：在容器中运行 Chromium + CDP。noVNC URL 会注入系统提示词中。无需在 `openclaw.json` 里启用 `browser.enabled`。
noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短期有效的 token URL（而不是在共享 URL 中暴露密码）。
- `allowHostControl: false`（默认）会阻止沙箱隔离会话以主机浏览器为目标。
- `network` 默认为 `openclaw-sandbox-browser`（专用桥接网络）。仅当你明确希望使用全局桥接连接时，才设置为 `bridge`。
- `cdpSourceRange` 可选，用于在容器边界将 CDP 入站限制到某个 CIDR 范围内（例如 `172.21.0.1/32`）。
- `allowHostControl: false`（默认）会阻止沙箱隔离会话将主机浏览器作为目标。
- `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。只有在你明确希望使用全局 bridge 连通性时，才设置为 `bridge`。
- `cdpSourceRange` 可选，用于在容器边界将 CDP 入站限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。
- `sandbox.browser.binds` 仅将额外的主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。
- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机进行了调优：
- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并已针对容器主机进行调优：
- `--remote-debugging-address=127.0.0.1`
- `--remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>`
- `--user-data-dir=${HOME}/.chrome`
@ -877,16 +862,17 @@ noVNC 观察者访问默认使用 VNC 认证，并且 OpenClaw 会发出一个
- `--renderer-process-limit=2`
- `--no-zygote`
- `--metrics-recording-only`
- `--disable-extensions`（默认启用）
- 默认启用 `--disable-extensions`
- `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu`
默认启用；如果 WebGL/3D 使用场景需要它们，可通过
`OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用这些默认标志。
- 如果你的工作流依赖扩展，`OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 可重新启用扩展。
默认启用；如果 WebGL/3D 使用场景需要，可通过
`OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 将其禁用。
- 如果你的工作流依赖扩展，可通过
`OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 重新启用扩展。
- `--renderer-process-limit=2` 可通过
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>` 修改；设为 `0` 可使用 Chromium 的
默认进程限制。
- 另外，当启用 `noSandbox` 时，还会加上 `--no-sandbox` 和 `--disable-setuid-sandbox`。
- 这些默认值是容器镜像的基线；如需更改容器默认值，请使用带有自定义
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>` 修改；设置为 `0` 会使用 Chromium 的
默认进程数限制。
- 当启用 `noSandbox` 时，另外还会加上 `--no-sandbox` 和 `--disable-setuid-sandbox`。
- 这些默认值是容器镜像的基线；如需修改容器默认值，请使用带有自定义
入口点的自定义浏览器镜像。
</Accordion>
@ -897,7 +883,7 @@ noVNC 观察者访问默认使用 VNC 认证，并且 OpenClaw 会发出一个
```bash
scripts/sandbox-setup.sh # 主沙箱镜像
scripts/sandbox-browser-setup.sh # 可选的浏览器镜像
scripts/sandbox-browser-setup.sh # 可选浏览器镜像
```
### `agents.list`（按智能体覆盖）
@ -913,9 +899,9 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像
workspace: "~/.openclaw/workspace",
agentDir: "~/.openclaw/agents/main/agent",
model: "anthropic/claude-opus-4-6", // 或 { primary, fallbacks }
thinkingDefault: "high", // 按智能体覆盖思考级别
reasoningDefault: "on", // 按智能体覆盖推理可见性
fastModeDefault: false, // 按智能体覆盖快速模式
thinkingDefault: "high", // 按智能体覆盖的默认思考级别
reasoningDefault: "on", // 按智能体覆盖的默认推理可见性
fastModeDefault: false, // 按智能体覆盖的默认快速模式
embeddedHarness: { runtime: "auto", fallback: "pi" },
params: { cacheRetention: "none" }, // 按键覆盖匹配的 defaults.models params
skills: ["docs-search"], // 设置后会替换 agents.defaults.skills
@ -949,27 +935,27 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像
}
```
- `id`：稳定的智能体 id（必填）。
- `default`：设置多个时，以第一个为准（会记录警告）。如果都未设置，则列表中的第一个条目为默认值。
- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 同时覆盖两者（`[]` 会禁用全局回退）。仅覆盖 `primary` 的 cron 作业仍会继承默认的回退列表，除非你设置 `fallbacks: []`。
- `params`：按智能体的流参数，会合并到 `agents.defaults.models` 中所选模型条目之上。可用于按智能体覆盖 `cacheRetention`、`temperature` 或 `maxTokens` 等参数，而无需复制整个模型目录。
- `skills`：可选的按智能体 Skills 允许列表。如果省略，在已设置时该智能体会继承 `agents.defaults.skills`；显式列表会替换默认值而不是合并，`[]` 表示没有 Skills。
- `thinkingDefault`：可选的按智能体默认思考级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当未设置按消息或按会话覆盖时，它会覆盖该智能体的 `agents.defaults.thinkingDefault`。所选提供商/模型配置决定了哪些值有效；对于 Google Gemini，`adaptive` 会保留由提供商控制的动态思考（Gemini 3/3.1 上省略 `thinkingLevel`，Gemini 2.5 上使用 `thinkingBudget: -1`）。
- `reasoningDefault`：可选的按智能体默认推理可见性（`on | off | stream`）。当未设置按消息或按会话的推理覆盖时应用。
- `fastModeDefault`：可选的按智能体默认快速模式（`true | false`）。当未设置按消息或按会话的快速模式覆盖时应用。
- `embeddedHarness`：可选的按智能体底层 harness 策略覆盖。使用 `{ runtime: "codex" }` 可让某个智能体仅使用 Codex，而其他智能体在 `auto` 模式下保留默认的 PI 回退。
- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，可使用 `type: "acp"` 以及 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。
- `identity.avatar`：工作区相对路径、`http(s)` URL 或 `data:` URI。
- `identity` 会派生默认值：`ackReaction` 取自 `emoji`，`mentionPatterns` 取自 `name`/`emoji`。
- `subagents.allowAgents`：用于 `sessions_spawn` 的智能体 id 允许列表（`["*"]` = 任意；默认：仅同一智能体）。
- 沙箱继承保护：如果请求方会话已启用沙箱隔离，`sessions_spawn` 会拒绝那些会在无沙箱状态下运行的目标。
- `subagents.requireAgentId`：设为 true 时，阻止未提供 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置；默认：false）。
- `id`：稳定的智能体 id（必需）。
- `default`：当设置了多个默认值时，以第一个为准（会记录警告）。如果都未设置，则列表中的第一个条目是默认值。
- `model`：字符串形式只覆盖 `primary`；对象形式 `{ primary, fallbacks }` 会同时覆盖两者（`[]` 会禁用全局回退）。仅覆盖 `primary` 的 cron 作业仍会继承默认回退项，除非你设置 `fallbacks: []`。
- `params`：按智能体合并到 `agents.defaults.models` 中所选模型条目之上的流参数。可用于像 `cacheRetention`、`temperature` 或 `maxTokens` 这样的智能体专属覆盖，而无需复制整个模型目录。
- `skills`：可选的按智能体 Skills 允许列表。如果省略，当设置了 `agents.defaults.skills` 时，该智能体会继承它；显式列表会替换默认值而不是合并，`[]` 表示没有 Skills。
- `thinkingDefault`：可选的按智能体默认思考级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当没有按消息或会话覆盖时，会覆盖该智能体的 `agents.defaults.thinkingDefault`。所选提供商/模型配置文件决定哪些值有效；对于 Google Gemini，`adaptive` 会保持由提供商控制的动态思考（Gemini 3/3.1 上省略 `thinkingLevel`，Gemini 2.5 上使用 `thinkingBudget: -1`）。
- `reasoningDefault`：可选的按智能体默认推理可见性（`on | off | stream`）。当没有按消息或会话推理覆盖时生效。
- `fastModeDefault`：可选的按智能体默认快速模式（`true | false`）。当没有按消息或会话快速模式覆盖时生效。
- `embeddedHarness`：可选的按智能体低层 harness 策略覆盖。使用 `{ runtime: "codex" }` 可让某个智能体仅使用 Codex，而其他智能体在 `auto` 模式下继续保留默认的 PI 回退。
- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 并设置 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。
- `identity.avatar`：相对于工作区的路径、`http(s)` URL 或 `data:` URI。
- `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name`/`emoji`。
- `subagents.allowAgents`：`sessions_spawn` 可用的智能体 id 允许列表（`["*"]` = 任意；默认：仅同一智能体）。
- 沙箱继承保护：如果请求方会话处于沙箱中，`sessions_spawn` 会拒绝那些会在无沙箱环境中运行的目标。
- `subagents.requireAgentId`：为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置；默认：false）。
---
## 多智能体路由
在一个 Gateway 网关内运行多个相互隔离的智能体。参见 [多智能体](/zh-CN/concepts/multi-agent)。
在一个 Gateway 网关内运行多个彼此隔离的智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。
```json5
{
@ -988,8 +974,8 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像
### 绑定匹配字段
- `type`（可选）：普通路由使用 `route`（缺失时默认就是 route），持久化 ACP 对话绑定使用 `acp`。
- `match.channel`（必填）
- `type`（可选）：`route` 用于普通路由（未填写时默认为 route），`acp` 用于持久化 ACP 会话绑定。
- `match.channel`（必需）
- `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号）
- `match.peer`（可选；`{ kind: direct|group|channel, id }`）
- `match.guildId` / `match.teamId`（可选；渠道特定）
@ -1001,14 +987,14 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像
2. `match.guildId`
3. `match.teamId`
4. `match.accountId`（精确匹配，无 peer/guild/team）
5. `match.accountId: "*"`（渠道范围）
5. `match.accountId: "*"`（整个渠道范围）
6. 默认智能体
在每一层中，第一个匹配的 `bindings` 条目胜出。
在每一层级中，第一个匹配的 `bindings` 条目胜出。
对于 `type: "acp"` 条目，OpenClaw 会按精确的会话身份（`match.channel` + account + `match.peer.id`）解析，不使用上述 route 绑定的分层顺序。
对于 `type: "acp"` 条目，OpenClaw 会按精确会话身份（`match.channel` + account + `match.peer.id`）解析，不使用上述 route 绑定层级顺序。
### 按智能体访问配置
### 按智能体划分的访问配置
<Accordion title="完全访问（无沙箱）">
@ -1103,7 +1089,7 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像
</Accordion>
有关优先级细节，请参阅 [多智能体沙箱隔离与工具](/zh-CN/tools/multi-agent-sandbox-tools)。
优先级细节请参见 [多智能体沙箱隔离与工具](/zh-CN/tools/multi-agent-sandbox-tools)。
---
@ -1141,10 +1127,10 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像
},
threadBindings: {
enabled: true,
idleHours: 24, // 默认按小时计算的闲置自动取消聚焦时间（`0` 表示禁用）
maxAgeHours: 0, // 默认按小时计算的硬性最大时长（`0` 表示禁用）
idleHours: 24, // 默认按小时计的无活动自动取消聚焦时间（`0` 表示禁用）
maxAgeHours: 0, // 默认按小时计的硬最大存活时间（`0` 表示禁用）
},
mainKey: "main", // 旧版字段（运行时始终使用 "main"）
mainKey: "main", // 旧字段（运行时始终使用 "main"）
agentToAgent: { maxPingPongTurns: 5 },
sendPolicy: {
rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
@ -1157,34 +1143,34 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像
<Accordion title="会话字段详情">
- **`scope`**：群聊上下文的基础会话分组策略。
- `per-sender`（默认）：在同一渠道上下文中，每个发送者都有独立的会话。
- `global`：同一渠道上下文中的所有参与者共享一个会话（仅在确实需要共享上下文时使用）。
- **`dmScope`**：私信的分组方式。
- `main`：所有私信共享主会话。
- `per-peer`：按发送者 id 跨渠道隔离。
- `per-sender`（默认）：在某个渠道上下文中，每个发送者都有独立会话。
- `global`：某个渠道上下文中的所有参与者共享一个会话（仅在你有意共享上下文时使用）。
- **`dmScope`**：私信 的分组方式。
- `main`：所有 私信 共享主会话。
- `per-peer`：按发送者 id 在跨渠道范围内隔离。
- `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。
- `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。
- **`identityLinks`**：将标准 id 映射到带提供商前缀的 peer，用于跨渠道共享会话。
- **`reset`**：主重置策略。`daily` 会在本地时间的 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。若两者都已配置，则以先到期者为准。
- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 仍可作为 `direct` 的别名使用。
- **`parentForkMaxTokens`**：创建 fork 线程会话时允许的父会话最大 `totalTokens`（默认 `100000`）。
- 如果父会话的 `totalTokens` 高于该值，OpenClaw 会启动一个全新的线程会话，而不是继承父级转录历史。
- 设为 `0` 可禁用此保护，并始终允许父级 fork。
- **`mainKey`**：旧版字段。运行时始终对主私聊桶使用 `"main"`。
- **`agentToAgent.maxPingPongTurns`**：智能体之间通信时允许的最大来回回复轮次（整数，范围：`0`–`5`）。`0` 表示禁用 ping-pong 链式回复。
- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 可作别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 规则优先。
- **`identityLinks`**：将规范 id 映射到带提供商前缀的 peer，用于跨渠道共享会话。
- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在空闲 `idleMinutes` 后重置。当两者都配置时，哪个先到期就以哪个为准。
- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名。
- **`parentForkMaxTokens`**：创建分叉线程会话时，允许的父会话最大 `totalTokens`（默认 `100000`）。
- 如果父会话的 `totalTokens` 高于该值，OpenClaw 会启动一个新的线程会话，而不是继承父转录历史。
- 设为 `0` 可禁用此保护，并始终允许从父会话 fork。
- **`mainKey`**：旧字段。运行时始终对主直接聊天桶使用 `"main"`。
- **`agentToAgent.maxPingPongTurns`**：智能体到智能体 交换期间，智能体之间允许的最大来回回复轮次（整数，范围：`0`–`5`）。`0` 表示禁用 ping-pong 链。
- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 生效。
- **`maintenance`**：会话存储清理 + 保留控制。
- `mode`：`warn` 仅发出警告；`enforce` 会执行清理。
- `pruneAfter`：陈旧条目的时效截止点（默认 `30d`）。
- `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。
- `rotateBytes`：当 `sessions.json` 超过此大小时轮转（默认 `10mb`）。
- `resetArchiveRetention`：`*.reset.<timestamp>` 转录归档的保留时间。默认与 `pruneAfter` 相同；设为 `false` 可禁用。
- `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先移除最旧的产物/会话。
- `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。
- `mode`：`warn` 仅发出警告；`enforce` 则执行清理。
- `pruneAfter`：陈旧条目的年龄截止值（默认 `30d`）。
- `maxEntries`：`sessions.json` 中允许的最大条目数（默认 `500`）。
- `rotateBytes`：当 `sessions.json` 超过该大小时进行轮转（默认 `10mb`）。
- `resetArchiveRetention`：`*.reset.<timestamp>` 转录归档的保留时长。默认等于 `pruneAfter`；设为 `false` 可禁用。
- `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先删除最旧的工件/会话。
- `highWaterBytes`：可选的预算清理后目标值。默认是 `maxDiskBytes` 的 `80%`。
- **`threadBindings`**：线程绑定会话功能的全局默认值。
- `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`）
- `idleHours`：默认按小时计算的闲置自动取消聚焦时间（`0` 表示禁用；提供商可覆盖）
- `maxAgeHours`：默认按小时计算的硬性最大时长（`0` 表示禁用；提供商可覆盖）
- `idleHours`：默认按小时计的无活动自动取消聚焦时间（`0` 表示禁用；提供商可覆盖）
- `maxAgeHours`：默认按小时计的硬最大存活时间（`0` 表示禁用；提供商可覆盖）
</Accordion>
@ -1224,34 +1210,34 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像
按渠道/账号覆盖：`channels.<channel>.responsePrefix`、`channels.<channel>.accounts.<id>.responsePrefix`。
解析顺序（越具体优先级越高）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生为 `[{identity.name}]`。
解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生为 `[{identity.name}]`。
**模板变量：**
| 变量 | 说明 | 示例 |
| Variable | 说明 | 示例 |
| ----------------- | ---------------- | --------------------------- |
| `{model}` | 简短模型名 | `claude-opus-4-6` |
| `{model}` | 短模型名 | `claude-opus-4-6` |
| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` |
| `{provider}` | 提供商名称 | `anthropic` |
| `{thinkingLevel}` | 当前思考级别 | `high`, `low`, `off` |
| `{thinkingLevel}` | 当前思考级别 | `high`、`low`、`off` |
| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） |
变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。
### 确认反应
- 默认使用当前智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。
- 默认使用当前活跃智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。
- 按渠道覆盖：`channels.<channel>.ackReaction`、`channels.<channel>.accounts.<id>.ackReaction`。
- 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退值。
- 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退。
- 作用域：`group-mentions`（默认）、`group-all`、`direct`、`all`。
- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，回复后移除确认反应。
- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，在回复后移除确认反应。
- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。
在 Slack 和 Discord 上，未设置时，如果确认反应处于激活状态，则会保持状态反应启用。
在 Telegram 上，需要显式将其设为 `true` 才会启用生命周期状态反应。
在 Slack 和 Discord 上，未设置时，只要确认反应处于激活状态，就会保持状态反应启用。
在 Telegram 上，需显式将其设为 `true` 才会启用生命周期状态反应。
### 入站去抖
### 入站防抖
将来自同一发送者的快速纯文本消息批量合并为一次智能体轮次。媒体/附件会立即刷新。控制命令会绕过去抖处理。
将来自同一发送者的快速连续纯文本消息合并为单个智能体轮次。媒体/附件会立即刷新。控制命令会绕过防抖。
### TTS（文本转语音）
@ -1284,6 +1270,11 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像
speed: 1.0,
},
},
microsoft: {
voice: "en-US-AvaMultilingualNeural",
lang: "en-US",
outputFormat: "audio-24khz-48kbitrate-mono-mp3",
},
openai: {
apiKey: "openai_api_key",
baseUrl: "https://api.openai.com/v1",
@ -1296,11 +1287,12 @@ scripts/sandbox-browser-setup.sh # 可选的浏览器镜像
}
```
- `auto` 控制默认的自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可覆盖本地偏好，`/tts status` 会显示生效状态。
- `summaryModel` 会覆盖用于自动摘要的 `agents.defaults.model.primary`。
- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（选择启用）。
- API 密钥会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。
- `providers.openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序是配置、然后 `OPENAI_TTS_BASE_URL`、最后 `https://api.openai.com/v1`。
- `auto` 控制默认的自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可覆盖本地偏好，`/tts status` 会显示实际生效状态。
- `summaryModel` 会覆盖自动摘要所用的 `agents.defaults.model.primary`。
- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需主动启用）。
- API key 会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。
- 内置语音提供商由插件负责所有权。如果设置了 `plugins.allow`，请包含你想使用的每个 TTS 提供商插件，例如用于 Edge TTS 的 `microsoft`。旧版提供商 id `edge` 可作为 `microsoft` 的别名使用。
- `providers.openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为：配置，然后是 `OPENAI_TTS_BASE_URL`，最后是 `https://api.openai.com/v1`。
- 当 `providers.openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为 OpenAI 兼容的 TTS 服务器，并放宽模型/语音校验。
---
@ -1331,13 +1323,13 @@ Talk 模式的默认值（macOS/iOS/Android）。
}
```
- `talk.provider` 在配置了多个 Talk 提供商时，必须与 `talk.providers` 中的某个键匹配。
- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，并会自动迁移到 `talk.providers.<provider>`。
- `talk.provider` 在配置了多个 Talk 提供商时，必须匹配 `talk.providers` 中的某个键。
- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，会自动迁移到 `talk.providers.<provider>`。
- Voice ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。
- `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。
- 仅当未配置 Talk API 密钥时，才会应用 `ELEVENLABS_API_KEY` 回退。
- `providers.*.voiceAliases` 让 Talk 指令可以使用友好的名称。
- `silenceTimeoutMs` 控制 Talk 模式在用户静默后等待多长时间再发送转录。未设置时会保留平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。
- 只有在未配置 Talk API key 时，才会使用 `ELEVENLABS_API_KEY` 回退。
- `providers.*.voiceAliases` 让 Talk 指令可使用友好名称。
- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多久才发送转录。未设置时会保留平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。
---

326
docs/zh-CN/gateway/configuration.md
View File

@ -2,33 +2,32 @@
read_when:
- 首次设置 OpenClaw
- 查找常见配置模式
- 跳转到特定配置章节
summary: 配置概览：常见任务、快速设置以及完整参考的链接
- 导航到特定配置章节
summary: 配置概览：常见任务、快速设置，以及完整参考的链接
title: 配置
x-i18n:
generated_at: "2026-04-24T04:02:18Z"
generated_at: "2026-04-25T03:24:36Z"
model: gpt-5.4
provider: openai
source_hash: 7a47a2c02c37b012a8d8222d3f160634343090b633be722393bac2ebd6adc91c
source_hash: 2749fca881115d1d1915271af2d06037cfe87d6c4caf96dc46d8bf893a0669c6
source_path: gateway/configuration.md
workflow: 15
---
OpenClaw 会从 `~/.openclaw/openclaw.json` 读取一个可选的 <Tooltip tip="JSON5 支持注释和尾随逗号">**JSON5**</Tooltip> 配置。
当前生效的配置路径必须是一个常规文件。对于 OpenClaw 自有写入，不支持使用符号链接的 `openclaw.json`
布局；原子写入可能会替换该路径，而不是保留符号链接。如果你将配置保存在默认状态目录之外，请将
`OPENCLAW_CONFIG_PATH` 直接指向真实文件。
OpenClaw 会从 `~/.openclaw/openclaw.json` 读取可选的 <Tooltip tip="JSON5 支持注释和尾随逗号">**JSON5**</Tooltip> 配置。
生效的配置路径必须是常规文件。对于由 OpenClaw 管理的写入操作，不支持使用符号链接的 `openclaw.json`
布局；原子写入可能会替换该路径，而不是保留符号链接。如果你将配置保存在默认状态目录之外，请将 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。
如果该文件不存在，OpenClaw 会使用安全的默认值。添加配置的常见原因包括：
如果文件缺失，OpenClaw 会使用安全默认值。添加配置的常见原因包括：
- 连接渠道并控制谁可以向机器人发消息
- 连接渠道并控制谁可以向机器人发送消息
- 设置模型、工具、沙箱隔离或自动化（cron、hooks）
- 调整会话、媒体、网络或 UI
每个可用字段的完整列表，请参阅[完整参考](/zh-CN/gateway/configuration-reference)。
请参阅[完整参考](/zh-CN/gateway/configuration-reference)了解所有可用字段。
<Tip>
**刚开始接触配置？** 可以先运行 `openclaw onboard` 进行交互式设置，或者查看[配置示例](/zh-CN/gateway/configuration-examples)指南，获取可直接复制粘贴的完整配置。
**刚接触配置？** 可先使用 `openclaw onboard` 进行交互式设置，或查看[配置示例](/zh-CN/gateway/configuration-examples)指南，获取可直接复制粘贴的完整配置。
</Tip>
## 最小配置
@ -46,7 +45,7 @@ OpenClaw 会从 `~/.openclaw/openclaw.json` 读取一个可选的 <Tooltip tip="
<Tabs>
<Tab title="交互式向导">
```bash
openclaw onboard # 完整新手引导流程
openclaw onboard # 完整的新手引导流程
openclaw configure # 配置向导
```
</Tab>
@ -57,46 +56,54 @@ OpenClaw 会从 `~/.openclaw/openclaw.json` 读取一个可选的 <Tooltip tip="
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
```
</Tab>
<Tab title="控制 UI">
<Tab title="Control UI">
打开 [http://127.0.0.1:18789](http://127.0.0.1:18789) 并使用 **配置** 标签页。
控制 UI 会根据实时配置 schema 渲染表单，包括字段
Control UI 会根据实时配置 schema 渲染表单，其中包含字段
`title` / `description` 文档元数据，以及可用时的插件和渠道 schema，
并提供 **Raw JSON** 编辑器作为兜底方式。对于下钻式
UI 和其他工具，Gateway 网关还会暴露 `config.schema.lookup`，
用于获取单个路径作用域的 schema 节点及其直接子级摘要。
同时提供 **Raw JSON** 编辑器作为兜底方案。对于下钻式
UI 和其他工具，Gateway 网关 还提供 `config.schema.lookup`，
用于获取单个路径范围的 schema 节点及其直接子节点摘要。
</Tab>
<Tab title="直接编辑">
直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关会监视该文件并自动应用更改（参见[热重载](#config-hot-reload)）。
直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关 会监视该文件并自动应用更改（参见[热重载](#config-hot-reload)）。
</Tab>
</Tabs>
## 严格校验
<Warning>
OpenClaw 只接受完全匹配 schema 的配置。未知键名、格式错误的类型或无效值都会导致 Gateway 网关**拒绝启动**。唯一的根级例外是 `$schema`（字符串），以便编辑器附加 JSON Schema 元数据。
OpenClaw 仅接受完全匹配 schema 的配置。未知键名、格式错误的类型或无效值都会导致 Gateway 网关 **拒绝启动**。唯一的根级例外是 `$schema`（字符串），这样编辑器就可以附加 JSON Schema 元数据。
</Warning>
`openclaw config schema` 会打印供控制 UI
和校验使用的规范 JSON Schema。`config.schema.lookup` 会获取单个路径作用域节点及其
子级摘要，供下钻式工具使用。字段 `title`/`description` 文档元数据
`openclaw config schema` 会打印供 Control UI
和校验使用的规范 JSON Schema。`config.schema.lookup` 会获取单个路径范围节点及其
子节点摘要，用于下钻式工具。字段 `title`/`description` 的文档元数据
会贯穿嵌套对象、通配符（`*`）、数组项（`[]`）以及 `anyOf`/
`oneOf`/`allOf` 分支。当清单注册表已加载时，运行时插件和渠道 schema 也会合并进来。
`oneOf`/`allOf` 分支。运行时插件和渠道 schema 会在
manifest 注册表加载后合并进来。
当校验失败时：
- Gateway 网关不会启动
- Gateway 网关 不会启动
- 只有诊断命令可用（`openclaw doctor`、`openclaw logs`、`openclaw health`、`openclaw status`）
- 运行 `openclaw doctor` 查看精确问题
- 运行 `openclaw doctor --fix`（或 `--yes`）以应用修复
- 运行 `openclaw doctor` 查看具体问题
- 运行 `openclaw doctor --fix`（或 `--yes`）应用修复
Gateway 网关会在每次成功启动后保留一份可信的最新正确副本。
如果之后 `openclaw.json` 校验失败（或丢失 `gateway.mode`、体积明显缩小，或前面意外插入了一行日志），OpenClaw 会将损坏文件保留为 `.clobbered.*`，恢复最新正确副本，并记录恢复原因。下一次智能体轮次也会收到一条系统事件警告，这样主智能体就不会盲目重写已恢复的配置。当候选内容包含已脱敏的密钥占位符（例如 `***`）时，将不会提升为最新正确副本。
Gateway 网关 在每次成功启动后都会保留一份可信的最近一次正常配置副本。
如果之后 `openclaw.json` 校验失败（或丢失 `gateway.mode`、明显缩小、
或前面意外插入了一行日志），OpenClaw 会将损坏的文件保留为
`.clobbered.*`，恢复最近一次正常配置副本，并记录恢复原因。
下一次智能体回合还会收到系统事件警告，这样主智能体就不会盲目重写已恢复的配置。
如果候选配置包含诸如 `***` 之类的已脱敏密钥占位符，则不会将其提升为最近一次正常配置。
当所有校验问题都限定在 `plugins.entries.<id>...` 范围内时，OpenClaw
不会执行整文件恢复。它会保持当前配置继续生效，并显示插件局部失败，
这样插件 schema 或宿主版本不匹配就不会回滚无关的用户设置。
## 常见任务
<AccordionGroup>
<Accordion title="设置一个渠道（WhatsApp、Telegram、Discord 等）">
每个渠道在 `channels.<provider>` 下都有自己的配置区段。设置步骤请参阅对应的渠道页面：
每个渠道在 `channels.<provider>` 下都有自己的配置章节。设置步骤请参阅对应渠道页面：
- [WhatsApp](/zh-CN/channels/whatsapp) — `channels.whatsapp`
- [Telegram](/zh-CN/channels/telegram) — `channels.telegram`
@ -109,7 +116,7 @@ Gateway 网关会在每次成功启动后保留一份可信的最新正确副本
- [iMessage](/zh-CN/channels/imessage) — `channels.imessage`
- [Mattermost](/zh-CN/channels/mattermost) — `channels.mattermost`
所有渠道都共用同一种私信策略模式：
所有渠道都共享相同的私信策略模式：
```json5
{
@ -118,7 +125,7 @@ Gateway 网关会在每次成功启动后保留一份可信的最新正确副本
enabled: true,
botToken: "123:abc",
dmPolicy: "pairing", // pairing | allowlist | open | disabled
allowFrom: ["tg:123"], // 仅用于 allowlist/open
allowFrom: ["tg:123"], // only for allowlist/open
},
},
}
@ -127,7 +134,7 @@ Gateway 网关会在每次成功启动后保留一份可信的最新正确副本
</Accordion>
<Accordion title="选择并配置模型">
设置主模型和可选的回退模型：
设置主模型以及可选的回退模型：
```json5
{
@ -146,31 +153,31 @@ Gateway 网关会在每次成功启动后保留一份可信的最新正确副本
}
```
- `agents.defaults.models` 定义模型目录，并充当 `/model` 的允许列表。
- 使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 添加允许列表条目，而不会移除现有模型。若普通替换会删除条目，则除非你传入 `--replace`，否则会被拒绝。
- `agents.defaults.models` 定义模型目录，并充当 `/model` 的 allowlist。
- 使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 添加 allowlist 条目，而不会移除现有模型。若普通替换会移除条目，则会被拒绝，除非你传入 `--replace`。
- 模型引用使用 `provider/model` 格式（例如 `anthropic/claude-opus-4-6`）。
- `agents.defaults.imageMaxDimensionPx` 控制转录 / 工具图像的缩放下限（默认 `1200`）；在大量使用截图的运行中，较低的值通常可以减少视觉 token 用量。
- 关于在聊天中切换模型，请参阅[模型 CLI](/zh-CN/concepts/models)；关于认证轮换和回退行为，请参阅[模型故障转移](/zh-CN/concepts/model-failover)。
- 对于自定义 / 自托管提供商，请参阅参考中的[自定义提供商](/zh-CN/gateway/config-tools#custom-providers-and-base-urls)。
- `agents.defaults.imageMaxDimensionPx` 控制转录/工具图像的缩放下限（默认 `1200`）；较低的值通常会在大量截图的运行中减少视觉 token 使用量。
- 请参阅[Models CLI](/zh-CN/concepts/models)了解如何在聊天中切换模型，并参阅[模型故障切换](/zh-CN/concepts/model-failover)了解凭证轮换和回退行为。
- 对于自定义/自托管提供商，请参阅参考中的[自定义提供商](/zh-CN/gateway/config-tools#custom-providers-and-base-urls)。
</Accordion>
<Accordion title="控制谁可以给机器人发消息">
私信访问通过每个渠道的 `dmPolicy` 控制：
<Accordion title="控制谁可以向机器人发送消息">
私信访问权限通过每个渠道的 `dmPolicy` 控制：
- `"pairing"`（默认）：未知发送者会收到一次性配对码以供批准
- `"allowlist"`：只允许 `allowFrom` 中的发送者（或已配对允许存储中的发送者）
- `"pairing"`（默认）：未知发送者会收到一个一次性配对码以供批准
- `"allowlist"`：仅允许 `allowFrom` 中的发送者（或已配对的允许存储）
- `"open"`：允许所有传入私信（要求 `allowFrom: ["*"]`）
- `"disabled"`：忽略所有私信
对于群组，请使用 `groupPolicy` + `groupAllowFrom` 或渠道特定的允许列表。
对于群组，请使用 `groupPolicy` + `groupAllowFrom` 或渠道特定的 allowlist。
每个渠道的详细信息，请参阅[完整参考](/zh-CN/gateway/config-channels#dm-and-group-access)。
请参阅[完整参考](/zh-CN/gateway/config-channels#dm-and-group-access)了解各渠道的详细信息。
</Accordion>
<Accordion title="设置群聊提及门控">
群消息默认**需要提及**。可按智能体配置模式：
群组消息默认**要求提及**。可按智能体配置模式：
```json5
{
@ -194,12 +201,12 @@ Gateway 网关会在每次成功启动后保留一份可信的最新正确副本
- **元数据提及**：原生 @ 提及（WhatsApp 点按提及、Telegram @bot 等）
- **文本模式**：`mentionPatterns` 中的安全正则模式
- 有关每个渠道的覆盖项和 self-chat 模式，请参阅[完整参考](/zh-CN/gateway/config-channels#group-chat-mention-gating)
- 请参阅[完整参考](/zh-CN/gateway/config-channels#group-chat-mention-gating)了解各渠道覆盖项和自聊模式。
</Accordion>
<Accordion title="按智能体限制 Skills">
使用 `agents.defaults.skills` 作为共享基线，然后通过 `agents.list[].skills` 覆盖特定
对共享基线使用 `agents.defaults.skills`，然后通过 `agents.list[].skills` 覆盖特定
智能体：
```json5
@ -209,24 +216,24 @@ Gateway 网关会在每次成功启动后保留一份可信的最新正确副本
skills: ["github", "weather"],
},
list: [
{ id: "writer" }, // 继承 github、weather
{ id: "docs", skills: ["docs-search"] }, // 替换默认值
{ id: "locked-down", skills: [] }, // 无 Skills
{ id: "writer" }, // inherits github, weather
{ id: "docs", skills: ["docs-search"] }, // replaces defaults
{ id: "locked-down", skills: [] }, // no skills
],
},
}
```
- 省略 `agents.defaults.skills` 表示默认情况下 Skills 不受限制。
- 省略 `agents.list[].skills` 表示继承默认值。
- 设置 `agents.list[].skills: []` 表示不使用 Skills。
- 参阅 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 以及
- 省略 `agents.defaults.skills` 则默认 Skills 不受限制。
- 省略 `agents.list[].skills` 则继承默认值。
- 设置 `agents.list[].skills: []` 表示不启用任何 Skills。
- 请参阅 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config)，以及
[配置参考](/zh-CN/gateway/config-agents#agents-defaults-skills)。
</Accordion>
<Accordion title="调整 Gateway 网关渠道健康监控">
控制 Gateway 网关对看起来已陈旧的渠道执行重启的积极程度：
<Accordion title="调整网关渠道健康监控">
控制网关对看起来已停滞渠道的重启激进程度：
```json5
{
@ -250,18 +257,18 @@ Gateway 网关会在每次成功启动后保留一份可信的最新正确副本
- 设置 `gateway.channelHealthCheckMinutes: 0` 可全局禁用健康监控重启。
- `channelStaleEventThresholdMinutes` 应大于或等于检查间隔。
- 使用 `channels.<provider>.healthMonitor.enabled` 或 `channels.<provider>.accounts.<id>.healthMonitor.enabled`，可在不禁用全局监控的情况下，仅为某个渠道或账户禁用自动重启。
- 有关运维调试，请参阅[健康检查](/zh-CN/gateway/health)；有关全部字段，请参阅[完整参考](/zh-CN/gateway/configuration-reference#gateway)。
- 使用 `channels.<provider>.healthMonitor.enabled` 或 `channels.<provider>.accounts.<id>.healthMonitor.enabled`，可只为某一个渠道或账户禁用自动重启，而无需关闭全局监控。
- 请参阅[健康检查](/zh-CN/gateway/health)了解运维调试，并参阅[完整参考](/zh-CN/gateway/configuration-reference#gateway)了解所有字段。
</Accordion>
<Accordion title="配置会话和重置">
会话控制对话的连续性和隔离性：
<Accordion title="配置会话与重置">
会话控制对话连续性和隔离性：
```json5
{
session: {
dmScope: "per-channel-peer", // 推荐用于多用户
dmScope: "per-channel-peer", // recommended for multi-user
threadBindings: {
enabled: true,
idleHours: 24,
@ -276,10 +283,10 @@ Gateway 网关会在每次成功启动后保留一份可信的最新正确副本
}
```
- `dmScope`：`main`（共享）| `per-peer` | `per-channel-peer` | `per-account-channel-peer`
- `dmScope`: `main`（共享） | `per-peer` | `per-channel-peer` | `per-account-channel-peer`
- `threadBindings`：线程绑定会话路由的全局默认值（Discord 支持 `/focus`、`/unfocus`、`/agents`、`/session idle` 和 `/session max-age`）。
- 有关作用域、身份链接和发送策略，请参阅[会话管理](/zh-CN/concepts/session)。
- 有关全部字段，请参阅[完整参考](/zh-CN/gateway/config-agents#session)。
- 请参阅[会话管理](/zh-CN/concepts/session)了解作用域、身份关联和发送策略。
- 请参阅[完整参考](/zh-CN/gateway/config-agents#session)了解所有字段。
</Accordion>
@ -299,16 +306,16 @@ Gateway 网关会在每次成功启动后保留一份可信的最新正确副本
}
```
先构建镜像：`scripts/sandbox-setup.sh`
请先构建镜像：`scripts/sandbox-setup.sh`
完整指南请参阅[沙箱隔离](/zh-CN/gateway/sandboxing)，全部选项请参阅[完整参考](/zh-CN/gateway/config-agents#agentsdefaultssandbox)。
请参阅[沙箱隔离](/zh-CN/gateway/sandboxing)了解完整指南，并参阅[完整参考](/zh-CN/gateway/config-agents#agentsdefaultssandbox)了解所有选项。
</Accordion>
<Accordion title="为官方 iOS 构建启用基于 relay 的推送">
基于 relay 的推送在 `openclaw.json` 中配置。
在 Gateway 网关配置中设置：
在 Gateway 网关 配置中设置以下内容：
```json5
{
@ -326,43 +333,43 @@ Gateway 网关会在每次成功启动后保留一份可信的最新正确副本
}
```
等效的 CLI 命令：
对应的 CLI 写法：
```bash
openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
```
这样做的作用：
其作用如下：
- 让 Gateway 网关能够通过外部 relay 发送 `push.test`、唤醒提示和重连唤醒。
- 使用由已配对 iOS 应用转发的、基于注册作用域的发送授权。Gateway 网关不需要部署范围的 relay 令牌。
- 将每个基于 relay 的注册绑定到 iOS 应用所配对的 Gateway 网关身份，因此其他 Gateway 网关无法复用已存储的注册信息。
- 本地 / 手动构建的 iOS 版本仍然使用直接 APNs。基于 relay 的发送仅适用于通过 relay 注册的官方分发版本。
- 必须与官方 / TestFlight iOS 构建中内置的 relay 基础 URL 匹配，这样注册和发送流量才能到达同一个 relay 部署。
- 让网关可以通过外部 relay 发送 `push.test`、唤醒提示以及重连唤醒。
- 使用由已配对 iOS 应用转发的、按注册范围限定的发送授权。Gateway 网关 不需要部署范围的 relay token。
- 将每个基于 relay 的注册绑定到 iOS 应用所配对的 Gateway 网关 身份，因此其他网关无法复用已存储的注册。
- 本地/手动构建的 iOS 版本仍然直接使用 APNs。基于 relay 的发送仅适用于通过 relay 注册的官方分发版本。
- 必须与官方/TestFlight iOS 构建中内置的 relay 基础 URL 一致，这样注册和发送流量才能到达同一个 relay 部署。
端到端流程：
1. 安装一个使用相同 relay 基础 URL 编译的官方 / TestFlight iOS 构建版本。
2. 在 Gateway 网关上配置 `gateway.push.apns.relay.baseUrl`。
3. 将 iOS 应用与 Gateway 网关配对，并让节点会话和操作员会话都连接上。
4. iOS 应用获取 Gateway 网关身份，使用 App Attest 和应用回执向 relay 注册，然后将基于 relay 的 `push.apns.register` 载荷发布到已配对的 Gateway 网关。
5. Gateway 网关存储 relay 句柄和发送授权，然后将它们用于 `push.test`、唤醒提示和重连唤醒。
1. 安装一个使用相同 relay 基础 URL 编译的官方/TestFlight iOS 构建。
2. 在网关上配置 `gateway.push.apns.relay.baseUrl`。
3. 将 iOS 应用与网关配对，并让节点会话和操作员会话都连接成功。
4. iOS 应用会获取网关身份，使用 App Attest 和应用回执向 relay 注册，然后将基于 relay 的 `push.apns.register` 负载发布到已配对的网关。
5. Gateway 网关 会存储 relay 句柄和发送授权，然后将它们用于 `push.test`、唤醒提示和重连唤醒。
运行说明：
运维说明：
- 如果你将 iOS 应用切换到另一个 Gateway 网关，请重新连接应用，以便它发布一个绑定到该 Gateway 网关的新 relay 注册信息。
- 如果你发布了一个指向不同 relay 部署的新 iOS 构建版本，应用会刷新其缓存的 relay 注册信息，而不是复用旧的 relay 来源。
- 如果你将 iOS 应用切换到另一个网关，请重新连接该应用，以便它发布一个绑定到该网关的新 relay 注册。
- 如果你发布了一个指向不同 relay 部署的新 iOS 构建，应用会刷新其缓存的 relay 注册，而不是复用旧的 relay 来源。
兼容性说明：
- `OPENCLAW_APNS_RELAY_BASE_URL` 和 `OPENCLAW_APNS_RELAY_TIMEOUT_MS` 仍可用作临时环境变量覆盖项。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍然只是一个仅限 local loopback 的开发逃生口；不要在配置中持久化 HTTP relay URL。
- `OPENCLAW_APNS_RELAY_BASE_URL` 和 `OPENCLAW_APNS_RELAY_TIMEOUT_MS` 仍可作为临时环境变量覆盖项使用。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍然只是一个仅限 local loopback 的开发兜底方案；不要在配置中持久化 HTTP relay URL。
有关端到端流程，请参阅 [iOS App](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)；有关 relay 安全模型，请参阅 [Authentication and trust flow](/zh-CN/platforms/ios#authentication-and-trust-flow)。
请参阅[iOS App](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)了解端到端流程，并参阅[认证与信任流程](/zh-CN/platforms/ios#authentication-and-trust-flow)了解 relay 安全模型。
</Accordion>
<Accordion title="设置心跳（周期性签到）">
<Accordion title="设置 heartbeat（定期 check-in）">
```json5
{
agents: {
@ -378,7 +385,7 @@ Gateway 网关会在每次成功启动后保留一份可信的最新正确副本
- `every`：时长字符串（`30m`、`2h`）。设置为 `0m` 可禁用。
- `target`：`last` | `none` | `<channel-id>`（例如 `discord`、`matrix`、`telegram` 或 `whatsapp`）
- `directPolicy`：对于私信风格的心跳目标，使用 `allow`（默认）或 `block`
- `directPolicy`：用于私信风格 heartbeat 目标的 `allow`（默认）或 `block`
- 完整指南请参阅 [Heartbeat](/zh-CN/gateway/heartbeat)。
</Accordion>
@ -398,14 +405,14 @@ Gateway 网关会在每次成功启动后保留一份可信的最新正确副本
}
```
- `sessionRetention`：从 `sessions.json` 中修剪已完成的隔离运行会话（默认 `24h`；设置为 `false` 可禁用）。
- `runLog`：按大小和保留行数修剪 `cron/runs/<jobId>.jsonl`。
- 有关功能概览和 CLI 示例，请参阅 [Cron jobs](/zh-CN/automation/cron-jobs)。
- `sessionRetention`：从 `sessions.json` 中清理已完成的隔离运行会话（默认 `24h`；设置为 `false` 可禁用）。
- `runLog`：按大小和保留行数清理 `cron/runs/<jobId>.jsonl`。
- 功能概览和 CLI 示例请参阅[cron 作业](/zh-CN/automation/cron-jobs)。
</Accordion>
<Accordion title="设置 webhooks（hooks）">
在 Gateway 网关上启用 HTTP webhook 端点：
<Accordion title="设置 webhook（hooks）">
在 Gateway 网关 上启用 HTTP webhook 端点：
```json5
{
@ -429,20 +436,20 @@ Gateway 网关会在每次成功启动后保留一份可信的最新正确副本
```
安全说明：
- 将所有 hook / webhook 载荷内容视为不可信输入。
- 使用专用的 `hooks.token`；不要复用共享的 Gateway 网关令牌。
- Hook 认证仅支持请求头（`Authorization: Bearer ...` 或 `x-openclaw-token`）；查询字符串中的令牌会被拒绝。
- `hooks.path` 不能是 `/`；请将 webhook 入口放在专用子路径上，例如 `/hooks`。
- 保持不安全内容绕过标志为禁用状态（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`），除非是在进行严格限定范围的调试。
- 如果启用了 `hooks.allowRequestSessionKey`，也请设置 `hooks.allowedSessionKeyPrefixes`，以限制调用方可选的会话键。
- 对于由 hook 驱动的智能体，优先使用现代高强度模型层级和严格的工具策略（例如尽可能仅允许消息类工具，并配合沙箱隔离）。
- 将所有 hook/webhook 负载内容都视为不受信任输入。
- 使用专用的 `hooks.token`；不要复用共享的 Gateway 网关 token。
- Hook 认证仅支持请求头（`Authorization: Bearer ...` 或 `x-openclaw-token`）；查询字符串 token 会被拒绝。
- `hooks.path` 不能是 `/`；请将 webhook 入口保持在专用子路径下，例如 `/hooks`。
- 保持不安全内容绕过标志关闭（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`），除非你是在进行严格限定范围的调试。
- 如果你启用了 `hooks.allowRequestSessionKey`，也请设置 `hooks.allowedSessionKeyPrefixes` 来限制调用方可选的会话键。
- 对于由 hook 驱动的智能体，优先选择更强的现代模型层级和严格的工具策略（例如仅消息传递，并尽可能启用沙箱隔离）。
所有映射选项和 Gmail 集成，请参阅[完整参考](/zh-CN/gateway/configuration-reference#hooks)。
所有映射选项和 Gmail 集成请参阅[完整参考](/zh-CN/gateway/configuration-reference#hooks)。
</Accordion>
<Accordion title="配置多智能体路由">
运行多个相互隔离的智能体，并分别使用不同的工作区和会话：
运行多个彼此隔离、拥有独立工作区和会话的智能体：
```json5
{
@ -459,7 +466,7 @@ Gateway 网关会在每次成功启动后保留一份可信的最新正确副本
}
```
绑定规则和按智能体划分的访问配置，请参阅 [Multi-Agent](/zh-CN/concepts/multi-agent) 和[完整参考](/zh-CN/gateway/config-agents#multi-agent-routing)。
绑定规则和每个智能体的访问配置请参阅[多智能体](/zh-CN/concepts/multi-agent)和[完整参考](/zh-CN/gateway/config-agents#multi-agent-routing)。
</Accordion>
@ -477,41 +484,50 @@ Gateway 网关会在每次成功启动后保留一份可信的最新正确副本
}
```
- **单个文件**：替换其所在的对象
- **单文件**：替换所在的整个对象
- **文件数组**：按顺序深度合并（后者优先）
- **同级键**：在 include 之后合并（覆盖 include 中的值）
- **嵌套 include**：支持，最多 10 层深度
- **相对路径**：相对于包含它的文件进行解析
- **OpenClaw 自有写入**：当一次写入只更改一个由单文件 include 支持的顶级区段时，例如 `plugins: { $include: "./plugins.json5" }`，
- **同级键**：在 include 之后合并（覆盖已包含的值）
- **嵌套 include**：支持，最多 10 层
- **相对路径**：相对于包含它的文件解析
- **由 OpenClaw 管理的写入**：当某次写入仅更改单个顶层部分，
且该部分由单文件 include 支持，例如 `plugins: { $include: "./plugins.json5" }`，
OpenClaw 会更新该被包含文件，并保持 `openclaw.json` 不变
- **不支持的透传写入**：对于根级 include、include 数组，以及带有同级覆盖项的 include，OpenClaw 自有写入会以关闭失败方式处理，而不是将配置拍平
- **错误处理**：对缺失文件、解析错误和循环 include 提供清晰错误信息
- **不支持的透传写入**：根级 include、include 数组，以及带有
同级覆盖的 include，在由 OpenClaw 管理的写入中会以失败关闭，而不是
将配置拍平成单个文件
- **错误处理**：对缺失文件、解析错误和循环 include 提供明确错误信息
</Accordion>
</AccordionGroup>
## 配置热重载
Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改 —— 对于大多数设置，不需要手动重启。
Gateway 网关 会监视 `~/.openclaw/openclaw.json` 并自动应用更改——大多数设置都不需要手动重启。
直接编辑文件会在通过校验前被视为不可信。监视器会等待
编辑器临时写入 / 重命名抖动稳定下来，读取最终文件，并通过恢复最新正确配置来拒绝无效的外部编辑。OpenClaw 自有的
配置写入在真正写入前也会经过同样的 schema 校验；像删除 `gateway.mode`
或将文件缩小到原来一半以下这类破坏性覆盖会被拒绝，并保存为 `.rejected.*` 以供检查。
直接编辑文件会被视为不受信任，直到通过校验为止。监视器会等待
编辑器临时写入/重命名的抖动稳定下来，读取最终文件，并通过恢复
最近一次正常配置来拒绝无效的外部编辑。由 OpenClaw 管理的
配置写入在写入前也会通过相同的 schema 闸门；像删除 `gateway.mode`
或将文件缩小到原来一半以下这类破坏性覆盖会被拒绝，
并保存为 `.rejected.*` 以供检查。
插件局部校验失败是例外：如果所有问题都位于
`plugins.entries.<id>...` 之下，重载会保持当前配置并报告该插件问题，
而不是恢复 `.last-good`。
如果你在日志中看到 `Config auto-restored from last-known-good` 或
`config reload restored last-known-good config`，请检查 `openclaw.json`
旁边对应的 `.clobbered.*` 文件，修复被拒绝的载荷，然后运行
`openclaw config validate`。恢复检查清单请参阅 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。
旁边对应的 `.clobbered.*` 文件，修复被拒绝的负载，然后运行
`openclaw config validate`。恢复检查清单请参阅[Gateway 网关 故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。
### 重载模式
| 模式 | 行为 |
| ---------------------- | --------------------------------------------------------------------------------------- |
| **`hybrid`**（默认） | 立即热应用安全更改。对关键更改自动重启。 |
| **`hot`** | 仅热应用安全更改。需要重启时记录警告 —— 由你手动处理。 |
| **`restart`** | 对任何配置更改都重启 Gateway 网关，无论是否安全。 |
| **`off`** | 禁用文件监视。更改会在下一次手动重启时生效。 |
| **`hybrid`**（默认） | 立即热应用安全更改。对于关键更改会自动重启。 |
| **`hot`** | 仅热应用安全更改。需要重启时会记录警告——由你来处理。 |
| **`restart`** | 任何配置更改都会重启 Gateway 网关，无论是否安全。 |
| **`off`** | 禁用文件监视。更改会在下次手动重启时生效。 |
```json5
{
@ -523,52 +539,54 @@ Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改 ——
### 哪些可以热应用，哪些需要重启
大多数字段都可以在不停机的情况下热应用。在 `hybrid` 模式下，需要重启的更改会自动处理。
大多数字段都可以无停机热应用。在 `hybrid` 模式下，需要重启的更改会自动处理。
| 类别 | 字段 | 需要重启？ |
| ------------------- | ----------------------------------------------------------------- | --------------- |
| 渠道 | `channels.*`、`web`（WhatsApp）—— 所有内置和插件渠道 | 否 |
| 智能体和模型 | `agent`、`agents`、`models`、`routing` | 否 |
| 渠道 | `channels.*`、`web`（WhatsApp）——所有内置渠道和渠道插件 | 否 |
| 智能体与模型 | `agent`、`agents`、`models`、`routing` | 否 |
| 自动化 | `hooks`、`cron`、`agent.heartbeat` | 否 |
| 会话和消息 | `session`、`messages` | 否 |
| 工具和媒体 | `tools`、`browser`、`skills`、`audio`、`talk` | 否 |
| UI 和其他 | `ui`、`logging`、`identity`、`bindings` | 否 |
| Gateway 网关服务器 | `gateway.*`（端口、绑定、认证、tailscale、TLS、HTTP） | **是** |
| 会话与消息 | `session`、`messages` | 否 |
| 工具与媒体 | `tools`、`browser`、`skills`、`audio`、`talk` | 否 |
| UI 与杂项 | `ui`、`logging`、`identity`、`bindings` | 否 |
| Gateway 网关 服务器 | `gateway.*`（port、bind、auth、tailscale、TLS、HTTP） | **是** |
| 基础设施 | `discovery`、`canvasHost`、`plugins` | **是** |
<Note>
`gateway.reload` 和 `gateway.remote` 是例外 —— 更改它们**不会**触发重启。
`gateway.reload` 和 `gateway.remote` 是例外——更改它们**不会**触发重启。
</Note>
### 重载规划
当你编辑一个通过 `$include` 引用的源文件时，OpenClaw 会根据源文件编写的布局来规划
重载，而不是根据拍平后的内存视图来规划。
即使某个顶级区段单独放在自己的被包含文件中，例如
`plugins: { $include: "./plugins.json5" }`，这样也能让热重载决策（热应用还是重启）保持可预测。
如果源布局存在歧义，重载规划会以关闭失败方式处理。
当你编辑一个通过 `$include` 引用的源文件时，OpenClaw 会根据源文件作者编写的布局
来规划重载，而不是根据已拍平的内存视图。
这样即使某个
单独的顶层部分位于其自己的包含文件中，例如
`plugins: { $include: "./plugins.json5" }`，热重载决策（热应用还是重启）也仍然可预测。
如果源布局存在歧义，重载规划会以失败关闭。
## 配置 RPC（程序化更新）
## Config RPC（程序化更新）
对于通过 Gateway 网关 API 写入配置的工具，推荐使用以下流程：
对于通过 Gateway 网关 API 写入配置的工具，建议优先使用以下流程：
- 使用 `config.schema.lookup` 检查一个子树（浅层 schema 节点 + 子级摘要）
- 使用 `config.schema.lookup` 检查一个子树（浅层 schema 节点 + 子节点
摘要）
- 使用 `config.get` 获取当前快照以及 `hash`
- 使用 `config.patch` 执行部分更新（JSON merge patch：对象合并、`null`
删除、数组替换）
- 仅在你确实打算替换整个配置时才使用 `config.apply`
- 使用 `config.patch` 进行部分更新（JSON merge patch：对象合并，`null`
删除，数组整体替换）
- 仅当你确实打算替换整个配置时才使用 `config.apply`
- 使用 `update.run` 执行显式自更新并重启
<Note>
控制平面写入（`config.apply`、`config.patch`、`update.run`）会
按每个 `deviceId+clientIp` 在 60 秒内限制为 3 次请求。
重启请求会被合并，然后在两次重启周期之间强制执行 30 秒冷却时间。
控制平面写入（`config.apply`、`config.patch`、`update.run`）会按
每个 `deviceId+clientIp` 在 60 秒内限制为 3 次请求。
重启请求会被合并，然后在两次重启周期之间强制 30 秒冷却时间。
</Note>
部分 patch 示例：
```bash
openclaw gateway call config.get --params '{}' # 获取 payload.hash
openclaw gateway call config.get --params '{}' # capture payload.hash
openclaw gateway call config.patch --params '{
"raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
"baseHash": "<hash>"
@ -581,7 +599,7 @@ openclaw gateway call config.patch --params '{
## 环境变量
OpenClaw 会读取来自父进程的环境变量，以及：
OpenClaw 会从父进程读取环境变量，另外还会读取：
- 当前工作目录中的 `.env`（如果存在）
- `~/.openclaw/.env`（全局回退）
@ -598,7 +616,7 @@ OpenClaw 会读取来自父进程的环境变量，以及：
```
<Accordion title="导入 shell 环境变量（可选）">
如果启用了此功能，并且预期键名尚未设置，OpenClaw 会运行你的登录 shell，并且只导入缺失的键名：
如果启用且预期键名尚未设置，OpenClaw 会运行你的登录 shell，并且只导入缺失的键名：
```json5
{
@ -608,7 +626,7 @@ OpenClaw 会读取来自父进程的环境变量，以及：
}
```
等效环境变量：`OPENCLAW_LOAD_SHELL_ENV=1`
对应的环境变量：`OPENCLAW_LOAD_SHELL_ENV=1`
</Accordion>
<Accordion title="在配置值中替换环境变量">
@ -624,9 +642,9 @@ OpenClaw 会读取来自父进程的环境变量，以及：
规则：
- 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`
- 缺失或为空的变量会在加载时抛出错误
- 使用 `$${VAR}` 转义以输出字面值
- 可在 `$include` 文件中使用
- 缺失或为空的环境变量会在加载时报错
- 使用 `$${VAR}` 转义以输出字面量
- 在 `$include` 文件中也可用
- 内联替换：`"${BASE}/v1"` → `"https://api.example.com/v1"`
</Accordion>
@ -664,11 +682,11 @@ OpenClaw 会读取来自父进程的环境变量，以及：
}
```
有关 SecretRef 的详细信息（包括用于 `env` / `file` / `exec` 的 `secrets.providers`），请参阅[密钥管理](/zh-CN/gateway/secrets)。
支持的凭证路径列在 [SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface) 中。
SecretRef 详情（包括适用于 `env`/`file`/`exec` 的 `secrets.providers`）见[密钥管理](/zh-CN/gateway/secrets)。
支持的凭证路径列于 [SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface)。
</Accordion>
完整的优先级和来源，请参阅[环境](/zh-CN/help/environment)。
完整的优先级和来源请参阅[环境](/zh-CN/help/environment)。
## 完整参考
@ -678,8 +696,8 @@ OpenClaw 会读取来自父进程的环境变量，以及：
_相关内容：[配置示例](/zh-CN/gateway/configuration-examples) · [配置参考](/zh-CN/gateway/configuration-reference) · [Doctor](/zh-CN/gateway/doctor)_
## 相关内容
## 相关
- [配置参考](/zh-CN/gateway/configuration-reference)
- [配置示例](/zh-CN/gateway/configuration-examples)
- [Gateway 网关运行手册](/zh-CN/gateway)
- [Gateway 网关 运行手册](/zh-CN/gateway)

289
docs/zh-CN/gateway/troubleshooting.md
View File

@ -1,26 +1,26 @@
---
read_when:
- 故障排除中心将你指引到这里，以进行更深入的诊断
- 故障排除中心将你引导到这里，以进行更深入的诊断
- 你需要基于稳定症状的操作手册章节，并包含精确命令
summary: Gateway 网关、渠道、自动化、节点和浏览器的深度故障排除操作手册
title: 故障排除
x-i18n:
generated_at: "2026-04-24T07:36:34Z"
generated_at: "2026-04-25T03:24:34Z"
model: gpt-5.4
provider: openai
source_hash: 20066bdab03f05304b3a620fbadc38e4dc74b740da151c58673dcf5196e5f1e1
source_hash: 14565a260226cbd3c78e1449621da5ff0bb8f580d3f10345a7d8650db9f706a8
source_path: gateway/troubleshooting.md
workflow: 15
---
# Gateway 网关故障排除
本页是深度操作手册。
如果你想先走快速分诊流程，请从 [/help/troubleshooting](/zh-CN/help/troubleshooting) 开始。
此页面是深度操作手册。
如果你想先使用快速分诊流程，请从 [/help/troubleshooting](/zh-CN/help/troubleshooting) 开始。
## 命令阶梯
先按顺序运行这些命令：
先按以下顺序运行这些命令：
```bash
openclaw status
@ -32,13 +32,13 @@ openclaw channels status --probe
预期的健康信号：
- `openclaw gateway status` 显示 `Runtime: running`、`Connectivity probe: ok`，以及一行 `Capability: ...`。
- `openclaw doctor` 报告没有会阻塞的配置 / 服务问题。
- `openclaw channels status --probe` 显示每个账户的实时传输状态，并在支持的情况下显示探测 / 审计结果，例如 `works` 或 `audit ok`。
- `openclaw gateway status` 显示 `Runtime: running`、`Connectivity probe: ok` 和一行 `Capability: ...`。
- `openclaw doctor` 报告没有阻塞性的配置或服务问题。
- `openclaw channels status --probe` 显示每个账号的实时传输状态，并且在支持的情况下，显示诸如 `works` 或 `audit ok` 之类的探测/审计结果。
## Anthropic 429：长上下文需要额外使用额度
## Anthropic 429：长上下文需要额外用量资格
当日志 / 错误中包含以下内容时，使用本节：
当日志/错误中包含以下内容时，使用本节：
`HTTP 429: rate_limit_error: Extra usage is required for long context requests`。
```bash
@ -49,14 +49,14 @@ openclaw config get agents.defaults.models
检查以下内容：
- 已选的 Anthropic Opus / Sonnet 模型启用了 `params.context1m: true`。
- 当前 Anthropic 凭证没有资格使用长上下文。
- 只有在需要走 1M beta 路径的长会话 / 模型运行中，请求才会失败。
- 所选的 Anthropic Opus/Sonnet 模型设置了 `params.context1m: true`。
- 当前的 Anthropic 凭证不具备长上下文用量资格。
- 只有在需要走 1M beta 路径的长会话/模型运行中，请求才会失败。
修复选项：
1. 为该模型禁用 `context1m`，回退到普通上下文窗口。
2. 使用有资格发起长上下文请求的 Anthropic 凭证，或切换到 Anthropic API key。
2. 使用具备长上下文请求资格的 Anthropic 凭证，或切换到 Anthropic API key。
3. 配置回退模型，以便在 Anthropic 长上下文请求被拒绝时，运行仍可继续。
相关内容：
@ -67,11 +67,11 @@ openclaw config get agents.defaults.models
## 本地 OpenAI 兼容后端可通过直接探测，但智能体运行失败
在以下情况使用本节：
在以下情况中使用本节：
- `curl ... /v1/models` 可用
- 很小的直接 `/v1/chat/completions` 调用可用
- OpenClaw 模型运行只在正常智能体轮次中失败
- OpenClaw 模型运行仅在正常智能体轮次中失败
```bash
curl http://127.0.0.1:1234/v1/models
@ -84,22 +84,22 @@ openclaw logs --follow
检查以下内容：
- 直接的小请求成功，但 OpenClaw 运行只在较大的提示词下失败
- 后端报错 `messages[].content` 需要字符串
- 只有在更大的提示词 token 数量或完整智能体运行时提示词下才会出现后端崩溃
- 直接的小请求成功，但 OpenClaw 运行仅在较大提示词下失败
- 后端报错，提示 `messages[].content` 预期是字符串
- 后端仅在较大 prompt token 数量或完整智能体运行时提示词下崩溃
常见特征：
- `messages[...].content: invalid type: sequence, expected a string` → 后端拒绝结构化的 Chat Completions 内容片段。修复方法：设置 `models.providers.<provider>.models[].compat.requiresStringContent: true`。
- 直接的小请求成功，但 OpenClaw 智能体运行因后端 / 模型崩溃而失败（例如某些 `inferrs` 构建中的 Gemma）→ OpenClaw 传输层很可能已经正确；是后端在处理更大的智能体运行时提示词形态时失败。
- 禁用工具后失败有所减少，但没有消失 → 工具 schema 是压力来源之一，但剩余问题仍然是上游模型 / 服务器容量不足或后端 bug。
- `messages[...].content: invalid type: sequence, expected a string` → 后端拒绝结构化的 Chat Completions 内容分段。修复方式：设置 `models.providers.<provider>.models[].compat.requiresStringContent: true`。
- 直接的小请求成功，但 OpenClaw 智能体运行因后端/模型崩溃而失败（例如某些 `inferrs` 构建中的 Gemma）→ OpenClaw 传输层很可能已经正确；是后端在更大的 Agent Runtimes 提示词形态下失败。
- 禁用工具后失败有所减少，但未消失 → 工具 schema 是压力来源之一，但剩余问题仍然是上游模型/服务器容量不足或后端 bug。
修复选项：
1. 对只支持字符串 Chat Completions 的后端设置 `compat.requiresStringContent: true`。
2. 对无法可靠处理 OpenClaw 工具 schema 表面的模型 / 后端设置 `compat.supportsTools: false`。
3. 尽可能降低提示词压力：更小的工作区引导、更短的会话历史、更轻量的本地模型，或换用对长上下文支持更强的后端。
4. 如果直接的小请求持续通过，而 OpenClaw 智能体轮次仍在后端内部崩溃，则应将其视为上游服务器 / 模型限制，并向上游提交复现，附上已被接受的负载形态。
1. 为仅接受字符串 Chat Completions 内容的后端设置 `compat.requiresStringContent: true`。
2. 为无法可靠处理 OpenClaw 工具 schema 接口的模型/后端设置 `compat.supportsTools: false`。
3. 尽可能降低提示词压力：更小的工作区引导、更短的会话历史、更轻量的本地模型，或使用对长上下文支持更强的后端。
4. 如果直接的小请求持续通过，但 OpenClaw 智能体轮次仍在后端内部崩溃，请将其视为上游服务器/模型限制，并向上游提交复现，附上它能够接受的载荷形态。
相关内容：
@ -107,9 +107,9 @@ openclaw logs --follow
- [/gateway/configuration](/zh-CN/gateway/configuration)
- [/gateway/configuration-reference#openai-compatible-endpoints](/zh-CN/gateway/configuration-reference#openai-compatible-endpoints)
## 无回复
## 没有回复
如果渠道已上线但没有任何回复，请先检查路由和策略，再重新连接任何内容。
如果渠道已上线但没有任何响应，在重新连接任何内容之前，请先检查路由和策略。
```bash
openclaw status
@ -123,13 +123,13 @@ openclaw logs --follow
- 私信发送者的配对仍在等待中。
- 群组提及门控（`requireMention`、`mentionPatterns`）。
- 渠道 / 群组允许列表不匹配。
- 渠道/群组 allowlist 不匹配。
常见特征：
- `drop guild message (mention required` → 群组消息会被忽略，直到包含提及。
- `pairing request` → 发送者需要获批。
- `blocked` / `allowlist` → 发送者 / 渠道被策略过滤。
- `drop guild message (mention required` → 群消息在被提及之前会被忽略。
- `pairing request` → 发送者需要批准。
- `blocked` / `allowlist` → 发送者/渠道被策略过滤。
相关内容：
@ -137,9 +137,9 @@ openclaw logs --follow
- [/channels/pairing](/zh-CN/channels/pairing)
- [/channels/groups](/zh-CN/channels/groups)
## Dashboard 控制 UI 连接性
## Dashboard 控制 UI 连接问题
当 dashboard / 控制 UI 无法连接时，请验证 URL、认证模式和安全上下文假设。
当 dashboard/控制 UI 无法连接时，请验证 URL、认证模式和安全上下文相关假设。
```bash
openclaw gateway status
@ -152,33 +152,33 @@ openclaw gateway status --json
检查以下内容：
- 正确的探测 URL 和 dashboard URL。
- 客户端与 Gateway 网关之间的认证模式 / token 是否不匹配。
- 在需要设备身份时是否仍在使用 HTTP。
- 客户端与 Gateway 网关之间的认证模式/token 不匹配。
- 在需要设备身份的情况下使用了 HTTP。
常见特征：
- `device identity required` → 非安全上下文或缺少设备认证。
- `origin not allowed` → 浏览器的 `Origin` 不在 `gateway.controlUi.allowedOrigins` 中（或者你正从非 loopback 的浏览器来源连接，但没有显式允许列表）。
- `device nonce required` / `device nonce mismatch` → 客户端没有完成基于挑战的设备认证流程（`connect.challenge` + `device.nonce`）。
- `device signature invalid` / `device signature expired` → 客户端针对当前握手签署了错误的负载（或使用了过期时间戳）。
- 带有 `canRetryWithDeviceToken=true` 的 `AUTH_TOKEN_MISMATCH` → 客户端可以使用缓存的设备 token 进行一次可信重试。
- 该缓存 token 重试会复用与已配对设备 token 一起存储的缓存作用域集合。显式 `deviceToken` / 显式 `scopes` 调用方则保留自己请求的作用域集合。
- 在该重试路径之外，连接认证优先级为：显式共享 token / password 优先，其次是显式 `deviceToken`，然后是存储的设备 token，最后是 bootstrap token。
- 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, ip}` 的失败尝试会在限流器记录失败前被串行化。因此，同一客户端的两个并发错误重试中，第二次可能会显示 `retry later`，而不是两个普通的不匹配。
- 来自浏览器来源 loopback 客户端的 `too many failed authentication attempts (retry later)` → 来自同一标准化 `Origin` 的重复失败会被暂时锁定；另一个 localhost 来源会使用单独的桶。
- 在该重试之后仍重复出现 `unauthorized` → 共享 token / 设备 token 已漂移；如有需要，请刷新 token 配置并重新批准 / 轮换设备 token。
- `gateway connect failed:` → 主机 / 端口 / URL 目标错误。
- `device identity required` → 非安全上下文，或缺少设备认证。
- `origin not allowed` → 浏览器的 `Origin` 不在 `gateway.controlUi.allowedOrigins` 中（或者你正从非 loopback 的浏览器 origin 连接，但没有显式 allowlist）。
- `device nonce required` / `device nonce mismatch` → 客户端未完成基于挑战的设备认证流程（`connect.challenge` + `device.nonce`）。
- `device signature invalid` / `device signature expired` → 客户端为当前握手签署了错误的载荷（或使用了过期时间戳）。
- 带有 `canRetryWithDeviceToken=true` 的 `AUTH_TOKEN_MISMATCH` → 客户端可以使用缓存的设备 token 执行一次可信重试。
- 该缓存 token 重试会复用与已配对设备 token 一起存储的缓存 scope 集合。显式 `deviceToken` / 显式 `scopes` 调用方则保留它们请求的 scope 集合。
- 在该重试路径之外，连接认证优先级为：显式共享 token/password 优先，然后是显式 `deviceToken`，再然后是存储的设备 token，最后是 bootstrap token。
- 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, ip}` 的失败尝试会在限流器记录失败之前被串行化。因此，同一客户端的两个并发错误重试中，第二次可能会显示 `retry later`，而不是两个普通的不匹配错误。
- 来自浏览器 origin 的 loopback 客户端如果出现 `too many failed authentication attempts (retry later)` → 来自同一归一化 `Origin` 的重复失败会被暂时锁定；另一个 localhost origin 会使用单独的桶。
- 在那次重试之后反复出现 `unauthorized` → 共享 token/设备 token 已漂移；如有需要，请刷新 token 配置并重新批准/轮换设备 token。
- `gateway connect failed:` → 主机/端口/URL 目标错误。
### 认证详细代码速查表
### 认证细节代码速查表
使用失败 `connect` 响应中的 `error.details.code` 选择下一步操作：
使用失败的 `connect` 响应中的 `error.details.code` 来选择下一步操作：
| 详细代码 | 含义 | 建议操作 |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `AUTH_TOKEN_MISSING` | 客户端未发送必需的共享 token。 | 在客户端中粘贴 / 设置 token 后重试。对于 dashboard 路径：`openclaw config get gateway.auth.token`，然后将其粘贴到 Control UI 设置中。 |
| `AUTH_TOKEN_MISMATCH` | 共享 token 与 Gateway 网关认证 token 不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许一次可信重试。缓存 token 重试会复用已存储且已批准的作用域；显式 `deviceToken` / `scopes` 调用方会保留请求的作用域。若仍失败，请运行 [token 漂移恢复清单](/zh-CN/cli/devices#token-drift-recovery-checklist)。 |
| `AUTH_DEVICE_TOKEN_MISMATCH` | 每设备缓存 token 已过期或已被撤销。 | 使用 [devices CLI](/zh-CN/cli/devices) 轮换 / 重新批准设备 token，然后重新连接。 |
| `PAIRING_REQUIRED` | 设备身份需要批准。检查 `error.details.reason`，其值可能为 `not-paired`、`scope-upgrade`、`role-upgrade` 或 `metadata-upgrade`，并在存在时使用 `requestId` / `remediationHint`。 | 批准待处理请求：`openclaw devices list`，然后 `openclaw devices approve <requestId>`。在你审查所请求的访问权限后，作用域 / 角色升级也使用同样的流程。 |
| 细节代码 | 含义 | 建议操作 |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_TOKEN_MISSING` | 客户端未发送所需的共享 token。 | 在客户端中粘贴/设置 token 并重试。对于 dashboard 路径：`openclaw config get gateway.auth.token`，然后将其粘贴到 Control UI 设置中。 |
| `AUTH_TOKEN_MISMATCH` | 共享 token 与 Gateway 网关认证 token 不匹配。 | 如果 `canRetryWithDeviceToken=true`，允许一次可信重试。缓存 token 重试会复用已存储、已批准的 scope；显式 `deviceToken` / `scopes` 调用方保留其请求的 scope。如果仍然失败，请运行 [token 漂移恢复检查清单](/zh-CN/cli/devices#token-drift-recovery-checklist)。 |
| `AUTH_DEVICE_TOKEN_MISMATCH` | 缓存的每设备 token 已过期或被撤销。 | 使用 [devices CLI](/zh-CN/cli/devices) 轮换/重新批准设备 token，然后重新连接。 |
| `PAIRING_REQUIRED` | 设备身份需要批准。检查 `error.details.reason`，可能的值包括 `not-paired`、`scope-upgrade`、`role-upgrade` 或 `metadata-upgrade`，并在存在时使用 `requestId` / `remediationHint`。 | 批准待处理请求：`openclaw devices list`，然后 `openclaw devices approve <requestId>`。Scope/角色升级在你审查所请求的访问权限后，也使用同一流程。 |
设备认证 v2 迁移检查：
@ -188,16 +188,16 @@ openclaw doctor
openclaw gateway status
```
如果日志显示 nonce / signature 错误，请更新正在连接的客户端并验证它是否：
如果日志显示 nonce/signature 错误，请更新发起连接的客户端并验证它：
1. 等待 `connect.challenge`
2. 对绑定挑战的负载进行签名
3. 发送 `connect.params.device.nonce`，并且使用相同的 challenge nonce
2. 对绑定该 challenge 的载荷进行签名
3. 使用同一个 challenge nonce 发送 `connect.params.device.nonce`
如果 `openclaw devices rotate` / `revoke` / `remove` 被意外拒绝：
- 已配对设备 token 会话只能管理**其自身**设备，除非调用方同时具有 `operator.admin`
- `openclaw devices rotate --scope ...` 只能请求调用方当前会话已经持有的 operator 作用域
- 已配对设备 token 会话只能管理**它们自己的**设备，除非调用方还具有 `operator.admin`
- `openclaw devices rotate --scope ...` 只能请求调用方当前会话已持有的 operator scope
相关内容：
@ -209,30 +209,30 @@ openclaw gateway status
## Gateway 网关服务未运行
当服务已安装但进程无法持续运行时，使用本节。
当服务已安装但进程无法保持运行时，使用本节。
```bash
openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep # 也会扫描系统级服务
openclaw gateway status --deep # 也扫描系统级服务
```
检查以下内容：
- 带退出提示的 `Runtime: stopped`。
- `Runtime: stopped`，并带有退出提示。
- 服务配置不匹配（`Config (cli)` 与 `Config (service)`）。
- 端口 / 监听器冲突。
- 使用 `--deep` 时出现额外的 launchd / systemd / schtasks 安装。
- 端口/监听器冲突。
- 使用 `--deep` 时发现额外的 launchd/systemd/schtasks 安装。
- `Other gateway-like services detected (best effort)` 清理提示。
常见特征：
- `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → 未启用本地 Gateway 网关模式，或者配置文件被覆盖导致丢失了 `gateway.mode`。修复方法：在你的配置中设置 `gateway.mode="local"`，或重新运行 `openclaw onboard --mode local` / `openclaw setup` 以重新写入预期的本地模式配置。如果你通过 Podman 运行 OpenClaw，默认配置路径是 `~/.openclaw/openclaw.json`。
- `refusing to bind gateway ... without auth` → 在没有有效 Gateway 网关认证路径的情况下绑定到非 loopback 地址（token / password，或已配置的 trusted-proxy）。
- `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → 未启用本地 Gateway 网关模式，或者配置文件被破坏并丢失了 `gateway.mode`。修复方式：在你的配置中设置 `gateway.mode="local"`，或重新运行 `openclaw onboard --mode local` / `openclaw setup` 以重新写入预期的本地模式配置。如果你通过 Podman 运行 OpenClaw，默认配置路径是 `~/.openclaw/openclaw.json`。
- `refusing to bind gateway ... without auth` → 在没有有效 Gateway 网关认证路径的情况下尝试绑定非 loopback 地址（token/password，或在已配置时使用 trusted-proxy）。
- `another gateway instance is already listening` / `EADDRINUSE` → 端口冲突。
- `Other gateway-like services detected (best effort)` → 存在过期或并行的 launchd / systemd / schtasks 单元。大多数部署应当每台机器只保留一个 Gateway 网关；如果你确实需要多个，请隔离端口 + 配置 / 状态 / 工作区。参见 [/gateway#multiple-gateways-same-host](/zh-CN/gateway#multiple-gateways-same-host)。
- `Other gateway-like services detected (best effort)` → 存在过期或并行的 launchd/systemd/schtasks 单元。大多数配置应当每台机器只保留一个 Gateway 网关；如果你确实需要多个，请隔离端口 + 配置/状态/工作区。参见 [/gateway#multiple-gateways-same-host](/zh-CN/gateway#multiple-gateways-same-host)。
相关内容：
@ -240,9 +240,9 @@ openclaw gateway status --deep # 也会扫描系统级服务
- [/gateway/configuration](/zh-CN/gateway/configuration)
- [/gateway/doctor](/zh-CN/gateway/doctor)
## Gateway 网关恢复了最后已知正常配置
## Gateway 网关已恢复最近一次已知正常配置
当 Gateway 网关能够启动，但日志显示它恢复了 `openclaw.json` 时，使用本节。
当 Gateway 网关可以启动，但日志显示它恢复了 `openclaw.json` 时，使用本节。
```bash
openclaw logs --follow
@ -256,15 +256,16 @@ openclaw doctor
- `Config auto-restored from last-known-good`
- `gateway: invalid config was restored from last-known-good backup`
- `config reload restored last-known-good config after invalid-config`
- 活动配置旁边是否存在带时间戳的 `openclaw.json.clobbered.*` 文件
- 以 `Config recovery warning` 开头的主智能体系统事件
- 在活动配置旁边是否存在带时间戳的 `openclaw.json.clobbered.*` 文件
- 是否有一个主智能体系统事件以 `Config recovery warning` 开头
发生了什么：
- 被拒绝的配置在启动或热重载期间未通过校验。
- OpenClaw 将被拒绝的负载保留为 `.clobbered.*`。
- 活动配置已从最后一次通过校验的最后已知正常副本中恢复。
- 下一次主智能体轮次会收到警告，不要盲目重写该被拒绝的配置。
- OpenClaw 将被拒绝的载荷保留为 `.clobbered.*`。
- 活动配置已从最近一次通过校验的 last-known-good 副本中恢复。
- 下一次主智能体轮次会收到警告，不要盲目重写被拒绝的配置。
- 如果所有校验问题都位于 `plugins.entries.<id>...` 下，OpenClaw 将不会恢复整个文件。插件本地失败会继续显式报错，而无关的用户设置会保留在活动配置中。
检查并修复：
@ -278,18 +279,18 @@ openclaw doctor
常见特征：
- 存在 `.clobbered.*` → 外部直接编辑或启动读取已被恢复。
- 存在 `.rejected.*` → 一次由 OpenClaw 发起的配置写入在提交前因 schema 或覆盖检查失败。
- 存在 `.clobbered.*` → 外部直接编辑或启动读取时的内容已被恢复。
- 存在 `.rejected.*` → OpenClaw 自身发起的配置写入在提交前未通过 schema 或 clobber 检查。
- `Config write rejected:` → 该写入尝试删除必需结构、显著缩小文件，或持久化无效配置。
- `missing-meta-vs-last-good`、`gateway-mode-missing-vs-last-good` 或 `size-drop-vs-last-good:*` → 启动时将当前文件视为已被覆盖，因为与最后已知正常备份相比，它丢失了字段或大小发生了下降。
- `Config last-known-good promotion skipped` → 候选配置包含已打码的 secret 占位符，例如 `***`。
- `missing-meta-vs-last-good`、`gateway-mode-missing-vs-last-good` 或 `size-drop-vs-last-good:*` → 启动时将当前文件视为已被破坏，因为与 last-known-good 备份相比，它丢失了字段或文件大小明显变小。
- `Config last-known-good promotion skipped` → 候选内容中包含被脱敏的 secret 占位符，例如 `***`。
修复选项：
1. 如果恢复后的活动配置是正确的，就保留它。
2. 只从 `.clobbered.*` 或 `.rejected.*` 复制你真正想要的键，然后使用 `openclaw config set` 或 `config.patch` 应用。
3. 重启前运行 `openclaw config validate`。
4. 如果你手动编辑，请保留完整的 JSON5 配置，而不是只保留你想改动的局部对象。
2. 仅从 `.clobbered.*` 或 `.rejected.*` 中复制你真正想要的键，然后通过 `openclaw config set` 或 `config.patch` 应用它们。
3. 在重启之前运行 `openclaw config validate`。
4. 如果你手动编辑，请保留完整的 JSON5 配置，而不仅仅是你想更改的局部对象。
相关内容：
@ -300,7 +301,7 @@ openclaw doctor
## Gateway 网关探测警告
当 `openclaw gateway probe` 能探测到目标，但仍打印警告块时，使用本节。
当 `openclaw gateway probe` 能探测到目标，但仍然打印警告块时，使用本节。
```bash
openclaw gateway probe
@ -311,15 +312,15 @@ openclaw gateway probe --ssh user@gateway-host
检查以下内容：
- JSON 输出中的 `warnings[].code` 和 `primaryTargetId`。
- 警告是否与 SSH 回退、多个 Gateway 网关、缺少作用域或未解析的认证引用有关。
- 该警告是否与 SSH 回退、多个 Gateway 网关、缺少 scope，或未解析的认证引用有关。
常见特征：
- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但命令仍尝试了直接的已配置 / loopback 目标。
- `multiple reachable gateways detected` → 有多个目标作出响应。通常意味着有意的多 Gateway 网关部署，或存在过期 / 重复的监听器。
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接成功，但详细 RPC 受作用域限制；请配对设备身份或使用具有 `operator.read` 的凭证。
- `Capability: pairing-pending` 或 `gateway closed (1008): pairing required` → Gateway 网关已响应，但该客户端在获得正常 operator 访问前仍需配对 / 批准。
- 未解析的 `gateway.auth.*` / `gateway.remote.*` SecretRef 警告文本 → 在该命令路径中，失败目标的认证材料不可用。
- `SSH tunnel failed to start; falling back to direct probes.` → SSH 设置失败，但命令仍尝试了直接配置的目标/loopback 目标。
- `multiple reachable gateways detected` → 有多个目标作出响应。通常这意味着有意配置了多个 Gateway 网关，或者存在过期/重复的监听器。
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → 连接成功了，但详细 RPC 受 scope 限制；请配对设备身份，或使用具有 `operator.read` 的凭证。
- `Capability: pairing-pending` 或 `gateway closed (1008): pairing required` → Gateway 网关已响应，但此客户端在获得正常 operator 访问权限之前仍需要配对/批准。
- 未解析的 `gateway.auth.*` / `gateway.remote.*` SecretRef 警告文本 → 在此命令路径中，失败目标所需的认证材料不可用。
相关内容：
@ -327,9 +328,9 @@ openclaw gateway probe --ssh user@gateway-host
- [/gateway#multiple-gateways-same-host](/zh-CN/gateway#multiple-gateways-same-host)
- [/gateway/remote](/zh-CN/gateway/remote)
## 渠道已连接但消息未流动
## 渠道已连接但消息不流转
如果渠道状态为已连接，但消息流完全停止，请重点检查策略、权限和渠道特定的投递规则。
如果渠道状态显示已连接，但消息流转中断，请重点检查策略、权限和渠道特有的投递规则。
```bash
openclaw channels status --probe
@ -342,14 +343,14 @@ openclaw config get channels
检查以下内容：
- 私信策略（`pairing`、`allowlist`、`open`、`disabled`）。
- 群组允许列表和提及要求。
- 缺失的渠道 API 权限 / scopes。
- 群组 allowlist 和提及要求。
- 缺失的渠道 API 权限/scope。
常见特征：
- `mention required` → 消息因群组提及策略而被忽略。
- `mention required` → 消息被群组提及策略忽略。
- `pairing` / 待批准痕迹 → 发送者尚未获批。
- `missing_scope`、`not_in_channel`、`Forbidden`、`401/403` → 渠道认证 / 权限问题。
- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → 渠道认证/权限问题。
相关内容：
@ -358,9 +359,9 @@ openclaw config get channels
- [/channels/telegram](/zh-CN/channels/telegram)
- [/channels/discord](/zh-CN/channels/discord)
## Cron 和心跳投递
## Cron 和 heartbeat 投递
如果 cron 或心跳未运行或未投递，请先验证调度器状态，再检查投递目标。
如果 cron 或 heartbeat 未运行或未投递，请先验证调度器状态，再检查投递目标。
```bash
openclaw cron status
@ -374,17 +375,17 @@ openclaw logs --follow
- Cron 已启用，且存在下一次唤醒时间。
- 作业运行历史状态（`ok`、`skipped`、`error`）。
- 心跳跳过原因（`quiet-hours`、`requests-in-flight`、`alerts-disabled`、`empty-heartbeat-file`、`no-tasks-due`）。
- Heartbeat 跳过原因（`quiet-hours`、`requests-in-flight`、`alerts-disabled`、`empty-heartbeat-file`、`no-tasks-due`）。
常见特征：
- `cron: scheduler disabled; jobs will not run automatically` → cron 已禁用。
- `cron: timer tick failed` → 调度器 tick 失败；请检查文件 / 日志 / 运行时错误。
- `heartbeat skipped` 且 `reason=quiet-hours` → 当前处于活跃时间窗口之外。
- `heartbeat skipped` 且 `reason=empty-heartbeat-file` → `HEARTBEAT.md` 存在，但只包含空行 / markdown 标题，因此 OpenClaw 会跳过模型调用。
- `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 包含 `tasks:` 块，但本次 tick 没有任何任务到期。
- `heartbeat: unknown accountId` → 心跳投递目标的账户 id 无效。
- `heartbeat skipped` 且 `reason=dm-blocked` → 心跳目标被解析为私信式目标，而 `agents.defaults.heartbeat.directPolicy`（或每个智能体的覆盖设置）被设为 `block`。
- `cron: timer tick failed` → 调度器 tick 失败；请检查文件/日志/运行时错误。
- `heartbeat skipped` 且 `reason=quiet-hours` → 当前在活跃时段窗口之外。
- `heartbeat skipped` 且 `reason=empty-heartbeat-file` → `HEARTBEAT.md` 存在，但只包含空行 / Markdown 标题，因此 OpenClaw 会跳过模型调用。
- `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 包含一个 `tasks:` 块，但本次 tick 没有任何任务到期。
- `heartbeat: unknown accountId` → heartbeat 投递目标的账号 id 无效。
- `heartbeat skipped` 且 `reason=dm-blocked` → heartbeat 目标被解析为私信风格的目标，而 `agents.defaults.heartbeat.directPolicy`（或每个智能体的覆盖配置）被设置为 `block`。
相关内容：
@ -394,7 +395,7 @@ openclaw logs --follow
## 已配对节点的工具失败
如果节点已配对，但工具仍失败，请隔离前台状态、权限和批准状态。
如果节点已配对但工具失败，请分别排查前台状态、权限和批准状态。
```bash
openclaw nodes status
@ -406,16 +407,16 @@ openclaw status
检查以下内容：
- 节点在线，并具备预期能力。
- 相机 / 麦克风 / 定位 / 屏幕的操作系统权限授予情况。
- Exec 批准和允许列表状态。
- 节点在线，并具有预期能力。
- 相机/麦克风/定位/屏幕的操作系统权限授权。
- Exec 批准和 allowlist 状态。
常见特征：
- `NODE_BACKGROUND_UNAVAILABLE` → 节点应用必须处于前台。
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → 缺少操作系统权限。
- `SYSTEM_RUN_DENIED: approval required` → Exec 批准待处理。
- `SYSTEM_RUN_DENIED: allowlist miss` → 命令被允许列表拦截。
- `SYSTEM_RUN_DENIED: allowlist miss` → 命令被 allowlist 阻止。
相关内容：
@ -425,7 +426,7 @@ openclaw status
## 浏览器工具失败
当 Gateway 网关本身健康，但浏览器工具操作仍失败时，使用本节。
当浏览器工具操作失败，但 Gateway 网关本身健康时，使用本节。
```bash
openclaw browser status
@ -437,44 +438,44 @@ openclaw doctor
检查以下内容：
- 是否设置了 `plugins.allow`，且其中包含 `browser`。
- 是否设置了 `plugins.allow`，并且其中包含 `browser`。
- 浏览器可执行文件路径是否有效。
- CDP 配置文件是否可达。
- 对于 `existing-session` / `user` 配置文件，本地 Chrome 是否可用。
- `existing-session` / `user` 配置文件所需的本地 Chrome 是否可用。
常见特征：
- `unknown command "browser"` 或 `unknown command 'browser'` → 内置 browser 插件被 `plugins.allow` 排除。
- 在 `browser.enabled=true` 时 browser 工具仍缺失 / 不可用 → `plugins.allow` 排除了 `browser`，因此插件根本没有加载。
- `unknown command "browser"` 或 `unknown command 'browser'` → 内置的浏览器插件被 `plugins.allow` 排除了。
- 在 `browser.enabled=true` 的情况下，浏览器工具缺失/不可用 → `plugins.allow` 排除了 `browser`，因此插件根本没有加载。
- `Failed to start Chrome CDP on port` → 浏览器进程启动失败。
- `browser.executablePath not found` → 配置的路径无效。
- `browser.cdpUrl must be http(s) or ws(s)` → 配置的 CDP URL 使用了不受支持的协议，例如 `file:` 或 `ftp:`。
- `browser.cdpUrl has invalid port` → 配置的 CDP URL 端口无效或超出范围。
- `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session 尚无法附加到所选浏览器数据目录。请打开浏览器检查页面，启用远程调试，保持浏览器开启，批准首次附加提示，然后重试。如果不需要登录状态，优先使用受管的 `openclaw` 配置文件。
- `browser.cdpUrl has invalid port` → 配置的 CDP URL 端口错误或超出范围。
- `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session 还无法附加到所选浏览器数据目录。打开浏览器检查页面，启用远程调试，保持浏览器开启，批准第一次附加提示，然后重试。如果不需要已登录状态，优先使用托管的 `openclaw` 配置文件。
- `No Chrome tabs found for profile="user"` → Chrome MCP 附加配置文件没有打开的本地 Chrome 标签页。
- `Remote CDP for profile "<name>" is not reachable` → 配置的远程 CDP 端点从 Gateway 网关主机不可达。
- `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加配置文件没有可达目标，或者 HTTP 端点已响应，但 CDP WebSocket 仍无法打开。
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → 当前 Gateway 网关安装缺少内置 browser 插件所需的 `playwright-core` 运行时依赖；请运行 `openclaw doctor --fix`，然后重启 Gateway 网关。ARIA 快照和基础页面截图仍然可用，但导航、AI 快照、基于 CSS 选择器的元素截图和 PDF 导出仍不可用。
- `fullPage is not supported for element screenshots` → 截图请求将 `--full-page` 与 `--ref` 或 `--element` 混用。
- `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加配置文件没有可达目标，或者 HTTP 端点已有响应，但 CDP WebSocket 仍无法打开。
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → 当前 Gateway 网关安装缺少内置浏览器插件所需的 `playwright-core` 运行时依赖；运行 `openclaw doctor --fix`，然后重启 Gateway 网关。ARIA 快照和基础页面截图仍可工作，但导航、AI 快照、基于 CSS 选择器的元素截图以及 PDF 导出仍不可用。
- `fullPage is not supported for element screenshots` → 截图请求同时混用了 `--full-page` 和 `--ref` 或 `--element`。
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → Chrome MCP / `existing-session` 截图调用必须使用页面捕获或快照 `--ref`，不能使用 CSS `--element`。
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP 上传钩子需要使用快照 ref，而不是 CSS 选择器。
- `existing-session file uploads currently support one file at a time.` → 在 Chrome MCP 配置文件上，每次调用只能发送一个上传文件。
- `existing-session dialog handling does not support timeoutMs.` → Chrome MCP 配置文件上的对话框钩子不支持超时覆盖。
- `existing-session type does not support timeoutMs overrides.` → 对 `profile="user"` / Chrome MCP existing-session 配置文件上的 `act:type`，请省略 `timeoutMs`，或者在需要自定义超时时使用受管 / CDP 浏览器配置文件。
- `existing-session evaluate does not support timeoutMs overrides.` → 对 `profile="user"` / Chrome MCP existing-session 配置文件上的 `act:evaluate`，请省略 `timeoutMs`，或者在需要自定义超时时使用受管 / CDP 浏览器配置文件。
- `response body is not supported for existing-session profiles yet.` → `responsebody` 目前仍需要受管浏览器或原始 CDP 配置文件。
- attach-only 或远程 CDP 配置文件上的陈旧 viewport / dark-mode / locale / offline 覆盖状态 → 运行 `openclaw browser stop --browser-profile <name>` 以关闭活动控制会话，并释放 Playwright / CDP 仿真状态，而无需重启整个 Gateway 网关。
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → Chrome MCP 文件上传钩子需要使用快照引用，而不是 CSS 选择器。
- `existing-session file uploads currently support one file at a time.` → 在 Chrome MCP 配置文件上，每次调用只发送一个上传文件。
- `existing-session dialog handling does not support timeoutMs.` → Chrome MCP 配置文件上的对话框钩子不支持 `timeoutMs` 覆盖。
- `existing-session type does not support timeoutMs overrides.` → 对 `profile="user"` / Chrome MCP existing-session 配置文件上的 `act:type`，不要传 `timeoutMs`，或者在需要自定义超时时使用托管/CDP 浏览器配置文件。
- `existing-session evaluate does not support timeoutMs overrides.` → 对 `profile="user"` / Chrome MCP existing-session 配置文件上的 `act:evaluate`，不要传 `timeoutMs`，或者在需要自定义超时时使用托管/CDP 浏览器配置文件。
- `response body is not supported for existing-session profiles yet.` → `responsebody` 目前仍需要托管浏览器或原始 CDP 配置文件。
- attach-only 或远程 CDP 配置文件上的陈旧 viewport / dark-mode / locale / offline 覆盖状态 → 运行 `openclaw browser stop --browser-profile <name>` 关闭活动控制会话并释放 Playwright/CDP 模拟状态，而无需重启整个 Gateway 网关。
相关内容：
- [/tools/browser-linux-troubleshooting](/zh-CN/tools/browser-linux-troubleshooting)
- [/tools/browser](/zh-CN/tools/browser)
## 如果你升级后突然出现故障
## 如果你升级后突然出现问题
大多数升级后的故障都源于配置漂移，或现在开始强制执行更严格的默认值。
大多数升级后的故障，都是配置漂移，或者现在开始强制执行更严格的默认值。
### 1) 认证和 URL 覆盖行为已更改
### 1) 认证和 URL 覆盖行为发生了变化
```bash
openclaw gateway status
@ -483,9 +484,9 @@ openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode
```
检查内容：
要检查的内容：
- 如果 `gateway.mode=remote`，CLI 调用可能会指向远程端，而你的本地服务其实正常。
- 如果 `gateway.mode=remote`，CLI 调用可能正在访问远程目标，而你的本地服务其实是正常的。
- 显式 `--url` 调用不会回退到已存储的凭证。
常见特征：
@ -493,7 +494,7 @@ openclaw config get gateway.auth.mode
- `gateway connect failed:` → URL 目标错误。
- `unauthorized` → 端点可达，但认证错误。
### 2) 绑定和认证护栏更严格了
### 2) 绑定和认证防护规则更加严格
```bash
openclaw config get gateway.bind
@ -503,17 +504,17 @@ openclaw gateway status
openclaw logs --follow
```
检查内容：
要检查的内容：
- 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 Gateway 网关认证路径：共享 token / password 认证，或正确配置的非 loopback `trusted-proxy` 部署。
- 旧键如 `gateway.token` 不能替代 `gateway.auth.token`。
- 非 loopback 绑定（`lan`、`tailnet`、`custom`）需要有效的 Gateway 网关认证路径：共享 token/password 认证，或者正确配置的非 loopback `trusted-proxy` 部署。
- 旧键名如 `gateway.token` 不能替代 `gateway.auth.token`。
常见特征：
- `refusing to bind gateway ... without auth` → 非 loopback 绑定缺少有效的 Gateway 网关认证路径。
- 在运行时已启动的情况下出现 `Connectivity probe: failed` → Gateway 网关存活，但无法通过当前 auth / url 访问。
- `refusing to bind gateway ... without auth` → 非 loopback 绑定没有有效的 Gateway 网关认证路径。
- 当运行时已启动，但 `Connectivity probe: failed` → Gateway 网关存活，但使用当前 auth/url 无法访问。
### 3) 配对和设备身份状态已更改
### 3) 配对和设备身份状态发生了变化
```bash
openclaw devices list
@ -522,17 +523,17 @@ openclaw logs --follow
openclaw doctor
```
检查内容：
要检查的内容：
- dashboard / 节点是否存在待批准的设备审批。
- 在策略或身份变更后，私信是否存在待批准的配对请求。
- dashboard/节点是否存在待处理的设备批准。
- 在策略或身份变更后，是否存在待处理的私信配对批准。
常见特征：
- `device identity required` → 设备认证未满足。
- `pairing required` → 发送者 / 设备必须先获批。
- `pairing required` → 发送者/设备必须先获批。
如果检查后服务配置和运行时仍不一致，请从同一 profile / 状态目录重新安装服务元数据：
如果检查后服务配置和运行时仍然不一致，请从同一个 profile/状态目录重新安装服务元数据：
```bash
openclaw gateway install --force

153
docs/zh-CN/platforms/macos.md
View File

@ -1,90 +1,84 @@
---
read_when:
- 实现 macOS 应用功能
- 更改 macOS 上的 Gateway 网关生命周期或节点桥接 аиҳабы to=final code omitted
- 更改 macOS 上的 Gateway 网关生命周期或节点桥接
summary: OpenClaw macOS 配套应用（菜单栏 + Gateway 网关代理）
title: macOS 应用
x-i18n:
generated_at: "2026-04-23T20:56:17Z"
generated_at: "2026-04-25T03:24:36Z"
model: gpt-5.4
provider: openai
source_hash: 6c7911d0a2e7be7fa437c5ef01a98c0f7da5e44388152ba182581cd2e381ba8b
source_hash: 852c93694ebb4ac083b9a44c2e4d6e40274e6e7f3aa6fa664a8eba1a82aaf5b1
source_path: platforms/macos.md
workflow: 15
---
macOS 应用是 OpenClaw 的**菜单栏配套应用**。它负责权限管理，
在本地管理/附加到 Gateway 网关（launchd 或手动），并将 macOS
能力作为节点暴露给智能体。
macOS 应用是 OpenClaw 的**菜单栏配套应用**。它负责权限管理，在本地管理/连接 Gateway 网关（`launchd` 或手动），并将 macOS 能力作为一个节点暴露给智能体。
## 它能做什么
## 它的作用
- 在菜单栏中显示原生通知和状态。
- 持有 TCC 提示（通知、辅助功能、屏幕录制、麦克风、
语音识别、自动化/AppleScript）。
- 负责 TCC 提示（通知、辅助功能、屏幕录制、麦克风、语音识别、自动化 / AppleScript）。
- 运行或连接到 Gateway 网关（本地或远程）。
- 暴露仅限 macOS 的工具（Canvas、Camera、Screen Recording、`system.run`）。
- 在**远程**模式下启动本地节点主机服务（launchd），并在**本地**模式下停止它。
- 可选托管 **PeekabooBridge**，用于 UI 自动化。
- 按需通过 npm、pnpm 或 bun 安装全局 CLI（`openclaw`）（应用优先使用 npm，然后 pnpm，再然后 bun；Node 仍然是推荐的 Gateway 网关运行时）。
- 以**远程**模式启动本地节点宿主服务（`launchd`），并以**本地**模式停止它。
- 可选择托管 **PeekabooBridge** 用于 UI 自动化。
- 可按需通过 npm、pnpm 或 bun 安装全局 CLI（`openclaw`）（应用优先使用 npm，其次是 pnpm，再其次是 bun；Node 仍是推荐的 Gateway 网关运行时）。
## 本地模式与远程模式
- **本地**（默认）：如果存在正在运行的本地 Gateway 网关，应用会附加到它；
否则会通过 `openclaw gateway install` 启用 launchd 服务。
- **远程**：应用通过 SSH/Tailscale 连接到 Gateway 网关，且绝不会启动
本地进程。
应用会启动本地的**节点主机服务**，这样远程 Gateway 网关就可以访问这台 Mac。
应用不会把 Gateway 网关作为子进程拉起。
Gateway 网关发现现在会优先使用 Tailscale MagicDNS 名称，而不是原始 tailnet IP，
因此当 tailnet IP 发生变化时，Mac 应用恢复得更可靠。
- **本地**（默认）：如果存在正在运行的本地 Gateway 网关，应用会附加到它；否则会通过 `openclaw gateway install` 启用 `launchd` 服务。
- **远程**：应用通过 SSH/Tailscale 连接到一个 Gateway 网关，且绝不会启动本地进程。
应用会启动本地**节点宿主服务**，以便远程 Gateway 网关可以访问这台 Mac。
应用不会将 Gateway 网关作为子进程生成。
Gateway 网关发现现在会优先使用 Tailscale MagicDNS 名称，而不是原始 tailnet IP，因此当 tailnet IP 变化时，Mac 应用能更可靠地恢复连接。
## Launchd 控制
应用会管理一个按用户划分的 LaunchAgent，标签为 `ai.openclaw.gateway`
（当使用 `--profile`/`OPENCLAW_PROFILE` 时为 `ai.openclaw.<profile>`；旧版 `com.openclaw.*` 仍可卸载）。
应用管理一个按用户区分的 LaunchAgent，标签为 `ai.openclaw.gateway`
（或在使用 `--profile`/`OPENCLAW_PROFILE` 时为 `ai.openclaw.<profile>`；旧版 `com.openclaw.*` 仍会被卸载）。
```bash
launchctl kickstart -k gui/$UID/ai.openclaw.gateway
launchctl bootout gui/$UID/ai.openclaw.gateway
```
如果使用的是具名 profile，请将标签替换为 `ai.openclaw.<profile>`。
如果你运行的是命名 profile，请将标签替换为 `ai.openclaw.<profile>`。
如果 LaunchAgent 尚未安装，请从应用中启用它，或运行
如果尚未安装 LaunchAgent，请在应用中启用它，或运行
`openclaw gateway install`。
## 节点能力（mac）
macOS 应用会将自己呈现为一个节点。常见命令：
macOS 应用将自己呈现为一个节点。常见命令：
- Canvas：`canvas.present`、`canvas.navigate`、`canvas.eval`、`canvas.snapshot`、`canvas.a2ui.*`
- Camera：`camera.snap`、`camera.clip`
- Screen：`screen.snapshot`、`screen.record`
- System：`system.run`、`system.notify`
该节点会上报一个 `permissions` 映射，以便智能体判断哪些操作被允许。
该节点会报告一个 `permissions` 映射，以便智能体决定哪些操作被允许。
节点服务 + 应用 IPC：
- 当无头节点主机服务正在运行（远程模式）时，它会作为节点连接到 Gateway 网关 WS。
- `system.run` 会在 macOS 应用中执行（UI/TCC 上下文），通过本地 Unix 套接字；提示和输出都保留在应用内。
- 当无头节点宿主服务运行时（远程模式），它会作为一个节点连接到 Gateway 网关 WS。
- `system.run` 在 macOS 应用中执行（UI/TCC 上下文），通过本地 Unix socket；提示和输出都保留在应用内。
图示（SCI）：
```
```text
Gateway -> Node Service (WS)
| IPC (UDS + token + HMAC + TTL)
v
Mac App (UI + TCC + system.run)
```
## Exec 审批（`system.run`）
## Exec approvals（system.run）
`system.run` 由 macOS 应用中的**Exec 审批**控制（Settings → Exec approvals）。
安全性 + 询问策略 + 允许列表会本地存储在 Mac 上：
`system.run` 由 macOS 应用中的 **Exec approvals** 控制（设置 → Exec approvals）。
安全策略 + 询问策略 + allowlist 存储在 Mac 本地：
```
```text
~/.openclaw/exec-approvals.json
```
@ -109,24 +103,24 @@ Gateway -> Node Service (WS)
说明：
- `allowlist` 条目是针对已解析二进制路径的 glob 模式。
- 含有 shell 控制或展开语法（`&&`、`||`、`;`、`|`、`` ` ``、`$`、`<`、`>`、`(`、`)`）的原始 shell 命令文本会被视为允许列表未命中，因此需要显式批准（或将 shell 二进制加入允许列表）。
- 在提示中选择 “Always Allow” 会将该命令添加到允许列表。
- `system.run` 的环境变量覆盖项会被过滤（会丢弃 `PATH`、`DYLD_*`、`LD_*`、`NODE_OPTIONS`、`PYTHON*`、`PERL*`、`RUBYOPT`、`SHELLOPTS`、`PS4`），然后与应用环境合并。
- 对于 shell 包装器（`bash|sh|zsh ... -c/-lc`），请求作用域内的环境变量覆盖项会被缩减为一个较小的显式允许列表（`TERM`、`LANG`、`LC_*`、`COLORTERM`、`NO_COLOR`、`FORCE_COLOR`）。
- 对于允许列表模式中的“始终允许”决策，已知调度包装器（`env`、`nice`、`nohup`、`stdbuf`、`timeout`）会持久化其内部可执行路径，而不是包装器路径。如果无法安全解包，则不会自动持久化允许列表条目。
- `allowlist` 条目可以是已解析二进制路径的 glob 模式，或通过 PATH 调用命令时的裸命令名。
- 包含 shell 控制或展开语法（`&&`、`||`、`;`、`|`、`` ` ``、`$`、`<`、`>`、`(`、`)`）的原始 shell 命令文本，会被视为未命中 allowlist，并需要显式批准（或者将 shell 二进制加入 allowlist）。
- 在提示中选择“Always Allow”会将该命令加入 allowlist。
- `system.run` 的环境变量覆盖会被过滤（丢弃 `PATH`、`DYLD_*`、`LD_*`、`NODE_OPTIONS`、`PYTHON*`、`PERL*`、`RUBYOPT`、`SHELLOPTS`、`PS4`），然后与应用自身的环境变量合并。
- 对于 shell 包装器（`bash|sh|zsh ... -c/-lc`），请求范围内的环境变量覆盖会缩减为一个小型显式 allowlist（`TERM`、`LANG`、`LC_*`、`COLORTERM`、`NO_COLOR`、`FORCE_COLOR`）。
- 对于 allowlist 模式下的始终允许决策，已知的分发包装器（`env`、`nice`、`nohup`、`stdbuf`、`timeout`）会持久化其内部可执行文件路径，而不是包装器路径。如果无法安全解包，则不会自动持久化任何 allowlist 条目。
## Deep links
## 深链接
应用注册了 `openclaw://` URL scheme，用于本地操作。
应用为本地操作注册了 `openclaw://` URL scheme。
### `openclaw://agent`
会触发一次 Gateway 网关 `agent` 请求。
触发一个 Gateway 网关 `agent` 请求。
__OC_I18N_900004__
查询参数：
- `message`（必填）
- `message`（必需）
- `sessionKey`（可选）
- `thinking`（可选）
- `deliver` / `to` / `channel`（可选）
@ -135,82 +129,81 @@ __OC_I18N_900004__
安全性：
- 如果没有 `key`，应用会提示确认。
- 如果没有 `key`，应用会对确认提示中的消息长度施加较短限制，并忽略 `deliver` / `to` / `channel`。
- 如果提供有效的 `key`，则该运行是无人值守的（适用于个人自动化）。
- 没有 `key` 时，应用会提示确认。
- 没有 `key` 时，应用会对确认提示中的消息长度施加较短限制，并忽略 `deliver` / `to` / `channel`。
- 使用有效的 `key` 时，运行将以无人值守方式进行（适用于个人自动化）。
## 新手引导流程（典型）
1. 安装并启动 **OpenClaw.app**。
2. 完成权限检查清单（TCC 提示）。
3. 确保启用了**本地**模式，并且 Gateway 网关正在运行。
4. 如果你希望使用终端访问，请安装 CLI。
3. 确保**本地**模式已启用，并且 Gateway 网关正在运行。
4. 如果你想要终端访问，请安装 CLI。
## 状态目录放置（macOS）
## 状态目录放置位置（macOS）
请避免将 OpenClaw 状态目录放在 iCloud 或其他云同步文件夹中。
基于同步的路径会增加延迟，并且偶尔会对
会话和凭证造成文件锁/同步竞争。
避免将你的 OpenClaw 状态目录放在 iCloud 或其他云同步文件夹中。
由同步服务支持的路径会增加延迟，并且偶尔会为
会话和凭证导致文件锁 / 同步竞争问题。
优先使用本地的非同步状态路径，例如：
建议使用本地的非同步状态路径，例如：
__OC_I18N_900005__
如果 `openclaw doctor` 检测到状态目录位于以下路径下：
- `~/Library/Mobile Documents/com~apple~CloudDocs/...`
- `~/Library/CloudStorage/...`
它会发出警告，并建议迁移回本地路径。
它会发出警告，并建议迁回本地路径。
## 构建与开发工作流（原生）
- `cd apps/macos && swift build`
- `swift run OpenClaw`（或使用 Xcode）
- `swift run OpenClaw`（或 Xcode）
- 打包应用：`scripts/package-mac-app.sh`
## 调试 Gateway 网关连接性（macOS CLI）
## 调试 Gateway 网关连接（macOS CLI）
使用调试 CLI 可以在不启动应用的情况下，验证与 macOS 应用相同的 Gateway 网关 WebSocket 握手和发现
逻辑。
使用调试 CLI 可以在不启动应用的情况下，执行与 macOS 应用相同的 Gateway 网关 WebSocket 握手和发现逻辑。
__OC_I18N_900006__
连接选项：
- `--url <ws://host:port>`：覆盖配置
- `--mode <local|remote>`：从配置解析（默认：配置值或 local）
- `--probe`：强制执行新的健康探测
- `--probe`：强制执行一次新的健康探测
- `--timeout <ms>`：请求超时（默认：`15000`）
- `--json`：用于 diff 的结构化输出
- `--json`：用于差异比较的结构化输出
发现选项：
- `--include-local`：包括那些原本会被过滤为“local”的 Gateway 网关
- `--include-local`：包含本会被过滤为“local”的 Gateway 网关
- `--timeout <ms>`：整体发现窗口（默认：`2000`）
- `--json`：用于 diff 的结构化输出
- `--json`：用于差异比较的结构化输出
提示：可与 `openclaw gateway discover --json` 对比，查看
macOS 应用的发现流水线（`local.` 加上已配置的广域域名，并带有
广域和 Tailscale Serve 回退）是否与
Node CLI 基于 `dns-sd` 的发现不同。
提示：可与 `openclaw gateway discover --json` 的结果进行比较，以查看
macOS 应用的发现管线（`local.` 加上已配置的广域域名，并带有
广域和 Tailscale Serve 回退）是否不同于
Node CLI 基于 `dns-sd` 的发现。
## 远程连接底层机制（SSH 隧道）
## 远程连接管线（SSH 隧道）
当 macOS 应用运行在**远程**模式时，它会打开一个 SSH 隧道，以便本地 UI
组件能够像访问 localhost 一样访问远程 Gateway 网关。
当 macOS 应用以**远程**模式运行时，它会打开一个 SSH 隧道，使本地 UI
组件能够像连接 localhost 一样与远程 Gateway 网关通信。
### 控制隧道（Gateway 网关 WebSocket 端口）
### 控制隧道（Gateway WebSocket 端口）
- **目的：** 健康检查、状态、Web Chat、配置以及其他控制平面调用。
- **用途：** 健康检查、状态、Web Chat、配置及其他控制平面调用。
- **本地端口：** Gateway 网关端口（默认 `18789`），始终稳定。
- **远程端口：** 远程主机上的同一个 Gateway 网关端口。
- **行为：** 不使用随机本地端口；应用会复用已有的健康隧道，
或在需要时重新启动它。
- **SSH 形式：** `ssh -N -L <local>:127.0.0.1:<remote>`，附带 BatchMode +
- **远程端口：** 远程主机上的同一 Gateway 网关端口。
- **行为：** 不使用随机本地端口；应用会重用现有的健康隧道，
或在需要时重启它。
- **SSH 形式：** `ssh -N -L <local>:127.0.0.1:<remote>`，带有 BatchMode +
ExitOnForwardFailure + keepalive 选项。
- **IP 报告：** SSH 隧道使用 loopback，因此 Gateway 网关会看到节点
IP 为 `127.0.0.1`。如果你希望显示真实客户端
IP，请使用 **Direct (ws/wss)** 传输（参见 [macOS 远程访问](/zh-CN/platforms/mac/remote)）。
- **IP 报告：** SSH 隧道使用 loopback，因此 Gateway 网关会将该节点的
IP 视为 `127.0.0.1`。如果你希望显示真实客户端
IP，请使用 **Direct (ws/wss)** 传输方式（参见 [macOS 远程访问](/zh-CN/platforms/mac/remote)）。
设置步骤请参见 [macOS 远程访问](/zh-CN/platforms/mac/remote)。协议
细节请参见 [Gateway 网关协议](/zh-CN/gateway/protocol)。
有关设置步骤，请参见 [macOS 远程访问](/zh-CN/platforms/mac/remote)。有关协议
细节，请参见 [Gateway protocol](/zh-CN/gateway/protocol)。
## 相关文档

378
docs/zh-CN/plugins/sdk-subpaths.md
View File

@ -1,23 +1,23 @@
---
read_when:
- 为插件导入选择合适的 plugin-sdk 子路径
- 审查内置插件子路径和辅助接口面向层
summary: 插件 SDK 子路径目录：按领域分组说明各导入路径的位置
- 审查 bundled-plugin 子路径和辅助接口
summary: 插件 SDK 子路径目录：按领域分组说明各导入位于何处
title: 插件 SDK 子路径
x-i18n:
generated_at: "2026-04-25T01:59:28Z"
generated_at: "2026-04-25T03:24:41Z"
model: gpt-5.4
provider: openai
source_hash: 44b6d3603a94328d94981642f94e43913f6d5476b1f6a0970baf23bed7e11105
source_hash: 0ff08a1f6801329cd9c20353e77983c3333a4237db9217d19a621b670c1b636f
source_path: plugins/sdk-subpaths.md
workflow: 15
---
插件 SDK 通过 `openclaw/plugin-sdk/` 下的一组精简子路径对外暴露。
本页按用途分组，整理了常用子路径。生成的完整列表包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json`；
其中也包含为内置插件保留的辅助子路径，但除非某个文档页面明确将其作为公开能力介绍，否则它们都属于实现细节。
插件 SDK 通过 `openclaw/plugin-sdk/` 下的一组精简子路径暴露。
本页按用途分组整理常用子路径。生成的完整列表包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json`；
其中也会列出保留的 bundled-plugin 辅助子路径，但除非某个文档页面明确将其作为公开能力介绍，否则它们都属于实现细节。
关于插件编写指南，参见 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。
关于插件编写指南，请参阅 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。
## 插件入口
@ -33,249 +33,249 @@ x-i18n:
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/config-schema` | 根 `openclaw.json` Zod schema 导出（`OpenClawSchema`） |
| `plugin-sdk/config-schema` | 根级 `openclaw.json` Zod schema 导出（`OpenClawSchema`） |
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/setup` | 共享的设置向导辅助函数、allowlist 提示、设置状态构建器 |
| `plugin-sdk/setup` | 共享设置向导辅助工具、allowlist 提示、设置状态构建器 |
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | 多账户配置 / 操作门控辅助函数，以及默认账户回退辅助函数 |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 规范化辅助函数 |
| `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助函数 |
| `plugin-sdk/account-helpers` | 精简的账户列表 / 账户操作辅助函数 |
| `plugin-sdk/account-core` | 多账户配置 / 操作门控辅助工具，默认账户回退辅助工具 |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 规范化辅助工具 |
| `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助工具 |
| `plugin-sdk/account-helpers` | 精简的账户列表 / 账户操作辅助工具 |
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | 渠道配置 schema 类型 |
| `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化 / 验证辅助函数，带内置契约回退 |
| `plugin-sdk/command-gating` | 精简的命令授权门控辅助函数 |
| `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化 / 校验辅助工具，带 bundled-contract 回退 |
| `plugin-sdk/command-gating` | 精简的命令授权门控辅助工具 |
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期 / 最终化辅助函数 |
| `plugin-sdk/inbound-envelope` | 共享的入站路由 + envelope 构建辅助函数 |
| `plugin-sdk/inbound-reply-dispatch` | 共享的入站记录与分发辅助函数 |
| `plugin-sdk/messaging-targets` | 目标解析 / 匹配辅助函数 |
| `plugin-sdk/outbound-media` | 共享的出站媒体加载辅助函数 |
| `plugin-sdk/outbound-runtime` | 出站投递、身份、发送委托、会话、格式化和负载规划辅助函数 |
| `plugin-sdk/poll-runtime` | 精简的投票规范化辅助函数 |
| `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助函数 |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期 / 终结辅助工具 |
| `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建辅助工具 |
| `plugin-sdk/inbound-reply-dispatch` | 共享入站记录与分发辅助工具 |
| `plugin-sdk/messaging-targets` | 目标解析 / 匹配辅助工具 |
| `plugin-sdk/outbound-media` | 共享出站媒体加载辅助工具 |
| `plugin-sdk/outbound-runtime` | 出站投递、身份、发送委托、会话、格式化以及负载规划辅助工具 |
| `plugin-sdk/poll-runtime` | 精简的投票规范化辅助工具 |
| `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期与适配器辅助工具 |
| `plugin-sdk/agent-media-payload` | 旧版智能体媒体负载构建器 |
| `plugin-sdk/conversation-runtime` | 会话 / 线程绑定、配对和已配置绑定辅助函数 |
| `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助函数 |
| `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助函数 |
| `plugin-sdk/channel-status` | 共享的渠道状态快照 / 摘要辅助函数 |
| `plugin-sdk/conversation-runtime` | 会话 / 线程绑定、配对以及已配置绑定辅助工具 |
| `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助工具 |
| `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助工具 |
| `plugin-sdk/channel-status` | 共享渠道状态快照 / 摘要辅助工具 |
| `plugin-sdk/channel-config-primitives` | 精简的渠道配置 schema 基元 |
| `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助函数 |
| `plugin-sdk/channel-plugin-common` | 共享的渠道插件前导导出 |
| `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑 / 读取辅助函数 |
| `plugin-sdk/group-access` | 共享的群组访问决策辅助函数 |
| `plugin-sdk/direct-dm` | 共享的直接私信认证 / 保护辅助函数 |
| `plugin-sdk/interactive-runtime` | 语义化消息呈现、投递，以及旧版交互式回复辅助函数。参见 [消息呈现](/zh-CN/plugins/message-presentation) |
| `plugin-sdk/channel-inbound` | 兼容性 barrel，包含入站去抖、提及匹配、提及策略辅助函数以及 envelope 辅助函数 |
| `plugin-sdk/channel-inbound-debounce` | 精简的入站去抖辅助函数 |
| `plugin-sdk/channel-mention-gating` | 精简的提及策略和提及文本辅助函数，不包含更广泛的入站运行时接口面 |
| `plugin-sdk/channel-envelope` | 精简的入站 envelope 格式化辅助函数 |
| `plugin-sdk/channel-location` | 渠道位置上下文和格式化辅助函数 |
| `plugin-sdk/channel-logging` | 用于入站丢弃和 typing / ack 失败的渠道日志辅助函数 |
| `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助工具 |
| `plugin-sdk/channel-plugin-common` | 共享渠道插件前导导出 |
| `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑 / 读取辅助工具 |
| `plugin-sdk/group-access` | 共享群组访问决策辅助工具 |
| `plugin-sdk/direct-dm` | 共享直接私信认证 / 守卫辅助工具 |
| `plugin-sdk/interactive-runtime` | 语义化消息呈现、投递以及旧版交互式回复辅助工具。参见 [消息呈现](/zh-CN/plugins/message-presentation) |
| `plugin-sdk/channel-inbound` | 入站防抖、提及匹配、提及策略辅助工具以及 envelope 辅助工具的兼容性 barrel |
| `plugin-sdk/channel-inbound-debounce` | 精简的入站防抖辅助工具 |
| `plugin-sdk/channel-mention-gating` | 不包含更广泛入站运行时能力的精简提及策略与提及文本辅助工具 |
| `plugin-sdk/channel-envelope` | 精简的入站 envelope 格式化辅助工具 |
| `plugin-sdk/channel-location` | 渠道位置上下文与格式化辅助工具 |
| `plugin-sdk/channel-logging` | 用于入站丢弃以及 typing / ack 失败的渠道日志辅助工具 |
| `plugin-sdk/channel-send-result` | 回复结果类型 |
| `plugin-sdk/channel-actions` | 渠道消息操作辅助函数，以及为保持插件兼容性而保留的已弃用原生 schema 辅助函数 |
| `plugin-sdk/channel-targets` | 目标解析 / 匹配辅助函数 |
| `plugin-sdk/channel-actions` | 渠道消息操作辅助工具，以及为保持插件兼容性而保留的已弃用原生 schema 辅助工具 |
| `plugin-sdk/channel-targets` | 目标解析 / 匹配辅助工具 |
| `plugin-sdk/channel-contract` | 渠道契约类型 |
| `plugin-sdk/channel-feedback` | 反馈 / reaction 接线 |
| `plugin-sdk/channel-secret-runtime` | 精简的 secret 契约辅助函数，例如 `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`，以及 secret 目标类型 |
| `plugin-sdk/channel-secret-runtime` | 精简的 secret 契约辅助工具，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 以及 secret target 类型 |
</Accordion>
<Accordion title="提供商子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/provider-setup` | 精选的本地 / 自托管提供商设置辅助函数 |
| `plugin-sdk/self-hosted-provider-setup` | 面向 OpenAI 兼容自托管提供商的聚焦设置辅助函数 |
| `plugin-sdk/provider-setup` | 精选的本地 / 自托管提供商设置辅助工具 |
| `plugin-sdk/self-hosted-provider-setup` | 聚焦 OpenAI 兼容型自托管提供商的设置辅助工具 |
| `plugin-sdk/cli-backend` | CLI 后端默认值 + watchdog 常量 |
| `plugin-sdk/provider-auth-runtime` | 面向提供商插件的运行时 API key 解析辅助函数 |
| `plugin-sdk/provider-auth-api-key` | API key 新手引导 / 配置档写入辅助函数，例如 `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-result` | 标准 OAuth 认证结果构建器 |
| `plugin-sdk/provider-auth-login` | 面向提供商插件的共享交互式登录辅助函数 |
| `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助函数 |
| `plugin-sdk/provider-auth-runtime` | 用于提供商插件的运行时 API key 解析辅助工具 |
| `plugin-sdk/provider-auth-api-key` | API key 新手引导 / 配置文件写入辅助工具，例如 `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-result` | 标准 OAuth auth-result 构建器 |
| `plugin-sdk/provider-auth-login` | 用于提供商插件的共享交互式登录辅助工具 |
| `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助工具 |
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助函数，以及诸如 `normalizeNativeXaiModelId` 之类的 model-id 规范化辅助函数 |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助工具，以及诸如 `normalizeNativeXaiModelId` 之类的 model-id 规范化辅助工具 |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-http` | 通用提供商 HTTP / endpoint 能力辅助函数、提供商 HTTP 错误，以及音频转录 multipart form 辅助函数 |
| `plugin-sdk/provider-web-fetch-contract` | 精简的 web-fetch 配置 / 选择契约辅助函数，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | web-fetch 提供商注册 / 缓存辅助函数 |
| `plugin-sdk/provider-web-search-config-contract` | 面向无需插件启用接线的提供商的精简 web-search 配置 / 凭证辅助函数 |
| `plugin-sdk/provider-web-search-contract` | 精简的 web-search 配置 / 凭证契约辅助函数，例如 `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`，以及作用域化凭证 setter / getter |
| `plugin-sdk/provider-web-search` | web-search 提供商注册 / 缓存 / 运行时辅助函数 |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 xAI 兼容辅助函数，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` 等 |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic / Bedrock / Google / Kilocode / Moonshot / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装器辅助函数 |
| `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助函数，例如受保护的 fetch、传输消息转换，以及可写传输事件流 |
| `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助函数 |
| `plugin-sdk/global-singleton` | 进程本地 singleton / map / cache 辅助函数 |
| `plugin-sdk/group-activation` | 精简的群组激活模式和命令解析辅助函数 |
| `plugin-sdk/provider-http` | 通用提供商 HTTP / endpoint 能力辅助工具、提供商 HTTP 错误以及音频转写 multipart form 辅助工具 |
| `plugin-sdk/provider-web-fetch-contract` | 精简的 web-fetch 配置 / 选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | web-fetch 提供商注册 / 缓存辅助工具 |
| `plugin-sdk/provider-web-search-config-contract` | 适用于不需要插件启用接线的提供商的精简 web-search 配置 / 凭证辅助工具 |
| `plugin-sdk/provider-web-search-contract` | 精简的 web-search 配置 / 凭证契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及作用域化凭证 setter / getter |
| `plugin-sdk/provider-web-search` | web-search 提供商注册 / 缓存 / 运行时辅助工具 |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema 清理 + 诊断，以及诸如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` 之类的 xAI 兼容性辅助工具 |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似内容 |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic / Bedrock / Google / Kilocode / Moonshot / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装器辅助工具 |
| `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助工具，例如受保护的 fetch、传输消息转换以及可写传输事件流 |
| `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助工具 |
| `plugin-sdk/global-singleton` | 进程本地 singleton / map / cache 辅助工具 |
| `plugin-sdk/group-activation` | 精简的群组激活模式与命令解析辅助工具 |
</Accordion>
<Accordion title="认证与安全子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助函数、发送者授权辅助函数 |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助工具、发送方授权辅助工具 |
| `plugin-sdk/command-status` | 命令 / 帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` |
| `plugin-sdk/approval-auth-runtime` | 审批人解析和同聊天操作认证辅助函数 |
| `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置档 / 过滤器辅助函数 |
| `plugin-sdk/approval-auth-runtime` | 审批人解析以及同聊天 action-auth 辅助工具 |
| `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件 / 过滤器辅助工具 |
| `plugin-sdk/approval-delivery-runtime` | 原生审批能力 / 投递适配器 |
| `plugin-sdk/approval-gateway-runtime` | 共享的审批 Gateway 网关解析辅助函数 |
| `plugin-sdk/approval-handler-adapter-runtime` | 面向高频渠道入口点的轻量级原生审批适配器加载辅助函数 |
| `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助函数；如果更精简的 adapter / gateway 接口已足够，优先使用它们 |
| `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助函数 |
| `plugin-sdk/approval-reply-runtime` | exec / 插件审批回复负载辅助函数 |
| `plugin-sdk/approval-runtime` | exec / 插件审批负载辅助函数、原生审批路由 / 运行时辅助函数，以及结构化审批展示辅助函数，例如 `formatApprovalDisplayPath` |
| `plugin-sdk/reply-dedupe` | 精简的入站回复去重重置辅助函数 |
| `plugin-sdk/channel-contract-testing` | 精简的渠道契约测试辅助函数，不包含宽泛的 testing barrel |
| `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助函数 |
| `plugin-sdk/command-detection` | 共享的命令检测辅助函数 |
| `plugin-sdk/command-primitives-runtime` | 面向高频渠道路径的轻量级命令文本谓词 |
| `plugin-sdk/command-surface` | 命令主体规范化和命令接口面辅助函数 |
| `plugin-sdk/approval-gateway-runtime` | 共享审批 Gateway 网关解析辅助工具 |
| `plugin-sdk/approval-handler-adapter-runtime` | 用于高频渠道入口点的轻量级原生审批适配器加载辅助工具 |
| `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助工具；如果更精简的 adapter / gateway 接缝已足够，优先使用它们 |
| `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助工具 |
| `plugin-sdk/approval-reply-runtime` | exec / 插件审批回复负载辅助工具 |
| `plugin-sdk/approval-runtime` | exec / 插件审批负载辅助工具、原生审批路由 / 运行时辅助工具，以及结构化审批显示辅助工具，例如 `formatApprovalDisplayPath` |
| `plugin-sdk/reply-dedupe` | 精简的入站回复去重重置辅助工具 |
| `plugin-sdk/channel-contract-testing` | 不带广泛 testing barrel 的精简渠道契约测试辅助工具 |
| `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助工具 |
| `plugin-sdk/command-detection` | 共享命令检测辅助工具 |
| `plugin-sdk/command-primitives-runtime` | 用于高频渠道路径的轻量级命令文本谓词 |
| `plugin-sdk/command-surface` | 命令主体规范化和命令表面辅助工具 |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/channel-secret-runtime` | 面向渠道 / 插件 secret 接口面的精简 secret 契约收集辅助函数 |
| `plugin-sdk/secret-ref-runtime` | 精简的 `coerceSecretRef` 和 SecretRef 类型辅助函数，用于 secret 契约 / 配置解析 |
| `plugin-sdk/security-runtime` | 共享的信任、私信门控、外部内容和 secret 收集辅助函数 |
| `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助函数 |
| `plugin-sdk/ssrf-dispatcher` | 精简的固定 dispatcher 辅助函数，不包含宽泛的基础设施运行时接口面 |
| `plugin-sdk/ssrf-runtime` | 固定 dispatcher、受 SSRF 保护的 fetch，以及 SSRF 策略辅助函数 |
| `plugin-sdk/secret-input` | secret 输入解析辅助函数 |
| `plugin-sdk/webhook-ingress` | Webhook 请求 / 目标辅助函数 |
| `plugin-sdk/webhook-request-guards` | 请求体大小 / 超时辅助函数 |
| `plugin-sdk/channel-secret-runtime` | 面向渠道 / 插件 secret surface 的精简 secret 契约收集辅助工具 |
| `plugin-sdk/secret-ref-runtime` | 面向 secret 契约 / 配置解析的精简 `coerceSecretRef` 和 SecretRef 类型辅助工具 |
| `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容和 secret 收集辅助工具 |
| `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助工具 |
| `plugin-sdk/ssrf-dispatcher` | 不带广泛基础设施运行时表面的精简固定 dispatcher 辅助工具 |
| `plugin-sdk/ssrf-runtime` | 固定 dispatcher、受 SSRF 保护的 fetch 以及 SSRF 策略辅助工具 |
| `plugin-sdk/secret-input` | secret 输入解析辅助工具 |
| `plugin-sdk/webhook-ingress` | webhook 请求 / 目标辅助工具 |
| `plugin-sdk/webhook-request-guards` | 请求体大小 / 超时辅助工具 |
</Accordion>
<Accordion title="运行时与存储子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/runtime` | 宽泛的运行时 / 日志 / 备份 / 插件安装辅助函数 |
| `plugin-sdk/runtime-env` | 精简的运行时环境、logger、超时、重试和退避辅助函数 |
| `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册和查找辅助函数 |
| `plugin-sdk/runtime` | 广泛的运行时 / 日志 / 备份 / 插件安装辅助工具 |
| `plugin-sdk/runtime-env` | 精简的运行时环境、日志记录器、超时、重试和退避辅助工具 |
| `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册与查找辅助工具 |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/plugin-runtime` | 共享的插件命令 / hook / http / 交互式辅助函数 |
| `plugin-sdk/hook-runtime` | 共享的 webhook / 内部钩子管道辅助函数 |
| `plugin-sdk/lazy-runtime` | 延迟运行时导入 / 绑定辅助函数，例如 `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | 进程 exec 辅助函数 |
| `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助函数 |
| `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助函数 |
| `plugin-sdk/config-runtime` | 配置加载 / 写入辅助函数和插件配置查找辅助函数 |
| `plugin-sdk/telegram-command-config` | Telegram 命令名称 / 描述规范化以及重复 / 冲突检查，即使内置 Telegram 契约接口面不可用时也可使用 |
| `plugin-sdk/text-autolink-runtime` | 文件引用自动链接检测，不包含宽泛的 text-runtime barrel |
| `plugin-sdk/approval-runtime` | exec / 插件审批辅助函数、审批能力构建器、认证 / 配置档辅助函数、原生路由 / 运行时辅助函数，以及结构化审批展示路径格式化 |
| `plugin-sdk/reply-runtime` | 共享的入站 / 回复运行时辅助函数、分块、分发、心跳、回复规划器 |
| `plugin-sdk/reply-dispatch-runtime` | 精简的回复分发 / 最终化和会话标签辅助函数 |
| `plugin-sdk/reply-history` | 共享的短窗口回复历史辅助函数，例如 `buildHistoryContext`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/plugin-runtime` | 共享插件命令 / hook / HTTP / 交互式辅助工具 |
| `plugin-sdk/hook-runtime` | 共享 webhook / 内部 hook 管道辅助工具 |
| `plugin-sdk/lazy-runtime` | 懒加载运行时导入 / 绑定辅助工具，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | 进程 exec 辅助工具 |
| `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助工具 |
| `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助工具 |
| `plugin-sdk/config-runtime` | 配置加载 / 写入辅助工具以及插件配置查找辅助工具 |
| `plugin-sdk/telegram-command-config` | Telegram 命令名称 / 描述规范化以及重复 / 冲突检查，即使 bundled Telegram 契约接口不可用时也可使用 |
| `plugin-sdk/text-autolink-runtime` | 不带广泛 text-runtime barrel 的文件引用自动链接检测 |
| `plugin-sdk/approval-runtime` | exec / 插件审批辅助工具、审批能力构建器、认证 / 配置文件辅助工具、原生路由 / 运行时辅助工具，以及结构化审批显示路径格式化 |
| `plugin-sdk/reply-runtime` | 共享入站 / 回复运行时辅助工具、分块、分发、心跳、回复规划器 |
| `plugin-sdk/reply-dispatch-runtime` | 精简的回复分发 / 终结和会话标签辅助工具 |
| `plugin-sdk/reply-history` | 共享短窗口回复历史辅助工具，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | 精简的文本 / Markdown 分块辅助函数 |
| `plugin-sdk/session-store-runtime` | 会话存储路径 + updated-at 辅助函数 |
| `plugin-sdk/state-paths` | state / OAuth 目录路径辅助函数 |
| `plugin-sdk/routing` | 路由 / 会话键 / 账户绑定辅助函数，例如 `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | 共享的渠道 / 账户状态摘要辅助函数、运行时状态默认值和问题元数据辅助函数 |
| `plugin-sdk/target-resolver-runtime` | 共享的目标解析器辅助函数 |
| `plugin-sdk/string-normalization-runtime` | slug / 字符串规范化辅助函数 |
| `plugin-sdk/reply-chunking` | 精简的文本 / markdown 分块辅助工具 |
| `plugin-sdk/session-store-runtime` | 会话存储路径 + updated-at 辅助工具 |
| `plugin-sdk/state-paths` | 状态 / OAuth 目录路径辅助工具 |
| `plugin-sdk/routing` | 路由 / 会话键 / 账户绑定辅助工具，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | 共享渠道 / 账户状态摘要辅助工具、运行时状态默认值以及问题元数据辅助工具 |
| `plugin-sdk/target-resolver-runtime` | 共享目标解析器辅助工具 |
| `plugin-sdk/string-normalization-runtime` | slug / 字符串规范化辅助工具 |
| `plugin-sdk/request-url` | 从 fetch / request 类输入中提取字符串 URL |
| `plugin-sdk/run-command` | 带超时的命令运行器，返回规范化的 stdout / stderr 结果 |
| `plugin-sdk/param-readers` | 常用工具 / CLI 参数读取器 |
| `plugin-sdk/param-readers` | 通用工具 / CLI 参数读取器 |
| `plugin-sdk/tool-payload` | 从工具结果对象中提取规范化负载 |
| `plugin-sdk/tool-send` | 从工具参数中提取规范的发送目标字段 |
| `plugin-sdk/temp-path` | 共享的临时下载路径辅助函数 |
| `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助函数 |
| `plugin-sdk/markdown-table-runtime` | Markdown 表格模式和转换辅助函数 |
| `plugin-sdk/json-store` | 小型 JSON 状态读写辅助函数 |
| `plugin-sdk/file-lock` | 可重入文件锁辅助函数 |
| `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助函数 |
| `plugin-sdk/acp-runtime` | ACP 运行时 / 会话和回复分发辅助函数 |
| `plugin-sdk/acp-binding-resolve-runtime` | 只读 ACP 绑定解析，不引入生命周期启动导入 |
| `plugin-sdk/agent-config-primitives` | 精简的智能体运行时配置 schema 基元 |
| `plugin-sdk/temp-path` | 共享临时下载路径辅助工具 |
| `plugin-sdk/logging-core` | 子系统日志记录器和脱敏辅助工具 |
| `plugin-sdk/markdown-table-runtime` | Markdown 表格模式和转换辅助工具 |
| `plugin-sdk/json-store` | 小型 JSON 状态读写辅助工具 |
| `plugin-sdk/file-lock` | 可重入文件锁辅助工具 |
| `plugin-sdk/persistent-dedupe` | 磁盘后备去重缓存辅助工具 |
| `plugin-sdk/acp-runtime` | ACP 运行时 / 会话和回复分发辅助工具 |
| `plugin-sdk/acp-binding-resolve-runtime` | 不带生命周期启动导入的只读 ACP 绑定解析 |
| `plugin-sdk/agent-config-primitives` | 精简的智能体运行时 config-schema 基元 |
| `plugin-sdk/boolean-param` | 宽松布尔参数读取器 |
| `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助函数 |
| `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助函数 |
| `plugin-sdk/extension-shared` | 共享的被动渠道、状态和环境代理辅助基元 |
| `plugin-sdk/models-provider-runtime` | `/models` 命令 / 提供商回复辅助函数 |
| `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助函数 |
| `plugin-sdk/native-command-registry` | 原生命令注册表 / 构建 / 序列化辅助函数 |
| `plugin-sdk/agent-harness` | 面向低层 Agent harness 的实验性可信插件接口面：harness 类型、活动运行 steer / abort 辅助函数、OpenClaw 工具桥接辅助函数、工具进度格式化 / 详情辅助函数，以及尝试结果工具函数 |
| `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint 检测辅助函数 |
| `plugin-sdk/infra-runtime` | 系统事件 / 心跳辅助函数 |
| `plugin-sdk/collection-runtime` | 小型有界缓存辅助函数 |
| `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助函数 |
| `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助函数、`isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | 封装的 fetch、代理和固定查找辅助函数 |
| `plugin-sdk/runtime-fetch` | 感知 dispatcher 的运行时 fetch，不引入代理 / 受保护 fetch 导入 |
| `plugin-sdk/response-limit-runtime` | 有界响应体读取器，不包含宽泛的媒体运行时接口面 |
| `plugin-sdk/session-binding-runtime` | 当前会话绑定状态，不包含已配置绑定路由或配对存储 |
| `plugin-sdk/session-store-runtime` | 会话存储读取辅助函数，不包含宽泛的配置写入 / 维护导入 |
| `plugin-sdk/context-visibility-runtime` | 上下文可见性解析和补充上下文过滤，不包含宽泛的配置 / 安全导入 |
| `plugin-sdk/string-coerce-runtime` | 精简的原始记录 / 字符串强制转换和规范化辅助函数，不包含 Markdown / 日志导入 |
| `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助函数 |
| `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助函数 |
| `plugin-sdk/agent-runtime` | 智能体目录 / 身份 / 工作区辅助函数 |
| `plugin-sdk/directory-runtime` | 基于配置的目录查询 / 去重 |
| `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助工具 |
| `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助工具 |
| `plugin-sdk/extension-shared` | 共享被动渠道、状态和环境代理辅助基元 |
| `plugin-sdk/models-provider-runtime` | `/models` 命令 / 提供商回复辅助工具 |
| `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助工具 |
| `plugin-sdk/native-command-registry` | 原生命令注册表 / 构建 / 序列化辅助工具 |
| `plugin-sdk/agent-harness` | 面向受信任插件、仍属实验性的底层 Agent harness 接口：harness 类型、活动运行 steer / abort 辅助工具、OpenClaw 工具桥接辅助工具、工具进度格式化 / 细节辅助工具，以及 attempt 结果工具 |
| `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint 检测辅助工具 |
| `plugin-sdk/infra-runtime` | 系统事件 / 心跳辅助工具 |
| `plugin-sdk/collection-runtime` | 小型有界缓存辅助工具 |
| `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助工具 |
| `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助工具、`isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | 封装的 fetch、代理和固定查找辅助工具 |
| `plugin-sdk/runtime-fetch` | 不导入 proxy / guarded-fetch 的 dispatcher 感知型运行时 fetch |
| `plugin-sdk/response-limit-runtime` | 不带广泛媒体运行时表面的有界响应体读取器 |
| `plugin-sdk/session-binding-runtime` | 不带已配置绑定路由或配对存储的当前会话绑定状态 |
| `plugin-sdk/session-store-runtime` | 不带广泛配置写入 / 维护导入的会话存储读取辅助工具 |
| `plugin-sdk/context-visibility-runtime` | 不带广泛配置 / 安全导入的上下文可见性解析和补充上下文过滤 |
| `plugin-sdk/string-coerce-runtime` | 不带 markdown / 日志导入的精简基元记录 / 字符串强制转换与规范化辅助工具 |
| `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助工具 |
| `plugin-sdk/retry-runtime` | 重试配置和重试执行器辅助工具 |
| `plugin-sdk/agent-runtime` | 智能体目录 / 身份 / 工作区辅助工具 |
| `plugin-sdk/directory-runtime` | 配置后备目录查询 / 去重 |
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
</Accordion>
<Accordion title="能力与测试子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/media-runtime` | 共享的媒体获取 / 转换 / 存储辅助函数，以及媒体负载构建器 |
| `plugin-sdk/media-store` | 精简的媒体存储辅助函数，例如 `saveMediaBuffer` |
| `plugin-sdk/media-generation-runtime` | 共享的媒体生成故障转移辅助函数、候选项选择和缺失模型提示 |
| `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像 / 音频辅助导出 |
| `plugin-sdk/text-runtime` | 共享的文本 / Markdown / 日志辅助函数，例如去除对助手可见的文本、Markdown 渲染 / 分块 / 表格辅助函数、脱敏辅助函数、directive-tag 辅助函数以及安全文本工具 |
| `plugin-sdk/text-chunking` | 出站文本分块辅助函数 |
| `plugin-sdk/media-runtime` | 共享媒体获取 / 转换 / 存储辅助工具，以及媒体负载构建器 |
| `plugin-sdk/media-store` | 精简的媒体存储辅助工具，例如 `saveMediaBuffer` |
| `plugin-sdk/media-generation-runtime` | 共享媒体生成故障转移辅助工具、候选项选择和缺失模型提示 |
| `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图片 / 音频辅助导出 |
| `plugin-sdk/text-runtime` | 共享文本 / markdown / 日志辅助工具，例如对智能体可见文本的剥离、markdown 渲染 / 分块 / 表格辅助工具、脱敏辅助工具、directive-tag 辅助工具以及安全文本工具 |
| `plugin-sdk/text-chunking` | 出站文本分块辅助工具 |
| `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表、校验和语音辅助导出 |
| `plugin-sdk/speech-core` | 共享的语音提供商类型、注册表、directive、规范化和语音辅助导出 |
| `plugin-sdk/realtime-transcription` | 实时转录提供商类型、注册表辅助函数和共享的 WebSocket 会话辅助函数 |
| `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助函数 |
| `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、directive、规范化和语音辅助导出 |
| `plugin-sdk/realtime-transcription` | 实时转写提供商类型、注册表辅助工具和共享 WebSocket 会话辅助工具 |
| `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助工具 |
| `plugin-sdk/image-generation` | 图像生成提供商类型 |
| `plugin-sdk/image-generation-core` | 共享的图像生成类型、故障转移、认证和注册表辅助函数 |
| `plugin-sdk/image-generation-core` | 共享图像生成类型、故障转移、认证和注册表辅助工具 |
| `plugin-sdk/music-generation` | 音乐生成提供商 / 请求 / 结果类型 |
| `plugin-sdk/music-generation-core` | 共享的音乐生成类型、故障转移辅助函数、提供商查找和 model-ref 解析 |
| `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障转移辅助工具、提供商查找和 model-ref 解析 |
| `plugin-sdk/video-generation` | 视频生成提供商 / 请求 / 结果类型 |
| `plugin-sdk/video-generation-core` | 共享的视频生成类型、故障转移辅助函数、提供商查找和 model-ref 解析 |
| `plugin-sdk/webhook-targets` | Webhook 目标注册表和路由安装辅助函数 |
| `plugin-sdk/webhook-path` | Webhook 路径规范化辅助函数 |
| `plugin-sdk/web-media` | 共享的远程 / 本地媒体加载辅助函数 |
| `plugin-sdk/zod` | 为插件 SDK 使用方重新导出的 `zod` |
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
| `plugin-sdk/video-generation-core` | 共享视频生成类型、故障转移辅助工具、提供商查找和 model-ref 解析 |
| `plugin-sdk/webhook-targets` | webhook 目标注册表和路由安装辅助工具 |
| `plugin-sdk/webhook-path` | webhook 路径规范化辅助工具 |
| `plugin-sdk/web-media` | 共享远程 / 本地媒体加载辅助工具 |
| `plugin-sdk/zod` | 为插件 SDK 使用者重新导出的 `zod` |
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`、`shouldAckReaction` |
</Accordion>
<Accordion title="Memory 子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/memory-core` | 内置的 memory-core 辅助接口面，用于 manager / config / file / CLI 辅助函数 |
| `plugin-sdk/memory-core-engine-runtime` | Memory 索引 / 搜索运行时外观层 |
| `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation 引擎导出 |
| `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 契约、注册表访问、本地提供商，以及通用批处理 / 远程辅助函数 |
| `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD 引擎导出 |
| `plugin-sdk/memory-core-host-engine-storage` | Memory host 存储引擎导出 |
| `plugin-sdk/memory-core-host-multimodal` | Memory host 多模态辅助函数 |
| `plugin-sdk/memory-core-host-query` | Memory host 查询辅助函数 |
| `plugin-sdk/memory-core-host-secret` | Memory host secret 辅助函数 |
| `plugin-sdk/memory-core-host-events` | Memory host 事件日志辅助函数 |
| `plugin-sdk/memory-core-host-status` | Memory host 状态辅助函数 |
| `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助函数 |
| `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助函数 |
| `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件 / 运行时辅助函数 |
| `plugin-sdk/memory-host-core` | 面向供应商中立的别名，对应 memory host 核心运行时辅助函数 |
| `plugin-sdk/memory-host-events` | 面向供应商中立的别名，对应 memory host 事件日志辅助函数 |
| `plugin-sdk/memory-host-files` | 面向供应商中立的别名，对应 memory host 文件 / 运行时辅助函数 |
| `plugin-sdk/memory-host-markdown` | 面向与 memory 相邻插件的共享托管 Markdown 辅助函数 |
| `plugin-sdk/memory-host-search` | 活跃 Memory 运行时外观层，用于 search-manager 访问 |
| `plugin-sdk/memory-host-status` | 面向供应商中立的别名，对应 memory host 状态辅助函数 |
| `plugin-sdk/memory-lancedb` | 内置的 memory-lancedb 辅助接口面 |
| `plugin-sdk/memory-core` | 内置的 memory-core 辅助接口，用于 manager / config / 文件 / CLI 辅助工具 |
| `plugin-sdk/memory-core-engine-runtime` | Memory 索引 / 搜索运行时门面 |
| `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation engine 导出 |
| `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 契约、注册表访问、本地 provider 以及通用批处理 / 远程辅助工具 |
| `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD engine 导出 |
| `plugin-sdk/memory-core-host-engine-storage` | Memory host storage engine 导出 |
| `plugin-sdk/memory-core-host-multimodal` | Memory host 多模态辅助工具 |
| `plugin-sdk/memory-core-host-query` | Memory host 查询辅助工具 |
| `plugin-sdk/memory-core-host-secret` | Memory host secret 辅助工具 |
| `plugin-sdk/memory-core-host-events` | Memory host 事件日志辅助工具 |
| `plugin-sdk/memory-core-host-status` | Memory host 状态辅助工具 |
| `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助工具 |
| `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助工具 |
| `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件 / 运行时辅助工具 |
| `plugin-sdk/memory-host-core` | 面向厂商中立的 memory host 核心运行时辅助工具别名 |
| `plugin-sdk/memory-host-events` | 面向厂商中立的 memory host 事件日志辅助工具别名 |
| `plugin-sdk/memory-host-files` | 面向厂商中立的 memory host 文件 / 运行时辅助工具别名 |
| `plugin-sdk/memory-host-markdown` | 面向 Memory 邻近插件的共享托管 markdown 辅助工具 |
| `plugin-sdk/memory-host-search` | 用于 search-manager 访问的活动 Memory 运行时门面 |
| `plugin-sdk/memory-host-status` | 面向厂商中立的 memory host 状态辅助工具别名 |
| `plugin-sdk/memory-lancedb` | 内置的 memory-lancedb 辅助接口 |
</Accordion>
<Accordion title="保留的内置辅助子路径">
| 分类 | 当前子路径 | 预期用途 |
| 家族 | 当前子路径 | 预期用途 |
| --- | --- | --- |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | 内置 Browser 插件支持辅助函数（`browser-support` 仍作为兼容性 barrel） |
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助 / 运行时接口面 |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助 / 运行时接口面 |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助接口面 |
| 渠道专用辅助函数 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | 内置渠道兼容性 / 辅助接口 |
| 认证 / 插件专用辅助函数 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能 / 插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken`, `resolveCopilotApiToken` |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | 内置 Browser 插件支持辅助工具。`browser-profiles` 导出 `resolveBrowserConfig`、`resolveProfile`、`ResolvedBrowserConfig`、`ResolvedBrowserProfile` 和 `ResolvedBrowserTabCleanupConfig`，用于规范化后的 `browser.tabCleanup` 结构。`browser-support` 仍然是兼容性 barrel。 |
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助 / 运行时接口 |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助 / 运行时接口 |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助接口 |
| 渠道专用辅助工具 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | 内置渠道兼容性 / 辅助接缝 |
| 认证 / 插件专用辅助工具 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能 / 插件辅助接缝；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |
</Accordion>
</AccordionGroup>

193
docs/zh-CN/tools/exec-approvals-advanced.md
View File

@ -1,32 +1,31 @@
---
read_when:
- 配置安全 bin 或自定义安全 bin 配置文件
- 配置安全二进制或自定义安全二进制配置档案
- 将审批转发到 Slack/Discord/Telegram 或其他聊天渠道
- 为某个渠道实现原生审批客户端
summary: 高级 exec 审批：安全 bin、解释器绑定、审批转发、原生投递
title: Exec 审批 — 高级内容
- 为渠道实现原生审批客户端
summary: 高级执行审批：安全二进制、解释器绑定、审批转发、本地原生交付
title: 执行审批——高级版
x-i18n:
generated_at: "2026-04-24T03:43:47Z"
generated_at: "2026-04-25T03:24:33Z"
model: gpt-5.4
provider: openai
source_hash: b7834a8ebfb623b38e4c2676f0e24285d5b44e2dce45c55a33db842d1bbf81be
source_hash: f5fab4a65d2d14f0d15cbe750d718b2a4e8f781a218debdb24b41be570a22d87
source_path: tools/exec-approvals-advanced.md
workflow: 15
---
高级 exec 审批主题：`safeBins` 快速路径、解释器/运行时绑定，以及将审批转发到聊天渠道（包括原生投递）。
有关核心策略和审批流程，请参阅 [Exec approvals](/zh-CN/tools/exec-approvals)。
高级执行审批主题：`safeBins` 快速路径、解释器/运行时绑定，以及将审批转发到聊天渠道（包括原生交付）。
有关核心策略和审批流程，请参阅 [执行审批](/zh-CN/tools/exec-approvals)。
## 安全 bin（仅 stdin）
## 安全二进制（仅 stdin）
`tools.exec.safeBins` 定义了一个小型的**仅 stdin** 二进制列表（例如 `cut`），这些二进制在 allowlist 模式下**无需**显式 allowlist 条目即可运行。安全 bin 会拒绝位置文件参数和类似路径的 token，因此它们只能处理传入流。请将其视为面向流过滤器的狭义快速路径，而不是通用信任列表。
`tools.exec.safeBins` 定义了一小组**仅 stdin** 的二进制程序（例如 `cut`），它们可以在允许列表模式下**无需**显式允许列表条目即可运行。安全二进制会拒绝位置文件参数和类似路径的令牌，因此它们只能对传入的数据流进行操作。请将其视为面向流过滤器的一条狭窄快速路径，而不是通用的信任列表。
<Warning>
**不要**将解释器或运行时二进制（例如 `python3`、`node`、
`ruby`、`bash`、`sh`、`zsh`）添加到 `safeBins`。如果某个命令按设计可以执行代码、运行子命令或读取文件，请优先使用显式 allowlist 条目，并保持审批提示启用。自定义安全 bin 必须在 `tools.exec.safeBinProfiles.<bin>` 中定义显式配置文件。
**不要**将解释器或运行时二进制程序（例如 `python3`、`node`、`ruby`、`bash`、`sh`、`zsh`）添加到 `safeBins` 中。如果某个命令按设计可以求值代码、执行子命令或读取文件，请优先使用显式允许列表条目，并保持审批提示启用。自定义安全二进制必须在 `tools.exec.safeBinProfiles.<bin>` 中定义一个显式配置档案。
</Warning>
默认安全 bin：
默认安全二进制：
[//]: # "SAFE_BIN_DEFAULTS:START"
@ -34,13 +33,13 @@ x-i18n:
[//]: # "SAFE_BIN_DEFAULTS:END"
`grep` 和 `sort` 不在默认列表中。如果你选择启用它们，请为其非 stdin 工作流保留显式 allowlist 条目。对于处于安全 bin 模式的 `grep`，请使用 `-e`/`--regexp` 提供模式；位置模式形式会被拒绝，以防文件操作数伪装成有歧义的位置参数。
`grep` 和 `sort` 不在默认列表中。如果你选择启用它们，请为其非 stdin 工作流保留显式允许列表条目。对于处于安全二进制模式的 `grep`，请使用 `-e`/`--regexp` 提供模式；位置模式形式会被拒绝，以防文件操作数伪装成含义不明确的位置参数。
### Argv 校验和被拒绝的标志
### Argv 验证与被拒绝的标志
校验仅根据 argv 形状以确定性方式进行（不检查主机文件系统是否存在），从而防止 allow/deny 差异导致文件存在性预言机行为。默认安全 bin 的面向文件选项会被拒绝；长选项使用 fail-closed 方式校验（未知标志和有歧义的缩写会被拒绝）。
验证仅根据 argv 形状以确定性方式进行（不检查主机文件系统中的存在性），这样可以防止因允许/拒绝差异而形成文件存在性探测行为。面向文件的选项会被默认安全二进制拒绝；长选项会以失败即关闭的方式验证（未知标志和含义不明确的缩写都会被拒绝）。
按安全 bin 配置文件划分的拒绝标志：
按安全二进制配置档案划分的被拒绝标志：
[//]: # "SAFE_BIN_DENIED_FLAGS:START"
@ -51,149 +50,145 @@ x-i18n:
[//]: # "SAFE_BIN_DENIED_FLAGS:END"
安全 bin 在执行时还会强制将 argv token 视为**字面文本**（无 glob 展开，也无 `$VARS` 扩展），适用于仅 stdin 的分段，因此像 `*` 或 `$HOME/...` 这样的模式无法被用来伪装文件读取。
安全二进制还会强制在执行时将 argv 令牌视为**字面文本**（不进行 glob 展开，也不进行 `$VARS` 展开）用于仅 stdin 的命令片段，因此像 `*` 或 `$HOME/...` 这样的模式无法被用来伪装文件读取。
### 受信任的二进制目录
安全 bin 必须从受信任的二进制目录解析（系统默认目录加上可选的 `tools.exec.safeBinTrustedDirs`）。`PATH` 条目永远不会自动受信任。默认受信任目录有意保持最小化：`/bin`、`/usr/bin`。如果你的安全 bin 可执行文件位于包管理器/用户路径中（例如 `/opt/homebrew/bin`、`/usr/local/bin`、`/opt/local/bin`、`/snap/bin`），请显式将其添加到 `tools.exec.safeBinTrustedDirs`。
安全二进制必须从受信任的二进制目录中解析（系统默认目录加上可选的 `tools.exec.safeBinTrustedDirs`）。`PATH` 条目绝不会被自动视为受信任。默认受信任目录被有意保持在最小范围：`/bin`、`/usr/bin`。如果你的安全二进制可执行文件位于包管理器/用户路径中（例如 `/opt/homebrew/bin`、`/usr/local/bin`、`/opt/local/bin`、`/snap/bin`），请将它们显式添加到 `tools.exec.safeBinTrustedDirs`。
### Shell 链接、包装器和多路复用器
### Shell 链接、包装器与多路复用器
只要每个顶层分段都满足 allowlist（包括安全 bin 或 Skills 自动允许），就允许使用 shell 链接（`&&`、`||`、`;`）。在 allowlist 模式下，重定向仍不受支持。命令替换（`$()` / 反引号）在 allowlist 解析期间会被拒绝，即使位于双引号内也是如此；如果你需要字面量 `$()` 文本，请使用单引号。
当每个顶层片段都满足允许列表要求（包括安全二进制或 Skills 自动允许）时，允许使用 shell 链接（`&&`、`||`、`;`）。在允许列表模式下，重定向仍不受支持。命令替换（`$()` / 反引号）会在允许列表解析期间被拒绝，包括双引号内的命令替换；如果你需要字面的 `$()` 文本，请使用单引号。
在 macOS 配套应用审批中，包含 shell 控制或扩展语法（`&&`、`||`、`;`、`|`、`` ` ``、`$`、`<`、`>`、`(`、`)`）的原始 shell 文本会被视为 allowlist miss，除非 shell 二进制本身已在 allowlist 中。
在 macOS 配套应用审批中，包含 shell 控制或展开语法（`&&`、`||`、`;`、`|`、`` ` ``、`$`、`<`、`>`、`(`、`)`）的原始 shell 文本会被视为不匹配允许列表，除非 shell 二进制本身已在允许列表中。
对于 shell 包装器（`bash|sh|zsh ... -c/-lc`），请求作用域的环境变量覆盖会被缩减为一个小型显式 allowlist（`TERM`、`LANG`、`LC_*`、`COLORTERM`、`NO_COLOR`、`FORCE_COLOR`）。
对于 shell 包装器（`bash|sh|zsh ... -c/-lc`），请求作用域的环境变量覆盖会被收缩为一个小型显式允许列表（`TERM`、`LANG`、`LC_*`、`COLORTERM`、`NO_COLOR`、`FORCE_COLOR`）。
对于 allowlist 模式下的 `allow-always` 决策，已知分发包装器（`env`、`nice`、`nohup`、`stdbuf`、`timeout`）会持久化内部可执行文件路径，而不是包装器路径。shell 多路复用器（`busybox`、`toybox`）对于 shell applet（`sh`、`ash` 等）也会以相同方式解包。如果某个包装器或多路复用器无法安全解包，则不会自动持久化任何 allowlist 条目。
对于允许列表模式下的 `allow-always` 决策，已知的分发包装器（`env`、`nice`、`nohup`、`stdbuf`、`timeout`）会持久化内部可执行文件路径，而不是包装器路径。Shell 多路复用器（`busybox`、`toybox`）也会对 shell applet（`sh`、`ash` 等）以同样方式进行拆包。如果某个包装器或多路复用器无法被安全拆包，则不会自动持久化任何允许列表条目。
如果你将 `python3` 或 `node` 这类解释器加入 allowlist，建议启用
`tools.exec.strictInlineEval=true`，这样内联求值仍然需要显式审批。在严格模式下，`allow-always` 仍可持久化无害的解释器/脚本调用，但内联求值载体不会自动持久化。
如果你将 `python3` 或 `node` 之类的解释器加入允许列表，建议启用 `tools.exec.strictInlineEval=true`，这样内联求值仍然需要显式审批。在严格模式下，`allow-always` 仍然可以持久化无害的解释器/脚本调用，但内联求值载体不会被自动持久化。
### 安全 bin 与 allowlist 的区别
### 安全二进制与允许列表的区别
| 主题 | `tools.exec.safeBins` | allowlist（`exec-approvals.json`） |
| ---------------- | --------------------------------------------------- | ----------------------------------------------------------- |
| 目标 | 自动允许狭义 stdin 过滤器 | 显式信任特定可执行文件 |
| 匹配类型 | 可执行文件名 + 安全 bin argv 策略 | 已解析可执行文件路径 glob 模式 |
| 参数范围 | 受安全 bin 配置文件和字面 token 规则限制 | 仅做路径匹配；参数的其他责任由你自行承担 |
| 典型示例 | `head`、`tail`、`tr`、`wc` | `jq`、`python3`、`node`、`ffmpeg`、自定义 CLI |
| 最佳用途 | 管道中的低风险文本转换 | 任何行为更广或带副作用的工具 |
| 主题 | `tools.exec.safeBins` | 允许列表（`exec-approvals.json`） |
| ---------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| 目标 | 自动允许范围狭窄的 stdin 过滤器 | 显式信任特定可执行文件 |
| 匹配类型 | 可执行文件名称 + 安全二进制 argv 策略 | 已解析的可执行文件路径 glob，或针对通过 `PATH` 调用命令的裸命令名 glob |
| 参数范围 | 受安全二进制配置档案和字面令牌规则限制 | 仅匹配路径；参数方面的责任由你自行承担 |
| 典型示例 | `head`、`tail`、`tr`、`wc` | `jq`、`python3`、`node`、`ffmpeg`、自定义 CLI |
| 最佳用途 | 管道中的低风险文本转换 | 任何行为更广泛或具有副作用的工具 |
配置位置：
- `safeBins` 来自配置（`tools.exec.safeBins` 或每智能体 `agents.list[].tools.exec.safeBins`）。
- `safeBinTrustedDirs` 来自配置（`tools.exec.safeBinTrustedDirs` 或每智能体 `agents.list[].tools.exec.safeBinTrustedDirs`）。
- `safeBinProfiles` 来自配置（`tools.exec.safeBinProfiles` 或每智能体 `agents.list[].tools.exec.safeBinProfiles`）。每智能体配置文件键会覆盖全局键。
- allowlist 条目存储在主机本地 `~/.openclaw/exec-approvals.json` 的 `agents.<id>.allowlist` 下（或通过 Control UI / `openclaw approvals allowlist ...`）。
- 当解释器/运行时 bin 出现在 `safeBins` 中但没有显式配置文件时，`openclaw security audit` 会发出 `tools.exec.safe_bins_interpreter_unprofiled` 警告。
- `openclaw doctor --fix` 可以为缺失的自定义 `safeBinProfiles.<bin>` 条目生成 `{}` 脚手架（之后请审查并收紧）。解释器/运行时 bin 不会自动生成脚手架。
- `safeBins` 来自配置（`tools.exec.safeBins` 或按智能体设置的 `agents.list[].tools.exec.safeBins`）。
- `safeBinTrustedDirs` 来自配置（`tools.exec.safeBinTrustedDirs` 或按智能体设置的 `agents.list[].tools.exec.safeBinTrustedDirs`）。
- `safeBinProfiles` 来自配置（`tools.exec.safeBinProfiles` 或按智能体设置的 `agents.list[].tools.exec.safeBinProfiles`）。按智能体设置的配置档案键会覆盖全局键。
- 允许列表条目位于主机本地的 `~/.openclaw/exec-approvals.json` 中的 `agents.<id>.allowlist` 下（或通过 Control UI / `openclaw approvals allowlist ...`）。
- 当解释器/运行时二进制出现在 `safeBins` 中但没有显式配置档案时，`openclaw security audit` 会发出 `tools.exec.safe_bins_interpreter_unprofiled` 警告。
- `openclaw doctor --fix` 可以为缺失的自定义 `safeBinProfiles.<bin>` 条目生成 `{}` 脚手架（之后请审查并收紧）。解释器/运行时二进制不会被自动生成脚手架。
自定义配置文件示例：
自定义配置档案例子：
__OC_I18N_900000__
如果你显式将 `jq` 选择加入 `safeBins`，OpenClaw 在安全 bin 模式下仍会拒绝 `env` 内建，因此 `jq -n env` 无法在没有显式 allowlist 路径或审批提示的情况下转储主机进程环境。
如果你显式将 `jq` 选择加入 `safeBins`，OpenClaw 在安全二进制模式下仍会拒绝 `env` 内建项，因此 `jq -n env` 不能在没有显式允许列表路径或审批提示的情况下转储主机进程环境。
## 解释器/运行时命令
带审批支持的解释器/运行时执行有意采用保守策略：
由审批支持的解释器/运行时执行会刻意保持保守：
- 始终绑定精确的 argv/cwd/env 上下文。
- 始终会绑定精确的 argv/cwd/env 上下文。
- 直接 shell 脚本和直接运行时文件形式会尽力绑定到一个具体的本地文件快照。
- 仍可解析为一个直接本地文件的常见包管理器包装形式（例如
`pnpm exec`、`pnpm node`、`npm exec`、`npx`）会在绑定前解包。
- 如果 OpenClaw 无法为某个解释器/运行时命令精确识别一个具体的本地文件（例如 package scripts、eval 形式、运行时特定 loader 链，或有歧义的多文件形式），则会拒绝带审批支持的执行，而不是声称覆盖了它并不具备的语义范围。
- 对于这些工作流，请优先考虑沙箱隔离、单独的主机边界，或显式的受信任 allowlist / 完整工作流，由操作员接受更广泛的运行时语义。
- 仍然能解析为单个直接本地文件的常见包管理器包装形式（例如 `pnpm exec`、`pnpm node`、`npm exec`、`npx`）会在绑定前被拆包。
- 如果 OpenClaw 无法为解释器/运行时命令准确识别出**唯一一个**具体的本地文件（例如包脚本、求值形式、运行时特定的加载器链，或含义不明确的多文件形式），则会拒绝基于审批的执行，而不是声称自己覆盖了实际并未覆盖的语义。
- 对于这些工作流，请优先考虑沙箱隔离、单独的主机边界，或显式受信任的允许列表/完整工作流，在这些情况下由操作员接受更广泛的运行时语义。
当需要审批时，exec 工具会立即返回一个审批 id。使用该 id 可以关联后续系统事件（`Exec finished` / `Exec denied`）。如果在超时前没有收到决策，该请求会被视为审批超时，并作为拒绝原因呈现。
当需要审批时，exec 工具会立即返回一个审批 id。请使用该 id 关联后续系统事件（`Exec finished` / `Exec denied`）。如果在超时前没有收到决策，请求会被视为审批超时，并作为拒绝原因显示出来。
### 后续投递行为
### 后续交付行为
批准的异步 exec 完成后，OpenClaw 会向同一会话发送一个后续 `agent` 轮次。
在已批准的异步 exec 完成后，OpenClaw 会向同一会话发送一个后续 `agent` 回合。
- 如果存在有效的外部投递目标（可投递渠道加目标 `to`），后续投递会使用该渠道。
- 在仅 webchat 或内部会话流中，如果没有外部目标，则后续投递保持为仅会话（`deliver: false`）。
- 如果调用方显式请求严格的外部投递，但没有可解析的外部渠道，则请求会以 `INVALID_REQUEST` 失败。
- 如果启用了 `bestEffortDeliver` 且无法解析出外部渠道，则投递会降级为仅会话，而不是失败。
- 如果存在有效的外部交付目标（可交付的渠道加目标 `to`），后续交付会使用该渠道。
- 在仅 webchat 或仅内部会话、且没有外部目标的流程中，后续交付会保持仅会话模式（`deliver: false`）。
- 如果调用方显式请求严格的外部交付，但无法解析出外部渠道，则请求会以 `INVALID_REQUEST` 失败。
- 如果启用了 `bestEffortDeliver` 且无法解析出外部渠道，交付会降级为仅会话模式，而不是直接失败。
## 将审批转发到聊天渠道
你可以将 exec 审批提示转发到任何聊天渠道（包括插件渠道），并使用 `/approve` 进行批准。这使用的是常规的出站投递管道。
你可以将 exec 审批提示转发到任何聊天渠道（包括渠道插件），并通过 `/approve` 进行审批。这会使用正常的出站交付流水线。
配置：
__OC_I18N_900001__
在聊天中回复：
__OC_I18N_900002__
`/approve` 命令同时处理 exec 审批和插件审批。如果该 ID 与待处理的 exec 审批不匹配，它会自动检查插件审批。
`/approve` 命令同时处理 exec 审批和插件审批。如果该 ID 与待处理的 exec 审批不匹配，它会自动继续检查插件审批。
### 插件审批转发
插件审批转发使用与 exec 审批相同的投递管道，但它拥有自己独立的 `approvals.plugin` 配置。启用或禁用其中一个不会影响另一个。
插件审批转发使用与 exec 审批相同的交付流水线，但它在 `approvals.plugin` 下拥有自己独立的配置。启用或禁用其中一个不会影响另一个。
__OC_I18N_900003__
配置结构与 `approvals.exec` 完全相同：`enabled`、`mode`、`agentFilter`、
`sessionFilter` 和 `targets` 的工作方式都一样。
配置结构与 `approvals.exec` 完全一致：`enabled`、`mode`、`agentFilter`、`sessionFilter` 和 `targets` 的工作方式都相同。
支持共享交互式回复的渠道会为 exec 审批和插件审批渲染相同的审批按钮。不支持共享交互式 UI 的渠道会回退为纯文本，并附带 `/approve` 说明。
支持共享交互式回复的渠道会为 exec 和插件审批都渲染相同的审批按钮。没有共享交互式 UI 的渠道会回退为带有 `/approve` 说明的纯文本。
### 任意渠道中的同聊审批
### 在任意渠道中于同一聊天内完成审批
当 exec 或插件审批请求源自一个可投递的聊天表面时，默认情况下，同一聊天现在可以直接使用 `/approve` 进行审批。这适用于 Slack、Matrix 和 Microsoft Teams 等渠道，以及现有的 Web UI 和终端 UI 流。
当某个 exec 或插件审批请求来自可交付的聊天界面时，现在默认可以在同一聊天中通过 `/approve` 进行审批。这适用于 Slack、Matrix 和 Microsoft Teams 等渠道，也适用于现有的 Web UI 和终端 UI 流程。
这条共享文本命令路径使用该会话的常规渠道认证模型。如果发起聊天已经能够发送命令并接收回复，那么审批请求不再需要单独的原生投递适配器才能保持待处理状态。
这条共享的文本命令路径会使用该对话的正常渠道认证模型。如果发起聊天本身已经可以发送命令并接收回复，那么审批请求就不再需要单独的原生交付适配器来维持待处理状态。
Discord 和 Telegram 也支持同聊 `/approve`，但即使禁用了原生审批投递，这些渠道在授权时仍会使用其已解析审批人列表。
Discord 和 Telegram 也支持同一聊天内的 `/approve`，但即使禁用了原生审批交付，这些渠道在授权时仍会使用其已解析的审批人列表。
对于 Telegram 和其他直接调用 Gateway 网关的原生审批客户端，这一回退被有意限制在“approval not found”失败场景中。真正的 exec 审批拒绝/错误不会被静默重试为插件审批。
对于 Telegram 和其他直接调用 Gateway 网关的原生审批客户端，这一回退机制会被有意限制在“未找到审批”失败这一类情况。真正的 exec 审批拒绝/错误不会被静默重试为插件审批。
### 原生审批投递
### 原生审批交付
某些渠道还可以充当原生审批客户端。原生客户端在共享的同聊 `/approve`
流程之上，增加了审批人私信、源聊天扇出以及渠道特定的交互式审批 UX。
某些渠道还可以充当原生审批客户端。原生客户端会在共享的同一聊天 `/approve` 流程之上，增加审批人私信、来源聊天扇出，以及渠道特定的交互式审批 UX。
当可用原生审批卡片/按钮时，该原生 UI 是面向智能体的主要路径。除非工具结果表明聊天审批不可用，或者手动审批是唯一剩余路径，否则智能体不应再额外回显一个重复的纯聊天 `/approve` 命令。
当原生审批卡片/按钮可用时，该原生 UI 是面向智能体的主要路径。除非工具结果表明聊天审批不可用，或者手动审批是唯一剩余路径，否则智能体不应另外回显重复的纯聊天 `/approve` 命令。
通用模型：
- 主机 exec 策略仍然决定是否需要 exec 审批
- 是否需要 exec 审批，仍由主机 exec 策略决定
- `approvals.exec` 控制是否将审批提示转发到其他聊天目标
- `channels.<channel>.execApprovals` 控制该渠道是否充当原生审批客户端
当以下条件全部满足时，原生审批客户端会自动启用“审批人私信优先”投递：
当以下条件全部满足时，原生审批客户端会自动启用“审批人私信优先”交付：
- 该渠道支持原生审批投递
- 可以从显式 `execApprovals.approvers` 或该渠道文档化的回退来源中解析出审批人
- `channels.<channel>.execApprovals.enabled` 未设置或为 `"auto"`
- 该渠道支持原生审批交付
- 可以从显式的 `execApprovals.approvers` 或该渠道文档化的后备来源中解析出审批人
- `channels.<channel>.execApprovals.enabled` 未设置，或设置为 `"auto"`
设置 `enabled: false` 可显式禁用某个原生审批客户端。设置 `enabled: true` 可在审批人可解析时强制启用它。公共源聊天投递仍通过 `channels.<channel>.execApprovals.target` 显式控制。
设置 `enabled: false` 可显式禁用原生审批客户端。设置 `enabled: true` 可在审批人可解析时强制启用。公开的来源聊天交付仍通过 `channels.<channel>.execApprovals.target` 显式控制。
常见问题：[为什么聊天审批会有两个 exec 审批配置？](/help/faq-first-run#why-are-there-two-exec-approval-configs-for-chat-approvals)
常见问题：[为什么聊天审批会有两套 exec 审批配置？](/help/faq-first-run#why-are-there-two-exec-approval-configs-for-chat-approvals)
- Discord：`channels.discord.execApprovals.*`
- Slack：`channels.slack.execApprovals.*`
- Telegram：`channels.telegram.execApprovals.*`
这些原生审批客户端在共享的同聊 `/approve` 流程和共享审批按钮之上，增加了私信路由和可选的渠道扇出。
这些原生审批客户端在共享的同一聊天 `/approve` 流程和共享审批按钮之上，增加了私信路由和可选的渠道扇出功能。
共享行为：
- Slack、Matrix、Microsoft Teams 及类似的可投递聊天使用常规渠道认证模型处理同聊 `/approve`
- 当原生审批客户端自动启用时，默认原生投递目标是审批人私信
- Slack、Matrix、Microsoft Teams 以及类似的可交付聊天使用正常的渠道认证模型来处理同一聊天内的 `/approve`
- 当原生审批客户端自动启用时，默认原生交付目标是审批人私信
- 对于 Discord 和 Telegram，只有已解析的审批人可以批准或拒绝
- Discord 审批人可以是显式配置（`execApprovals.approvers`），也可以从 `commands.ownerAllowFrom` 推断
- Telegram 审批人可以是显式配置（`execApprovals.approvers`），也可以从现有所有者配置推断（`allowFrom`，以及在支持时的直接消息 `defaultTo`）
- Slack 审批人可以是显式配置（`execApprovals.approvers`），也可以从 `commands.ownerAllowFrom` 推断
- Slack 原生按钮会保留审批 id 类型，因此 `plugin:` id 可以解析到插件审批，而无需第二层 Slack 本地回退
- Matrix 原生私信/渠道路由和反应快捷方式同时处理 exec 审批和插件审批；插件授权仍来自 `channels.matrix.dm.allowFrom`
- 请求方不需要是审批人
- 当源聊天本身已支持命令和回复时，它可以直接使用 `/approve` 进行审批
- 原生 Discord 审批按钮按审批 id 类型路由：`plugin:` id 直接进入插件审批，其他一切都进入 exec 审批
- 原生 Telegram 审批按钮遵循与 `/approve` 相同的有界 exec 到插件回退
- 当原生 `target` 启用源聊天投递时，审批提示会包含命令文本
- 待处理的 exec 审批默认会在 30 分钟后过期
- 如果没有操作员 UI 或已配置的审批客户端可以接收请求，提示会回退到 `askFallback`
- Discord 审批人可以显式指定（`execApprovals.approvers`），也可以从 `commands.ownerAllowFrom` 推断
- Telegram 审批人可以显式指定（`execApprovals.approvers`），也可以从现有的 owner 配置推断（`allowFrom`，以及在支持时的私信 `defaultTo`）
- Slack 审批人可以显式指定（`execApprovals.approvers`），也可以从 `commands.ownerAllowFrom` 推断
- Slack 原生按钮会保留审批 id 类型，因此 `plugin:` id 可以解析到插件审批，而无需第二层 Slack 本地后备逻辑
- Matrix 原生私信/渠道路由和表情回应快捷方式同时处理 exec 与插件审批；插件授权仍来自 `channels.matrix.dm.allowFrom`
- 请求发起者不需要是审批人
- 当来源聊天本身已经支持命令和回复时，来源聊天可以直接使用 `/approve` 进行审批
- 原生 Discord 审批按钮按审批 id 类型路由：`plugin:` id 会直接进入插件审批，其他所有情况都会进入 exec 审批
- 原生 Telegram 审批按钮遵循与 `/approve` 相同的、受限的从 exec 到插件的回退逻辑
- 当原生 `target` 启用来源聊天交付时，审批提示会包含命令文本
- 待处理的 exec 审批默认在 30 分钟后过期
- 如果没有任何操作员 UI 或已配置的审批客户端可以接受该请求，提示会回退到 `askFallback`
Telegram 默认投递到审批人私信（`target: "dm"`）。如果你希望审批提示也出现在源 Telegram 聊天/话题中，可以切换为 `channel` 或 `both`。对于 Telegram 论坛话题，OpenClaw 会保留审批提示和审批后后续消息所属的话题。
Telegram 默认使用审批人私信（`target: "dm"`）。如果你希望审批提示也出现在来源 Telegram 聊天/话题中，可以切换为 `channel` 或 `both`。对于 Telegram 论坛话题，OpenClaw 会在审批提示和审批后的后续消息中保留该话题。
请参阅：
参见：
- [Discord](/channels/discord)
- [Telegram](/channels/telegram)
@ -202,13 +197,13 @@ Telegram 默认投递到审批人私信（`target: "dm"`）。如果你希望审
__OC_I18N_900004__
安全说明：
- Unix socket 模式 `0600`，令牌存储在 `exec-approvals.json` 中。
- Unix socket 模式为 `0600`，token 存储在 `exec-approvals.json` 中。
- 同一 UID 对等方检查。
- 挑战/响应（nonce + HMAC token + 请求哈希）+ 短 TTL。
## 相关
## 相关内容
- [Exec approvals](/zh-CN/tools/exec-approvals) — 核心策略和审批流程
- [执行审批](/zh-CN/tools/exec-approvals) —— 核心策略与审批流程
- [Exec 工具](/zh-CN/tools/exec)
- [增强模式](/zh-CN/tools/elevated)
- [Skills](/zh-CN/tools/skills) — 基于 Skills 的自动允许行为
- [提权模式](/zh-CN/tools/elevated)
- [Skills](/zh-CN/tools/skills) —— 由 Skills 支持的自动允许行为

204
docs/zh-CN/tools/exec-approvals.md
View File

@ -1,65 +1,63 @@
---
read_when:
- 配置执行审批或允许列表
- 在 macOS 应用中实现执行审批用户体验
- 在 macOS 应用中实现执行审批 UX
- 审查沙箱逃逸提示及其影响
summary: 执行审批、允许列表和沙箱逃逸提示
title: 执行审批
x-i18n:
generated_at: "2026-04-23T23:21:50Z"
generated_at: "2026-04-25T03:24:35Z"
model: gpt-5.4
provider: openai
source_hash: 0d7c5cd24e7c1831d5a865da6fa20f4c23280a0ec12b9e8f7f3245170a05a37d
source_hash: 44bf7af57d322280f6d0089207041214b1233d0c9eca99656d51fc4aed88941b
source_path: tools/exec-approvals.md
workflow: 15
---
执行审批是**配套应用 / 节点主机防护栏**，用于让处于沙箱隔离的智能体在真实主机（`gateway` 或 `node`）上运行命令。它是一个安全联锁机制：只有当策略 + 允许列表 +（可选）用户审批三者全部一致同意时，命令才会被允许执行。执行审批会**叠加在**工具策略和 elevated 门控之上（除非 elevated 设为 `full`，这会跳过审批）。
执行审批是**配套应用 / 节点主机防护栏**，用于让处于沙箱隔离的智能体在真实主机（`gateway` 或 `node`）上运行命令。这是一种安全联锁机制：只有当策略 + 允许列表 +（可选）用户审批全部同意时，命令才会被允许执行。执行审批叠加在工具策略和 elevated 门控机制**之上**（除非 elevated 设为 `full`，此时会跳过审批）。
<Note>
生效策略取 `tools.exec.*` 与审批默认值中**更严格**的一方；如果某个 approvals 字段被省略，则使用 `tools.exec` 的值。主机执行还会使用该机器上的本地 approvals 状态——如果 `~/.openclaw/exec-approvals.json` 中的主机本地 `ask: "always"` 已设置，即使会话或配置默认值请求 `ask: "on-miss"`，也仍然会持续弹出提示。
生效策略是 `tools.exec.*` 与审批默认值中**更严格**的那一个；如果某个审批字段被省略，则使用 `tools.exec` 的值。主机执行还会使用该机器上的本地审批状态——如果 `~/.openclaw/exec-approvals.json` 中存在主机本地的 `ask: "always"`，即使会话或配置默认值请求 `ask: "on-miss"`，系统仍然会持续提示。
</Note>
## 检查生效策略
- `openclaw approvals get`、`... --gateway`、`... --node <id|name|ip>` —— 显示请求的策略、主机策略来源，以及最终生效结果。
- `openclaw approvals get`、`... --gateway`、`... --node <id|name|ip>` —— 显示请求的策略、主机策略来源以及最终生效结果。
- `openclaw exec-policy show` —— 显示本地机器上的合并视图。
- `openclaw exec-policy set|preset` —— 一步同时同步本地请求策略和本地主机 approvals 文件。
- `openclaw exec-policy set|preset` —— 一步完成，将本地请求的策略与本地主机审批文件同步。
当本地作用域请求 `host=node` 时，`exec-policy show` 会在运行时将该作用域报告为由节点管理，而不是假装本地 approvals 文件才是事实来源。
当本地作用域请求 `host=node` 时，`exec-policy show` 会在运行时将该作用域报告为由节点管理，而不是假装本地审批文件是真实来源。
如果配套应用 UI **不可用**，任何原本需要弹出提示的请求都会通过 **ask fallback** 处理（默认：拒绝）。
如果配套应用 UI **不可用**，任何通常需要提示的请求都会由 **ask fallback** 处理（默认：拒绝）。
<Tip>
原生聊天审批客户端可以在待审批消息上预置特定渠道的便捷交互。例如，Matrix 会预置反应快捷方式（`✅`
允许一次、`❌` 拒绝、`♾️` 始终允许），同时仍然在消息中保留 `/approve ...`
命令作为后备方式。
原生聊天审批客户端可以在待审批消息上预置特定渠道的便捷交互。例如，Matrix 会预置反应快捷方式（`✅` 允许一次、`❌` 拒绝、`♾️` 始终允许），同时仍在消息中保留 `/approve ...` 命令作为后备方案。
</Tip>
## 适用范围
执行审批会在执行主机本地强制生效：
执行审批会在执行主机本地强制执行：
- **Gateway 网关主机** → Gateway 网关机器上的 `openclaw` 进程
- **节点主机** → 节点运行器（macOS 配套应用或无头节点主机）
- **gateway host** → Gateway 机器上的 `openclaw` 进程
- **node host** → 节点运行器（macOS 配套应用或无头节点主机）
信任模型说明：
- 通过 Gateway 网关认证的调用方，是该 Gateway 网关的受信任操作员。
- 已配对节点会将这种受信任操作员能力扩展到节点主机。
- 执行审批会降低误执行风险，但它并不是按用户划分的身份验证边界。
- 已批准的节点主机执行会绑定规范化执行上下文：规范化 `cwd`、精确 `argv`、存在时的环境变量绑定，以及适用时固定的可执行文件路径。
- 对于 shell 脚本以及直接调用解释器 / 运行时文件的情况，OpenClaw 还会尝试绑定一个具体的本地文件操作数。如果该绑定文件在审批后、执行前发生变化，则会拒绝执行，而不是执行已漂移的内容。
- 这种文件绑定有意设计为尽力而为，并不是对每一种解释器 / 运行时加载路径的完整语义建模。如果审批模式无法识别出**恰好一个**可绑定的具体本地文件，它会拒绝签发基于审批的执行，而不是假装已经完全覆盖。
- 通过 Gateway 认证的调用方，是该 Gateway 网关的受信任操作员。
- 已配对节点会将这种受信任操作员能力扩展到节点主机上。
- 执行审批可以降低意外执行风险，但并不是按用户划分的身份验证边界。
- 已批准的节点主机执行会绑定规范化执行上下文：规范化的 cwd、精确的 argv、存在时的 env 绑定，以及适用时固定的可执行文件路径。
- 对于 shell 脚本和直接的解释器 / 运行时文件调用，OpenClaw 还会尝试绑定一个具体的本地文件操作数。如果该绑定文件在审批后、执行前发生变化，运行将被拒绝，而不是执行已漂移的内容。
- 这种文件绑定是有意设计为“尽力而为”，而不是覆盖所有解释器 / 运行时加载路径的完整语义模型。如果审批模式无法识别并绑定**恰好一个**具体本地文件，它将拒绝签发基于审批的运行，而不是假装已经完全覆盖。
macOS 拆分：
- **节点主机服务** 通过本地 IPC 将 `system.run` 转发给 **macOS 应用**。
- **macOS 应用** 负责执行审批并在 UI 上下文中运行命令。
- **node host service** 通过本地 IPC 将 `system.run` 转发给 **macOS app**。
- **macOS app** 负责执行审批 + 在 UI 上下文中运行命令。
## 设置与存储
审批信息保存在执行主机上的本地 JSON 文件中：
审批存储在执行主机上的本地 JSON 文件中：
`~/.openclaw/exec-approvals.json`
@ -100,33 +98,30 @@ macOS 拆分：
## 无需审批的 “YOLO” 模式
如果你希望主机执行在没有审批提示的情况下运行，你必须同时放开**两层**策略：
如果你希望主机执行在没有审批提示的情况下运行，必须同时放开**两个**策略层：
- OpenClaw 配置中的请求执行策略（`tools.exec.*`）
- `~/.openclaw/exec-approvals.json` 中的主机本地 approvals 策略
- `~/.openclaw/exec-approvals.json` 中主机本地的审批策略
现在这已是默认主机行为，除非你显式收紧它：
除非你显式收紧，否则这现在是默认的主机行为：
- `tools.exec.security`: 在 `gateway` / `node` 上设为 `full`
- `tools.exec.ask`: `off`
- 主机 `askFallback`: `full`
- `tools.exec.security`：在 `gateway` / `node` 上设为 `full`
- `tools.exec.ask`：设为 `off`
- 主机 `askFallback`：设为 `full`
重要区别：
- `tools.exec.host=auto` 选择执行运行的位置：有沙箱时在沙箱中，否则在 Gateway 网关上。
- YOLO 选择的是主机执行的审批方式：`security=full` 加 `ask=off`。
- 暴露自身非交互权限模式的基于 CLI 的提供商可以遵循此策略。
Claude CLI 会在 OpenClaw 的请求执行策略为
YOLO 时添加 `--permission-mode bypassPermissions`。你可以在
`agents.defaults.cliBackends.claude-cli.args` / `resumeArgs` 下通过显式 Claude 参数覆盖该后端行为，例如
`--permission-mode default`、`acceptEdits` 或 `bypassPermissions`。
- 在 YOLO 模式下，OpenClaw 不会在已配置的主机执行策略之上，再额外添加独立的启发式命令混淆审批门控或脚本预检拒绝层。
- `auto` 不会让 Gateway 网关路由成为沙箱隔离会话中的免费覆盖选项。允许从 `auto` 发起单次调用的 `host=node` 请求，而只有在没有活动沙箱运行时时，才允许从 `auto` 发起 `host=gateway`。如果你希望获得稳定的非 auto 默认值，请设置 `tools.exec.host` 或显式使用 `/exec host=...`。
- `tools.exec.host=auto` 决定执行在哪里运行：有沙箱时在沙箱中，否则在 gateway 上运行。
- YOLO 决定主机执行如何获批：`security=full` 加 `ask=off`。
- 暴露其自身非交互权限模式的基于 CLI 的提供商可以遵循此策略。
当 OpenClaw 请求的执行策略为 YOLO 时，Claude CLI 会添加 `--permission-mode bypassPermissions`。你可以通过 `agents.defaults.cliBackends.claude-cli.args` / `resumeArgs` 下的显式 Claude 参数覆盖该后端行为，例如 `--permission-mode default`、`acceptEdits` 或 `bypassPermissions`。
- 在 YOLO 模式下，OpenClaw 不会在已配置的主机执行策略之上，额外添加单独的启发式命令混淆审批门控或脚本预检拒绝层。
- `auto` 不会让 gateway 路由成为来自沙箱隔离会话的免费覆盖项。每次调用的 `host=node` 请求可在 `auto` 下被允许，而 `host=gateway` 只有在没有活动沙箱运行时时，才可从 `auto` 被允许。如果你想要稳定的非 auto 默认值，请设置 `tools.exec.host`，或显式使用 `/exec host=...`。
如果你想使用更保守的设置，可以将任一层收紧回 `allowlist` / `on-miss`
如果你想采用更保守的设置，可以将任一层重新收紧为 `allowlist` / `on-miss`
或 `deny`。
持久化的 Gateway 网关主机 “永不提示” 设置：
持久化的 gateway host “永不提示” 设置：
```bash
openclaw config set tools.exec.host gateway
@ -135,7 +130,7 @@ openclaw config set tools.exec.ask off
openclaw gateway restart
```
然后将主机 approvals 文件设置为匹配值：
然后将主机审批文件设置为匹配值：
```bash
openclaw approvals set --stdin <<'EOF'
@ -150,7 +145,7 @@ openclaw approvals set --stdin <<'EOF'
EOF
```
用于在当前机器上设置相同 Gateway 网关主机策略的本地快捷方式：
在当前机器上应用相同 gateway host 策略的本地快捷方式：
```bash
openclaw exec-policy preset yolo
@ -161,11 +156,10 @@ openclaw exec-policy preset yolo
- 本地 `tools.exec.host/security/ask`
- 本地 `~/.openclaw/exec-approvals.json` 默认值
它有意仅在本地生效。如果你需要远程更改 Gateway 网关主机或节点主机审批，
请继续使用 `openclaw approvals set --gateway` 或
它有意只作用于本地。如果你需要远程更改 gateway host 或 node host 审批，请继续使用 `openclaw approvals set --gateway` 或
`openclaw approvals set --node <id|name|ip>`。
对于节点主机，请在该节点上应用相同的 approvals 文件：
对于节点主机，请改为在该节点上应用相同的审批文件：
```bash
openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
@ -184,16 +178,16 @@ EOF
- `openclaw exec-policy` 不会同步节点审批
- `openclaw exec-policy set --host node` 会被拒绝
- 节点执行审批会在运行时从节点获取，因此面向节点的更新必须使用 `openclaw approvals --node ...`
- 节点执行审批会在运行时从节点获取，因此针对节点的更新必须使用 `openclaw approvals --node ...`
仅限当前会话的快捷方式：
仅会话快捷方式：
- `/exec security=full ask=off` 只会更改当前会话。
- `/elevated full` 是一个紧急放行快捷方式，也会跳过该会话的执行审批。
- `/elevated full` 是一个紧急破窗快捷方式，也会为该会话跳过执行审批。
如果主机 approvals 文件仍然比配置更严格，那么更严格的主机策略依然会生效。
如果主机审批文件仍比配置更严格，仍以更严格的主机策略为准。
## 策略旋钮
## 策略开关
### 安全性（`exec.security`）
@ -204,21 +198,21 @@ EOF
### 询问（`exec.ask`）
- **off**：从不提示。
- **on-miss**：仅在允许列表不匹配时提示。
- **always**：每条命令都提示。
- 当生效的 ask 模式为 `always` 时，`allow-always` 的持久信任不会抑制提示
- **on-miss**：仅当允许列表不匹配时提示。
- **always**：每个命令都提示。
- 当生效的询问模式为 `always` 时，`allow-always` 的持久信任不会抑制提示
### 询问回退（`askFallback`）
### 询问后备（`askFallback`）
如果需要提示，但没有可达的 UI，则由 fallback 决定：
如果需要提示但没有可达的 UI，则由后备策略决定：
- **deny**：阻止。
- **allowlist**：仅在允许列表匹配时允许。
- **allowlist**：仅当允许列表匹配时允许。
- **full**：允许。
### 行内解释器求值加固（`tools.exec.strictInlineEval`）
### 内联解释器 eval 加固（`tools.exec.strictInlineEval`）
当 `tools.exec.strictInlineEval=true` 时，即使解释器二进制本身已在允许列表中，OpenClaw 也会将行内代码求值形式视为仅可通过审批执行。
当 `tools.exec.strictInlineEval=true` 时，即使解释器二进制本身在允许列表中，OpenClaw 也会将内联代码求值形式视为“仅可通过审批执行”。
示例：
@ -230,52 +224,51 @@ EOF
- `lua -e`
- `osascript -e`
这是针对无法清晰映射到单一稳定文件操作数的解释器加载路径所做的纵深防御。在严格模式下：
这是对那些无法干净映射到单一稳定文件操作数的解释器加载路径所做的纵深防御。在严格模式下：
- 这些命令仍然需要显式审批；
- `allow-always` 不会自动为它们持久化新的允许列表条目。
- `allow-always` 不会自动为它们持久保存新的允许列表条目。
## 允许列表（按智能体划分）
## 允许列表（按智能体）
允许列表是**按智能体**划分的。如果存在多个智能体，请在 macOS 应用中切换你正在编辑的智能体。模式为**不区分大小写的 glob 匹配**。
模式应解析为**二进制路径**（仅文件名的条目会被忽略）。
允许列表是**按智能体**划分的。如果存在多个智能体，请在 macOS 应用中切换你要编辑的智能体。模式使用 glob 匹配。
模式可以是已解析的二进制路径 glob，也可以是裸命令名 glob。裸名称只匹配通过 PATH 调用的命令，因此当命令是 `rg` 时，`rg` 可以匹配 `/opt/homebrew/bin/rg`，但不能匹配 `./rg` 或 `/tmp/rg`。如果你想信任某一个特定的二进制位置，请使用路径 glob。
旧版 `agents.default` 条目会在加载时迁移到 `agents.main`。
像 `echo ok && pwd` 这样的 shell 链式命令，仍然要求每个顶层片段都满足允许列表规则。
示例：
- `rg`
- `~/Projects/**/bin/peekaboo`
- `~/.local/bin/*`
- `/opt/homebrew/bin/rg`
每个允许列表条目会跟踪：
- **id**：用于 UI 标识的稳定 UUID（可选）
- **上次使用**
- **上次使用的命令**
- **上次解析的路径**
- **id**：供 UI 标识使用的稳定 UUID（可选）
- **last used**：上次使用时间戳
- **last used command**
- **last resolved path**
## 自动允许技能 CLI
## 自动允许 Skill CLI
当启用 **Auto-allow skill CLIs** 时，已知 Skills 引用的可执行文件会在节点上（macOS 节点或无头节点主机）被视为已加入允许列表。此功能会通过 Gateway 网关 RPC 使用
`skills.bins` 获取 Skills 二进制列表。如果你希望严格使用手动允许列表，请禁用此项。
启用 **Auto-allow skill CLIs** 后，已知 Skills 引用的可执行文件会在节点上（macOS 节点或无头节点主机）被视为已加入允许列表。这会通过 Gateway RPC 使用 `skills.bins` 获取 skill 二进制列表。如果你想使用严格的手动允许列表，请关闭此选项。
重要信任说明：
- 这是一个**隐式的便捷允许列表**，与手动路径允许列表条目分开。
- 它适用于 Gateway 网关与节点位于同一信任边界内的受信任操作员环境。
- 它适用于 Gateway 网关与节点处于同一信任边界内的受信任操作员环境。
- 如果你需要严格的显式信任，请保持 `autoAllowSkills: false`，并仅使用手动路径允许列表条目。
## 安全二进制与审批转发
有关安全二进制（仅 stdin 的快速路径）、解释器绑定细节，以及如何将审批提示转发到 Slack/Discord/Telegram（或将它们作为原生审批客户端运行），请参阅 [Exec approvals — advanced](/zh-CN/tools/exec-approvals-advanced)。
关于安全二进制（仅 stdin 的快速路径）、解释器绑定细节，以及如何将审批提示转发到 Slack/Discord/Telegram（或将它们作为原生审批客户端运行），请参见 [执行审批——高级](/zh-CN/tools/exec-approvals-advanced)。
<!-- moved to /tools/exec-approvals-advanced -->
## Control UI 编辑
使用 **Control UI → Nodes → Exec approvals** 卡片来编辑默认值、按智能体划分的覆盖项和允许列表。选择一个作用域（默认值或某个智能体），调整策略，
添加 / 删除允许列表模式，然后点击 **Save**。UI 会显示每个模式的**上次使用**元数据，方便你保持列表整洁。
使用 **Control UI → Nodes → Exec approvals** 卡片来编辑默认值、按智能体的覆盖项和允许列表。选择一个作用域（默认值或某个智能体），调整策略，添加 / 删除允许列表模式，然后点击 **Save**。UI 会为每个模式显示 **last used** 元数据，方便你保持列表整洁。
目标选择器可选择 **Gateway**（本地审批）或 **Node**。节点必须声明 `system.execApprovals.get/set`（macOS 应用或无头节点主机）。
如果某个节点尚未声明执行审批，请直接编辑其本地
@ -285,68 +278,67 @@ CLI：`openclaw approvals` 支持编辑 gateway 或 node（参见 [Approvals CLI
## 审批流程
当需要提示时，Gateway 网关会向操作员客户端广播 `exec.approval.requested`。
Control UI 和 macOS 应用通过 `exec.approval.resolve` 处理它，然后 Gateway 网关将
已批准的请求转发到节点主机。
当需要提示时，gateway 会向操作员客户端广播 `exec.approval.requested`。
Control UI 和 macOS 应用通过 `exec.approval.resolve` 进行处理，然后 gateway 会将已批准的请求转发到节点主机。
对于 `host=node`，审批请求包含规范化的 `systemRunPlan` 负载。Gateway 网关在转发已批准的 `system.run`
请求时，会将该计划作为权威的命令 / `cwd` / 会话上下文。
对于 `host=node`，审批请求会包含规范化的 `systemRunPlan` 负载。gateway 在转发已批准的 `system.run`
请求时，会将该 plan 作为权威的命令 / cwd / 会话上下文。
这对异步审批延迟很重要：
这对于异步审批延迟很重要：
- 节点执行路径会预先准备一个规范化计划
- 审批记录会存储该计划及其绑定元数据
- 一旦获批，最终转发的 `system.run` 调用会复用已存储的计划
而不是信任调用方后续的编辑
- 如果调用方在创建审批请求后更改了 `command`、`rawCommand`、`cwd`、`agentId` 或
`sessionKey`，Gateway 网关会将转发执行拒绝为审批不匹配
- 节点执行路径会预先准备一个规范化 plan
- 审批记录会存储该 plan 及其绑定元数据
- 一旦获批，最终转发的 `system.run` 调用会复用已存储的 plan
而不是信任调用方后续的修改
- 如果审批请求创建后，调用方更改了 `command`、`rawCommand`、`cwd`、`agentId` 或
`sessionKey`，gateway 会将该转发运行拒绝为审批不匹配
## 系统事件
执行生命周期会以系统消息的形式呈现：
执行生命周期会作为系统消息呈现：
- `Exec running`（仅当命令超过运行中通知阈值时）
- `Exec running`（仅当命令超过“正在运行”通知阈值时显示）
- `Exec finished`
- `Exec denied`
这些消息会在节点报告事件后发布到智能体的会话中。
Gateway 网关主机执行审批在命令结束时也会发出相同的生命周期事件（如果运行时间超过阈值，也可选发出运行中事件）。
这些消息会在节点上报事件后发布到智能体的会话中。
gateway host 执行审批也会在命令结束时发出相同的生命周期事件（如果运行时间超过阈值，也会在运行中发出可选事件）。
受审批门控的执行会在这些消息中复用审批 id 作为 `runId`，以便轻松关联。
## 审批被拒绝时的行为
当异步执行审批被拒绝时，OpenClaw 会阻止智能体在会话中复用同一命令任何更早一次运行的输出。拒绝原因会连同明确说明一起传递，指出没有可用的命令输出，从而阻止智能体声称存在新的输出，或在使用先前成功运行留下的陈旧结果时重复被拒绝的命令。
当异步执行审批被拒绝时，OpenClaw 会阻止智能体复用该会话中此前同一命令任意一次运行的输出。拒绝原因会连同明确指引一起传递，说明没有可用的命令输出，这样可阻止智能体声称存在新的输出，或使用先前成功运行的陈旧结果重复已被拒绝的命令。
## 影响
- **full** 权限很强；尽可能优先使用允许列表。
- **ask** 可以让你保持知情，同时仍支持快速审批。
- 按智能体划分的允许列表可以防止某个智能体的审批泄漏到其他智能体。
- **full** 权限很强；如果可能，优先使用允许列表。
- **ask** 让你保持参与审批流程，同时仍可实现快速审批。
- 按智能体划分的允许列表可防止一个智能体的审批泄漏到其他智能体。
- 审批仅适用于来自**已授权发送方**的主机执行请求。未授权发送方无法发出 `/exec`。
- `/exec security=full` 是面向已授权操作员的会话级便捷方式，并且按设计会跳过审批。要硬性阻止主机执行，请将 approvals security 设为 `deny`，或通过工具策略拒绝 `exec` 工具。
- `/exec security=full` 是面向已授权操作员的会话级便捷方式，并且按设计会跳过审批。若要强制阻止主机执行，请将审批安全性设为 `deny`，或通过工具策略拒绝 `exec` 工具。
## 相关内容
<CardGroup cols={2}>
<Card title="Exec approvals — advanced" href="/zh-CN/tools/exec-approvals-advanced" icon="gear">
安全二进制、解释器绑定，以及向聊天转发审批。
<Card title="执行审批——高级" href="/zh-CN/tools/exec-approvals-advanced" icon="gear">
安全二进制、解释器绑定以及将审批转发到聊天渠道。
</Card>
<Card title="Exec tool" href="/zh-CN/tools/exec" icon="terminal">
<Card title="Exec 工具" href="/zh-CN/tools/exec" icon="terminal">
Shell 命令执行工具。
</Card>
<Card title="Elevated mode" href="/zh-CN/tools/elevated" icon="shield-exclamation">
也会跳过审批的紧急放行路径。
<Card title="Elevated 模式" href="/zh-CN/tools/elevated" icon="shield-exclamation">
也会跳过审批的紧急破窗路径。
</Card>
<Card title="Sandboxing" href="/zh-CN/gateway/sandboxing" icon="box">
<Card title="沙箱隔离" href="/zh-CN/gateway/sandboxing" icon="box">
沙箱模式与工作区访问。
</Card>
<Card title="Security" href="/zh-CN/gateway/security" icon="lock">
<Card title="安全性" href="/zh-CN/gateway/security" icon="lock">
安全模型与加固。
</Card>
<Card title="Sandbox vs tool policy vs elevated" href="/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated" icon="sliders">
何时应使用各类控制方式。
<Card title="沙箱隔离 vs 工具策略 vs elevated" href="/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated" icon="sliders">
何时应使用各项控制。
</Card>
<Card title="Skills" href="/zh-CN/tools/skills" icon="sparkles">
基于 Skills 的自动允许行为。
由 Skills 支持的自动允许行为。
</Card>
</CardGroup>

166
docs/zh-CN/tools/exec.md
View File

@ -1,14 +1,14 @@
---
read_when:
- 使用或修改 exec 工具
- 使用或修改 Exec 工具
- 调试 stdin 或 TTY 行为
summary: Exec 工具用法、stdin 模式和 TTY 支持
title: Exec 工具
x-i18n:
generated_at: "2026-04-23T23:21:50Z"
generated_at: "2026-04-25T03:25:10Z"
model: gpt-5.4
provider: openai
source_hash: 4cad17fecfaf7d6a523282ef4f0090e4ffaab89ab53945b5cd831e426f3fc3ac
source_hash: 358f9155120382fa2b03b22e22408bdb9e51715f80c8b1701a1ff7fd05850188
source_path: tools/exec.md
workflow: 15
---
@ -28,11 +28,11 @@ x-i18n:
</ParamField>
<ParamField path="env" type="object">
叠加到继承环境之上的键/值环境变量覆盖。
在继承环境之上合并的键 / 值环境变量覆盖。
</ParamField>
<ParamField path="yieldMs" type="number" default="10000">
在这段延迟（毫秒）后自动将命令转入后台。
在此延迟（毫秒）后自动将命令转入后台。
</ParamField>
<ParamField path="background" type="boolean" default="false">
@ -40,68 +40,68 @@ x-i18n:
</ParamField>
<ParamField path="timeout" type="number" default="1800">
在这么多秒后终止该命令。
在这么多秒后终止命令。
</ParamField>
<ParamField path="pty" type="boolean" default="false">
在可用时于伪终端中运行。适用于仅支持 TTY 的 CLI、编码智能体和终端 UI。
在可用时于伪终端中运行。用于仅支持 TTY 的 CLI、编码智能体和终端 UI。
</ParamField>
<ParamField path="host" type="'auto' | 'sandbox' | 'gateway' | 'node'" default="auto">
执行位置。`auto` 会在当前会话启用了沙箱运行时时解析为 `sandbox`，否则解析为 `gateway`。
执行位置。启用了沙箱运行时时，`auto` 解析为 `sandbox`，否则解析为 `gateway`。
</ParamField>
<ParamField path="security" type="'deny' | 'allowlist' | 'full'">
`gateway` / `node` 执行的强制策略模式。
用于 `gateway` / `node` 执行的强制模式。
</ParamField>
<ParamField path="ask" type="'off' | 'on-miss' | 'always'">
`gateway` / `node` 执行的审批提示行为。
用于 `gateway` / `node` 执行的批准提示行为。
</ParamField>
<ParamField path="node" type="string">
当 `host=node` 时使用的节点 id/名称。
当 `host=node` 时的节点 id / 名称。
</ParamField>
<ParamField path="elevated" type="boolean" default="false">
请求提升模式——跳出沙箱并切换到已配置的主机路径。只有当 elevated 解析为 `full` 时，才会强制 `security=full`。
请求提升模式——从沙箱逃逸到已配置的宿主路径。仅当 elevated 解析为 `full` 时，才会强制 `security=full`。
</ParamField>
说明：
- `host` 默认为 `auto`：当会话启用了沙箱运行时时为 `sandbox`，否则为 `gateway`。
- `auto` 是默认路由策略，不是通配符。在 `auto` 下，每次调用都允许 `host=node`；只有在当前没有启用沙箱运行时时，每次调用才允许 `host=gateway`。
- 不做额外配置时，`host=auto` 依然能够“开箱即用”：没有沙箱时，它会解析为 `gateway`；存在活动沙箱时，它会保留在沙箱中。
- `elevated` 会跳出沙箱并切换到已配置的主机路径：默认是 `gateway`，或者当 `tools.exec.host=node`（或会话默认值是 `host=node`）时为 `node`。只有当前会话/提供商启用了提升访问时，此选项才可用。
- `gateway`/`node` 的审批由 `~/.openclaw/exec-approvals.json` 控制。
- `node` 需要一个已配对的节点（配套应用或无头节点主机）。
- 如果有多个节点可用，请设置 `exec.node` 或 `tools.exec.node` 来选择其中一个。
- `exec host=node` 是节点唯一的 shell 执行路径；旧版 `nodes.run` 包装器已移除。
- 在非 Windows 主机上，exec 会优先使用已设置的 `SHELL`；如果 `SHELL` 是 `fish`，它会优先从 `PATH` 中选择 `bash`（或 `sh`）以避免与 fish 不兼容的脚本问题；如果两者都不存在，才会回退到 `SHELL`。
- 在 Windows 主机上，exec 会优先发现 PowerShell 7（Program Files、ProgramW6432，然后是 PATH），然后回退到 Windows PowerShell 5.1。
- 主机执行（`gateway`/`node`）会拒绝 `env.PATH` 和加载器覆盖（`LD_*`/`DYLD_*`），以防止二进制劫持或注入代码。
- OpenClaw 会在生成的命令环境中设置 `OPENCLAW_SHELL=exec`（包括 PTY 和沙箱执行），以便 shell/profile 规则识别 exec 工具上下文。
- 重要：默认情况下，沙箱隔离是**关闭**的。如果沙箱隔离关闭，隐式 `host=auto` 会解析为 `gateway`。显式 `host=sandbox` 仍会以关闭失败的方式处理，而不是静默在 Gateway 网关主机上运行。请启用沙箱隔离，或结合审批使用 `host=gateway`。
- 脚本预检（用于发现常见的 Python/Node shell 语法错误）只会检查有效 `workdir` 边界内的文件。如果脚本路径解析到 `workdir` 之外，则会跳过该文件的预检。
- 对于现在开始的长时间运行任务，只需启动一次，并在启用了自动完成唤醒且命令输出内容或失败时依赖自动唤醒。
- `host` 默认为 `auto`：如果当前会话启用了沙箱运行时，则为 `sandbox`，否则为 `gateway`。
- `auto` 是默认路由策略，不是通配符。允许在单次调用中使用 `host=node`；仅当未启用沙箱运行时时，才允许在单次调用中使用 `host=gateway`。
- 在没有额外配置时，`host=auto` 仍然可以“直接工作”：没有沙箱时，它会解析为 `gateway`；有活动沙箱时，它会保留在沙箱中。
- `elevated` 会从沙箱逃逸到已配置的宿主路径：默认是 `gateway`，或者当 `tools.exec.host=node`（或会话默认值为 `host=node`）时为 `node`。只有当前会话 / 提供商启用了提升访问时才可用。
- `gateway`/`node` 批准由 `~/.openclaw/exec-approvals.json` 控制。
- `node` 需要一个已配对的节点（配套应用或无头节点宿主）。
- 如果有多个可用节点，请设置 `exec.node` 或 `tools.exec.node` 进行选择。
- `exec host=node` 是节点唯一的 shell 执行路径；旧版 `nodes.run` 包装器已被移除。
- 在非 Windows 宿主上，如果设置了 `SHELL`，exec 会使用它；如果 `SHELL` 是 `fish`，则会优先从 `PATH` 中选择 `bash`（或 `sh`）以避免与 fish 不兼容的脚本，然后在两者都不存在时回退到 `SHELL`。
- 在 Windows 宿主上，exec 会优先发现 PowerShell 7（`pwsh`）（依次检查 Program Files、ProgramW6432、再到 PATH），然后回退到 Windows PowerShell 5.1。
- 宿主执行（`gateway`/`node`）会拒绝 `env.PATH` 和加载器覆盖（`LD_*`/`DYLD_*`），以防止二进制劫持或注入代码。
- OpenClaw 会在生成的命令环境中设置 `OPENCLAW_SHELL=exec`（包括 PTY 和沙箱执行），这样 shell / profile 规则就能检测到 exec 工具上下文。
- 重要：默认情况下**关闭**沙箱隔离。如果沙箱隔离关闭，隐式 `host=auto` 会解析为 `gateway`。显式 `host=sandbox` 仍会以失败关闭的方式处理，而不是悄悄地在 gateway 宿主上运行。请启用沙箱隔离，或使用带批准的 `host=gateway`。
- 脚本预检（用于常见的 Python/Node shell 语法错误）仅检查有效 `workdir` 边界内的文件。如果脚本路径解析到 `workdir` 之外，则会跳过该文件的预检。
- 对于现在开始的长时间运行工作，只启动一次，并在启用了自动完成唤醒且命令产生输出或失败时依赖自动完成唤醒。
使用 `process` 处理日志、状态、输入或干预；不要用 sleep 循环、timeout 循环或重复轮询来模拟调度。
- 对于应稍后执行或按计划执行的任务，请使用 cron，而不是
`exec` 的 sleep/delay 模式。
- 对于应稍后执行或按计划执行的工作，请使用 cron，而不是
`exec` 的 sleep / delay 模式。
## 配置
- `tools.exec.notifyOnExit`（默认：true）：为 true 时，已后台化的 exec 会话在退出时会入队一个系统事件并请求一次 heartbeat。
- `tools.exec.approvalRunningNoticeMs`（默认：10000）：当需要审批的 exec 运行超过该时长时发出一次“正在运行”通知（设为 0 可禁用）。
- `tools.exec.host`（默认：`auto`；当沙箱运行时处于活动状态时解析为 `sandbox`，否则为 `gateway`）
- `tools.exec.notifyOnExit`（默认：true）：为 true 时，转入后台的 exec 会话会在退出时排入一个系统事件并请求一次心跳。
- `tools.exec.approvalRunningNoticeMs`（默认：10000）：当需要批准的 exec 运行时间超过此值时，发出一次“运行中”通知（设为 0 可禁用）。
- `tools.exec.host`（默认：`auto`；启用了沙箱运行时时解析为 `sandbox`，否则为 `gateway`）
- `tools.exec.security`（默认：沙箱为 `deny`，未设置时 gateway + node 为 `full`）
- `tools.exec.ask`（默认：`off`）
- 对 gateway + node 来说，默认是无需审批的主机 exec。如果你想启用审批/allowlist 行为，请同时收紧 `tools.exec.*` 和主机上的 `~/.openclaw/exec-approvals.json`；参见 [Exec 审批](/zh-CN/tools/exec-approvals#no-approval-yolo-mode)。
- YOLO 来自主机策略默认值（`security=full`、`ask=off`），而不是 `host=auto`。如果你想强制使用 gateway 或 node 路由，请设置 `tools.exec.host` 或使用 `/exec host=...`。
- 在 `security=full` 加 `ask=off` 模式下，主机 exec 会直接遵循已配置的策略；不会额外增加启发式命令混淆预过滤器或脚本预检拒绝层。
- 无需批准的宿主 exec 是 gateway + node 的默认行为。如果你希望使用批准 / allowlist 行为，请同时收紧 `tools.exec.*` 和宿主 `~/.openclaw/exec-approvals.json`；参见 [Exec approvals](/zh-CN/tools/exec-approvals#no-approval-yolo-mode)。
- YOLO 来自宿主策略默认值（`security=full`、`ask=off`），而不是 `host=auto`。如果你想强制使用 gateway 或 node 路由，请设置 `tools.exec.host` 或使用 `/exec host=...`。
- 在 `security=full` 且 `ask=off` 模式下，宿主 exec 会直接遵循已配置策略；不会有额外的启发式命令混淆预过滤层，也不会有脚本预检拒绝层。
- `tools.exec.node`（默认：未设置）
- `tools.exec.strictInlineEval`（默认：false）：为 true 时，内联解释器求值形式，如 `python -c`、`node -e`、`ruby -e`、`perl -e`、`php -r`、`lua -e` 和 `osascript -e`，始终需要显式审批。`allow-always` 仍可持久放行无害的解释器/脚本调用，但内联求值形式每次仍会提示。
- `tools.exec.pathPrepend`：在 exec 运行时预置到 `PATH` 前部的目录列表（仅 gateway + sandbox）。
- `tools.exec.safeBins`：仅通过 stdin 使用、可在无需显式 allowlist 条目的情况下运行的安全二进制。有关行为细节，请参见 [Safe bins](/zh-CN/tools/exec-approvals-advanced#safe-bins-stdin-only)。
- `tools.exec.strictInlineEval`（默认：false）：为 true 时，内联解释器求值形式，如 `python -c`、`node -e`、`ruby -e`、`perl -e`、`php -r`、`lua -e` 和 `osascript -e`，始终需要显式批准。`allow-always` 仍可持久化良性的解释器 / 脚本调用，但内联求值形式每次仍会提示。
- `tools.exec.pathPrepend`：在 exec 运行前追加到 `PATH` 前面的目录列表（仅 gateway + sandbox）。
- `tools.exec.safeBins`：仅 stdin 的安全二进制，可在没有显式 allowlist 条目的情况下运行。有关行为细节，请参见 [Safe bins](/zh-CN/tools/exec-approvals-advanced#safe-bins-stdin-only)。
- `tools.exec.safeBinTrustedDirs`：用于 `safeBins` 路径检查的额外显式可信目录。`PATH` 条目永远不会被自动信任。内置默认值为 `/bin` 和 `/usr/bin`。
- `tools.exec.safeBinProfiles`：可选的每个 safe bin 自定义 argv 策略（`minPositional`、`maxPositional`、`allowedValueFlags`、`deniedFlags`）。
@ -119,13 +119,14 @@ x-i18n:
### PATH 处理
- `host=gateway`：将你的登录 shell `PATH` 合并进 exec 环境。主机执行会拒绝 `env.PATH` 覆盖。守护进程本身仍以最小化 `PATH` 运行：
- `host=gateway`：将你的登录 shell `PATH` 合并到 exec 环境中。宿主执行会拒绝 `env.PATH` 覆盖。不过守护进程本身仍使用一个最小化的 `PATH`：
- macOS：`/opt/homebrew/bin`、`/usr/local/bin`、`/usr/bin`、`/bin`
- Linux：`/usr/local/bin`、`/usr/bin`、`/bin`
- `host=sandbox`：在容器内运行 `sh -lc`（登录 shell），因此 `/etc/profile` 可能会重置 `PATH`。
OpenClaw 会在 profile 加载之后通过内部环境变量将 `env.PATH` 预置到前部（不进行 shell 插值）；`tools.exec.pathPrepend` 在这里同样适用。
- `host=node`：只有你传入的、未被拦截的环境覆盖会被发送到节点。主机执行会拒绝 `env.PATH` 覆盖，而节点主机也会忽略它。如果你需要在节点上添加额外的 PATH 条目，
请配置节点主机服务环境（systemd/launchd），或将工具安装到标准位置。
OpenClaw 会在 profile source 之后，通过一个内部环境变量（不使用 shell 插值）将 `env.PATH` 追加到前面；
`tools.exec.pathPrepend` 在这里同样适用。
- `host=node`：只会将你传入的未被阻止的环境变量覆盖发送到节点。宿主执行会拒绝 `env.PATH` 覆盖，节点宿主也会忽略它们。如果你需要在节点上添加额外的 PATH 条目，
请配置节点宿主服务环境（systemd/launchd），或将工具安装到标准位置。
按智能体绑定节点（在配置中使用智能体列表索引）：
@ -134,84 +135,83 @@ openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
```
控制 UI：Nodes 选项卡包含一个小型“Exec 节点绑定”面板，用于设置相同的配置。
控制 UI：Nodes 标签页包含一个小型“Exec node binding”面板，用于配置相同设置。
## 会话覆盖（`/exec`）
使用 `/exec` 设置**按会话生效**的 `host`、`security`、`ask` 和 `node` 默认值。
使用 `/exec` 设置**按会话**的 `host`、`security`、`ask` 和 `node` 默认值。
发送不带参数的 `/exec` 可显示当前值。
示例：
```
```text
/exec host=auto security=allowlist ask=on-miss node=mac-1
```
## 授权模型
`/exec` 仅对**已授权的发送方**生效（渠道 allowlist/配对 + `commands.useAccessGroups`）。
它只更新**会话状态**，不会写入配置。若要彻底禁用 exec，请通过工具
策略拒绝它（`tools.deny: ["exec"]` 或按智能体配置）。除非你显式设置
`security=full` 且 `ask=off`，否则主机审批仍然适用。
`/exec` 仅对**已授权发送者**生效（渠道 allowlist / 配对，加上 `commands.useAccessGroups`）。
它只会更新**会话状态**，不会写入配置。若要硬禁用 exec，请通过工具
策略拒绝它（`tools.deny: ["exec"]` 或按智能体配置）。
除非你显式设置 `security=full` 且 `ask=off`，否则宿主批准仍然适用。
## Exec 审批（配套应用 / 节点主机）
## Exec approvals（配套应用 / 节点宿主）
处于沙箱隔离中的智能体可以要求在 exec 在 Gateway 网关或节点主机上运行前进行逐次请求审批。
有关策略、allowlist 和 UI 流程，请参见 [Exec 审批](/zh-CN/tools/exec-approvals)。
沙箱隔离的智能体可以要求在 `exec` 于 gateway 或 node 宿主上运行前逐请求批准。
有关策略、allowlist 和 UI 流程，请参见 [Exec approvals](/zh-CN/tools/exec-approvals)。
当需要审批时，exec 工具会立即返回，
其中包含 `status: "approval-pending"` 和一个审批 id。一旦获得批准（或被拒绝 / 超时），
当需要批准时，exec 工具会立即返回，
其中包含 `status: "approval-pending"` 和一个 approval id。一旦批准（或拒绝 / 超时），
Gateway 网关会发出系统事件（`Exec finished` / `Exec denied`）。如果命令在
`tools.exec.approvalRunningNoticeMs` 之后仍在运行，则会发出一次 `Exec running` 通知。
在原生支持审批卡片/按钮的渠道上，智能体应优先依赖该
原生 UI，只有当工具结果明确指出聊天审批不可用或手动审批是唯一
途径时，才应包含手动 `/approve` 命令。
在支持原生批准卡片 / 按钮的渠道上，智能体应优先依赖该
原生 UI，仅当工具结果明确指出聊天批准不可用，或手动批准是唯一途径时，才包含手动 `/approve` 命令。
## Allowlist + safe bins
手动 allowlist 强制仅匹配**解析后的二进制路径**（不匹配 basename）。当
`security=allowlist` 时，只有当管道中的每个片段都在
allowlist 中或属于 safe bin 时，shell 命令才会被自动允许。
在 allowlist 模式下，链式命令（`;`、`&&`、`||`）和重定向会被拒绝，除非每个顶层片段都满足 allowlist 要求（包括 safe bins）。
重定向仍不受支持。
持久化的 `allow-always` 信任也不会绕过这条规则：链式命令仍然要求每个
手动 allowlist 强制会匹配已解析二进制路径 glob 和裸命令名
glob。裸名称只匹配通过 PATH 调用的命令，因此当命令是 `rg` 时，`rg` 可以匹配
`/opt/homebrew/bin/rg`，但不能匹配 `./rg` 或 `/tmp/rg`。
当 `security=allowlist` 时，仅当管道中的每个片段都在 allowlist 中或属于 safe bin，shell 命令才会被自动允许。链式命令（`;`、`&&`、`||`）和重定向
在 allowlist 模式下会被拒绝，除非每个顶层片段都满足
allowlist 条件（包括 safe bins）。重定向仍然不受支持。
持久化的 `allow-always` 信任也不会绕过该规则：链式命令仍要求每个
顶层片段都匹配。
`autoAllowSkills` 是 exec 审批中的另一种便捷路径。它不同于
手动路径 allowlist 条目。若要实行严格的显式信任，请保持
`autoAllowSkills` 为禁用状态。
`autoAllowSkills` 是 exec approvals 中一个单独的便捷路径。它与
手动路径 allowlist 条目不同。如果你需要严格的显式信任，请保持 `autoAllowSkills` 关闭。
请将这两种控制分别用于不同场景：
请将这两种控制用于不同用途：
- `tools.exec.safeBins`：小型、仅 stdin 的流过滤二进制。
- `tools.exec.safeBinTrustedDirs`：用于 safe-bin 可执行路径的显式额外可信目录。
- `tools.exec.safeBinProfiles`：用于自定义 safe bin 的显式 argv 策略。
- `tools.exec.safeBinTrustedDirs`：用于 safe-bin 可执行路径的额外显式可信目录。
- `tools.exec.safeBinProfiles`：用于自定义 safe bins 的显式 argv 策略。
- allowlist：对可执行路径的显式信任。
不要把 `safeBins` 当作通用 allowlist，也不要添加解释器/运行时二进制（例如 `python3`、`node`、`ruby`、`bash`）。如果你需要这些，请使用显式 allowlist 条目，并保持审批提示启用。
当解释器/运行时的 `safeBins` 条目缺少显式 profile 时，`openclaw security audit` 会发出警告，`openclaw doctor --fix` 可以为缺失的自定义 `safeBinProfiles` 条目生成脚手架。
如果你明确将像 `jq` 这样行为范围较广的二进制重新加入 `safeBins`，`openclaw security audit` 和 `openclaw doctor` 也会发出警告。
如果你显式 allowlist 了解释器，请启用 `tools.exec.strictInlineEval`，这样内联代码求值形式仍然需要新的审批。
不要将 `safeBins` 当作通用 allowlist，也不要添加解释器 / 运行时二进制（例如 `python3`、`node`、`ruby`、`bash`）。如果你需要这些，请使用显式 allowlist 条目，并保持批准提示开启。
当解释器 / 运行时 `safeBins` 条目缺少显式 profiles 时，`openclaw security audit` 会发出警告，而 `openclaw doctor --fix` 可以为缺失的自定义 `safeBinProfiles` 条目生成脚手架。
当你显式将诸如 `jq` 之类的广泛行为二进制重新加入 `safeBins` 时，`openclaw security audit` 和 `openclaw doctor` 也会发出警告。
如果你显式将解释器加入 allowlist，请启用 `tools.exec.strictInlineEval`，这样内联代码求值形式仍然需要新的批准。
有关完整策略细节和示例，请参见 [Exec 审批](/zh-CN/tools/exec-approvals-advanced#safe-bins-stdin-only) 和 [Safe bins 与 allowlist 的区别](/zh-CN/tools/exec-approvals-advanced#safe-bins-versus-allowlist)。
有关完整的策略细节和示例，请参见 [Exec approvals](/zh-CN/tools/exec-approvals-advanced#safe-bins-stdin-only) 和 [Safe bins versus allowlist](/zh-CN/tools/exec-approvals-advanced#safe-bins-versus-allowlist)。
## 示例
前台执行：
前台：
```json
{ "tool": "exec", "command": "ls -la" }
```
后台执行 + 轮询：
后台 + 轮询：
```json
{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}
```
轮询用于按需查看状态，而不是用于等待循环。如果启用了自动完成唤醒，
当命令输出内容或失败时，它可以唤醒会话。
轮询用于按需查看状态，而不是等待循环。如果启用了自动完成唤醒，
命令在产生输出或失败时可以唤醒会话。
发送按键（tmux 风格）：
@ -236,7 +236,7 @@ allowlist 中或属于 safe bin 时，shell 命令才会被自动允许。
## apply_patch
`apply_patch` 是 `exec` 的一个子工具，用于结构化的多文件编辑。
对于 OpenAI 和 OpenAI Codex 模型，它默认启用。只有在你想禁用它或将其限制到特定模型时，才需要使用配置：
它默认对 OpenAI 和 OpenAI Codex 模型启用。只有在你想禁用它或将其限制为特定模型时，才需要使用配置：
```json5
{
@ -250,15 +250,15 @@ allowlist 中或属于 safe bin 时，shell 命令才会被自动允许。
说明：
- 仅适用于 OpenAI/OpenAI Codex 模型。
- 仅对 OpenAI/OpenAI Codex 模型可用。
- 工具策略仍然适用；`allow: ["write"]` 会隐式允许 `apply_patch`。
- 配置位于 `tools.exec.applyPatch` 下。
- `tools.exec.applyPatch.enabled` 默认为 `true`；如果要为 OpenAI 模型禁用该工具，请将其设为 `false`。
- `tools.exec.applyPatch.workspaceOnly` 默认为 `true`（限制在工作区内）。只有当你明确希望 `apply_patch` 在工作区目录之外执行写入/删除时，才将其设为 `false`。
- `tools.exec.applyPatch.enabled` 默认值为 `true`；将其设为 `false` 可对 OpenAI 模型禁用该工具。
- `tools.exec.applyPatch.workspaceOnly` 默认值为 `true`（限制在工作区内）。仅当你明确希望 `apply_patch` 在工作区目录之外写入 / 删除时，才将其设为 `false`。
## 相关内容
- [Exec 审批](/zh-CN/tools/exec-approvals) — shell 命令的审批门控
- [Exec Approvals](/zh-CN/tools/exec-approvals) — shell 命令的批准门控
- [沙箱隔离](/zh-CN/gateway/sandboxing) — 在沙箱隔离环境中运行命令
- [后台进程](/zh-CN/gateway/background-process) — 长时间运行的 exec 和 process 工具
- [安全](/zh-CN/gateway/security) — 工具策略和提升访问