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 08:46:12 +00:00
parent b286f732d2
commit 33098a7d58
2 changed files with 461 additions and 465 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

326
docs/zh-CN/channels/telegram.md
View File

@ -1,18 +1,18 @@
---
read_when:
- 开发 Telegram 功能或 webhook 时
- 正在开发 Telegram 功能或 Webhook
summary: Telegram 机器人支持状态、功能和配置
title: Telegram
x-i18n:
generated_at: "2026-04-25T07:27:07Z"
generated_at: "2026-04-25T08:43:04Z"
model: gpt-5.4
provider: openai
source_hash: 8401457440f52a1c8342d650d8dedb363639bc1cda0c1bbe7150d2b243c09087
source_hash: 258cf292a6ba70fc05c509af7c4f70a58b95579ec61ec958e789c84ecbb59681
source_path: channels/telegram.md
workflow: 15
---
通过 grammY 为机器人私信和群组提供生产就绪支持。长轮询是默认模式；webhook 模式为可选。
通过 grammY 为机器人私信和群组提供可用于生产环境的支持。长轮询是默认模式；Webhook 模式为可选。
<CardGroup cols={3}>
<Card title="配对" icon="link" href="/zh-CN/channels/pairing">
@ -26,11 +26,11 @@ x-i18n:
</Card>
</CardGroup>
## 快速开始
## 快速设置
<Steps>
<Step title="在 BotFather 中创建机器人令牌">
打开 Telegram 并与 **@BotFather** 聊天（确认用户名完全是 `@BotFather`）。
打开 Telegram，并与 **@BotFather** 聊天（确认用户名完全是 `@BotFather`）。
运行 `/newbot`，按照提示操作，并保存令牌。
@ -51,8 +51,8 @@ x-i18n:
}
```
环境变量回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账号）。
Telegram **不**使用 `openclaw channels login telegram`；请在配置/环境变量中配置令牌，然后启动 Gateway 网关。
环境变量回退：`TELEGRAM_BOT_TOKEN=...`（仅默认账户）。
Telegram **不**使用 `openclaw channels login telegram`；请在配置/环境变量中设置令牌，然后启动 Gateway 网关。
</Step>
@ -74,35 +74,35 @@ openclaw pairing approve telegram <CODE>
</Steps>
<Note>
令牌解析顺序会感知账号。实际情况下，配置值优先于环境变量回退，而 `TELEGRAM_BOT_TOKEN` 仅适用于默认账号。
令牌解析顺序具有账户感知能力。实际上，配置中的值优先于环境变量回退，而 `TELEGRAM_BOT_TOKEN` 仅适用于默认账户。
</Note>
## Telegram 端设置
## Telegram 侧设置
<AccordionGroup>
<Accordion title="隐私模式和群组可见性">
Telegram 机器人默认启用 **隐私模式**，这会限制它们能接收的群组消息。
Telegram 机器人默认启用 **隐私模式**，这会限制它们能接收到的群组消息。
如果机器人必须看到所有群组消息，可以采用以下任一方式：
如果机器人必须看到所有群组消息，可以采取以下任一方式：
- 通过 `/setprivacy` 禁用隐私模式，或
- 将机器人设为群组管理员。
切换隐私模式后，请在每个群组中移除并重新添加该机器人，以便 Telegram 应用此更改。
切换隐私模式后，请在每个群组中移除并重新添加机器人，以便 Telegram 应用更改。
</Accordion>
<Accordion title="群组权限">
管理员状态在 Telegram 群组设置中控制。
管理员状态由 Telegram 群组设置控制。
管理员机器人会接收所有群组消息，这对始终在线的群组行为很有帮助。
管理员机器人会接收所有群组消息，这对于始终在线的群组行为很有用。
</Accordion>
<Accordion title="有用的 BotFather 开关">
- `/setjoingroups` 允许/拒绝加入群组
- `/setprivacy` 控制群组可见性行为
- `/setjoingroups` 用于允许/拒绝加入群组
- `/setprivacy` 用于控制群组可见性行为
</Accordion>
</AccordionGroup>
@ -115,24 +115,24 @@ openclaw pairing approve telegram <CODE>
- `pairing`（默认）
- `allowlist`（要求 `allowFrom` 中至少有一个发送者 ID）
- `open`（要求 `allowFrom` 包含 `"*"`)
- `open`（要求 `allowFrom` 包含 `"*"`）
- `disabled`
`channels.telegram.allowFrom` 接受数字型 Telegram 用户 ID。支持并会规范化 `telegram:` / `tg:` 前缀。
`dmPolicy: "allowlist"` 且 `allowFrom` 为空时会阻止所有私信，并会被配置校验拒绝。
设置时只会要求填写数字型用户 ID。
如果你升级后发现配置中包含 `@username` allowlist 条目，请运行 `openclaw doctor --fix` 来解析它们（尽力而为；需要 Telegram 机器人令牌）。
如果你之前依赖配对存储 allowlist 文件，在 allowlist 流程中（例如 `dmPolicy: "allowlist"` 还没有显式 ID 时），`openclaw doctor --fix` 可以将这些条目恢复到 `channels.telegram.allowFrom`。
`channels.telegram.allowFrom` 接受 Telegram 数字用户 ID。支持 `telegram:` / `tg:` 前缀，并会规范化处理。
`dmPolicy: "allowlist"` 且 `allowFrom` 为空时会阻止所有私信，并被配置校验拒绝。
设置流程只会要求输入数字用户 ID。
如果你升级后配置中包含 `@username` 形式的 allowlist 条目，请运行 `openclaw doctor --fix` 来解析它们（尽力而为；需要 Telegram 机器人令牌）。
如果你之前依赖配对存储中的 allowlist 文件，在 allowlist 流程中（例如 `dmPolicy: "allowlist"` 还没有显式 ID 时），`openclaw doctor --fix` 可以将这些条目恢复到 `channels.telegram.allowFrom` 中。
对于单所有者机器人，建议优先使用 `dmPolicy: "allowlist"` 并明确填写数字型 `allowFrom` ID，这样可以让访问策略稳定保存在配置中（而不是依赖之前的配对批准）。
对于单所有者机器人，建议使用 `dmPolicy: "allowlist"` 并显式设置数字 `allowFrom` ID，以便将访问策略稳定地保存在配置中（而不是依赖之前的配对批准）。
常见困惑：批准私信配对并不意味着“这个发送者在任何地方都被授权”。
配对仅授予私信访问权限。群组发送者授权仍然来自显式配置的 allowlist。
如果你想实现“我授权一次后，私信和群组命令都可用”，请把你的数字型 Telegram 用户 ID 放入 `channels.telegram.allowFrom`。
常见困惑：私信配对批准并不意味着“这个发送者在所有地方都已获授权”。
配对只授予私信访问权限。群组发送者授权仍然来自显式配置的 allowlist。
如果你希望“我授权一次后，私信和群组命令都能工作”，请将你的 Telegram 数字用户 ID 放入 `channels.telegram.allowFrom`。
### 查找你的 Telegram 用户 ID
更安全的方法（无需第三方机器人）：
更安全的方法（不使用第三方机器人）：
1. 给你的机器人发送私信。
2. 运行 `openclaw logs --follow`。
@ -149,13 +149,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
</Tab>
<Tab title="群组策略和 allowlist">
有两个控制项会同时生效：
两项控制会同时生效：
1. **允许哪些群组**（`channels.telegram.groups`）
- 没有 `groups` 配置：
- 配合 `groupPolicy: "open"`：任意群组都可以通过群组 ID 检查
- 配合 `groupPolicy: "allowlist"`（默认）：群组会被阻止，直到你添加 `groups` 条目（或 `"*"`)
- 已配置 `groups`：它会作为 allowlist 使用（显式 ID 或 `"*"`）
- 当 `groupPolicy: "open"` 时：任何群组都可以通过群组 ID 检查
- 当 `groupPolicy: "allowlist"`（默认）时：在你添加 `groups` 条目（或 `"*"`）之前，群组都会被阻止
- 已配置 `groups`：其作用是 allowlist（显式 ID 或 `"*"`）
2. **群组中允许哪些发送者**（`channels.telegram.groupPolicy`）
- `open`
@ -163,14 +163,14 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `disabled`
`groupAllowFrom` 用于群组发送者过滤。如果未设置，Telegram 会回退到 `allowFrom`。
`groupAllowFrom` 条目应为数字型 Telegram 用户 ID（`telegram:` / `tg:` 前缀会被规范化）。
`groupAllowFrom` 条目应为 Telegram 数字用户 ID（`telegram:` / `tg:` 前缀会被规范化）。
不要把 Telegram 群组或超级群组聊天 ID 放进 `groupAllowFrom`。负数聊天 ID 应放在 `channels.telegram.groups` 下。
非数字条目会在发送者授权时被忽略。
非数字条目会在发送者授权中被忽略。
安全边界（`2026.2.25+`）：群组发送者授权**不会**继承私信配对存储批准。
配对仍然仅限私信。对于群组，请设置 `groupAllowFrom` 或按群组/按话题设置 `allowFrom`。
如果未设置 `groupAllowFrom`，Telegram 会回退到配置中的 `allowFrom`，而不是配对存储。
单所有者机器人的实用模式：将你的用户 ID 放入 `channels.telegram.allowFrom`，保持 `groupAllowFrom` 未设置，并在 `channels.telegram.groups` 下允许目标群组。
运行时说明：如果完全缺少 `channels.telegram`，运行时默认采用故障关闭的 `groupPolicy="allowlist"`，除非显式设置了 `channels.defaults.groupPolicy`。
如果 `groupAllowFrom` 未设置，Telegram 会回退到配置中的 `allowFrom`，而不是配对存储。
单所有者机器人的实用模式：在 `channels.telegram.allowFrom` 中设置你的用户 ID，保持 `groupAllowFrom` 未设置，并在 `channels.telegram.groups` 下允许目标群组。
运行时说明：如果完全缺少 `channels.telegram`，运行时默认会采用失败即关闭的 `groupPolicy="allowlist"`，除非显式设置了 `channels.defaults.groupPolicy`。
示例：允许某个特定群组中的任意成员：
@ -189,7 +189,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
示例：仅允许某个特定群组中的特定用户：
示例：只允许某个特定群组中的特定用户：
```json5
{
@ -210,14 +210,14 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
常见错误：`groupAllowFrom` 不是 Telegram 群组 allowlist。
- 将 `-1001234567890` 这类负数 Telegram 群组或超级群组聊天 ID 放在 `channels.telegram.groups` 下。
- 当你想限制允许群组中哪些人可以触发机器人时，将 `8734062810` 这类 Telegram 用户 ID 放在 `groupAllowFrom` 下。
- 仅当你希望允许群组中的任意成员都能与机器人对话时，才使用 `groupAllowFrom: ["*"]`。
- 当你想限制允许群组内哪些人可以触发机器人时，将 `8734062810` 这类 Telegram 用户 ID 放在 `groupAllowFrom` 下。
- 仅当你希望允许群组中的任意成员与机器人对话时，才使用 `groupAllowFrom: ["*"]`。
</Warning>
</Tab>
<Tab title="提及行为">
群组回复默认需要提及。
默认情况下，群组回复需要提及。
提及可以来自：
@ -247,7 +247,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
获取群组聊天 ID：
获取群组聊天 ID 的方式：
- 将群组消息转发给 `@userinfobot` / `@getidsbot`
- 或从 `openclaw logs --follow` 中读取 `chat.id`
@ -258,13 +258,14 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
## 运行时行为
- Telegram 由 Gateway 网关进程负责。
- 路由是确定性的：Telegram 入站消息会回复到 Telegram（模型不会选择渠道）。
- 入站消息会规范化为共享渠道信封，其中包含回复元数据和媒体占位符。
- Telegram 由 Gateway 网关进程管理。
- 路由是确定性的：Telegram 入站回复会回到 Telegram（模型不会选择渠道）。
- 入站消息会规范化为共享渠道信封格式，并附带回复元数据和媒体占位符。
- 群组会话按群组 ID 隔离。论坛话题会追加 `:topic:<threadId>` 以保持话题隔离。
- 私信消息可以携带 `message_thread_id`；OpenClaw 会使用具备线程感知的会话键进行路由，并为回复保留线程 ID。
- 长轮询使用 grammY runner，并按聊天/线程顺序执行。整体 runner sink 并发度使用 `agents.defaults.maxConcurrent`。
- 默认情况下，如果 120 秒内没有完成的 `getUpdates` 存活信号，长轮询看门狗会触发重启。只有当你的部署在长时间运行任务期间仍然出现误判的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。该值以毫秒为单位，允许范围为 `30000` 到 `600000`；支持按账号覆盖。
- 私信消息可以携带 `message_thread_id`；OpenClaw 会使用具备线程感知能力的会话键进行路由，并为回复保留线程 ID。
- 长轮询使用带有每聊天/每线程顺序控制的 grammY runner。整体 runner sink 并发度使用 `agents.defaults.maxConcurrent`。
- 在每个 Gateway 网关进程内部，长轮询都有保护机制，因此同一时间只有一个活跃轮询器可以使用某个机器人令牌。如果你仍然看到 `getUpdates` 409 冲突，可能是另一个 OpenClaw Gateway 网关、脚本或外部轮询器正在使用同一个令牌。
- 默认情况下，如果 120 秒内没有完成的 `getUpdates` 存活信号，长轮询看门狗会触发重启。只有当你的部署在长时间运行任务期间仍出现误判的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。该值以毫秒为单位，允许范围为 `30000` 到 `600000`；支持按账户覆盖。
- Telegram Bot API 不支持已读回执（`sendReadReceipts` 不适用）。
## 功能参考
@ -279,11 +280,11 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
要求：
- `channels.telegram.streaming` 为 `off | partial | block | progress`（默认：`partial`）
- 在 Telegram 上，`progress` 映射为 `partial`（与跨渠道命名兼容）
- `streaming.preview.toolProgress` 控制工具/进度更新是否复用同一条已编辑的预览消息（默认：当预览流式传输处于激活状态时为 `true`）
- `progress` 在 Telegram 上映射为 `partial`（与跨渠道命名兼容）
- `streaming.preview.toolProgress` 控制工具/进度更新是否复用同一条被编辑的预览消息（默认：启用预览流式传输时为 `true`）
- 旧版 `channels.telegram.streamMode` 和布尔型 `streaming` 值会自动映射
工具进度预览更新是指工具运行期间显示的简短“Working...”行，例如命令执行、文件读取、规划更新或补丁摘要。Telegram 默认保持这些更新启用，以匹配 `v2026.4.22` 及之后已发布的 OpenClaw 行为。如果你希望为答案文本保留编辑后的预览，但隐藏工具进度行，请设置：
工具进度预览更新是工具运行期间显示的简短“处理中...”行，例如命令执行、文件读取、规划更新或补丁摘要。Telegram 默认保持启用这些更新，以匹配 `v2026.4.22` 及之后版本中已发布的 OpenClaw 行为。如果你想保留用于答案文本的编辑预览，但隐藏工具进度行，请设置：
```json
{
@ -300,20 +301,20 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
仅当你想完全禁用 Telegram 预览编辑时，才使用 `streaming.mode: "off"`。如果你只想禁用工具进度状态行，请使用 `streaming.preview.toolProgress: false`。
只有当你想完全禁用 Telegram 预览编辑时，才使用 `streaming.mode: "off"`。当你只想禁用工具进度状态行时，使用 `streaming.preview.toolProgress: false`。
对于纯文本回复：
- 私信：OpenClaw 会保留同一条预览消息，并在原地进行最终编辑（不会发送第二条消息）
- 群组/话题：OpenClaw 会保留同一条预览消息，并在原地进行最终编辑（不会发送第二条消息）
- 私信：OpenClaw 会保留同一条预览消息，并原地执行最终编辑（不会发送第二条消息）
- 群组/话题：OpenClaw 会保留同一条预览消息，并原地执行最终编辑（不会发送第二条消息）
对于复杂回复（例如媒体负载），OpenClaw 会回退到正常的最终投递方式，然后清理预览消息。
对于复杂回复（例如媒体负载），OpenClaw 会回退到正常的最终发送，然后清理预览消息。
预览流式传输独立于分块流式传输。当为 Telegram 显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。
预览流式传输与分块流式传输是分开的。当为 Telegram 显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免双重流式传输。
如果原生草稿传输不可用/被拒绝，OpenClaw 会自动回退到 `sendMessage` + `editMessageText`。
仅限 Telegram 的推理流：
仅 Telegram 的推理流：
- `/reasoning stream` 会在生成期间将推理发送到实时预览中
- 最终答案发送时不包含推理文本
@ -325,18 +326,18 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- 类 Markdown 文本会被渲染为 Telegram 安全的 HTML。
- 原始模型 HTML 会被转义，以减少 Telegram 解析失败。
- 如果 Telegram 拒绝解析后的 HTML，OpenClaw 会以纯文本重试。
- 如果 Telegram 拒绝已解析的 HTML，OpenClaw 会以纯文本重试。
链接预览默认启用，可通过 `channels.telegram.linkPreview: false` 禁用。
默认启用链接预览，可通过 `channels.telegram.linkPreview: false` 禁用。
</Accordion>
<Accordion title="原生命令和自定义命令">
Telegram 命令菜单注册会在启动时通过 `setMyCommands` 处理。
Telegram 命令菜单注册在启动时通过 `setMyCommands` 处理。
原生命令默认值：
- `commands.native: "auto"` 会为 Telegram 启用原生命令
- `commands.native: "auto"` 为 Telegram 启用原生命令
添加自定义命令菜单项：
@ -355,21 +356,21 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
规则：
- 名称会被规范化（去掉前导 `/`，转为小写）
- 名称会被规范化（去除前导 `/`，转为小写）
- 有效模式：`a-z`、`0-9`、`_`，长度 `1..32`
- 自定义命令不能覆盖原生命令
- 冲突/重复项会被跳过并记录日志
说明：
- 自定义命令仅是菜单项；它们不会自动实现行为
- plugin/skill 命令即使未显示在 Telegram 菜单中，手动输入后仍可工作
- 自定义命令只是菜单项；它们不会自动实现行为
- 即使没有显示在 Telegram 菜单中，plugin/Skills 命令在手动输入时仍然可以工作
如果禁用了原生命令，内置命令会被移除。自定义/plugin 命令如果已配置，仍可能注册。
如果禁用了原生命令，内置命令会被移除。如果已配置，自定义/plugin 命令仍可能被注册。
常见设置失败：
- `setMyCommands failed` 且出现 `BOT_COMMANDS_TOO_MUCH`，表示 Telegram 菜单在裁剪后仍然溢出；请减少 plugin/skill/自定义命令数量，或禁用 `channels.telegram.commands.native`。
- `setMyCommands failed` 且报错 `BOT_COMMANDS_TOO_MUCH`，表示 Telegram 菜单在裁剪后仍然溢出；请减少 plugin/Skills/自定义命令，或禁用 `channels.telegram.commands.native`。
- `setMyCommands failed` 且出现网络/fetch 错误，通常表示到 `api.telegram.org` 的出站 DNS/HTTPS 被阻止。
### 设备配对命令（`device-pair` plugin）
@ -377,23 +378,23 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
安装 `device-pair` plugin 后：
1. `/pair` 生成设置代码
2. 在 iOS 应用中粘贴该代码
2. 在 iOS 应用中粘贴代码
3. `/pair pending` 列出待处理请求（包括角色/作用域）
4. 批准请求：
- `/pair approve <requestId>` 用于显式批准
- 当只有一个待处理请求时，使用 `/pair approve`
- `/pair approve latest` 用于最近的一项
- 只有一个待处理请求时，使用 `/pair approve`
- 使用 `/pair approve latest` 批准最近的请求
设置代码携带短期有效的 bootstrap 令牌。内置 bootstrap 交接会将主节点令牌保持为 `scopes: []`；任何已交接的 operator 令牌都仍限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write`。Bootstrap 作用域检查使用角色前缀，因此 operator allowlist 只满足 operator 请求；非 operator 角色仍需要其自身角色前缀下的作用域。
设置代码携带短期有效的 bootstrap 令牌。内置 bootstrap 交接会将主节点令牌保持为 `scopes: []`；任何交接出的 operator 令牌都会限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write` 范围内。Bootstrap 作用域检查带有角色前缀，因此 operator allowlist 只会满足 operator 请求；非 operator 角色仍然需要其自身角色前缀下的作用域。
如果设备以变更后的认证详情重试（例如角色/作用域/公钥），之前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。
如果设备在重试时更改了认证详情（例如角色/作用域/公钥），之前的待处理请求会被替代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。
更多详情：[配对](/zh-CN/channels/pairing#pair-via-telegram-recommended-for-ios)。
</Accordion>
<Accordion title="内联按钮">
配置内联键盘作用范围：
配置内联键盘作用域：
```json5
{
@ -407,7 +408,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
按账号覆盖：
按账户覆盖：
```json5
{
@ -425,7 +426,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
范围：
作用域：
- `off`
- `dm`
@ -458,16 +459,16 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
</Accordion>
<Accordion title="供智能体和自动化使用的 Telegram 消息操作">
<Accordion title="用于智能体和自动化的 Telegram 消息操作">
Telegram 工具操作包括：
- `sendMessage`（`to`、`content`、可选 `mediaUrl`、`replyToMessageId`、`messageThreadId`）
- `sendMessage`（`to`、`content`、可选的 `mediaUrl`、`replyToMessageId`、`messageThreadId`）
- `react`（`chatId`、`messageId`、`emoji`）
- `deleteMessage`（`chatId`、`messageId`）
- `editMessage`（`chatId`、`messageId`、`content`）
- `createForumTopic`（`chatId`、`name`、可选 `iconColor`、`iconCustomEmojiId`）
- `createForumTopic`（`chatId`、`name`、可选的 `iconColor`、`iconCustomEmojiId`）
渠道消息操作公开了更易用的别名（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。
渠道消息操作提供了更易用的别名（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。
控制开关：
@ -476,8 +477,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `channels.telegram.actions.reactions`
- `channels.telegram.actions.sticker`（默认：禁用）
注意：`edit` 和 `topic-create` 当前默认启用，并且没有单独的 `channels.telegram.actions.*` 开关。
运行时发送使用当前生效的配置/密钥快照（启动/重载时），因此操作路径不会在每次发送时临时重新解析 SecretRef。
说明：`edit` 和 `topic-create` 当前默认启用，且没有单独的 `channels.telegram.actions.*` 开关。
运行时发送使用当前活动的配置/密钥快照（启动/重载时），因此操作路径不会在每次发送时临时重新解析 SecretRef。
移除反应的语义：[/tools/reactions](/zh-CN/tools/reactions)
@ -495,7 +496,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `first`
- `all`
注意：`off` 会禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍会被遵循。
说明：`off` 会禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍会被遵循。
</Accordion>
@ -507,15 +508,15 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- 话题配置路径：
`channels.telegram.groups.<chatId>.topics.<threadId>`
常规话题（`threadId=1`）特殊情况：
通用话题（`threadId=1`）特殊情况：
- 发送消息时会省略 `message_thread_id`（Telegram 会拒绝 `sendMessage(...thread_id=1)`）
- 输入动作仍然包含 `message_thread_id`
话题继承：除非被覆盖，话题条目会继承群组设置（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。
`agentId` 仅限话题级，不会从群组默认值继承。
`agentId` 仅适用于话题，不会从群组默认值继承。
**按话题的智能体路由**：每个话题都可以通过在话题配置中设置 `agentId` 路由到不同的智能体。这样每个话题都有自己独立的工作区、记忆和会话。示例：
**按话题的智能体路由**：每个话题都可以通过在话题配置中设置 `agentId` 路由到不同的智能体。这使每个话题拥有各自独立的工作区、记忆和会话。示例：
```json5
{
@ -524,7 +525,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
groups: {
"-1001234567890": {
topics: {
"1": { agentId: "main" }, // 常规话题 → main 智能体
"1": { agentId: "main" }, // 通用话题 → main 智能体
"3": { agentId: "zu" }, // 开发话题 → zu 智能体
"5": { agentId: "coder" } // 代码审查 → coder 智能体
}
@ -535,23 +536,23 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
此后每个话题都有自己的会话键：`agent:zu:telegram:group:-1001234567890:topic:3`
然后每个话题都会有自己的会话键：`agent:zu:telegram:group:-1001234567890:topic:3`
**持久 ACP 话题绑定**：论坛话题可以通过顶层类型化 ACP 绑定（`bindings[]` 中 `type: "acp"`，且 `match.channel: "telegram"`、`peer.kind: "group"`，以及带话题限定的 id，如 `-1001234567890:topic:42`）固定到 ACP harness 会话。目前仅适用于群组/超级群组中的论坛话题。参见 [ACP Agents](/zh-CN/tools/acp-agents)。
**持久化 ACP 话题绑定**：论坛话题可以通过顶层类型化 ACP 绑定（`bindings[]` 中 `type: "acp"`，且 `match.channel: "telegram"`、`peer.kind: "group"`，以及带话题限定的 id，如 `-1001234567890:topic:42`）固定 ACP harness 会话。目前仅限群组/超级群组中的论坛话题。参见 [ACP Agents](/zh-CN/tools/acp-agents)。
**从聊天中生成线程绑定的 ACP**：`/acp spawn <agent> --thread here|auto` 会将当前话题绑定到一个新的 ACP 会话；后续消息会直接路由到该会话。OpenClaw 会在话题内固定生成确认消息。需要 `channels.telegram.threadBindings.spawnAcpSessions=true`。
**从聊天中生成线程绑定的 ACP**：`/acp spawn <agent> --thread here|auto` 会将当前话题绑定到一个新的 ACP 会话；后续消息会直接路由到该会话。OpenClaw 会将生成确认固定在话题内。需要 `channels.telegram.threadBindings.spawnAcpSessions=true`。
模板上下文会暴露 `MessageThreadId` 和 `IsForum`。带有 `message_thread_id` 的私信聊天会保持私信路由，但使用具备线程感知的会话键。
模板上下文暴露 `MessageThreadId` 和 `IsForum`。带有 `message_thread_id` 的私信聊天会保持私信路由，但使用具备线程感知能力的会话键。
</Accordion>
<Accordion title="音频、视频和贴纸">
### 音频消息
Telegram 区分语音便笺和音频文件。
Telegram 区分语音消息和音频文件。
- 默认：音频文件行为
- 在智能体回复中添加标签 `[[audio_as_voice]]` 可强制按语音便笺发送
- 在智能体回复中添加标签 `[[audio_as_voice]]` 可强制作为语音消息发送
消息操作示例：
@ -587,7 +588,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
入站贴纸处理：
- 静态 WEBP：会下载并处理（占位符 `<media:sticker>`）
- 静态 WEBP：下载并处理（占位符 `<media:sticker>`）
- 动画 TGS：跳过
- 视频 WEBM：跳过
@ -630,7 +631,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
搜索缓存贴纸：
搜索缓存的贴纸：
```json5
{
@ -644,7 +645,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
</Accordion>
<Accordion title="反应通知">
Telegram 反应以 `message_reaction` 更新的形式到达（与消息负载分离）。
Telegram 反应会以 `message_reaction` 更新形式到达（与消息负载分离）。
启用后，OpenClaw 会将如下系统事件加入队列：
@ -657,13 +658,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
说明：
- `own` 表示仅处理用户对机器人发送消息的反应（基于已发送消息缓存，尽力而为）。
- 反应事件仍遵循 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权发送者会被丢弃。
- `own` 表示仅用户对机器人发送消息的反应（尽力通过已发送消息缓存实现）。
- 反应事件仍然遵循 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权发送者会被丢弃。
- Telegram 不会在反应更新中提供线程 ID。
- 非论坛群组会路由到群组聊天会话
- 论坛群组会路由到群组常规话题会话（`:topic:1`），而不是精确的原始话题
- 非论坛群组会路由到群聊会话
- 论坛群组会路由到群组的通用话题会话（`:topic:1`），而不是确切的原始话题
轮询/webhook 的 `allowed_updates` 会自动包含 `message_reaction`。
轮询/Webhook 的 `allowed_updates` 会自动包含 `message_reaction`。
</Accordion>
@ -679,12 +680,12 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
说明：
- Telegram 需要 unicode emoji（例如 "👀"）。
- 使用 `""` 可为某个渠道或账号禁用该反应。
- Telegram 要求使用 unicode emoji（例如 "👀"）。
- 使用 `""` 可为某个渠道或账户禁用该反应。
</Accordion>
<Accordion title="由 Telegram 事件和命令触发的配置写入">
<Accordion title="来自 Telegram 事件和命令的配置写入">
默认启用渠道配置写入（`configWrites !== false`）。
由 Telegram 触发的写入包括：
@ -692,7 +693,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- 群组迁移事件（`migrate_to_chat_id`），用于更新 `channels.telegram.groups`
- `/config set` 和 `/config unset`（需要启用命令）
禁用方式：
禁用：
```json5
{
@ -706,29 +707,29 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
</Accordion>
<Accordion title="长轮询与 webhook">
默认使用长轮询。若要使用 webhook 模式，请设置 `channels.telegram.webhookUrl` 和 `channels.telegram.webhookSecret`；可选项包括 `webhookPath`、`webhookHost`、`webhookPort`（默认分别为 `/telegram-webhook`、`127.0.0.1`、`8787`）。
<Accordion title="长轮询与 Webhook">
默认是长轮询。对于 Webhook 模式，请设置 `channels.telegram.webhookUrl` 和 `channels.telegram.webhookSecret`；可选项包括 `webhookPath`、`webhookHost`、`webhookPort`（默认分别为 `/telegram-webhook`、`127.0.0.1`、`8787`）。
本地监听器绑定到 `127.0.0.1:8787`。对于公共入口，要么在本地端口前放置反向代理，要么有意设置 `webhookHost: "0.0.0.0"`。
本地监听器绑定到 `127.0.0.1:8787`。对于公共入口，请在本地端口前放置反向代理，或有意设置 `webhookHost: "0.0.0.0"`。
webhook 模式会在向 Telegram 返回 `200` 之前校验请求保护、Telegram 密钥令牌以及 JSON 请求体。
之后 OpenClaw 会通过与长轮询相同的按聊天/按话题 bot 通道异步处理更新，因此缓慢的智能体轮次不会阻塞 Telegram 的投递 ACK。
Webhook 模式会在向 Telegram 返回 `200` 之前，校验请求保护机制、Telegram 密钥令牌和 JSON 请求体。
然后，OpenClaw 会通过与长轮询相同的每聊天/每话题机器人通道异步处理该更新，因此缓慢的智能体轮次不会阻塞 Telegram 的投递 ACK。
</Accordion>
<Accordion title="限制、重试和 CLI 目标">
- `channels.telegram.textChunkLimit` 默认为 4000。
- `channels.telegram.chunkMode="newline"` 会在按长度拆分之前优先按段落边界（空行）拆分。
- `channels.telegram.mediaMaxMb`（默认 100）限制 Telegram 入站和出站媒体大小。
- `channels.telegram.timeoutSeconds` 会覆盖 Telegram API 客户端超时（如果未设置，则使用 grammY 默认值）。
- `channels.telegram.pollingStallThresholdMs` 默认为 `120000`；仅在出现误判轮询停滞重启时，才在 `30000` 到 `600000` 之间调优。
- `channels.telegram.textChunkLimit` 默认值为 4000。
- `channels.telegram.chunkMode="newline"` 会在按长度拆分之前，优先选择段落边界（空行）。
- `channels.telegram.mediaMaxMb`（默认 100）限制入站和出站 Telegram 媒体大小。
- `channels.telegram.timeoutSeconds` 会覆盖 Telegram API 客户端超时时间（如果未设置，则使用 grammY 默认值）。
- `channels.telegram.pollingStallThresholdMs` 默认值为 `120000`；仅在出现误报的轮询停滞重启时，才调整为 `30000` 到 `600000` 之间。
- 群组上下文历史使用 `channels.telegram.historyLimit` 或 `messages.groupChat.historyLimit`（默认 50）；`0` 表示禁用。
- 回复/引用/转发的补充上下文当前会按接收到的内容传递。
- Telegram allowlist 主要用于限制谁可以触发智能体，而不是完整的补充上下文脱敏边界。
- Telegram allowlist 主要控制谁可以触发智能体，而不是完整的补充上下文脱敏边界。
- 私信历史控制：
- `channels.telegram.dmHistoryLimit`
- `channels.telegram.dms["<user_id>"].historyLimit`
- `channels.telegram.retry` 配置适用于 Telegram 发送辅助功能（CLI/工具/操作）中的可恢复出站 API 错误。
- `channels.telegram.retry` 配置会应用到 Telegram 发送辅助函数（CLI/工具/操作），用于处理可恢复的出站 API 错误。
CLI 发送目标可以是数字聊天 ID 或用户名：
@ -747,7 +748,7 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
--poll-duration-seconds 300 --poll-public
```
仅限 Telegram 的投票标志：
仅 Telegram 的投票标志：
- `--poll-duration-seconds`（5-600）
- `--poll-anonymous`
@ -756,46 +757,46 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
Telegram 发送还支持：
- 当 `channels.telegram.capabilities.inlineButtons` 允许时，使用带有 `buttons` 块的 `--presentation` 来提供内联键盘
- 使用 `--pin` 或 `--delivery '{"pin":true}'` 请求固定投递，前提是机器人在该聊天中有固定权限
- `--force-document` 将出站图片和 GIF 作为文档发送，而不是作为压缩照片或动画媒体上传
- 当 `channels.telegram.capabilities.inlineButtons` 允许时，使用带有 `buttons` 块的 `--presentation` 来实现内联键盘
- `--pin` 或 `--delivery '{"pin":true}'`，用于在机器人有权限固定消息的聊天中请求固定投递
- `--force-document`，用于将出站图片和 GIF 作为文档发送，而不是压缩照片或动画媒体上传
操作开关：
操作控制：
- `channels.telegram.actions.sendMessage=false` 会禁用 Telegram 出站消息，包括投票
- `channels.telegram.actions.sendMessage=false` 会禁用出站 Telegram 消息，包括投票
- `channels.telegram.actions.poll=false` 会禁用 Telegram 投票创建，同时保留常规发送功能
</Accordion>
<Accordion title="Telegram 中的执行批准">
Telegram 支持在批准者私信中进行执行批准，也可选择在原始聊天或话题中发布提示。批准者必须是数字型 Telegram 用户 ID。
<Accordion title="Telegram 中的 Exec 审批">
Telegram 支持在审批者私信中进行 exec 审批，并且可以选择在原始聊天或话题中发布提示。审批者必须是 Telegram 数字用户 ID。
配置路径：
- `channels.telegram.execApprovals.enabled`（当至少有一个批准者可解析时自动启用）
- `channels.telegram.execApprovals.enabled`（当至少有一个审批者可解析时自动启用）
- `channels.telegram.execApprovals.approvers`（回退到来自 `allowFrom` / `defaultTo` 的数字所有者 ID）
- `channels.telegram.execApprovals.target`: `dm`（默认）| `channel` | `both`
- `agentFilter`、`sessionFilter`
渠道投递会在聊天中显示命令文本；仅在受信任的群组/话题中启用 `channel` 或 `both`。当提示落在论坛话题中时，OpenClaw 会为批准提示及其后续消息保留该话题。执行批准默认会在 30 分钟后过期。
渠道投递会在聊天中显示命令文本；仅在受信任的群组/话题中启用 `channel` 或 `both`。当提示投递到论坛话题中时，OpenClaw 会为审批提示和后续消息保留该话题。Exec 审批默认在 30 分钟后过期。
内联批准按钮还要求 `channels.telegram.capabilities.inlineButtons` 允许目标界面（`dm`、`group` 或 `all`）。带 `plugin:` 前缀的批准 ID 会通过 plugin 批准解析；其他 ID 会优先通过执行批准解析。
内联审批按钮还要求 `channels.telegram.capabilities.inlineButtons` 允许目标表面（`dm`、`group` 或 `all`）。以 `plugin:` 为前缀的审批 ID 会通过 plugin 审批解析；其他 ID 则会优先通过 exec 审批解析。
参见 [执行批准](/zh-CN/tools/exec-approvals)。
参见 [Exec 审批](/zh-CN/tools/exec-approvals)。
</Accordion>
</AccordionGroup>
## 错误回复控制
当智能体遇到投递或提供商错误时，Telegram 可以回复错误文本，也可以将其抑制。两个配置键控制此行为：
当智能体遇到投递错误或提供商错误时，Telegram 可以选择回复错误文本或抑制错误文本。两个配置键控制此行为：
| 键 | 值 | 默认值 | 描述 |
| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` 会向聊天发送一条友好的错误消息。`silent` 会完全抑制错误回复。 |
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | 同一聊天两次错误回复之间的最短时间。可防止在故障期间出现错误刷屏。 |
| 键 | 值 | 默认值 | 描述 |
| ----------------------------------- | ----------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` 会向聊天发送一条友好的错误消息。`silent` 会完全抑制错误回复。 |
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | 向同一聊天发送错误回复之间的最短时间。可防止在故障期间出现错误刷屏。 |
支持按账号、按群组和按话题覆盖（与其他 Telegram 配置键具有相同的继承方式）。
支持按账户、按群组和按话题覆盖（继承规则与其他 Telegram 配置键相同）。
```json5
{
@ -818,40 +819,40 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
<AccordionGroup>
<Accordion title="机器人不响应未提及的群组消息">
- 如果 `requireMention=false`，Telegram 隐私模式必须允许完全可见。
- BotFather：`/setprivacy` -> 禁用
- 然后从群组中移除并重新添加机器人
- 当配置预期接收未提及的群组消息时，`openclaw channels status` 会发出警告。
- `openclaw channels status --probe` 可以检查显式数字群组 ID；无法对通配符 `"*"` 进行成员资格探测。
- 如果 `requireMention=false`，Telegram 隐私模式必须允许完全可见性。
- BotFather：`/setprivacy` -> Disable
- 然后移除并重新添加机器人到群组
- 当配置期望接收未提及的群组消息时，`openclaw channels status` 会发出警告。
- `openclaw channels status --probe` 可以检查显式数字群组 ID；通配符 `"*"` 无法进行成员资格探测。
- 快速会话测试：`/activation always`。
</Accordion>
<Accordion title="机器人完全看不到群组消息">
- 当存在 `channels.telegram.groups` 时，必须列出该群组（或包含 `"*"`)
- 验证机器人是否在群组中
- 查看日志：使用 `openclaw logs --follow` 检查跳过原因
- 当存在 `channels.telegram.groups` 时，群组必须被列出（或包含 `"*"`）
- 验证机器人是否已加入群组
- 查看日志：`openclaw logs --follow` 以获取跳过原因
</Accordion>
<Accordion title="命令部分可用或完全不可用">
- 授权你的发送者身份（配对和/或数字型 `allowFrom`）
- 即使群组策略是 `open`，命令授权仍然适用
- `setMyCommands failed` 且出现 `BOT_COMMANDS_TOO_MUCH`，表示原生命令菜单条目过多；请减少 plugin/skill/自定义命令数量，或禁用原生菜单
- 授权你的发送者身份（配对和/或数字 `allowFrom`）
- 即使群组策略为 `open`，命令授权仍然适用
- `setMyCommands failed` 且报错 `BOT_COMMANDS_TOO_MUCH`，表示原生命令菜单条目过多；请减少 plugin/Skills/自定义命令，或禁用原生菜单
- `setMyCommands failed` 且出现网络/fetch 错误，通常表示到 `api.telegram.org` 的 DNS/HTTPS 可达性存在问题
</Accordion>
<Accordion title="轮询或网络不稳定">
- Node 22+ + 自定义 fetch/proxy 如果 AbortSignal 类型不匹配，可能触发立即中止行为。
- 某些主机会优先将 `api.telegram.org` 解析为 IPv6；损坏的 IPv6 出站连接会导致 Telegram API 间歇性失败。
- 如果日志包含 `TypeError: fetch failed` 或 `Network request for 'getUpdates' failed!`，OpenClaw 现在会将这些作为可恢复网络错误进行重试。
- 如果日志包含 `Polling stall detected`，默认情况下 OpenClaw 会在 120 秒内没有完成的长轮询存活信号后重启轮询并重建 Telegram 传输层。
- 仅当长时间运行的 `getUpdates` 调用本身健康，但你的主机仍报告误判的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。持续停滞通常意味着主机与 `api.telegram.org` 之间存在代理、DNS、IPv6 或 TLS 出站问题。
- 在直接出站/TLS 不稳定的 VPS 主机上，可通过 `channels.telegram.proxy` 让 Telegram API 调用走代理：
- Node 22+ + 自定义 fetch/proxy 可能会在 AbortSignal 类型不匹配时触发立即中止行为。
- 某些主机会优先将 `api.telegram.org` 解析为 IPv6；损坏的 IPv6 出站连接可能导致 Telegram API 间歇性失败。
- 如果日志包含 `TypeError: fetch failed` 或 `Network request for 'getUpdates' failed!`，OpenClaw 现在会将其作为可恢复的网络错误进行重试。
- 如果日志包含 `Polling stall detected`，默认情况下，OpenClaw 会在 120 秒内没有完成的长轮询存活信号后重启轮询并重建 Telegram 传输。
- 只有当长时间运行的 `getUpdates` 调用本身是健康的，但你的主机仍然报告误报的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。持续的停滞通常意味着主机与 `api.telegram.org` 之间存在代理、DNS、IPv6 或 TLS 出站问题。
- 在出站连接/TLS 不稳定的 VPS 主机上，可通过 `channels.telegram.proxy` 路由 Telegram API 调用：
```yaml
channels:
@ -860,7 +861,7 @@ channels:
```
- Node 22+ 默认使用 `autoSelectFamily=true`（WSL2 除外）和 `dnsResultOrder=ipv4first`。
- 如果你的主机是 WSL2，或明确在仅 IPv4 行为下工作得更好，请强制指定地址族选择：
- 如果你的主机是 WSL2，或者明确在仅 IPv4 模式下工作更稳定，请强制指定地址族选择：
```yaml
channels:
@ -869,8 +870,7 @@ channels:
autoSelectFamily: false
```
- RFC 2544 基准范围地址（`198.18.0.0/15`）默认已经允许用于 Telegram 媒体下载。
如果受信任的 fake-IP 或透明代理在媒体下载期间将 `api.telegram.org` 重写为其他私有/内部/特殊用途地址，你可以选择启用仅限 Telegram 的绕过：
- RFC 2544 基准范围地址（`198.18.0.0/15`）默认已被允许用于 Telegram 媒体下载。如果受信任的 fake-IP 或透明代理在媒体下载期间将 `api.telegram.org` 重写到其他私有/内部/特殊用途地址，你可以选择启用仅限 Telegram 的绕过：
```yaml
channels:
@ -879,14 +879,12 @@ channels:
dangerouslyAllowPrivateNetwork: true
```
- 相同的启用项也可按账号设置在
- 同样的可选设置也可按账户使用，路径为
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`。
- 如果你的代理将 Telegram 媒体主机解析到 `198.18.x.x`，请先保持危险标志关闭。Telegram 媒体默认已经允许 RFC 2544 基准范围。
- 如果你的代理将 Telegram 媒体主机解析到 `198.18.x.x`，请先保持危险标志关闭。Telegram 媒体默认已允许 RFC 2544 基准范围。
<Warning>
`channels.telegram.network.dangerouslyAllowPrivateNetwork` 会削弱 Telegram
媒体 SSRF 保护。仅在受信任的、由操作员控制的代理环境中使用它，
例如 Clash、Mihomo 或 Surge 的 fake-IP 路由，且这些环境会在 RFC 2544 基准范围之外合成私有或特殊用途响应。对于普通公网 Telegram 访问，请保持关闭。
`channels.telegram.network.dangerouslyAllowPrivateNetwork` 会削弱 Telegram 媒体 SSRF 防护。仅在受信任的、由操作员控制的代理环境中使用，例如 Clash、Mihomo 或 Surge 的 fake-IP 路由场景，且它们会在 RFC 2544 基准范围之外合成私有地址或特殊用途地址答案时才启用。对于普通公网 Telegram 访问，请保持关闭。
</Warning>
- 环境变量覆盖（临时）：
@ -907,19 +905,19 @@ dig +short api.telegram.org AAAA
## 配置参考
主参考文档：[配置参考 - Telegram](/zh-CN/gateway/config-channels#telegram)。
主要参考：[配置参考 - Telegram](/zh-CN/gateway/config-channels#telegram)。
<Accordion title="高信号 Telegram 字段">
- 启动/认证：`enabled`、`botToken`、`tokenFile`、`accounts.*`（`tokenFile` 必须指向常规文件；符号链接会被拒绝）
- 访问控制：`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups`、`groups.*.topics.*`、顶层 `bindings[]`（`type: "acp"`）
- 执行批准：`execApprovals`、`accounts.*.execApprovals`
- exec 审批：`execApprovals`、`accounts.*.execApprovals`
- 命令/菜单：`commands.native`、`commands.nativeSkills`、`customCommands`
- 线程/回复：`replyToMode`
- 流式传输：`streaming`（预览）、`streaming.preview.toolProgress`、`blockStreaming`
- 格式化/投递：`textChunkLimit`、`chunkMode`、`linkPreview`、`responsePrefix`
- 媒体/网络：`mediaMaxMb`、`timeoutSeconds`、`pollingStallThresholdMs`、`retry`、`network.autoSelectFamily`、`network.dangerouslyAllowPrivateNetwork`、`proxy`
- webhook：`webhookUrl`、`webhookSecret`、`webhookPath`、`webhookHost`
- Webhook：`webhookUrl`、`webhookSecret`、`webhookPath`、`webhookHost`
- 操作/能力：`capabilities.inlineButtons`、`actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
- 反应：`reactionNotifications`、`reactionLevel`
- 错误：`errorPolicy`、`errorCooldownMs`
@ -928,14 +926,14 @@ dig +short api.telegram.org AAAA
</Accordion>
<Note>
多账号优先级：当配置了两个或更多账号 ID 时，请设置 `channels.telegram.defaultAccount`（或包含 `channels.telegram.accounts.default`）以显式指定默认路由。否则 OpenClaw 会回退到第一个规范化后的账号 ID，并且 `openclaw doctor` 会发出警告。命名账号会继承 `channels.telegram.allowFrom` / `groupAllowFrom`，但不会继承 `accounts.default.*` 的值。
多账户优先级：当配置了两个或更多账户 ID 时，请设置 `channels.telegram.defaultAccount`（或包含 `channels.telegram.accounts.default`），以显式指定默认路由。否则 OpenClaw 会回退到第一个规范化账户 ID，并且 `openclaw doctor` 会发出警告。命名账户会继承 `channels.telegram.allowFrom` / `groupAllowFrom`，但不会继承 `accounts.default.*` 的值。
</Note>
## 相关内容
<CardGroup cols={2}>
<Card title="配对" icon="link" href="/zh-CN/channels/pairing">
将 Telegram 用户与网关配对。
将 Telegram 用户与 Gateway 网关配对。
</Card>
<Card title="群组" icon="users" href="/zh-CN/channels/groups">
群组和话题 allowlist 行为。
@ -944,7 +942,7 @@ dig +short api.telegram.org AAAA
将入站消息路由到智能体。
</Card>
<Card title="安全" icon="shield" href="/zh-CN/gateway/security">
威胁模型与加固。
威胁模型和加固。
</Card>
<Card title="多智能体路由" icon="sitemap" href="/zh-CN/concepts/multi-agent">
将群组和话题映射到智能体。

600
docs/zh-CN/gateway/configuration-reference.md
View File

@ -2,73 +2,73 @@
read_when:
- 你需要精确到字段级别的配置语义或默认值
- 你正在验证渠道、模型、Gateway 网关或工具配置块
summary: Gateway 网关 配置参考，涵盖核心 OpenClaw 键名、默认值，以及指向各专用子系统参考文档的链接
summary: Gateway 网关配置参考，涵盖 OpenClaw 核心键名、默认值，以及指向专用子系统参考文档的链接
title: 配置参考
x-i18n:
generated_at: "2026-04-25T07:51:42Z"
generated_at: "2026-04-25T08:43:04Z"
model: gpt-5.4
provider: openai
source_hash: fd4ebfce263df22d2daa8e0a01e8ab7f590f86b424c534a85d39a25cee98e053
source_hash: debcc9f7151314c02484a3b801bb0e2270b982e9d59567506a032762696aff1c
source_path: gateway/configuration-reference.md
workflow: 15
---
`~/.openclaw/openclaw.json` 的核心配置参考。若需面向任务的概览，请参阅 [配置](/zh-CN/gateway/configuration)。
`~/.openclaw/openclaw.json` 的核心配置参考。若需面向任务的概览，请参见 [Configuration](/zh-CN/gateway/configuration)。
本页涵盖 OpenClaw 的主要配置面，并在某个子系统有自己更深入的参考文档时提供外链。由渠道和插件自行维护的命令目录，以及深入的内存/QMD 调节项，分别位于各自页面，而不是集中放在本页。
本文涵盖 OpenClaw 的主要配置层面，并在某个子系统拥有更深入的独立参考时提供对应链接。由渠道和插件自行维护的命令目录，以及更深入的 memory/QMD 选项，分别位于各自页面中，而不在本文中说明。
代码层面的真实来源：
代码事实依据：
- `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置/插件/渠道元数据
- `config.schema.lookup` 会返回一个按路径划分的 schema 节点，供下钻工具使用
- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 面，校验配置文档基线哈希值
- `config.schema.lookup` 会返回一个按路径范围限定的 schema 节点，供下钻工具使用
- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 层面，验证配置文档基线哈希
专门的深入参考文档：
专门的深度参考：
- [内存配置参考](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置
- [斜杠命令](/zh-CN/tools/slash-commands)，适用于当前内置 + 内置打包的命令目录
- 各自所属的渠道/插件页面，适用于渠道特定的命令面
- [Memory configuration reference](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置
- [Slash commands](/zh-CN/tools/slash-commands)，适用于当前内置 + 随附的命令目录
- 各自所属的渠道/插件页面，适用于特定渠道的命令层面
配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段均为可选——省略时，OpenClaw 会使用安全的默认值。
配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的——省略时，OpenClaw 会使用安全的默认值。
---
## 渠道
各渠道配置键已迁移到专门页面——请参阅
[配置——渠道](/zh-CN/gateway/config-channels)，了解 `channels.*`，
包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 及其他
每个渠道的配置键已迁移到专门页面——请参见
[Configuration — channels](/zh-CN/gateway/config-channels) 了解 `channels.*`，
其中包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage，以及其他
内置渠道（认证、访问控制、多账号、提及门控）。
## 智能体默认值、多智能体、会话和消息
已迁移到专门页面——请参阅
[配置——智能体](/zh-CN/gateway/config-agents)，内容包括：
已迁移到专门页面——请参见
[Configuration — agents](/zh-CN/gateway/config-agents)，其中包括：
- `agents.defaults.*`（工作区、模型、思考、心跳、内存、媒体、Skills、沙箱）
- `agents.defaults.*`（工作区、模型、思考、心跳、记忆、媒体、Skills、沙箱）
- `multiAgent.*`（多智能体路由和绑定）
- `session.*`（会话生命周期、压缩、修剪）
- `session.*`（会话生命周期、压缩、清理）
- `messages.*`（消息投递、TTS、Markdown 渲染）
- `talk.*`（Talk 模式）
- `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录内容前保留平台默认的停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）
- `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录文本前保持平台默认的停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）
## 工具和自定义提供商
工具策略、实验性开关、由提供商支持的工具配置，以及自定义
提供商 / base-URL 设置，已迁移到专门页面——请参阅
[配置——工具和自定义提供商](/zh-CN/gateway/config-tools)。
提供商 / base-URL 设置，已迁移到专门页面——请参见
[Configuration — tools and custom providers](/zh-CN/gateway/config-tools)。
## MCP
由 OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，
供嵌入式 Pi 和其他运行时适配器使用。`openclaw mcp list`、
`show`、`set` 和 `unset` 命令可在编辑配置时管理该配置块，
且不会连接目标服务器。
`show`、`set` 和 `unset` 命令可管理该配置块，而不会在编辑配置时连接到
目标服务器。
```json5
{
mcp: {
// 可选。默认值：600000 ms（10 分钟）。设为 0 可禁用空闲驱逐。
// Optional. Default: 600000 ms (10 minutes). Set 0 to disable idle eviction.
sessionIdleTtlMs: 600000,
servers: {
docs: {
@ -87,16 +87,16 @@ x-i18n:
}
```
- `mcp.servers`：为暴露已配置 MCP 工具的运行时提供命名的 stdio 或远程 MCP 服务器定义。
- `mcp.sessionIdleTtlMs`：面向会话作用域的内置 MCP 运行时的空闲 TTL。
一次性嵌入式运行会请求在运行结束时清理；该 TTL 是
- `mcp.servers`：为暴露已配置 MCP 工具的运行时提供具名的 stdio 或远程 MCP 服务器定义。
- `mcp.sessionIdleTtlMs`：会话范围内随附 MCP 运行时的空闲 TTL。
一次性嵌入运行会请求在运行结束时清理；此 TTL 是针对
长生命周期会话和未来调用方的兜底机制。
- `mcp.*` 下的变更会通过释放缓存的会话 MCP 运行时来热应用。
下一次工具发现/使用时会根据新配置重新创建它们，因此已移除的
`mcp.servers` 条目会立即被回收，而不是等到空闲 TTL 到期。
- `mcp.*` 下的更改会通过释放已缓存的会话 MCP 运行时来热应用。
下一次工具发现/使用时会根据新配置重新创建它们，因此被移除的
`mcp.servers` 条目会立即清理，而不是等待空闲 TTL 到期。
有关运行时行为，请参阅 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和
[CLI 后端](/zh-CN/gateway/cli-backends#bundle-mcp-overlays)。
运行时行为请参见 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和
[CLI backends](/zh-CN/gateway/cli-backends#bundle-mcp-overlays)。
## Skills
@ -124,13 +124,11 @@ x-i18n:
```
- `allowBundled`：仅适用于内置 Skills 的可选允许列表（托管/工作区 Skills 不受影响）。
- `load.extraDirs`：额外的共享 Skill 根目录（优先级最低）。
- `install.preferBrew`：当为 true 且存在 `brew` 时，优先使用 Homebrew 安装器，
然后才回退到其他安装器类型。
- `install.nodeManager`：用于 `metadata.openclaw.install`
规范的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。
- `entries.<skillKey>.enabled: false`：即使 Skill 已内置/安装，也会禁用该 Skill。
- `entries.<skillKey>.apiKey`：为声明主环境变量的 Skill 提供的便捷字段（明文字符串或 SecretRef 对象）。
- `load.extraDirs`：额外的共享 skill 根目录（优先级最低）。
- `install.preferBrew`：当为 true 时，如果 `brew` 可用，则优先使用 Homebrew 安装器，再回退到其他安装器类型。
- `install.nodeManager`：`metadata.openclaw.install` 规范的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。
- `entries.<skillKey>.enabled: false`：即使某个 skill 已内置/已安装，也会将其禁用。
- `entries.<skillKey>.apiKey`：为声明了主要环境变量的 skills 提供的便捷字段（明文字符串或 SecretRef 对象）。
---
@ -159,44 +157,44 @@ x-i18n:
```
- 从 `~/.openclaw/extensions`、`<workspace>/.openclaw/extensions` 以及 `plugins.load.paths` 加载。
- 设备发现支持原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。
- **配置变更需要重启 Gateway 网关。**
- 设备发现接受原生 OpenClaw plugins，以及兼容的 Codex bundles 和 Claude bundles，包括无 manifest 的 Claude 默认布局 bundle。
- **配置更改需要重启 Gateway 网关。**
- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。
- `plugins.entries.<id>.apiKey`：插件级 API key 便捷字段（当插件支持时）。
- `plugins.entries.<id>.apiKey`：插件级 API 密钥便捷字段（当插件支持时）。
- `plugins.entries.<id>.env`：插件作用域的环境变量映射。
- `plugins.entries.<id>.hooks.allowPromptInjection`：当为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示词的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子，以及受支持的由 bundle 提供的钩子目录。
- `plugins.entries.<id>.hooks.allowConversationAccess`：当为 `true` 时，受信任的非内置插件可以从类型化钩子（如 `llm_input`、`llm_output` 和 `agent_end`）中读取原始对话内容。
- `plugins.entries.<id>.subagent.allowModelOverride`：显式信任此插件，使其可为后台子智能体运行请求按次运行的 `provider` 和 `model` 覆盖。
- `plugins.entries.<id>.subagent.allowedModels`：受信任子智能体覆盖的规范 `provider/model` 目标可选允许列表。仅当你确实想允许任意模型时，才使用 `"*"`。
- `plugins.entries.<id>.config`：插件定义的配置对象（可在可用时由原生 OpenClaw 插件 schema 验证）。
- 渠道插件的账号/运行时设置位于 `channels.<id>` 下，应由所属插件 manifest 的 `channelConfigs` 元数据描述，而不是由 OpenClaw 的中央选项注册表描述。
- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web-fetch 提供商设置。
- `apiKey`：Firecrawl API key（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。
- `baseUrl`：Firecrawl API 基础 URL（默认值：`https://api.firecrawl.dev`）。
- `onlyMainContent`：仅提取页面主体内容（默认值：`true`）。
- `maxAgeMs`：最大缓存时长（毫秒）（默认值：`172800000` / 2 天）。
- `timeoutSeconds`：抓取请求超时时间（秒）（默认值：`60`）。
- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web 搜索）设置。
- `plugins.entries.<id>.hooks.allowPromptInjection`：当为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示词的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子以及受支持的 bundle 提供的钩子目录。
- `plugins.entries.<id>.hooks.allowConversationAccess`：当为 `true` 时，受信任的非内置插件可以从 `llm_input`、`llm_output` 和 `agent_end` 等类型化钩子中读取原始会话内容。
- `plugins.entries.<id>.subagent.allowModelOverride`：显式信任该插件可为后台子智能体运行请求按次运行的 `provider` 和 `model` 覆盖。
- `plugins.entries.<id>.subagent.allowedModels`：受信任子智能体覆盖的规范 `provider/model` 目标可选允许列表。仅当你明确希望允许任意模型时，才使用 `"*"`。
- `plugins.entries.<id>.config`：插件定义的配置对象（若可用，则由原生 OpenClaw 插件 schema 验证）。
- 渠道插件的账号/运行时设置位于 `channels.<id>` 下，应由所属插件 manifest 中的 `channelConfigs` 元数据描述，而不是由集中式 OpenClaw 选项注册表描述。
- `plugins.entries.firecrawl.config.webFetch`：Firecrawl 网页抓取提供商设置。
- `apiKey`：Firecrawl API 密钥（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey`，或 `FIRECRAWL_API_KEY` 环境变量。
- `baseUrl`：Firecrawl API base URL（默认：`https://api.firecrawl.dev`）。
- `onlyMainContent`：仅提取页面主体内容（默认：`true`）。
- `maxAgeMs`：最大缓存时长（毫秒）（默认：`172800000` / 2 天）。
- `timeoutSeconds`：抓取请求超时时间（秒）（默认：`60`）。
- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok 网页搜索）设置。
- `enabled`：启用 X Search 提供商。
- `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。
- `plugins.entries.memory-core.config.dreaming`：内存 dreaming 设置。有关阶段和阈值，请参阅 [Dreaming](/zh-CN/concepts/dreaming)。
- `enabled`：dreaming 总开关（默认值为 `false`）。
- `frequency`：每次完整 dreaming 扫描的 cron 频率（默认值为 `"0 3 * * *"`）。
- `plugins.entries.memory-core.config.dreaming`：memory dreaming 设置。阶段和阈值请参见 [Dreaming](/zh-CN/concepts/dreaming)。
- `enabled`：dreaming 总开关（默认 `false`）。
- `frequency`：每次完整 dreaming 扫描的 cron 频率（默认 `"0 3 * * *"`）。
- 阶段策略和阈值属于实现细节（不是面向用户的配置键）。
- 完整的内存配置位于 [内存配置参考](/zh-CN/reference/memory-config)：
- 完整 memory 配置位于 [Memory configuration reference](/zh-CN/reference/memory-config)：
- `agents.defaults.memorySearch.*`
- `memory.backend`
- `memory.citations`
- `memory.qmd.*`
- `plugins.entries.memory-core.config.dreaming`
- 已启用的 Claude bundle 插件也可以通过 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为经过清理的智能体设置应用，而不是作为原始 OpenClaw 配置补丁应用。
- `plugins.slots.memory`：选择当前活动的内存插件 id，或使用 `"none"` 禁用内存插件。
- `plugins.slots.contextEngine`：选择当前活动的上下文引擎插件 id；默认值为 `"legacy"`，除非你安装并选择了其他引擎。
- 已启用的 Claude bundle 插件也可以通过 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为已清理的智能体设置应用，而不是作为原始 OpenClaw 配置补丁应用。
- `plugins.slots.memory`：选择活动 memory 插件 id，或使用 `"none"` 禁用 memory 插件。
- `plugins.slots.contextEngine`：选择活动上下文引擎插件 id；默认值为 `"legacy"`，除非你安装并选择了其他引擎。
- `plugins.installs`：由 CLI 管理的安装元数据，供 `openclaw plugins update` 使用。
- 包含 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。
- 将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。
- 包括 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。
- 将 `plugins.installs.*` 视为受管状态；优先使用 CLI 命令，而不是手动编辑。
请参阅 [插件](/zh-CN/tools/plugin)。
请参见 [Plugins](/zh-CN/tools/plugin)。
---
@ -209,8 +207,8 @@ x-i18n:
evaluateEnabled: true,
defaultProfile: "user",
ssrfPolicy: {
// dangerouslyAllowPrivateNetwork: true, // 仅在受信任的私有网络访问场景下选择启用
// allowPrivateNetwork: true, // 旧版别名
// dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
// allowPrivateNetwork: true, // legacy alias
// hostnameAllowlist: ["*.example.com", "example.com"],
// allowedHostnames: ["localhost"],
},
@ -247,35 +245,35 @@ x-i18n:
```
- `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。
- `tabCleanup` 会在空闲超时后，或当某个
会话超过其上限时，回收被跟踪的主智能体标签页。将 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 设为
0，可分别禁用这些单独的清理模式。
- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时为禁用状态，因此默认情况下浏览器导航保持严格限制。
- 仅当你明确愿意信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。
- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间，也会受到相同的私有网络阻止限制。
- `tabCleanup` 会在空闲一段时间后，或当某个会话超过其上限时，回收被跟踪的主智能体标签页。将 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 设为
禁用这些各自的清理模式。
- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时为禁用状态，因此浏览器导航默认保持严格模式。
- 仅当你明确选择信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。
- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/发现检查期间也会受到相同的私有网络阻止。
- `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。
- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 进行显式例外配置。
- 远程配置文件为仅附加模式（禁用 start/stop/reset）。
- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 来设置显式例外。
- 远程配置文件仅支持附加模式（禁用 start/stop/reset）。
- `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。
当你希望 OpenClaw 发现 `/json/version` 时，使用 HTTP(S)；当你的提供商直接提供 DevTools WebSocket URL 时，
使用 WS(S)。
当你希望 OpenClaw 发现 `/json/version` 时，请使用 HTTP(S)；使用 WS(S)
则适用于你的提供商直接给出 DevTools WebSocket URL 的情况。
- `existing-session` 配置文件使用 Chrome MCP 而不是 CDP，并且可以附加到
所选主机上，或通过已连接的浏览器节点附加。
- `existing-session` 配置文件可以设置 `userDataDir`，以定位特定的
基于 Chromium 的浏览器配置文件，例如 Brave 或 Edge。
Chromium 内核浏览器配置文件，例如 Brave 或 Edge。
- `existing-session` 配置文件保留当前 Chrome MCP 路由限制：
使用 snapshot/ref 驱动的操作，而不是 CSS 选择器定位；单文件上传
使用基于快照/引用驱动的操作，而不是 CSS 选择器定位；单文件上传
钩子；不支持对话框超时覆盖；不支持 `wait --load networkidle`；也不支持
`responsebody`、PDF 导出、下载拦截或批量操作。
- 本地受管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 场景下
才显式设置 `cdpUrl`。
- 本地受管配置文件可以设置 `executablePath`，以覆盖该配置文件的全局
`browser.executablePath`。可借此让一个配置文件运行在 Chrome 中，另一个运行在 Brave 中。
- 自动检测顺序：默认浏览器（若为基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。
- `browser.executablePath` 接受 `~`，表示你操作系统的 home 目录。
- 控制服务：仅 loopback（端口由 `gateway.port` 派生，默认值为 `18791`）。
- `extraArgs` 会为本地 Chromium 启动追加额外的启动标志（例如
`--disable-gpu`、窗口尺寸设置或调试标志）。
- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 场景下
才需要显式设置 `cdpUrl`。
- 本地托管配置文件可以设置 `executablePath`，以覆盖该配置文件的全局
`browser.executablePath`。你可以用它让一个配置文件运行在 Chrome 中，
另一个运行在 Brave 中。
- 自动检测顺序：默认浏览器（若基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。
- `browser.executablePath` 接受 `~` 作为你操作系统主目录的表示。
- 控制服务：仅限 loopback（端口从 `gateway.port` 派生，默认 `18791`）。
- `extraArgs` 会将额外启动标志追加到本地 Chromium 启动参数中（例如
`--disable-gpu`、窗口大小设置或调试标志）。
---
@ -293,8 +291,8 @@ x-i18n:
}
```
- `seamColor`：原生应用 UI 外框的强调色（Talk Mode 气泡着色等）。
- `assistant`：Control UI 身份覆盖。回退到当前活动智能体身份。
- `seamColor`：原生应用 UI 外框的强调色（Talk 模式气泡着色等）。
- `assistant`：Control UI 身份覆盖。会回退到当前激活智能体的身份。
---
@ -341,20 +339,20 @@ x-i18n:
// password: "your-password",
},
trustedProxies: ["10.0.0.1"],
// 可选。默认值为 false。
// Optional. Default false.
allowRealIpFallback: false,
nodes: {
pairing: {
// 可选。默认未设置/已禁用。
// Optional. Default unset/disabled.
autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"],
},
allowCommands: ["canvas.navigate"],
denyCommands: ["system.run"],
},
tools: {
// 附加的 /tools/invoke HTTP 拒绝项
// Additional /tools/invoke HTTP denies
deny: ["browser"],
// 从默认 HTTP 拒绝列表中移除工具
// Remove tools from the default HTTP deny list
allow: ["gateway"],
},
push: {
@ -371,71 +369,71 @@ x-i18n:
<Accordion title="Gateway 网关字段详情">
- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关拒绝启动。
- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关会拒绝启动。
- `port`：用于 WS + HTTP 的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。
- `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。
- **旧版 bind 别名**：在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用 host 别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。
- **Docker 注意事项**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 Gateway 网关无法访问。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 且 `customBindHost: "0.0.0.0"`）以监听所有接口。
- **认证**：默认必需。非 loopback bind 要求 Gateway 网关认证。实际这意味着使用共享 token/password，或使用配置了 `gateway.auth.mode: "trusted-proxy"` 的身份感知型反向代理。新手引导向导默认会生成一个 token。
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请将 `gateway.auth.mode` 显式设置为 `token` 或 `password`。当两者都已配置但未设置 mode 时，启动和服务安装/修复流程都会失败。
- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的本地 local loopback 设置；新手引导提示中不会提供该选项，这是有意设计。
- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知型反向代理，并信任来自 `gateway.trustedProxies` 的身份头（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求**非 loopback** 的代理来源；同主机 loopback 反向代理不满足 trusted-proxy 认证要求。
- `gateway.auth.allowTailscale`：当为 `true` 时，Tailscale Serve 身份头可满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 头认证；它们仍遵循 Gateway 网关的常规 HTTP 认证模式。该无 token 流程假定 Gateway 网关主机受信任。当 `tailscale.mode = "serve"` 时，默认值为 `true`。
- `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证作用域生效（共享密钥和设备 token 分别独立跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。
- 在异步 Tailscale Serve Control UI 路径中，同一 `{scope, clientIp}` 的失败尝试会在写入失败记录前被串行化。因此，同一客户端的并发错误尝试可能会在第二个请求时触发限流，而不是两个请求都像普通不匹配那样竞态通过。
- `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；若你明确希望连 localhost 流量也被限流（例如测试环境或严格代理部署），请设置为 `false`。
- 来自浏览器源的 WS 认证尝试始终会被限流，且禁用 loopback 豁免（作为防御纵深，防止基于浏览器的 localhost 暴力破解）。
- **旧版 bind 别名**：请在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用 host 别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。
- **Docker 注意事项**：默认的 `loopback` bind 会在容器内部监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 Gateway 网关不可访问。请使用 `--network host`，或设置 `bind: "lan"`（或设置 `bind: "custom"` 并配合 `customBindHost: "0.0.0.0"`）以监听所有接口。
- **认证**：默认必须启用。非 loopback 绑定要求 Gateway 网关认证。实际来说，这意味着要使用共享 token/password，或使用配置了 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成一个 token。
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请将 `gateway.auth.mode` 明确设置为 `token` 或 `password`。如果二者都已配置但未设置 mode，启动以及服务安装/修复流程都会失败。
- `gateway.auth.mode: "none"`：显式无认证模式。仅适用于受信任的本地 local loopback 设置；新手引导提示中不会提供此选项，这是有意设计。
- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份头（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求 **非 loopback** 的代理来源；同机 loopback 反向代理不满足 trusted-proxy 认证要求。
- `gateway.auth.allowTailscale`：当为 `true` 时，Tailscale Serve 身份头可以满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点 **不会** 使用该 Tailscale 头认证；它们仍遵循 Gateway 网关正常的 HTTP 认证模式。此无 token 流程假定 Gateway 网关主机是受信任的。当 `tailscale.mode = "serve"` 时，默认值为 `true`。
- `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证范围生效（共享密钥和设备 token 分别独立跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。
- 在异步 Tailscale Serve Control UI 路径上，同一 `{scope, clientIp}` 的失败尝试会在写入失败记录前被串行化。因此，同一客户端的并发错误尝试可能会在第二个请求时触发限流器，而不是两个请求都作为普通不匹配同时通过。
- `gateway.auth.rateLimit.exemptLoopback` 默认值为 `true`；如果你明确希望 localhost 流量也被限流（例如测试环境或严格代理部署），请将其设为 `false`。
- 来自浏览器源的 WS 认证尝试始终会启用节流，并禁用 loopback 豁免（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。
- 在 loopback 上，这些来自浏览器源的锁定会按归一化后的 `Origin`
值彼此隔离，因此来自某个 localhost 源的重复失败不会自动
锁定另一个源。
- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公网，需要认证）。
- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器源允许列表。若预期浏览器客户端来自非 loopback 源，则必须设置。
- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host 头源策略的部署启用 Host 头源回退。
值隔离，因此来自某一个 localhost origin 的重复失败不会自动
锁定另一个 origin。
- `tailscale.mode`：`serve`（仅 tailnet，loopback 绑定）或 `funnel`（公开访问，需要认证）。
- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器源允许列表。当预计会有来自非 loopback 源的浏览器客户端时必须设置。
- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host 头 origin 策略的部署启用 Host 头 origin 回退。
- `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境变量中的紧急放行开关，
允许使用明文 `ws://` 连接受信任的私有网络
IP；默认仍仅允许 loopback 使用明文。`openclaw.json`
中没有对应项，且浏览器私有网络配置，例如
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境变量中的紧急放行覆盖，
允许对受信任私有网络 IP 使用明文 `ws://`；默认仍然仅允许 loopback 使用明文。
没有对应的 `openclaw.json`
配置项，并且浏览器私有网络相关配置，如
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`，不会影响 Gateway 网关
WebSocket 客户端。
- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。
- `gateway.push.apns.relay.baseUrl`：外部 APNs relay 的基础 HTTPS URL，供官方/TestFlight iOS 构建在向 Gateway 网关发布基于 relay 的注册后使用。该 URL 必须与编译进 iOS 构建中的 relay URL 一致。
- `gateway.remote.token` / `.password`：远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。
- `gateway.push.apns.relay.baseUrl`：外部 APNs relay 的基础 HTTPS URL，供官方/TestFlight iOS 构建在向 Gateway 网关发布基于 relay 的注册后使用。此 URL 必须与编译进 iOS 构建中的 relay URL 一致。
- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时时间（毫秒）。默认值：`10000`。
- 基于 relay 的注册会委托给特定的 Gateway 网关身份。已配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并向 Gateway 网关转发一个作用于该注册的发送授权。另一个 Gateway 网关无法复用该已存储注册。
- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：用于覆盖上述 relay 配置的临时环境变量。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅供开发使用的逃生开关，用于允许使用 loopback HTTP relay URL。生产环境 relay URL 应保持使用 HTTPS。
- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔（分钟）。设为 `0` 可全局禁用健康监控重启。默认值：`5`。
- `gateway.channelStaleEventThresholdMinutes`：陈旧套接字阈值（分钟）。请保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。
- `gateway.channelMaxRestartsPerHour`：每个渠道/账号在滚动一小时内允许的最大健康监控重启次数。默认值：`10`。
- `channels.<provider>.healthMonitor.enabled`：渠道级退出设置，可在保留全局监控启用的同时禁用健康监控重启。
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`：多账号渠道的账号级覆盖。设置后，其优先级高于渠道级覆盖。
- 本地 Gateway 网关调用路径仅在 `gateway.auth.*` 未设置时，才可回退使用 `gateway.remote.*`。
- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 但未解析成功，解析将以关闭方式失败（不会用远程回退来掩盖问题）。
- `trustedProxies`：终止 TLS 或注入转发客户端头的反向代理 IP。仅列出你控制的代理。loopback 条目对于同主机代理/本地检测设置仍然有效（例如 Tailscale Serve 或本地反向代理），但它们**不会**使 loopback 请求符合 `gateway.auth.mode: "trusted-proxy"` 的条件。
- `allowRealIpFallback`：当为 `true` 时，若缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认值为 `false`，以实现失败即关闭的行为。
- `gateway.nodes.pairing.autoApproveCidrs`：可选的 CIDR/IP 允许列表，用于自动批准首次节点设备配对，前提是不请求任何作用域。未设置时为禁用状态。它不会自动批准 operator/browser/Control UI/WebChat 配对，也不会自动批准角色、作用域、元数据或公钥升级。
- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：在配对和允许列表评估之后，对已声明节点命令进行全局允许/拒绝整形。
- `gateway.tools.deny`：对 HTTP `POST /tools/invoke` 额外阻止的工具名称（扩展默认拒绝列表）。
- `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名称。
- 基于 relay 的注册会委托给某个特定 Gateway 网关身份。配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并向 Gateway 网关转发一个按注册范围限定的发送授权。另一个 Gateway 网关无法复用该已存储的注册。
- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：对上述 relay 配置的临时环境变量覆盖。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅供开发使用的逃生阀，允许 loopback HTTP relay URL。生产环境的 relay URL 应保持为 HTTPS。
- `gateway.channelHealthCheckMinutes`：渠道健康监视间隔，单位为分钟。设为 `0` 可全局禁用健康监视重启。默认值：`5`。
- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值，单位为分钟。请保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。
- `gateway.channelMaxRestartsPerHour`：每个渠道/账号在滚动一小时内允许的最大健康监视重启次数。默认值：`10`。
- `channels.<provider>.healthMonitor.enabled`：每个渠道单独选择退出健康监视重启，同时保留全局监视器启用状态。
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`：多账号渠道中每个账号的覆盖设置。设置后，其优先级高于渠道级覆盖。
- 本地 Gateway 网关调用路径仅会在 `gateway.auth.*` 未设置时，将 `gateway.remote.*` 作为回退使用。
- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 但无法解析，则解析会以失败关闭方式处理（不会由远程回退掩盖）。
- `trustedProxies`：终止 TLS 或注入转发客户端头的反向代理 IP。只列出你控制的代理。loopback 条目对于同机代理/本地检测设置仍然有效（例如 Tailscale Serve 或本地反向代理），但它们 **不会** 让 loopback 请求符合 `gateway.auth.mode: "trusted-proxy"` 的条件。
- `allowRealIpFallback`：当为 `true` 时，如果缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认值为 `false`，以保持失败关闭行为。
- `gateway.nodes.pairing.autoApproveCidrs`：用于自动批准首次节点设备配对且未请求任何 scope 的可选 CIDR/IP 允许列表。未设置时禁用。它不会自动批准 operator/browser/Control UI/WebChat 配对，也不会自动批准角色、scope、元数据或公钥升级。
- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：在配对和允许列表评估之后，对已声明节点命令进行全局 allow/deny 控制。
- `gateway.tools.deny`：为 HTTP `POST /tools/invoke` 额外阻止的工具名（扩展默认 deny 列表）。
- `gateway.tools.allow`：从默认 HTTP deny 列表中移除工具名。
</Accordion>
### OpenAI 兼容端点
- Chat Completions：默认禁用。通过 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。
- Chat Completions：默认禁用。使用 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。
- Responses API：`gateway.http.endpoints.responses.enabled`。
- Responses URL 输入加固：
- `gateway.http.endpoints.responses.maxUrlParts`
- `gateway.http.endpoints.responses.files.urlAllowlist`
- `gateway.http.endpoints.responses.images.urlAllowlist`
空允许列表会被视为未设置；请使用 `gateway.http.endpoints.responses.files.allowUrl=false`
空 allowlist 会被视为未设置；请使用 `gateway.http.endpoints.responses.files.allowUrl=false`
和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 来禁用 URL 抓取。
- 可选的响应加固头：
- `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS 源设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)）
### 多实例隔离
在同一主机上运行多个 Gateway 网关时，请使用唯一的端口和状态目录：
在同一主机上运行多个 Gateway 网关时，请为每个实例使用唯一端口和状态目录：
```bash
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
@ -443,9 +441,9 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001
```
便捷标志：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`）、`--profile <name>`（使用 `~/.openclaw-<name>`）。
便捷标志：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`），`--profile <name>`（使用 `~/.openclaw-<name>`）。
参见 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。
请参见 [Multiple Gateways](/zh-CN/gateway/multiple-gateways)。
### `gateway.tls`
@ -463,8 +461,8 @@ openclaw gateway --port 19001
}
```
- `enabled`：在 Gateway 网关监听器上启用 TLS 终止（HTTPS/WSS）（默认值：`false`）。
- `autoGenerate`：当未配置显式文件时，自动生成本地自签名 cert/key 对；仅用于本地/开发环境。
- `enabled`：在 Gateway 网关监听器处启用 TLS 终止（HTTPS/WSS）（默认：`false`）。
- `autoGenerate`：当未配置显式文件时，自动生成本地自签名证书/密钥对；仅适用于本地/开发用途。
- `certPath`：TLS 证书文件的文件系统路径。
- `keyPath`：TLS 私钥文件的文件系统路径；请保持权限受限。
- `caPath`：可选的 CA bundle 路径，用于客户端验证或自定义信任链。
@ -477,19 +475,19 @@ openclaw gateway --port 19001
reload: {
mode: "hybrid", // off | restart | hot | hybrid
debounceMs: 500,
deferralTimeoutMs: 300000,
deferralTimeoutMs: 0,
},
},
}
```
- `mode`：控制在运行时如何应用配置编辑。
- `"off"`：忽略实时编辑；变更需要显式重启。
- `"restart"`：配置变更时始终重启 Gateway 网关进程。
- `"hot"`：在不重启的情况下于进程内应用变更。
- `"hybrid"`（默认）：先尝试热重载；若有需要则回退为重启。
- `debounceMs`：应用配置变更前的防抖窗口（毫秒）（非负整数）。
- `deferralTimeoutMs`：在强制重启前等待进行中操作完成的最长时间（毫秒）（默认值：`300000` = 5 分钟）。
- `mode`：控制如何在运行时应用配置编辑。
- `"off"`：忽略实时编辑；更改需要显式重启。
- `"restart"`：配置更改时始终重启 Gateway 网关进程。
- `"hot"`：在不重启的情况下进程内应用更改。
- `"hybrid"`（默认）：先尝试热重载；如有需要则回退到重启。
- `debounceMs`：应用配置更改前的去抖窗口，单位为毫秒（非负整数）。
- `deferralTimeoutMs`：可选的最长等待时间，单位为毫秒，用于等待进行中的操作完成后再强制重启。省略或设为 `0` 表示无限等待，并定期记录仍在等待中的警告。
---
@ -529,21 +527,21 @@ openclaw gateway --port 19001
认证：`Authorization: Bearer <token>` 或 `x-openclaw-token: <token>`。
拒绝使用查询字符串中的 hook token。
验证与安全说明：
验证和安全说明：
- `hooks.enabled=true` 要求 `hooks.token` 为非空。
- `hooks.token` 必须与 `gateway.auth.token` **不同**；复用 Gateway 网关 token 会被拒绝。
- `hooks.path` 不能为 `/`；请使用专用子路径，例如 `/hooks`。
- `hooks.path` 不能是 `/`；请使用专用子路径，例如 `/hooks`。
- 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。
- 如果某个映射或预设使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要该显式启用。
- 如果某个 mapping 或 preset 使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态 mapping 键不需要该显式启用。
**端点：**
- `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }`
- `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }`
- 仅当 `hooks.allowRequestSessionKey=true` 时，才接受请求负载中的 `sessionKey`（默认值：`false`）。
- 仅当 `hooks.allowRequestSessionKey=true` 时，才接受请求负载中的 `sessionKey`（默认：`false`）。
- `POST /hooks/<name>` → 通过 `hooks.mappings` 解析
- 通过模板渲染得到的映射 `sessionKey` 值会被视为外部提供，因此同样要求 `hooks.allowRequestSessionKey=true`。
- 模板渲染得到的 mapping `sessionKey` 值会被视为外部提供，因此也要求 `hooks.allowRequestSessionKey=true`。
<Accordion title="映射详情">
@ -551,22 +549,22 @@ openclaw gateway --port 19001
- `match.source` 匹配通用路径中的某个负载字段。
- 像 `{{messages[0].subject}}` 这样的模板会从负载中读取。
- `transform` 可以指向一个返回 hook 动作的 JS/TS 模块。
- `transform.module` 必须是相对路径，并保持在 `hooks.transformsDir` 范围内（绝对路径和路径遍历会被拒绝）。
- `transform.module` 必须是相对路径，并且必须保持在 `hooks.transformsDir` 范围内（绝对路径和路径穿越会被拒绝）。
- `agentId` 会路由到指定智能体；未知 ID 会回退到默认值。
- `allowedAgentIds`：限制显式路由（`*` 或省略 = 全部允许，`[]` = 全部拒绝）。
- `defaultSessionKey`：可选的固定会话键，用于未显式提供 `sessionKey` 的 hook 智能体运行。
- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方以及由模板驱动的映射会话键设置 `sessionKey`（默认值：`false`）。
- `allowedSessionKeyPrefixes`：用于显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任意映射或预设使用模板化 `sessionKey` 时，它就成为必填项。
- `defaultSessionKey`：可选的固定会话键，用于没有显式 `sessionKey` 的 hook 智能体运行。
- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方以及模板驱动的 mapping 会话键设置 `sessionKey`（默认：`false`）。
- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + mapping）的可选前缀允许列表，例如 `["hook:"]`。当任意 mapping 或 preset 使用模板化 `sessionKey` 时，它会成为必填项。
- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认为 `last`。
- `model` 会覆盖此次 hook 运行使用的 LLM（如果设置了模型目录，则必须在允许范围内）。
- `model`：为此次 hook 运行覆盖 LLM（如果设置了模型目录，则必须是允许的模型）。
</Accordion>
### Gmail 集成
- 内置 Gmail 预设使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。
- 如果你保留这种按消息路由的方式，请设置 `hooks.allowRequestSessionKey: true`，并约束 `hooks.allowedSessionKeyPrefixes` 以匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。
- 如果你需要 `hooks.allowRequestSessionKey: false`，请用静态 `sessionKey` 覆盖该预设，而不是使用模板化默认值。
- 内置 Gmail preset 使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。
- 如果你保留这种按消息路由方式，请设置 `hooks.allowRequestSessionKey: true`，并约束 `hooks.allowedSessionKeyPrefixes` 以匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。
- 如果你需要 `hooks.allowRequestSessionKey: false`，请使用静态 `sessionKey` 覆盖该 preset，而不要使用模板化默认值。
```json5
{
@ -590,7 +588,7 @@ openclaw gateway --port 19001
```
- 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用。
- 不要与 Gateway 网关同时单独运行另一个 `gog gmail watch serve`。
- 不要在 Gateway 网关旁边额外运行单独的 `gog gmail watch serve`。
---
@ -610,14 +608,14 @@ openclaw gateway --port 19001
- `http://<gateway-host>:<gateway.port>/__openclaw__/canvas/`
- `http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/`
- 仅限本地：请保持 `gateway.bind: "loopback"`（默认）。
- 非 loopback bind：canvas 路由与其他 Gateway 网关 HTTP 面一样，需要 Gateway 网关认证（token/password/trusted-proxy）。
- 节点 WebView 通常不会发送认证头；节点完成配对并连接后，Gateway 网关会为 canvas/A2UI 访问公布节点作用域能力 URL。
- 能力 URL 绑定到当前活动的节点 WS 会话，并且很快过期。不使用基于 IP 的回退。
- 会将 live-reload 客户端注入到所提供的 HTML 中。
- 为空时会自动创建起始 `index.html`。
- 非 loopback 绑定：canvas 路由与其他 Gateway 网关 HTTP 层面一样，需要 Gateway 网关认证（token/password/trusted-proxy）。
- Node WebViews 通常不会发送认证头；节点完成配对并连接后，Gateway 网关会公布带有节点作用域能力 URL，供 canvas/A2UI 访问使用。
- 能力 URL 绑定到当前激活的节点 WS 会话，并且很快过期。不使用基于 IP 的回退。
- 会向所提供的 HTML 中注入实时重载客户端。
- 为空时会自动创建初始 `index.html`。
- 也会在 `/__openclaw__/a2ui/` 提供 A2UI。
- 变更需要重启 Gateway 网关。
- 对于大型目录或出现 `EMFILE` 错误时，请禁用 live reload。
- 更改需要重启 Gateway 网关。
- 对于大型目录或出现 `EMFILE` 错误时，请禁用实时重载。
---
@ -635,8 +633,8 @@ openclaw gateway --port 19001
}
```
- `minimal`（默认）：在 TXT 记录中省略 `cliPath` 和 `sshPort`。
- `full`：包含 `cliPath` 和 `sshPort`。
- `minimal`（默认）：在 TXT 记录中省略 `cliPath` + `sshPort`。
- `full`：包含 `cliPath` + `sshPort`。
- 主机名默认为 `openclaw`。可通过 `OPENCLAW_MDNS_HOSTNAME` 覆盖。
### 广域（DNS-SD）
@ -649,7 +647,7 @@ openclaw gateway --port 19001
}
```
会在 `~/.openclaw/dns/` 下写入一个单播 DNS-SD 区域。若需跨网络设备发现，请配合 DNS 服务器（推荐 CoreDNS）和 Tailscale split DNS 一起使用。
会在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。若要实现跨网络设备发现，请配合 DNS 服务器（推荐 CoreDNS）+ Tailscale split DNS。
设置：`openclaw dns setup --apply`。
@ -674,10 +672,10 @@ openclaw gateway --port 19001
}
```
- 仅当进程环境中缺少该键时，才会应用内联环境变量。
- `.env` 文件：当前工作目录下的 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。
- 仅当进程环境中缺少对应键时，才会应用内联环境变量。
- `.env` 文件：当前工作目录下的 `.env` + `~/.openclaw/.env`（两者都不会覆盖已有变量）。
- `shellEnv`：从你的登录 shell 配置文件中导入缺失的预期键名。
- 完整优先级请参阅 [环境](/zh-CN/help/environment)。
- 完整优先级请参见 [Environment](/zh-CN/help/environment)。
### 环境变量替换
@ -693,18 +691,18 @@ openclaw gateway --port 19001
- 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。
- 缺失/为空的变量会在加载配置时抛出错误。
- 使用 `$${VAR}` 来转义，得到字面量 `${VAR}`。
- 使用 `$${VAR}` 可转义为字面量 `${VAR}`。
- 适用于 `$include`。
---
## 密钥
## Secrets
SecretRef 采用增量方式：明文值仍然可用。
SecretRef 是增量特性：明文值仍然可用。
### `SecretRef`
使用以下对象结构：
使用以下对象形态：
```json5
{ source: "env" | "file" | "exec", provider: "default", id: "..." }
@ -718,13 +716,13 @@ SecretRef 采用增量方式：明文值仍然可用。
- `source: "exec"` 的 id 模式：`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
- `source: "exec"` 的 id 不得包含以斜杠分隔的 `.` 或 `..` 路径段（例如 `a/../b` 会被拒绝）
### 支持的凭证面
### 支持的凭证层面
- 规范矩阵：[SecretRef 凭证面](/zh-CN/reference/secretref-credential-surface)
- `secrets apply` 以受支持的 `openclaw.json` 凭证路径为目标。
- `auth-profiles.json` 中的引用会被纳入运行时解析和审计覆盖范围。
- 规范矩阵：[SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface)
- `secrets apply` 面向受支持的 `openclaw.json` 凭证路径。
- `auth-profiles.json` 中的 ref 也包含在运行时解析和审计覆盖范围内。
### 密钥提供商配置
### Secret providers 配置
```json5
{
@ -754,14 +752,14 @@ SecretRef 采用增量方式：明文值仍然可用。
说明：
- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。
- 当 Windows ACL 验证不可用时，file 和 exec 提供商路径会以关闭方式失败。仅对无法验证但受信任的路径设置 `allowInsecurePath: true`。
- `exec` 提供商要求使用绝对 `command` 路径，并通过 stdin/stdout 使用协议负载。
- `file` provider 支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。
- 当 Windows ACL 验证不可用时，file 和 exec provider 路径会以失败关闭方式处理。仅对无法验证但受信任的路径设置 `allowInsecurePath: true`。
- `exec` provider 要求使用绝对 `command` 路径，并通过 stdin/stdout 使用协议负载。
- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时验证解析后的目标路径。
- 如果配置了 `trustedDirs`，则受信任目录检查会应用到解析后的目标路径。
- `exec` 子进程环境默认最小化；请通过 `passEnv` 显式传入所需变量。
- SecretRef 会在激活时解析到内存快照中，之后请求路径只读取该快照。
- 激活期间会应用活动面过滤：已启用面的未解析引用会导致启动/重载失败，而非活动面会被跳过并输出诊断信息。
- 如果配置了 `trustedDirs`，受信任目录检查会应用于解析后的目标路径。
- `exec` 子进程环境默认最小化；请使用 `passEnv` 显式传递所需变量。
- Secret ref 会在激活时解析为内存中的快照，之后请求路径仅从该快照读取。
- 激活期间会应用活跃层面过滤：启用层面上的未解析 ref 会导致启动/重载失败，而非活跃层面会被跳过并记录诊断信息。
---
@ -783,13 +781,13 @@ SecretRef 采用增量方式：明文值仍然可用。
}
```
- 按智能体划分的配置文件存储在 `<agentDir>/auth-profiles.json`。
- `auth-profiles.json` 支持值级引用（静态凭证模式下，`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。
- OAuth 模式配置文件（`auth.profiles.<id>.mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。
- 静态运行时凭证来自已解析的内存快照；发现旧版静态 `auth.json` 条目时会将其清除。
- 每个智能体的 profile 存储在 `<agentDir>/auth-profiles.json`。
- `auth-profiles.json` 支持值级 ref（静态凭证模式下，`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。
- OAuth 模式的 profile（`auth.profiles.<id>.mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。
- 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会进行清理。
- 旧版 OAuth 会从 `~/.openclaw/credentials/oauth.json` 导入。
- 参见 [OAuth](/zh-CN/concepts/oauth)。
- 密钥运行时行为及 `audit/configure/apply` 工具：参见 [密钥管理](/zh-CN/gateway/secrets)。
- 请参见 [OAuth](/zh-CN/concepts/oauth)。
- Secrets 运行时行为以及 `audit/configure/apply` 工具：请参见 [Secrets Management](/zh-CN/gateway/secrets)。
### `auth.cooldowns`
@ -811,20 +809,20 @@ SecretRef 采用增量方式：明文值仍然可用。
}
```
- `billingBackoffHours`：当某个配置文件因真实的
账单/额度不足错误而失败时，基础回退时间（小时）（默认值：`5`）。明确的账单文本
- `billingBackoffHours`：当某个 profile 因真实的
计费/余额不足错误而失败时使用的基础回退时长（小时）（默认：`5`）。明确的计费文本
即使出现在 `401`/`403` 响应中，仍可能归入这里，但提供商特定的文本
匹配器仍限定在其所属提供商范围内（例如 OpenRouter
的 `Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或
组织/工作区支出上限消息则仍归入 `rate_limit` 路径。
- `billingBackoffHoursByProvider`：按提供商覆盖账单回退小时数的可选配置。
- `billingMaxHours`：账单回退指数增长的小时上限（默认值：`24`）。
- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础回退时间（分钟）（默认值：`10`）。
- `authPermanentMaxMinutes`：`auth_permanent` 回退增长的分钟上限（默认值：`60`）。
- `failureWindowHours`：用于回退计数器的滚动窗口（小时）（默认值：`24`）。
- `overloadedProfileRotations`：在切换到模型回退前，针对过载错误允许的同一提供商 auth-profile 轮换最大次数（默认值：`1`）。例如 `ModelNotReadyException` 这类提供商繁忙形态就归入这里。
- `overloadedBackoffMs`：在重试过载提供商/配置文件轮换前的固定延迟（毫秒）（默认值：`0`）。
- `rateLimitedProfileRotations`：在切换到模型回退前，针对限流错误允许的同一提供商 auth-profile 轮换最大次数（默认值：`1`）。该限流桶包括提供商形态文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。
匹配器仍然只作用于拥有该匹配规则的提供商（例如 OpenRouter
`Key limit exceeded`）。可重试的 HTTP `402` 用量窗口或
organization/workspace 支出上限消息则仍归入 `rate_limit` 路径。
- `billingBackoffHoursByProvider`：按提供商覆盖计费回退时长（小时）的可选配置。
- `billingMaxHours`：计费回退指数增长的上限时长（小时）（默认：`24`）。
- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础回退时长（分钟）（默认：`10`）。
- `authPermanentMaxMinutes`：`auth_permanent` 回退增长的上限时长（分钟）（默认：`60`）。
- `failureWindowHours`：用于回退计数器的滚动窗口时长（小时）（默认：`24`）。
- `overloadedProfileRotations`：对于过载错误，在切换到模型回退前，同一提供商 auth-profile 允许的最大轮换次数（默认：`1`）。像 `ModelNotReadyException` 这样的提供商繁忙形态归入这里。
- `overloadedBackoffMs`：在重试过载提供商/profile 轮换前的固定延迟（毫秒）（默认：`0`）。
- `rateLimitedProfileRotations`：对于限流错误，在切换到模型回退前，同一提供商 auth-profile 允许的最大轮换次数（默认：`1`）。该限流桶包括提供商形态的文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。
---
@ -844,9 +842,9 @@ SecretRef 采用增量方式：明文值仍然可用。
```
- 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。
- 设置 `logging.file` 可使用稳定路径。
- 使用 `--verbose` 时，`consoleLevel` 会提升到 `debug`。
- `maxFileBytes`：在抑制写入前允许的最大日志文件大小（字节）（正整数；默认值：`524288000` = 500 MB）。生产部署请使用外部日志轮转。
- 设置 `logging.file` 可使用固定路径。
- 当使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。
- `maxFileBytes`：在抑制写入前允许的最大日志文件大小（字节）（正整数；默认：`524288000` = 500 MB）。生产部署请使用外部日志轮转。
---
@ -891,22 +889,22 @@ SecretRef 采用增量方式：明文值仍然可用。
}
```
- `enabled`：仪表输出的总开关（默认值：`true`）。
- `flags`：用于启用定向日志输出的标志字符串数组（支持 `"telegram.*"` 或 `"*"` 之类的通配符）。
- `stuckSessionWarnMs`：当会话持续处于处理中状态时，发出卡住会话警告的时间阈值（毫秒）。
- `otel.enabled`：启用 OpenTelemetry 导出管线（默认值：`false`）。
- `otel.endpoint`：用于 OTel 导出的 collector URL。
- `enabled`：检测输出的总开关（默认：`true`）。
- `flags`：用于启用定向日志输出的标志字符串数组（支持通配符，如 `"telegram.*"` 或 `"*"`）。
- `stuckSessionWarnMs`：当某个会话仍处于处理状态时，发出卡住会话警告的时长阈值（毫秒）。
- `otel.enabled`：启用 OpenTelemetry 导出管线（默认：`false`）。
- `otel.endpoint`：用于 OTel 导出的收集器 URL。
- `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。
- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据头。
- `otel.serviceName`：资源属性的服务名称。
- `otel.serviceName`：资源属性中的服务名称。
- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或日志导出。
- `otel.sampleRate`：trace 采样率，范围 `0`–`1`。
- `otel.sampleRate`：trace 采样率 `0`–`1`。
- `otel.flushIntervalMs`：定期刷新遥测数据的时间间隔（毫秒）。
- `otel.captureContent`：用于 OTel span 属性的原始内容捕获选择性启用项。默认关闭。布尔值 `true` 会捕获非 system 的消息/工具内容；对象形式则可让你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。
- `OPENCLAW_OTEL_PRELOADED=1`：适用于已经注册了全局 OpenTelemetry SDK 的主机的环境开关。OpenClaw 随后会跳过插件自有的 SDK 启动/关闭，同时保持诊断监听器处于活动状态。
- `cacheTrace.enabled`：为嵌入式运行记录缓存跟踪快照（默认值：`false`）。
- `cacheTrace.filePath`：缓存跟踪 JSONL 的输出路径（默认值：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。
- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出中包含哪些内容（默认均为 `true`）。
- `otel.captureContent`：为 OTEL span 属性选择性启用原始内容捕获。默认关闭。布尔值 `true` 会捕获非 system 消息/工具内容；对象形式允许你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。
- `OPENCLAW_OTEL_PRELOADED=1`：适用于已注册全局 OpenTelemetry SDK 的主机的环境变量开关。此时 OpenClaw 会跳过插件自有的 SDK 启动/关闭，同时保持诊断监听器处于活动状态。
- `cacheTrace.enabled`：为嵌入式运行记录缓存 trace 快照（默认：`false`）。
- `cacheTrace.filePath`：缓存 trace JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。
- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存 trace 输出中包含哪些内容（默认均为：`true`）。
---
@ -928,12 +926,12 @@ SecretRef 采用增量方式：明文值仍然可用。
}
```
- `channel`：适用于 npm/git 安装的发布渠道——`"stable"`、`"beta"` 或 `"dev"`。
- `checkOnStart`：Gateway 网关启动时检查 npm 更新（默认值：`true`）。
- `auto.enabled`：为包安装启用后台自动更新（默认值：`false`）。
- `auto.stableDelayHours`：stable 渠道自动应用前的最小延迟（小时）（默认值：`6`；最大值：`168`）。
- `auto.stableJitterHours`：stable 渠道额外发布扩散窗口（小时）（默认值：`12`；最大值：`168`）。
- `auto.betaCheckIntervalHours`：beta 渠道检查运行频率（小时）（默认值：`1`；最大值：`24`）。
- `channel`：npm/git 安装的发布渠道——`"stable"`、`"beta"` 或 `"dev"`。
- `checkOnStart`：Gateway 网关启动时检查 npm 更新（默认：`true`）。
- `auto.enabled`：为包安装启用后台自动更新（默认：`false`）。
- `auto.stableDelayHours`：stable 渠道自动应用前的最小延迟时长（小时）（默认：`6`；最大：`168`）。
- `auto.stableJitterHours`：stable 渠道额外的发布扩散窗口时长（小时）（默认：`12`；最大：`168`）。
- `auto.betaCheckIntervalHours`：beta 渠道检查运行的频率（小时）（默认：`1`；最大：`24`）。
---
@ -966,22 +964,22 @@ SecretRef 采用增量方式：明文值仍然可用。
}
```
- `enabled`：全局 ACP 功能门控（默认值：`false`）。
- `dispatch.enabled`：ACP 会话轮次分发的独立门控（默认值：`true`）。设为 `false` 可在保留 ACP 命令可用的同时阻止执行。
- `enabled`：全局 ACP 功能门控（默认：`false`）。
- `dispatch.enabled`：ACP 会话轮次分发的独立门控（默认：`true`）。设为 `false` 可保留 ACP 命令可用，同时阻止执行。
- `backend`：默认 ACP 运行时后端 id（必须与已注册的 ACP 运行时插件匹配）。
- `defaultAgent`：当 spawn 未指定显式目标时，ACP 目标智能体 id 的回退值。
- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 列表；空值表示无额外限制。
- `maxConcurrentSessions`：同时处于活动状态的 ACP 会话最大数量。
- `maxConcurrentSessions`：允许同时处于活动状态的 ACP 会话最大数量。
- `stream.coalesceIdleMs`：流式文本的空闲合并刷新窗口（毫秒）。
- `stream.maxChunkChars`：拆分流式块投影前的最大块大小。
- `stream.repeatSuppression`：按轮次抑制重复的状态/工具行（默认值：`true`）。
- `stream.maxChunkChars`：流式块投影在拆分前允许的最大块大小。
- `stream.repeatSuppression`：每轮抑制重复的状态/工具行（默认：`true`）。
- `stream.deliveryMode`：`"live"` 表示增量流式传输；`"final_only"` 表示缓冲到轮次终止事件后再输出。
- `stream.hiddenBoundarySeparator`：隐藏工具事件后、可见文本前的分隔符（默认值：`"paragraph"`）。
- `stream.maxOutputChars`：每个 ACP 轮次投影的智能体输出最大字符数。
- `stream.maxSessionUpdateChars`：投影的 ACP 状态/更新行最大字符数。
- `stream.tagVisibility`：记录 tag 名称到布尔可见性覆盖值的映射，用于流式事件。
- `runtime.ttlMinutes`：ACP 会话工作进程在可清理前的空闲 TTL（分钟）。
- `runtime.installCommand`：在引导 ACP 运行时环境时执行的可选安装命令。
- `stream.hiddenBoundarySeparator`：在隐藏工具事件后的可见文本前使用的分隔符（默认：`"paragraph"`）。
- `stream.maxOutputChars`：每个 ACP 轮次可投影的智能体输出最大字符数。
- `stream.maxSessionUpdateChars`：投影 ACP 状态/更新行的最大字符数。
- `stream.tagVisibility`：标签名称到布尔可见性覆盖的映射记录，用于流式事件。
- `runtime.ttlMinutes`：ACP 会话 worker 在可清理前的空闲 TTL（分钟）。
- `runtime.installCommand`：可选安装命令，在引导 ACP 运行时环境时执行。
---
@ -998,8 +996,8 @@ SecretRef 采用增量方式：明文值仍然可用。
```
- `cli.banner.taglineMode` 控制 banner 标语样式：
- `"random"`（默认）：轮换显示有趣/季节性标语。
- `"default"`：固定中性标语（`All your chats, one OpenClaw.`）。
- `"random"`（默认）：轮换的有趣/季节性标语。
- `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。
- `"off"`：不显示标语文本（仍显示 banner 标题/版本）。
- 若要隐藏整个 banner（而不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。
@ -1025,13 +1023,13 @@ SecretRef 采用增量方式：明文值仍然可用。
## 身份
请参阅 [智能体默认值](/zh-CN/gateway/config-agents#agent-defaults) 下 `agents.list` 的身份字段。
请参见 [Agent defaults](/zh-CN/gateway/config-agents#agent-defaults) 下的 `agents.list` 身份字段。
---
## Bridge protocol（旧版节点，历史参考）（旧版，已移除）
## Bridge protocol（旧版节点，历史参考）
当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前验证会失败；`openclaw doctor --fix` 可以清除未知键）。
当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前验证会失败；`openclaw doctor --fix` 可以移除未知键）。
<Accordion title="旧版 bridge 配置（历史参考）">
@ -1071,11 +1069,11 @@ SecretRef 采用增量方式：明文值仍然可用。
}
```
- `sessionRetention`：在从 `sessions.json` 修剪前，保留已完成的隔离 cron 运行会话多长时间。也控制已归档的已删除 cron 转录内容的清理。默认值：`24h`；设为 `false` 可禁用。
- `runLog.maxBytes`：每个运行日志文件（`cron/runs/<jobId>.jsonl`）在触发修剪前的最大大小。默认值：`2_000_000` 字节。
- `runLog.keepLines`：触发运行日志修剪时保留的最新行数。默认值：`2000`。
- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；若省略则不会发送认证头。
- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于仍保留 `notify: true` 的已存储任务。
- `sessionRetention`：在从 `sessions.json` 中清理之前，保留已完成的独立 cron 运行会话的时长。也控制已归档的已删除 cron 转录的清理。默认：`24h`；设为 `false` 可禁用。
- `runLog.maxBytes`：每个运行日志文件（`cron/runs/<jobId>.jsonl`）在清理前允许的最大大小。默认：`2_000_000` 字节。
- `runLog.keepLines`：触发运行日志清理时保留的最新行数。默认：`2000`。
- `webhookToken`：用于 cron webhook POST 投递的 bearer token（`delivery.mode = "webhook"`）；若省略则不会发送认证头。
- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于仍保留 `notify: true` 的已存储作业。
### `cron.retry`
@ -1091,11 +1089,11 @@ SecretRef 采用增量方式：明文值仍然可用。
}
```
- `maxAttempts`：一次性任务在瞬时错误下的最大重试次数（默认值：`3`；范围：`0`–`10`）。
- `backoffMs`：每次重试尝试对应的回退延迟数组（毫秒）（默认值：`[30000, 60000, 300000]`；1–10 个条目）。
- `maxAttempts`：一次性作业在瞬时错误下的最大重试次数（默认：`3`；范围：`0`–`10`）。
- `backoffMs`：每次重试尝试的回退延迟数组，单位为毫秒（默认：`[30000, 60000, 300000]`；1–10 项）。
- `retryOn`：触发重试的错误类型——`"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略则重试所有瞬时类型。
仅适用于一次性 cron 任务。周期性任务使用单独的失败处理机制。
仅适用于一次性 cron 作业。周期性作业使用单独的失败处理机制。
### `cron.failureAlert`
@ -1113,10 +1111,10 @@ SecretRef 采用增量方式：明文值仍然可用。
}
```
- `enabled`：为 cron 任务启用失败告警（默认值：`false`）。
- `after`：在触发告警前的连续失败次数（正整数，最小值：`1`）。
- `cooldownMs`：同一任务重复告警之间的最小间隔（毫秒）（非负整数）。
- `mode`：投递模式——`"announce"` 通过渠道消息发送；`"webhook"` 向已配置的 webhook 发送 POST。
- `enabled`：启用 cron 作业失败告警（默认：`false`）。
- `after`：连续失败多少次后触发告警（正整数，最小值：`1`）。
- `cooldownMs`：同一作业重复告警之间的最小间隔（毫秒）（非负整数）。
- `mode`：投递模式——`"announce"` 通过渠道消息发送；`"webhook"` 向已配置的 webhook 发起 POST。
- `accountId`：可选的账号或渠道 id，用于限定告警投递范围。
### `cron.failureDestination`
@ -1134,16 +1132,16 @@ SecretRef 采用增量方式：明文值仍然可用。
}
```
- 所有任务共用的 cron 失败通知默认目标。
- `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认使用 `"announce"`。
- `channel`：announce 投递的渠道覆盖值。`"last"` 会复用上次已知的投递渠道。
- `to`：显式的 announce 目标或 webhook URL。webhook 模式下为必填。
- 所有作业共用的 cron 失败通知默认目标。
- `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认值为 `"announce"`。
- `channel`：announce 投递的渠道覆盖值。`"last"` 会复用最后一次已知的投递渠道。
- `to`：显式的 announce 目标或 webhook URL。webhook 模式下必填。
- `accountId`：可选的投递账号覆盖值。
- 单个任务的 `delivery.failureDestination` 会覆盖该全局默认值。
- 当全局和单任务失败目标都未设置时，已经通过 `announce` 投递的任务在失败时会回退到其主 announce 目标。
- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 的任务，除非该任务的主 `delivery.mode` 为 `"webhook"`。
- 每个作业的 `delivery.failureDestination` 会覆盖这个全局默认值。
- 当全局和每个作业的失败目标都未设置时，已经通过 `announce` 投递的作业会在失败时回退到其主要 announce 目标。
- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 的作业，除非该作业的主 `delivery.mode` 为 `"webhook"`。
请参阅 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为 [后台任务](/zh-CN/automation/tasks) 跟踪。
请参见 [Cron Jobs](/zh-CN/automation/cron-jobs)。独立 cron 执行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。
---
@ -1151,34 +1149,34 @@ SecretRef 采用增量方式：明文值仍然可用。
在 `tools.media.models[].args` 中展开的模板占位符：
| Variable | 描述 |
| 变量 | 说明 |
| ------------------ | ------------------------------------------------- |
| `{{Body}}` | 完整的传入消息正文 |
| `{{RawBody}}` | 原始正文（无历史记录/发送者包装） |
| `{{BodyStripped}}` | 已去除群组提及的正文 |
| `{{From}}` | 发送者标识符 |
| `{{To}}` | 目标标识符 |
| `{{MessageSid}}` | 渠道消息 id |
| `{{SessionId}}` | 当前会话 UUID |
| `{{IsNewSession}}` | 创建新会话时为 `"true"` |
| `{{MediaUrl}}` | 传入媒体伪 URL |
| `{{MediaPath}}` | 本地媒体路径 |
| `{{MediaType}}` | 媒体类型（image/audio/document/…） |
| `{{Transcript}}` | 音频转录内容 |
| `{{Prompt}}` | CLI 条目的已解析媒体提示词 |
| `{{MaxChars}}` | CLI 条目的已解析最大输出字符数 |
| `{{Body}}` | 完整的入站消息正文 |
| `{{RawBody}}` | 原始正文（无历史记录/发送者包装） |
| `{{BodyStripped}}` | 去除群组提及后的正文 |
| `{{From}}` | 发送者标识符 |
| `{{To}}` | 目标标识符 |
| `{{MessageSid}}` | 渠道消息 id |
| `{{SessionId}}` | 当前会话 UUID |
| `{{IsNewSession}}` | 新建会话时为 `"true"` |
| `{{MediaUrl}}` | 入站媒体伪 URL |
| `{{MediaPath}}` | 本地媒体路径 |
| `{{MediaType}}` | 媒体类型（image/audio/document/…） |
| `{{Transcript}}` | 音频转录文本 |
| `{{Prompt}}` | 用于 CLI 条目的已解析媒体提示词 |
| `{{MaxChars}}` | 用于 CLI 条目的已解析最大输出字符数 |
| `{{ChatType}}` | `"direct"` 或 `"group"` |
| `{{GroupSubject}}` | 群组主题（尽力而为） |
| `{{GroupMembers}}` | 群组成员预览（尽力而为） |
| `{{SenderName}}` | 发送者显示名称（尽力而为） |
| `{{SenderE164}}` | 发送者电话号码（尽力而为） |
| `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） |
| `{{GroupSubject}}` | 群组主题（尽力而为） |
| `{{GroupMembers}}` | 群组成员预览（尽力而为） |
| `{{SenderName}}` | 发送者显示名称（尽力而为） |
| `{{SenderE164}}` | 发送者电话号码（尽力而为） |
| `{{Provider}}` | provider 提示（whatsapp、telegram、discord 等） |
---
## 配置包含（`$include`）
## 配置 include（`$include`）
将配置拆分为多个文件：
将配置拆分到多个文件中：
```json5
// ~/.openclaw/openclaw.json
@ -1193,20 +1191,20 @@ SecretRef 采用增量方式：明文值仍然可用。
**合并行为：**
- 单个文件：替换其所在的对象。
- 单个文件：替换所在的对象。
- 文件数组：按顺序深度合并（后者覆盖前者）。
- 同级键：在包含项之后合并（覆盖已包含的值）。
- 嵌套包含：最多 10 层。
- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。仅当绝对路径/`../` 形式最终仍解析到该边界内时才允许。
- 当 OpenClaw 自有写入仅变更一个由单文件 include 支持的顶层 section 时，会直接写回该包含文件。例如，`plugins install` 会更新 `plugins: { $include: "./plugins.json5" }` 中的 `plugins.json5`，并保持 `openclaw.json` 不变。
- 根级 includes、include 数组，以及带有同级覆盖的 includes 对 OpenClaw 自有写入来说是只读的；这些写入会以关闭方式失败，而不是将配置拍平。
- 错误：对缺失文件、解析错误和循环包含提供清晰的错误消息。
- 同级键：会在 includes 之后合并（覆盖已包含的值）。
- 嵌套 include：最多 10 层深。
- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。仅当绝对路径/`../` 形式最终仍解析到该边界内时，才允许使用。
- 仅更改某个由单文件 include 支持的顶层 section 的 OpenClaw 自有写入，会直写到该包含文件中。例如，`plugins install` 会更新 `plugins: { $include: "./plugins.json5" }` 中的 `plugins.json5`，并保持 `openclaw.json` 不变。
- 根级 include、include 数组以及带有同级覆盖的 include，对于 OpenClaw 自有写入而言是只读的；这些写入会以失败关闭方式处理，而不是将配置展平。
- 错误：对缺失文件、解析错误和循环 include 提供清晰消息。
---
_相关内容：[配置](/zh-CN/gateway/configuration) · [配置示例](/zh-CN/gateway/configuration-examples) · [Doctor](/zh-CN/gateway/doctor)_
_相关内容：[Configuration](/zh-CN/gateway/configuration) · [Configuration Examples](/zh-CN/gateway/configuration-examples) · [Doctor](/zh-CN/gateway/doctor)_
## 相关
- [配置](/zh-CN/gateway/configuration)
- [配置示例](/zh-CN/gateway/configuration-examples)
- [Configuration](/zh-CN/gateway/configuration)
- [Configuration examples](/zh-CN/gateway/configuration-examples)