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

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-29 11:01:02 +00:00
parent 0a238ec9a6
commit 3ec49a7a87
7 changed files with 508 additions and 490 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
docs/zh-CN/auth-credential-semantics.md
View File

@ -1,26 +1,26 @@
---
read_when:
- 处理认证配置文件解析或凭证路由时
- 调试模型认证失败或配置文件顺序时
summary: 认证配置文件的规范凭证资格与解析语义
title: 凭证认证语义
- 处理认证配置文件解析或凭据路由
- 调试模型凭证失败或配置文件顺序
summary: 认证配置文件的规范凭证适用性与解析语义
title: 身份验证凭据语义
x-i18n:
generated_at: "2026-04-27T07:11:15Z"
model: gpt-5.4
generated_at: "2026-04-29T10:59:48Z"
model: gpt-5.5
provider: openai
source_hash: a1172a87053986567ac6051afe99946a9d36e1e838ce693cd56d56e71242d679
source_hash: 1f235d0c43a6cb38edf76762d530c2316ff62dfa16204875b80704b58324c176
source_path: auth-credential-semantics.md
workflow: 15
workflow: 16
---
本文档定义了以下各处使用的规范凭证资格与解析语义：
本文档定义了在以下场景中使用的规范凭证资格判定和解析语义：
- `resolveAuthProfileOrder`
- `resolveApiKeyForProfile`
- `models status --probe`
- `doctor-auth`
目标是保持选择时行为与运行时行为一致。
目标是保持选择时行为和运行时行为一致。
## 稳定的探测原因代码
@ -36,47 +36,60 @@ x-i18n:
令牌凭证（`type: "token"`）支持内联 `token` 和/或 `tokenRef`。
### 资格规则
### 资格判定规则
1. 当 `token` 和 `tokenRef` 都不存在时，令牌配置文件不具备资格。
1. 当 `token` 和 `tokenRef` 都不存在时，令牌配置文件不符合资格。
2. `expires` 是可选的。
3. 如果存在 `expires`，它必须是大于 `0` 的有限数字。
4. 如果 `expires` 无效（`NaN`、`0`、负数、非有限值或类型错误），则该配置文件不具备资格，原因为 `invalid_expires`。
5. 如果 `expires` 已过期，则该配置文件不具备资格，原因为 `expired`。
6. `tokenRef` 不会绕过 `expires` 验证。
4. 如果 `expires` 无效（`NaN`、`0`、负数、非有限值或类型错误），该配置文件不符合资格，原因是 `invalid_expires`。
5. 如果 `expires` 已过期，该配置文件不符合资格，原因是 `expired`。
6. `tokenRef` 不会绕过 `expires` 校验。
### 解析规则
1. 解析器对 `expires` 的语义与资格语义一致。
2. 对于具备资格的配置文件，令牌内容可以从内联值或 `tokenRef` 解析得到。
1. 解析器语义与 `expires` 的资格判定语义一致。
2. 对于符合资格的配置文件，令牌材料可以从内联值或 `tokenRef` 解析。
3. 无法解析的引用会在 `models status --probe` 输出中产生 `unresolved_ref`。
## 显式认证顺序过滤
## 智能体复制可移植性
- 当为某个提供商设置了 `auth.order.<provider>` 或认证存储顺序覆盖时，`models status --probe` 只会探测该提供商已解析认证顺序中仍然保留的配置文件 id。
- 某个提供商的已存储配置文件如果被显式顺序省略，不会在之后被悄悄尝试。探测输出会将其报告为 `reasonCode: excluded_by_auth_order`，详情为 `Excluded by auth.order for this provider.`
智能体凭证继承是透传读取的。当智能体没有本地配置文件时，它可以在运行时从默认/主智能体存储解析配置文件，而无需将秘密材料复制到自己的 `auth-profiles.json` 中。
显式复制流程（例如 `openclaw agents add`）使用此可移植性策略：
- `api_key` 配置文件默认可移植，除非 `copyToAgents: false`。
- `token` 配置文件默认可移植，除非 `copyToAgents: false`。
- `oauth` 配置文件默认不可移植，因为刷新令牌可能是一次性使用或对轮换敏感的。
- 提供商拥有的 OAuth 流程仅在已知跨智能体复制刷新材料安全时，才可以通过 `copyToAgents: true` 选择启用。
不可移植的配置文件仍可通过透传读取继承使用，除非目标智能体单独登录并创建自己的本地配置文件。
## 显式凭证顺序过滤
- 当为某个提供商设置了 `auth.order.<provider>` 或认证存储顺序覆盖时，`models status --probe` 只会探测仍保留在该提供商已解析凭证顺序中的配置文件 ID。
- 该提供商的已存储配置文件如果被显式顺序省略，之后不会被静默尝试。探测输出会用 `reasonCode: excluded_by_auth_order` 报告它，并附带详情 `Excluded by auth.order for this provider.`
## 探测目标解析
- 探测目标可以来自认证配置文件、环境变量凭证或 `models.json`。
- 如果某个提供商具有凭证，但 OpenClaw 无法为其解析出可探测的模型候选项，则 `models status --probe` 会报告 `status: no_model` 和 `reasonCode: no_model`。
- 探测目标可以来自凭证配置文件、环境凭证或 `models.json`。
- 如果某个提供商有凭证，但 OpenClaw 无法为其解析可探测的模型候选项，`models status --probe` 会报告 `status: no_model`，并附带 `reasonCode: no_model`。
## OAuth SecretRef 策略保护
- SecretRef 输入仅用于静态凭证。
- 如果某个配置文件凭证的 `type` 为 `oauth`，则该配置文件凭证材料不支持 SecretRef 对象。
- 如果 `auth.profiles.<id>.mode` 为 `"oauth"`，则会拒绝该配置文件的 `keyRef`/`tokenRef` SecretRef 支持输入。
- 违规会在启动/重载认证解析路径中导致硬失败。
- 如果配置文件凭证是 `type: "oauth"`，则该配置文件凭证材料不支持 SecretRef 对象。
- 如果 `auth.profiles.<id>.mode` 是 `"oauth"`，则会拒绝该配置文件使用由 SecretRef 支持的 `keyRef`/`tokenRef` 输入。
- 违规会导致启动/重载凭证解析路径中的硬失败。
## 兼容旧版的消息提示
## 旧版兼容消息
为保持脚本兼容性，探测错误会保持以下首行不变：
为保持脚本兼容性，探测错误会保持此首行不变：
`Auth profile credentials are missing or expired.`
可以在后续行中添加更适合人类阅读的详情和稳定原因代码。
后续行可能会添加更便于人类阅读的详情和稳定的原因代码。
## 相关内容
- [Secrets 管理](/zh-CN/gateway/secrets)
- [认证存储](/zh-CN/concepts/oauth)
- [密钥管理](/zh-CN/gateway/secrets)
- [凭证存储](/zh-CN/concepts/oauth)

271
docs/zh-CN/channels/whatsapp.md
View File

@ -1,43 +1,43 @@
---
read_when:
- 处理 WhatsApp/网页渠道行为或收件箱路由
summary: WhatsApp 渠道支持、访问控制、送达行为和运维
summary: WhatsApp 渠道支持、访问控制、投递行为和运维
title: WhatsApp
x-i18n:
generated_at: "2026-04-29T05:38:54Z"
generated_at: "2026-04-29T10:59:36Z"
model: gpt-5.5
provider: openai
source_hash: 9057208c69d125aea8d063f7c16c98babbf70ded7f693bdb15cde159c4920019
source_hash: f5acfebb37e16c4a3602ead7c9a4f2e16315d07612dc1e929f30fb7b1bc37761
source_path: channels/whatsapp.md
workflow: 16
---
Status：已通过 WhatsApp Web（Baileys）达到生产就绪。Gateway 网关拥有已关联会话。
Status: 可通过 WhatsApp Web（Baileys）投入生产使用。Gateway 网关拥有已关联的会话。
## 安装（按需）
- 新手引导（`openclaw onboard`）和 `openclaw channels add --channel whatsapp`
会在你首次选择 WhatsApp 插件时提示安装。
- 当插件尚未存在时，`openclaw channels login --channel whatsapp` 也会提供安装流程。
- 开发渠道 + git checkout：默认使用本地插件路径。
- Dev 渠道 + git checkout：默认使用本地插件路径。
- Stable/Beta：当当前软件包已发布时，使用 npm 包 `@openclaw/whatsapp`。
仍然可以手动安装：
仍可手动安装：
```bash
openclaw plugins install @openclaw/whatsapp
```
如果 npm 报告 OpenClaw 拥有的软件包已弃用或缺失，请使用当前打包的 OpenClaw 构建或本地 checkout，直到 npm 包发布链路跟上。
如果 npm 报告 OpenClaw 拥有的软件包已弃用或缺失，请使用当前打包的 OpenClaw 构建，或使用本地 checkout，直到 npm 包发布节奏跟上。
<CardGroup cols={3}>
<Card title="配对" icon="link" href="/zh-CN/channels/pairing">
<Card title="Pairing" icon="link" href="/zh-CN/channels/pairing">
未知发送者的默认私信策略是配对。
</Card>
<Card title="渠道故障排除" icon="wrench" href="/zh-CN/channels/troubleshooting">
<Card title="Channel troubleshooting" icon="wrench" href="/zh-CN/channels/troubleshooting">
跨渠道诊断和修复手册。
</Card>
<Card title="Gateway 网关配置" icon="settings" href="/zh-CN/gateway/configuration">
<Card title="Gateway configuration" icon="settings" href="/zh-CN/gateway/configuration">
完整的渠道配置模式和示例。
</Card>
</CardGroup>
@ -45,7 +45,7 @@ openclaw plugins install @openclaw/whatsapp
## 快速设置
<Steps>
<Step title="配置 WhatsApp 访问策略">
<Step title="Configure WhatsApp access policy">
```json5
{
@ -62,7 +62,7 @@ openclaw plugins install @openclaw/whatsapp
</Step>
<Step title="关联 WhatsApp（二维码）">
<Step title="Link WhatsApp (QR)">
```bash
openclaw channels login --channel whatsapp
@ -74,7 +74,7 @@ openclaw channels login --channel whatsapp
openclaw channels login --channel whatsapp --account work
```
若要在登录前附加现有/自定义 WhatsApp Web 认证目录：
如需在登录前附加现有/自定义 WhatsApp Web 凭证目录：
```bash
openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth
@ -83,7 +83,7 @@ openclaw channels login --channel whatsapp --account work
</Step>
<Step title="启动 Gateway 网关">
<Step title="Start the gateway">
```bash
openclaw gateway
@ -91,31 +91,31 @@ openclaw gateway
</Step>
<Step title="批准第一个配对请求（如果使用配对模式）">
<Step title="Approve first pairing request (if using pairing mode)">
```bash
openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>
```
配对请求会在 1 小时后过期。每个渠道的待处理请求上限为 3 个。
配对请求会在 1 小时后过期。每个渠道最多保留 3 个待处理请求。
</Step>
</Steps>
<Note>
OpenClaw 建议在可能时使用单独号码运行 WhatsApp。（渠道元数据和设置流程针对这种设置进行了优化，但也支持个人号码设置。）
OpenClaw 建议尽可能在单独号码上运行 WhatsApp。（渠道元数据和设置流程针对这种设置进行了优化，但也支持个人号码设置。）
</Note>
## 部署模式
<AccordionGroup>
<Accordion title="专用号码（推荐）">
<Accordion title="Dedicated number (recommended)">
这是最清晰的运维模式：
- 为 OpenClaw 使用单独的 WhatsApp 身份
- 更清晰的私信 allowlist 和路由边界
- 更低的自聊混淆概率
- 降低自聊混淆的可能性
最小策略模式：
@ -132,8 +132,8 @@ OpenClaw 建议在可能时使用单独号码运行 WhatsApp。（渠道元数
</Accordion>
<Accordion title="个人号码备用方案">
新手引导支持个人号码模式，并会写入适合自聊的基线：
<Accordion title="Personal-number fallback">
新手引导支持个人号码模式，并写入适合自聊的基线：
- `dmPolicy: "allowlist"`
- `allowFrom` 包含你的个人号码
@ -143,7 +143,7 @@ OpenClaw 建议在可能时使用单独号码运行 WhatsApp。（渠道元数
</Accordion>
<Accordion title="仅限 WhatsApp Web 的渠道范围">
<Accordion title="WhatsApp Web-only channel scope">
在当前 OpenClaw 渠道架构中，消息平台渠道基于 WhatsApp Web（`Baileys`）。
内置聊天渠道注册表中没有单独的 Twilio WhatsApp 消息渠道。
@ -153,20 +153,22 @@ OpenClaw 建议在可能时使用单独号码运行 WhatsApp。（渠道元数
## 运行时模型
- Gateway 网关拥有 WhatsApp socket 和重连循环。
- 重连 watchdog 使用 WhatsApp Web 传输活动，而不仅是入站应用消息量，因此安静的已关联设备会话不会仅因为最近没人发送消息而被重启。如果传输帧持续到达，但在 watchdog 窗口内没有处理任何应用消息，较长的应用静默上限仍会强制重连。
- Baileys socket 计时在 `web.whatsapp.*` 下显式配置：`keepAliveIntervalMs` 控制 WhatsApp Web 应用 ping，`connectTimeoutMs` 控制开启握手超时，`defaultQueryTimeoutMs` 控制 Baileys 查询超时。
- 出站发送需要目标账户有活跃的 WhatsApp 监听器。
- Gateway 网关拥有 WhatsApp 套接字和重连循环。
- 重连看门狗使用 WhatsApp Web 传输活动，而不仅是入站应用消息数量，因此安静的已关联设备会话不会仅仅因为最近没人发送消息而被重启。如果传输帧持续到达但在看门狗窗口内没有处理任何应用消息，较长的应用静默上限仍会强制重连；对于最近活跃会话的临时重连之后，该应用静默检查会在首个恢复窗口使用常规消息超时。
- Baileys 套接字时序在 `web.whatsapp.*` 下显式配置：`keepAliveIntervalMs` 控制 WhatsApp Web 应用 ping，`connectTimeoutMs` 控制开启握手超时，`defaultQueryTimeoutMs` 控制 Baileys 查询超时。
- 出站发送要求目标账户有活跃的 WhatsApp 监听器。
- Status 和广播聊天会被忽略（`@status`、`@broadcast`）。
- 重连 watchdog 跟随 WhatsApp Web 传输活动，而不仅是入站应用消息量：只要传输帧持续，安静的已关联设备会话就会保持在线，但传输停滞会在更晚的远端断开路径之前强制重连。
- 重连看门狗跟随 WhatsApp Web 传输活动，而不仅是入站应用消息数量：只要传输帧持续，安静的已关联设备会话就会保持在线，但传输停滞会在较晚的远端断开路径之前强制重连。
- 直接聊天使用私信会话规则（`session.dmScope`；默认 `main` 会将私信折叠到智能体主会话）。
- 群组会话隔离（`agent:<agentId>:whatsapp:group:<jid>`）。
- 群组会话是隔离的（`agent:<agentId>:whatsapp:group:<jid>`）。
- WhatsApp Web 传输遵循 Gateway 网关主机上的标准代理环境变量（`HTTPS_PROXY`、`HTTP_PROXY`、`NO_PROXY` / 小写变体）。优先使用主机级代理配置，而不是渠道特定的 WhatsApp 代理设置。
- 启用 `messages.removeAckAfterReply` 时，OpenClaw 会在可见回复送达后清除 WhatsApp ack reaction。
- 启用 `messages.removeAckAfterReply` 后，OpenClaw 会在可见回复送达后清除 WhatsApp 确认反应。
## 插件钩子和隐私
WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标识符、发送者姓名和会话关联字段。因此，除非你显式选择启用，否则 WhatsApp 不会向插件广播入站 `message_received` 钩子 payload：
WhatsApp 入站消息可能包含个人消息内容、电话号码、
群组标识符、发送者姓名和会话关联字段。因此，
除非你显式选择加入，否则 WhatsApp 不会向插件广播入站 `message_received` 钩子载荷：
```json5
{
@ -180,7 +182,7 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标
}
```
你可以将选择启用限定到一个账户：
你可以将选择加入限定到一个账户：
```json5
{
@ -198,12 +200,12 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标
}
```
只对你信任、可接收入站 WhatsApp 消息内容和标识符的插件启用此选项。
仅为你信任可接收入站 WhatsApp 消息内容和标识符的插件启用此选项。
## 访问控制和激活
<Tabs>
<Tab title="私信策略">
<Tab title="DM policy">
`channels.whatsapp.dmPolicy` 控制直接聊天访问：
- `pairing`（默认）
@ -211,60 +213,60 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标
- `open`（要求 `allowFrom` 包含 `"*"`）
- `disabled`
`allowFrom` 接受 E.164 风格号码（内部会规范化）。
`allowFrom` 接受 E.164 风格的号码（内部会规范化）。
多账户覆盖：`channels.whatsapp.accounts.<id>.dmPolicy`（以及 `allowFrom`）优先于该账户的渠道级默认值。
运行时行为详情：
- 配对会持久化到渠道 allow-store，并与已配置的 `allowFrom` 合并
- 配对会持久化到渠道允许存储中，并与配置的 `allowFrom` 合并
- 如果未配置 allowlist，则默认允许已关联的自身号码
- OpenClaw 绝不会自动配对出站 `fromMe` 私信（你从已关联设备发送给自己的消息）
- OpenClaw 从不自动配对出站 `fromMe` 私信（你从已关联设备发给自己的消息）
</Tab>
<Tab title="群组策略 + allowlists">
<Tab title="Group policy + allowlists">
群组访问有两层：
1. **群组成员 allowlist**（`channels.whatsapp.groups`）
- 如果省略 `groups`，则所有群组都符合条件
- 如果省略 `groups`，所有群组都符合条件
- 如果存在 `groups`，它会作为群组 allowlist（允许 `"*"`）
2. **群组发送者策略**（`channels.whatsapp.groupPolicy` + `groupAllowFrom`）
- `open`：绕过发送者 allowlist
- `allowlist`：发送者必须匹配 `groupAllowFrom`（或 `*`）
- `disabled`：阻止所有群组入站
- `disabled`：阻止所有群组入站消息
发送者 allowlist 备用逻辑：
发送者 allowlist 回退：
- 如果未设置 `groupAllowFrom`，运行时会在可用时回退到 `allowFrom`
- 发送者 allowlist 会在提及/回复激活前评估
- 发送者 allowlist 会在提及/回复激活前求值
注意：如果完全不存在 `channels.whatsapp` 块，则运行时群组策略备用值是 `allowlist`（并记录警告日志），即使设置了 `channels.defaults.groupPolicy` 也是如此。
注意：如果完全没有 `channels.whatsapp` 块，即使设置了 `channels.defaults.groupPolicy`，运行时群组策略回退也是 `allowlist`（并记录警告日志）。
</Tab>
<Tab title="提及 + /activation">
<Tab title="Mentions + /activation">
默认情况下，群组回复需要提及。
提及检测包括：
- 显式提及 bot 身份的 WhatsApp mention
- 已配置的提及正则模式（`agents.list[].groupChat.mentionPatterns`，备用 `messages.groupChat.mentionPatterns`）
- 已授权群组消息的入站语音便笺转录
- 隐式回复 bot 检测（回复发送者匹配 bot 身份）
- 对机器人身份的显式 WhatsApp 提及
- 配置的提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`）
- 授权群组消息的入站语音备注转录
- 隐式回复机器人检测（回复发送者匹配机器人身份）
安全说明：
- quote/reply 只满足提及门控；它**不会**授予发送者授权
- 使用 `groupPolicy: "allowlist"` 时，非 allowlisted 发送者仍会被阻止，即使他们回复的是 allowlisted 用户的消息
- 引用/回复只满足提及门控；它**不会**授予发送者授权
- 使用 `groupPolicy: "allowlist"` 时，即使非 allowlist 发送者回复 allowlist 用户的消息，仍会被阻止
会话级激活命令：
- `/activation mention`
- `/activation always`
`activation` 会更新会话状态（不是全局配置）。它受 owner 门控。
`activation` 会更新会话状态（不是全局配置）。它受所有者门控。
</Tab>
</Tabs>
@ -274,14 +276,14 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标
当已关联的自身号码也存在于 `allowFrom` 中时，WhatsApp 自聊保护会激活：
- 跳过自聊轮次的已读回执
- 忽略原本会 ping 你自己的 mention-JID 自动触发行为
- 忽略否则会 ping 你自己的 mention-JID 自动触发行为
- 如果未设置 `messages.responsePrefix`，自聊回复默认使用 `[{identity.name}]` 或 `[openclaw]`
## 消息规范化和上下文
<AccordionGroup>
<Accordion title="入站信封 + 回复上下文">
入站 WhatsApp 消息会包装在共享入站信封中。
<Accordion title="Inbound envelope + reply context">
传入 WhatsApp 消息会封装在共享入站信封中。
如果存在引用回复，上下文会以这种形式追加：
@ -291,12 +293,12 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标
[/Replying]
```
可用时也会填充回复元数据字段（`ReplyToId`、`ReplyToBody`、`ReplyToSender`、发送者 JID/E.164）。
可用时，也会填充回复元数据字段（`ReplyToId`、`ReplyToBody`、`ReplyToSender`、发送者 JID/E.164）。
</Accordion>
<Accordion title="媒体占位符和位置/联系人提取">
仅媒体的入站消息会规范化为如下占位符：
<Accordion title="Media placeholders and location/contact extraction">
仅媒体的入站消息会使用如下占位符规范化：
- `<media:image>`
- `<media:video>`
@ -304,18 +306,19 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标
- `<media:document>`
- `<media:sticker>`
当正文只有 `<media:audio>` 时，已授权的群组语音便笺会在提及门控前转录，因此在语音便笺中说出 bot mention 可以触发回复。如果转录文本仍未提及 bot，转录文本会保留在待处理群组历史中，而不是保留原始占位符。
授权群组语音备注会在提及门控前转录，前提是正文只有 `<media:audio>`，因此在语音备注中说出机器人提及可以触发回复。如果转录仍未提及机器人，
转录会保留在待处理群组历史中，而不是原始占位符。
位置正文使用简短坐标文本。位置标签/评论和联系人/vCard 详情会呈现为 fenced untrusted metadata，而不是内联 prompt 文本。
位置正文使用简短坐标文本。位置标签/评论和联系人/vCard 详情会呈现为围栏式不可信元数据，而不是内联提示文本。
</Accordion>
<Accordion title="待处理群组历史注入">
对于群组，未处理消息可以被缓冲，并在 bot 最终被触发时作为上下文注入。
<Accordion title="Pending group history injection">
对于群组，未处理的消息可以被缓冲，并在机器人最终被触发时作为上下文注入。
- 默认限制：`50`
- 配置：`channels.whatsapp.historyLimit`
- 备用：`messages.groupChat.historyLimit`
- 回退：`messages.groupChat.historyLimit`
- `0` 禁用
注入标记：
@ -325,8 +328,8 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标
</Accordion>
<Accordion title="已读回执">
对已接受的入站 WhatsApp 消息，默认启用已读回执。
<Accordion title="Read receipts">
对于已接受的入站 WhatsApp 消息，默认启用已读回执。
全局禁用：
@ -364,7 +367,7 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标
## 送达、分块和媒体
<AccordionGroup>
<Accordion title="文本分块">
<Accordion title="Text chunking">
- 默认分块限制：`channels.whatsapp.textChunkLimit = 4000`
- `channels.whatsapp.chunkMode = "length" | "newline"`
- `newline` 模式优先使用段落边界（空行），然后回退到长度安全的分块
@ -372,14 +375,14 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标
</Accordion>
<Accordion title="出站媒体行为">
- 支持图片、视频、音频（PTT 语音便笺）和文档载荷
- 音频媒体会通过 Baileys `audio` 载荷并带上 `ptt: true` 发送，因此 WhatsApp 客户端会将其渲染为一条按住说话语音便笺
- 回复载荷会保留 `audioAsVoice`；即使提供商返回 MP3 或 WebM，WhatsApp 的 TTS 语音便笺输出仍会走这条 PTT 路径
- 原生 Ogg/Opus 音频会作为 `audio/ogg; codecs=opus` 发送，以兼容语音便笺
- 非 Ogg 音频（包括 Microsoft Edge TTS 的 MP3/WebM 输出）会先用 `ffmpeg` 转码为 48 kHz 单声道 Ogg/Opus，再进行 PTT 投递
- `/tts latest` 会把最新的助手回复作为一条语音便笺发送，并抑制同一条回复的重复发送；`/tts chat on|off|default` 控制当前 WhatsApp 聊天的自动 TTS
- 支持图片、视频、音频（PTT 语音消息）和文档载荷
- 音频媒体会通过 Baileys `audio` 载荷并带 `ptt: true` 发送，因此 WhatsApp 客户端会将其渲染为按键说话语音消息
- 回复载荷会保留 `audioAsVoice`；WhatsApp 的 TTS 语音消息输出会继续使用这条 PTT 路径，即使提供商返回 MP3 或 WebM
- 原生 Ogg/Opus 音频会以 `audio/ogg; codecs=opus` 发送，以兼容语音消息
- 非 Ogg 音频（包括 Microsoft Edge TTS 的 MP3/WebM 输出）会先用 `ffmpeg` 转码为 48 kHz 单声道 Ogg/Opus，再通过 PTT 发送
- `/tts latest` 会把最新的助手回复作为一条语音消息发送，并阻止同一条回复重复发送；`/tts chat on|off|default` 控制当前 WhatsApp 聊天的自动 TTS
- 通过视频发送中的 `gifPlayback: true` 支持动画 GIF 播放
- 发送多媒体回复载荷时，说明文字会应用到第一个媒体项；但 PTT 语音便笺会先发送音频，再单独发送可见文本，因为 WhatsApp 客户端不会稳定渲染语音便笺说明文字
- 发送多媒体回复载荷时，说明文字会应用到第一个媒体项；但 PTT 语音消息会先发送音频，再单独发送可见文本，因为 WhatsApp 客户端不会一致地渲染语音消息说明文字
- 媒体来源可以是 HTTP(S)、`file://` 或本地路径
</Accordion>
@ -387,8 +390,8 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标
<Accordion title="媒体大小限制和回退行为">
- 入站媒体保存上限：`channels.whatsapp.mediaMaxMb`（默认 `50`）
- 出站媒体发送上限：`channels.whatsapp.mediaMaxMb`（默认 `50`）
- 每账号覆盖使用 `channels.whatsapp.accounts.<accountId>.mediaMaxMb`
- 图片会自动优化（调整大小/质量扫描）以符合限制
- 按账号覆盖使用 `channels.whatsapp.accounts.<accountId>.mediaMaxMb`
- 图片会自动优化（调整尺寸/质量扫描）以符合限制
- 媒体发送失败时，首项回退会发送文本警告，而不是静默丢弃响应
</Accordion>
@ -396,7 +399,7 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标
## 错误可见性
`channels.whatsapp.exposeErrorText` 控制是否将智能体/提供商错误文本回传到 WhatsApp。默认值为 `true`。将其设为 `false` 可让 WhatsApp 上的失败保持静默，同时保留其他渠道行为。
`channels.whatsapp.exposeErrorText` 控制是否将智能体/提供商错误文本送回 WhatsApp。默认值为 `true`。将其设为 `false` 可以让 WhatsApp 上的失败保持静默，同时保留其他渠道行为。
```json5
{
@ -408,20 +411,20 @@ WhatsApp 入站消息可能包含个人消息内容、电话号码、群组标
}
```
每账号覆盖使用 `channels.whatsapp.accounts.<id>.exposeErrorText`。
按账号覆盖使用 `channels.whatsapp.accounts.<id>.exposeErrorText`。
## 回复引用
WhatsApp 支持原生回复引用，即出站回复会可见地引用入站消息。用 `channels.whatsapp.replyToMode` 控制。
WhatsApp 支持原生回复引用，即出站回复会可见地引用入站消息。使用 `channels.whatsapp.replyToMode` 控制。
| 值 | 行为 |
| ----------- | ------------------------------------------------------ |
| `"off"` | 从不引用；作为普通消息发送 |
| `"first"` | 仅引用第一个出站回复分块 |
| `"all"` | 引用每个出站回复分块 |
| `"batched"` | 引用排队的批量回复，同时让即时回复不带引用 |
| 值 | 行为 |
| ----------- | ---------------------------------------------------------------- |
| `"off"` | 永不引用；作为普通消息发送 |
| `"first"` | 仅引用第一个出站回复片段 |
| `"all"` | 引用每个出站回复片段 |
| `"batched"` | 引用已排队的批量回复，同时让即时回复不带引用 |
默认值为 `"off"`。每账号覆盖使用 `channels.whatsapp.accounts.<id>.replyToMode`。
默认值为 `"off"`。按账号覆盖使用 `channels.whatsapp.accounts.<id>.replyToMode`。
```json5
{
@ -433,20 +436,20 @@ WhatsApp 支持原生回复引用，即出站回复会可见地引用入站消
}
```
## 表情回应级别
## 反应级别
`channels.whatsapp.reactionLevel` 控制智能体在 WhatsApp 上使用表情回应的范围：
`channels.whatsapp.reactionLevel` 控制智能体在 WhatsApp 上使用表情反应的范围：
| 级别 | 确认回应 | 智能体发起的回应 | 描述 |
| 级别 | 确认反应 | 智能体发起的反应 | 描述 |
| ------------- | -------- | ---------------- | ---------------------------------- |
| `"off"` | 否 | 否 | 完全不使用回应 |
| `"ack"` | 是 | 否 | 仅确认回应（回复前回执） |
| `"minimal"` | 是 | 是（保守） | 确认 + 带保守指引的智能体回应 |
| `"extensive"` | 是 | 是（鼓励） | 确认 + 带鼓励指引的智能体回应 |
| `"off"` | 否 | 否 | 完全不使用反应 |
| `"ack"` | 是 | 否 | 仅确认反应（回复前回执） |
| `"minimal"` | 是 | 是（保守） | 确认 + 带保守指引的智能体反应 |
| `"extensive"` | 是 | 是（鼓励） | 确认 + 带鼓励指引的智能体反应 |
默认值：`"minimal"`。
每账号覆盖使用 `channels.whatsapp.accounts.<id>.reactionLevel`。
按账号覆盖使用 `channels.whatsapp.accounts.<id>.reactionLevel`。
```json5
{
@ -458,10 +461,10 @@ WhatsApp 支持原生回复引用，即出站回复会可见地引用入站消
}
```
## 确认回应
## 确认反应
WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时立即发送确认回应。
确认回应受 `reactionLevel` 控制 —— 当 `reactionLevel` 为 `"off"` 时会被抑制。
WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时立即发送确认反应。
确认反应受 `reactionLevel` 限制，当 `reactionLevel` 为 `"off"` 时会被抑制。
```json5
{
@ -479,40 +482,40 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时
行为说明：
- 入站消息被接受后立即发送（回复前）
- 失败会记录日志，但不会阻止正常回复投递
- group 模式 `mentions` 会在由提及触发的轮次中回应；group 激活 `always` 会作为此检查的绕过
- WhatsApp 使用 `channels.whatsapp.ackReaction`（这里不使用旧版 `messages.ackReaction`）
- 在入站消息被接受后立即发送（回复前）
- 失败会被记录，但不会阻止正常回复送达
- 群组模式 `mentions` 会在由提及触发的轮次中作出反应；群组激活 `always` 会作为此检查的绕过条件
- WhatsApp 使用 `channels.whatsapp.ackReaction`（此处不使用旧版 `messages.ackReaction`）
## 多账号和凭证
## 多账号和凭据
<AccordionGroup>
<Accordion title="账号选择和默认值">
- 账号 ID 来自 `channels.whatsapp.accounts`
- 默认账号选择：如果存在则使用 `default`，否则使用第一个已配置账号 ID（排序后）
- 账号 ID 会在内部规范化后用于查找
- 默认账号选择：如果存在 `default`，则使用它；否则使用第一个已配置账号 ID（排序后）
- 账号 ID 会在内部规范化以便查找
</Accordion>
<Accordion title="凭证路径和旧版兼容性">
<Accordion title="凭据路径和旧版兼容性">
- 当前认证路径：`~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
- 备份文件：`creds.json.bak`
- `~/.openclaw/credentials/` 中的旧版默认认证仍会在默认账号流程中被识别/迁移
- 仍会识别/迁移 `~/.openclaw/credentials/` 中的旧版默认认证，用于默认账号流程
</Accordion>
<Accordion title="登出行为">
`openclaw channels logout --channel whatsapp [--account <id>]` 会清除该账号的 WhatsApp 认证状态。
在旧版认证目录中，`oauth.json` 会保留，同时移除 Baileys 认证文件。
在旧版认证目录中，`oauth.json` 会被保留，而 Baileys 认证文件会被删除。
</Accordion>
</AccordionGroup>
## 工具、操作和配置写入
- 智能体工具支持包括 WhatsApp 表情回应操作（`react`）。
- 操作门控：
- 智能体工具支持包括 WhatsApp 反应操作（`react`）。
- 操作开关：
- `channels.whatsapp.actions.reactions`
- `channels.whatsapp.actions.polls`
- 渠道发起的配置写入默认启用（可通过 `channels.whatsapp.configWrites=false` 禁用）。
@ -520,8 +523,8 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时
## 故障排除
<AccordionGroup>
<Accordion title="未关联（需要 QR）">
症状：渠道 Status 报告未关联。
<Accordion title="未链接（需要 QR）">
症状：渠道状态报告未链接。
修复：
@ -532,12 +535,12 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时
</Accordion>
<Accordion title="已关联但断开连接 / 重连循环">
症状：已关联账号反复断开连接或尝试重连。
<Accordion title="已链接但已断开 / 重连循环">
症状：已链接账号反复断开连接或尝试重连。
安静账号可以在正常消息超时后继续保持连接；当 WhatsApp Web 传输活动停止、套接字关闭，或应用层活动在更长的安全窗口内持续静默时，看门狗会重启。
安静账号可以在正常消息超时后仍保持连接；当 WhatsApp Web 传输活动停止、套接字关闭，或应用级活动在更长的安全窗口之外持续静默时，看门狗会重启。
如果日志显示重复的 `status=408 Request Time-out Connection was lost`，请调优 `web.whatsapp` 下的 Baileys 套接字时序。先将 `keepAliveIntervalMs` 缩短到低于你的网络空闲超时，并在慢速或有丢包的链路上增大 `connectTimeoutMs`：
如果日志显示重复的 `status=408 Request Time-out Connection was lost`，请调整 `web.whatsapp` 下的 Baileys 套接字时序。先将 `keepAliveIntervalMs` 缩短到低于你的网络空闲超时时间，并在缓慢或丢包链路上增大 `connectTimeoutMs`：
```json5
{
@ -558,26 +561,26 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时
openclaw logs --follow
```
如有需要，使用 `channels login` 重新关联。
如有需要，使用 `channels login` 重新链接。
</Accordion>
<Accordion title="代理后面的 QR 登录超时">
症状：`openclaw channels login --channel whatsapp` 在显示可用 QR 码之前失败，并出现 `status=408 Request Time-out` 或 TLS 套接字断开。
WhatsApp Web 登录使用 Gateway 网关主机的标准代理环境（`HTTPS_PROXY`、`HTTP_PROXY`、小写变体以及 `NO_PROXY`）。确认 Gateway 网关进程继承了代理环境变量，并且 `NO_PROXY` 不匹配 `mmg.whatsapp.net`。
WhatsApp Web 登录使用 Gateway 网关主机的标准代理环境（`HTTPS_PROXY`、`HTTP_PROXY`、小写变体和 `NO_PROXY`）。确认 Gateway 网关进程继承了代理环境变量，并且 `NO_PROXY` 不匹配 `mmg.whatsapp.net`。
</Accordion>
<Accordion title="发送时没有活跃监听器">
当目标账号没有活跃的 Gateway 网关监听器时，出站发送会快速失败。
<Accordion title="发送时没有活动监听器">
当目标账号没有活动的 Gateway 网关监听器时，出站发送会快速失败。
确保 Gateway 网关正在运行且账号已关联。
确保 Gateway 网关正在运行且账号已链接。
</Accordion>
<Accordion title="群组消息被意外忽略">
按以下顺序检查：
按此顺序检查：
- `groupPolicy`
- `groupAllowFrom` / `allowFrom`
@ -594,34 +597,34 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时
## 系统提示词
WhatsApp 支持通过 `groups` 和 `direct` 映射，为群组和直接聊天配置 Telegram 风格的系统提示词。
WhatsApp 支持通过 `groups` 和 `direct` 映射为群组和直接聊天设置 Telegram 风格的系统提示词。
群组消息的解析层级：
首先确定有效的 `groups` 映射：如果账号定义了自己的 `groups`，它会完全替换根级 `groups` 映射（不做深度合并）。随后在生成的单一映射上执行提示词查找：
首先确定有效的 `groups` 映射：如果账号定义了自己的 `groups`，它会完全替换根级 `groups` 映射（不进行深度合并）。然后在得到的单一映射上执行提示词查找：
1. **群组特定系统提示词**（`groups["<groupId>"].systemPrompt`）：当映射中存在特定群组条目**并且**定义了其 `systemPrompt` 键时使用。如果 `systemPrompt` 是空字符串（`""`），则通配符会被抑制，且不会应用任何系统提示词。
2. **群组通配符系统提示词**（`groups["*"].systemPrompt`）：当映射中完全不存在特定群组条目，或该条目存在但没有定义 `systemPrompt` 键时使用。
1. **群组专属系统提示词**（`groups["<groupId>"].systemPrompt`）：当映射中存在特定群组条目**且**定义了其 `systemPrompt` 键时使用。如果 `systemPrompt` 是空字符串（`""`），通配符会被抑制，并且不会应用任何系统提示词。
2. **群组通配系统提示词**（`groups["*"].systemPrompt`）：当映射中完全没有特定群组条目，或存在该条目但未定义 `systemPrompt` 键时使用。
直接消息的解析层级：
首先确定有效的 `direct` 映射：如果账号定义了自己的 `direct`，它会完全替换根级 `direct` 映射（不做深度合并）。随后在生成的单一映射上执行提示词查找：
首先确定有效的 `direct` 映射：如果账号定义了自己的 `direct`，它会完全替换根级 `direct` 映射（不进行深度合并）。然后在得到的单一映射上执行提示词查找：
1. **直接聊天特定系统提示词**（`direct["<peerId>"].systemPrompt`）：当映射中存在特定对端条目**并且**定义了其 `systemPrompt` 键时使用。如果 `systemPrompt` 是空字符串（`""`），则通配符会被抑制，且不会应用任何系统提示词。
2. **直接聊天通配符系统提示词**（`direct["*"].systemPrompt`）：当映射中完全不存在特定对端条目，或该条目存在但没有定义 `systemPrompt` 键时使用。
1. **直接聊天专属系统提示词**（`direct["<peerId>"].systemPrompt`）：当映射中存在特定对端条目**且**定义了其 `systemPrompt` 键时使用。如果 `systemPrompt` 是空字符串（`""`），通配符会被抑制，并且不会应用任何系统提示词。
2. **直接聊天通配系统提示词**（`direct["*"].systemPrompt`）：当映射中完全没有特定对端条目，或存在该条目但未定义 `systemPrompt` 键时使用。
<Note>
`dms` 仍是轻量的每私信历史覆盖桶（`dms.<id>.historyLimit`）。提示词覆盖位于 `direct` 下。
`dms` 仍然是轻量级的按私信历史覆盖存储桶（`dms.<id>.historyLimit`）。提示词覆盖位于 `direct` 下。
</Note>
**与 Telegram 多账号行为的区别：**在 Telegram 中，多账号设置会有意对所有账号抑制根级 `groups` —— 即使某些账号没有定义自己的 `groups` —— 以防止机器人接收它不属于的群组消息。WhatsApp 不应用此保护：根级 `groups` 和根级 `direct` 始终会被未定义账号级覆盖的账号继承，无论配置了多少账号。在多账号 WhatsApp 设置中，如果你想要按账号配置群组或直接聊天提示词，请在每个账号下显式定义完整映射，而不是依赖根级默认值。
**与 Telegram 多账号行为的差异：** 在 Telegram 中，根级 `groups` 会被有意对多账号设置中的所有账号抑制，即使某些账号没有定义自己的 `groups`，也是如此，以防止机器人接收它不属于的群组的群组消息。WhatsApp 不应用此保护：根级 `groups` 和根级 `direct` 始终会被没有定义账号级覆盖的账号继承，无论配置了多少个账号。在多账号 WhatsApp 设置中，如果你想要按账号设置群组或直接聊天提示词，请在每个账号下显式定义完整映射，而不是依赖根级默认值。
重要行为：
- `channels.whatsapp.groups` 既是每群组配置映射，也是聊天级群组允许列表。在根作用域或账号作用域中，`groups["*"]` 表示该作用域“允许所有群组”。
- 仅当你已经希望该作用域允许所有群组时，才添加通配符群组 `systemPrompt`。如果你仍希望只有一组固定的群组 ID 具备资格，不要使用 `groups["*"]` 作为提示词默认值。请改为在每个显式允许列出的群组条目上重复该提示词。
- 群组准入和发送者授权是独立检查。`groups["*"]` 会扩大可进入群组处理的群组集合，但它本身不会授权这些群组中的每个发送者。发送者访问仍由 `channels.whatsapp.groupPolicy` 和 `channels.whatsapp.groupAllowFrom` 单独控制。
- `channels.whatsapp.direct` 对私信没有相同的副作用。`direct["*"]` 只会在私信已通过 `dmPolicy` 加 `allowFrom` 或配对存储规则被准入后，提供默认的直接聊天配置。
- `channels.whatsapp.groups` 既是按群组配置映射，也是聊天级群组允许列表。在根级或账号作用域中，`groups["*"]` 表示该作用域“允许所有群组”。
- 仅当你已经希望该作用域允许所有群组时，才添加通配群组 `systemPrompt`。如果你仍只希望固定的一组群组 ID 符合条件，请不要使用 `groups["*"]` 作为提示词默认值。请改为在每个显式允许列出的群组条目上重复该提示词。
- 群组准入和发送者授权是两个独立检查。`groups["*"]` 会扩大可以进入群组处理的群组集合，但它本身不会授权这些群组中的每个发送者。发送者访问仍由 `channels.whatsapp.groupPolicy` 和 `channels.whatsapp.groupAllowFrom` 单独控制。
- `channels.whatsapp.direct` 对私信没有相同的副作用。`direct["*"]` 只会在私信已经通过 `dmPolicy` 加 `allowFrom` 或配对存储规则准入后，提供默认的直接聊天配置。
示例：
@ -663,7 +666,7 @@ WhatsApp 支持通过 `groups` 和 `direct` 映射，为群组和直接聊天配
}
```
## 配置参考指引
## 配置参考指针
主要参考：
@ -671,14 +674,14 @@ WhatsApp 支持通过 `groups` 和 `direct` 映射，为群组和直接聊天配
高价值 WhatsApp 字段：
- 访问：`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups`
- 访问控制：`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups`
- 投递：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`sendReadReceipts`、`ackReaction`、`reactionLevel`、`exposeErrorText`
- 多账号：`accounts.<id>.enabled`、`accounts.<id>.authDir`、账号级覆盖项
- 操作：`configWrites`、`debounceMs`、`web.enabled`、`web.heartbeatSeconds`、`web.reconnect.*`、`web.whatsapp.*`
- 会话行为：`session.dmScope`、`historyLimit`、`dmHistoryLimit`、`dms.<id>.historyLimit`
- 提示词：`groups.<id>.systemPrompt`、`groups["*"].systemPrompt`、`direct.<id>.systemPrompt`、`direct["*"].systemPrompt`
## 相关
## 相关内容
- [配对](/zh-CN/channels/pairing)
- [群组](/zh-CN/channels/groups)

75
docs/zh-CN/cli/agents.md
View File

@ -1,26 +1,26 @@
---
read_when:
- 你希望拥有多个相互隔离的智能体（工作区 + 路由 + 认证）
- 你想要多个相互隔离的智能体（工作区 + 路由 + 凭证）
summary: '`openclaw agents` 的 CLI 参考（list/add/delete/bindings/bind/unbind/set identity）'
title: 智能体
x-i18n:
generated_at: "2026-04-27T06:02:52Z"
model: gpt-5.4
generated_at: "2026-04-29T10:59:37Z"
model: gpt-5.5
provider: openai
source_hash: 41683d8684eba61421124bc3977690ad40b01d63a109d931854638a5d2c372a2
source_hash: 46742a890a57cb1035a053f14fe574044e4a3d7dcc04812cd11c633bd808819b
source_path: cli/agents.md
workflow: 15
workflow: 16
---
# `openclaw agents`
管理相互隔离的智能体（工作区 + 认证 + 路由）。
管理隔离的智能体（工作区 + 凭证 + 路由）。
相关内容：
相关：
- [多智能体路由](/zh-CN/concepts/multi-agent)
- [智能体工作区](/zh-CN/concepts/agent-workspace)
- [Skills 配置](/zh-CN/tools/skills-config)：Skills 可见性配置。
- [Agent 工作区](/zh-CN/concepts/agent-workspace)
- [Skills 配置](/zh-CN/tools/skills-config)：Skill 可见性配置。
## 示例
@ -41,7 +41,7 @@ openclaw agents delete work
使用路由绑定将入站渠道流量固定到特定智能体。
如果你还希望每个智能体看到不同的 Skills，请在 `openclaw.json` 中配置 `agents.defaults.skills` 和 `agents.list[].skills`。参见 [Skills 配置](/zh-CN/tools/skills-config) 和[配置参考](/zh-CN/gateway/config-agents#agents-defaults-skills)。
如果你还想为每个智能体配置不同的可见 Skills，请在 `openclaw.json` 中配置 `agents.defaults.skills` 和 `agents.list[].skills`。请参阅 [Skills 配置](/zh-CN/tools/skills-config)和[配置参考](/zh-CN/gateway/config-agents#agents-defaults-skills)。
列出绑定：
@ -57,27 +57,27 @@ openclaw agents bindings --json
openclaw agents bind --agent work --bind telegram:ops --bind discord:guild-a
```
如果你省略 `accountId`（`--bind <channel>`），OpenClaw 会在可用时根据渠道默认值和插件设置钩子解析它。
如果省略 `accountId`（`--bind <channel>`），OpenClaw 会在可用时从渠道默认值和插件设置钩子解析它。
如果你在 `bind` 或 `unbind` 中省略 `--agent`，OpenClaw 会将当前默认智能体作为目标。
如果为 `bind` 或 `unbind` 省略 `--agent`，OpenClaw 会以当前默认智能体为目标。
### 绑定作用域行为
- 不带 `accountId` 的绑定只匹配渠道默认账号。
- `accountId: "*"` 是渠道级回退（所有账号），其特异性低于显式账号绑定。
- 如果同一个智能体已经有一个不带 `accountId` 的匹配渠道绑定，而你之后使用显式或已解析的 `accountId` 进行绑定，OpenClaw 会就地升级现有绑定，而不是添加重复项。
- 没有 `accountId` 的绑定仅匹配渠道默认账号。
- `accountId: "*"` 是渠道范围内的后备项（所有账号），其优先级低于显式账号绑定。
- 如果同一个智能体已经有一个不带 `accountId` 的匹配渠道绑定，而你稍后使用显式或已解析的 `accountId` 绑定，OpenClaw 会就地升级该现有绑定，而不是添加重复项。
示例：
```bash
# 初始仅渠道绑定
# initial channel-only binding
openclaw agents bind --agent work --bind telegram
# 之后升级为账号作用域绑定
# later upgrade to account-scoped binding
openclaw agents bind --agent work --bind telegram:ops
```
升级后，该绑定的路由将限定为 `telegram:ops`。如果你还希望保留默认账号路由，请显式添加它（例如 `--bind telegram:default`）。
升级后，该绑定的路由范围限定为 `telegram:ops`。如果你还想要默认账号路由，请显式添加它（例如 `--bind telegram:default`）。
移除绑定：
@ -86,20 +86,20 @@ openclaw agents unbind --agent work --bind telegram:ops
openclaw agents unbind --agent work --all
```
`unbind` 只能接受 `--all` 或一个或多个 `--bind` 值，不能同时使用两者。
`unbind` 接受 `--all` 或一个或多个 `--bind` 值，但不能同时使用二者。
## 命令面
## 命令界面
### `agents`
运行不带子命令的 `openclaw agents` 等同于 `openclaw agents list`。
不带子命令运行 `openclaw agents` 等同于 `openclaw agents list`。
### `agents list`
选项：
- `--json`
- `--bindings`：包含完整路由规则，而不仅仅是每个智能体的计数/摘要
- `--bindings`：包含完整路由规则，而不只是按智能体的计数/摘要
### `agents add [name]`
@ -114,9 +114,14 @@ openclaw agents unbind --agent work --all
说明：
- 传入任何显式的 add 标志都会使该命令进入非交互路径。
- 非交互模式要求同时提供智能体名称和 `--workspace`。
- `main` 是保留字，不能用作新的智能体 ID。
- 传入任何显式添加标志都会将命令切换到非交互路径。
- 非交互模式需要同时提供智能体名称和 `--workspace`。
- `main` 是保留项，不能用作新的智能体 ID。
- 在交互模式中，凭证种子仅复制可移植的静态配置文件
（默认是 `api_key` 和静态 `token`）。OAuth 刷新令牌配置文件仍然
只能通过从真实 `main` 智能体存储读取继承来使用。
如果配置的默认智能体不是 `main`，请为新智能体单独登录 OAuth
配置文件。
### `agents bindings`
@ -152,9 +157,9 @@ openclaw agents unbind --agent work --all
说明：
- `main` 不能删除。
- 没有 `--force` 时，需要交互式确认。
- 工作区、智能体状态和会话转录目录会被移到回收站，而不是被硬删除。
- 如果另一个智能体的工作区是相同路径、位于此工作区内部，或包含此工作区，
- 不带 `--force` 时，需要交互式确认。
- 工作区、智能体状态和会话记录目录会被移到废纸篓，而不是硬删除。
- 如果另一个智能体的工作区是同一路径、位于此工作区内，或包含此工作区，
该工作区会被保留，并且 `--json` 会报告 `workspaceRetained`、
`workspaceRetainedReason` 和 `workspaceSharedWith`。
@ -163,18 +168,18 @@ openclaw agents unbind --agent work --all
每个智能体工作区都可以在工作区根目录包含一个 `IDENTITY.md`：
- 示例路径：`~/.openclaw/workspace/IDENTITY.md`
- `set-identity --from-identity` 会从工作区根目录读取（或从显式 `--identity-file` 读取）
- `set-identity --from-identity` 从工作区根目录（或显式的 `--identity-file`）读取
头像路径相对于工作区根目录解析。
## 设置身份
`set-identity` 会将字段写入 `agents.list[].identity`：
`set-identity` 将字段写入 `agents.list[].identity`：
- `name`
- `theme`
- `emoji`
- `avatar`（相对于工作区的路径、http(s) URL 或 data URI）
- `avatar`（工作区相对路径、http(s) URL 或 data URI）
选项：
@ -191,8 +196,8 @@ openclaw agents unbind --agent work --all
说明：
- 可以使用 `--agent` 或 `--workspace` 选择目标智能体。
- 如果你依赖 `--workspace` 且有多个智能体共享该工作区，命令会失败，并要求你传入 `--agent`。
- 当未提供显式身份字段时，该命令会从 `IDENTITY.md` 读取身份数据。
- 如果你依赖 `--workspace`，且多个智能体共享该工作区，命令会失败并要求你传入 `--agent`。
- 当没有提供显式身份字段时，命令会从 `IDENTITY.md` 读取身份数据。
从 `IDENTITY.md` 加载：
@ -226,8 +231,8 @@ openclaw agents set-identity --agent main --name "OpenClaw" --emoji "🦞" --ava
}
```
## 相关内容
## 相关
- [CLI 参考](/zh-CN/cli)
- [多智能体路由](/zh-CN/concepts/multi-agent)
- [智能体工作区](/zh-CN/concepts/agent-workspace)
- [Agent 工作区](/zh-CN/concepts/agent-workspace)

162
docs/zh-CN/concepts/multi-agent.md
View File

@ -5,49 +5,49 @@ status: active
summary: 多智能体路由：隔离的智能体、渠道账号和绑定
title: 多智能体路由
x-i18n:
generated_at: "2026-04-28T11:49:36Z"
generated_at: "2026-04-29T10:59:29Z"
model: gpt-5.5
provider: openai
source_hash: 75770f058453345ef2de281d5fffb20ccfda5e73815e27b1643909a624007b86
source_hash: 67adea74d5f97feff3f816cc4c34c9429e7659289013e5a7c7623bd185a50a31
source_path: concepts/multi-agent.md
workflow: 16
---
运行多个_隔离_智能体：每个智能体都有自己的工作区、状态目录（`agentDir`）和会话历史；还可以在一个运行中的 Gateway 网关中使用多个渠道账号（例如两个 WhatsApp）。入站消息会通过绑定路由到正确的智能体。
运行多个_隔离_智能体，每个智能体都有自己的工作区、状态目录（`agentDir`）和会话历史；同时还可以在一个正在运行的 Gateway 网关中使用多个渠道账号（例如两个 WhatsApp 账号）。入站消息会通过绑定路由到正确的智能体。
这里的**智能体**是完整的按 persona 划分的范围：工作区文件、认证配置、模型注册表和会话存储。`agentDir` 是磁盘上的状态目录，用来保存这个按智能体划分的配置，位置为 `~/.openclaw/agents/<agentId>/`。**绑定**会把一个渠道账号（例如一个 Slack 工作区或一个 WhatsApp 号码）映射到其中一个智能体。
这里的**智能体**是完整的每角色作用域：工作区文件、认证配置文件、模型注册表和会话存储。`agentDir` 是磁盘上的状态目录，位于 `~/.openclaw/agents/<agentId>/`，用于保存此每智能体配置。**绑定**会将一个渠道账号（例如 Slack 工作区或 WhatsApp 号码）映射到这些智能体之一。
## “一个智能体”是什么？
## 什么是“一个智能体”？
**智能体**是一个完全划定范围的“大脑”，拥有自己的：
**智能体**是一个完全限定作用域的大脑，拥有自己的：
- **工作区**（文件、AGENTS.md/SOUL.md/USER.md、本地笔记、persona 规则）。
- **状态目录**（`agentDir`），用于认证配置、模型注册表和按智能体划分的配置。
- **工作区**（文件、AGENTS.md/SOUL.md/USER.md、本地笔记、角色规则）。
- **状态目录**（`agentDir`），用于认证配置文件、模型注册表和每智能体配置。
- **会话存储**（聊天历史 + 路由状态），位于 `~/.openclaw/agents/<agentId>/sessions` 下。
认证配置是**按智能体划分**的。每个智能体都会从自己的位置读取：
认证配置文件按**每智能体**隔离。每个智能体都会从自己的位置读取：
```text
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
```
<Note>
这里 `sessions_history` 也是更安全的跨会话回忆路径：它返回的是有边界、已清理的视图，而不是原始转录的直接转储。Assistant 回忆会在脱敏/截断前剥离思考标签、`<relevant-memories>` 脚手架、纯文本工具调用 XML 载荷（包括 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>` 以及被截断的工具调用块）、降级后的工具调用脚手架、泄漏的 ASCII/全角模型控制 token，以及格式错误的 MiniMax 工具调用 XML。
`session_history` 在这里也是更安全的跨会话回忆路径：它返回的是有界且经过清理的视图，而不是原始转录的直接转储。助手回忆会在脱敏/截断前移除思考标签、`<relevant-memories>` 脚手架、明文工具调用 XML 载荷（包括 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>` 和被截断的工具调用块）、降级后的工具调用脚手架、泄漏的 ASCII/全角模型控制令牌，以及格式错误的 MiniMax 工具调用 XML。
</Note>
<Warning>
主智能体凭证**不会**自动共享。不要在多个智能体之间复用 `agentDir`（这会导致认证/会话冲突）。如果你想共享凭证，请把 `auth-profiles.json` 复制到另一个智能体的 `agentDir` 中。
不要在多个智能体之间复用 `agentDir`（这会导致认证/会话冲突）。当智能体没有本地配置文件时，可以回退读取默认/主智能体的认证配置文件，但 OpenClaw 不会把 OAuth 刷新令牌克隆到次级智能体存储中。如果你想使用独立的 OAuth 账号，请从该智能体登录；如果你手动复制凭证，只复制可移植的静态 `api_key` 或 `token` 配置文件。
</Warning>
Skills 会从每个智能体工作区以及 `~/.openclaw/skills` 等共享根目录加载，然后在配置了有效智能体技能允许列表时进行过滤。使用 `agents.defaults.skills` 设置共享基线，使用 `agents.list[].skills` 设置按智能体替换。参见 [Skills：按智能体与共享](/zh-CN/tools/skills#per-agent-vs-shared-skills) 和 [Skills：智能体技能允许列表](/zh-CN/tools/skills#agent-skill-allowlists)。
Skills 会从每个智能体工作区以及 `~/.openclaw/skills` 等共享根目录加载，然后在配置后按生效的智能体 Skills 允许列表过滤。使用 `agents.defaults.skills` 设置共享基线，使用 `agents.list[].skills` 进行每智能体替换。参见 [Skills：每智能体与共享](/zh-CN/tools/skills#per-agent-vs-shared-skills) 和 [Skills：智能体 Skills 允许列表](/zh-CN/tools/skills#agent-skill-allowlists)。
Gateway 网关可以托管**一个智能体**（默认）或**多个智能体**并排运行。
<Note>
**工作区注意事项：**每个智能体的工作区是**默认 cwd**，不是强沙箱。相对路径会在工作区内解析，但除非启用了沙箱隔离，否则绝对路径可以访问主机上的其他位置。参见[沙箱隔离](/zh-CN/gateway/sandboxing)。
**工作区说明：**每个智能体的工作区是**默认 cwd**，不是硬性沙箱。相对路径会在工作区内解析，但除非启用沙箱隔离，否则绝对路径可以访问主机上的其他位置。参见[沙箱隔离](/zh-CN/gateway/sandboxing)。
</Note>
## 路径（快速图示）
## 路径（快速映射）
- 配置：`~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`）
- 状态目录：`~/.openclaw`（或 `OPENCLAW_STATE_DIR`）
@ -57,24 +57,24 @@ Gateway 网关可以托管**一个智能体**（默认）或**多个智能体**
### 单智能体模式（默认）
如果你什么都不做，OpenClaw 会运行单个智能体：
如果你什么都不做，OpenClaw 会运行一个智能体：
- `agentId` 默认为 **`main`**。
- 会话以 `agent:main:<mainKey>` 作为键。
- 工作区默认为 `~/.openclaw/workspace`（设置了 `OPENCLAW_PROFILE` 时则为 `~/.openclaw/workspace-<profile>`）。
- 状态默认为 `~/.openclaw/agents/main/agent`。
- `agentId` 默认是 **`main`**。
- 会话键形如 `agent:main:<mainKey>`。
- 工作区默认是 `~/.openclaw/workspace`（设置 `OPENCLAW_PROFILE` 时则为 `~/.openclaw/workspace-<profile>`）。
- 状态默认位于 `~/.openclaw/agents/main/agent`。
## 智能体助手
## 智能体辅助工具
使用智能体向导添加一个新的隔离智能体：
使用智能体向导添加新的隔离智能体：
```bash
openclaw agents add work
```
然后添加 `bindings`（或让向导完成）来路由入站消息。
然后添加 `bindings`（或让向导完成）以路由入站消息。
使用以下命令验证：
用以下命令验证：
```bash
openclaw agents list --bindings
@ -91,15 +91,15 @@ openclaw agents list --bindings
openclaw agents add social
```
每个智能体都会获得自己的工作区，其中包含 `SOUL.md`、`AGENTS.md` 和可选的 `USER.md`，并且在 `~/.openclaw/agents/<agentId>` 下拥有专用的 `agentDir` 和会话存储。
每个智能体都会获得自己的工作区，其中包含 `SOUL.md`、`AGENTS.md` 和可选的 `USER.md`，并在 `~/.openclaw/agents/<agentId>` 下拥有专用 `agentDir` 和会话存储。
</Step>
<Step title="创建渠道账号">
在你偏好的渠道上为每个智能体创建一个账号：
- Discord：每个智能体一个 bot，启用 Message Content Intent，复制每个 token。
- Telegram：通过 BotFather 为每个智能体创建一个 bot，复制每个 token。
- WhatsApp：为每个账号关联对应的电话号码。
- Discord：每个智能体一个机器人，启用消息内容意图，复制每个令牌。
- Telegram：通过 BotFather 为每个智能体创建一个机器人，复制每个令牌。
- WhatsApp：为每个账号关联各自的电话号码。
```bash
openclaw channels login --channel whatsapp --account work
@ -120,19 +120,19 @@ openclaw agents list --bindings
</Step>
</Steps>
## 多个智能体 = 多个人、多个个性
## 多个智能体 = 多个人、多种个性
使用**多个智能体**时，每个 `agentId` 都会成为一个**完全隔离的 persona**：
使用**多个智能体**时，每个 `agentId` 都会变成一个**完全隔离的角色**：
- **不同的电话号码/账号**（按渠道 `accountId`）。
- **不同的个性**（按智能体划分的工作区文件，例如 `AGENTS.md` 和 `SOUL.md`）。
- **独立的认证 + 会话**（除非显式启用，否则不会串线）。
- **不同的电话号码/账号**（每渠道一个 `accountId`）。
- **不同的个性**（每智能体工作区文件，例如 `AGENTS.md` 和 `SOUL.md`）。
- **独立的认证 + 会话**（除非显式启用，否则不会串话）。
这让**多个人**可以共享一个 Gateway 网关服务器，同时让他们的 AI“大脑”和数据保持隔离。
这让**多个人**可以共享一台 Gateway 网关服务器，同时保持他们的 AI “大脑”和数据彼此隔离。
## 跨智能体 QMD 记忆搜索
如果一个智能体应搜索另一个智能体的 QMD 会话转录，请在 `agents.list[].memorySearch.qmd.extraCollections` 下添加额外 collection。只有当每个智能体都应该继承相同的共享转录 collection 时，才使用 `agents.defaults.memorySearch.qmd.extraCollections`。
如果一个智能体需要搜索另一个智能体的 QMD 会话转录，请在 `agents.list[].memorySearch.qmd.extraCollections` 下添加额外集合。只有当每个智能体都应继承同一组共享转录集合时，才使用 `agents.defaults.memorySearch.qmd.extraCollections`。
```json5
{
@ -165,11 +165,11 @@ openclaw agents list --bindings
}
```
额外 collection 路径可以在多个智能体之间共享，但当路径位于智能体工作区之外时，collection 名称会保持显式。工作区内的路径仍然按智能体划定范围，因此每个智能体都会保留自己的转录搜索集。
额外集合路径可以在多个智能体之间共享，但当路径位于智能体工作区之外时，集合名称会保持显式。工作区内的路径仍然限定在智能体作用域内，因此每个智能体都会保留自己的转录搜索集。
## 一个 WhatsApp 号码，多个人（私信拆分）
你可以在**一个 WhatsApp 账号**上，将**不同 WhatsApp 私信**路由到不同智能体。使用 `peer.kind: "direct"` 按发送方 E.164（例如 `+15551234567`）匹配。回复仍然来自同一个 WhatsApp 号码（没有按智能体划分的发送方身份）。
你可以在**一个 WhatsApp 账号**上，将**不同的 WhatsApp 私信**路由到不同智能体。使用发送方 E.164（例如 `+15551234567`）并配合 `peer.kind: "direct"` 进行匹配。回复仍然来自同一个 WhatsApp 号码（没有按智能体区分的发件身份）。
<Note>
直接聊天会折叠到智能体的**主会话键**，因此真正隔离需要**每个人一个智能体**。
@ -204,10 +204,10 @@ openclaw agents list --bindings
}
```
注意：
说明：
- 私信访问控制是**每个 WhatsApp 账号的全局设置**（配对/允许列表），不是按智能体划分。
- 对于共享群组，请把群组绑定到一个智能体，或使用[广播群组](/zh-CN/channels/broadcast-groups)。
- 私信访问控制是**每个 WhatsApp 账号全局**的（配对/允许列表），不是按智能体隔离。
- 对于共享群组，请将群组绑定到一个智能体，或使用[广播群组](/zh-CN/channels/broadcast-groups)。
## 路由规则（消息如何选择智能体）
@ -230,7 +230,7 @@ openclaw agents list --bindings
Slack。
</Step>
<Step title="渠道的 accountId 匹配">
按账号回退。
每账号回退。
</Step>
<Step title="渠道级匹配">
`accountId: "*"`。
@ -241,24 +241,24 @@ openclaw agents list --bindings
</Steps>
<AccordionGroup>
<Accordion title="平局处理和 AND 语义">
- 如果同一层级中有多个绑定匹配，则配置顺序中第一个匹配项获胜。
- 如果一个绑定设置了多个匹配字段（例如 `peer` + `guildId`），则所有指定字段都必须满足（`AND` 语义）。
<Accordion title="平局判定和 AND 语义">
- 如果同一层级中有多个绑定匹配，则配置顺序中的第一个获胜。
- 如果一个绑定设置了多个匹配字段（例如 `peer` + `guildId`），则所有指定字段都是必需的（`AND` 语义）。
</Accordion>
<Accordion title="账号范围细节">
- 省略 `accountId` 的绑定只会匹配默认账号。
- 使用 `accountId: "*"` 为渠道中的所有账号设置兜底。
- 如果你之后为同一个智能体添加了同一绑定，但带有显式账号 ID，OpenClaw 会把现有的仅渠道绑定升级为按账号划分的绑定，而不是创建重复项。
<Accordion title="账号作用域细节">
- 省略 `accountId` 的绑定只匹配默认账号。
- 对所有账号使用 `accountId: "*"` 作为渠道范围回退。
- 如果你之后为同一智能体添加带有显式账号 ID 的相同绑定，OpenClaw 会将现有的仅渠道绑定升级为账号作用域绑定，而不是复制它。
</Accordion>
</AccordionGroup>
## 多账号 / 电话号码
## 多账号/电话号码
支持**多账号**的渠道（例如 WhatsApp）使用 `accountId` 标识每次登录。每个 `accountId` 都可以路由到不同的智能体，因此一台服务器可以托管多个电话号码而不会混合会话。
支持**多账号**的渠道（例如 WhatsApp）使用 `accountId` 来标识每次登录。每个 `accountId` 都可以路由到不同智能体，因此一台服务器可以托管多个电话号码，而不会混淆会话。
如果你想在省略 `accountId` 时使用渠道范围的默认账号，请设置 `channels.<channel>.defaultAccount`（可选）。未设置时，如果存在 `default`，OpenClaw 会回退到它，否则回退到第一个配置的账号 ID（排序后）。
如果你想在省略 `accountId` 时使用渠道范围默认账号，请设置 `channels.<channel>.defaultAccount`（可选）。未设置时，OpenClaw 会回退到 `default`（如果存在），否则使用排序后的第一个已配置账号 ID。
支持此模式的常见渠道包括：
@ -268,16 +268,16 @@ openclaw agents list --bindings
## 概念
- `agentId`：一个“大脑”（工作区、按智能体划分的认证、按智能体划分的会话存储）。
- `agentId`：一个“大脑”（工作区、每智能体认证、每智能体会话存储）。
- `accountId`：一个渠道账号实例（例如 WhatsApp 账号 `"personal"` 与 `"biz"`）。
- `binding`：通过 `(channel, accountId, peer)` 以及可选的 guild/team ID，将入站消息路由到某个 `agentId`。
- 直接聊天会折叠为 `agent:<agentId>:<mainKey>`（按智能体划分的“main”；`session.mainKey`）。
- `binding`：按 `(channel, accountId, peer)` 以及可选的服务器/团队 ID 将入站消息路由到 `agentId`。
- 直接聊天会折叠到 `agent:<agentId>:<mainKey>`（每智能体的 `main`；`session.mainKey`）。
## 平台示例
<AccordionGroup>
<Accordion title="每个智能体一个 Discord bot">
每个 Discord bot 账号都会映射到一个唯一的 `accountId`。将每个账号绑定到一个智能体，并按 bot 保持允许列表。
<Accordion title="每智能体一个 Discord 机器人">
每个 Discord 机器人账号都会映射到一个唯一的 `accountId`。将每个账号绑定到一个智能体，并按机器人保留允许列表。
```json5
{
@ -321,11 +321,11 @@ openclaw agents list --bindings
}
```
- 邀请每个 bot 加入 guild 并启用 Message Content Intent。
- Token 存放在 `channels.discord.accounts.<id>.token` 中（默认账号可以使用 `DISCORD_BOT_TOKEN`）。
- 邀请每个机器人加入 guild，并启用 Message Content Intent。
- Token 位于 `channels.discord.accounts.<id>.token`（默认账号可以使用 `DISCORD_BOT_TOKEN`）。
</Accordion>
<Accordion title="每个智能体对应的 Telegram 机器人">
<Accordion title="每个智能体一个 Telegram 机器人">
```json5
{
agents: {
@ -356,19 +356,19 @@ openclaw agents list --bindings
}
```
- 使用 BotFather 为每个智能体创建一个机器人，并复制每个令牌。
- 令牌位于 `channels.telegram.accounts.<id>.botToken`（默认账号可以使用 `TELEGRAM_BOT_TOKEN`）。
- 使用 BotFather 为每个智能体创建一个机器人，并复制每个 token。
- Token 位于 `channels.telegram.accounts.<id>.botToken`（默认账号可以使用 `TELEGRAM_BOT_TOKEN`）。
</Accordion>
<Accordion title="每个智能体对应的 WhatsApp 号码">
启动 Gateway 网关前，先链接每个账号：
<Accordion title="每个智能体一个 WhatsApp 号码">
在启动 Gateway 网关前关联每个账号：
```bash
openclaw channels login --channel whatsapp --account personal
openclaw channels login --channel whatsapp --account biz
```
`~/.openclaw/openclaw.json`（JSON5）：
`~/.openclaw/openclaw.json` (JSON5)：
```js
{
@ -465,14 +465,14 @@ openclaw agents list --bindings
}
```
说明：
注意：
- 如果一个渠道有多个账号，请在绑定中添加 `accountId`（例如 `{ channel: "whatsapp", accountId: "personal" }`）。
- 要将单个私信/群组路由到 Opus，同时让其余消息保留在 chat 上，请为该对端添加 `match.peer` 绑定；对端匹配始终优先于渠道级规则。
- 如果某个渠道有多个账号，请在绑定中添加 `accountId`（例如 `{ channel: "whatsapp", accountId: "personal" }`）。
- 要将单个私信/群组路由到 Opus，同时让其余内容继续走 chat，请为该 peer 添加 `match.peer` 绑定；peer 匹配始终优先于渠道级规则。
</Tab>
<Tab title="同一渠道，将一个对端路由到 Opus">
让 WhatsApp 保持在快速智能体上，但将一个私信路由到 Opus：
<Tab title="同一渠道，将一个 peer 路由到 Opus">
让 WhatsApp 保持使用快速智能体，但将一个私信路由到 Opus：
```json5
{
@ -502,11 +502,11 @@ openclaw agents list --bindings
}
```
对端绑定始终优先，所以请将它们放在渠道级规则上方。
Peer 绑定始终优先，因此请将它们放在渠道级规则上方。
</Tab>
<Tab title="绑定到 WhatsApp 群组的家庭智能体">
将一个专用家庭智能体绑定到单个 WhatsApp 群组，并启用提及门控和更严格的工具策略：
将专用家庭智能体绑定到单个 WhatsApp 群组，并启用提及门控和更严格的工具策略：
```json5
{
@ -551,15 +551,15 @@ openclaw agents list --bindings
}
```
说明：
注意：
- 工具允许/拒绝列表是**工具**，不是 Skills。如果某个 Skills 需要运行二进制文件，请确保允许 `exec`，并且该二进制文件存在于沙箱中。
- 如需更严格的门控，请设置 `agents.list[].groupChat.mentionPatterns`，并保持该渠道的群组允许列表处于启用状态。
- 工具允许/拒绝列表是**工具**，不是 Skills。如果某个 skill 需要运行二进制文件，请确保允许 `exec`，并且该二进制文件存在于沙箱中。
- 如需更严格的门控，请设置 `agents.list[].groupChat.mentionPatterns`，并保持该渠道的群组允许列表启用。
</Tab>
</Tabs>
## 每智能体沙箱和工具配置
## 每个智能体的沙箱和工具配置
每个智能体都可以有自己的沙箱和工具限制：
@ -597,25 +597,25 @@ openclaw agents list --bindings
```
<Note>
`setupCommand` 位于 `sandbox.docker` 下，并在容器创建时运行一次。当解析后的作用域为 `"shared"` 时，会忽略每智能体的 `sandbox.docker.*` 覆盖项。
`setupCommand` 位于 `sandbox.docker` 下，并在容器创建时运行一次。当解析后的 scope 为 `"shared"` 时，每个智能体的 `sandbox.docker.*` 覆盖会被忽略。
</Note>
**优势：**
- **安全隔离**：限制不受信任智能体的工具。
- **资源控制**：对特定智能体使用沙箱，同时让其他智能体保留在主机上。
- **安全隔离**：限制不受信任智能体可用的工具。
- **资源控制**：将特定智能体放入沙箱，同时让其他智能体保留在主机上。
- **灵活策略**：为每个智能体设置不同权限。
<Note>
`tools.elevated` 是**全局**且基于发送者的；它不能按智能体配置。如果你需要每智能体边界，请使用 `agents.list[].tools` 来拒绝 `exec`。对于群组目标，请使用 `agents.list[].groupChat.mentionPatterns`，让 @提及清晰映射到目标智能体。
`tools.elevated` 是**全局**且基于发送者的；它不能按智能体配置。如果你需要每个智能体的边界，请使用 `agents.list[].tools` 来拒绝 `exec`。对于群组定向，请使用 `agents.list[].groupChat.mentionPatterns`，让 @提及能够清晰映射到目标智能体。
</Note>
详细示例见[多智能体沙箱和工具](/zh-CN/tools/multi-agent-sandbox-tools)。
详见[多智能体沙箱和工具](/zh-CN/tools/multi-agent-sandbox-tools)中的详细示例。
## 相关
## 相关内容
- [ACP 智能体](/zh-CN/tools/acp-agents) — 运行外部编码 harness
- [渠道路由](/zh-CN/channels/channel-routing) — 消息如何路由到智能体
- [在线状态](/zh-CN/concepts/presence) — 智能体在线状态和可用性
- [Presence](/zh-CN/concepts/presence) — 智能体在线状态和可用性
- [会话](/zh-CN/concepts/session) — 会话隔离和路由
- [子智能体](/zh-CN/tools/subagents) — 生成后台智能体运行

131
docs/zh-CN/concepts/oauth.md
View File

@ -1,90 +1,89 @@
---
read_when:
- 你想端到端了解 OpenClaw OAuth
- 你遇到了令牌失效或退出登录问题
- 你遇到了令牌失效 / 退出登录问题
- 你想使用 Claude CLI 或 OAuth 认证流程
- 你想使用多个账户或配置文件路由
- 你想要多个账户或配置文件路由
summary: OpenClaw 中的 OAuth：令牌交换、存储和多账户模式
title: OAuth
x-i18n:
generated_at: "2026-04-29T06:56:18Z"
generated_at: "2026-04-29T10:59:57Z"
model: gpt-5.5
provider: openai
source_hash: 493251e4341489e5fba9ab561d71200245d26888e10f153239d2ac8fc8fe1830
source_hash: b4b228c83a79afa4018e9572f790ddfef016a73d2383d2847facdc5bb61ed004
source_path: concepts/oauth.md
workflow: 16
---
OpenClaw 支持通过 OAuth 使用“订阅凭证”，适用于提供该能力的提供商
（尤其是 **OpenAI Codex（ChatGPT OAuth）**）。对于 Anthropic，实际划分
OpenClaw 通过 OAuth 支持提供它的提供商使用“订阅认证”
（尤其是 **OpenAI Codex（ChatGPT OAuth）**）。对于 Anthropic，实际拆分
现在是：
- **Anthropic API 密钥**：正常的 Anthropic API 计费
- **OpenClaw 内的 Anthropic Claude CLI / 订阅凭证**：Anthropic 员工
告诉我们，这种用法已再次被允许
- **Anthropic API key**：普通 Anthropic API 计费
- **Anthropic Claude CLI / OpenClaw 内的订阅认证**：Anthropic 员工
告诉我们这种用法重新被允许
OpenAI Codex OAuth 明确支持在 OpenClaw 这类外部工具中使用。本页说明：
OpenAI Codex OAuth 明确支持用于 OpenClaw 这样的外部工具。本页说明：
对于生产环境中的 Anthropic，API 密钥凭证是更安全的推荐路径。
对于生产环境中的 Anthropic，API key 认证是更安全的推荐路径。
- OAuth **令牌交换**如何工作（PKCE）
- 令牌**存储**在哪里（以及原因）
- 如何处理**多个账号**（配置文件 + 按会话覆盖）
- 如何处理**多个账户**（配置档 + 按会话覆盖）
OpenClaw 也支持**提供商插件**，这些插件会附带自己的 OAuth 或 API 密钥
OpenClaw 还支持**提供商插件**，它们会提供自己的 OAuth 或 API key
流程。通过以下命令运行：
```bash
openclaw models auth login --provider <id>
```
## 令牌接收端（为什么存在）
## 令牌汇聚点（为什么存在）
OAuth 提供商通常会在登录/刷新流程中生成一个**新的刷新令牌**。某些提供商（或 OAuth 客户端）可能会在为同一用户/应用签发新令牌时使旧的刷新令牌失效。
OAuth 提供商通常会在登录/刷新流程中签发一个**新的刷新令牌**。一些提供商（或 OAuth 客户端）可能会在为同一用户/应用签发新令牌时使旧的刷新令牌失效。
实际现象：
实际症状：
- 你通过 OpenClaw _以及_ Claude Code / Codex CLI 登录 → 之后其中一个会随机“退出登录”
- 你通过 OpenClaw _并且_ 通过 Claude Code / Codex CLI 登录 → 之后其中一个会随机“退出登录”
为减少这种情况，OpenClaw 将 `auth-profiles.json` 视为**令牌接收端**：
为减少这种情况，OpenClaw 将 `auth-profiles.json` 视为**令牌汇聚点**：
- 运行时从**一个位置**读取凭据
- 我们可以保留多个配置文件，并以确定性方式路由它们
- 外部 CLI 复用是提供商特定的：Codex CLI 可以引导一个空的
`openai-codex:default` 配置文件，但一旦 OpenClaw 拥有本地 OAuth 配置文件，
本地刷新令牌就是权威来源；其他集成可以继续由外部管理，并重新读取它们的
CLI 凭证存储
- 已经知道已配置提供商集合的 Status 和启动路径，会将外部 CLI 发现限定在
该集合内，因此单提供商设置不会探测无关的 CLI 登录存储
- 运行时从**一个位置**读取凭证
- 我们可以保留多个配置档，并以确定性的方式路由它们
- 外部 CLI 复用取决于提供商：Codex CLI 可以引导创建一个空的
`openai-codex:default` 配置档，但一旦 OpenClaw 拥有本地 OAuth 配置档，
本地刷新令牌就是权威来源；其他集成可以继续由外部管理，并重新读取它们的 CLI 认证存储
- 已经知道已配置提供商集合的 Status 和启动路径会将外部 CLI 发现范围限定到该集合，
因此在单提供商设置中不会探测无关的 CLI 登录存储
## 存储（令牌存放位置）
密钥按**每个智能体**存储：
密钥存储在智能体认证存储中：
- 凭证配置文件（OAuth + API 密钥 + 可选的值级引用）：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
- 认证配置档（OAuth + API keys + 可选值级引用）：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
- 旧版兼容文件：`~/.openclaw/agents/<agentId>/agent/auth.json`
（发现静态 `api_key` 条目时会清除）
（发现静态 `api_key` 条目时会将其清除）
仅用于旧版导入的文件（仍受支持，但不是主存储）：
- `~/.openclaw/credentials/oauth.json`（首次使用时导入到 `auth-profiles.json`）
以上全部也遵循 `$OPENCLAW_STATE_DIR`（状态目录覆盖）。完整参考：[/gateway/configuration](/zh-CN/gateway/configuration-reference#auth-storage)
以上所有路径也都遵循 `$OPENCLAW_STATE_DIR`（状态目录覆盖）。完整参考：[/gateway/configuration](/zh-CN/gateway/configuration-reference#auth-storage)
关于静态密钥引用和运行时快照激活行为，请参阅 [密钥管理](/zh-CN/gateway/secrets)。
有关静态密钥引用和运行时快照激活行为，请参阅[密钥管理](/zh-CN/gateway/secrets)。
当次要智能体没有本地认证配置档时，OpenClaw 会从默认/主智能体存储进行透读继承。它不会在读取时克隆主智能体的 `auth-profiles.json`。OAuth 刷新令牌尤其敏感：普通复制流程默认会跳过它们，因为一些提供商会在使用后轮换或使刷新令牌失效。当智能体需要独立账户时，请为该智能体配置单独的 OAuth 登录。
## Anthropic 旧版令牌兼容性
<Warning>
Anthropic 的公开 Claude Code 文档表示，直接使用 Claude Code 会保持在
Claude 订阅限制内，并且 Anthropic 员工告诉我们，OpenClaw 风格的 Claude
CLI 用法已再次被允许。因此，除非 Anthropic 发布新政策，否则 OpenClaw
会将此集成中的 Claude CLI 复用和 `claude -p` 用法视为已获认可。
Anthropic 的公开 Claude Code 文档称，直接使用 Claude Code 会保持在 Claude 订阅限制内，Anthropic 员工也告诉我们，OpenClaw 风格的 Claude CLI 用法重新被允许。因此，除非 Anthropic 发布新政策，否则 OpenClaw 会将 Claude CLI 复用和 `claude -p` 用法视为此集成中被认可的方式。
关于 Anthropic 当前的直接 Claude Code 计划文档，请参阅 [通过你的 Pro 或 Max
计划使用 Claude Code](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
和 [通过你的 Team 或 Enterprise
计划使用 Claude Code](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/)。
有关 Anthropic 当前直接使用 Claude Code 的计划文档，请参阅[将 Claude Code
与你的 Pro 或 Max
计划一起使用](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
以及[将 Claude Code 与你的 Team 或 Enterprise
计划一起使用](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/)。
如果你想在 OpenClaw 中使用其他订阅式选项，请参阅 [OpenAI
Codex](/zh-CN/providers/openai)、[Qwen Cloud Coding
@ -92,12 +91,11 @@ Plan](/zh-CN/providers/qwen)、[MiniMax Coding Plan](/zh-CN/providers/minimax)
和 [Z.AI / GLM Coding Plan](/zh-CN/providers/glm)。
</Warning>
OpenClaw 也将 Anthropic setup-token 作为受支持的令牌凭证路径公开，但现在会在可用时优先使用 Claude CLI 复用和 `claude -p`。
OpenClaw 也将 Anthropic setup-token 作为受支持的令牌认证路径公开，但现在会在可用时优先使用 Claude CLI 复用和 `claude -p`。
## Anthropic Claude CLI 迁移
OpenClaw 再次支持 Anthropic Claude CLI 复用。如果你已经在主机上有本地
Claude 登录，新手引导/配置可以直接复用它。
OpenClaw 再次支持复用 Anthropic Claude CLI。如果你已经在主机上有本地 Claude 登录，新手引导/配置可以直接复用它。
## OAuth 交换（登录如何工作）
@ -108,9 +106,9 @@ OpenClaw 的交互式登录流程在 `@mariozechner/pi-ai` 中实现，并接入
流程形态：
1. 从 OpenClaw 启动 Anthropic setup-token 或 paste-token
2. OpenClaw 将生成的 Anthropic 凭据存储到凭证配置文件中
2. OpenClaw 将生成的 Anthropic 凭证存入认证配置档
3. 模型选择保持在 `anthropic/...`
4. 现有 Anthropic 凭证配置文件仍可用于回滚/顺序控制
4. 现有 Anthropic 认证配置档仍可用于回滚/顺序控制
### OpenAI Codex（ChatGPT OAuth）
@ -121,67 +119,64 @@ OpenAI Codex OAuth 明确支持在 Codex CLI 之外使用，包括 OpenClaw 工
1. 生成 PKCE verifier/challenge + 随机 `state`
2. 打开 `https://auth.openai.com/oauth/authorize?...`
3. 尝试在 `http://127.0.0.1:1455/auth/callback` 捕获回调
4. 如果回调无法绑定（或你在远程/无头环境中），粘贴重定向 URL/代码
4. 如果无法绑定回调（或你处于远程/无头环境），粘贴重定向 URL/code
5. 在 `https://auth.openai.com/oauth/token` 交换
6. 从访问令牌中提取 `accountId`，并存储 `{ access, refresh, expires, accountId }`
向导路径是 `openclaw onboard` → 凭证选择 `openai-codex`。
向导路径是 `openclaw onboard` → 认证选择 `openai-codex`。
## 刷新 + 过期
配置文件会存储 `expires` 时间戳。
配置档会存储一个 `expires` 时间戳。
运行时：
- 如果 `expires` 在未来 → 使用存储的访问令牌
- 如果已过期 → 刷新（在文件锁下）并覆盖已存储的凭据
- 例外：某些外部 CLI 凭据仍由外部管理；OpenClaw
会重新读取这些 CLI 凭证存储，而不是消耗复制来的刷新令牌。
Codex CLI 引导被有意收窄：它会植入一个空的
`openai-codex:default` 配置文件，然后由 OpenClaw 拥有的刷新流程保持本地
配置文件为权威来源。
- 如果 `expires` 在未来 → 使用已存储的访问令牌
- 如果已过期 → 刷新（在文件锁下）并覆盖已存储的凭证
- 如果次要智能体读取继承的主智能体 OAuth 配置档，刷新会写回主智能体存储，而不是将刷新令牌复制到次要智能体存储
- 例外：一些外部 CLI 凭证仍由外部管理；OpenClaw 会重新读取这些 CLI 认证存储，而不是消耗复制过来的刷新令牌。Codex CLI 引导刻意更窄：它会播种一个空的 `openai-codex:default` 配置档，随后由 OpenClaw 拥有的刷新会保持本地配置档为权威来源。
刷新流程是自动的；你通常不需要手动管理令牌。
刷新流程是自动的；通常你不需要手动管理令牌。
## 多账号（配置文件）+ 路由
## 多账户（配置档）+ 路由
两种模式：
### 1) 推荐：独立智能体
### 1) 首选：独立智能体
如果你希望“个人”和“工作”永不交互，请使用隔离的智能体（独立会话 + 凭据 + 工作区）：
如果你希望“个人”和“工作”永不互相影响，请使用隔离的智能体（独立会话 + 凭证 + 工作区）：
```bash
openclaw agents add work
openclaw agents add personal
```
然后按智能体配置凭证（向导），并将聊天路由到正确的智能体。
然后按智能体配置认证（向导），并将聊天路由到正确的智能体。
### 2) 高级：一个智能体中的多个配置文件
### 2) 高级：一个智能体中的多个配置档
`auth-profiles.json` 支持同一提供商的多个配置文件 ID。
`auth-profiles.json` 支持同一提供商使用多个配置档 ID。
选择使用哪个配置文件：
选择要使用的配置档：
- 通过配置顺序（`auth.order`）全局选择
- 通过配置顺序全局选择（`auth.order`）
- 通过 `/model ...@<profileId>` 按会话选择
示例（会话覆盖）：
- `/model Opus@anthropic:work`
如何查看现有配置文件 ID：
如何查看存在哪些配置档 ID：
- `openclaw channels list --json`（显示 `auth[]`）
相关文档：
- [模型故障转移](/zh-CN/concepts/model-failover)（轮换 + 冷却规则）
- [斜杠命令](/zh-CN/tools/slash-commands)（命令界面）
- [斜杠命令](/zh-CN/tools/slash-commands)（命令表面）
## 相关
- [身份验证](/zh-CN/gateway/authentication) — 模型提供商凭证概览
- [密钥](/zh-CN/gateway/secrets) — 凭据存储和 SecretRef
- [配置参考](/zh-CN/gateway/configuration-reference#auth-storage) — 凭证配置键
- [认证](/zh-CN/gateway/authentication) — 模型提供商认证概览
- [密钥](/zh-CN/gateway/secrets) — 凭证存储和 SecretRef
- [配置参考](/zh-CN/gateway/configuration-reference#auth-storage) — 认证配置键

218
docs/zh-CN/help/faq-models.md
View File

@ -2,15 +2,15 @@
read_when:
- 选择或切换模型，配置别名
- 调试模型故障转移 / “所有模型均失败”
- 了解认证配置文件及其管理方式
- 了解凭证配置档案及其管理方式
sidebarTitle: Models FAQ
summary: 常见问题：模型默认值、选择、别名、切换、故障转移和凭证配置档案
summary: 常见问题：模型默认值、选择、别名、切换、故障转移和凭证配置文件
title: 常见问题：模型和凭证
x-i18n:
generated_at: "2026-04-28T11:55:43Z"
generated_at: "2026-04-29T10:59:55Z"
model: gpt-5.5
provider: openai
source_hash: f80163d645a31b07220c7a4c5bbfe79ed431facbd7232968c12095b7cd9ac4a9
source_hash: eaa72bf66d3f1528f95762e2a2763bc2f6bfddbc1d4c24a9ec2df7f943ebc14b
source_path: help/faq-models.md
workflow: 16
---
@ -22,30 +22,31 @@ x-i18n:
<AccordionGroup>
<Accordion title='什么是“默认模型”？'>
OpenClaw 的默认模型就是你设置为以下项的任何模型：
OpenClaw 的默认模型就是你设置为以下项的内容：
```
agents.defaults.model.primary
```
模型以 `provider/model` 的形式引用（例如：`openai/gpt-5.5` 或 `openai-codex/gpt-5.5`）。如果省略提供商，OpenClaw 会先尝试别名，然后尝试与该确切模型 ID 匹配的唯一已配置提供商，最后才会回退到已配置的默认提供商（这是已弃用的兼容路径）。如果该提供商不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露过时的已移除提供商默认值。你仍然应该**显式**设置 `provider/model`。
模型以 `provider/model` 形式引用（例如：`openai/gpt-5.5` 或 `openai-codex/gpt-5.5`）。如果省略提供商，OpenClaw 会先尝试别名，然后尝试与该精确模型 ID 唯一匹配的已配置提供商，最后才会回退到已配置的默认提供商；这是已弃用的兼容路径。如果该提供商不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露一个已过期的、已移除提供商的默认值。你仍应**显式**设置 `provider/model`。
</Accordion>
<Accordion title="你推荐什么模型？">
**推荐默认值：**使用你的提供商栈中可用的最强最新一代模型。
**对于启用工具或处理不受信任输入的智能体：**优先考虑模型能力，而不是成本。
**对于常规/低风险聊天：**使用更便宜的备用模型，并按智能体角色路由。
<Accordion title="你推荐使用什么模型？">
**推荐默认值：** 使用你的提供商栈中可用的最强最新一代模型。
**对于启用工具或处理不受信任输入的智能体：** 优先考虑模型能力，而不是成本。
**对于常规/低风险聊天：** 使用更便宜的回退模型，并按智能体角色路由。
MiniMax 有自己的文档：[MiniMax](/zh-CN/providers/minimax) 和
[本地模型](/zh-CN/gateway/local-models)。
经验法则：对高风险工作使用**你负担得起的最佳模型**，对常规聊天或摘要使用更便宜的
模型。你可以按智能体路由模型，并使用子智能体并行处理长任务（每个子智能体都会消耗 token）。请参阅 [Models](/zh-CN/concepts/models) 和
经验法则：对高风险工作使用你**负担得起的最佳模型**，对常规聊天或摘要使用更便宜的
模型。你可以按智能体路由模型，并使用子智能体来
并行处理长任务（每个子智能体都会消耗 token）。请参阅 [Models](/zh-CN/concepts/models) 和
[子智能体](/zh-CN/tools/subagents)。
强烈警告：较弱或过度量化的模型更容易受到提示词
注入和不安全行为的影响。请参阅 [安全](/zh-CN/gateway/security)。
强烈警告：较弱/过度量化的模型更容易受到提示词
注入和不安全行为影响。请参阅 [安全](/zh-CN/gateway/security)。
更多背景：[Models](/zh-CN/concepts/models)。
@ -61,10 +62,10 @@ x-i18n:
- `openclaw configure --section model`（交互式）
- 编辑 `~/.openclaw/openclaw.json` 中的 `agents.defaults.model`
避免对部分对象使用 `config.apply`，除非你确实打算替换整个配置。
对于 RPC 编辑，请先用 `config.schema.lookup` 检查，并优先使用 `config.patch`。lookup 载荷会给出规范化路径、浅层 schema 文档/约束，以及直接子项摘要。
避免对部分对象使用 `config.apply`，除非你确实想替换整个配置。
对于 RPC 编辑，请先用 `config.schema.lookup` 检查，并优先使用 `config.patch`。查找载荷会提供规范化路径、浅层 schema 文档/约束，以及直接子项摘要。
用于部分更新。
如果你确实覆盖了配置，请从备份恢复，或重新运行 `openclaw doctor` 进行修复。
如果你已经覆盖了配置，请从备份恢复，或重新运行 `openclaw doctor` 进行修复。
文档：[Models](/zh-CN/concepts/models)、[配置](/zh-CN/cli/configure)、[配置](/zh-CN/cli/config)、[Doctor](/zh-CN/gateway/doctor)。
@ -76,19 +77,19 @@ x-i18n:
最快设置：
1. 从 `https://ollama.com/download` 安装 Ollama
2. 拉取本地模型，例如 `ollama pull gemma4`
3. 如果你也想使用云模型，运行 `ollama signin`
2. 拉取一个本地模型，例如 `ollama pull gemma4`
3. 如果你也想使用云端模型，运行 `ollama signin`
4. 运行 `openclaw onboard` 并选择 `Ollama`
5. 选择 `Local` 或 `Cloud + Local`
注意：
- `Cloud + Local` 会提供云模型以及你的本地 Ollama 模型
- `kimi-k2.5:cloud` 等云模型不需要本地拉取
- `Cloud + Local` 会提供云端模型以及你的本地 Ollama 模型
- 像 `kimi-k2.5:cloud` 这样的云端模型不需要本地拉取
- 如需手动切换，使用 `openclaw models list` 和 `openclaw models set ollama/<model>`
安全注意事项：较小或大量量化的模型更容易受到提示词
注入影响。对于任何可以使用工具的机器人，我们强烈建议使用**大模型**。
安全注意事项：较小或高度量化的模型更容易受到提示词
注入影响。对于任何可以使用工具的机器人，我们强烈推荐使用**大模型**。
如果你仍想使用小模型，请启用沙箱隔离和严格的工具允许列表。
文档：[Ollama](/zh-CN/providers/ollama)、[本地模型](/zh-CN/gateway/local-models)、
@ -98,14 +99,14 @@ x-i18n:
</Accordion>
<Accordion title="OpenClaw、Flawd 和 Krill 使用什么模型？">
- 这些部署可能不同，并且可能随时间变化；没有固定的提供商建议。
- 这些部署可能不同，并且可能随时间变化；没有固定的提供商推荐。
- 使用 `openclaw models status` 检查每个 Gateway 网关上的当前运行时设置。
- 对于安全敏感/启用工具的智能体，请使用可用的最强最新一代模型。
</Accordion>
<Accordion title="如何即时切换模型（不重启）？">
将 `/model` 命令作为独立消息使用：
<Accordion title="如何动态切换模型（不重启）？">
将 `/model` 命令作为单独消息使用：
```
/model sonnet
@ -119,7 +120,7 @@ x-i18n:
这些是内置别名。可以通过 `agents.defaults.models` 添加自定义别名。
你可以用 `/model`、`/model list` 或 `/model status` 列出可用模型。
你可以使用 `/model`、`/model list` 或 `/model status` 列出可用模型。
`/model`（以及 `/model list`）会显示一个紧凑的编号选择器。按编号选择：
@ -135,27 +136,27 @@ x-i18n:
```
提示：`/model status` 会显示哪个智能体处于活动状态、正在使用哪个 `auth-profiles.json` 文件，以及接下来会尝试哪个身份验证配置文件。
如果可用，它还会显示已配置的提供商端点（`baseUrl`）和 API 模式（`api`）。
它还会在可用时显示已配置的提供商端点（`baseUrl`）和 API 模式（`api`）。
**如何取消固定我用 @profile 设置的配置文件？**
重新运行 `/model`，但**不要**带 `@profile` 后缀：
重新运行 `/model`，但**不要**带上 `@profile` 后缀：
```
/model anthropic/claude-opus-4-6
```
如果你想返回默认值，请从 `/model` 中选择它（或发送 `/model <default provider/model>`）。
如果你想回到默认值，请从 `/model` 中选择它（或发送 `/model <default provider/model>`）。
使用 `/model status` 确认哪个身份验证配置文件处于活动状态。
</Accordion>
<Accordion title="我可以将 GPT 5.5 用于日常任务，将 Codex 5.5 用于编码吗？">
<Accordion title="我可以用 GPT 5.5 处理日常任务，用 Codex 5.5 编码吗？">
可以。将其中一个设为默认值，并按需切换：
- **快速切换（按会话）：**对当前直接 OpenAI API key 任务使用 `/model openai/gpt-5.5`，或对 GPT-5.5 Codex OAuth 任务使用 `/model openai-codex/gpt-5.5`。
- **默认值：**将 `agents.defaults.model.primary` 设置为 `openai/gpt-5.5` 以使用 API key，或设置为 `openai-codex/gpt-5.5` 以使用 GPT-5.5 Codex OAuth。
- **子智能体：**将编码任务路由到使用不同默认模型的子智能体。
- **快速切换（按会话）：** 对当前直接 OpenAI API key 任务使用 `/model openai/gpt-5.5`，或对 GPT-5.5 Codex OAuth 任务使用 `/model openai-codex/gpt-5.5`。
- **默认值：** 对 API key 用法，将 `agents.defaults.model.primary` 设置为 `openai/gpt-5.5`；对 GPT-5.5 Codex OAuth 用法，将其设置为 `openai-codex/gpt-5.5`。
- **子智能体：** 将编码任务路由到使用不同默认模型的子智能体。
请参阅 [Models](/zh-CN/concepts/models) 和 [斜杠命令](/zh-CN/tools/slash-commands)。
@ -164,8 +165,8 @@ x-i18n:
<Accordion title="如何为 GPT 5.5 配置快速模式？">
使用会话开关或配置默认值：
- **按会话：**在会话使用 `openai/gpt-5.5` 或 `openai-codex/gpt-5.5` 时发送 `/fast on`。
- **按模型默认值：**将 `agents.defaults.models["openai/gpt-5.5"].params.fastMode` 或 `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` 设置为 `true`。
- **按会话：** 当会话使用 `openai/gpt-5.5` 或 `openai-codex/gpt-5.5` 时发送 `/fast on`。
- **按模型默认值：** 将 `agents.defaults.models["openai/gpt-5.5"].params.fastMode` 或 `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` 设置为 `true`。
示例：
@ -185,40 +186,40 @@ x-i18n:
}
```
对于 OpenAI，在受支持的原生 Responses 请求中，快速模式映射到 `service_tier = "priority"`。会话 `/fast` 覆盖优先于配置默认值。
对于 OpenAI，快速模式会在支持的原生 Responses 请求上映射为 `service_tier = "priority"`。会话 `/fast` 覆盖优先于配置默认值。
请参阅 [思考和快速模式](/zh-CN/tools/thinking) 以及 [OpenAI 快速模式](/zh-CN/providers/openai#fast-mode)。
</Accordion>
<Accordion title='为什么我看到“Model ... is not allowed”，然后没有回复？'>
如果设置了 `agents.defaults.models`，它就会成为 `/model` 和任何
会话覆盖项的**允许列表**。选择不在该列表中的模型会返回：
<Accordion title='为什么我会看到“Model ... is not allowed”，然后没有回复？'>
如果设置了 `agents.defaults.models`，它会成为 `/model` 和任何
会话覆盖的**允许列表**。选择不在该列表中的模型会返回：
```
Model "provider/model" is not allowed. Use /model to list available models.
```
该错误会被返回，**而不是**正常回复。修复方法：将模型添加到
`agents.defaults.models`，移除允许列表，或从 `/model list` 中选择模型。
`agents.defaults.models`，移除允许列表，或从 `/model list` 中选择一个模型。
</Accordion>
<Accordion title='为什么我看到“Unknown model: minimax/MiniMax-M2.7”？'>
这表示**提供商未配置**（未找到 MiniMax 提供商配置或身份验证
<Accordion title='为什么我会看到“Unknown model: minimax/MiniMax-M2.7”？'>
这意味着**提供商未配置**（未找到 MiniMax 提供商配置或身份验证
配置文件），因此无法解析模型。
修复清单：
1. 升级到当前 OpenClaw 版本（或从源码 `main` 运行），然后重启 Gateway 网关。
2. 确保 MiniMax 已配置（向导或 JSON），或者 MiniMax 身份验证
存在于环境/身份验证配置文件中，以便可以注入匹配的提供商
2. 确保 MiniMax 已配置（向导或 JSON），或者确保 MiniMax 身份验证
存在于环境变量/身份验证配置文件中，以便可以注入匹配的提供商
（`MINIMAX_API_KEY` 用于 `minimax`，`MINIMAX_OAUTH_TOKEN` 或存储的 MiniMax
OAuth 用于 `minimax-portal`）。
3. 为你的身份验证路径使用确切的模型 ID（区分大小写）：
API key 设置使用 `minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed`，
OAuth 设置使用 `minimax-portal/MiniMax-M2.7` /
`minimax-portal/MiniMax-M2.7-highspeed`。
3. 为你的身份验证路径使用精确模型 ID（区分大小写）：
`minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed` 用于 API key
设置，或者 `minimax-portal/MiniMax-M2.7` /
`minimax-portal/MiniMax-M2.7-highspeed` 用于 OAuth 设置。
4. 运行：
```bash
@ -231,9 +232,9 @@ x-i18n:
</Accordion>
<Accordion title="我可以将 MiniMax 作为默认模型，并将 OpenAI 用于复杂任务吗？">
<Accordion title="我可以把 MiniMax 作为默认值，并将 OpenAI 用于复杂任务吗？">
可以。将 **MiniMax 作为默认值**，并在需要时**按会话**切换模型。
备用项用于**错误**，不是用于“困难任务”，因此请使用 `/model` 或单独的智能体。
回退用于**错误**，而不是“困难任务”，因此请使用 `/model` 或单独的智能体。
**选项 A：按会话切换**
@ -260,8 +261,8 @@ x-i18n:
**选项 B：单独的智能体**
- 智能体 A 默认：MiniMax
- 智能体 B 默认：OpenAI
- 智能体 A 默认值：MiniMax
- 智能体 B 默认值：OpenAI
- 按智能体路由，或使用 `/agent` 切换
文档：[Models](/zh-CN/concepts/models)、[多智能体路由](/zh-CN/concepts/multi-agent)、[MiniMax](/zh-CN/providers/minimax)、[OpenAI](/zh-CN/providers/openai)。
@ -269,18 +270,18 @@ x-i18n:
</Accordion>
<Accordion title="opus / sonnet / gpt 是内置快捷方式吗？">
是。OpenClaw 附带一些默认简写（仅当模型存在于 `agents.defaults.models` 中时应用）：
是。OpenClaw 附带了一些默认简写（仅在模型存在于 `agents.defaults.models` 中时应用）：
- `opus` → `anthropic/claude-opus-4-6`
- `sonnet` → `anthropic/claude-sonnet-4-6`
- `gpt` → API key 设置中的 `openai/gpt-5.5`，或配置为 Codex OAuth 时的 `openai-codex/gpt-5.5`
- `gpt` → `openai/gpt-5.5` 用于 API key 设置，或在配置为 Codex OAuth 时指向 `openai-codex/gpt-5.5`
- `gpt-mini` → `openai/gpt-5.4-mini`
- `gpt-nano` → `openai/gpt-5.4-nano`
- `gemini` → `google/gemini-3.1-pro-preview`
- `gemini-flash` → `google/gemini-3-flash-preview`
- `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview`
如果你设置了同名的自定义别名，你的值优先。
如果你用相同名称设置自己的别名，你的值优先。
</Accordion>
@ -307,7 +308,7 @@ x-i18n:
</Accordion>
<Accordion title="如何添加来自 OpenRouter 或 Z.AI 等其他提供商的模型？">
OpenRouter（按 token 付费；模型众多）：
OpenRouter（按 token 付费；模型很多）：
```json5
{
@ -335,11 +336,12 @@ x-i18n:
}
```
如果你引用了某个提供商/模型，但缺少所需的提供商密钥，会收到运行时凭证错误（例如 `No API key found for provider "zai"`）。
如果你引用某个提供商/模型，但缺少所需的提供商密钥，会收到运行时凭证错误（例如 `No API key found for provider "zai"`）。
**添加新智能体后找不到提供商的 API 密钥**
这通常意味着**新智能体**的凭证存储为空。凭证按智能体区分，并存储在：
这通常表示**新智能体**的凭证存储为空。凭证按智能体隔离，并
存储在：
```
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
@ -347,10 +349,11 @@ x-i18n:
修复选项：
- 运行 `openclaw agents add <id>` 并在向导中配置凭证。
- 或者将主智能体 `agentDir` 中的 `auth-profiles.json` 复制到新智能体的 `agentDir` 中。
- 运行 `openclaw agents add <id>`，并在向导中配置凭证。
- 或者只把可移植的静态 `api_key` / `token` 配置档案从主智能体的凭证存储复制到新智能体的凭证存储。
- 对于 OAuth 配置档案，当新智能体需要自己的账号时，请从新智能体登录；否则 OpenClaw 可以透传读取默认/主智能体，而无需克隆刷新令牌。
**不要**在多个智能体之间复用 `agentDir`；这会导致凭证/会话冲突。
不要在多个智能体之间复用 `agentDir`；这会导致凭证/会话冲突。
</Accordion>
</AccordionGroup>
@ -364,44 +367,43 @@ x-i18n:
1. 同一提供商内的**凭证配置档案轮换**。
2. **模型回退**到 `agents.defaults.model.fallbacks` 中的下一个模型。
冷却会应用于失败的配置档案（指数退避），因此即使某个提供商受到速率限制或暂时失败，OpenClaw 也可以继续响应。
冷却会应用于失败的配置档案（指数退避），因此即使某个提供商被限流或暂时失败，OpenClaw 也可以继续响应。
速率限制分组包含的不只是普通的 `429` 响应。OpenClaw
还会把 `Too many concurrent requests`、
限流桶包含的不只是普通的 `429` 响应。OpenClaw
也会把 `Too many concurrent requests`、
`ThrottlingException`、`concurrency limit reached`、
`workers_ai ... quota limit exceeded`、`resource exhausted`，以及周期性
用量窗口限制（`weekly/monthly limit reached`）这类消息视为值得故障转移的
速率限制。
使用窗口限制（`weekly/monthly limit reached`）等消息视为值得触发故障转移的
限流。
有些看起来像计费问题的响应并不是 `402`，而有些 HTTP `402`
响应也会留在这个临时分组中。如果提供商在 `401` 或 `403` 上返回
明确的计费文本，OpenClaw 仍然可以将其保留在
计费通道中，但提供商特定的文本匹配器会限定在拥有它们的
提供商范围内（例如 OpenRouter `Key limit exceeded`）。如果 `402`
消息看起来更像可重试的用量窗口或
组织/工作区花费限制（`daily limit reached, resets tomorrow`、
有些看起来像计费的响应不是 `402`，而有些 HTTP `402`
响应也会留在这个临时桶中。如果提供商在 `401` 或 `403` 上返回
明确的计费文本，OpenClaw 仍可将其保留在
计费通道中，但提供商专属的文本匹配器仍限定在拥有它们的
提供商范围内（例如 OpenRouter 的 `Key limit exceeded`）。如果 `402`
消息反而看起来像可重试的使用窗口限制或
组织/工作区支出限制（`daily limit reached, resets tomorrow`、
`organization spending limit exceeded`），OpenClaw 会将其视为
`rate_limit`，而不是长期计费停用。
`rate_limit`，而不是长期计费禁用。
上下文溢出错误不同：诸如
`request_too_large`、`input exceeds the maximum number of tokens`、
`input token count exceeds the maximum number of input tokens`、
`input is too long for the model`，或 `ollama error: context length
exceeded` 这样的签名会留在压缩/重试路径上，而不是推进模型
exceeded` 这样的签名会留在压缩/重试路径上，而不会推进模型
回退。
通用服务器错误文本有意比“任何包含
unknown/error 的内容”更窄。OpenClaw 确实会把提供商限定的临时形态
视为值得故障转移的超时/过载信号，例如 Anthropic 裸
`An unknown error occurred`、OpenRouter 裸
`Provider returned error`、像 `Unhandled stop reason:
error` 这样的停止原因错误、带有临时服务器文本
unknown/error 的内容”更窄。OpenClaw 确实会在提供商上下文
匹配时，把提供商范围内的临时形态视为值得触发故障转移的超时/过载信号，
例如 Anthropic 裸 `An unknown error occurred`、OpenRouter 裸
`Provider returned error`、类似 `Unhandled stop reason:
error` 的停止原因错误、带有临时服务器文本
（`internal server error`、`unknown error, 520`、`upstream error`、`backend
error`）的 JSON `api_error` 载荷，以及像 `ModelNotReadyException` 这样的
提供商繁忙错误，前提是提供商上下文
匹配。
像 `LLM request failed with an unknown
error.` 这样的通用内部回退文本会保持保守，本身不会触发模型回退。
error`）的 JSON `api_error` 载荷，以及类似 `ModelNotReadyException` 的
提供商繁忙错误。
类似 `LLM request failed with an unknown
error.` 的通用内部回退文本会保持保守，单独出现时不会触发模型回退。
</Accordion>
@ -410,7 +412,7 @@ x-i18n:
**修复检查清单：**
- **确认凭证配置档案存放位置**（新路径与旧路径）
- **确认凭证配置档案的存放位置**（新路径与旧路径）
- 当前：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
- 旧版：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移）
- **确认你的环境变量已由 Gateway 网关加载**
@ -418,46 +420,46 @@ x-i18n:
- **确保你正在编辑正确的智能体**
- 多智能体设置意味着可能存在多个 `auth-profiles.json` 文件。
- **对模型/凭证状态做完整性检查**
- 使用 `openclaw models status` 查看已配置的模型以及提供商是否已完成身份验证。
- 使用 `openclaw models status` 查看已配置的模型以及提供商是否已完成凭证配置。
**“No credentials found for profile anthropic” 的修复检查清单**
这表示本次运行被固定到一个 Anthropic 凭证配置档案，但 Gateway 网关
无法在它的凭证存储中找到该配置档案。
这表示此次运行被固定到某个 Anthropic 凭证配置档案，但 Gateway 网关
无法在其凭证存储中找到它。
- **使用 Claude CLI**
- 在 Gateway 网关主机上运行 `openclaw models auth login --provider anthropic --method cli --set-default`。
- **如果你想改用 API 密钥**
- 将 `ANTHROPIC_API_KEY` 放到 **Gateway 网关主机** 上的 `~/.openclaw/.env` 中。
- 在 **Gateway 网关主机** 上把 `ANTHROPIC_API_KEY` 放入 `~/.openclaw/.env`。
- 清除任何强制使用缺失配置档案的固定顺序：
```bash
openclaw models auth order clear --provider anthropic
```
- **确认你是在 Gateway 网关主机上运行命令**
- 在远程模式下，凭证配置档案存放在 Gateway 网关机器上，而不是你的笔记本电脑上。
- **确认你正在 Gateway 网关主机上运行命令**
- 在远程模式下，凭证配置档案存在于 Gateway 网关机器上，而不是你的笔记本电脑上。
</Accordion>
<Accordion title="为什么它还尝试了 Google Gemini 并失败？">
如果你的模型配置包含 Google Gemini 作为回退模型（或者你切换到了 Gemini 简写），OpenClaw 会在模型回退期间尝试它。如果你尚未配置 Google 凭证，会看到 `No API key found for provider "google"`。
如果你的模型配置包含 Google Gemini 作为回退项（或你切换到了 Gemini 简写），OpenClaw 会在模型回退期间尝试它。如果你没有配置 Google 凭证，会看到 `No API key found for provider "google"`。
修复：提供 Google 凭证，或者从 `agents.defaults.model.fallbacks` / 别名中移除或避免使用 Google 模型，这样回退就不会路由到那里。
修复：提供 Google 凭证，或从 `agents.defaults.model.fallbacks` / 别名中移除/避免 Google 模型，这样回退就不会路由到那里。
**LLM 请求被拒绝：需要 thinking 签名（Google Antigravity）**
原因：会话历史包含**没有签名的 thinking 块**（通常来自
中止/不完整的流）。Google Antigravity 要求 thinking 块带有签名。
已中止/不完整的流）。Google Antigravity 要求 thinking 块带签名。
修复：OpenClaw 现在会为 Google Antigravity Claude 去除未签名的 thinking 块。如果仍然出现，请启动一个**新会话**，或为该智能体设置 `/thinking off`。
修复：OpenClaw 现在会为 Google Antigravity Claude 剥离未签名的 thinking 块。如果它仍然出现，请启动一个**新会话**，或为该智能体设置 `/thinking off`。
</Accordion>
</AccordionGroup>
## 凭证配置档案：它们是什么以及如何管理
相关：[/concepts/oauth](/zh-CN/concepts/oauth)（OAuth 流程、令牌存储、多账户模式）
相关：[/concepts/oauth](/zh-CN/concepts/oauth)（OAuth 流程、令牌存储、多账号模式）
<AccordionGroup>
<Accordion title="什么是凭证配置档案？">
@ -478,14 +480,14 @@ x-i18n:
</Accordion>
<Accordion title="我可以控制优先尝试哪个凭证配置档案吗？">
可以。配置支持为配置档案添加可选元数据，并按提供商设置顺序（`auth.order.<provider>`）。这**不会**存储密钥；它会将 ID 映射到提供商/模式，并设置轮换顺序。
<Accordion title="我可以控制先尝试哪个凭证配置档案吗？">
可以。配置支持为配置档案提供可选元数据，并为每个提供商设置顺序（`auth.order.<provider>`）。这**不会**存储秘密；它会把 ID 映射到提供商/模式，并设置轮换顺序。
如果某个配置档案处于短暂**冷却**状态（速率限制/超时/凭证失败）或较长的**停用**状态（计费/余额不足），OpenClaw 可能会暂时跳过它。要检查这一点，运行 `openclaw models status --json` 并查看 `auth.unusableProfiles`。调优项：`auth.cooldowns.billingBackoffHours*`。
如果某个配置档案处于短暂**冷却**（限流/超时/凭证失败）或较长的**禁用**状态（计费/额度不足），OpenClaw 可能会暂时跳过它。要检查这一点，请运行 `openclaw models status --json` 并查看 `auth.unusableProfiles`。调优项：`auth.cooldowns.billingBackoffHours*`。
速率限制冷却可以限定到模型。某个配置档案如果正在因一个模型冷却，
仍可能可用于同一提供商上的同级模型，
而计费/停用窗口仍会阻止整个配置档案。
限流冷却可以按模型限定。某个配置档案如果正在因
一个模型冷却，它仍可能可用于同一提供商上的兄弟模型，
而计费/禁用窗口仍会阻止整个配置档案。
你还可以通过 CLI 设置**按智能体**的顺序覆盖（存储在该智能体的 `auth-state.json` 中）：
@ -515,16 +517,16 @@ x-i18n:
openclaw models status --probe
```
如果存储的配置档案被显式顺序省略，探测会为该配置档案报告
如果存储的配置档案被显式顺序省略，probe 会为该配置档案报告
`excluded_by_auth_order`，而不是静默尝试它。
</Accordion>
<Accordion title="OAuth 与 API 密钥有什么区别？">
<Accordion title="OAuth 和 API 密钥有什么区别？">
OpenClaw 两者都支持：
- **OAuth** 通常会利用订阅访问权限（在适用时）。
- **API 密钥** 使用按令牌付费的计费方式。
- **OAuth** 通常会利用订阅访问权限（如适用）。
- **API 密钥** 使用按令牌计费。
向导明确支持 Anthropic Claude CLI、OpenAI Codex OAuth 和 API 密钥。

68
docs/zh-CN/tools/multi-agent-sandbox-tools.md
View File

@ -2,33 +2,33 @@
read_when: You want per-agent sandboxing or per-agent tool allow/deny policies in a multi-agent gateway.
sidebarTitle: Multi-agent sandbox and tools
status: active
summary: 按智能体设置的沙箱 + 工具限制、优先级和示例
summary: 每个智能体的沙箱 + 工具限制、优先级和示例
title: 多智能体沙箱和工具
x-i18n:
generated_at: "2026-04-28T12:05:40Z"
generated_at: "2026-04-29T10:59:30Z"
model: gpt-5.5
provider: openai
source_hash: d6c43b9ff881d05c49f3e9d93859dd620e7b8e9febfddb16b7a9fd8b8e331e65
source_hash: eedb36301f670bcd8956dbeb81788acfc96627e39401e34434c2348fcb10f155
source_path: tools/multi-agent-sandbox-tools.md
workflow: 16
---
每个多智能体设置中的智能体都可以覆盖全局沙箱和工具策略。本页介绍按智能体配置、优先级规则和示例。
每个多智能体设置中的智能体都可以覆盖全局沙箱和工具策略。本页介绍每智能体配置、优先级规则和示例。
<CardGroup cols={3}>
<Card title="沙箱隔离" href="/zh-CN/gateway/sandboxing">
后端和模式 — 完整沙箱参考。
</Card>
<Card title="沙箱与工具策略与提权" href="/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated">
<Card title="沙箱 vs 工具策略 vs 提权" href="/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated">
调试“为什么这被阻止了？”
</Card>
<Card title="提权模式" href="/zh-CN/tools/elevated">
面向受信发送者的提权 exec。
面向受信任发送者的提权 exec。
</Card>
</CardGroup>
<Warning>
凭证按智能体隔离：每个智能体都会从自己的 `agentDir` 凭证存储读取，位置是 `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`。凭据**不会**在智能体之间共享。切勿在多个智能体之间复用 `agentDir`。如果你想共享凭据，请将 `auth-profiles.json` 复制到另一个智能体的 `agentDir`。
凭证按智能体划分作用域：每个智能体都有自己的 `agentDir` 凭证存储，位于 `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`。切勿在多个智能体之间复用 `agentDir`。当智能体没有本地配置文件时，可以读取默认/主智能体的凭证配置文件，但 OAuth 刷新令牌不会克隆到次级智能体存储中。如果手动复制凭证，只复制可移植的静态 `api_key` 或 `token` 配置文件。
</Warning>
---
@ -36,7 +36,7 @@ x-i18n:
## 配置示例
<AccordionGroup>
<Accordion title="示例 1：个人智能体 + 受限家庭智能体">
<Accordion title="示例 1：个人 + 受限家庭智能体">
```json
{
"agents": {
@ -175,11 +175,11 @@ x-i18n:
## 配置优先级
当全局配置（`agents.defaults.*`）和智能体特定配置（`agents.list[].*`）同时存在时：
当全局（`agents.defaults.*`）和智能体专属（`agents.list[].*`）配置同时存在时：
### 沙箱配置
智能体特定设置会覆盖全局设置：
智能体专属设置会覆盖全局设置：
```
agents.list[].sandbox.mode > agents.defaults.sandbox.mode
@ -192,7 +192,7 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
```
<Note>
`agents.list[].sandbox.{docker,browser,prune}.*` 会覆盖该智能体的 `agents.defaults.sandbox.{docker,browser,prune}.*`（当沙箱 scope 解析为 `"shared"` 时忽略）。
`agents.list[].sandbox.{docker,browser,prune}.*` 会为该智能体覆盖 `agents.defaults.sandbox.{docker,browser,prune}.*`（当沙箱作用域解析为 `"shared"` 时忽略）。
</Note>
### 工具限制
@ -200,10 +200,10 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
过滤顺序如下：
<Steps>
<Step title="工具 profile">
<Step title="工具配置文件">
`tools.profile` 或 `agents.list[].tools.profile`。
</Step>
<Step title="提供商工具 profile">
<Step title="提供商工具配置文件">
`tools.byProvider[provider].profile` 或 `agents.list[].tools.byProvider[provider].profile`。
</Step>
<Step title="全局工具策略">
@ -212,7 +212,7 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
<Step title="提供商工具策略">
`tools.byProvider[provider].allow/deny`。
</Step>
<Step title="智能体特定工具策略">
<Step title="智能体专属工具策略">
`agents.list[].tools.allow/deny`。
</Step>
<Step title="智能体提供商策略">
@ -222,7 +222,7 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
`tools.sandbox.tools` 或 `agents.list[].tools.sandbox.tools`。
</Step>
<Step title="子智能体工具策略">
`tools.subagents.tools`，如适用。
`tools.subagents.tools`，如果适用。
</Step>
</Steps>
@ -231,24 +231,24 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
- 每一层都可以进一步限制工具，但不能重新授予前面层级已拒绝的工具。
- 如果设置了 `agents.list[].tools.sandbox.tools`，它会替换该智能体的 `tools.sandbox.tools`。
- 如果设置了 `agents.list[].tools.profile`，它会覆盖该智能体的 `tools.profile`。
- 提供商工具键既可以接受 `provider`（例如 `google-antigravity`），也可以接受 `provider/model`（例如 `openai/gpt-5.4`）。
- 提供商工具键可以接受 `provider`（例如 `google-antigravity`）或 `provider/model`（例如 `openai/gpt-5.4`）。
</Accordion>
<Accordion title="空允许列表行为">
如果该链中的任何显式允许列表让本次运行没有可调用工具，OpenClaw 会在向模型提交提示之前停止。这是有意设计的：配置了缺失工具的智能体，例如 `agents.list[].tools.allow: ["query_db"]`，应当在注册 `query_db` 的插件启用之前明确失败，而不是继续作为纯文本智能体运行。
如果该链路中的任何显式允许列表导致本次运行没有可调用工具，OpenClaw 会在向模型提交提示词之前停止。这是有意设计的：配置了缺失工具（例如 `agents.list[].tools.allow: ["query_db"]`）的智能体应当明确失败，直到注册 `query_db` 的插件被启用，而不是继续作为纯文本智能体运行。
</Accordion>
</AccordionGroup>
工具策略支持 `group:*` 简写，它们会展开为多个工具。完整列表见[工具组](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated#tool-groups-shorthands)。
工具策略支持会展开为多个工具的 `group:*` 简写。完整列表见[工具组](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated#tool-groups-shorthands)。
按智能体提权覆盖（`agents.list[].tools.elevated`）可以进一步限制特定智能体的提权 exec。详情见[提权模式](/zh-CN/tools/elevated)。
每智能体提权覆盖（`agents.list[].tools.elevated`）可以进一步限制特定智能体的提权 exec。详情见[提权模式](/zh-CN/tools/elevated)。
---
## 从单智能体迁移
<Tabs>
<Tab title="之前（单智能体）">
<Tab title="迁移前（单智能体）">
```json
{
"agents": {
@ -270,7 +270,7 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
}
```
</Tab>
<Tab title="之后（多智能体）">
<Tab title="迁移后（多智能体）">
```json
{
"agents": {
@ -289,7 +289,7 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
</Tabs>
<Note>
旧版 `agent.*` 配置会由 `openclaw doctor` 迁移；后续优先使用 `agents.defaults` + `agents.list`。
旧版 `agent.*` 配置会由 `openclaw doctor` 迁移；以后优先使用 `agents.defaults` + `agents.list`。
</Note>
---
@ -328,17 +328,17 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
}
```
此 profile 中的 `sessions_history` 仍会返回有界且经过清理的回忆视图，而不是原始转录转储。助手回忆会在脱敏/截断前移除 thinking 标签、`<relevant-memories>` 脚手架、纯文本工具调用 XML 负载（包括 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>`，以及被截断的工具调用块）、降级后的工具调用脚手架、泄漏的 ASCII/全角模型控制 token，以及格式异常的 MiniMax 工具调用 XML。
此配置文件中的 `sessions_history` 仍会返回有界且经过净化的回忆视图，而不是原始转录转储。助手回忆会在重打码/截断前移除思考标签、`<relevant-memories>` 脚手架、纯文本工具调用 XML 载荷（包括 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>` 和被截断的工具调用块）、降级后的工具调用脚手架、泄露的 ASCII/全角模型控制令牌，以及格式错误的 MiniMax 工具调用 XML。
</Tab>
</Tabs>
---
## 常见陷阱：`non-main`
## 常见陷阱：“non-main”
<Warning>
`agents.defaults.sandbox.mode: "non-main"` 基于 `session.mainKey`（默认为 `"main"`），而不是智能体 ID。群组/渠道会话始终获得自己的键，因此会被视为非 main 并被沙箱隔离。如果你希望某个智能体永远不进入沙箱，请设置 `agents.list[].sandbox.mode: "off"`。
`agents.defaults.sandbox.mode: "non-main"` 基于 `session.mainKey`（默认 `"main"`），而不是智能体 ID。群组/渠道会话始终获得自己的键，因此会被视为非主会话并被沙箱隔离。如果你希望某个智能体永不使用沙箱，请设置 `agents.list[].sandbox.mode: "off"`。
</Warning>
---
@ -360,7 +360,7 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
</Step>
<Step title="测试工具限制">
- 发送一条需要受限工具的消息。
- 验证智能体无法使用被拒绝的工具。
- 验证智能体不能使用被拒绝的工具。
</Step>
<Step title="监控日志">
@ -375,20 +375,20 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
## 故障排除
<AccordionGroup>
<Accordion title="尽管设置了 `mode: 'all'`，智能体仍未被沙箱隔离">
- 检查是否存在覆盖它的全局 `agents.defaults.sandbox.mode`。
- 智能体特定配置优先，因此请设置 `agents.list[].sandbox.mode: "all"`。
<Accordion title="尽管 `mode: 'all'`，智能体仍未被沙箱隔离">
- 检查是否存在会覆盖它的全局 `agents.defaults.sandbox.mode`。
- 智能体专属配置优先，因此请设置 `agents.list[].sandbox.mode: "all"`。
</Accordion>
<Accordion title="尽管有 deny list，工具仍可用">
<Accordion title="尽管有拒绝列表，工具仍可用">
- 检查工具过滤顺序：全局 → 智能体 → 沙箱 → 子智能体。
- 每一层只能进一步限制，不能重新授予。
- 使用日志验证：`[tools] filtering tools for agent:${agentId}`。
</Accordion>
<Accordion title="容器未按智能体隔离">
- 在智能体特定沙箱配置中设置 `scope: "agent"`。
- 默认值是 `"session"`，即每个会话创建一个容器。
- 在智能体专属沙箱配置中设置 `scope: "agent"`。
- 默认值为 `"session"`，这会为每个会话创建一个容器。
</Accordion>
</AccordionGroup>
@ -400,6 +400,6 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
- [提权模式](/zh-CN/tools/elevated)
- [多智能体路由](/zh-CN/concepts/multi-agent)
- [沙箱配置](/zh-CN/gateway/config-agents#agentsdefaultssandbox)
- [沙箱与工具策略与提权](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated) — 调试“为什么这被阻止了？”
- [沙箱隔离](/zh-CN/gateway/sandboxing) — 完整沙箱参考（模式、scope、后端、镜像）
- [沙箱 vs 工具策略 vs 提权](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated) — 调试“为什么这被阻止了？”
- [沙箱隔离](/zh-CN/gateway/sandboxing) — 完整沙箱参考（模式、作用域、后端、镜像）
- [会话管理](/zh-CN/concepts/session)