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-05-02 10:14:37 +00:00
parent a5bd9ad158
commit b09e6327a4
3 changed files with 540 additions and 549 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -4,15 +4,15 @@ read_when:
summary: Telegram 机器人支持状态、能力和配置
title: Telegram
x-i18n:
generated_at: "2026-05-02T10:03:53Z"
generated_at: "2026-05-02T10:12:03Z"
model: gpt-5.5
provider: openai
source_hash: da808a835655730721cb887d0eb3b9160b681d88e7ba791d50286aaeabc353e7
source_hash: 4b5a733970f21e6b5a145b9ebb13134fb8e18b81fa0c723607019837c60f5497
source_path: channels/telegram.md
workflow: 16
---
生产就绪，可通过 grammY 用于机器人私信和群组。默认模式是长轮询；webhook 模式是可选项。
生产级可用，支持通过 grammY 处理机器人私信和群组。长轮询是默认模式；Webhook 模式是可选的。
<CardGroup cols={3}>
<Card title="配对" icon="link" href="/zh-CN/channels/pairing">
@ -30,7 +30,7 @@ x-i18n:
<Steps>
<Step title="在 BotFather 中创建机器人令牌">
打开 Telegram 并与 **@BotFather** 聊天（确认名称正好是 `@BotFather`）。
打开 Telegram 并与 **@BotFather** 聊天（确认用户名正好是 `@BotFather`）。
运行 `/newbot`，按提示操作，并保存令牌。
@ -69,19 +69,19 @@ openclaw pairing approve telegram <CODE>
</Step>
<Step title="将机器人添加到群组">
将机器人添加到你的群组，然后设置 `channels.telegram.groups` 和 `groupPolicy` 以匹配你的访问模型。
将机器人添加到你的群组，然后设置 `channels.telegram.groups` 和 `groupPolicy`，使其匹配你的访问模型。
</Step>
</Steps>
<Note>
令牌解析顺序会感知账号。实践中，配置值优先于环境变量回退，而 `TELEGRAM_BOT_TOKEN` 只适用于默认账号。
令牌解析顺序是账号感知的。实际使用中，配置值优先于环境变量回退，且 `TELEGRAM_BOT_TOKEN` 只适用于默认账号。
</Note>
## Telegram 侧设置
## Telegram 端设置
<AccordionGroup>
<Accordion title="隐私模式和群组可见性">
Telegram 机器人默认使用**隐私模式**，这会限制它们能接收哪些群组消息。
Telegram 机器人默认启用**隐私模式**，这会限制它们能接收哪些群组消息。
如果机器人必须看到所有群组消息，可以：
@ -111,34 +111,34 @@ openclaw pairing approve telegram <CODE>
<Tabs>
<Tab title="私信策略">
`channels.telegram.dmPolicy` 控制私信访问：
`channels.telegram.dmPolicy` 控制直接消息访问：
- `pairing`（默认）
- `allowlist`（要求 `allowFrom` 中至少有一个发送者 ID）
- `open`（要求 `allowFrom` 包含 `"*"`）
- `open`（要求 `allowFrom` 包含 `"*"`)
- `disabled`
`dmPolicy: "open"` 配合 `allowFrom: ["*"]` 会让任何找到或猜到机器人用户名的 Telegram 账号都能指挥机器人。只应将它用于有严格工具限制的有意公开机器人；单所有者机器人应使用带数字用户 ID 的 `allowlist`。
`dmPolicy: "open"` 搭配 `allowFrom: ["*"]` 会让任何找到或猜到机器人用户名的 Telegram 账号都能命令机器人。仅应将它用于有意公开、且工具权限严格受限的机器人；单所有者机器人应使用包含数字用户 ID 的 `allowlist`。
`channels.telegram.allowFrom` 接受数字 Telegram 用户 ID。`telegram:` / `tg:` 前缀会被接受并规范化。
在多账号配置中，限制性的顶层 `channels.telegram.allowFrom` 会被视为安全边界：账号级 `allowFrom: ["*"]` 条目不会让该账号公开，除非合并后的有效账号允许列表仍包含显式通配符。
`dmPolicy: "allowlist"` 搭配空的 `allowFrom` 会阻止所有私信，并会被配置校验拒绝。
设置只会要求输入数字用户 ID。
如果你已升级，并且配置中包含 `@username` 允许列表条目，请运行 `openclaw doctor --fix` 来解析它们（尽力而为；需要 Telegram 机器人令牌）。
如果你已升级，且配置包含 `@username` 允许列表条目，请运行 `openclaw doctor --fix` 解析它们（尽力而为；需要 Telegram 机器人令牌）。
如果你之前依赖配对存储允许列表文件，`openclaw doctor --fix` 可以在允许列表流程中将条目恢复到 `channels.telegram.allowFrom`（例如当 `dmPolicy: "allowlist"` 尚无显式 ID 时）。
对于单所有者机器人，建议使用带显式数字 `allowFrom` ID 的 `dmPolicy: "allowlist"`，以便在配置中持久化访问策略（而不是依赖之前的配对批准）。
对于单所有者机器人，优先使用带显式数字 `allowFrom` ID 的 `dmPolicy: "allowlist"`，以便将访问策略持久保存在配置中（而不是依赖之前的配对批准）。
常见混淆：私信配对批准并不表示“这个发送者在所有地方都已授权”。
配对授予私信访问权限。如果还没有命令所有者，第一次获批配对也会设置 `commands.ownerAllowFrom`，让仅所有者命令和 exec 批准拥有显式操作员账号。
常见困惑：私信配对批准并不表示“该发送者在所有位置都已授权”。
配对授予私信访问权限。如果尚不存在命令所有者，首次批准的配对还会设置 `commands.ownerAllowFrom`，让仅所有者命令和 exec 批准拥有显式操作员账号。
群组发送者授权仍来自显式配置允许列表。
如果你想要“我授权一次后，私信和群组命令都可用”，请将你的数字 Telegram 用户 ID 放入 `channels.telegram.allowFrom`；对于仅所有者命令，请确保 `commands.ownerAllowFrom` 包含 `telegram:<your user id>`。
### 查找你的 Telegram 用户 ID
更安全（无第三方机器人）：
更安全（无需第三方机器人）：
1. 私信你的机器人。
1. 给你的机器人发私信。
2. 运行 `openclaw logs --follow`。
3. 读取 `from.id`。
@ -156,9 +156,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
两项控制会共同生效：
1. **允许哪些群组**（`channels.telegram.groups`）
- 没有 `groups` 配置：
- 使用 `groupPolicy: "open"`：任何群组都能通过群组 ID 检查
- 使用 `groupPolicy: "allowlist"`（默认）：在添加 `groups` 条目（或 `"*"`）之前，群组会被阻止
- 无 `groups` 配置：
- 使用 `groupPolicy: "open"` 时：任何群组都可以通过群组 ID 检查
- 使用 `groupPolicy: "allowlist"`（默认）时：群组会被阻止，直到你添加 `groups` 条目（或 `"*"`）
- 已配置 `groups`：作为允许列表（显式 ID 或 `"*"`）
2. **群组中允许哪些发送者**（`channels.telegram.groupPolicy`）
@ -168,15 +168,15 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
`groupAllowFrom` 用于群组发送者过滤。如果未设置，Telegram 会回退到 `allowFrom`。
`groupAllowFrom` 条目应为数字 Telegram 用户 ID（`telegram:` / `tg:` 前缀会被规范化）。
不要将 Telegram 群组或超级群组聊天 ID 放入 `groupAllowFrom`。负数聊天 ID 属于 `channels.telegram.groups`。
非数字条目会被发送者授权忽略。
安全边界（`2026.2.25+`）：群组发送者身份验证**不会**继承私信配对存储批准。
配对仅限私信。对于群组，请设置 `groupAllowFrom` 或按群组/按话题设置 `allowFrom`。
不要将 Telegram 群组或超级群聊天 ID 放入 `groupAllowFrom`。负数聊天 ID 应放在 `channels.telegram.groups` 下。
非数字条目会在发送者授权中被忽略。
安全边界（`2026.2.25+`）：群组发送者认证**不会**继承私信配对存储批准。
配对仅限私信。对于群组，请设置 `groupAllowFrom` 或每群组/每话题的 `allowFrom`。
如果未设置 `groupAllowFrom`，Telegram 会回退到配置中的 `allowFrom`，而不是配对存储。
单所有者机器人的实用模式：在 `channels.telegram.allowFrom` 中设置你的用户 ID，保持 `groupAllowFrom` 未设置，并在 `channels.telegram.groups` 下允许目标群组。
运行时说明：如果完全缺少 `channels.telegram`，除非显式设置了 `channels.defaults.groupPolicy`，运行时默认会故障关闭为 `groupPolicy="allowlist"`。
运行时说明：如果完全缺少 `channels.telegram`，运行时会默认故障关闭为 `groupPolicy="allowlist"`，除非显式设置了 `channels.defaults.groupPolicy`。
示例：允许一个特定群组中的任何成员：
示例：允许某个特定群组中的任何成员：
```json5
{
@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
示例：只允许一个特定群组中的特定用户：
示例：仅允许某个特定群组中的特定用户：
```json5
{
@ -213,9 +213,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
<Warning>
常见错误：`groupAllowFrom` 不是 Telegram 群组允许列表。
- 将类似 `-1001234567890` 的负数 Telegram 群组或超级群组聊天 ID 放在 `channels.telegram.groups` 下。
- 当你想限制已允许群组中哪些人可以触发机器人时，将类似 `8734062810` 的 Telegram 用户 ID 放在 `groupAllowFrom` 下。
- 只有当你希望已允许群组中的任何成员都能与机器人对话时，才使用 `groupAllowFrom: ["*"]`。
- 将 `-1001234567890` 这样的负数 Telegram 群组或超级群聊天 ID 放在 `channels.telegram.groups` 下。
- 当你想限制允许群组中哪些人可以触发机器人时，将 `8734062810` 这样的 Telegram 用户 ID 放在 `groupAllowFrom` 下。
- 仅当你希望允许群组中的任何成员都能与机器人交谈时，才使用 `groupAllowFrom: ["*"]`。
</Warning>
@ -227,7 +227,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
提及可以来自：
- 原生 `@botusername` 提及，或
- 以下位置的提及模式：
- 以下位置中的提及模式：
- `agents.list[].groupChat.mentionPatterns`
- `messages.groupChat.mentionPatterns`
@ -236,7 +236,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `/activation always`
- `/activation mention`
这些只会更新会话状态。请使用配置实现持久化。
这些只会更新会话状态。使用配置来实现持久化。
持久化配置示例：
@ -265,18 +265,18 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- Telegram 由 Gateway 网关进程拥有。
- 路由是确定性的：Telegram 入站会回复到 Telegram（模型不会选择渠道）。
- 入站消息会规范化为共享渠道信封，并包含回复元数据和媒体占位符。
- 群组会话按群组 ID 隔离。论坛话题会附加 `:topic:<threadId>` 以保持话题隔离。
- 私信消息可以携带 `message_thread_id`；OpenClaw 会保留线程 ID 用于回复，但默认让私信保持在扁平会话中。当你确实需要私信话题会话隔离时，请配置 `channels.telegram.dm.threadReplies: "inbound"`、`channels.telegram.direct.<chatId>.threadReplies: "inbound"`、`requireTopic: true`，或匹配的话题配置。
- 长轮询使用 grammY runner，并按聊天/按线程排序。整体 runner sink 并发使用 `agents.defaults.maxConcurrent`。
- 长轮询在每个 Gateway 网关进程内有保护，因此同一时间只有一个活动轮询器可以使用一个机器人令牌。如果你仍看到 `getUpdates` 409 冲突，很可能是另一个 OpenClaw Gateway 网关、脚本或外部轮询器正在使用同一个令牌。
- 长轮询看门狗重启默认会在 120 秒内没有完成的 `getUpdates` 存活信号后触发。只有当你的部署在长时间运行的工作期间仍出现误判的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。该值以毫秒为单位，允许范围为 `30000` 到 `600000`；支持按账号覆盖。
- 入站消息会规范化为共享渠道信封，并带有回复元数据和媒体占位符。
- 群组会话按群组 ID 隔离。论坛话题会追加 `:topic:<threadId>`，以保持话题隔离。
- 私信消息可以携带 `message_thread_id`；OpenClaw 会保留线程 ID 用于回复，但默认将私信保持在扁平会话上。当你有意想要私信话题会话隔离时，请配置 `channels.telegram.dm.threadReplies: "inbound"`、`channels.telegram.direct.<chatId>.threadReplies: "inbound"`、`requireTopic: true`，或匹配的话题配置。
- 长轮询使用 grammY runner，并按每聊天/每线程排序。整体 runner sink 并发使用 `agents.defaults.maxConcurrent`。
- 每个 Gateway 网关进程内部会保护长轮询，因此同一时间只有一个活跃轮询器可以使用某个机器人令牌。如果你仍然看到 `getUpdates` 409 冲突，可能是另一个 OpenClaw Gateway 网关、脚本或外部轮询器正在使用同一令牌。
- 默认情况下，长轮询看门狗会在 120 秒内没有完成的 `getUpdates` 存活信号后触发重启。仅当你的部署在长时间运行工作期间仍看到误判的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。该值以毫秒为单位，允许范围为 `30000` 到 `600000`；支持按账号覆盖。
- Telegram Bot API 不支持已读回执（`sendReadReceipts` 不适用）。
## 功能参考
<AccordionGroup>
<Accordion title="实时流式预览（消息编辑）">
<Accordion title="实时流预览（消息编辑）">
OpenClaw 可以实时流式传输部分回复：
- 直接聊天：预览消息 + `editMessageText`
@ -284,12 +284,12 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
要求：
- `channels.telegram.streaming` 是 `off | partial | block | progress`（默认：`partial`）
- `progress` 在 Telegram 上映射为 `partial`（兼容跨渠道命名）
- `streaming.preview.toolProgress` 控制工具/进度更新是否复用同一条已编辑的预览消息（默认：预览流式传输激活时为 `true`）
- 会检测旧版 `channels.telegram.streamMode` 和布尔型 `streaming` 值；运行 `openclaw doctor --fix` 可将它们迁移到 `channels.telegram.streaming.mode`
- `channels.telegram.streaming` 为 `off | partial | block | progress`（默认：`partial`）
- 在 Telegram 上，`progress` 会映射到 `partial`（兼容跨渠道命名）
- `streaming.preview.toolProgress` 控制工具/进度更新是否复用同一条已编辑预览消息（默认：预览流式传输启用时为 `true`）
- 会检测旧版 `channels.telegram.streamMode` 和布尔值 `streaming` 值；运行 `openclaw doctor --fix` 可将它们迁移到 `channels.telegram.streaming.mode`
工具进度预览更新是在工具运行时显示的简短“正在工作...”行，例如命令执行、文件读取、规划更新或补丁摘要。Telegram 默认保持启用这些内容，以匹配 `v2026.4.22` 及之后发布的 OpenClaw 行为。若要保留答案文本的已编辑预览，但隐藏工具进度行，请设置：
工具进度预览更新是在工具运行时显示的短 “Working...” 行，例如命令执行、文件读取、计划更新或补丁摘要。Telegram 默认保持这些更新启用，以匹配 `v2026.4.22` 及之后版本发布的 OpenClaw 行为。若要保留用于答案文本的编辑预览，但隐藏工具进度行，请设置：
```json
{
@ -306,25 +306,25 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
Use `streaming.mode: "off"` 仅在你想要只交付最终答复时使用：Telegram 预览编辑会被禁用，通用工具/进度闲聊会被抑制，而不是作为独立的 “Working...” 消息发送。审批提示、媒体载荷和错误仍会通过正常的最终交付路径发送。仅当你想保留答案预览编辑，同时隐藏工具进度状态行时，使用 `streaming.preview.toolProgress: false`。
仅当你想要仅最终结果交付时才使用 `streaming.mode: "off"`：Telegram 预览编辑会被禁用，通用工具/进度提示会被抑制，而不是作为独立的 “Working...” 消息发送。审批提示、媒体载荷和错误仍会通过正常的最终交付路径路由。仅当你想保留答案预览编辑，同时隐藏工具进度状态行时，使用 `streaming.preview.toolProgress: false`。
对于纯文本回复：
- 简短的私信/群组/话题预览：OpenClaw 会保留同一条预览消息，并在原位置执行最终编辑
- 超过约一分钟的预览：OpenClaw 会将完成后的回复作为新的最终消息发送，然后清理预览，因此 Telegram 的可见时间戳会反映完成时间，而不是预览创建时间
- 简短私信/群组/话题预览：OpenClaw 会保留同一条预览消息，并在原位置执行最终编辑
- 超过约一分钟的预览：OpenClaw 会将完成的回复作为新的最终消息发送，然后清理预览，因此 Telegram 的可见时间戳会反映完成时间，而不是预览创建时间
对于复杂回复（例如媒体载荷），OpenClaw 会回退到正常的最终交付，然后清理预览消息。
对于复杂回复（例如媒体载荷），OpenClaw 会回退到正常最终交付，然后清理预览消息。
预览流式传输独立于分块流式传输。当为 Telegram 显式启用分块流式传输时，OpenClaw 会跳过预览流，以避免重复流式传输。
预览流式传输独立于分块流式传输。当为 Telegram 明确启用分块流式传输时，OpenClaw 会跳过预览流，避免双重流式传输。
仅限 Telegram 的推理流：
- `/reasoning stream` 会在生成过程中将推理发送到实时预览
- `/reasoning stream` 会在生成期间将推理发送到实时预览
- 最终答案发送时不包含推理文本
</Accordion>
<Accordion title="格式化和 HTML 回退">
<Accordion title="格式化与 HTML 回退">
出站文本使用 Telegram `parse_mode: "HTML"`。
- 类 Markdown 文本会渲染为 Telegram 安全的 HTML。
@ -342,7 +342,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `commands.native: "auto"` 会为 Telegram 启用原生命令
添加自定义命令菜单条目：
添加自定义命令菜单项：
```json5
{
@ -359,24 +359,24 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
规则：
- 名称会被规范化（去掉前导 `/`，转换为小写）
- 名称会被规范化（去除开头的 `/`，转换为小写）
- 有效模式：`a-z`、`0-9`、`_`，长度 `1..32`
- 自定义命令不能覆盖原生命令
- 冲突/重复项会被跳过并记录日志
注意：
说明：
- 自定义命令只是菜单条目；它们不会自动实现行为
- 即使未显示在 Telegram 菜单中，插件/Skills 命令在输入时仍可能工作
- 自定义命令只是菜单项；它们不会自动实现行为
- 插件/Skills 命令即使未显示在 Telegram 菜单中，输入时仍然可以工作
如果禁用原生命令，内置命令会被移除。自定义/插件命令在配置后仍可注册。
如果禁用原生命令，内置命令会被移除。自定义/插件命令在已配置的情况下仍可注册。
常见设置失败：
- `setMyCommands failed` 搭配 `BOT_COMMANDS_TOO_MUCH` 表示 Telegram 菜单在裁剪后仍然溢出；减少插件/Skills/自定义命令，或禁用 `channels.telegram.commands.native`。
- 当直接使用 Bot API curl 命令正常，但 `deleteWebhook`、`deleteMyCommands` 或 `setMyCommands` 失败并返回 `404: Not Found` 时，可能表示 `channels.telegram.apiRoot` 被设置成了完整的 `/bot<TOKEN>` 端点。`apiRoot` 必须仅为 Bot API 根路径，并且 `openclaw doctor --fix` 会移除意外尾随的 `/bot<TOKEN>`。
- `getMe returned 401` 表示 Telegram 拒绝了配置的 bot token。使用当前 BotFather token 更新 `botToken`、`tokenFile` 或 `TELEGRAM_BOT_TOKEN`；OpenClaw 会在轮询前停止，因此这不会被报告为 webhook 清理失败。
- `setMyCommands failed` 搭配网络/获取错误通常表示到 `api.telegram.org` 的出站 DNS/HTTPS 被阻止。
- `setMyCommands failed` 带有 `BOT_COMMANDS_TOO_MUCH` 表示 Telegram 菜单在裁剪后仍然溢出；减少插件/Skills/自定义命令，或禁用 `channels.telegram.commands.native`。
- 当直接 Bot API curl 命令可用，但 `deleteWebhook`、`deleteMyCommands` 或 `setMyCommands` 失败并显示 `404: Not Found` 时，可能表示 `channels.telegram.apiRoot` 被设置为完整的 `/bot<TOKEN>` 端点。`apiRoot` 必须只是 Bot API 根地址，`openclaw doctor --fix` 会移除意外尾随的 `/bot<TOKEN>`。
- `getMe returned 401` 表示 Telegram 拒绝了已配置的机器人令牌。用当前 BotFather 令牌更新 `botToken`、`tokenFile` 或 `TELEGRAM_BOT_TOKEN`；OpenClaw 会在轮询前停止，因此这不会被报告为 webhook 清理失败。
- `setMyCommands failed` 带有网络/fetch 错误通常表示到 `api.telegram.org` 的出站 DNS/HTTPS 被阻止。
### 设备配对命令（`device-pair` 插件）
@ -390,9 +390,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- 只有一个待处理请求时使用 `/pair approve`
- `/pair approve latest` 用于最近的请求
设置代码携带一个短期有效的 bootstrap token。内置 bootstrap 移交会将主节点 token 保持在 `scopes: []`；任何被移交的操作员 token 都会被限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write` 范围内。Bootstrap 作用域检查带有角色前缀，因此该操作员 allowlist 只满足操作员请求；非操作员角色仍需要其自身角色前缀下的作用域。
设置代码携带一个短期有效的引导令牌。内置引导移交会将主节点令牌保持在 `scopes: []`；任何被移交的操作员令牌仍限制在 `operator.approvals`、`operator.read`、`operator.talk.secrets` 和 `operator.write`。引导作用域检查带有角色前缀，因此该操作员允许列表只满足操作员请求；非操作员角色仍需要位于其自身角色前缀下的作用域。
如果设备使用已更改的认证详情（例如角色/作用域/公钥）重试，先前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。
如果设备使用变更后的认证详情重试（例如角色/作用域/公钥），先前的待处理请求会被取代，新请求会使用不同的 `requestId`。批准前请重新运行 `/pair pending`。
更多详情：[配对](/zh-CN/channels/pairing#pair-via-telegram-recommended-for-ios)。
@ -439,9 +439,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `all`
- `allowlist`（默认）
旧版 `capabilities: ["inlineButtons"]` 会映射到 `inlineButtons: "all"`。
旧版 `capabilities: ["inlineButtons"]` 会映射为 `inlineButtons: "all"`。
消息动作示例：
消息操作示例：
```json5
{
@ -464,8 +464,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
</Accordion>
<Accordion title="面向智能体和自动化的 Telegram 消息动作">
Telegram 工具动作包括：
<Accordion title="用于智能体和自动化的 Telegram 消息操作">
Telegram 工具操作包括：
- `sendMessage`（`to`、`content`、可选 `mediaUrl`、`replyToMessageId`、`messageThreadId`）
- `react`（`chatId`、`messageId`、`emoji`）
@ -473,7 +473,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `editMessage`（`chatId`、`messageId`、`content`）
- `createForumTopic`（`chatId`、`name`、可选 `iconColor`、`iconCustomEmojiId`）
渠道消息动作暴露符合人体工程学的别名（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。
渠道消息操作暴露符合人体工学的别名（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。
门控控制：
@ -482,10 +482,10 @@ 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 重新解析。
移除 Reaction 的语义：[/tools/reactions](/zh-CN/tools/reactions)
移除回应的语义：[/tools/reactions](/zh-CN/tools/reactions)
</Accordion>
@ -493,7 +493,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
Telegram 支持在生成输出中使用显式回复线程标签：
- `[[reply_to_current]]` 回复触发消息
- `[[reply_to:<id>]]` 回复特定的 Telegram 消息 ID
- `[[reply_to:<id>]]` 回复指定的 Telegram 消息 ID
`channels.telegram.replyToMode` 控制处理方式：
@ -501,29 +501,29 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `first`
- `all`
启用回复线程且原始 Telegram 文本或说明文字可用时，OpenClaw 会自动包含原生 Telegram 引用摘录。Telegram 将原生引用文本限制为 1024 个 UTF-16 码元，因此更长的消息会从开头开始引用；如果 Telegram 拒绝该引用，则回退为普通回复。
当启用回复线程，并且原始 Telegram 文本或说明文字可用时，OpenClaw 会自动包含原生 Telegram 引用摘录。Telegram 将原生引用文本限制为 1024 个 UTF-16 码元，因此较长消息会从开头引用；如果 Telegram 拒绝该引用，则回退为普通回复。
注意：`off` 会禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍会被遵守。
注意：`off` 会禁用隐式回复线程。显式 `[[reply_to_*]]` 标签仍会被遵循。
</Accordion>
<Accordion title="论坛话题和线程行为">
论坛超级群组：
- 话题会话键会追加 `:topic:<threadId>`
- 回复和正在输入状态会以话题线程为目标
- 话题会话键追加 `:topic:<threadId>`
- 回复和输入状态会定位到话题线程
- 话题配置路径：
`channels.telegram.groups.<chatId>.topics.<threadId>`
常规话题（`threadId=1`）特殊情况：
通用话题（`threadId=1`）特殊情况：
- 消息发送会省略 `message_thread_id`（Telegram 会拒绝 `sendMessage(...thread_id=1)`）
- 正在输入动作仍会包含 `message_thread_id`
- 输入状态操作仍包含 `message_thread_id`
话题继承：话题条目会继承群组设置，除非被覆盖（`requireMention`、`allowFrom`、`skills`、`systemPrompt`、`enabled`、`groupPolicy`）。
`agentId` 仅限话题使用，不会从群组默认值继承。
`agentId` 仅适用于话题，不会从群组默认值继承。
**按话题进行智能体路由**：每个话题都可以通过在话题配置中设置 `agentId` 路由到不同的智能体。这会让每个话题拥有自己隔离的工作区、记忆和会话。示例：
**按话题的智能体路由**：每个话题都可以通过在话题配置中设置 `agentId` 路由到不同智能体。这会让每个话题拥有自己隔离的工作区、记忆和会话。示例：
```json5
{
@ -543,26 +543,28 @@ 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"`，并使用类似 `-1001234567890:topic:42` 的话题限定 ID）固定 ACP harness 会话。目前作用域限定为群组/超级群组中的论坛话题。参见 [ACP 智能体](/zh-CN/tools/acp-agents)。
**持久 ACP 话题绑定**：论坛话题可以通过顶层类型化 ACP 绑定（`bindings[]`，其中 `type: "acp"`、`match.channel: "telegram"`、`peer.kind: "group"`，以及类似 `-1001234567890:topic:42` 的话题限定 ID）固定 ACP harness 会话。目前作用域限定为群组/超级群组中的论坛话题。参见 [ACP 智能体](/zh-CN/tools/acp-agents)。
**从聊天生成线程绑定的 ACP**：`/acp spawn <agent> --thread here|auto` 会将当前话题绑定到新的 ACP 会话；后续消息会直接路由到该处。OpenClaw 会在话题内固定生成确认消息。需要保持启用 `channels.telegram.threadBindings.spawnSessions`（默认：`true`）。
**从聊天生成线程绑定的 ACP**：`/acp spawn <agent> --thread here|auto` 会将当前话题绑定到新的 ACP 会话；后续消息会直接路由到那里。OpenClaw 会在话题内固定生成确认。要求 `channels.telegram.threadBindings.spawnSessions` 保持启用（默认：`true`）。
模板上下文会暴露 `MessageThreadId` 和 `IsForum`。带有 `message_thread_id` 的私信聊天默认会保留私信路由，并在扁平会话上保留回复元数据；只有在配置了 `threadReplies: "inbound"`、`threadReplies: "always"`、`requireTopic: true` 或匹配的话题配置时，它们才会使用线程感知会话键。使用顶层 `channels.telegram.dm.threadReplies` 设置账号默认值，或使用 `direct.<chatId>.threadReplies` 为单个私信设置。
模板上下文暴露 `MessageThreadId` 和 `IsForum`。带有 `message_thread_id` 的私信聊天默认保留私信路由和扁平会话上的回复元数据；只有在配置了 `threadReplies: "inbound"`、`threadReplies: "always"`、`requireTopic: true` 或匹配的话题配置时，它们才会使用线程感知会话键。使用顶层 `channels.telegram.dm.threadReplies` 作为账号默认值，或使用 `direct.<chatId>.threadReplies` 配置单个私信。
</Accordion>
<Accordion title="音频、视频和贴纸">
### 音频消息
Telegram 会区分语音消息和音频文件。
Telegram 区分语音便条和音频文件。
- 默认：音频文件行为
- 在智能体回复中使用标签 `[[audio_as_voice]]` 强制作为语音消息发送
- 入站语音消息转录会在智能体上下文中被框定为机器生成的、不受信任的文本；提及检测仍使用原始转录，因此带提及门控的语音消息会继续工作。
- 在智能体回复中使用标签 `[[audio_as_voice]]` 强制作为语音便条发送
- 入站语音便条转写会在智能体上下文中被框定为机器生成的、
不可信文本；提及检测仍使用原始
转写，因此受提及门控的语音消息会继续工作。
消息动作示例：
消息操作示例：
```json5
{
@ -576,9 +578,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
### 视频消息
Telegram 会区分视频文件和视频消息。
Telegram 区分视频文件和视频便条。
消息动作示例：
消息操作示例：
```json5
{
@ -590,7 +592,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
视频消息不支持说明文字；提供的消息文本会单独发送。
视频便条不支持说明文字；提供的消息文本会单独发送。
### 贴纸
@ -612,9 +614,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `~/.openclaw/telegram/sticker-cache.json`
贴纸会被描述一次（在可能的情况下），并缓存以减少重复的视觉调用。
贴纸会被描述一次（如果可能）并缓存，以减少重复的视觉调用。
启用贴纸动作：
启用贴纸操作：
```json5
{
@ -639,7 +641,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
搜索缓存的贴纸：
搜索已缓存的贴纸：
```json5
{
@ -652,31 +654,31 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
</Accordion>
<Accordion title="回应通知">
Telegram 回应会作为 `message_reaction` 更新到达（与消息载荷分开）。
<Accordion title="Reaction 通知">
Telegram reaction 会作为 `message_reaction` 更新到达（与消息负载分开）。
启用后，OpenClaw 会将类似这样的系统事件加入队列：
启用后，OpenClaw 会将如下系统事件加入队列：
- `Telegram reaction added: 👍 by Alice (@alice) on msg 42`
配置：
- `channels.telegram.reactionNotifications`: `off | own | all`（默认：`own`）
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive`（默认：`minimal`）
- `channels.telegram.reactionNotifications`：`off | own | all`（默认：`own`）
- `channels.telegram.reactionLevel`：`off | ack | minimal | extensive`（默认：`minimal`）
注意事项：
- `own` 表示仅针对用户对机器人发送消息的回应（通过已发送消息缓存尽力而为）。
- 回应事件仍然遵守 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权发送者会被丢弃。
- Telegram 不会在回应更新中提供话题 ID。
- 非论坛群组路由到群聊会话
- 论坛群组路由到群组通用话题会话（`:topic:1`），而不是确切的原始话题
- `own` 表示仅用户对机器人发送消息的 reaction（通过已发送消息缓存尽力判断）。
- Reaction 事件仍遵守 Telegram 访问控制（`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`）；未授权发送者会被丢弃。
- Telegram 不会在 reaction 更新中提供话题 ID。
- 非论坛群组会路由到群聊会话
- 论坛群组会路由到群组通用话题会话（`:topic:1`），而不是确切的原始话题
用于轮询/webhook 的 `allowed_updates` 会自动包含 `message_reaction`。
</Accordion>
<Accordion title="确认回应">
<Accordion title="Ack reaction">
`ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认表情符号。
解析顺序：
@ -688,8 +690,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
注意事项：
- Telegram 需要 unicode 表情符号（例如 "👀"）。
- 使用 `""` 可为某个渠道或账号禁用该回应。
- Telegram 预期使用 unicode 表情符号（例如 "👀"）。
- 使用 `""` 可为某个渠道或账号禁用 reaction。
</Accordion>
@ -716,28 +718,28 @@ 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`）。
默认是长轮询。对于 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 密钥令牌和 JSON 正文，然后再向 Telegram 返回 `200`。
随后 OpenClaw 会通过与长轮询相同的按聊天/按话题机器人通道异步处理更新，因此较慢的智能体回合不会阻塞 Telegram 的投递 ACK。
Webhook 模式会先验证请求保护、Telegram secret token 和 JSON 正文，然后再向 Telegram 返回 `200`。
随后 OpenClaw 会通过与长轮询相同的按聊天/按话题机器人通道异步处理该更新，因此缓慢的智能体轮次不会阻塞 Telegram 的投递 ACK。
</Accordion>
<Accordion title="限制、重试和 CLI 目标">
- `channels.telegram.textChunkLimit` 默认值为 4000。
- `channels.telegram.chunkMode="newline"` 会在按长度拆分前优先选择段落边界（空行）。
- `channels.telegram.chunkMode="newline"` 会在按长度拆分前优先使用段落边界（空行）。
- `channels.telegram.mediaMaxMb`（默认 100）限制入站和出站 Telegram 媒体大小。
- `channels.telegram.timeoutSeconds` 覆盖 Telegram API 客户端超时（如果未设置，则使用 grammY 默认值）。长轮询机器人客户端会将低于 45 秒 `getUpdates` 请求保护的配置值钳制住，以免空闲轮询在 30 秒轮询窗口完成前被中止。
- `channels.telegram.pollingStallThresholdMs` 默认为 `120000`；仅在轮询卡滞重启出现误报时，才在 `30000` 到 `600000` 之间调节。
- `channels.telegram.timeoutSeconds` 会覆盖 Telegram API 客户端超时（未设置时，使用 grammY 默认值）。机器人客户端会将低于 60 秒出站文本/typing 请求保护的配置值钳制在该保护以下，避免 grammY 在 OpenClaw 的传输保护和回退运行前中止可见回复投递。长轮询仍使用 45 秒的 `getUpdates` 请求保护，因此空闲轮询不会被无限期放弃。
- `channels.telegram.pollingStallThresholdMs` 默认值为 `120000`；仅在误报轮询停滞重启时，在 `30000` 到 `600000` 之间调整。
- 群组上下文历史使用 `channels.telegram.historyLimit` 或 `messages.groupChat.historyLimit`（默认 50）；`0` 表示禁用。
- 回复/引用/转发的补充上下文目前按接收内容传递。
- Telegram 允许列表主要用于限制谁可以触发智能体，而不是完整的补充上下文脱敏边界。
- reply/quote/forward 补充上下文目前会按收到的内容传递。
- Telegram allowlist 主要限制谁可以触发智能体，而不是完整的补充上下文脱敏边界。
- 私信历史控制：
- `channels.telegram.dmHistoryLimit`
- `channels.telegram.dms["<user_id>"].historyLimit`
- `channels.telegram.retry` 配置适用于 Telegram 发送辅助函数（CLI/工具/操作），用于可恢复的出站 API 错误。入站最终回复投递也会对 Telegram 预连接失败使用有界的安全发送重试，但不会重试可能导致可见消息重复的、发送后语义不明确的网络信封。
- `channels.telegram.retry` 配置适用于 Telegram 发送辅助函数（CLI/工具/操作）的可恢复出站 API 错误。入站最终回复投递也会对 Telegram 预连接失败使用有界 safe-send 重试，但不会重试可能导致可见消息重复的模糊发送后网络信封。
CLI 发送目标可以是数字聊天 ID 或用户名：
@ -756,55 +758,55 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
--poll-duration-seconds 300 --poll-public
```
仅 Telegram 支持的投票标志：
仅 Telegram 可用的投票标志：
- `--poll-duration-seconds`（5-600）
- `--poll-anonymous`
- `--poll-public`
- 用于论坛话题的 `--thread-id`（或使用 `:topic:` 目标）
- `--thread-id` 用于论坛话题（或使用 `:topic:` 目标）
Telegram 发送还支持：
- 当 `channels.telegram.capabilities.inlineButtons` 允许时，使用带有 `buttons` 块的 `--presentation` 作为内联键盘
- 当 `channels.telegram.capabilities.inlineButtons` 允许时，`--presentation` 可配合 `buttons` 块用于内联键盘
- 当机器人可以在该聊天中置顶时，使用 `--pin` 或 `--delivery '{"pin":true}'` 请求置顶投递
- 使用 `--force-document` 将出站图片和 GIF 作为文档发送，而不是作为压缩照片或动画媒体上传
- `--force-document` 用于将出站图片和 GIF 作为文件发送，而不是压缩照片或 animated-media 上传
操作门控：
- `channels.telegram.actions.sendMessage=false` 会禁用出站 Telegram 消息，包括投票
- `channels.telegram.actions.poll=false` 会禁用 Telegram 投票创建，同时保留常规发送
- `channels.telegram.actions.poll=false` 会禁用 Telegram 投票创建，同时保留常规发送启用
</Accordion>
<Accordion title="Telegram 中的 exec 审批">
Telegram 支持在审批人私信中进行 exec 审批，也可以选择在原始聊天或话题中发布提示。审批人必须是数字 Telegram 用户 ID。
Telegram 支持在审批者私信中进行 exec 审批，并可选择在原始聊天或话题中发布提示。审批者必须是数字 Telegram 用户 ID。
配置路径：
- `channels.telegram.execApprovals.enabled`（当至少一个审批人可解析时自动启用）
- `channels.telegram.execApprovals.approvers`（回退到 `commands.ownerAllowFrom` 中的数字所有者 ID）
- `channels.telegram.execApprovals.target`: `dm`（默认）| `channel` | `both`
- `channels.telegram.execApprovals.enabled`（至少有一个可解析审批者时自动启用）
- `channels.telegram.execApprovals.approvers`（回退到 `commands.ownerAllowFrom` 中的数字 owner ID）
- `channels.telegram.execApprovals.target`：`dm`（默认）| `channel` | `both`
- `agentFilter`、`sessionFilter`
`channels.telegram.allowFrom`、`groupAllowFrom` 和 `defaultTo` 控制谁可以与机器人对话，以及机器人向哪里发送普通回复。它们不会让某人成为 exec 审批人。当尚不存在命令所有者时，首次获批的私信配对会引导初始化 `commands.ownerAllowFrom`，因此单所有者设置仍可正常工作，无需在 `execApprovals.approvers` 下重复 ID。
`channels.telegram.allowFrom`、`groupAllowFrom` 和 `defaultTo` 控制谁可以与机器人交互，以及机器人向哪里发送普通回复。它们不会让某人成为 exec 审批者。当尚不存在命令 owner 时，第一次获批的私信配对会引导生成 `commands.ownerAllowFrom`，因此单 owner 设置仍可工作，而无需在 `execApprovals.approvers` 下重复 ID。
渠道投递会在聊天中显示命令文本；仅在受信任的群组/话题中启用 `channel` 或 `both`。当提示落在论坛话题中时，OpenClaw 会为审批提示和后续消息保留该话题。exec 审批默认在 30 分钟后过期。
渠道投递会在聊天中显示命令文本；仅在可信群组/话题中启用 `channel` 或 `both`。当提示落在论坛话题中时，OpenClaw 会为审批提示和后续消息保留该话题。Exec 审批默认在 30 分钟后过期。
内联审批按钮还要求 `channels.telegram.capabilities.inlineButtons` 允许目标表面（`dm`、`group` 或 `all`）。以 `plugin:` 为前缀的审批 ID 会通过插件审批解析；其他 ID 会先通过 exec 审批解析。
内联审批按钮还需要 `channels.telegram.capabilities.inlineButtons` 允许目标表面（`dm`、`group` 或 `all`）。以 `plugin:` 为前缀的审批 ID 会通过插件审批解析；其他 ID 会先通过 exec 审批解析。
参见 [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 配置键相同）。
@ -829,53 +831,53 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
<AccordionGroup>
<Accordion title="机器人不响应未提及它的群组消息">
- 如果 `requireMention=false`，Telegram 隐私模式必须允许完全可见。
- BotFather：`/setprivacy` -> 禁用
- 如果 `requireMention=false`，Telegram 隐私模式必须允许完整可见性。
- BotFather：`/setprivacy` -> Disable
- 然后将机器人从群组移除并重新添加
- 当配置预期未提及的群组消息时，`openclaw channels status` 会发出警告。
- `openclaw channels status --probe` 可以检查显式的数字群组 ID；通配符 `"*"` 无法进行成员探测。
- `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` 表示原生命令菜单条目过多；减少插件/skill/自定义命令，或禁用原生命令菜单
- 启动时的 `deleteMyCommands` / `setMyCommands` 调用是有界的，并会在请求超时时通过 Telegram 的传输回退重试一次。持续的网络/fetch 错误通常表示到 `api.telegram.org` 的 DNS/HTTPS 可达性问题
- 即使群组策略为 `open`，命令授权仍会生效
- `setMyCommands failed` 携带 `BOT_COMMANDS_TOO_MUCH` 表示原生命令菜单条目过多；减少插件/skill/自定义命令，或禁用原生菜单
- `deleteMyCommands` / `setMyCommands` 启动调用和 `sendChatAction` typing 调用都有边界，并会在请求超时时通过 Telegram 的传输回退重试一次。持续的网络/fetch 错误通常表示到 `api.telegram.org` 的 DNS/HTTPS 可达性问题
</Accordion>
<Accordion title="启动报告未授权令牌">
<Accordion title="启动报告未授权 token">
- `getMe returned 401` 是针对已配置机器人令牌的 Telegram 身份验证失败。
- 在 BotFather 中重新复制或重新生成机器人令牌，然后更新默认账号的 `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts.<id>.botToken` 或 `TELEGRAM_BOT_TOKEN`。
- 启动期间的 `deleteWebhook 401 Unauthorized` 也是身份验证失败；将其视为“webhook 不存在”只会把同一个坏令牌失败推迟到后续 API 调用。
- 如果轮询启动期间 `deleteWebhook` 因短暂网络错误而失败，OpenClaw 会检查 `getWebhookInfo`；当 Telegram 报告空 webhook URL 时，轮询会继续，因为清理已经满足。
- `getMe returned 401` 是已配置机器人 token 的 Telegram 认证失败。
- 在 BotFather 中重新复制或重新生成机器人 token，然后更新默认账号的 `channels.telegram.botToken`、`channels.telegram.tokenFile`、`channels.telegram.accounts.<id>.botToken` 或 `TELEGRAM_BOT_TOKEN`。
- 启动期间的 `deleteWebhook 401 Unauthorized` 也是认证失败；将其视为“没有 webhook 存在”只会把相同的错误 token 失败推迟到后续 API 调用。
- 如果 `deleteWebhook` 在轮询启动期间因瞬时网络错误失败，OpenClaw 会检查 `getWebhookInfo`；当 Telegram 报告空 webhook URL 时，轮询会继续，因为清理已经满足。
</Accordion>
<Accordion title="轮询或网络不稳定">
- Node 22+ + 自定义 fetch/proxy 在 AbortSignal 类型不匹配时可能触发立即中止行为。
- 一些主机会先将 `api.telegram.org` 解析为 IPv6；损坏的 IPv6 出站连接可能导致 Telegram API 间歇性失败。
- Node 22+ + 自定义 fetch/proxy 可能会在 AbortSignal 类型不匹配时触发立即中止行为。
- 某些主机会先将 `api.telegram.org` 解析为 IPv6；损坏的 IPv6 出站连接可能导致间歇性 Telegram API 失败。
- 如果日志包含 `TypeError: fetch failed` 或 `Network request for 'getUpdates' failed!`，OpenClaw 现在会将这些错误作为可恢复的网络错误重试。
- 如果 Telegram 套接字按较短的固定周期回收，请检查 `channels.telegram.timeoutSeconds` 是否过低；长轮询机器人客户端会将配置值限制在 `getUpdates` 请求保护值以下，但旧版本在该值低于长轮询超时时，可能会在每次轮询时中止。
- 如果日志包含 `Polling stall detected`，OpenClaw 默认会在 120 秒内没有完成长轮询存活性检查后重启轮询并重建 Telegram 传输。
- 当正在运行的轮询账号在启动宽限期后尚未完成 `getUpdates`、正在运行的 webhook 账号在启动宽限期后尚未完成 `setWebhook`，或上一次成功的轮询传输活动已过期时，`openclaw channels status --probe` 和 `openclaw doctor` 会发出警告。
- 仅当长时间运行的 `getUpdates` 调用是健康的，但你的主机仍报告误报的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。持续停滞通常指向主机与 `api.telegram.org` 之间的代理、DNS、IPv6 或 TLS 出站问题。
- Telegram 的 Bot API 传输也遵循进程代理环境变量，包括 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 及其小写变体。`NO_PROXY` / `no_proxy` 仍可绕过 `api.telegram.org`。
- 如果服务环境通过 `OPENCLAW_PROXY_URL` 配置了 OpenClaw 托管代理，并且没有标准代理环境变量，Telegram 也会将该 URL 用于 Bot API 传输。
- 在直接出站/TLS 不稳定的 VPS 主机上，通过 `channels.telegram.proxy` 路由 Telegram API 调用：
- 如果 Telegram 套接字以较短的固定周期回收，请检查是否设置了过低的 `channels.telegram.timeoutSeconds`；bot 客户端会将配置值限制在出站请求和 `getUpdates` 请求保护阈值以下，但旧版本在该值低于这些保护阈值时，可能会在每次轮询或回复时中止。
- 如果日志包含 `Polling stall detected`，OpenClaw 默认会在 120 秒内没有完成长轮询活性检查后重启轮询并重建 Telegram 传输。
- 当正在运行的轮询账号在启动宽限期后尚未完成 `getUpdates`、正在运行的 webhook 账号在启动宽限期后尚未完成 `setWebhook`，或最近一次成功的轮询传输活动已经过期时，`openclaw channels status --probe` 和 `openclaw doctor` 会发出警告。
- 只有在长时间运行的 `getUpdates` 调用正常，但你的主机仍报告误判的轮询停滞重启时，才增加 `channels.telegram.pollingStallThresholdMs`。持续停滞通常指向主机与 `api.telegram.org` 之间的代理、DNS、IPv6 或 TLS 出站问题。
- Telegram 还会在 Bot API 传输中遵循进程代理环境变量，包括 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 及其小写变体。`NO_PROXY` / `no_proxy` 仍然可以绕过 `api.telegram.org`。
- 如果在服务环境中通过 `OPENCLAW_PROXY_URL` 配置了 OpenClaw 托管代理，并且不存在标准代理环境变量，Telegram 也会将该 URL 用于 Bot API 传输。
- 在直连出站/TLS 不稳定的 VPS 主机上，通过 `channels.telegram.proxy` 路由 Telegram API 调用：
```yaml
channels:
@ -884,7 +886,7 @@ channels:
```
- Node 22+ 默认使用 `autoSelectFamily=true`（WSL2 除外）。Telegram DNS 结果顺序依次遵循 `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`、`channels.telegram.network.dnsResultOrder`，然后是进程默认值，例如 `NODE_OPTIONS=--dns-result-order=ipv4first`；如果都不适用，Node 22+ 会回退到 `ipv4first`。
- 如果你的主机是 WSL2，或明确在仅 IPv4 行为下工作得更好，请强制选择地址族：
- 如果你的主机是 WSL2，或明确更适合仅 IPv4 行为，请强制选择地址族：
```yaml
channels:
@ -893,7 +895,7 @@ channels:
autoSelectFamily: false
```
- RFC 2544 基准测试范围的应答（`198.18.0.0/15`）默认已允许用于 Telegram 媒体下载。如果受信任的 fake-IP 或透明代理在媒体下载期间将 `api.telegram.org` 重写到其他私有/内部/特殊用途地址，你可以选择启用仅限 Telegram 的绕过：
- 默认情况下，Telegram 媒体下载已允许 RFC 2544 基准测试范围地址（`198.18.0.0/15`）。如果受信任的 fake-IP 或透明代理在媒体下载期间将 `api.telegram.org` 重写为其他私有/内部/特殊用途地址，你可以选择启用仅限 Telegram 的绕过：
```yaml
channels:
@ -902,22 +904,20 @@ channels:
dangerouslyAllowPrivateNetwork: true
```
- 同一项选择启用也可按账号配置在
- 同一选择性启用项也可按账号配置在
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`。
- 如果你的代理将 Telegram 媒体主机解析为 `198.18.x.x`，请先保持危险标志关闭。Telegram 媒体默认已允许 RFC 2544 基准测试范围。
<Warning>
`channels.telegram.network.dangerouslyAllowPrivateNetwork` 会削弱 Telegram
媒体 SSRF 防护。仅在受信任的、由操作员控制的代理
环境中使用它，例如 Clash、Mihomo 或 Surge fake-IP 路由，且这些环境会
合成 RFC 2544 基准测试范围之外的私有或特殊用途应答。对于普通公共互联网 Telegram 访问，请保持关闭。
媒体 SSRF 防护。仅在受信任、由运维人员控制的代理环境中使用它，例如 Clash、Mihomo 或 Surge fake-IP 路由，并且这些环境会合成 RFC 2544 基准测试范围以外的私有或特殊用途答案。对于普通公网 Telegram 访问，请保持关闭。
</Warning>
- 环境覆盖（临时）：
- `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
- `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
- `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
- 验证 DNS 应答：
- 验证 DNS 答案：
```bash
dig +short api.telegram.org A
@ -933,17 +933,17 @@ dig +short api.telegram.org AAAA
主要参考：[配置参考 - Telegram](/zh-CN/gateway/config-channels#telegram)。
<Accordion title="高信号 Telegram 字段">
<Accordion title="High-signal Telegram fields">
- 启动/认证：`enabled`、`botToken`、`tokenFile`、`accounts.*`（`tokenFile` 必须指向常规文件；符号链接会被拒绝）
- 启动/身份验证：`enabled`、`botToken`、`tokenFile`、`accounts.*`（`tokenFile` 必须指向常规文件；符号链接会被拒绝）
- 访问控制：`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups`、`groups.*.topics.*`、顶层 `bindings[]`（`type: "acp"`）
- 执行审批：`execApprovals`、`accounts.*.execApprovals`
- 命令/菜单：`commands.native`、`commands.nativeSkills`、`customCommands`
- 会话串/回复：`replyToMode`、`dm.threadReplies`、`direct.*.threadReplies`
- 线程/回复：`replyToMode`、`dm.threadReplies`、`direct.*.threadReplies`
- 流式传输：`streaming`（预览）、`streaming.preview.toolProgress`、`blockStreaming`
- 格式化/投递：`textChunkLimit`、`chunkMode`、`linkPreview`、`responsePrefix`
- 媒体/网络：`mediaMaxMb`、`timeoutSeconds`、`pollingStallThresholdMs`、`retry`、`network.autoSelectFamily`、`network.dangerouslyAllowPrivateNetwork`、`proxy`
- 自定义 API 根地址：`apiRoot`（仅限 Bot API 根地址；不要包含 `/bot<TOKEN>`）
- 自定义 API 根地址：`apiRoot`（仅 Bot API 根地址；不要包含 `/bot<TOKEN>`）
- webhook：`webhookUrl`、`webhookSecret`、`webhookPath`、`webhookHost`
- 操作/能力：`capabilities.inlineButtons`、`actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
- 表情回应：`reactionNotifications`、`reactionLevel`
@ -953,28 +953,28 @@ 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">
<Card title="Pairing" icon="link" href="/zh-CN/channels/pairing">
将 Telegram 用户与 Gateway 网关配对。
</Card>
<Card title="群组" icon="users" href="/zh-CN/channels/groups">
群组和话题的允许列表行为。
<Card title="Groups" icon="users" href="/zh-CN/channels/groups">
群组和话题 allowlist 行为。
</Card>
<Card title="渠道路由" icon="route" href="/zh-CN/channels/channel-routing">
<Card title="Channel routing" icon="route" href="/zh-CN/channels/channel-routing">
将入站消息路由到智能体。
</Card>
<Card title="安全" icon="shield" href="/zh-CN/gateway/security">
<Card title="Security" icon="shield" href="/zh-CN/gateway/security">
威胁模型与加固。
</Card>
<Card title="多智能体路由" icon="sitemap" href="/zh-CN/concepts/multi-agent">
<Card title="Multi-agent routing" icon="sitemap" href="/zh-CN/concepts/multi-agent">
将群组和话题映射到智能体。
</Card>
<Card title="故障排除" icon="wrench" href="/zh-CN/channels/troubleshooting">
<Card title="Troubleshooting" icon="wrench" href="/zh-CN/channels/troubleshooting">
跨渠道诊断。
</Card>
</CardGroup>

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

@ -1,35 +1,38 @@
---
read_when:
- 你需要精确的字段级配置语义或默认值
- 你需要精确到字段级别的配置语义或默认值
- 你正在验证渠道、模型、Gateway 网关或工具配置块
summary: Gateway 网关配置参考，涵盖 OpenClaw 核心键名、默认值，并链接到专用子系统参考
summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键名、默认值，以及指向专用子系统参考的链接
title: 配置参考
x-i18n:
generated_at: "2026-05-02T09:29:26Z"
generated_at: "2026-05-02T10:12:03Z"
model: gpt-5.5
provider: openai
source_hash: fa8aeec6143ae70905e75f1034005c97c3a72fcaa34f14f61294dece561f4ce6
source_hash: 615dda0385c6a4efb9bfcc010de221b2d799dab73e612f6e4681fd14d45f15d0
source_path: gateway/configuration-reference.md
workflow: 16
---
OpenClaw 的核心配置参考，适用于 `~/.openclaw/openclaw.json`。如需面向任务的概览，请参阅[配置](/zh-CN/gateway/configuration)。
`~/.openclaw/openclaw.json` 的核心配置参考。若需面向任务的概览，请参阅[配置](/zh-CN/gateway/configuration)。
涵盖主要的 OpenClaw 配置表面，并在某个子系统拥有自己的更深入参考时链接过去。由渠道和插件拥有的命令目录，以及深层记忆/QMD 调节项位于各自页面，而不是此页面。
涵盖主要的 OpenClaw 配置表面；当某个子系统有自己的更深入参考时，会链接到对应页面。渠道和插件拥有的命令目录，以及深层记忆/QMD 调节项位于各自页面，而不是本页。
代码事实：
- `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置/插件/渠道元数据
- `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema；在可用时会合并内置/插件/渠道元数据
- `config.schema.lookup` 会返回一个按路径限定的 schema 节点，供下钻工具使用
- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面验证配置文档基线哈希
智能体查找路径：编辑前，使用 `gateway` 工具操作 `config.schema.lookup` 获取准确的字段级文档和约束。使用[配置](/zh-CN/gateway/configuration)获取面向任务的指导，使用本页查看更广泛的字段映射、默认值，以及指向子系统参考的链接。
智能体查找路径：编辑前，使用 `gateway` 工具操作 `config.schema.lookup`
获取精确的字段级文档和约束。使用
[配置](/zh-CN/gateway/configuration) 获取面向任务的指导，并使用本页
查看更宽泛的字段图、默认值和子系统参考链接。
专用深层参考：
- [记忆配置参考](/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)：适用于当前内置 + 内置捆绑命令目录
- 拥有对应渠道专属命令表面的渠道/插件页面
- [记忆配置参考](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及 `plugins.entries.memory-core.config.dreaming` 下的 Dreaming 配置
- [斜杠命令](/zh-CN/tools/slash-commands)，适用于当前内置 + 捆绑命令目录
- 拥有渠道专属命令表面的渠道/插件页面
配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的，省略时 OpenClaw 会使用安全默认值。
@ -37,27 +40,35 @@ OpenClaw 的核心配置参考，适用于 `~/.openclaw/openclaw.json`。如需
## 渠道
每个渠道的配置键已移至专用页面，请参阅[配置 - 渠道](/zh-CN/gateway/config-channels)，了解 `channels.*`，包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 以及其他内置渠道（凭证、访问控制、多账号、提及门控）。
每个渠道的配置键已移至专用页面，请参阅
[配置 — 渠道](/zh-CN/gateway/config-channels)，其中涵盖 `channels.*`，
包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 以及其他
内置渠道（认证、访问控制、多账号、提及门控）。
## 智能体默认值、多智能体、会话和消息
已移至专用页面，请参阅[配置 - 智能体](/zh-CN/gateway/config-agents)，了解：
已移至专用页面，请参阅
[配置 — 智能体](/zh-CN/gateway/config-agents)，其中涵盖：
- `agents.defaults.*`（工作区、模型、思考、Heartbeat、记忆、媒体、Skills、沙箱）
- `multiAgent.*`（多智能体路由和绑定）
- `session.*`（会话生命周期、压缩、裁剪）
- `session.*`（会话生命周期、压缩、修剪）
- `messages.*`（消息投递、TTS、Markdown 渲染）
- `talk.*`（Talk 模式）
- `talk.speechLocale`：可选的 BCP 47 区域设置 ID，用于 iOS/macOS 上的 Talk 语音识别
- `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录稿前保留平台默认暂停窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`）
- `talk.speechLocale`：用于 iOS/macOS 上 Talk 语音识别的可选 BCP 47 locale id
- `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录文本前保留平台默认暂停窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`）
## 工具和自定义提供商
工具策略、实验性开关、由提供商支持的工具配置，以及自定义提供商 / 基础 URL 设置已移至专用页面，请参阅[配置 - 工具和自定义提供商](/zh-CN/gateway/config-tools)。
工具策略、实验性开关、由提供商支持的工具配置，以及自定义
提供商 / base-URL 设置已移至专用页面，请参阅
[配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools)。
## Models
提供商定义、模型允许列表和自定义提供商设置位于[配置 - 工具和自定义提供商](/zh-CN/gateway/config-tools#custom-providers-and-base-urls)。`models` 根节点还拥有全局模型目录行为。
提供商定义、模型允许列表和自定义提供商设置位于
[配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools#custom-providers-and-base-urls)。
`models` 根节点还拥有全局模型目录行为。
```json5
{
@ -69,12 +80,16 @@ OpenClaw 的核心配置参考，适用于 `~/.openclaw/openclaw.json`。如需
```
- `models.mode`：提供商目录行为（`merge` 或 `replace`）。
- `models.providers`：按提供商 ID 键控的自定义提供商映射。
- `models.pricing.enabled`：控制后台价格引导流程。当为 `false` 时，Gateway 网关启动会跳过 OpenRouter 和 LiteLLM 价格目录获取；已配置的 `models.providers.*.models[].cost` 值仍可用于本地成本估算。
- `models.providers`：以提供商 id 为键的自定义提供商映射。
- `models.pricing.enabled`：控制后台 pricing bootstrap，它会在 sidecar 和渠道到达 Gateway 网关就绪路径后启动。当为 `false` 时，
Gateway 网关会跳过 OpenRouter 和 LiteLLM 定价目录获取；已配置的
`models.providers.*.models[].cost` 值仍可用于本地成本估算。
## MCP
OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式 Pi 和其他运行时适配器使用。`openclaw mcp list`、`show`、`set` 和 `unset` 命令会管理此块，并且在配置编辑期间不会连接到目标服务器。
OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式 Pi
和其他运行时适配器使用。`openclaw mcp list`、`show`、`set` 和 `unset`
命令会管理此块，且在配置编辑期间不会连接到目标服务器。
```json5
{
@ -98,11 +113,18 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式
}
```
- `mcp.servers`：具名 stdio 或远程 MCP 服务器定义，供公开已配置 MCP 工具的运行时使用。远程条目使用 `transport: "streamable-http"` 或 `transport: "sse"`；`type: "http"` 是 CLI 原生别名，`openclaw mcp set` 和 `openclaw doctor --fix` 会将其规范化为标准 `transport` 字段。
- `mcp.sessionIdleTtlMs`：会话级内置 MCP 运行时的空闲 TTL。一次性嵌入式运行会请求运行结束清理；此 TTL 是长生命周期会话和未来调用方的兜底机制。
- `mcp.*` 下的更改会通过释放缓存的会话 MCP 运行时来热应用。下一次工具发现/使用会基于新配置重新创建它们，因此已移除的 `mcp.servers` 条目会立即被回收，而不是等待空闲 TTL。
- `mcp.servers`：具名 stdio 或远程 MCP 服务器定义，供暴露已配置 MCP 工具的运行时使用。
远程条目使用 `transport: "streamable-http"` 或 `transport: "sse"`；
`type: "http"` 是 CLI 原生别名，`openclaw mcp set` 和
`openclaw doctor --fix` 会将其规范化为标准 `transport` 字段。
- `mcp.sessionIdleTtlMs`：会话范围内内置 MCP 运行时的空闲 TTL。
一次性嵌入运行会请求运行结束清理；此 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 后端](/zh-CN/gateway/cli-backends#bundle-mcp-overlays)了解运行时行为。
## Skills
@ -129,12 +151,13 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式
}
```
- `allowBundled`：仅适用于内置 Skills 的可选允许列表（不影响托管/工作区 Skills）。
- `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，即使它是内置/已安装的。
- `entries.<skillKey>.apiKey`：为声明主环境变量的 Skills 提供的便捷项（明文字符串或 SecretRef 对象）。
- `install.nodeManager`：用于 `metadata.openclaw.install`
规格的 node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。
- `entries.<skillKey>.enabled: false`：即使 Skill 为内置/已安装，也会禁用它。
- `entries.<skillKey>.apiKey`：供声明主环境变量的 Skills 使用的便捷项（明文字符串或 SecretRef 对象）。
---
@ -164,29 +187,29 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式
- 从 `~/.openclaw/extensions`、`<workspace>/.openclaw/extensions` 以及 `plugins.load.paths` 加载。
- 设备发现接受原生 OpenClaw 插件，以及兼容的 Codex 捆绑包和 Claude 捆绑包，包括无 manifest 的 Claude 默认布局捆绑包。
- **配置更改需要重启 Gateway 网关。**
- **配置变更需要重启 Gateway 网关。**
- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。
- `plugins.entries.<id>.apiKey`：插件级 API key 便捷字段（当插件支持时）。
- `plugins.entries.<id>.env`：插件作用域的环境变量映射。
- `plugins.entries.<id>.hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略来自旧版 `before_agent_start` 的提示词变更字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子，以及受支持的捆绑包所提供的钩子目录。
- `plugins.entries.<id>.hooks.allowConversationAccess`：为 `true` 时，可信的非内置插件可以从类型化钩子中读取原始对话内容，例如 `llm_input`、`llm_output`、`before_agent_finalize` 和 `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 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 天）。
- `plugins.entries.<id>.apiKey`：插件级 API key 便捷字段（在插件支持时）。
- `plugins.entries.<id>.env`：插件范围的环境变量映射。
- `plugins.entries.<id>.hooks.allowPromptInjection`：当为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会改变提示的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子以及受支持的捆绑包提供的钩子目录。
- `plugins.entries.<id>.hooks.allowConversationAccess`：当为 `true` 时，受信任的非内置插件可以从类型化钩子读取原始对话内容，例如 `llm_input`、`llm_output`、`before_agent_finalize` 和 `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 搜索）设置。
- `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 * * *"`）。
- `model`：可选的 Dream Diary 子智能体模型覆盖。需要 `plugins.entries.memory-core.subagent.allowModelOverride: true`；与 `allowedModels` 配合使用以限制目标。模型不可用错误会使用会话默认模型重试一次；信任或允许列表失败不会静默回退。
- `plugins.entries.memory-core.config.dreaming`：记忆 Dreaming 设置。阶段和阈值请参阅 [Dreaming](/zh-CN/concepts/dreaming)。
- `enabled`：Dreaming 总开关（默认 `false`）。
- `frequency`：每次完整 Dreaming 扫描的 cron 节奏（默认为 `"0 3 * * *"`）。
- `model`：可选的 Dream Diary 子智能体模型覆盖。需要 `plugins.entries.memory-core.subagent.allowModelOverride: true`；与 `allowedModels` 搭配使用以限制目标。模型不可用错误会使用会话默认模型重试一次；信任或允许列表失败不会静默回退。
- 阶段策略和阈值属于实现细节（不是面向用户的配置键）。
- 完整记忆配置位于[记忆配置参考](/zh-CN/reference/memory-config)：
- `agents.defaults.memorySearch.*`
@ -194,9 +217,9 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式
- `memory.citations`
- `memory.qmd.*`
- `plugins.entries.memory-core.config.dreaming`
- 已启用的 Claude 捆绑插件也可以从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将这些作为经过清理的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。
- `plugins.slots.memory`：选择活动记忆插件 ID，或选择 `"none"` 以禁用记忆插件。
- `plugins.slots.contextEngine`：选择活动上下文引擎插件 ID；默认为 `"legacy"`，除非你安装并选择了另一个引擎。
- 已启用的 Claude 捆绑插件也可以从 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为已清理的智能体设置应用，而不是作为原始 OpenClaw 配置补丁。
- `plugins.slots.memory`：选择活动记忆插件 id，或选择 `"none"` 以禁用记忆插件。
- `plugins.slots.contextEngine`：选择活动上下文引擎插件 id；除非你安装并选择了其他引擎，否则默认为 `"legacy"`。
请参阅[插件](/zh-CN/tools/plugin)。
@ -249,24 +272,24 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式
```
- `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` 设置显式例外。
- 远程配置是仅附加模式（禁用启动/停止/重置）。
- `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。当你希望 OpenClaw 发现 `/json/version` 时使用 HTTP(S)；当你的提供商提供直接的 DevTools WebSocket URL 时使用 WS(S)。
- `remoteCdpTimeoutMs` 和 `remoteCdpHandshakeTimeoutMs` 适用于远程以及 `attachOnly` CDP 可达性和标签页打开请求。托管的 loopback 配置会保留本地 CDP 默认值。
- 如果外部托管的 CDP 服务可通过 loopback 访问，请为该配置设置 `attachOnly: true`；否则 OpenClaw 会将该 loopback 端口视为本地托管浏览器配置，并可能报告本地端口归属错误。
- `existing-session` 配置使用 Chrome MCP 而不是 CDP，并且可以附加到选定主机，或通过已连接的浏览器节点附加。
- `existing-session` 配置可以设置 `userDataDir`，以指向特定的基于 Chromium 的浏览器配置，例如 Brave 或 Edge。
- `existing-session` 配置保留当前 Chrome MCP 路由限制：使用 snapshot/ref 驱动的操作而不是 CSS 选择器定位、单文件上传钩子、无对话框超时覆盖、无 `wait --load networkidle`，并且不支持 `responsebody`、PDF 导出、下载拦截或批量操作。
- 本地托管的 `openclaw` 配置会自动分配 `cdpPort` 和 `cdpUrl`；仅对远程 CDP 显式设置 `cdpUrl`。
- 本地托管配置可以设置 `executablePath`，以覆盖该配置的全局 `browser.executablePath`。可用它让一个配置运行在 Chrome 中，另一个运行在 Brave 中。
- 本地托管配置使用 `browser.localLaunchTimeoutMs` 处理进程启动后的 Chrome CDP HTTP 发现，并使用 `browser.localCdpReadyTimeoutMs` 处理启动后的 CDP websocket 就绪状态。在 Chrome 能成功启动但就绪检查与启动过程发生竞态的较慢主机上，可提高这些值。两个值都必须是最大为 `120000` ms 的正整数；无效配置值会被拒绝。
- 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 配置显式例外。
- 远程配置文件仅支持附加（启动/停止/重置已禁用）。
- `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。当你希望 OpenClaw 发现 `/json/version` 时使用 HTTP(S)；当你的提供商给你直接的 DevTools WebSocket URL 时使用 WS(S)。
- `remoteCdpTimeoutMs` 和 `remoteCdpHandshakeTimeoutMs` 适用于远程和 `attachOnly` CDP 可达性以及打开标签页的请求。托管的 loopback 配置文件保留本地 CDP 默认值。
- 如果一个外部托管的 CDP 服务可通过 loopback 访问，请将该配置文件的 `attachOnly: true`；否则 OpenClaw 会把 loopback 端口视为本地托管的浏览器配置文件，并可能报告本地端口归属错误。
- `existing-session` 配置文件使用 Chrome MCP 而不是 CDP，并且可以附加到所选主机或通过已连接的浏览器节点附加。
- `existing-session` 配置文件可以设置 `userDataDir`，以指向特定的基于 Chromium 的浏览器配置文件，例如 Brave 或 Edge。
- `existing-session` 配置文件保留当前 Chrome MCP 路由限制：基于快照/引用驱动的操作而不是 CSS 选择器目标定位、单文件上传钩子、无对话框超时覆盖、无 `wait --load networkidle`，并且没有 `responsebody`、PDF 导出、下载拦截或批量操作。
- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅为远程 CDP 显式设置 `cdpUrl`。
- 本地托管配置文件可以设置 `executablePath`，以覆盖该配置文件的全局 `browser.executablePath`。可用它让一个配置文件运行在 Chrome 中，另一个运行在 Brave 中。
- 本地托管配置文件在进程启动后使用 `browser.localLaunchTimeoutMs` 进行 Chrome CDP HTTP 发现，并使用 `browser.localCdpReadyTimeoutMs` 等待启动后的 CDP websocket 就绪。在较慢主机上，如果 Chrome 能成功启动但就绪检查与启动过程竞争，请提高这些值。两个值都必须是最大为 `120000` 毫秒的正整数；无效配置值会被拒绝。
- 自动检测顺序：默认浏览器（如果基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。
- `browser.executablePath` 和 `browser.profiles.<name>.executablePath` 都接受 `~` 和 `~/...`，用于在启动 Chromium 前表示你的操作系统主目录。`existing-session` 配置上的按配置 `userDataDir` 也会展开波浪号。
- `browser.executablePath` 和 `browser.profiles.<name>.executablePath` 都接受 `~` 和 `~/...`，表示 Chromium 启动前你的操作系统主目录。`existing-session` 配置文件上的按配置文件设置的 `userDataDir` 也会展开波浪号。
- 控制服务：仅 loopback（端口派生自 `gateway.port`，默认 `18791`）。
- `extraArgs` 会向本地 Chromium 启动追加额外启动标志（例如 `--disable-gpu`、窗口大小或调试标志）。
@ -287,7 +310,7 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式
```
- `seamColor`：原生应用 UI chrome 的强调色（Talk Mode 气泡色调等）。
- `assistant`：Control UI 身份覆盖。回退到活动智能体身份。
- `assistant`：Control UI 身份覆盖。回退到当前活跃智能体身份。
---
@ -364,50 +387,51 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式
<Accordion title="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`。
- **旧版绑定别名**：在 `gateway.bind` 中使用绑定模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用主机别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。
- **Docker 注意事项**：默认的 `loopback` 绑定会在容器内监听 `127.0.0.1`。使用 Docker 桥接网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 Gateway 网关无法访问。使用 `--network host`，或设置 `bind: "lan"`（或设置 `bind: "custom"` 并使用 `customBindHost: "0.0.0.0"`）以监听所有接口。
- **身份验证**：默认必需。非 loopback 绑定需要 Gateway 网关身份验证。实际含义是共享令牌/密码，或使用 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成一个令牌。
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRefs），请将 `gateway.auth.mode` 显式设置为 `token` 或 `password`。当两者都已配置且未设置模式时，启动和服务安装/修复流程会失败。
- `gateway.auth.mode: "none"`：显式无身份验证模式。仅用于可信的 local loopback 设置；新手引导提示有意不提供此选项。
- `gateway.auth.mode: "trusted-proxy"`：将浏览器/用户身份验证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份标头（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式默认预期使用**非 loopback** 代理来源；同主机 loopback 反向代理需要显式设置 `gateway.auth.trustedProxy.allowLoopback = true`。内部同主机调用方可以使用 `gateway.auth.password` 作为本地直接回退；`gateway.auth.token` 仍然与 trusted-proxy 模式互斥。
- `gateway.auth.allowTailscale`：当为 `true` 时，Tailscale Serve 身份标头可满足 Control UI/WebSocket 身份验证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 标头身份验证；它们改为遵循 Gateway 网关的常规 HTTP 身份验证模式。此无令牌流程假设 Gateway 网关主机可信。当 `tailscale.mode = "serve"` 时默认值为 `true`。
- `gateway.auth.rateLimit`：可选的身份验证失败限流器。按客户端 IP 和身份验证范围应用（shared-secret 与 device-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 绑定）或 `funnel`（公开，需要身份验证）。
- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器来源允许列表。当预期浏览器客户端来自非 loopback 来源时必需。
- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host 标头来源策略的部署启用 Host 标头来源回退。
- `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。
- `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`），不要使用主机别名（`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 网关身份验证。实际含义是使用共享令牌/密码，或使用带有 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认生成令牌。
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRefs），请将 `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 反向代理需要显式设置 `gateway.auth.trustedProxy.allowLoopback = true`。内部同主机调用方可以使用 `gateway.auth.password` 作为本地直连回退；`gateway.auth.token` 仍然与 trusted-proxy 模式互斥。
- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份标头可以满足 Control UI/WebSocket 身份验证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 标头身份验证；它们改为遵循 Gateway 网关的普通 HTTP 身份验证模式。此无令牌流程假定 Gateway 网关主机受信任。当 `tailscale.mode = "serve"` 时，默认为 `true`。
- `gateway.auth.rateLimit`：可选的身份验证失败限流器。按客户端 IP 和身份验证范围应用（shared-secret 和 device-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-header 来源策略的部署启用 Host-header 来源回退。
- `remote.transport`: `ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境中的
应急覆盖，允许对可信私有网络 IP 使用明文 `ws://`；明文默认仍然仅限 loopback。
没有等效的 `openclaw.json` 配置，并且浏览器私有网络配置（例如
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`）不会影响 Gateway 网关
应急覆盖开关，允许对受信任的私有网络
IP 使用明文 `ws://`；明文默认仍仅限 loopback。没有等效的 `openclaw.json`
配置，并且类似
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 的浏览器私有网络配置不会影响 Gateway 网关
WebSocket 客户端。
- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关身份验证。
- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 构建在向 Gateway 网关发布由中继支持的注册后所使用的外部 APNs 中继的基础 HTTPS URL。此 URL 必须与编译进 iOS 构建的中继 URL 匹配。
- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到中继的发送超时，单位为毫秒。默认值为 `10000`。
- 由中继支持的注册会委托给特定的 Gateway 网关身份。配对的 iOS 应用会获取 `gateway.identity.get`，在中继注册中包含该身份，并将注册范围内的发送授权转发给 Gateway 网关。另一个 Gateway 网关不能复用该已存储的注册。
- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：用于上述中继配置的临时环境覆盖。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅用于开发的逃生口，允许 loopback HTTP 中继 URL。生产中继 URL 应保持使用 HTTPS。
- `gateway.handshakeTimeoutMs`：身份验证前 Gateway 网关 WebSocket 握手超时，单位为毫秒。默认值：`15000`。设置后，`OPENCLAW_HANDSHAKE_TIMEOUT_MS` 优先。当负载较高或低功耗主机上的本地客户端可以连接但启动预热仍在稳定时，请增大此值。
- `gateway.channelHealthCheckMinutes`：渠道健康监视器间隔，单位为分钟。设置为 `0` 可全局禁用健康监视器重启。默认值：`5`。
- `gateway.channelStaleEventThresholdMinutes`：陈旧套接字阈值，单位为分钟。保持此值大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。
- `gateway.channelMaxRestartsPerHour`：每个渠道/账号在滚动一小时内的最大健康监视器重启次数。默认值：`10`。
- `channels.<provider>.healthMonitor.enabled`：每个渠道的健康监视器重启选择退出，同时保留全局监视器启用。
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`：多账号渠道的每账号覆盖。设置后，它优先于渠道级覆盖。
- 仅当 `gateway.auth.*` 未设置时，本地 Gateway 网关调用路径才能将 `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`：在配对和平台允许列表评估后，对已声明节点命令进行全局允许/拒绝塑形。使用 `allowCommands` 选择启用危险节点命令，例如 `camera.snap`、`camera.clip` 和 `screen.record`；即使平台默认值或显式允许本会包含某个命令，`denyCommands` 也会移除它。节点更改其声明的命令列表后，请拒绝并重新批准该设备配对，以便 Gateway 网关存储更新后的命令快照。
- `gateway.push.apns.relay.baseUrl`：官方/TestFlight iOS 构建在将中继支持的注册发布到 Gateway 网关后使用的外部 APNs 中继的 HTTPS 基础 URL。此 URL 必须匹配编译进 iOS 构建中的中继 URL。
- `gateway.push.apns.relay.timeoutMs`: Gateway 网关到中继的发送超时，单位为毫秒。默认值为 `10000`。
- 中继支持的注册会委托给特定的 Gateway 网关身份。配对的 iOS 应用会获取 `gateway.identity.get`，在中继注册中包含该身份，并将注册范围的发送授权转发给 Gateway 网关。另一个 Gateway 网关无法复用已存储的注册。
- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：用于上述中继配置的临时环境变量覆盖。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅用于开发的逃生口，允许 loopback HTTP 中继 URL。生产中继 URL 应保持 HTTPS。
- `gateway.handshakeTimeoutMs`：身份验证前的 Gateway 网关 WebSocket 握手超时，单位为毫秒。默认值：`15000`。设置后，`OPENCLAW_HANDSHAKE_TIMEOUT_MS` 优先。当本地客户端可连接但启动预热仍在收敛的高负载或低性能主机上，请增大此值。
- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔，单位为分钟。设置为 `0` 可全局禁用健康监控重启。默认值：`5`。
- `gateway.channelStaleEventThresholdMinutes`：陈旧 socket 阈值，单位为分钟。保持该值大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。
- `gateway.channelMaxRestartsPerHour`：每个渠道/账户在滚动一小时内的最大健康监控重启次数。默认值：`10`。
- `channels.<provider>.healthMonitor.enabled`：按渠道选择退出健康监控重启，同时保持全局监控启用。
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`：多账户渠道的按账户覆盖。设置后，它优先于渠道级覆盖。
- 仅当未设置 `gateway.auth.*` 时，本地 Gateway 网关调用路径才可以使用 `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`：配对和平台允许列表评估之后，用于已声明节点命令的全局允许/拒绝塑形。使用 `allowCommands` 选择启用危险节点命令，例如 `camera.snap`、`camera.clip` 和 `screen.record`；即使平台默认值或显式允许本来会包含某个命令，`denyCommands` 也会移除它。节点更改其已声明的命令列表后，请拒绝并重新批准该设备配对，以便 Gateway 网关存储更新后的命令快照。
- `gateway.tools.deny`：为 HTTP `POST /tools/invoke` 阻止的额外工具名称（扩展默认拒绝列表）。
- `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名称。
@ -428,7 +452,7 @@ OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，并由嵌入式
### 多实例隔离
在一台主机上运行多个 Gateway 网关，并使用唯一端口和状态目录：
使用唯一端口和状态目录在一台主机上运行多个 Gateway 网关：
```bash
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
@ -436,7 +460,7 @@ 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)。
@ -456,11 +480,11 @@ openclaw gateway --port 19001
}
```
- `enabled`：在 Gateway 网关监听器处启用 TLS 终止（HTTPS/WSS）（默认值：`false`）。
- `autoGenerate`：当未配置显式文件时，自动生成本地自签名证书/密钥对；仅用于本地/开发用途。
- `enabled`：在 Gateway 网关监听器启用 TLS 终止（HTTPS/WSS）（默认值：`false`）。
- `autoGenerate`：未配置显式文件时，自动生成本地自签名证书/密钥对；仅用于本地/开发。
- `certPath`：TLS 证书文件的文件系统路径。
- `keyPath`：TLS 私钥文件的文件系统路径；请限制权限。
- `caPath`：用于客户端验证或自定义信任链的可选 CA 包路径。
- `keyPath`：TLS 私钥文件的文件系统路径；保持权限受限。
- `caPath`：用于客户端验证或自定义信任链的可选 CA bundle 路径。
### `gateway.reload`
@ -478,11 +502,11 @@ openclaw gateway --port 19001
- `mode`：控制配置编辑在运行时的应用方式。
- `"off"`：忽略实时编辑；更改需要显式重启。
- `"restart"`：配置更改时始终重启 Gateway 网关进程。
- `"hot"`：在进程内应用更改而不重启。
- `"hybrid"`（默认）：先尝试热重载；必要时回退到重启。
- `debounceMs`：应用配置更改前的防抖窗口，单位为毫秒（非负整数）。
- `deferralTimeoutMs`：可选的最大等待时间，单位为毫秒，用于在强制重启前等待进行中的操作。省略时使用默认有界等待（`300000`）；设置为 `0` 可无限期等待，并定期记录仍有挂起操作的警告。
- `"restart"`：配置变更时始终重启 Gateway 网关进程。
- `"hot"`：在进程内应用更改，不重启。
- `"hybrid"`（默认）：先尝试热重载；如有必要则回退到重启。
- `debounceMs`：应用配置更改前的防抖窗口，单位为 ms（非负整数）。
- `deferralTimeoutMs`：在强制重启前等待进行中操作的可选最大时间，单位为 ms。省略它以使用默认的有界等待（`300000`）；设置为 `0` 可无限期等待并定期记录仍待处理的警告。
---
@ -522,45 +546,45 @@ openclaw gateway --port 19001
身份验证：`Authorization: Bearer <token>` 或 `x-openclaw-token: <token>`。
查询字符串钩子令牌会被拒绝。
验证与安全说明：
验证和安全说明：
- `hooks.enabled=true` 要求 `hooks.token` 非空。
- `hooks.enabled=true` 需要非空的 `hooks.token`。
- `hooks.token` 必须与 `gateway.auth.token` **不同**；重复使用 Gateway 网关令牌会被拒绝。
- `hooks.path` 不能是 `/`；请使用专用子路径，例如 `/hooks`。
- 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。
- 如果映射或预设使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要此选择启用。
- 如果 `hooks.allowRequestSessionKey=true`，请限制 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。
- 如果映射或预设使用模板化 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要此显式启用。
**端点：**
- `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }`
- `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }`
- 仅当 `hooks.allowRequestSessionKey=true`（默认值：`false`）时，才接受请求载荷中的 `sessionKey`。
- 仅当 `hooks.allowRequestSessionKey=true` 时，才接受来自请求载荷的 `sessionKey`（默认值：`false`）。
- `POST /hooks/<name>` → 通过 `hooks.mappings` 解析
- 模板渲染的映射 `sessionKey` 值会被视为外部提供，也要求 `hooks.allowRequestSessionKey=true`。
- 模板渲染的映射 `sessionKey` 值会被视为外部提供，也需要 `hooks.allowRequestSessionKey=true`。
<Accordion title="Mapping details">
- `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。
- `match.source` 匹配通用路径的载荷字段。
- `match.source` 匹配通用路径的一个载荷字段。
- 类似 `{{messages[0].subject}}` 的模板会从载荷读取。
- `transform` 可以指向一个返回钩子操作的 JS/TS 模块。
- `transform.module` 必须是相对路径，并且保持在 `hooks.transformsDir` 内（绝对路径和路径穿越会被拒绝）。
- 将 `hooks.transformsDir` 保持在 `~/.openclaw/hooks/transforms` 下；工作区 Skills 目录会被拒绝。如果 `openclaw doctor` 报告此路径无效，请将转换模块移动到钩子转换目录，或移除 `hooks.transformsDir`。
- `transform` 可以指向返回钩子操作的 JS/TS 模块。
- `transform.module` 必须是相对路径，并保持在 `hooks.transformsDir` 内（绝对路径和路径遍历会被拒绝）。
- 将 `hooks.transformsDir` 保持在 `~/.openclaw/hooks/transforms` 下；工作区 Skills 目录会被拒绝。如果 `openclaw doctor` 报告此路径无效，请将转换模块移入 hooks 转换目录，或移除 `hooks.transformsDir`。
- `agentId` 路由到特定智能体；未知 ID 会回退到默认值。
- `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 拒绝全部）。
- `defaultSessionKey`：可选的固定会话键，用于没有显式 `sessionKey` 的钩子智能体运行。
- `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 全部拒绝）。
- `defaultSessionKey`：没有显式 `sessionKey` 的钩子智能体运行所用的可选固定会话键。
- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方和模板驱动的映射会话键设置 `sessionKey`（默认值：`false`）。
- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任何映射或预设使用模板化的 `sessionKey` 时，它会变为必需项。
- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任何映射或预设使用模板化 `sessionKey` 时，它会变为必需。
- `deliver: true` 将最终回复发送到渠道；`channel` 默认为 `last`。
- `model` 会为这次钩子运行覆盖 LLM（如果设置了模型目录，则必须被允许）。
- `model` 会覆盖此钩子运行的 LLM（如果设置了模型目录，则必须被允许）。
</Accordion>
### Gmail 集成
- 内置 Gmail 预设使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。
- 如果保留这种按消息路由，请设置 `hooks.allowRequestSessionKey: true`，并约束 `hooks.allowedSessionKeyPrefixes` 以匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。
- 如果你需要 `hooks.allowRequestSessionKey: false`，请使用静态 `sessionKey` 覆盖预设，而不是使用模板化默认值。
- 如果保留这种按消息路由，请设置 `hooks.allowRequestSessionKey: true`，并限制 `hooks.allowedSessionKeyPrefixes` 以匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。
- 如果需要 `hooks.allowRequestSessionKey: false`，请用静态 `sessionKey` 覆盖该预设，而不是使用模板化默认值。
```json5
{
@ -600,18 +624,18 @@ openclaw gateway --port 19001
}
```
- 在 Gateway 网关端口下通过 HTTP 提供智能体可编辑的 HTML/CSS/JS 和 A2UI：
- 通过 Gateway 网关端口下的 HTTP 提供智能体可编辑的 HTML/CSS/JS 和 A2UI：
- `http://<gateway-host>:<gateway.port>/__openclaw__/canvas/`
- `http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/`
- 仅本地：保持 `gateway.bind: "loopback"`（默认值）。
- 非 loopback 绑定：canvas 路由要求 Gateway 网关认证（令牌/密码/受信任代理），与其他 Gateway 网关 HTTP 表面相同。
- 节点 WebView 通常不会发送认证标头；节点配对并连接后，Gateway 网关会公布节点作用域的能力 URL，用于访问 canvas/A2UI。
- 能力 URL 绑定到活动节点 WS 会话，并会很快过期。不使用基于 IP 的回退。
- 向提供的 HTML 注入实时重载客户端。
- 为空时自动创建入门 `index.html`。
- 也会在 `/__openclaw__/a2ui/` 提供 A2UI。
- 非 loopback 绑定：canvas 路由需要 Gateway 网关认证（令牌/密码/可信代理），与其他 Gateway 网关 HTTP 表面相同。
- Node WebViews 通常不会发送认证标头；节点完成配对并连接后，Gateway 网关会为 canvas/A2UI 访问通告节点作用域的能力 URL。
- 能力 URL 绑定到活动节点 WS 会话，并会快速过期。不使用基于 IP 的回退。
- 将实时重载客户端注入到所提供的 HTML 中。
- 为空时自动创建起始 `index.html`。
- 也在 `/__openclaw__/a2ui/` 提供 A2UI。
- 更改需要重启 Gateway 网关。
- 对于大型目录或 `EMFILE` 错误，请禁用实时重载。
- 对大型目录或 `EMFILE` 错误禁用实时重载。
---
@ -631,7 +655,7 @@ openclaw gateway --port 19001
- `minimal`（默认值）：从 TXT 记录中省略 `cliPath` + `sshPort`。
- `full`：包含 `cliPath` + `sshPort`。
- 当系统主机名是有效 DNS 标签时，主机名默认为系统主机名，否则回退到 `openclaw`。可用 `OPENCLAW_MDNS_HOSTNAME` 覆盖。
- 当系统主机名是有效 DNS 标签时，主机名默认使用系统主机名，否则回退到 `openclaw`。可使用 `OPENCLAW_MDNS_HOSTNAME` 覆盖。
### 广域（DNS-SD）
@ -643,7 +667,7 @@ openclaw gateway --port 19001
}
```
在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。对于跨网络设备发现，请搭配 DNS 服务器（推荐 CoreDNS）+ Tailscale 拆分 DNS。
在 `~/.openclaw/dns/` 下写入单播 DNS-SD 区域。对于跨网络设备发现，请搭配 DNS 服务器（推荐 CoreDNS）+ Tailscale 分割 DNS。
设置：`openclaw dns setup --apply`。
@ -668,14 +692,14 @@ openclaw gateway --port 19001
}
```
- 仅当进程环境缺少对应键时，才应用内联环境变量。
- 仅当进程环境缺少该键时，才应用内联环境变量。
- `.env` 文件：CWD `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。
- `shellEnv`：从你的登录 shell 配置文件导入缺失的预期键名。
- 参见[环境](/zh-CN/help/environment)了解完整优先级。
- `shellEnv`：从你的登录 shell profile 导入缺失的预期键名。
- 完整优先级请参阅 [环境](/zh-CN/help/environment)。
### 环境变量替换
在任何配置字符串中使用 `${VAR_NAME}` 引用环境变量：
在任意配置字符串中使用 `${VAR_NAME}` 引用环境变量：
```json5
{
@ -688,17 +712,17 @@ openclaw gateway --port 19001
- 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。
- 缺失/空变量会在配置加载时报错。
- 使用 `$${VAR}` 转义为字面量 `${VAR}`。
- 适用于 `$include`。
- 可与 `$include` 配合使用。
---
## 密钥
密钥引用是增量能力：明文值仍然可用。
Secret refs 是增量功能：明文值仍可使用。
### `SecretRef`
使用一种对象形态：
使用一种对象形状：
```json5
{ source: "env" | "file" | "exec", provider: "default", id: "..." }
@ -710,13 +734,13 @@ openclaw gateway --port 19001
- `source: "env"` id 模式：`^[A-Z][A-Z0-9_]{0,127}$`
- `source: "file"` id：绝对 JSON 指针（例如 `"/providers/openai/apiKey"`）
- `source: "exec"` id 模式：`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
- `source: "exec"` id 不得包含 `.` 或 `..` 这种以斜杠分隔的路径片段（例如 `a/../b` 会被拒绝）
- `source: "exec"` id 不得包含 `.` 或 `..` 斜杠分隔路径段（例如 `a/../b` 会被拒绝）
### 支持的凭证表面
### 支持的凭据表面
- 规范矩阵：[SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface)
- `secrets apply` 面向受支持的 `openclaw.json` 凭证路径。
- `auth-profiles.json` 引用包含在运行时解析和审计覆盖范围内。
- 规范矩阵：[SecretRef 凭据表面](/zh-CN/reference/secretref-credential-surface)
- `secrets apply` 目标为受支持的 `openclaw.json` 凭据路径。
- `auth-profiles.json` refs 包含在运行时解析和审计覆盖范围中。
### 密钥提供商配置
@ -749,13 +773,13 @@ openclaw gateway --port 19001
说明：
- `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须是 `"value"`）。
- 当 Windows ACL 验证不可用时，文件和 exec 提供商路径会失败关闭。仅对无法验证但受信任的路径设置 `allowInsecurePath: true`。
- `exec` 提供商要求使用绝对 `command` 路径，并在 stdin/stdout 上使用协议载荷。
- 当 Windows ACL 验证不可用时，文件和 exec 提供商路径会失败关闭。仅对无法验证的可信路径设置 `allowInsecurePath: true`。
- `exec` 提供商需要绝对 `command` 路径，并在 stdin/stdout 上使用协议载荷。
- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时验证解析后的目标路径。
- 如果配置了 `trustedDirs`，受信任目录检查会应用到解析后的目标路径。
- `exec` 子进程环境默认是最小环境；请使用 `passEnv` 显式传递所需变量。
- 密钥引用会在激活时解析到内存中的快照，随后请求路径只读取该快照。
- 激活期间会应用活动表面过滤：已启用表面上的未解析引用会导致启动/重载失败，而非活动表面会跳过并给出诊断。
- 如果配置了 `trustedDirs`，可信目录检查会应用于解析后的目标路径。
- 默认情况下，`exec` 子环境是最小化的；请用 `passEnv` 显式传入所需变量。
- Secret refs 会在激活时解析到内存快照中，之后请求路径只读取该快照。
- 激活期间会应用活动表面过滤：启用表面上的未解析 refs 会导致启动/重载失败，而非活动表面会被跳过并附带诊断信息。
---
@ -777,13 +801,13 @@ openclaw gateway --port 19001
}
```
- 按智能体配置文件存储在 `<agentDir>/auth-profiles.json`。
- 对于静态凭证模式，`auth-profiles.json` 支持值级引用（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。
- 旧版扁平 `auth-profiles.json` 映射（例如 `{ "provider": { "apiKey": "..." } }`）不是运行时格式；`openclaw doctor --fix` 会将它们重写为规范的 `provider:default` API-key 配置文件，并生成 `.legacy-flat.*.bak` 备份。
- OAuth 模式配置文件（`auth.profiles.<id>.mode = "oauth"`）不支持由 SecretRef 支持的认证配置文件凭证。
- 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会清除它们。
- 每智能体 profiles 存储在 `<agentDir>/auth-profiles.json`。
- `auth-profiles.json` 支持值级 refs（静态凭据模式中，`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。
- 旧版扁平 `auth-profiles.json` 映射（例如 `{ "provider": { "apiKey": "..." } }`）不是运行时格式；`openclaw doctor --fix` 会将它们重写为规范的 `provider:default` API-key profiles，并带有 `.legacy-flat.*.bak` 备份。
- OAuth 模式 profiles（`auth.profiles.<id>.mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭据。
- 静态运行时凭据来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会将其清除。
- 旧版 OAuth 从 `~/.openclaw/credentials/oauth.json` 导入。
- 参见 [OAuth](/zh-CN/concepts/oauth)。
- 请参阅 [OAuth](/zh-CN/concepts/oauth)。
- 密钥运行时行为和 `audit/configure/apply` 工具：[密钥管理](/zh-CN/gateway/secrets)。
### `auth.cooldowns`
@ -806,19 +830,19 @@ openclaw gateway --port 19001
}
```
- `billingBackoffHours`：当配置档案因真实的计费/余额不足错误失败时，以小时为单位的基础退避（默认：`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`：在切换到模型回退之前，过载错误可进行的最大同一提供商认证配置档案轮换次数（默认：`1`）。诸如 `ModelNotReadyException` 的提供商繁忙形态会归入这里。
- `overloadedBackoffMs`：在重试过载的提供商/配置档案轮换前的固定延迟（默认：`0`）。
- `rateLimitedProfileRotations`：在切换到模型回退之前，限速错误可进行的最大同一提供商认证配置档案轮换次数（默认：`1`）。该限速桶包含提供商形态的文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。
- `billingBackoffHours`：当某个配置档案因真实的账单/余额不足错误而失败时，以小时为单位的基础退避时间（默认值：`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`：在切换到模型回退之前，过载错误允许的最大同一提供商身份配置轮换次数（默认值：`1`）。诸如 `ModelNotReadyException` 这类提供商繁忙形态会归入这里。
- `overloadedBackoffMs`：重试过载的提供商/配置档案轮换前的固定延迟（默认值：`0`）。
- `rateLimitedProfileRotations`：在切换到模型回退之前，限流错误允许的最大同一提供商身份配置轮换次数（默认值：`1`）。该限流桶包括提供商形态的文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。
---
## 日志
## 日志记录
```json5
{
@ -835,9 +859,9 @@ openclaw gateway --port 19001
- 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。
- 设置 `logging.file` 可使用稳定路径。
- 使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。
- `maxFileBytes`：轮转前活动日志文件的最大字节大小（正整数；默认：`104857600` = 100 MB）。OpenClaw 会在活动文件旁保留最多五个编号归档。
- `redactSensitive` / `redactPatterns`：对控制台输出、文件日志、OTLP 日志记录和持久化会话转录文本进行尽力而为的遮蔽。`redactSensitive: "off"` 只会禁用此通用日志/转录策略；UI/工具/诊断安全表面在发出前仍会遮蔽密钥。
- 使用 `--verbose` 时，`consoleLevel` 会提升到 `debug`。
- `maxFileBytes`：轮换前活动日志文件的最大字节数（正整数；默认值：`104857600` = 100 MB）。OpenClaw 会在活动文件旁最多保留五个编号归档文件。
- `redactSensitive` / `redactPatterns`：尽力对控制台输出、文件日志、OTLP 日志记录和持久化的会话转录文本进行掩码处理。`redactSensitive: "off"` 只会禁用这个通用日志/转录策略；UI/工具/诊断安全表面仍会在发出前遮盖密钥。
---
@ -885,25 +909,25 @@ openclaw gateway --port 19001
}
```
- `enabled`：仪表输出的主开关（默认：`true`）。
- `flags`：启用目标日志输出的标志字符串数组（支持 `"telegram.*"` 或 `"*"` 等通配符）。
- `stuckSessionWarnMs`：用于将长时间运行的处理会话分类为 `session.long_running`、`session.stalled` 或 `session.stuck` 的无进展时间阈值，单位为毫秒。回复、工具、Status、分块和 ACP 进度会重置计时器；重复的 `session.stuck` 诊断在未变化时会退避。
- `otel.enabled`：启用 OpenTelemetry 导出管线（默认：`false`）。完整配置、信号目录和隐私模型见 [OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)。
- `otel.endpoint`：OTel 导出的收集器 URL。
- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`：可选的特定信号 OTLP 端点。设置后，它们只会覆盖该信号的 `otel.endpoint`。
- `enabled`：仪表输出的总开关（默认值：`true`）。
- `flags`：启用定向日志输出的标志字符串数组（支持 `"telegram.*"` 或 `"*"` 这样的通配符）。
- `stuckSessionWarnMs`：用于将长时间运行的处理会话归类为 `session.long_running`、`session.stalled` 或 `session.stuck` 的无进展时长阈值，单位为 ms。回复、工具、Status、分块和 ACP 进度会重置计时器；重复的 `session.stuck` 诊断会在未变化时退避。
- `otel.enabled`：启用 OpenTelemetry 导出管线（默认值：`false`）。完整配置、信号目录和隐私模型见 [OpenTelemetry 导出](/zh-CN/gateway/opentelemetry)。
- `otel.endpoint`：用于 OTel 导出的收集器 URL。
- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`：可选的按信号指定的 OTLP 端点。设置后，它们只会覆盖对应信号的 `otel.endpoint`。
- `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。
- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据标头。
- `otel.serviceName`：资源属性的服务名称。
- `otel.traces` / `otel.metrics` / `otel.logs`：启用追踪、指标或日志导出。
- `otel.sampleRate`：追踪采样率 `0`–`1`。
- `otel.flushIntervalMs`：定期遥测刷新间隔，单位为毫秒。
- `otel.captureContent`：选择性捕获原始内容用于 OTEL span 属性。默认关闭。布尔值 `true` 会捕获非系统消息/工具内容；对象形式可让你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。
- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`：用于最新实验性 GenAI span 提供商属性的环境开关。默认情况下，span 会保留旧版 `gen_ai.system` 属性以保持兼容；GenAI 指标使用有界语义属性。
- `OPENCLAW_OTEL_PRELOADED=1`：用于已注册全局 OpenTelemetry SDK 的宿主的环境开关。随后 OpenClaw 会跳过插件拥有的 SDK 启动/关闭，同时保持诊断监听器活动。
- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`、`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` 和 `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`：在匹配的配置键未设置时使用的特定信号端点环境变量。
- `cacheTrace.enabled`：为嵌入式运行记录缓存追踪快照（默认：`false`）。
- `cacheTrace.filePath`：缓存追踪 JSONL 的输出路径（默认：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。
- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存追踪输出中包含哪些内容（全部默认：`true`）。
- `otel.flushIntervalMs`：周期性遥测刷新间隔，单位为 ms。
- `otel.captureContent`：选择启用用于 OTEL span 属性的原始内容捕获。默认关闭。布尔值 `true` 会捕获非系统消息/工具内容；对象形式允许你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。
- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`：用于最新实验性 GenAI span 提供商属性的环境开关。默认情况下，为兼容性，span 保留旧版 `gen_ai.system` 属性；GenAI 指标使用有界语义属性。
- `OPENCLAW_OTEL_PRELOADED=1`：用于已经注册全局 OpenTelemetry SDK 的主机的环境开关。随后 OpenClaw 会跳过插件拥有的 SDK 启动/关闭，同时保持诊断监听器活跃。
- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`、`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` 和 `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`：当匹配的配置键未设置时使用的按信号指定的端点环境变量。
- `cacheTrace.enabled`：为嵌入式运行记录缓存追踪快照（默认值：`false`）。
- `cacheTrace.filePath`：缓存追踪 JSONL 的输出路径（默认值：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。
- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存追踪输出中包含哪些内容（全部默认值：`true`）。
---
@ -926,11 +950,11 @@ openclaw gateway --port 19001
```
- `channel`：npm/git 安装的发布渠道 — `"stable"`、`"beta"` 或 `"dev"`。
- `checkOnStart`：Gateway 网关启动时检查 npm 更新（默认：`true`）。
- `auto.enabled`：为软件包安装启用后台自动更新（默认：`false`）。
- `auto.stableDelayHours`：稳定渠道自动应用前的最小延迟小时数（默认：`6`；最大：`168`）。
- `auto.stableJitterHours`：稳定渠道发布扩散窗口的额外小时数（默认：`12`；最大：`168`）。
- `auto.betaCheckIntervalHours`：beta 渠道检查运行的频率，单位为小时（默认：`1`；最大：`24`）。
- `checkOnStart`：Gateway 网关启动时检查 npm 更新（默认值：`true`）。
- `auto.enabled`：为包安装启用后台自动更新（默认值：`false`）。
- `auto.stableDelayHours`：稳定渠道自动应用前的最小延迟小时数（默认值：`6`；最大值：`168`）。
- `auto.stableJitterHours`：稳定渠道发布扩散窗口的额外小时数（默认值：`12`；最大值：`168`）。
- `auto.betaCheckIntervalHours`：Beta 渠道检查运行频率，单位为小时（默认值：`1`；最大值：`24`）。
---
@ -963,22 +987,22 @@ openclaw gateway --port 19001
}
```
- `enabled`：全局 ACP 功能门控（默认：`true`；设为 `false` 可隐藏 ACP 派发和生成入口）。
- `dispatch.enabled`：ACP 会话轮次派发的独立门控（默认：`true`）。设为 `false` 可在保留 ACP 命令可用的同时阻止执行。
- `enabled`：全局 ACP 功能门控（默认值：`true`；设置为 `false` 可隐藏 ACP 分发和派生入口）。
- `dispatch.enabled`：ACP 会话轮次分发的独立门控（默认值：`true`）。设置为 `false` 可在保留 ACP 命令可用的同时阻止执行。
- `backend`：默认 ACP 运行时后端 ID（必须匹配已注册的 ACP 运行时插件）。
请先安装后端插件；如果设置了 `plugins.allow`，请包含后端插件 ID（例如 `acpx`），否则 ACP 后端不会加载。
- `defaultAgent`：生成未指定显式目标时的回退 ACP 目标智能体 ID。
先安装后端插件；如果设置了 `plugins.allow`，请包含后端插件 ID（例如 `acpx`），否则 ACP 后端不会加载。
- `defaultAgent`：当派生未指定显式目标时使用的回退 ACP 目标智能体 ID。
- `allowedAgents`：允许用于 ACP 运行时会话的智能体 ID 允许列表；为空表示没有额外限制。
- `maxConcurrentSessions`：并发活动 ACP 会话的最大数量。
- `stream.coalesceIdleMs`：流式文本的空闲刷新窗口，单位为毫秒。
- `stream.maxChunkChars`：拆分流式分块投影前的最大分块大小。
- `stream.repeatSuppression`：按轮次抑制重复的 Status/工具行（默认：`true`）。
- `maxConcurrentSessions`：并发活跃 ACP 会话的最大数量。
- `stream.coalesceIdleMs`：流式文本的空闲刷新窗口，单位为 ms。
- `stream.maxChunkChars`：分割流式分块投影前的最大分块大小。
- `stream.repeatSuppression`：按轮次抑制重复的 Status/工具行（默认值：`true`）。
- `stream.deliveryMode`：`"live"` 会增量流式传输；`"final_only"` 会缓冲到轮次终止事件。
- `stream.hiddenBoundarySeparator`：隐藏工具事件之后、可见文本之前的分隔符（默认：`"paragraph"`）。
- `stream.hiddenBoundarySeparator`：隐藏工具事件后、可见文本前的分隔符（默认值：`"paragraph"`）。
- `stream.maxOutputChars`：每个 ACP 轮次投影的最大助手输出字符数。
- `stream.maxSessionUpdateChars`：投影 ACP Status/更新行的最大字符数。
- `stream.maxSessionUpdateChars`：投影的 ACP Status/更新行的最大字符数。
- `stream.tagVisibility`：标记名称到流式事件布尔可见性覆盖的记录。
- `runtime.ttlMinutes`：ACP 会话工作进程在可清理前的空闲 TTL，单位为分钟。
- `runtime.ttlMinutes`：ACP 会话 worker 可被清理前的空闲 TTL，单位为分钟。
- `runtime.installCommand`：引导 ACP 运行时环境时要运行的可选安装命令。
---
@ -996,9 +1020,9 @@ openclaw gateway --port 19001
```
- `cli.banner.taglineMode` 控制横幅标语样式：
- `"random"`（默认）：轮换的趣味/季节性标语。
- `"random"`（默认）：轮换的有趣/季节性标语。
- `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。
- `"off"`：不显示标语文本（仍显示横幅标题/版本）。
- `"off"`：无标语文本（仍会显示横幅标题/版本）。
- 要隐藏整个横幅（不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。
---
@ -1023,15 +1047,15 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数
## 身份
请参阅 [智能体默认值](/zh-CN/gateway/config-agents#agent-defaults) 下的 `agents.list` 身份字段。
见 [Agent 默认值](/zh-CN/gateway/config-agents#agent-defaults) 下的 `agents.list` 身份字段。
---
## 桥接（旧版，已移除）
## Bridge（旧版，已移除）
当前构建不再包含 TCP 桥接。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键不再属于配置架构（验证会失败，直到移除；`openclaw doctor --fix` 可剥离未知键）。
当前构建不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键不再是配置架构的一部分（移除前验证会失败；`openclaw doctor --fix` 可以剥离未知键）。
<Accordion title="旧版桥接配置（历史参考）">
<Accordion title="旧版 bridge 配置（历史参考）">
```json
{
@ -1069,11 +1093,11 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数
}
```
- `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 令牌；如果省略，则不发送认证标头。
- `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 交付（`delivery.mode = "webhook"`）的 bearer token；如果省略，则不发送身份验证标头。
- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于仍有 `notify: true` 的已存储任务。
### `cron.retry`
@ -1089,11 +1113,11 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数
}
```
- `maxAttempts`：一次性任务在暂态错误上的最大重试次数（默认：`3`；范围：`0`–`10`）。
- `backoffMs`：每次重试尝试的退避延迟数组，单位为 ms（默认：`[30000, 60000, 300000]`；1–10 个条目）。
- `retryOn`：触发重试的错误类型：`"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略时会重试所有暂态类型。
- `maxAttempts`：一次性任务在瞬时错误上的最大重试次数（默认：`3`；范围：`0`–`10`）。
- `backoffMs`：每次重试尝试的退避延迟数组，单位为 ms（默认：`[30000, 60000, 300000]`；1–10 项）。
- `retryOn`：触发重试的错误类型 — `"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略则重试所有瞬时类型。
仅适用于一次性 cron 任务。周期性任务使用单独的失败处理。
仅适用于一次性 cron 任务。重复任务使用单独的失败处理。
### `cron.failureAlert`
@ -1112,12 +1136,12 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数
}
```
- `enabled`：启用 cron 任务的失败提醒（默认：`false`）。
- `after`：提醒触发前的连续失败次数（正整数，最小：`1`）。
- `cooldownMs`：同一任务重复提醒之间的最小毫秒数（非负整数）。
- `includeSkipped`：将连续跳过的运行计入提醒阈值（默认：`false`）。跳过的运行会单独跟踪，不影响执行错误退避。
- `mode`：投递模式：`"announce"` 通过渠道消息发送；`"webhook"` 发布到配置的 webhook。
- `accountId`：可选的账号或渠道 id，用于限定提醒投递范围。
- `enabled`：为 cron 任务启用失败告警（默认：`false`）。
- `after`：触发告警前的连续失败次数（正整数，最小值：`1`）。
- `cooldownMs`：同一任务重复告警之间的最小毫秒数（非负整数）。
- `includeSkipped`：将连续跳过的运行计入告警阈值（默认：`false`）。跳过的运行会单独跟踪，不影响执行错误退避。
- `mode`：投递模式 — `"announce"` 通过渠道消息发送；`"webhook"` 发布到已配置的 webhook。
- `accountId`：用于限定告警投递范围的可选账号或渠道 ID。
### `cron.failureDestination`
@ -1135,15 +1159,15 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数
```
- 所有任务的 cron 失败通知默认目标。
- `mode`：`"announce"` 或 `"webhook"`；当有足够目标数据时默认为 `"announce"`。
- `channel`：announce 投递的渠道覆盖项。`"last"` 会复用最后一个已知投递渠道。
- `mode`：`"announce"` 或 `"webhook"`；当存在足够目标数据时默认使用 `"announce"`。
- `channel`：announce 投递的渠道覆盖项。`"last"` 会复用最后已知的投递渠道。
- `to`：显式 announce 目标或 webhook URL。webhook 模式必填。
- `accountId`：可选的投递账号覆盖项。
- 每个任务的 `delivery.failureDestination` 会覆盖这个全局默认值。
- 当既未设置全局失败目标也未设置每任务失败目标时，已经通过 `announce` 投递的任务会在失败时回退到该主要 announce 目标。
- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 任务，除非任务的主要 `delivery.mode` 是 `"webhook"`。
- `accountId`：投递的可选账号覆盖项。
- 单个任务的 `delivery.failureDestination` 会覆盖此全局默认值。
- 当既未设置全局失败目标，也未设置单个任务失败目标时，已经通过 `announce` 投递的任务会在失败时回退到其主要 announce 目标。
- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 任务，除非该任务的主要 `delivery.mode` 为 `"webhook"`。
参见 [Cron 任务](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。
参见 [Cron 任务](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)跟踪。
---
@ -1151,34 +1175,34 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数
在 `tools.media.models[].args` 中展开的模板占位符：
| 变量 | 描述 |
| ------------------ | ---------------------------------------------- |
| `{{Body}}` | 完整的入站消息正文 |
| `{{RawBody}}` | 原始正文（无历史记录/发送者包装） |
| `{{BodyStripped}}` | 已去除群组提及的正文 |
| `{{From}}` | 发送者标识符 |
| `{{To}}` | 目标标识符 |
| `{{MessageSid}}` | 渠道消息 id |
| `{{SessionId}}` | 当前会话 UUID |
| `{{IsNewSession}}` | 创建新会话时为 `"true"` |
| `{{MediaUrl}}` | 入站媒体伪 URL |
| `{{MediaPath}}` | 本地媒体路径 |
| `{{MediaType}}` | 媒体类型（图片/音频/文档/…） |
| `{{Transcript}}` | 音频转写文本 |
| `{{Prompt}}` | CLI 条目的已解析媒体提示词 |
| `{{MaxChars}}` | CLI 条目的已解析最大输出字符数 |
| `{{ChatType}}` | `"direct"` 或 `"group"` |
| `{{GroupSubject}}` | 群组主题（尽力获取） |
| `{{GroupMembers}}` | 群组成员预览（尽力获取） |
| `{{SenderName}}` | 发送者显示名称（尽力获取） |
| `{{SenderE164}}` | 发送者电话号码（尽力获取） |
| `{{Provider}}` | 提供商提示（WhatsApp、Telegram、Discord 等） |
| 变量 | 描述 |
| ------------------ | ------------------------------------------------- |
| `{{Body}}` | 完整的入站消息正文 |
| `{{RawBody}}` | 原始正文（无历史记录/发送者包装） |
| `{{BodyStripped}}` | 已去除群组提及的正文 |
| `{{From}}` | 发送者标识符 |
| `{{To}}` | 目标标识符 |
| `{{MessageSid}}` | 渠道消息 ID |
| `{{SessionId}}` | 当前会话 UUID |
| `{{IsNewSession}}` | 创建新会话时为 `"true"` |
| `{{MediaUrl}}` | 入站媒体伪 URL |
| `{{MediaPath}}` | 本地媒体路径 |
| `{{MediaType}}` | 媒体类型（图片/音频/文档/…） |
| `{{Transcript}}` | 音频转写文本 |
| `{{Prompt}}` | CLI 条目的已解析媒体提示词 |
| `{{MaxChars}}` | CLI 条目的已解析最大输出字符数 |
| `{{ChatType}}` | `"direct"` 或 `"group"` |
| `{{GroupSubject}}` | 群组主题（尽力获取） |
| `{{GroupMembers}}` | 群组成员预览（尽力获取） |
| `{{SenderName}}` | 发送者显示名称（尽力获取） |
| `{{SenderE164}}` | 发送者电话号码（尽力获取） |
| `{{Provider}}` | 提供商提示（whatsapp、telegram、discord 等） |
---
## 配置包含（`$include`）
将配置拆分到多个文件：
将配置拆分为多个文件：
```json5
// ~/.openclaw/openclaw.json
@ -1197,10 +1221,10 @@ CLI 引导式设置流程（`onboard`、`configure`、`doctor`）写入的元数
- 文件数组：按顺序深度合并（后面的覆盖前面的）。
- 同级键：在包含后合并（覆盖已包含的值）。
- 嵌套包含：最多深入 10 层。
- 路径：相对于发起包含的文件解析，但必须留在顶层配置目录（`openclaw.json` 的 `dirname`）内。仅当绝对路径/`../` 形式仍解析到该边界内时才允许使用。
- OpenClaw 拥有的写入如果只更改由单文件包含支持的一个顶层分区，会透传写入该被包含文件。例如，`plugins install` 会在 `plugins.json5` 中更新 `plugins: { $include: "./plugins.json5" }`，并保持 `openclaw.json` 不变。
- 根包含、包含数组以及带同级覆盖的包含对于 OpenClaw 拥有的写入是只读的；这些写入会关闭失败，而不是将配置扁平化。
- 错误：针对缺失文件、解析错误和循环包含提供清晰消息。
- 路径：相对于包含它的文件解析，但必须保留在顶层配置目录（`openclaw.json` 的 `dirname`）内。绝对路径/`../` 形式仅在仍解析到该边界内时才允许。
- 仅更改由单文件包含支持的一个顶层部分的 OpenClaw 自有写入，会写入该包含文件。例如，`plugins install` 会在 `plugins.json5` 中更新 `plugins: { $include: "./plugins.json5" }`，并保持 `openclaw.json` 不变。
- 根包含、包含数组以及带同级覆盖项的包含，对 OpenClaw 自有写入是只读的；这些写入会失败关闭，而不是扁平化配置。
- 错误：对缺失文件、解析错误和循环包含提供清晰消息。
---

177
docs/zh-CN/reference/token-use.md
View File

@ -1,112 +1,98 @@
---
read_when:
- 解释令牌用量、成本或上下文窗口
- 解释 token 使用量、费用或上下文窗口
- 调试上下文增长或压缩行为
summary: OpenClaw 如何构建提示词上下文并报告 token 用量和成本
title: 词元使用量和费用
summary: OpenClaw 如何构建提示词上下文并报告词元用量和成本
title: Token 使用量和费用
x-i18n:
generated_at: "2026-04-28T12:04:01Z"
generated_at: "2026-05-02T10:12:06Z"
model: gpt-5.5
provider: openai
source_hash: a3807ccae3313a731c2673edace8a5b37dc22259d436a67b4d787e45682dad3c
source_hash: 648c1624aa81e896dacdbdc10784ca10fba2e43114823903da6455e7de512ace
source_path: reference/token-use.md
workflow: 16
---
# 词元使用与成本
# Token 使用与成本
OpenClaw 跟踪的是**词元**，不是字符。词元因模型而异，但大多数
OpenAI 风格模型处理英文文本时，平均约 4 个字符对应 1 个词元。
OpenClaw 跟踪的是 **token**，不是字符。token 因模型而异，但大多数
OpenAI 风格模型在英文文本中平均约为每个 token 4 个字符。
## 系统提示是如何构建的
## 系统提示如何构建
OpenClaw 每次运行时都会组装自己的系统提示。它包括：
OpenClaw 会在每次运行时组装自己的系统提示。它包括：
- 工具列表 + 简短说明
- Skills 列表（仅元数据；指令会按需通过 `read` 加载）。
紧凑 Skills 块受 `skills.limits.maxSkillsPromptChars` 限制，
也可以通过
`agents.list[].skillsLimits.maxSkillsPromptChars`
为每个智能体设置可选覆盖。
- 自我更新指令
- 工作区 + 引导文件（新建时包括 `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`，存在时还包括 `MEMORY.md`）。小写根目录 `memory.md` 不会被注入；当它与 `MEMORY.md` 配对时，它只是 `openclaw doctor --fix` 的旧版修复输入。大文件会按 `agents.defaults.bootstrapMaxChars` 截断（默认：12000），引导注入总量受 `agents.defaults.bootstrapTotalMaxChars` 限制（默认：60000）。`memory/*.md` 每日文件不是常规引导提示的一部分；在普通轮次中，它们仍然通过记忆工具按需使用，但重置/启动模型运行可以为第一轮预置一次性的启动上下文块，其中包含最近的每日记忆。裸聊天 `/new` 和 `/reset` 命令会在不调用模型的情况下被确认。启动前导由 `agents.defaults.startupContext` 控制。
- Skills 列表（仅元数据；说明会按需用 `read` 加载）。
紧凑的 Skills 区块受 `skills.limits.maxSkillsPromptChars` 限制，
也可以在每个智能体上通过
`agents.list[].skillsLimits.maxSkillsPromptChars` 覆盖。
- 自更新说明
- 工作区 + 引导文件（新建时的 `AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`，以及存在时的 `MEMORY.md`）。小写根目录 `memory.md` 不会注入；当它与 `MEMORY.md` 配对时，它是 `openclaw doctor --fix` 的旧版修复输入。大型文件会被 `agents.defaults.bootstrapMaxChars` 截断（默认值：12000），总引导注入量受 `agents.defaults.bootstrapTotalMaxChars` 限制（默认值：60000）。`memory/*.md` 每日文件不是普通引导提示的一部分；在普通轮次中，它们仍通过记忆工具按需使用，但重置/启动模型运行可以为第一个轮次前置一个一次性启动上下文区块，其中包含最近的每日记忆。裸聊天 `/new` 和 `/reset` 命令会被确认，而不会调用模型。启动前奏由 `agents.defaults.startupContext` 控制。
- 时间（UTC + 用户时区）
- 回复标签 + 心跳行为
- 运行时元数据（主机/OS/模型/思考）
- 回复标签 + Heartbeat 行为
- 运行时元数据（主机/操作系统/模型/思考）
完整拆解见[系统提示](/zh-CN/concepts/system-prompt)。
完整拆解见 [System Prompt](/zh-CN/concepts/system-prompt)。
## 上下文窗口中计入什么
模型收到的所有内容都会计入上下文限制：
模型收到的一切都会计入上下文限制：
- 系统提示（上面列出的所有部分）
- 对话历史（用户 + 助手消息）
- 工具调用和工具结果
- 附件/转录（图像、音频、文件）
- 压缩摘要和修剪产物
- 提供商包装层或安全标头（不可见，但仍会计入）
- 附件/转录内容（图片、音频、文件）
- 压缩摘要和剪枝产物
- 提供商包装器或安全头（不可见，但仍会计入）
一些运行时负载较重的表面有自己的显式上限：
一些运行时占用较重的表面有自己的显式上限：
- `agents.defaults.contextLimits.memoryGetMaxChars`
- `agents.defaults.contextLimits.memoryGetDefaultLines`
- `agents.defaults.contextLimits.toolResultMaxChars`
- `agents.defaults.contextLimits.postCompactionMaxChars`
每个智能体的覆盖位于 `agents.list[].contextLimits` 下。这些开关用于
有界运行时摘录和运行时拥有的注入块。它们与引导限制、启动上下文限制和 Skills 提示
限制是分开的。
每个智能体的覆盖项位于 `agents.list[].contextLimits` 下。这些旋钮用于有界运行时摘录和注入的运行时自有区块。它们与引导限制、启动上下文限制和 Skills 提示限制相互独立。
对于图像，OpenClaw 会在调用提供商前缩小转录/工具图像载荷。
使用 `agents.defaults.imageMaxDimensionPx`（默认：`1200`）调整此行为：
对于图片，OpenClaw 会在调用提供商之前缩小转录/工具图片载荷。
使用 `agents.defaults.imageMaxDimensionPx`（默认值：`1200`）来调优：
- 较低的值通常会减少视觉词元用量和载荷大小。
- 较低的值通常会减少视觉 token 用量和载荷大小。
- 较高的值会为 OCR/UI 密集型截图保留更多视觉细节。
如需实际拆解（按注入文件、工具、Skills 和系统提示大小），请使用 `/context list` 或 `/context detail`。见[上下文](/zh-CN/concepts/context)。
如需实用拆解（按注入文件、工具、Skills 和系统提示大小），请使用 `/context list` 或 `/context detail`。见 [Context](/zh-CN/concepts/context)。
## 如何查看当前词元用量
## 如何查看当前 token 用量
在聊天中使用：
在聊天中使用这些命令：
- `/status` → **富表情 Status 卡片**，包含会话模型、上下文用量、
上一次响应的输入/输出词元，以及**估算成本**（仅 API key）。
- `/usage off|tokens|full` → 为每条回复追加**逐响应用量页脚**。
- `/status` → 带有丰富表情的 **Status 卡片**，包含会话模型、上下文用量、
上一次响应的输入/输出 token，以及 **估算成本**（仅 API key）。
- `/usage off|tokens|full` → 为每次回复追加 **单响应用量页脚**。
- 按会话持久化（存储为 `responseUsage`）。
- OAuth 凭证**隐藏成本**（仅显示词元）。
- `/usage cost` → 显示来自 OpenClaw 会话日志的本地成本摘要。
- OAuth 凭证 **会隐藏成本**（仅显示 token）。
- `/usage cost` → 从 OpenClaw 会话日志显示本地成本摘要。
其他表面：
- **TUI/Web TUI：**支持 `/status` + `/usage`。
- **CLI：**`openclaw status --usage` 和 `openclaw channels list` 显示
规范化的提供商配额窗口（`X% left`，不是逐响应成本）。
- **TUI/Web TUI：** 支持 `/status` + `/usage`。
- **CLI：** `openclaw status --usage` 和 `openclaw channels list` 会显示
规范化的提供商配额窗口（`X% left`，不是单响应成本）。
当前用量窗口提供商：Anthropic、GitHub Copilot、Gemini CLI、
OpenAI Codex、MiniMax、Xiaomi 和 z.ai。
用量表面在显示前会规范化常见的提供商原生字段别名。
用量表面会在显示前规范化常见的提供商原生字段别名。
对于 OpenAI 系列 Responses 流量，这包括 `input_tokens` /
`output_tokens` 和 `prompt_tokens` / `completion_tokens`，因此传输层特定的
字段名不会改变 `/status`、`/usage` 或会话摘要。
`output_tokens` 和 `prompt_tokens` / `completion_tokens`，因此传输专用字段名不会改变 `/status`、`/usage` 或会话摘要。
Gemini CLI JSON 用量也会被规范化：回复文本来自 `response`，并且
`stats.cached` 映射到 `cacheRead`；当 CLI 省略显式 `stats.input` 字段时，
使用 `stats.input_tokens - stats.cached`。
对于原生 OpenAI 系列 Responses 流量，WebSocket/SSE 用量别名会以同样方式
规范化，并且当 `total_tokens` 缺失或为 `0` 时，总量会回退到规范化后的输入 + 输出。
当当前会话快照较稀疏时，`/status` 和 `session_status` 也可以从最近的
转录用量日志中恢复词元/缓存计数器和活跃运行时模型标签。现有非零实时值仍然
优先于转录回退值；当已存储总量缺失或更小时，面向提示的较大
转录总量可以胜出。
提供商配额窗口的用量认证在可用时来自提供商特定钩子；否则 OpenClaw 会回退到
从认证配置、环境变量或配置中匹配 OAuth/API-key 凭证。
助手转录条目会持久化相同的规范化用量形状，包括
在活跃模型已配置价格且提供商返回用量元数据时的 `usage.cost`。
这让 `/usage cost` 和基于转录的会话状态在实时运行时状态消失后仍有稳定来源。
`stats.cached` 会映射到 `cacheRead`；当 CLI 省略显式 `stats.input` 字段时，会使用 `stats.input_tokens - stats.cached`。
对于原生 OpenAI 系列 Responses 流量，WebSocket/SSE 用量别名会以相同方式规范化，并且当 `total_tokens` 缺失或为 `0` 时，总量会回退为规范化的输入 + 输出。
当当前会话快照稀疏时，`/status` 和 `session_status` 也可以从最近的转录用量日志中恢复 token/缓存计数器和活动运行时模型标签。现有的非零实时值仍优先于转录回退值，并且当已存储总量缺失或更小时，更大的、面向提示的转录总量可以胜出。
提供商配额窗口的用量凭证在可用时来自提供商特定钩子；否则，OpenClaw 会回退到从认证配置文件、环境变量或配置中匹配 OAuth/API key 凭证。
助手转录条目会持久化相同的规范化用量形状，包括当活动模型已配置价格且提供商返回用量元数据时的 `usage.cost`。即使实时运行时状态已经消失，这也会为 `/usage cost` 和基于转录的会话状态提供稳定来源。
OpenClaw 将提供商用量计量与当前上下文快照分开。提供商 `usage.total` 可以包括缓存输入、输出和多次
工具循环模型调用，因此它对成本和遥测很有用，但可能会高估
实时上下文窗口。上下文显示和诊断会使用最新的提示快照（`promptTokens`，或者在没有提示快照时使用最后一次模型调用）作为 `context.used`。
OpenClaw 将提供商用量计量与当前上下文快照分开。提供商 `usage.total` 可以包括缓存输入、输出和多个工具循环模型调用，因此它对成本和遥测有用，但可能夸大实时上下文窗口。上下文显示和诊断会使用最新提示快照（`promptTokens`，或没有提示快照时的最后一次模型调用）作为 `context.used`。
## 成本估算（显示时）
@ -116,40 +102,27 @@ OpenClaw 将提供商用量计量与当前上下文快照分开。提供商 `usa
models.providers.<provider>.models[].cost
```
这些是 `input`、`output`、`cacheRead` 和
`cacheWrite` 的**每 100 万词元美元价格**。如果缺少定价，OpenClaw 只显示词元。OAuth token
永不显示美元成本。
这些是 `input`、`output`、`cacheRead` 和 `cacheWrite` 的 **每 100 万 token 美元价格**。如果缺少定价，OpenClaw 只显示 token。OAuth token 永远不会显示美元成本。
Gateway 网关启动时还会对尚无本地定价的已配置模型引用执行可选的后台定价引导。
该引导会拉取远程 OpenRouter 和 LiteLLM 定价目录。在离线
或受限网络上，将 `models.pricing.enabled: false` 设为跳过这些启动目录拉取；显式的 `models.providers.*.models[].cost` 条目
仍会继续驱动本地成本估算。
当 sidecar 和渠道到达 Gateway 网关就绪路径后，OpenClaw 会为尚无本地定价的已配置模型引用启动可选的后台定价引导。该引导会获取远程 OpenRouter 和 LiteLLM 定价目录。在离线或受限网络中，将 `models.pricing.enabled: false` 设为跳过这些目录获取；显式
`models.providers.*.models[].cost` 条目会继续驱动本地成本估算。
## 缓存 TTL 和修剪影响
## 缓存 TTL 和剪枝影响
提供商提示缓存只在缓存 TTL 窗口内适用。OpenClaw 可以
选择性运行**缓存 TTL 修剪**：缓存 TTL 过期后修剪会话，然后重置缓存窗口，
以便后续请求可以复用新缓存的上下文，而不是重新缓存完整历史。这会在会话空闲超过 TTL 时
降低缓存写入成本。
提供商提示缓存只会在缓存 TTL 窗口内适用。OpenClaw 可以选择运行 **cache-ttl 剪枝**：它会在缓存 TTL 过期后剪枝会话，然后重置缓存窗口，这样后续请求可以复用新缓存的上下文，而不是重新缓存完整历史。当会话空闲时间超过 TTL 时，这会降低缓存写入成本。
在 [Gateway 网关配置](/zh-CN/gateway/configuration)中配置它，并在
[会话修剪](/zh-CN/concepts/session-pruning)中查看行为详情。
在 [Gateway 网关配置](/zh-CN/gateway/configuration) 中配置它，并在 [Session pruning](/zh-CN/concepts/session-pruning) 中查看行为细节。
心跳可以跨空闲间隔保持缓存**预热**。如果你的模型缓存 TTL
是 `1h`，将心跳间隔设置为略低于该值（例如 `55m`）可以避免
重新缓存完整提示，从而减少缓存写入成本。
Heartbeat 可以让缓存在空闲间隔中保持 **温热**。如果你的模型缓存 TTL 是 `1h`，将 Heartbeat 间隔设置为略低于该值（例如 `55m`）可以避免重新缓存完整提示，从而降低缓存写入成本。
在多智能体设置中，你可以保持一个共享模型配置，并用 `agents.list[].params.cacheRetention`
为每个智能体调整缓存行为。
在多智能体设置中，你可以保留一个共享模型配置，并通过 `agents.list[].params.cacheRetention` 为每个智能体调优缓存行为。
完整的逐项开关指南见[提示缓存](/zh-CN/reference/prompt-caching)。
完整逐项旋钮指南见 [Prompt Caching](/zh-CN/reference/prompt-caching)。
对于 Anthropic API 定价，缓存读取显著低于输入
词元价格，而缓存写入按更高倍数计费。最新费率和 TTL 倍数见 Anthropic 的
提示缓存定价：
对于 Anthropic API 定价，缓存读取比输入 token 便宜得多，而缓存写入会按更高倍数计费。最新费率和 TTL 倍数见 Anthropic 的提示缓存定价：
[https://docs.anthropic.com/docs/build-with-claude/prompt-caching](https://docs.anthropic.com/docs/build-with-claude/prompt-caching)
### 示例：用心跳保持 1h 缓存预热
### 示例：用 Heartbeat 保持 1 小时缓存温热
```yaml
agents:
@ -164,7 +137,7 @@ agents:
every: "55m"
```
### 示例：使用按智能体缓存策略的混合流量
### 示例：按智能体缓存策略处理混合流量
```yaml
agents:
@ -185,14 +158,11 @@ agents:
cacheRetention: "none" # avoid cache writes for bursty notifications
```
`agents.list[].params` 会合并到所选模型的 `params` 之上，因此你可以
只覆盖 `cacheRetention`，并保持其他模型默认值不变。
`agents.list[].params` 会合并到所选模型的 `params` 之上，因此你可以只覆盖 `cacheRetention`，并原样继承其他模型默认值。
### 示例：启用 Anthropic 1M 上下文 beta 标头
### 示例：启用 Anthropic 100 万上下文 beta 头
Anthropic 的 1M 上下文窗口目前受 beta 门控。OpenClaw 可以在受支持的 Opus
或 Sonnet 模型上启用 `context1m` 时注入所需的
`anthropic-beta` 值。
Anthropic 的 100 万上下文窗口目前受 beta 门控。OpenClaw 可以在受支持的 Opus 或 Sonnet 模型上启用 `context1m` 时，注入所需的 `anthropic-beta` 值。
```yaml
agents:
@ -203,26 +173,23 @@ agents:
context1m: true
```
这会映射到 Anthropic 的 `context-1m-2025-08-07` beta 标头。
这会映射到 Anthropic 的 `context-1m-2025-08-07` beta 头。
这仅在该模型条目上设置了 `context1m: true` 时适用。
这只会在该模型条目上设置了 `context1m: true` 时适用。
要求：凭证必须有资格使用长上下文。如果没有，
Anthropic 会对该请求返回提供商侧速率限制错误。
要求：凭证必须有资格使用长上下文。否则，Anthropic 会针对该请求返回提供商侧速率限制错误。
如果你使用 OAuth/订阅 token（`sk-ant-oat-*`）认证 Anthropic，
OpenClaw 会跳过 `context-1m-*` beta 标头，因为 Anthropic 当前
会以 HTTP 401 拒绝该组合。
如果你使用 OAuth/订阅 token（`sk-ant-oat-*`）认证 Anthropic，OpenClaw 会跳过 `context-1m-*` beta 头，因为 Anthropic 目前会以 HTTP 401 拒绝该组合。
## 降低词元压力的提示
## 降低 token 压力的提示
- 使用 `/compact` 总结长会话。
- 在你的工作流中裁剪大型工具输出。
- 对截图密集型会话降低 `agents.defaults.imageMaxDimensionPx`。
- 保持技能描述简短（技能列表会注入到提示中）。
- 对冗长的探索性工作优先使用较小模型。
- 在你的工作流中修剪大型工具输出。
- 对截图密集型会话，降低 `agents.defaults.imageMaxDimensionPx`。
- 保持 Skills 说明简短（Skills 列表会注入提示）。
- 对冗长的探索性工作，优先使用更小的模型。
精确的技能列表开销公式见 [Skills](/zh-CN/tools/skills)。
精确的 Skills 列表开销公式见 [Skills](/zh-CN/tools/skills)。
## 相关