chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
46f3fa770c
commit
dfd36c5e2e
@ -2,21 +2,21 @@
|
||||
read_when:
|
||||
- 说明入站消息如何变成回复
|
||||
- 说明会话、排队模式或流式传输行为
|
||||
- 记录推理可见性和用量影响
|
||||
- 记录推理可见性和使用影响
|
||||
summary: 消息流、会话、排队和推理可见性
|
||||
title: 消息
|
||||
x-i18n:
|
||||
generated_at: "2026-04-29T05:40:11Z"
|
||||
generated_at: "2026-04-29T21:52:59Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: d5db090a990c48c03f6dc010e211523590d4743aaa0e86fa76bfda0f001e5def
|
||||
source_hash: 32e11bec46190e37fa6ce13ff876fe7c04299ae16a3690e5bbfac1d308071660
|
||||
source_path: concepts/messages.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw 通过一条包含会话解析、排队、流式传输、工具执行和推理可见性的流水线处理入站消息。本页说明从入站消息到回复的路径。
|
||||
OpenClaw 通过一条包含会话解析、排队、流式传输、工具执行和推理可见性的流水线处理入站消息。本页展示从入站消息到回复的路径。
|
||||
|
||||
## 消息流程（高层）
|
||||
## 消息流（高层级）
|
||||
|
||||
```
|
||||
Inbound message
|
||||
@ -26,7 +26,7 @@ Inbound message
|
||||
-> outbound replies (channel limits + chunking)
|
||||
```
|
||||
|
||||
关键开关位于配置中：
|
||||
关键旋钮位于配置中：
|
||||
|
||||
- `messages.*` 用于前缀、排队和群组行为。
|
||||
- `agents.defaults.*` 用于分块流式传输和分块默认值。
|
||||
@ -36,13 +36,13 @@ Inbound message
|
||||
|
||||
## 入站去重
|
||||
|
||||
渠道在重新连接后可能会重新投递同一条消息。OpenClaw 会保留一个短生命周期缓存，以渠道/账号/对端/会话/消息 ID 为键，确保重复投递不会触发另一次智能体运行。
|
||||
渠道在重新连接后可能会重新投递同一条消息。OpenClaw 会保留一个短生命周期缓存，按渠道/账号/对端/会话/消息 ID 建键，因此重复投递不会触发另一次智能体运行。
|
||||
|
||||
## 入站防抖
|
||||
|
||||
来自**同一发送者**的快速连续消息可以通过 `messages.inbound` 批处理成单个智能体轮次。防抖按渠道 + 对话限定范围，并使用最新消息进行回复串联/ID 关联。
|
||||
来自**同一发送者**的快速连续消息可以通过 `messages.inbound` 批处理为单个智能体轮次。防抖按渠道 + 对话限定作用域，并使用最新消息进行回复串接/ID 处理。
|
||||
|
||||
配置（全局默认值 + 按渠道覆盖）：
|
||||
配置（全局默认 + 按渠道覆盖）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -61,18 +61,18 @@ Inbound message
|
||||
|
||||
注意：
|
||||
|
||||
- 防抖适用于**仅文本**消息；媒体/附件会立即刷新。
|
||||
- 控制命令会绕过防抖，以便保持独立；**例外情况**是某个渠道显式选择加入同一发送者私信合并（例如 [BlueBubbles `coalesceSameSenderDms`](/zh-CN/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)），这时私信命令会在防抖窗口内等待，以便拆分发送的载荷可以加入同一个智能体轮次。
|
||||
- 防抖适用于**纯文本**消息；媒体/附件会立即刷新。
|
||||
- 控制命令会绕过防抖，因此保持独立，**除非**某个渠道显式选择启用同发送者私信合并（例如 [BlueBubbles `coalesceSameSenderDms`](/zh-CN/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)），此时私信命令会在防抖窗口内等待，以便拆分发送的载荷可以加入同一个智能体轮次。
|
||||
|
||||
## 会话和设备
|
||||
|
||||
会话由 Gateway 网关拥有，而不是由客户端拥有。
|
||||
|
||||
- 直接聊天会折叠到智能体主会话键中。
|
||||
- 直接聊天会折叠到智能体主会话键。
|
||||
- 群组/渠道会获得自己的会话键。
|
||||
- 会话存储和转录记录位于 Gateway 网关主机上。
|
||||
|
||||
多个设备/渠道可以映射到同一个会话，但历史记录不会完整同步回每个客户端。建议：长对话使用一个主设备，以避免上下文分歧。Control UI 和 TUI 始终显示由 Gateway 网关支持的会话转录记录，因此它们是真实来源。
|
||||
多个设备/渠道可以映射到同一个会话，但历史记录不会完全同步回每个客户端。建议：为长对话使用一个主设备，以避免上下文分叉。Control UI 和 TUI 始终显示由 Gateway 网关支持的会话转录记录，因此它们是事实来源。
|
||||
|
||||
详情：[会话管理](/zh-CN/concepts/session)。
|
||||
|
||||
@ -83,8 +83,8 @@ Inbound message
|
||||
OpenClaw 会明确保持这条边界：
|
||||
|
||||
- `toolResult.details` 会在提供商重放和压缩输入之前被剥离。
|
||||
- 持久化的会话转录记录只保留有界的 `details`；过大的元数据会替换为标记了 `persistedDetailsTruncated: true` 的紧凑摘要。
|
||||
- 插件和工具应将模型必须读取的文本放在 `content` 中，而不只是放在 `details` 中。
|
||||
- 持久化的会话转录记录只保留有界的 `details`；过大的元数据会被替换为带有 `persistedDetailsTruncated: true` 标记的紧凑摘要。
|
||||
- 插件和工具应将模型必须读取的文本放入 `content`，而不是只放在 `details` 中。
|
||||
|
||||
## 入站正文和历史上下文
|
||||
|
||||
@ -94,29 +94,30 @@ OpenClaw 会区分**提示正文**和**命令正文**：
|
||||
- `CommandBody`：用于指令/命令解析的原始用户文本。
|
||||
- `RawBody`：`CommandBody` 的旧版别名（为兼容性保留）。
|
||||
|
||||
当渠道提供历史记录时，会使用共享包装：
|
||||
当渠道提供历史记录时，它使用共享包装：
|
||||
|
||||
- `[Chat messages since your last reply - for context]`
|
||||
- `[Current message - respond to this]`
|
||||
|
||||
对于**非直接聊天**（群组/渠道/房间），**当前消息正文**会加上发送者标签前缀（与历史条目使用相同样式）。这会让实时消息和已排队/历史消息在智能体提示中保持一致。
|
||||
对于**非直接聊天**（群组/渠道/房间），**当前消息正文**会带上发送者标签前缀（与历史条目使用相同样式）。这让实时消息和排队/历史消息在智能体提示中保持一致。
|
||||
|
||||
历史缓冲区是**仅待处理**的：它们包含未触发运行的群组消息（例如受提及门控的消息），并**排除**已经在会话转录记录中的消息。
|
||||
|
||||
指令剥离只适用于**当前消息**部分，因此历史记录保持完整。包装历史记录的渠道应将 `CommandBody`（或 `RawBody`）设置为原始消息文本，并保持 `Body` 为组合后的提示。历史缓冲区可通过 `messages.groupChat.historyLimit`（全局默认值）以及按渠道覆盖项配置，例如 `channels.slack.historyLimit` 或 `channels.telegram.accounts.<id>.historyLimit`（设置为 `0` 可禁用）。
|
||||
指令剥离只应用于**当前消息**部分，因此历史记录保持完整。包装历史记录的渠道应将 `CommandBody`（或 `RawBody`）设置为原始消息文本，并将 `Body` 保持为组合后的提示。历史缓冲区可通过 `messages.groupChat.historyLimit`（全局默认）以及按渠道覆盖项配置，例如 `channels.slack.historyLimit` 或 `channels.telegram.accounts.<id>.historyLimit`（设置为 `0` 可禁用）。
|
||||
|
||||
## 排队和跟进
|
||||
|
||||
如果已有运行处于活动状态，入站消息可以排队、转向进入当前运行，或收集起来用于跟进轮次。
|
||||
如果已有一次运行处于活动状态，入站消息可以排队、引导进入当前运行，或收集到跟进轮次中。
|
||||
|
||||
- 通过 `messages.queue`（以及 `messages.queue.byChannel`）配置。
|
||||
- 模式：`interrupt`、`steer`、`followup`、`collect`，以及积压变体。
|
||||
- 默认模式是 `steer`，当引导回退到排队跟进投递时，会使用 500ms 跟进防抖。
|
||||
- 模式：`steer`、`followup`、`collect`、`steer-backlog`、`interrupt`，以及旧版 `queue` 别名。
|
||||
|
||||
详情：[排队](/zh-CN/concepts/queue)。
|
||||
详情：[命令队列](/zh-CN/concepts/queue)。
|
||||
|
||||
## 渠道运行所有权
|
||||
|
||||
渠道插件可以在消息进入会话队列之前保持顺序、对输入进行防抖，并应用传输背压。它们不应围绕智能体轮次本身强加单独的超时。一旦消息被路由到会话，长时间运行的工作就由会话、工具和运行时生命周期管理，这样所有渠道都能一致地报告慢轮次并从中恢复。
|
||||
渠道插件可以在消息进入会话队列前保留顺序、对输入防抖，并施加传输背压。它们不应围绕智能体轮次本身施加单独的超时。一旦消息路由到会话，长时间运行的工作就由会话、工具和运行时生命周期治理，因此所有渠道都能一致地报告慢轮次并从中恢复。
|
||||
|
||||
## 流式传输、分块和批处理
|
||||
|
||||
@ -128,7 +129,7 @@ OpenClaw 会区分**提示正文**和**命令正文**：
|
||||
- `agents.defaults.blockStreamingBreak`（`text_end|message_end`）
|
||||
- `agents.defaults.blockStreamingChunk`（`minChars|maxChars|breakPreference`）
|
||||
- `agents.defaults.blockStreamingCoalesce`（基于空闲的批处理）
|
||||
- `agents.defaults.humanDelay`（块回复之间的类人暂停）
|
||||
- `agents.defaults.humanDelay`（分块回复之间的类人停顿）
|
||||
- 渠道覆盖项：`*.blockStreaming` 和 `*.blockStreamingCoalesce`（非 Telegram 渠道需要显式设置 `*.blockStreaming: true`）
|
||||
|
||||
详情：[流式传输 + 分块](/zh-CN/concepts/streaming)。
|
||||
@ -138,33 +139,33 @@ OpenClaw 会区分**提示正文**和**命令正文**：
|
||||
OpenClaw 可以公开或隐藏模型推理：
|
||||
|
||||
- `/reasoning on|off|stream` 控制可见性。
|
||||
- 当模型生成推理内容时，它仍会计入 token 用量。
|
||||
- 推理内容在由模型生成时仍会计入 token 使用量。
|
||||
- Telegram 支持将推理流式传输到草稿气泡中。
|
||||
|
||||
详情：[思考 + 推理指令](/zh-CN/tools/thinking)和 [Token 使用](/zh-CN/reference/token-use)。
|
||||
|
||||
## 前缀、串联和回复
|
||||
## 前缀、串接和回复
|
||||
|
||||
出站消息格式集中在 `messages` 中：
|
||||
|
||||
- `messages.responsePrefix`、`channels.<channel>.responsePrefix` 和 `channels.<channel>.accounts.<id>.responsePrefix`（出站前缀级联），以及 `channels.whatsapp.messagePrefix`（WhatsApp 入站前缀）
|
||||
- 通过 `replyToMode` 和按渠道默认值实现回复串联
|
||||
- 通过 `replyToMode` 和按渠道默认值进行回复串接
|
||||
|
||||
详情：[配置](/zh-CN/gateway/config-agents#messages)和渠道文档。
|
||||
|
||||
## 静默回复
|
||||
|
||||
精确的静默 token `NO_REPLY` / `no_reply` 表示“不要投递用户可见的回复”。当某个轮次还有待处理的工具媒体（例如生成的 TTS 音频）时，OpenClaw 会剥离静默文本，但仍会投递媒体附件。OpenClaw 按对话类型解析该行为：
|
||||
精确的静默 token `NO_REPLY` / `no_reply` 表示“不要投递用户可见的回复”。当某个轮次还有待处理的工具媒体（例如生成的 TTS 音频）时，OpenClaw 会剥离静默文本，但仍会投递媒体附件。OpenClaw 会按对话类型解析该行为：
|
||||
|
||||
- 直接对话默认不允许静默，并会将裸静默回复改写为简短可见的兜底回复。
|
||||
- 直接对话默认不允许静默，并会将裸静默回复改写为简短的可见回退回复。
|
||||
- 群组/渠道默认允许静默。
|
||||
- 内部编排默认允许静默。
|
||||
|
||||
OpenClaw 还会将静默回复用于非直接聊天中发生在任何助手回复之前的内部运行器失败，这样群组/渠道不会看到 Gateway 网关错误样板。直接聊天默认显示紧凑的失败文案；只有当 `/verbose` 为 `on` 或 `full` 时，才会显示原始运行器详情。
|
||||
OpenClaw 还会对发生在非直接聊天中任何助手回复之前的内部运行器失败使用静默回复，因此群组/渠道不会看到 Gateway 网关错误样板文本。直接聊天默认显示紧凑的失败文案；原始运行器详情只会在 `/verbose` 为 `on` 或 `full` 时显示。
|
||||
|
||||
默认值位于 `agents.defaults.silentReply` 和 `agents.defaults.silentReplyRewrite` 下；`surfaces.<id>.silentReply` 和 `surfaces.<id>.silentReplyRewrite` 可以按 surface 覆盖它们。
|
||||
|
||||
当父会话有一个或多个待处理的已生成子智能体运行时，所有 surface 上的裸静默回复都会被丢弃，而不是被改写，因此父会话会保持安静，直到子完成事件投递真实回复。
|
||||
当父会话有一个或多个待处理的已生成子智能体运行时，裸静默回复会在所有 surface 上被丢弃，而不是被改写，因此父会话会保持安静，直到子完成事件投递真实回复。
|
||||
|
||||
## 相关
|
||||
|
||||
|
||||
@ -1,60 +1,65 @@
|
||||
---
|
||||
read_when:
|
||||
- 更改自动回复执行或并发设置
|
||||
summary: 序列化入站自动回复运行的命令队列设计
|
||||
- 更改自动回复的执行方式或并发设置
|
||||
- 解释 /queue 模式或消息引导行为
|
||||
summary: 自动回复队列模式、默认值和按会话覆盖设置
|
||||
title: 命令队列
|
||||
x-i18n:
|
||||
generated_at: "2026-04-28T19:41:16Z"
|
||||
generated_at: "2026-04-29T21:52:57Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 8ed2bd9fad7f35f124b99c570703ddd075c742391061a977323c28feaf3ab508
|
||||
source_hash: 59d14a2b8e1b8d5bc1433c0f052869efed42912c9b85cdd79e518633d9919729
|
||||
source_path: concepts/queue.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
我们通过一个很小的进程内队列，对入站自动回复运行（所有渠道）进行序列化，防止多个智能体运行相互冲突，同时仍允许在不同会话之间进行安全并行。
|
||||
我们通过一个很小的进程内队列来串行化入站自动回复运行（所有渠道），防止多个智能体运行相互冲突，同时仍允许跨会话的安全并行。
|
||||
|
||||
## 原因
|
||||
|
||||
- 自动回复运行可能很昂贵（LLM 调用），并且当多个入站消息几乎同时到达时可能发生冲突。
|
||||
- 序列化可避免竞争共享资源（会话文件、日志、CLI stdin），并降低触发上游速率限制的概率。
|
||||
- 自动回复运行可能开销很高（LLM 调用），并且当多条入站消息短时间内到达时可能发生冲突。
|
||||
- 串行化可以避免争抢共享资源（会话文件、日志、CLI 标准输入），并降低触发上游速率限制的概率。
|
||||
|
||||
## 工作原理
|
||||
## 工作方式
|
||||
|
||||
- 一个感知通道的 FIFO 队列会按通道排空，并带有可配置的并发上限（未配置通道默认 1；main 默认 4，subagent 默认 8）。
|
||||
- `runEmbeddedPiAgent` 按**会话键**（通道 `session:<key>`）入队，以保证每个会话同一时间只有一个活跃运行。
|
||||
- 然后，每个会话运行会被排入一个**全局通道**（默认 `main`），因此整体并行度受 `agents.defaults.maxConcurrent` 限制。
|
||||
- 启用详细日志时，如果排队运行在启动前等待超过约 2s，会发出一条简短通知。
|
||||
- 输入中指示器仍会在入队时立即触发（如果渠道支持），因此在等待轮到我们期间，用户体验保持不变。
|
||||
- 感知 lane 的 FIFO 队列按可配置的并发上限排空每个 lane（未配置的 lane 默认为 1；main 默认为 4，subagent 为 8）。
|
||||
- `runEmbeddedPiAgent` 按**会话键**（lane `session:<key>`）入队，以保证每个会话只有一个活跃运行。
|
||||
- 每个会话运行随后会被排入一个**全局 lane**（默认是 `main`），因此整体并行度受 `agents.defaults.maxConcurrent` 限制。
|
||||
- 启用详细日志时，如果已排队的运行在启动前等待超过约 2 秒，会发出一条简短提示。
|
||||
- 输入状态指示器仍会在入队时立即触发（渠道支持时），因此用户体验在等待轮次时不会改变。
|
||||
|
||||
## 队列模式（按渠道）
|
||||
## 默认值
|
||||
|
||||
入站消息可以引导当前运行、等待后续轮次，或两者都做：
|
||||
未设置时，所有入站渠道界面使用：
|
||||
|
||||
- `steer`：立即注入当前运行（在下一个工具边界后取消待处理的工具调用）。如果不是流式传输，则回退到 followup。
|
||||
- `followup`：在当前运行结束后，为下一次智能体轮次入队。
|
||||
- `collect`：将所有排队消息合并为**单个**后续轮次（默认）。如果消息目标是不同渠道/线程，则会单独排空以保留路由。
|
||||
- `steer-backlog`（也称为 `steer+backlog`）：现在引导，**同时**保留消息用于后续轮次。
|
||||
- `interrupt`（旧版）：中止该会话中的活跃运行，然后运行最新消息。
|
||||
- `mode: "steer"`
|
||||
- `debounceMs: 500`
|
||||
- `cap: 20`
|
||||
- `drop: "summarize"`
|
||||
|
||||
`steer` 是默认值，因为它可以让活跃模型轮次保持响应，而无需启动第二个会话运行。如果当前运行不能接受 steering，OpenClaw 会回退到 followup 队列条目。
|
||||
|
||||
## 队列模式
|
||||
|
||||
入站消息可以 steer 当前运行、等待后续轮次，或两者都做：
|
||||
|
||||
- `steer`：向活跃 Pi 运行排入一条 steering 消息。Pi 会在**当前助手轮次完成执行其工具调用之后**、下一次 LLM 调用之前递送它。如果运行没有处于活跃流式传输状态，或 steering 不可用，OpenClaw 会回退到 followup 队列条目。
|
||||
- `followup`：在当前运行结束后，为后续智能体轮次将每条消息入队。
|
||||
- `collect`：在静默窗口后，将已排队的消息合并为**单个** followup 轮次。如果消息面向不同渠道/线程，它们会分别排空以保留路由。
|
||||
- `steer-backlog`（也称为 `steer+backlog`）：现在 steer，**并且**为 followup 轮次保留同一条消息。
|
||||
- `interrupt`（旧版）：中止该会话的活跃运行，然后运行最新消息。
|
||||
- `queue`（旧版别名）：与 `steer` 相同。
|
||||
|
||||
Steer-backlog 表示你可能会在被引导的运行之后获得一个后续响应，因此
|
||||
流式传输界面可能看起来像重复响应。如果你想要
|
||||
每条入站消息对应一个响应，请优先使用 `collect`/`steer`。
|
||||
发送 `/queue collect` 作为独立命令（按会话），或设置 `messages.queue.byChannel.discord: "collect"`。
|
||||
Steer-backlog 意味着你可能会在 steered 运行之后得到 followup 响应，因此流式传输界面看起来可能像重复响应。如果你希望每条入站消息只有一个响应，请优先使用 `collect`/`steer`。
|
||||
|
||||
默认值（配置中未设置时）：
|
||||
|
||||
- 所有界面 → `collect`
|
||||
|
||||
通过 `messages.queue` 进行全局配置或按渠道配置：
|
||||
通过 `messages.queue` 进行全局或按渠道配置：
|
||||
|
||||
```json5
|
||||
{
|
||||
messages: {
|
||||
queue: {
|
||||
mode: "collect",
|
||||
debounceMs: 1000,
|
||||
mode: "steer",
|
||||
debounceMs: 500,
|
||||
cap: 20,
|
||||
drop: "summarize",
|
||||
byChannel: { discord: "collect" },
|
||||
@ -65,36 +70,48 @@ Steer-backlog 表示你可能会在被引导的运行之后获得一个后续响
|
||||
|
||||
## 队列选项
|
||||
|
||||
选项适用于 `followup`、`collect` 和 `steer-backlog`（也适用于回退到 followup 的 `steer`）：
|
||||
选项适用于 `followup`、`collect` 和 `steer-backlog`（以及 `steer` 回退到 followup 时）：
|
||||
|
||||
- `debounceMs`：等待安静后再启动后续轮次（防止“继续，继续”）。
|
||||
- `cap`：每个会话的最大排队消息数。
|
||||
- `drop`：溢出策略（`old`、`new`、`summarize`）。
|
||||
- `debounceMs`：排空已排队 followup 前的静默窗口。裸数字表示毫秒；`/queue` 选项接受单位 `ms`、`s`、`m`、`h` 和 `d`。
|
||||
- `cap`：每个会话的最大排队消息数。小于 `1` 的值会被忽略。
|
||||
- `drop: "summarize"`：默认值。按需丢弃最旧的队列条目，保留紧凑摘要，并将它们作为合成 followup 提示注入。
|
||||
- `drop: "old"`：按需丢弃最旧的队列条目，不保留摘要。
|
||||
- `drop: "new"`：当队列已满时拒绝最新消息。
|
||||
|
||||
Summarize 会保留一份被丢弃消息的简短项目符号列表，并将其作为合成后续提示注入。
|
||||
默认值：`debounceMs: 1000`、`cap: 20`、`drop: summarize`。
|
||||
默认值：`debounceMs: 500`、`cap: 20`、`drop: summarize`。
|
||||
|
||||
## 按会话覆盖
|
||||
## 优先级
|
||||
|
||||
- 发送 `/queue <mode>` 作为独立命令，以保存当前会话的模式。
|
||||
- 选项可以组合：`/queue collect debounce:2s cap:25 drop:summarize`
|
||||
对于模式选择，OpenClaw 按以下顺序解析：
|
||||
|
||||
1. 内联或已存储的每会话 `/queue` 覆盖。
|
||||
2. `messages.queue.byChannel.<channel>`。
|
||||
3. `messages.queue.mode`。
|
||||
4. 默认 `steer`。
|
||||
|
||||
对于选项，内联或已存储的 `/queue` 选项优先于配置。然后会应用渠道特定 debounce（`messages.queue.debounceMsByChannel`）、插件 debounce 默认值、全局 `messages.queue` 选项以及内置默认值。`cap` 和 `drop` 是全局/会话选项，不是按渠道配置键。
|
||||
|
||||
## 每会话覆盖
|
||||
|
||||
- 发送 `/queue <mode>` 作为独立命令，为当前会话存储模式。
|
||||
- 选项可以组合：`/queue collect debounce:0.5s cap:25 drop:summarize`
|
||||
- `/queue default` 或 `/queue reset` 会清除会话覆盖。
|
||||
|
||||
## 范围和保证
|
||||
|
||||
- 适用于所有使用 Gateway 网关回复管线的入站渠道上的自动回复智能体运行（WhatsApp web、Telegram、Slack、Discord、Signal、iMessage、webchat 等）。
|
||||
- 默认通道（`main`）对于入站 + 主心跳在整个进程内生效；设置 `agents.defaults.maxConcurrent` 可允许多个会话并行。
|
||||
- 可能存在其他通道（例如 `cron`、`cron-nested`、`nested`、`subagent`），因此后台任务可以并行运行，而不会阻塞入站回复。隔离的 cron 智能体轮次会占用一个 `cron` 槽位，而其内部智能体执行使用 `cron-nested`；两者都使用 `cron.maxConcurrentRuns`。共享的非 cron `nested` 流程保留自身的通道行为。这些分离运行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。
|
||||
- 按会话通道保证同一时间只有一个智能体运行会触碰给定会话。
|
||||
- 没有外部依赖或后台工作线程；纯 TypeScript + promises。
|
||||
- 默认 lane（`main`）在入站 + main heartbeats 中是进程范围的；设置 `agents.defaults.maxConcurrent` 可允许多个会话并行运行。
|
||||
- 可能存在其他 lane（例如 `cron`、`cron-nested`、`nested`、`subagent`），因此后台作业可以并行运行，而不会阻塞入站回复。隔离的 cron 智能体轮次会在其内部智能体执行使用 `cron-nested` 时持有一个 `cron` slot；两者都使用 `cron.maxConcurrentRuns`。共享的非 cron `nested` 流程保留自身的 lane 行为。这些分离的运行会作为[后台任务](/zh-CN/automation/tasks)被跟踪。
|
||||
- 每会话 lane 保证同一时间只有一个智能体运行会触碰给定会话。
|
||||
- 没有外部依赖或后台 worker 线程；纯 TypeScript + promises。
|
||||
|
||||
## 故障排除
|
||||
|
||||
- 如果命令看起来卡住，请启用详细日志，并查找“queued for …ms”行以确认队列正在排空。
|
||||
- 如果命令看起来卡住，请启用详细日志，并查找“queued for …ms”行，以确认队列正在排空。
|
||||
- 如果你需要队列深度，请启用详细日志并观察队列计时行。
|
||||
- 启用诊断时，超过 `diagnostics.stuckSessionWarnMs` 仍停留在 `processing` 的会话会记录卡住会话警告。默认情况下，活跃的嵌入式运行、活跃的回复操作和活跃的通道任务只会发出警告；没有活跃会话工作的陈旧启动记账可以释放受影响的会话通道，使排队工作继续排空。
|
||||
- 启用诊断时，超过 `diagnostics.stuckSessionWarnMs` 后仍保持 `processing` 的会话会记录 stuck-session 警告。默认情况下，活跃 embedded 运行、活跃回复操作和活跃 lane 任务仍仅发出警告；如果启动时的过期 bookkeeping 没有活跃会话工作，可以释放受影响的会话 lane，使已排队工作继续排空。
|
||||
|
||||
## 相关内容
|
||||
## 相关
|
||||
|
||||
- [会话管理](/zh-CN/concepts/session)
|
||||
- [重试策略](/zh-CN/concepts/retry)
|
||||
|
||||
@ -1,20 +1,20 @@
|
||||
---
|
||||
read_when:
|
||||
- 调整智能体默认设置（模型、思考、工作区、心跳、媒体、Skills）
|
||||
- 调整智能体默认设置（模型、思考、工作区、Heartbeat、媒体、Skills）
|
||||
- 配置多智能体路由和绑定
|
||||
- 调整会话、消息投递和对话模式行为
|
||||
summary: 智能体默认设置、多智能体路由、会话、消息和对话配置
|
||||
summary: 智能体默认值、多智能体路由、会话、消息和 talk 配置
|
||||
title: 配置 — 智能体
|
||||
x-i18n:
|
||||
generated_at: "2026-04-29T10:51:18Z"
|
||||
generated_at: "2026-04-29T21:53:08Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 66bf05119121715f1aed8de9b72b5c79bdcec8d005684e0d5ebe19413b8561e3
|
||||
source_hash: 71ffa1a7315a9f12b9685ca4aeef1414a5da994105f4466718fea56f3c53fbc2
|
||||
source_path: gateway/config-agents.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
智能体作用域配置键位于 `agents.*`、`multiAgent.*`、`session.*`、`messages.*` 和 `talk.*` 下。关于渠道、工具、Gateway 网关运行时和其他顶层键，请参阅[配置参考](/zh-CN/gateway/configuration-reference)。
|
||||
`agents.*`、`multiAgent.*`、`session.*`、`messages.*` 和 `talk.*` 下的智能体作用域配置键。关于渠道、工具、Gateway 网关运行时和其他顶层键，请参阅[配置参考](/zh-CN/gateway/configuration-reference)。
|
||||
|
||||
## 智能体默认值
|
||||
|
||||
@ -30,7 +30,7 @@ x-i18n:
|
||||
|
||||
### `agents.defaults.repoRoot`
|
||||
|
||||
可选的仓库根目录，会显示在系统提示词的运行时行中。如果未设置，OpenClaw 会从工作区开始向上遍历并自动检测。
|
||||
系统提示的运行时行中显示的可选仓库根目录。如果未设置，OpenClaw 会从工作区开始向上遍历来自动检测。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -40,29 +40,29 @@ x-i18n:
|
||||
|
||||
### `agents.defaults.skills`
|
||||
|
||||
可选的默认 Skills 允许列表，用于未设置 `agents.list[].skills` 的智能体。
|
||||
对于未设置 `agents.list[].skills` 的智能体，可选的默认 Skills 允许列表。
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: { skills: ["github", "weather"] },
|
||||
list: [
|
||||
{ id: "writer" }, // 继承 github、weather
|
||||
{ id: "docs", skills: ["docs-search"] }, // 替换默认值
|
||||
{ id: "locked-down", skills: [] }, // 没有 Skills
|
||||
{ id: "writer" }, // inherits github, weather
|
||||
{ id: "docs", skills: ["docs-search"] }, // replaces defaults
|
||||
{ id: "locked-down", skills: [] }, // no skills
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
- 省略 `agents.defaults.skills` 可默认不限制 Skills。
|
||||
- 省略 `agents.list[].skills` 可继承默认值。
|
||||
- 设置 `agents.list[].skills: []` 表示没有 Skills。
|
||||
- 省略 `agents.defaults.skills`，默认不限制 Skills。
|
||||
- 省略 `agents.list[].skills` 以继承默认值。
|
||||
- 设置 `agents.list[].skills: []` 表示不使用 Skills。
|
||||
- 非空的 `agents.list[].skills` 列表是该智能体的最终集合；它不会与默认值合并。
|
||||
|
||||
### `agents.defaults.skipBootstrap`
|
||||
|
||||
禁用自动创建工作区引导文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。
|
||||
禁用工作区引导文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）的自动创建。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -72,10 +72,10 @@ x-i18n:
|
||||
|
||||
### `agents.defaults.contextInjection`
|
||||
|
||||
控制何时将工作区引导文件注入系统提示词。默认值：`"always"`。
|
||||
控制何时将工作区引导文件注入系统提示。默认值：`"always"`。
|
||||
|
||||
- `"continuation-skip"`：安全的继续轮次（在已完成的助手响应之后）会跳过工作区引导重新注入，从而减少提示词大小。心跳运行和压缩后的重试仍会重建上下文。
|
||||
- `"never"`：在每一轮都禁用工作区引导和上下文文件注入。仅对完全自行管理提示词生命周期的智能体使用此选项（自定义上下文引擎、构建自身上下文的原生运行时，或专门的无引导工作流）。心跳和压缩恢复轮次也会跳过注入。
|
||||
- `"continuation-skip"`：安全的延续轮次（在一次已完成的助手响应之后）会跳过工作区引导的重新注入，从而减少提示大小。Heartbeat 运行和压缩后的重试仍会重建上下文。
|
||||
- `"never"`：在每个轮次都禁用工作区引导和上下文文件注入。仅对完全自行管理提示生命周期的智能体使用此选项（自定义上下文引擎、构建自身上下文的原生运行时，或不需要引导的专用工作流）。Heartbeat 和压缩恢复轮次也会跳过注入。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -95,7 +95,7 @@ x-i18n:
|
||||
|
||||
### `agents.defaults.bootstrapTotalMaxChars`
|
||||
|
||||
所有工作区引导文件合计注入的最大总字符数。默认值：`60000`。
|
||||
所有工作区引导文件合计注入的最大字符数。默认值：`60000`。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -105,11 +105,12 @@ x-i18n:
|
||||
|
||||
### `agents.defaults.bootstrapPromptTruncationWarning`
|
||||
|
||||
控制引导上下文被截断时智能体可见的警告文本。默认值：`"once"`。
|
||||
控制引导上下文被截断时，智能体可见的警告文本。
|
||||
默认值：`"once"`。
|
||||
|
||||
- `"off"`：永不将警告文本注入系统提示词。
|
||||
- `"once"`：对每个唯一截断签名注入一次警告（推荐）。
|
||||
- `"always"`：存在截断时，每次运行都注入警告。
|
||||
- `"off"`：绝不向系统提示注入警告文本。
|
||||
- `"once"`：对每个唯一的截断签名仅注入一次警告（推荐）。
|
||||
- `"always"`：存在截断时，在每次运行都注入警告。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -117,30 +118,31 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
### 上下文预算归属映射
|
||||
### 上下文预算归属图
|
||||
|
||||
OpenClaw 有多个高容量提示词/上下文预算，它们会按子系统刻意拆分，而不是全部流经一个通用开关。
|
||||
OpenClaw 有多个高容量提示/上下文预算，并且它们有意按子系统拆分，而不是全部通过一个通用旋钮控制。
|
||||
|
||||
- `agents.defaults.bootstrapMaxChars` /
|
||||
`agents.defaults.bootstrapTotalMaxChars`：
|
||||
常规工作区引导注入。
|
||||
- `agents.defaults.startupContext.*`：
|
||||
一次性的重置/启动模型运行前导内容，包括最近的每日 `memory/*.md` 文件。裸聊天 `/new` 和 `/reset` 命令会在不调用模型的情况下确认重置。
|
||||
一次性重置/启动模型运行前置内容，包括最近的每日 `memory/*.md` 文件。裸聊天 `/new` 和 `/reset` 命令会在不调用模型的情况下确认重置。
|
||||
- `skills.limits.*`：
|
||||
注入系统提示词的紧凑 Skills 列表。
|
||||
注入系统提示的紧凑 Skills 列表。
|
||||
- `agents.defaults.contextLimits.*`：
|
||||
有界运行时摘录和注入的运行时所有块。
|
||||
有界运行时摘录和注入的运行时自有块。
|
||||
- `memory.qmd.limits.*`：
|
||||
已索引的内存搜索片段和注入大小。
|
||||
索引化记忆搜索片段和注入大小。
|
||||
|
||||
仅当某个智能体需要不同预算时，才使用匹配的按智能体覆盖：
|
||||
仅当某个智能体需要不同预算时，才使用匹配的按智能体覆盖项：
|
||||
|
||||
- `agents.list[].skillsLimits.maxSkillsPromptChars`
|
||||
- `agents.list[].contextLimits.*`
|
||||
|
||||
#### `agents.defaults.startupContext`
|
||||
|
||||
控制在重置/启动模型运行时注入的首轮启动前导内容。裸聊天 `/new` 和 `/reset` 命令会在不调用模型的情况下确认重置，因此不会加载此前导内容。
|
||||
控制在重置/启动模型运行时注入的首轮启动前置内容。
|
||||
裸聊天 `/new` 和 `/reset` 命令会在不调用模型的情况下确认重置，因此不会加载此前置内容。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -178,14 +180,14 @@ OpenClaw 有多个高容量提示词/上下文预算，它们会按子系统刻
|
||||
}
|
||||
```
|
||||
|
||||
- `memoryGetMaxChars`：在添加截断元数据和继续提示前，默认的 `memory_get` 摘录上限。
|
||||
- `memoryGetMaxChars`：在添加截断元数据和延续通知前，默认的 `memory_get` 摘录上限。
|
||||
- `memoryGetDefaultLines`：省略 `lines` 时，默认的 `memory_get` 行窗口。
|
||||
- `toolResultMaxChars`：用于持久化结果和溢出恢复的实时工具结果上限。
|
||||
- `postCompactionMaxChars`：压缩后刷新注入期间使用的 AGENTS.md 摘录上限。
|
||||
|
||||
#### `agents.list[].contextLimits`
|
||||
|
||||
共享 `contextLimits` 开关的按智能体覆盖。省略的字段会继承自 `agents.defaults.contextLimits`。
|
||||
对共享 `contextLimits` 旋钮的按智能体覆盖。省略的字段会继承自 `agents.defaults.contextLimits`。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -211,7 +213,7 @@ OpenClaw 有多个高容量提示词/上下文预算，它们会按子系统刻
|
||||
|
||||
#### `skills.limits.maxSkillsPromptChars`
|
||||
|
||||
注入系统提示词的紧凑 Skills 列表的全局上限。这不会影响按需读取 `SKILL.md` 文件。
|
||||
注入系统提示的紧凑 Skills 列表的全局上限。这不会影响按需读取 `SKILL.md` 文件。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -225,7 +227,7 @@ OpenClaw 有多个高容量提示词/上下文预算，它们会按子系统刻
|
||||
|
||||
#### `agents.list[].skillsLimits.maxSkillsPromptChars`
|
||||
|
||||
Skills 提示词预算的按智能体覆盖。
|
||||
Skills 提示预算的按智能体覆盖。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -244,9 +246,11 @@ Skills 提示词预算的按智能体覆盖。
|
||||
|
||||
### `agents.defaults.imageMaxDimensionPx`
|
||||
|
||||
在调用提供商之前，转录/工具图像块中图像最长边的最大像素尺寸。默认值：`1200`。
|
||||
在 provider 调用前，转录/工具图片块中图片最长边的最大像素尺寸。
|
||||
默认值：`1200`。
|
||||
|
||||
较低的值通常会减少大量截图运行中的视觉 token 用量和请求载荷大小。较高的值会保留更多视觉细节。
|
||||
较低的值通常会减少大量截图运行中的视觉 token 使用量和请求载荷大小。
|
||||
较高的值会保留更多视觉细节。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -256,7 +260,7 @@ Skills 提示词预算的按智能体覆盖。
|
||||
|
||||
### `agents.defaults.userTimezone`
|
||||
|
||||
系统提示词上下文使用的时区（不是消息时间戳）。回退为主机时区。
|
||||
系统提示上下文使用的时区（不是消息时间戳）。回退到主机时区。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -266,7 +270,7 @@ Skills 提示词预算的按智能体覆盖。
|
||||
|
||||
### `agents.defaults.timeFormat`
|
||||
|
||||
系统提示词中的时间格式。默认值：`auto`（操作系统偏好设置）。
|
||||
系统提示中的时间格式。默认值：`auto`（操作系统偏好）。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -304,9 +308,9 @@ Skills 提示词预算的按智能体覆盖。
|
||||
primary: "anthropic/claude-opus-4-6",
|
||||
fallbacks: ["openai/gpt-5.4-mini"],
|
||||
},
|
||||
params: { cacheRetention: "long" }, // 全局默认提供商参数
|
||||
params: { cacheRetention: "long" }, // global default provider params
|
||||
agentRuntime: {
|
||||
id: "pi", // pi | auto | 已注册 harness id，例如 codex
|
||||
id: "pi", // pi | auto | registered harness id, e.g. codex
|
||||
fallback: "pi", // pi | none
|
||||
},
|
||||
pdfMaxBytesMb: 10,
|
||||
@ -326,53 +330,57 @@ Skills 提示词预算的按智能体覆盖。
|
||||
|
||||
- `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
|
||||
- 字符串形式仅设置主模型。
|
||||
- 对象形式设置主模型以及有序的故障转移模型。
|
||||
- 对象形式设置主模型以及按顺序排列的故障转移模型。
|
||||
- `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
|
||||
- 由 `image` 工具路径用作其视觉模型配置。
|
||||
- 当所选/默认模型无法接受图像输入时，也用作回退路由。
|
||||
- 优先使用显式的 `provider/model` 引用。为兼容性也接受裸 ID；如果某个裸 ID 唯一匹配 `models.providers.*.models` 中已配置且支持图像的条目，OpenClaw 会将其限定到该提供商。配置中存在歧义匹配时，需要显式提供提供商前缀。
|
||||
- 当选定/默认模型无法接受图像输入时，也用作回退路由。
|
||||
- 优先使用显式的 `provider/model` 引用。为兼容性也接受裸 ID；如果裸 ID 唯一匹配 `models.providers.*.models` 中已配置且支持图像的条目，OpenClaw 会将其限定到该提供商。存在歧义的已配置匹配需要显式提供商前缀。
|
||||
- `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
|
||||
- 由共享图像生成能力以及任何未来生成图像的工具/插件表面使用。
|
||||
- 由共享的图像生成能力以及未来任何生成图像的工具/插件表面使用。
|
||||
- 典型值：用于原生 Gemini 图像生成的 `google/gemini-3.1-flash-image-preview`、用于 fal 的 `fal/fal-ai/flux/dev`、用于 OpenAI Images 的 `openai/gpt-image-2`，或用于透明背景 OpenAI PNG/WebP 输出的 `openai/gpt-image-1.5`。
|
||||
- 如果你直接选择提供商/模型，也要配置匹配的提供商身份验证（例如用于 `google/*` 的 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`、用于 `openai/gpt-image-2` / `openai/gpt-image-1.5` 的 `OPENAI_API_KEY` 或 OpenAI Codex OAuth、用于 `fal/*` 的 `FAL_KEY`）。
|
||||
- 如果省略，`image_generate` 仍可推断有身份验证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。
|
||||
- 如果直接选择提供商/模型，也要配置匹配的提供商凭证（例如用于 `google/*` 的 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，用于 `openai/gpt-image-2` / `openai/gpt-image-1.5` 的 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，用于 `fal/*` 的 `FAL_KEY`）。
|
||||
- 如果省略，`image_generate` 仍可推断有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。
|
||||
- `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
|
||||
- 由共享音乐生成能力和内置 `music_generate` 工具使用。
|
||||
- 由共享的音乐生成能力和内置 `music_generate` 工具使用。
|
||||
- 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.6`。
|
||||
- 如果省略，`music_generate` 仍可推断有身份验证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。
|
||||
- 如果你直接选择提供商/模型，也要配置匹配的提供商身份验证/API 密钥。
|
||||
- 如果省略，`music_generate` 仍可推断有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。
|
||||
- 如果直接选择提供商/模型，也要配置匹配的提供商凭证/API key。
|
||||
- `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
|
||||
- 由共享视频生成能力和内置 `video_generate` 工具使用。
|
||||
- 由共享的视频生成能力和内置 `video_generate` 工具使用。
|
||||
- 典型值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。
|
||||
- 如果省略，`video_generate` 仍可推断有身份验证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。
|
||||
- 如果你直接选择提供商/模型，也要配置匹配的提供商身份验证/API 密钥。
|
||||
- 内置 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。
|
||||
- 如果省略，`video_generate` 仍可推断有凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。
|
||||
- 如果直接选择提供商/模型，也要配置匹配的提供商凭证/API key。
|
||||
- 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。
|
||||
- `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
|
||||
- 由 `pdf` 工具用于模型路由。
|
||||
- 如果省略，PDF 工具会回退到 `imageModel`，然后回退到已解析的会话/默认模型。
|
||||
- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具的默认 PDF 大小限制。
|
||||
- `pdfMaxPages`：`pdf` 工具中提取回退模式考虑的默认最大页数。
|
||||
- `verboseDefault`：智能体的默认详细级别。值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。
|
||||
- `reasoningDefault`：智能体的默认推理可见性。值：`"off"`、`"on"`、`"stream"`。按智能体设置的 `agents.list[].reasoningDefault` 会覆盖此默认值。仅当未设置按消息或会话的推理覆盖项时，配置的推理默认值才会应用于所有者、已授权发送者或操作员管理员 Gateway 网关上下文。
|
||||
- `reasoningDefault`：智能体的默认推理可见性。值：`"off"`、`"on"`、`"stream"`。按智能体设置的 `agents.list[].reasoningDefault` 会覆盖此默认值。已配置的推理默认值仅在没有设置按消息或会话推理覆盖时，才会应用于所有者、已授权发送者或操作员管理员 Gateway 网关上下文。
|
||||
- `elevatedDefault`：智能体的默认提升输出级别。值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。
|
||||
- `model.primary`：格式为 `provider/model`（例如用于 API 密钥访问的 `openai/gpt-5.5`，或用于 Codex OAuth 的 `openai-codex/gpt-5.5`）。如果省略提供商，OpenClaw 会先尝试别名，然后尝试与该确切模型 ID 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此优先使用显式的 `provider/model`）。如果该提供商不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露陈旧的已移除提供商默认值。
|
||||
- `model.primary`：格式为 `provider/model`（例如，用于 API key 访问的 `openai/gpt-5.5`，或用于 Codex OAuth 的 `openai-codex/gpt-5.5`）。如果省略提供商，OpenClaw 会先尝试别名，然后为该精确模型 ID 尝试唯一的已配置提供商匹配，只有在这之后才回退到已配置的默认提供商（已废弃的兼容行为，因此请优先使用显式的 `provider/model`）。如果该提供商不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露陈旧的已移除提供商默认值。
|
||||
- `models`：为 `/model` 配置的模型目录和允许列表。每个条目可以包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`、`chat_template_kwargs`、`extra_body`/`extraBody`）。
|
||||
- 安全编辑：使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 添加条目。除非传入 `--replace`，否则 `config set` 会拒绝会移除现有允许列表条目的替换。
|
||||
- 按提供商限定的配置/新手引导流程会将所选提供商模型合并到此映射中，并保留已配置的无关提供商。
|
||||
- 对于直接 OpenAI Responses 模型，服务端压缩会自动启用。使用 `params.responsesServerCompaction: false` 停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆盖阈值。参见 [OpenAI 服务端压缩](/zh-CN/providers/openai#server-side-compaction-responses-api)。
|
||||
- `params`：应用于所有模型的全局默认提供商参数。在 `agents.defaults.params` 设置（例如 `{ cacheRetention: "long" }`）。
|
||||
- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配智能体 ID）按键覆盖。详见 [Prompt Caching](/zh-CN/reference/prompt-caching)。
|
||||
- `params.extra_body`/`params.extraBody`：高级透传 JSON，会合并到 OpenAI 兼容代理的 `api: "openai-completions"` 请求体中。如果它与生成的请求键冲突，额外请求体会获胜；非原生 completions 路由之后仍会剥离 OpenAI 专属的 `store`。
|
||||
- `params.chat_template_kwargs`：vLLM/OpenAI 兼容聊天模板参数，会合并到顶层 `api: "openai-completions"` 请求体中。对于关闭 thinking 的 `vllm/nemotron-3-*`，内置 vLLM 插件会自动发送 `enable_thinking: false` 和 `force_nonempty_content: true`；显式 `chat_template_kwargs` 会覆盖生成的默认值，而 `extra_body.chat_template_kwargs` 仍具有最终优先级。对于 vLLM Qwen thinking 控制，在该模型条目上将 `params.qwenThinkingFormat` 设置为 `"chat-template"` 或 `"top-level"`。
|
||||
- 按提供商限定的配置/新手引导流程会将选定的提供商模型合并到此映射中，并保留已配置的其他无关提供商。
|
||||
- 对于直接的 OpenAI Responses 模型，会自动启用服务器端压缩。使用 `params.responsesServerCompaction: false` 停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆盖阈值。参见 [OpenAI 服务器端压缩](/zh-CN/providers/openai#server-side-compaction-responses-api)。
|
||||
- `params`：应用到所有模型的全局默认提供商参数。设置在 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。
|
||||
- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配智能体 ID）按键覆盖。详情参见 [提示词缓存](/zh-CN/reference/prompt-caching)。
|
||||
- `params.extra_body`/`params.extraBody`：高级透传 JSON，会合并到用于 OpenAI 兼容代理的 `api: "openai-completions"` 请求体中。如果它与生成的请求键冲突，额外请求体优先；之后，非原生 completions 路由仍会剥离仅 OpenAI 支持的 `store`。
|
||||
- `params.chat_template_kwargs`：vLLM/OpenAI 兼容聊天模板参数，会合并到顶层 `api: "openai-completions"` 请求体中。对于关闭 thinking 的 `vllm/nemotron-3-*`，内置 vLLM 插件会自动发送 `enable_thinking: false` 和 `force_nonempty_content: true`；显式的 `chat_template_kwargs` 会覆盖生成的默认值，而 `extra_body.chat_template_kwargs` 仍具有最终优先级。对于 vLLM Qwen thinking 控制，请在该模型条目上将 `params.qwenThinkingFormat` 设置为 `"chat-template"` 或 `"top-level"`。
|
||||
- `compat.supportedReasoningEfforts`：按模型设置的 OpenAI 兼容推理强度列表。对于确实接受它的自定义端点，包含 `"xhigh"`；随后 OpenClaw 会在命令菜单、Gateway 网关会话行、会话补丁验证、智能体 CLI 验证和 `llm-task` 验证中，为该已配置提供商/模型公开 `/think xhigh`。当后端需要某个规范级别对应的提供商特定值时，使用 `compat.reasoningEffortMap`。
|
||||
- `params.preserveThinking`：仅 Z.AI 使用的保留 thinking 选择加入项。启用并且 thinking 开启时，OpenClaw 会发送 `thinking.clear_thinking: false` 并重放先前的 `reasoning_content`；参见 [Z.AI thinking 和保留 thinking](/zh-CN/providers/zai#thinking-and-preserved-thinking)。
|
||||
- `agentRuntime`：默认低级智能体运行时策略。省略 ID 时默认使用 OpenClaw Pi。使用 `id: "pi"` 强制使用内置 PI harness，使用 `id: "auto"` 让已注册的插件 harness 认领受支持的模型，使用已注册的 harness ID（例如 `id: "codex"`），或使用受支持的 CLI 后端别名（例如 `id: "claude-cli"`）。设置 `fallback: "none"` 可禁用自动 PI 回退。显式插件运行时（例如 `codex`）默认失败即关闭，除非你在同一覆盖作用域中设置 `fallback: "pi"`。保持模型引用为规范形式 `provider/model`；通过运行时配置选择 Codex、Claude CLI、Gemini CLI 和其他执行后端，而不是使用旧版运行时提供商前缀。参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)，了解这与提供商/模型选择的区别。
|
||||
- 更改这些字段的配置写入器（例如 `/models set`、`/models set-image` 和回退添加/移除命令）会保存规范对象形式，并在可能时保留现有回退列表。
|
||||
- `params.preserveThinking`：仅 Z.AI 支持的保留 thinking 选择启用项。启用后且 thinking 开启时，OpenClaw 会发送 `thinking.clear_thinking: false` 并重放先前的 `reasoning_content`；参见 [Z.AI thinking 和保留 thinking](/zh-CN/providers/zai#thinking-and-preserved-thinking)。
|
||||
- `agentRuntime`：默认低级智能体运行时策略。省略 ID 时默认使用 OpenClaw Pi。使用 `id: "pi"` 强制使用内置 PI 执行框架，使用 `id: "auto"` 让已注册的插件执行框架认领支持的模型，使用已注册的执行框架 ID（例如 `id: "codex"`），或使用支持的 CLI 后端别名（例如 `id: "claude-cli"`）。设置 `fallback: "none"` 可禁用自动 PI 回退。显式插件运行时（例如 `codex`）默认会失败关闭，除非你在同一覆盖作用域中设置 `fallback: "pi"`。保持模型引用采用规范的 `provider/model`；通过运行时配置选择 Codex、Claude CLI、Gemini CLI 和其他执行后端，而不是使用旧版运行时提供商前缀。关于它与提供商/模型选择的差异，参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
|
||||
- 会变更这些字段的配置写入器（例如 `/models set`、`/models set-image` 和回退添加/移除命令）会保存规范对象形式，并尽可能保留现有回退列表。
|
||||
- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话仍会串行化）。默认值：4。
|
||||
|
||||
### `agents.defaults.agentRuntime`
|
||||
|
||||
`agentRuntime` 控制哪个低级执行器运行智能体轮次。多数部署应保留默认的 OpenClaw Pi 运行时。当受信任插件提供原生 harness（例如内置 Codex 应用服务器 harness），或当你需要受支持的 CLI 后端（例如 Claude CLI）时使用它。关于心智模型，参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
|
||||
`agentRuntime` 控制哪个低级执行器运行智能体轮次。大多数
|
||||
部署应保留默认的 OpenClaw Pi 运行时。当受信任的
|
||||
插件提供原生执行框架（例如内置 Codex app-server 执行框架），
|
||||
或当你需要受支持的 CLI 后端（例如 Claude CLI）时使用它。关于心智
|
||||
模型，参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -388,14 +396,14 @@ Skills 提示词预算的按智能体覆盖。
|
||||
}
|
||||
```
|
||||
|
||||
- `id`：`"auto"`、`"pi"`、已注册的插件 harness ID，或受支持的 CLI 后端别名。内置 Codex 插件注册 `codex`；内置 Anthropic 插件提供 `claude-cli` CLI 后端。
|
||||
- `fallback`：`"pi"` 或 `"none"`。在 `id: "auto"` 中，省略的 fallback 默认值为 `"pi"`，因此旧配置在没有插件 harness 认领某次运行时仍可继续使用 PI。在显式插件运行时模式（例如 `id: "codex"`）中，省略的 fallback 默认值为 `"none"`，因此缺失 harness 会失败，而不是静默使用 PI。运行时覆盖项不会从更广作用域继承 fallback；当你有意需要该兼容性回退时，请在显式运行时旁同时设置 `fallback: "pi"`。所选插件 harness 的失败始终会直接暴露。
|
||||
- `id`：`"auto"`、`"pi"`、已注册的插件执行框架 ID，或受支持的 CLI 后端别名。内置 Codex 插件注册 `codex`；内置 Anthropic 插件提供 `claude-cli` CLI 后端。
|
||||
- `fallback`：`"pi"` 或 `"none"`。在 `id: "auto"` 中，省略的 fallback 默认值为 `"pi"`，因此旧配置可在没有插件执行框架认领运行时继续使用 PI。在显式插件运行时模式中，例如 `id: "codex"`，省略的 fallback 默认值为 `"none"`，因此缺失执行框架会失败，而不是静默使用 PI。运行时覆盖不会从更宽的作用域继承 fallback；当你有意需要该兼容性回退时，请在显式运行时旁边设置 `fallback: "pi"`。选定的插件执行框架失败始终会直接暴露。
|
||||
- 环境覆盖：`OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` 覆盖 `id`；`OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` 覆盖该进程的 fallback。
|
||||
- 对于仅使用 Codex 的部署，设置 `model: "openai/gpt-5.5"` 和 `agentRuntime.id: "codex"`。你也可以显式设置 `agentRuntime.fallback: "none"` 以提升可读性；它是显式插件运行时的默认值。
|
||||
- 对于 Claude CLI 部署，优先使用 `model: "anthropic/claude-opus-4-7"` 加 `agentRuntime.id: "claude-cli"`。旧版 `claude-cli/claude-opus-4-7` 模型引用仍可用于兼容，但新配置应保持提供商/模型选择的规范形式，并将执行后端放在 `agentRuntime.id` 中。
|
||||
- 旧版运行时策略键会由 `openclaw doctor --fix` 重写为 `agentRuntime`。
|
||||
- 第一次嵌入式运行后，harness 选择会按会话 ID 固定。配置/环境变化会影响新的或重置的会话，不影响现有 transcript。存在 transcript 历史但没有记录固定项的旧版会话会被视为已固定到 PI。`/status` 会报告有效运行时，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。
|
||||
- 这只控制文本智能体轮次执行。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用它们的提供商/模型设置。
|
||||
- 对于仅 Codex 的部署，设置 `model: "openai/gpt-5.5"` 和 `agentRuntime.id: "codex"`。你也可以为可读性显式设置 `agentRuntime.fallback: "none"`；这是显式插件运行时的默认值。
|
||||
- 对于 Claude CLI 部署，优先使用 `model: "anthropic/claude-opus-4-7"` 加 `agentRuntime.id: "claude-cli"`。旧版 `claude-cli/claude-opus-4-7` 模型引用仍可出于兼容性工作，但新配置应保持提供商/模型选择为规范形式，并将执行后端放在 `agentRuntime.id` 中。
|
||||
- 较旧的运行时策略键会由 `openclaw doctor --fix` 重写为 `agentRuntime`。
|
||||
- 首次嵌入式运行后，执行框架选择会按会话 ID 固定。配置/环境更改会影响新的或已重置的会话，而不会影响现有 transcript。带有 transcript 历史但没有记录固定选择的旧版会话会被视为固定到 PI。`/status` 会报告有效运行时，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。
|
||||
- 这仅控制文本智能体轮次执行。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用它们的提供商/模型设置。
|
||||
|
||||
**内置别名简写**（仅当模型位于 `agents.defaults.models` 中时适用）：
|
||||
|
||||
@ -403,7 +411,7 @@ Skills 提示词预算的按智能体覆盖。
|
||||
| ------------------- | ------------------------------------------ |
|
||||
| `opus` | `anthropic/claude-opus-4-6` |
|
||||
| `sonnet` | `anthropic/claude-sonnet-4-6` |
|
||||
| `gpt` | `openai/gpt-5.5` 或 `openai-codex/gpt-5.5` |
|
||||
| `gpt` | `openai/gpt-5.5` or `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` |
|
||||
@ -413,12 +421,12 @@ Skills 提示词预算的按智能体覆盖。
|
||||
你配置的别名始终优先于默认值。
|
||||
|
||||
Z.AI GLM-4.x 模型会自动启用思考模式，除非你设置 `--thinking off` 或自行定义 `agents.defaults.models["zai/<model>"].params.thinking`。
|
||||
Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/<model>"].params.tool_stream` 设置为 `false` 可禁用它。
|
||||
Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adaptive` 思考。
|
||||
Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/<model>"].params.tool_stream` 设为 `false` 可禁用它。
|
||||
Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `adaptive` 思考。
|
||||
|
||||
### `agents.defaults.cliBackends`
|
||||
|
||||
用于纯文本回退运行的可选 CLI 后端（无工具调用）。当 API 提供商失败时可作为备用方案。
|
||||
用于纯文本回退运行的可选 CLI 后端（无工具调用）。当 API 提供商失败时，可作为备用方案。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -447,13 +455,13 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adapti
|
||||
}
|
||||
```
|
||||
|
||||
- CLI 后端以文本优先；工具始终被禁用。
|
||||
- CLI 后端以文本优先；工具始终禁用。
|
||||
- 设置 `sessionArg` 时支持会话。
|
||||
- 当 `imageArg` 接受文件路径时，支持图片透传。
|
||||
- 当 `imageArg` 接受文件路径时支持图像透传。
|
||||
|
||||
### `agents.defaults.systemPromptOverride`
|
||||
|
||||
用固定字符串替换整个由 OpenClaw 组装的系统提示。可在默认级别（`agents.defaults.systemPromptOverride`）或每个智能体（`agents.list[].systemPromptOverride`）设置。每个智能体的值优先；空值或仅含空白的值会被忽略。适用于受控的提示实验。
|
||||
用固定字符串替换整个由 OpenClaw 组装的系统提示。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体（`agents.list[].systemPromptOverride`）设置。按智能体的值优先；空值或仅包含空白的值会被忽略。适用于受控提示实验。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -467,7 +475,7 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adapti
|
||||
|
||||
### `agents.defaults.promptOverlays`
|
||||
|
||||
按模型系列应用的、与提供商无关的提示叠加层。GPT-5 系列模型 ID 会跨提供商接收共享行为契约；`personality` 仅控制友好的交互风格层。
|
||||
按模型系列应用的提供商无关提示叠加层。GPT-5 系列模型 ID 会跨提供商接收共享行为契约；`personality` 只控制友好的交互风格层。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -483,13 +491,13 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adapti
|
||||
}
|
||||
```
|
||||
|
||||
- `"friendly"`（默认）和 `"on"` 会启用友好的交互风格层。
|
||||
- `"off"` 仅禁用友好层；带标记的 GPT-5 行为契约仍会启用。
|
||||
- 当此共享设置未设置时，仍会读取旧版 `plugins.entries.openai.config.personality`。
|
||||
- `"friendly"`（默认）和 `"on"` 启用友好的交互风格层。
|
||||
- `"off"` 只禁用友好层；带标签的 GPT-5 行为契约仍保持启用。
|
||||
- 当未设置此共享设置时，仍会读取旧版 `plugins.entries.openai.config.personality`。
|
||||
|
||||
### `agents.defaults.heartbeat`
|
||||
|
||||
周期性心跳运行。
|
||||
周期性 Heartbeat 运行。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -517,16 +525,16 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adapti
|
||||
}
|
||||
```
|
||||
|
||||
- `every`：时长字符串（ms/s/m/h）。默认：`30m`（API 密钥凭证）或 `1h`（OAuth 凭证）。设置为 `0m` 可禁用。
|
||||
- `includeSystemPromptSection`：为 false 时，从系统提示中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入引导上下文。默认：`true`。
|
||||
- `suppressToolErrorWarnings`：为 true 时，在心跳运行期间抑制工具错误警告载荷。
|
||||
- `timeoutSeconds`：心跳智能体轮次在被中止前允许的最长秒数。留空则使用 `agents.defaults.timeoutSeconds`。
|
||||
- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 凭证）或 `1h`（OAuth 凭证）。设为 `0m` 可禁用。
|
||||
- `includeSystemPromptSection`：为 false 时，会从系统提示中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入到启动上下文。默认值：`true`。
|
||||
- `suppressToolErrorWarnings`：为 true 时，在 Heartbeat 运行期间抑制工具错误警告载荷。
|
||||
- `timeoutSeconds`：Heartbeat 智能体轮次在中止前允许的最长秒数。未设置时使用 `agents.defaults.timeoutSeconds`。
|
||||
- `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 抑制直接目标投递并发出 `reason=dm-blocked`。
|
||||
- `lightContext`：为 true 时，心跳运行使用轻量级引导上下文，并且仅从工作区引导文件保留 `HEARTBEAT.md`。
|
||||
- `isolatedSession`：为 true 时，每次心跳都会在没有先前对话历史的新会话中运行。与 cron `sessionTarget: "isolated"` 相同的隔离模式。将每次心跳的 token 成本从约 100K 降至约 2-5K token。
|
||||
- `skipWhenBusy`：为 true 时，心跳运行会在额外繁忙通道上延后：子智能体或嵌套命令工作。即使没有此标志，Cron 通道也始终会延后心跳。
|
||||
- 每个智能体：设置 `agents.list[].heartbeat`。当任何智能体定义了 `heartbeat` 时，**只有这些智能体**会运行心跳。
|
||||
- 心跳会运行完整智能体轮次，更短的间隔会消耗更多 token。
|
||||
- `lightContext`：为 true 时，Heartbeat 运行使用轻量启动上下文，并且只保留工作区启动文件中的 `HEARTBEAT.md`。
|
||||
- `isolatedSession`：为 true 时，每次 Heartbeat 都在没有先前对话历史的新会话中运行。与 cron `sessionTarget: "isolated"` 相同的隔离模式。将每次 Heartbeat 的令牌成本从约 100K 降至约 2-5K 令牌。
|
||||
- `skipWhenBusy`：为 true 时，Heartbeat 运行会在额外繁忙通道上延后：子智能体或嵌套命令工作。即使没有此标志，Cron 通道也始终会延后 Heartbeat。
|
||||
- 按智能体：设置 `agents.list[].heartbeat`。当任何智能体定义了 `heartbeat` 时，**只有这些智能体**会运行 Heartbeat。
|
||||
- Heartbeat 会运行完整的智能体轮次，间隔越短消耗的令牌越多。
|
||||
|
||||
### `agents.defaults.compaction`
|
||||
|
||||
@ -561,22 +569,22 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adapti
|
||||
}
|
||||
```
|
||||
|
||||
- `mode`：`default` 或 `safeguard`（用于长历史的分块摘要）。参见 [压缩](/zh-CN/concepts/compaction)。
|
||||
- `provider`：已注册压缩提供商插件的 ID。设置后会调用该提供商的 `summarize()`，而不是内置 LLM 摘要。失败时会回退到内置方式。设置提供商会强制 `mode: "safeguard"`。参见 [压缩](/zh-CN/concepts/compaction)。
|
||||
- `timeoutSeconds`：OpenClaw 中止单次压缩操作前允许的最长秒数。默认：`900`。
|
||||
- `keepRecentTokens`：用于逐字保留最近 transcript 尾部的 Pi 分割点预算。手动 `/compact` 在显式设置时会遵循此值；否则手动压缩是一个硬检查点。
|
||||
- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在压缩摘要期间预置内置的不透明标识符保留指引。
|
||||
- `mode`：`default` 或 `safeguard`（用于长历史的分块摘要）。参见[压缩](/zh-CN/concepts/compaction)。
|
||||
- `provider`：已注册压缩提供商插件的 ID。设置后会调用该提供商的 `summarize()`，而不是内置 LLM 摘要。失败时回退到内置方式。设置提供商会强制使用 `mode: "safeguard"`。参见[压缩](/zh-CN/concepts/compaction)。
|
||||
- `timeoutSeconds`：单个压缩操作在 OpenClaw 中止前允许的最长秒数。默认值：`900`。
|
||||
- `keepRecentTokens`：用于逐字保留最近 transcript 尾部的 Pi 截断点预算。手动 `/compact` 在显式设置时会遵循此值；否则手动压缩是硬检查点。
|
||||
- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在压缩摘要期间前置内置的不透明标识符保留指导。
|
||||
- `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。
|
||||
- `qualityGuard`：针对 safeguard 摘要的格式异常输出重试检查。在 safeguard 模式下默认启用；设置 `enabled: false` 可跳过审核。
|
||||
- `postCompactionSections`：压缩后要重新注入的可选 AGENTS.md H2/H3 部分名称。默认为 `["Session Startup", "Red Lines"]`；设置 `[]` 可禁用重新注入。当未设置或显式设置为该默认组合时，也接受旧版 `Every Session`/`Safety` 标题作为旧版回退。
|
||||
- `model`：仅用于压缩摘要的可选 `provider/model-id` 覆盖。当主会话应保留一个模型、而压缩摘要应在另一个模型上运行时使用；未设置时，压缩使用会话的主模型。
|
||||
- `maxActiveTranscriptBytes`：可选字节阈值（`number` 或类似 `"20mb"` 的字符串），当活跃 JSONL 超过该阈值时，会在运行前触发普通本地压缩。需要 `truncateAfterCompaction`，以便成功压缩后可以轮转到更小的后继 transcript。未设置或为 `0` 时禁用。
|
||||
- `notifyUser`：为 `true` 时，在压缩开始和完成时向用户发送简短通知（例如，“正在压缩上下文...”和“压缩完成”）。默认禁用，以保持压缩静默。
|
||||
- `memoryFlush`：自动压缩前的静默智能体轮次，用于存储持久记忆。当这个维护轮次应留在本地模型上时，将 `model` 设置为确切的提供商/模型，例如 `ollama/qwen3:8b`；该覆盖不会继承活跃会话的回退链。当工作区为只读时会跳过。
|
||||
- `qualityGuard`：针对 safeguard 摘要的格式错误输出重试检查。在 safeguard 模式下默认启用；设置 `enabled: false` 可跳过审计。
|
||||
- `postCompactionSections`：压缩后要重新注入的可选 AGENTS.md H2/H3 章节名称。默认为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。当未设置或显式设置为该默认对时，较旧的 `Every Session`/`Safety` 标题也会作为旧版回退被接受。
|
||||
- `model`：仅用于压缩摘要的可选 `provider/model-id` 覆盖。当主会话应保留一个模型但压缩摘要应在另一个模型上运行时使用；未设置时，压缩会使用会话的主模型。
|
||||
- `maxActiveTranscriptBytes`：可选字节阈值（`number` 或类似 `"20mb"` 的字符串），当活跃 JSONL 超过该阈值时，在运行前触发普通本地压缩。需要 `truncateAfterCompaction`，以便成功压缩后可以轮换到更小的后继 transcript。未设置或为 `0` 时禁用。
|
||||
- `notifyUser`：为 `true` 时，在压缩开始和完成时向用户发送简短通知（例如，“正在压缩上下文...”和“压缩完成”）。默认禁用以保持压缩静默。
|
||||
- `memoryFlush`：自动压缩前用于存储持久记忆的静默 agentic 轮次。当此清理轮次应留在本地模型上时，将 `model` 设置为精确的 provider/model，例如 `ollama/qwen3:8b`；该覆盖不会继承活跃会话的回退链。当工作区为只读时跳过。
|
||||
|
||||
### `agents.defaults.contextPruning`
|
||||
|
||||
在发送给 LLM 前，从内存上下文中修剪**旧工具结果**。**不会**修改磁盘上的会话历史。
|
||||
在发送给 LLM 前，从内存上下文中剪除**旧工具结果**。**不会**修改磁盘上的会话历史。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -600,23 +608,23 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adapti
|
||||
|
||||
<Accordion title="cache-ttl mode behavior">
|
||||
|
||||
- `mode: "cache-ttl"` 启用修剪流程。
|
||||
- `ttl` 控制修剪在多久之后可以再次运行（从上次缓存触碰后计算）。
|
||||
- 修剪会先软修剪过大的工具结果，然后在需要时硬清除更旧的工具结果。
|
||||
- `mode: "cache-ttl"` 启用剪除过程。
|
||||
- `ttl` 控制剪除多久可以再次运行（从上次缓存触碰后开始计算）。
|
||||
- 剪除会先软裁剪过大的工具结果，然后在需要时硬清除更旧的工具结果。
|
||||
|
||||
**软修剪**会保留开头 + 结尾，并在中间插入 `...`。
|
||||
**软裁剪**保留开头 + 结尾，并在中间插入 `...`。
|
||||
|
||||
**硬清除**会用占位符替换整个工具结果。
|
||||
**硬清除**将整个工具结果替换为占位符。
|
||||
|
||||
注意：
|
||||
|
||||
- 图片块永远不会被修剪/清除。
|
||||
- 比例基于字符（近似），不是精确 token 数。
|
||||
- 如果助手消息少于 `keepLastAssistants` 条，则跳过修剪。
|
||||
- 图像块永远不会被裁剪/清除。
|
||||
- 比率按字符计算（近似），不是精确的令牌数。
|
||||
- 如果 assistant 消息少于 `keepLastAssistants` 条，则跳过剪除。
|
||||
|
||||
</Accordion>
|
||||
|
||||
参见 [会话修剪](/zh-CN/concepts/session-pruning) 了解行为详情。
|
||||
行为详情参见[会话剪除](/zh-CN/concepts/session-pruning)。
|
||||
|
||||
### 分块流式传输
|
||||
|
||||
@ -635,12 +643,12 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adapti
|
||||
```
|
||||
|
||||
- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。
|
||||
- 渠道覆盖：`channels.<channel>.blockStreamingCoalesce`（以及每个账号的变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。
|
||||
- `humanDelay`：分块回复之间的随机暂停。`natural` = 800-2500ms。每个智能体覆盖：`agents.list[].humanDelay`。
|
||||
- 渠道覆盖：`channels.<channel>.blockStreamingCoalesce`（以及按账号的变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。
|
||||
- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。按智能体覆盖：`agents.list[].humanDelay`。
|
||||
|
||||
参见 [流式传输](/zh-CN/concepts/streaming) 了解行为 + 分块详情。
|
||||
行为和分块详情参见[流式传输](/zh-CN/concepts/streaming)。
|
||||
|
||||
### 输入状态指示器
|
||||
### 正在输入指示器
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -656,13 +664,13 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adapti
|
||||
- 默认值：直接聊天/提及时为 `instant`，未提及的群聊中为 `message`。
|
||||
- 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。
|
||||
|
||||
参见[输入状态指示器](/zh-CN/concepts/typing-indicators)。
|
||||
参见 [正在输入指示器](/zh-CN/concepts/typing-indicators)。
|
||||
|
||||
<a id="agentsdefaultssandbox"></a>
|
||||
|
||||
### `agents.defaults.sandbox`
|
||||
|
||||
嵌入式智能体的可选沙箱隔离。完整指南请参见[沙箱隔离](/zh-CN/gateway/sandboxing)。
|
||||
嵌入式智能体的可选沙箱隔离。完整指南见 [沙箱隔离](/zh-CN/gateway/sandboxing)。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -757,7 +765,7 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adapti
|
||||
}
|
||||
```
|
||||
|
||||
<Accordion title="Sandbox details">
|
||||
<Accordion title="沙箱详情">
|
||||
|
||||
**后端：**
|
||||
|
||||
@ -770,12 +778,12 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adapti
|
||||
|
||||
**SSH 后端配置：**
|
||||
|
||||
- `target`：`user@host[:port]` 格式的 SSH 目标
|
||||
- `target`：`user@host[:port]` 形式的 SSH 目标
|
||||
- `command`：SSH 客户端命令（默认：`ssh`）
|
||||
- `workspaceRoot`：用于各作用域工作区的绝对远程根目录
|
||||
- `workspaceRoot`：用于按作用域工作区的绝对远程根目录
|
||||
- `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件
|
||||
- `identityData` / `certificateData` / `knownHostsData`：OpenClaw 在运行时具现化为临时文件的内联内容或 SecretRef
|
||||
- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关
|
||||
- `identityData` / `certificateData` / `knownHostsData`：OpenClaw 在运行时物化为临时文件的内联内容或 SecretRef
|
||||
- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略旋钮
|
||||
|
||||
**SSH 凭证优先级：**
|
||||
|
||||
@ -786,15 +794,15 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adapti
|
||||
|
||||
**SSH 后端行为：**
|
||||
|
||||
- 创建或重新创建后播种一次远程工作区
|
||||
- 然后保持远程 SSH 工作区为权威版本
|
||||
- 创建或重新创建后对远程工作区进行一次种子初始化
|
||||
- 随后保持远程 SSH 工作区为权威来源
|
||||
- 通过 SSH 路由 `exec`、文件工具和媒体路径
|
||||
- 不会自动将远程变更同步回主机
|
||||
- 不会自动把远程更改同步回主机
|
||||
- 不支持沙箱浏览器容器
|
||||
|
||||
**工作区访问：**
|
||||
|
||||
- `none`：`~/.openclaw/sandboxes` 下按作用域划分的沙箱工作区
|
||||
- `none`：位于 `~/.openclaw/sandboxes` 下的按作用域沙箱工作区
|
||||
- `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent`
|
||||
- `rw`：智能体工作区以读写方式挂载到 `/workspace`
|
||||
|
||||
@ -832,30 +840,30 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adapti
|
||||
|
||||
**OpenShell 模式：**
|
||||
|
||||
- `mirror`：执行前从本地播种远程，执行后同步回来；本地工作区保持为权威版本
|
||||
- `remote`：创建沙箱时播种一次远程，然后保持远程工作区为权威版本
|
||||
- `mirror`：exec 前从本地为远程初始化，exec 后同步回来；本地工作区保持为权威来源
|
||||
- `remote`：创建沙箱时为远程初始化一次，随后保持远程工作区为权威来源
|
||||
|
||||
在 `remote` 模式下，播种步骤之后，在 OpenClaw 外部进行的主机本地编辑不会自动同步到沙箱。
|
||||
在 `remote` 模式下，种子步骤完成后，在 OpenClaw 之外对主机本地所做的编辑不会自动同步到沙箱中。
|
||||
传输方式是通过 SSH 进入 OpenShell 沙箱，但插件负责沙箱生命周期和可选的镜像同步。
|
||||
|
||||
**`setupCommand`** 在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根目录和 root 用户。
|
||||
**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根目录、root 用户。
|
||||
|
||||
**容器默认使用 `network: "none"`**，如果智能体需要出站访问，请设为 `"bridge"`（或自定义桥接网络）。
|
||||
`"host"` 被阻止。默认情况下 `"container:<id>"` 被阻止，除非你显式设置
|
||||
**容器默认使用 `network: "none"`** — 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义桥接网络）。
|
||||
`"host"` 会被阻止。默认情况下 `"container:<id>"` 会被阻止，除非你显式设置
|
||||
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急破例）。
|
||||
|
||||
**入站附件**会暂存到活动工作区中的 `media/inbound/*`。
|
||||
**入站附件** 会暂存到活动工作区中的 `media/inbound/*`。
|
||||
|
||||
**`docker.binds`** 会挂载额外主机目录；全局绑定和按智能体绑定会合并。
|
||||
**`docker.binds`** 挂载额外的主机目录；全局绑定和按智能体绑定会合并。
|
||||
|
||||
**沙箱隔离浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。noVNC URL 会注入系统提示。不需要在 `openclaw.json` 中设置 `browser.enabled`。
|
||||
noVNC 观察者访问默认使用 VNC 凭证，OpenClaw 会发出短期令牌 URL（而不是在共享 URL 中暴露密码）。
|
||||
**沙箱隔离浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。noVNC URL 会注入系统提示词。不需要在 `openclaw.json` 中设置 `browser.enabled`。
|
||||
noVNC 观察者访问默认使用 VNC 身份验证，OpenClaw 会发出短期有效的令牌 URL（而不是在共享 URL 中暴露密码）。
|
||||
|
||||
- `allowHostControl: false`（默认）会阻止沙箱隔离会话以主机浏览器为目标。
|
||||
- `network` 默认值为 `openclaw-sandbox-browser`（专用桥接网络）。只有在你明确需要全局桥接连通性时才设置为 `bridge`。
|
||||
- `cdpSourceRange` 可选地将容器边缘的 CDP 入站限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。
|
||||
- `sandbox.browser.binds` 只会将额外主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`）会替换浏览器容器的 `docker.binds`。
|
||||
- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机进行了调优：
|
||||
- `network` 默认为 `openclaw-sandbox-browser`（专用桥接网络）。仅当你明确想要全局桥接连通性时才设置为 `bridge`。
|
||||
- `cdpSourceRange` 可选地将容器边缘的 CDP 入站限制为一个 CIDR 范围（例如 `172.21.0.1/32`）。
|
||||
- `sandbox.browser.binds` 仅将额外的主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。
|
||||
- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机调优：
|
||||
- `--remote-debugging-address=127.0.0.1`
|
||||
- `--remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>`
|
||||
- `--user-data-dir=${HOME}/.chrome`
|
||||
@ -874,15 +882,16 @@ noVNC 观察者访问默认使用 VNC 凭证，OpenClaw 会发出短期令牌 UR
|
||||
- `--metrics-recording-only`
|
||||
- `--disable-extensions`（默认启用）
|
||||
- `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu`
|
||||
默认启用；如果 WebGL/3D 使用需要，可以通过
|
||||
默认启用；如果 WebGL/3D 用法需要，可以用
|
||||
`OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用。
|
||||
- 如果你的工作流依赖扩展，`OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会重新启用扩展。
|
||||
- `--renderer-process-limit=2` 可通过
|
||||
- 如果你的工作流依赖扩展，
|
||||
`OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会重新启用扩展。
|
||||
- `--renderer-process-limit=2` 可以通过
|
||||
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>` 更改；设置为 `0` 可使用 Chromium 的
|
||||
默认进程限制。
|
||||
- 当 `noSandbox` 启用时，另加 `--no-sandbox`。
|
||||
- 默认值是容器镜像基线；使用带有自定义
|
||||
入口点的自定义浏览器镜像来更改容器默认值。
|
||||
- 启用 `noSandbox` 时还会加上 `--no-sandbox`。
|
||||
- 默认值是容器镜像基线；要更改容器默认值，请使用带自定义
|
||||
入口点的自定义浏览器镜像。
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -897,12 +906,12 @@ scripts/sandbox-browser-setup.sh # optional browser image
|
||||
|
||||
### `agents.list`（按智能体覆盖）
|
||||
|
||||
使用 `agents.list[].tts` 为某个智能体配置自己的 TTS 提供商、语音、模型、
|
||||
使用 `agents.list[].tts` 为智能体指定自己的 TTS 提供商、语音、模型、
|
||||
风格或自动 TTS 模式。智能体块会深度合并到全局
|
||||
`messages.tts` 之上，因此共享凭证可以保留在一个位置，而各个
|
||||
`messages.tts` 之上，因此共享凭证可以保存在一个位置，而各个
|
||||
智能体只覆盖它们需要的语音或提供商字段。活动智能体的
|
||||
覆盖会应用于自动语音回复、`/tts audio`、`/tts status` 和
|
||||
`tts` 智能体工具。提供商示例和优先级请参见[文本转语音](/zh-CN/tools/tts#per-agent-voice-overrides)。
|
||||
覆盖适用于自动语音回复、`/tts audio`、`/tts status` 和
|
||||
`tts` 智能体工具。提供商示例和优先级见 [文本转语音](/zh-CN/tools/tts#per-agent-voice-overrides)。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -956,28 +965,28 @@ scripts/sandbox-browser-setup.sh # optional browser image
|
||||
}
|
||||
```
|
||||
|
||||
- `id`: 稳定的智能体标识（必填）。
|
||||
- `default`: 当设置了多个时，第一个生效（会记录警告）。如果未设置任何一个，则列表中的第一项为默认值。
|
||||
- `model`: 字符串形式会为每个智能体设置严格的 primary，且没有模型回退；对象形式 `{ primary }` 也是严格的，除非你添加 `fallbacks`。使用 `{ primary, fallbacks: [...] }` 让该智能体启用回退，或使用 `{ primary, fallbacks: [] }` 显式声明严格行为。仅覆盖 `primary` 的定时任务仍会继承默认回退，除非你设置 `fallbacks: []`。
|
||||
- `params`: 每个智能体的流式参数，会覆盖合并到 `agents.defaults.models` 中所选的模型条目。使用它设置智能体专用覆盖项，例如 `cacheRetention`、`temperature` 或 `maxTokens`，无需复制整个模型目录。
|
||||
- `tts`: 可选的每个智能体文本转语音覆盖项。该块会深度合并到 `messages.tts` 之上，因此请在 `messages.tts` 中保留共享的提供商凭证和回退策略，并仅在此处设置人设专用值，例如 provider、voice、model、style 或自动模式。
|
||||
- `skills`: 可选的每个智能体 Skills 允许列表。如果省略，则智能体会在设置了 `agents.defaults.skills` 时继承它；显式列表会替换默认值而不是合并，`[]` 表示没有 Skills。
|
||||
- `thinkingDefault`: 可选的每个智能体默认思考级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当未设置每条消息或会话级覆盖项时，它会为此智能体覆盖 `agents.defaults.thinkingDefault`。所选的提供商/模型配置文件会控制哪些值有效；对于 Google Gemini，`adaptive` 会保留提供商托管的动态思考（Gemini 3/3.1 上省略 `thinkingLevel`，Gemini 2.5 上使用 `thinkingBudget: -1`）。
|
||||
- `reasoningDefault`: 可选的每个智能体默认推理可见性（`on | off | stream`）。当未设置每条消息或会话级推理覆盖项时，它会为此智能体覆盖 `agents.defaults.reasoningDefault`。
|
||||
- `fastModeDefault`: 可选的每个智能体快速模式默认值（`true | false`）。当未设置每条消息或会话级快速模式覆盖项时适用。
|
||||
- `agentRuntime`: 可选的每个智能体低层运行时策略覆盖项。使用 `{ id: "codex" }` 可让一个智能体仅使用 Codex，而其他智能体在 `auto` 模式下保留默认 Pi 回退。
|
||||
- `runtime`: 可选的每个智能体运行时描述符。当智能体应默认使用 ACP 执行框架会话时，使用 `type: "acp"` 以及 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。
|
||||
- `identity.avatar`: 工作区相对路径、`http(s)` URL 或 `data:` URI。
|
||||
- `id`：稳定的智能体 ID（必填）。
|
||||
- `default`：设置多个时，第一个生效（会记录警告）。如果未设置，列表中的第一个条目就是默认值。
|
||||
- `model`：字符串形式会设置严格的每智能体主模型，且没有模型回退；对象形式 `{ primary }` 同样严格，除非你添加 `fallbacks`。使用 `{ primary, fallbacks: [...] }` 让该智能体启用回退，或使用 `{ primary, fallbacks: [] }` 明确启用严格行为。只覆盖 `primary` 的 Cron 任务仍会继承默认回退，除非你设置 `fallbacks: []`。
|
||||
- `params`：每智能体流参数，会合并覆盖 `agents.defaults.models` 中选定的模型条目。使用它为智能体设置专属覆盖项，例如 `cacheRetention`、`temperature` 或 `maxTokens`，无需复制整个模型目录。
|
||||
- `tts`：可选的每智能体文本转语音覆盖项。该块会深度合并到 `messages.tts` 之上，因此请把共享提供商凭证和回退策略放在 `messages.tts` 中，并且这里只设置角色专属值，例如提供商、语音、模型、风格或自动模式。
|
||||
- `skills`：可选的每智能体技能允许列表。如果省略，智能体会在设置了 `agents.defaults.skills` 时继承它；显式列表会替换默认值而不是合并，`[]` 表示没有 Skills。
|
||||
- `thinkingDefault`：可选的每智能体默认思考等级（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当未设置每条消息或会话覆盖项时，会覆盖此智能体的 `agents.defaults.thinkingDefault`。所选提供商/模型配置控制哪些值有效；对于 Google Gemini，`adaptive` 会保留提供商拥有的动态思考（Gemini 3/3.1 上省略 `thinkingLevel`，Gemini 2.5 上为 `thinkingBudget: -1`）。
|
||||
- `reasoningDefault`：可选的每智能体默认推理可见性（`on | off | stream`）。当未设置每条消息或会话推理覆盖项时，会覆盖此智能体的 `agents.defaults.reasoningDefault`。
|
||||
- `fastModeDefault`：可选的每智能体快速模式默认值（`true | false`）。当未设置每条消息或会话快速模式覆盖项时适用。
|
||||
- `agentRuntime`：可选的每智能体低层运行时策略覆盖项。使用 `{ id: "codex" }` 可让一个智能体仅使用 Codex，而其他智能体在 `auto` 模式下保留默认 Pi 回退。
|
||||
- `runtime`：可选的每智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，将 `type: "acp"` 与 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）搭配使用。
|
||||
- `identity.avatar`：工作区相对路径、`http(s)` URL 或 `data:` URI。
|
||||
- `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name`/`emoji`。
|
||||
- `subagents.allowAgents`: 显式 `sessions_spawn.agentId` 目标的智能体标识允许列表（`["*"]` = 任意；默认：仅同一智能体）。当应允许以自身为目标的 `agentId` 调用时，请包含请求者标识。
|
||||
- 沙箱继承保护：如果请求者会话处于沙箱隔离状态，`sessions_spawn` 会拒绝将在无沙箱隔离状态下运行的目标。
|
||||
- `subagents.requireAgentId`: 为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置文件；默认：false）。
|
||||
- `subagents.allowAgents`：用于显式 `sessions_spawn.agentId` 目标的智能体 ID 允许列表（`["*"]` = 任意；默认：仅同一智能体）。当应允许自指向的 `agentId` 调用时，请包含请求者 ID。
|
||||
- 沙箱继承保护：如果请求者会话是沙箱隔离的，`sessions_spawn` 会拒绝会以非沙箱隔离方式运行的目标。
|
||||
- `subagents.requireAgentId`：为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置档；默认：false）。
|
||||
|
||||
---
|
||||
|
||||
## 多智能体路由
|
||||
|
||||
在一个 Gateway 网关中运行多个隔离的智能体。参见 [多智能体](/zh-CN/concepts/multi-agent)。
|
||||
在一个 Gateway 网关内运行多个隔离智能体。参见 [多智能体](/zh-CN/concepts/multi-agent)。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -996,11 +1005,11 @@ scripts/sandbox-browser-setup.sh # optional browser image
|
||||
|
||||
### 绑定匹配字段
|
||||
|
||||
- `type`（可选）：`route` 用于普通路由（缺少 type 时默认为 route），`acp` 用于持久 ACP 对话绑定。
|
||||
- `type`（可选）：`route` 用于普通路由（缺少类型时默认是 route），`acp` 用于持久 ACP 对话绑定。
|
||||
- `match.channel`（必填）
|
||||
- `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号）
|
||||
- `match.accountId`（可选；`*` = 任意账户；省略 = 默认账户）
|
||||
- `match.peer`（可选；`{ kind: direct|group|channel, id }`）
|
||||
- `match.guildId` / `match.teamId`（可选；特定渠道）
|
||||
- `match.guildId` / `match.teamId`（可选；渠道专属）
|
||||
- `acp`（可选；仅用于 `type: "acp"`）：`{ mode, label, cwd, backend }`
|
||||
|
||||
**确定性匹配顺序：**
|
||||
@ -1008,15 +1017,15 @@ scripts/sandbox-browser-setup.sh # optional browser image
|
||||
1. `match.peer`
|
||||
2. `match.guildId`
|
||||
3. `match.teamId`
|
||||
4. `match.accountId`（精确匹配，无 peer/guild/team）
|
||||
5. `match.accountId: "*"`（渠道范围）
|
||||
4. `match.accountId`（精确，无 peer/guild/team）
|
||||
5. `match.accountId: "*"`（整个渠道）
|
||||
6. 默认智能体
|
||||
|
||||
在每个层级中，第一个匹配的 `bindings` 条目生效。
|
||||
在每一层中，第一个匹配的 `bindings` 条目生效。
|
||||
|
||||
对于 `type: "acp"` 条目，OpenClaw 按精确的对话身份（`match.channel` + 账号 + `match.peer.id`）解析，而不使用上述路由绑定层级顺序。
|
||||
对于 `type: "acp"` 条目，OpenClaw 会按精确对话身份（`match.channel` + account + `match.peer.id`）解析，并且不会使用上面的 route 绑定层级顺序。
|
||||
|
||||
### 每个智能体的访问配置文件
|
||||
### 每智能体访问配置档
|
||||
|
||||
<Accordion title="完全访问（无沙箱）">
|
||||
|
||||
@ -1111,7 +1120,7 @@ scripts/sandbox-browser-setup.sh # optional browser image
|
||||
|
||||
</Accordion>
|
||||
|
||||
有关优先级详细信息，请参见 [多智能体沙箱与工具](/zh-CN/tools/multi-agent-sandbox-tools)。
|
||||
优先级详情见 [多智能体沙箱与工具](/zh-CN/tools/multi-agent-sandbox-tools)。
|
||||
|
||||
---
|
||||
|
||||
@ -1164,34 +1173,34 @@ scripts/sandbox-browser-setup.sh # optional browser image
|
||||
<Accordion title="会话字段详情">
|
||||
|
||||
- **`scope`**：群聊上下文的基础会话分组策略。
|
||||
- `per-sender`（默认）：每个发送者在一个渠道上下文中获得隔离的会话。
|
||||
- `per-sender`（默认）：每个发送者在一个渠道上下文中获得隔离会话。
|
||||
- `global`：一个渠道上下文中的所有参与者共享单个会话（仅在有意共享上下文时使用）。
|
||||
- **`dmScope`**：私信的分组方式。
|
||||
- `main`：所有私信共享主会话。
|
||||
- `per-peer`：跨渠道按发送者标识隔离。
|
||||
- `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。
|
||||
- `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。
|
||||
- **`identityLinks`**：将规范标识映射到带提供商前缀的对端，以实现跨渠道会话共享。`/dock_discord` 等 Dock 命令使用同一映射，将活动会话的回复路由切换到另一个已链接的渠道对端；参见 [渠道停靠](/zh-CN/concepts/channel-docking)。
|
||||
- **`reset`**：主重置策略。`daily` 在本地时间 `atHour` 重置；`idle` 在 `idleMinutes` 后重置。两者都配置时，先到期者生效。每日重置的新鲜度依据会话行的 `sessionStartedAt`；闲置重置的新鲜度依据 `lastInteractionAt`。心跳、定时唤醒、exec 通知和 Gateway 网关内部记录维护等后台/系统事件写入可以更新 `updatedAt`，但它们不会让每日/闲置会话保持有效状态。
|
||||
- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名。
|
||||
- **`parentForkMaxTokens`**：创建派生线程会话时允许的父会话 `totalTokens` 最大值（默认 `100000`）。
|
||||
- 如果父 `totalTokens` 高于此值，OpenClaw 会启动全新的线程会话，而不是继承父会话的对话记录历史。
|
||||
- 设置为 `0` 可禁用此保护并始终允许父会话派生。
|
||||
- **`mainKey`**：旧版字段。运行时始终对主直接聊天桶使用 `"main"`。
|
||||
- **`agentToAgent.maxPingPongTurns`**：智能体到智能体交换期间，智能体之间最大来回回复轮数（整数，范围：`0`–`5`）。`0` 禁用往返链式回复。
|
||||
- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 生效。
|
||||
- `per-peer`：跨渠道按发送者 ID 隔离。
|
||||
- `per-channel-peer`：按渠道 + 发送者隔离（建议用于多用户收件箱）。
|
||||
- `per-account-channel-peer`：按账户 + 渠道 + 发送者隔离（建议用于多账户）。
|
||||
- **`identityLinks`**：将规范 ID 映射到带提供商前缀的 peer，用于跨渠道共享会话。`/dock_discord` 等 Dock 命令使用同一映射，将活跃会话的回复路由切换到另一个已关联的渠道 peer；参见 [渠道停靠](/zh-CN/concepts/channel-docking)。
|
||||
- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。两者都配置时，先到期者生效。每日重置的新鲜度使用会话行的 `sessionStartedAt`；空闲重置的新鲜度使用 `lastInteractionAt`。后台/系统事件写入，例如 Heartbeat、Cron 唤醒、exec 通知和 Gateway 网关记账，可以更新 `updatedAt`，但它们不会让 daily/idle 会话保持新鲜。
|
||||
- **`resetByType`**：每类型覆盖项（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名。
|
||||
- **`parentForkMaxTokens`**：创建分叉线程会话时允许的父会话 `totalTokens` 最大值（默认 `100000`）。
|
||||
- 如果父级 `totalTokens` 高于此值，OpenClaw 会启动一个新的线程会话，而不是继承父级转录历史。
|
||||
- 设置为 `0` 可禁用此保护，并始终允许父级分叉。
|
||||
- **`mainKey`**：旧版字段。运行时始终使用 `"main"` 作为主直接聊天桶。
|
||||
- **`agentToAgent.maxPingPongTurns`**：智能体到智能体交换期间，智能体之间来回回复的最大轮数（整数，范围：`0`–`5`）。`0` 会禁用来回链式回复。
|
||||
- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，并带旧版 `dm` 别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 生效。
|
||||
- **`maintenance`**：会话存储清理 + 保留控制。
|
||||
- `mode`：`warn` 仅发出警告；`enforce` 执行清理。
|
||||
- `mode`：`warn` 仅发出警告；`enforce` 会执行清理。
|
||||
- `pruneAfter`：陈旧条目的年龄截止值（默认 `30d`）。
|
||||
- `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。运行时会用一个小的高水位缓冲批量写入清理，以适配生产规模上限；`openclaw sessions cleanup --enforce` 会立即应用该上限。
|
||||
- `rotateBytes`：已弃用并被忽略；`openclaw doctor --fix` 会将其从旧配置中移除。
|
||||
- `resetArchiveRetention`：`*.reset.<timestamp>` 对话记录归档的保留时间。默认值为 `pruneAfter`；设置为 `false` 可禁用。
|
||||
- `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会先移除最旧的产物/会话。
|
||||
- `highWaterBytes`：预算清理后的可选目标。默认值为 `maxDiskBytes` 的 `80%`。
|
||||
- `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。运行时会为生产规模上限使用较小高水位缓冲执行批量清理写入；`openclaw sessions cleanup --enforce` 会立即应用上限。
|
||||
- `rotateBytes`：已弃用并被忽略；`openclaw doctor --fix` 会从旧配置中移除它。
|
||||
- `resetArchiveRetention`：`*.reset.<timestamp>` 转录归档的保留期。默认值为 `pruneAfter`；设置为 `false` 可禁用。
|
||||
- `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会先移除最旧的工件/会话。
|
||||
- `highWaterBytes`：预算清理后的可选目标。默认是 `maxDiskBytes` 的 `80%`。
|
||||
- **`threadBindings`**：线程绑定会话功能的全局默认值。
|
||||
- `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`）
|
||||
- `idleHours`：默认闲置自动取消聚焦时长（小时）（`0` 禁用；提供商可覆盖）
|
||||
- `maxAgeHours`：默认硬性最大时长（小时）（`0` 禁用；提供商可覆盖）
|
||||
- `enabled`：主默认开关（提供商可以覆盖；Discord 使用 `channels.discord.threadBindings.enabled`）
|
||||
- `idleHours`：默认不活动自动取消聚焦小时数（`0` 禁用；提供商可以覆盖）
|
||||
- `maxAgeHours`：默认硬性最大年龄小时数（`0` 禁用；提供商可以覆盖）
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -1207,13 +1216,13 @@ scripts/sandbox-browser-setup.sh # optional browser image
|
||||
ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
|
||||
removeAckAfterReply: false,
|
||||
queue: {
|
||||
mode: "collect", // steer | followup | collect | steer-backlog | steer+backlog | queue | interrupt
|
||||
debounceMs: 1000,
|
||||
mode: "steer", // steer | followup | collect | steer-backlog | steer+backlog | queue | interrupt
|
||||
debounceMs: 500,
|
||||
cap: 20,
|
||||
drop: "summarize", // old | new | summarize
|
||||
byChannel: {
|
||||
whatsapp: "collect",
|
||||
telegram: "collect",
|
||||
whatsapp: "steer",
|
||||
telegram: "steer",
|
||||
},
|
||||
},
|
||||
inbound: {
|
||||
@ -1235,30 +1244,30 @@ scripts/sandbox-browser-setup.sh # optional browser image
|
||||
|
||||
**模板变量：**
|
||||
|
||||
| 变量 | 描述 | 示例 |
|
||||
| ----------------- | ---------------- | --------------------------- |
|
||||
| `{model}` | 短模型名称 | `claude-opus-4-6` |
|
||||
| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` |
|
||||
| `{provider}` | 提供商名称 | `anthropic` |
|
||||
| `{thinkingLevel}` | 当前思考级别 | `high`, `low`, `off` |
|
||||
| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） |
|
||||
| 变量 | 描述 | 示例 |
|
||||
| ----------------- | ------------------ | --------------------------- |
|
||||
| `{model}` | 短模型名称 | `claude-opus-4-6` |
|
||||
| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` |
|
||||
| `{provider}` | 提供商名称 | `anthropic` |
|
||||
| `{thinkingLevel}` | 当前思考级别 | `high`, `low`, `off` |
|
||||
| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） |
|
||||
|
||||
变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。
|
||||
|
||||
### 确认反应
|
||||
### 确认表情反应
|
||||
|
||||
- 默认使用活动智能体的 `identity.emoji`，否则为 `"👀"`。设置为 `""` 可禁用。
|
||||
- 默认使用活动智能体的 `identity.emoji`，否则使用 `"👀"`。设置为 `""` 可禁用。
|
||||
- 按渠道覆盖：`channels.<channel>.ackReaction`、`channels.<channel>.accounts.<id>.ackReaction`。
|
||||
- 解析顺序：账号 → 渠道 → `messages.ackReaction` → 身份回退值。
|
||||
- 作用范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。
|
||||
- `removeAckAfterReply`：在 Slack、Discord、Telegram、WhatsApp 和 BlueBubbles 等支持反应的渠道上，回复后移除确认反应。
|
||||
- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期 Status 反应。
|
||||
在 Slack 和 Discord 上，未设置时，如果确认反应处于活动状态，则保持 Status 反应启用。
|
||||
在 Telegram 上，需要显式设置为 `true` 才能启用生命周期 Status 反应。
|
||||
- `removeAckAfterReply`：在 Slack、Discord、Telegram、WhatsApp 和 BlueBubbles 等支持表情反应的渠道上，回复后移除确认表情反应。
|
||||
- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期 Status 表情反应。
|
||||
在 Slack 和 Discord 上，未设置时，如果确认表情反应处于活动状态，则保持 Status 表情反应启用。
|
||||
在 Telegram 上，需要显式设置为 `true` 才能启用生命周期 Status 表情反应。
|
||||
|
||||
### 入站防抖
|
||||
|
||||
将同一发送者快速发来的纯文本消息批处理为一次智能体轮次。媒体/附件会立即刷新。控制命令会绕过防抖。
|
||||
将同一发送者快速发送的纯文本消息合并为单个智能体轮次。媒体/附件会立即刷新。控制命令会绕过防抖。
|
||||
|
||||
### TTS（文本转语音）
|
||||
|
||||
@ -1308,13 +1317,13 @@ scripts/sandbox-browser-setup.sh # optional browser image
|
||||
}
|
||||
```
|
||||
|
||||
- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可以覆盖本地偏好，`/tts status` 会显示有效状态。
|
||||
- `auto` 控制默认自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可以覆盖本地偏好设置，`/tts status` 会显示生效状态。
|
||||
- `summaryModel` 会覆盖 `agents.defaults.model.primary`，用于自动摘要。
|
||||
- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（选择加入）。
|
||||
- API 密钥会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。
|
||||
- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（选择启用）。
|
||||
- API key 会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。
|
||||
- 内置语音提供商由插件拥有。如果设置了 `plugins.allow`，请包含你想使用的每个 TTS 提供商插件，例如用于 Edge TTS 的 `microsoft`。旧版 `edge` 提供商 ID 可作为 `microsoft` 的别名使用。
|
||||
- `providers.openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为：配置，然后是 `OPENAI_TTS_BASE_URL`，然后是 `https://api.openai.com/v1`。
|
||||
- 当 `providers.openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为 OpenAI 兼容的 TTS 服务器，并放宽模型/语音验证。
|
||||
- `providers.openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置，然后是 `OPENAI_TTS_BASE_URL`，然后是 `https://api.openai.com/v1`。
|
||||
- 当 `providers.openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽模型/语音校验。
|
||||
|
||||
---
|
||||
|
||||
@ -1349,16 +1358,16 @@ Talk 模式（macOS/iOS/Android）的默认值。
|
||||
}
|
||||
```
|
||||
|
||||
- 配置多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的某个键。
|
||||
- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，并会自动迁移到 `talk.providers.<provider>`。
|
||||
- 配置多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的一个键。
|
||||
- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容性，并会自动迁移到 `talk.providers.<provider>`。
|
||||
- 语音 ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。
|
||||
- `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。
|
||||
- 只有未配置 Talk API 密钥时，才会应用 `ELEVENLABS_API_KEY` 回退值。
|
||||
- `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。
|
||||
- 仅当没有配置 Talk API key 时，才会应用 `ELEVENLABS_API_KEY` 回退。
|
||||
- `providers.*.voiceAliases` 允许 Talk 指令使用易读名称。
|
||||
- `providers.mlx.modelId` 选择 macOS 本地 MLX 辅助程序使用的 Hugging Face 仓库。如果省略，macOS 会使用 `mlx-community/Soprano-80M-bf16`。
|
||||
- macOS MLX 播放会在存在时通过内置 `openclaw-mlx-tts` 辅助程序运行，或通过 `PATH` 上的可执行文件运行；`OPENCLAW_MLX_TTS_BIN` 会覆盖用于开发的辅助程序路径。
|
||||
- `speechLocale` 设置 iOS/macOS Talk 语音识别使用的 BCP 47 区域设置 ID。保持未设置则使用设备默认值。
|
||||
- `silenceTimeoutMs` 控制 Talk 模式在用户静默后等待多久再发送转录文本。未设置时保持平台默认暂停窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`）。
|
||||
- macOS MLX 播放会在存在时通过内置的 `openclaw-mlx-tts` 辅助程序运行，或通过 `PATH` 上的可执行文件运行；`OPENCLAW_MLX_TTS_BIN` 会覆盖用于开发的辅助程序路径。
|
||||
- `speechLocale` 设置 iOS/macOS Talk 语音识别使用的 BCP 47 区域设置 ID。留空则使用设备默认值。
|
||||
- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多长时间再发送转录。未设置时会保留平台默认暂停窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`）。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -1,20 +1,20 @@
|
||||
---
|
||||
read_when:
|
||||
- 了解如何配置 OpenClaw
|
||||
- 学习如何配置 OpenClaw
|
||||
- 正在查找配置示例
|
||||
- 首次设置 OpenClaw
|
||||
summary: 常见 OpenClaw 设置的符合模式的配置示例
|
||||
summary: 适用于常见 OpenClaw 设置的、符合模式定义的配置示例
|
||||
title: 配置示例
|
||||
x-i18n:
|
||||
generated_at: "2026-04-29T10:51:08Z"
|
||||
generated_at: "2026-04-29T21:53:04Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 82e0a721fdddd5f115df78211fea5405569ce3e8fb01ccab8daa0d545d39503d
|
||||
source_hash: 8bc1f8877bc635d6e3aafd911852d61e71fa08de9144751209542fd67c70f0ba
|
||||
source_path: gateway/configuration-examples.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
下面的示例与当前配置架构保持一致。完整参考和逐字段说明，请参阅[配置](/zh-CN/gateway/configuration)。
|
||||
以下示例与当前配置 schema 保持一致。完整参考和每个字段的说明，请参阅[配置](/zh-CN/gateway/configuration)。
|
||||
|
||||
## 快速开始
|
||||
|
||||
@ -27,9 +27,9 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
保存到 `~/.openclaw/openclaw.json`，然后你就可以从该号码向机器人发送私信。
|
||||
保存到 `~/.openclaw/openclaw.json` 后，你就可以从该号码向 bot 发送私信。
|
||||
|
||||
### 推荐入门配置
|
||||
### 推荐起步配置
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -59,7 +59,7 @@ x-i18n:
|
||||
|
||||
## 扩展示例（主要选项）
|
||||
|
||||
> JSON5 允许你使用注释和尾随逗号。常规 JSON 也可以使用。
|
||||
> JSON5 允许使用注释和尾随逗号。普通 JSON 也可以使用。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -118,18 +118,18 @@ x-i18n:
|
||||
visibleReplies: "message_tool", // normal final replies stay private in groups/channels
|
||||
},
|
||||
queue: {
|
||||
mode: "collect",
|
||||
debounceMs: 1000,
|
||||
mode: "steer",
|
||||
debounceMs: 500,
|
||||
cap: 20,
|
||||
drop: "summarize",
|
||||
byChannel: {
|
||||
whatsapp: "collect",
|
||||
telegram: "collect",
|
||||
discord: "collect",
|
||||
slack: "collect",
|
||||
signal: "collect",
|
||||
imessage: "collect",
|
||||
webchat: "collect",
|
||||
whatsapp: "steer",
|
||||
telegram: "steer",
|
||||
discord: "steer",
|
||||
slack: "steer",
|
||||
signal: "steer",
|
||||
imessage: "steer",
|
||||
webchat: "steer",
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -491,7 +491,7 @@ x-i18n:
|
||||
|
||||
- `agents.defaults.skills` 是共享基线。
|
||||
- `agents.list[].skills` 会为单个智能体替换该基线。
|
||||
- 当某个智能体不应看到任何 Skills 时，使用 `skills: []`。
|
||||
- 当智能体不应看到任何 Skills 时，使用 `skills: []`。
|
||||
|
||||
### 多平台设置
|
||||
|
||||
@ -516,7 +516,7 @@ x-i18n:
|
||||
|
||||
### 可信节点网络自动批准
|
||||
|
||||
除非你控制网络路径，否则请保持设备配对为手动。对于专用实验室或 tailnet 子网，你可以选择使用精确 CIDR 或 IP 来启用首次节点设备自动批准：
|
||||
除非你控制网络路径，否则请保持设备配对为手动。对于专用实验室或 tailnet 子网，你可以选择使用精确的 CIDR 或 IP，为首次节点设备启用自动批准：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -530,11 +530,11 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
未设置时，此功能保持关闭。它只适用于没有请求作用域的全新 `role: node` 配对。操作员/浏览器客户端，以及角色、作用域、元数据或公钥升级仍然需要手动批准。
|
||||
未设置时，此功能保持关闭。它仅适用于没有请求作用域的新 `role: node` 配对。操作员/浏览器客户端，以及 role、scope、metadata 或 public-key 升级仍需要手动批准。
|
||||
|
||||
### 安全私信模式（共享收件箱 / 多用户私信）
|
||||
|
||||
如果不止一个人可以向你的 bot 发送私信（`allowFrom` 中有多个条目、批准了多人的配对，或使用 `dmPolicy: "open"`），请启用**安全私信模式**，这样来自不同发送者的私信默认不会共享同一个上下文：
|
||||
如果不止一个人可以向你的机器人发送私信（`allowFrom` 中有多个条目、多个用户的配对批准，或 `dmPolicy: "open"`），请启用**安全私信模式**，这样来自不同发送者的私信默认不会共享同一个上下文：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -559,9 +559,9 @@ x-i18n:
|
||||
```
|
||||
|
||||
对于 Discord/Slack/Google Chat/Microsoft Teams/Mattermost/IRC，发送者授权默认优先使用 ID。
|
||||
只有在你明确接受风险时，才为每个渠道启用直接可变的名称/邮箱/nick 匹配：`dangerouslyAllowNameMatching: true`。
|
||||
只有在你明确接受该风险时，才为各渠道启用 `dangerouslyAllowNameMatching: true`，以允许直接使用可变的名称/电子邮件/昵称进行匹配。
|
||||
|
||||
### Anthropic API 密钥 + MiniMax 回退
|
||||
### Anthropic API key + MiniMax 回退
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -595,7 +595,7 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
### 工作 bot（受限访问）
|
||||
### 工作机器人（受限访问）
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -620,7 +620,7 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
### 仅使用本地模型
|
||||
### 仅本地模型
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -654,9 +654,9 @@ x-i18n:
|
||||
|
||||
## 提示
|
||||
|
||||
- 如果你设置了 `dmPolicy: "open"`，匹配的 `allowFrom` 列表必须包含 `"*"`。
|
||||
- 如果你设置了 `dmPolicy: "open"`，对应的 `allowFrom` 列表必须包含 `"*"`。
|
||||
- 提供商 ID 各不相同（电话号码、用户 ID、渠道 ID）。请使用提供商文档确认格式。
|
||||
- 可稍后添加的可选部分：`web`、`browser`、`ui`、`discovery`、`canvasHost`、`talk`、`signal`、`imessage`。
|
||||
- 稍后可添加的可选部分：`web`、`browser`、`ui`、`discovery`、`canvasHost`、`talk`、`signal`、`imessage`。
|
||||
- 请参阅[提供商](/zh-CN/providers)和[故障排除](/zh-CN/gateway/troubleshooting)，了解更深入的设置说明。
|
||||
|
||||
## 相关内容
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -3,20 +3,20 @@ read_when:
|
||||
- 使用或配置聊天命令
|
||||
- 调试命令路由或权限
|
||||
sidebarTitle: Slash commands
|
||||
summary: 斜杠命令：文本与原生、配置和支持的命令
|
||||
summary: 斜杠命令：文本式与原生式、配置和支持的命令
|
||||
title: 斜杠命令
|
||||
x-i18n:
|
||||
generated_at: "2026-04-29T17:09:38Z"
|
||||
generated_at: "2026-04-29T21:52:56Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: bdc4c9e4e2d541c5be089113f144907c150b85cce1922b8a6975fd11a57927aa
|
||||
source_hash: 58b9a4bf0106df4d8397737976ddd4df665d80709892b686d71978d8a3bafae0
|
||||
source_path: tools/slash-commands.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。仅主机 bash 聊天命令使用 `! <cmd>`（`/bash <cmd>` 是别名）。
|
||||
|
||||
当对话或线程绑定到 ACP 会话时，普通后续文本会路由到该 ACP harness。Gateway 网关管理命令仍然保持本地处理：`/acp ...` 始终会到达 OpenClaw ACP 命令处理器，并且只要该表面的命令处理已启用，`/status` 加 `/unfocus` 就会保持本地处理。
|
||||
当某个对话或线程绑定到 ACP 会话时，普通后续文本会路由到该 ACP harness。Gateway 网关管理命令仍然保持本地处理：`/acp ...` 始终到达 OpenClaw ACP 命令处理器，并且只要该界面启用了命令处理，`/status` 加 `/unfocus` 就保持本地处理。
|
||||
|
||||
有两个相关系统：
|
||||
|
||||
@ -27,16 +27,16 @@ x-i18n:
|
||||
<Accordion title="指令">
|
||||
`/think`、`/fast`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/exec`、`/model`、`/queue`。
|
||||
|
||||
- 指令会在模型看到消息前从消息中移除。
|
||||
- 在普通聊天消息中（不是仅包含指令的消息），它们会被视为“内联提示”，并且**不会**持久化会话设置。
|
||||
- 在仅包含指令的消息中（消息只包含指令），它们会持久化到会话并回复确认。
|
||||
- 指令只会应用于**已授权发送者**。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则授权来自渠道允许列表/配对，以及 `commands.useAccessGroups`。未授权发送者的指令会被视为纯文本。
|
||||
- 指令会在模型看到消息之前从消息中移除。
|
||||
- 在普通聊天消息中（不是仅指令消息），它们会被视为“内联提示”，并且**不会**持久化会话设置。
|
||||
- 在仅指令消息中（消息只包含指令），它们会持久化到会话，并回复确认。
|
||||
- 指令只会应用于**已授权发送者**。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则授权来自渠道允许列表/配对以及 `commands.useAccessGroups`。未授权发送者的指令会被当作普通文本处理。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="内联快捷方式">
|
||||
仅限允许列表/已授权发送者：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
|
||||
仅限允许列表中/已授权的发送者：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
|
||||
|
||||
它们会立即运行，在模型看到消息前被移除，剩余文本会继续走正常流程。
|
||||
它们会立即运行，在模型看到消息之前被移除，剩余文本会继续走正常流程。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -69,19 +69,19 @@ x-i18n:
|
||||
```
|
||||
|
||||
<ParamField path="commands.text" type="boolean" default="true">
|
||||
启用在聊天消息中解析 `/...`。在没有原生命令的表面（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams）上，即使你将其设置为 `false`，文本命令仍然可用。
|
||||
启用在聊天消息中解析 `/...`。在没有原生命令的界面上（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams），即使你将此项设置为 `false`，文本命令仍然可用。
|
||||
</ParamField>
|
||||
<ParamField path="commands.native" type='boolean | "auto"' default='"auto"'>
|
||||
注册原生命令。自动：对 Discord/Telegram 开启；对 Slack 关闭（直到你添加斜杠命令）；对不支持原生命令的提供商忽略。设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。`false` 会在启动时清除 Discord/Telegram 上先前注册的命令。Slack 命令在 Slack 应用中管理，不会自动移除。
|
||||
注册原生命令。Auto：对 Discord/Telegram 启用；对 Slack 关闭（直到你添加斜杠命令）；对于不支持原生命令的提供商会被忽略。设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 以按提供商覆盖（布尔值或 `"auto"`）。`false` 会在启动时清除 Discord/Telegram 上之前注册的命令。Slack 命令在 Slack 应用中管理，不会自动移除。
|
||||
</ParamField>
|
||||
<ParamField path="commands.nativeSkills" type='boolean | "auto"' default='"auto"'>
|
||||
在支持时原生注册 **Skill** 命令。自动：对 Discord/Telegram 开启；对 Slack 关闭（Slack 要求为每个 Skill 创建一个斜杠命令）。设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。
|
||||
在支持时原生注册 **skill** 命令。Auto：对 Discord/Telegram 启用；对 Slack 关闭（Slack 需要为每个 skill 创建一个斜杠命令）。设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 以按提供商覆盖（布尔值或 `"auto"`）。
|
||||
</ParamField>
|
||||
<ParamField path="commands.bash" type="boolean" default="false">
|
||||
启用 `! <cmd>` 来运行主机 shell 命令（`/bash <cmd>` 是别名；需要 `tools.elevated` 允许列表）。
|
||||
</ParamField>
|
||||
<ParamField path="commands.bashForegroundMs" type="number" default="2000">
|
||||
控制 bash 在切换到后台模式前等待多久（`0` 表示立即后台运行）。
|
||||
控制 bash 在切换到后台模式之前等待多久（`0` 表示立即转入后台）。
|
||||
</ParamField>
|
||||
<ParamField path="commands.config" type="boolean" default="false">
|
||||
启用 `/config`（读取/写入 `openclaw.json`）。
|
||||
@ -90,28 +90,28 @@ x-i18n:
|
||||
启用 `/mcp`（读取/写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 配置）。
|
||||
</ParamField>
|
||||
<ParamField path="commands.plugins" type="boolean" default="false">
|
||||
启用 `/plugins`（插件发现/Status，以及安装和启用/停用控制）。
|
||||
启用 `/plugins`（插件发现/Status，以及安装 + 启用/禁用控件）。
|
||||
</ParamField>
|
||||
<ParamField path="commands.debug" type="boolean" default="false">
|
||||
启用 `/debug`（仅运行时覆盖）。
|
||||
</ParamField>
|
||||
<ParamField path="commands.restart" type="boolean" default="true">
|
||||
启用 `/restart` 以及 Gateway 网关重启工具操作。
|
||||
启用 `/restart` 以及 gateway 重启工具操作。
|
||||
</ParamField>
|
||||
<ParamField path="commands.ownerAllowFrom" type="string[]">
|
||||
为仅限所有者的命令/工具表面设置显式所有者允许列表。这是可以批准危险操作并运行 `/diagnostics`、`/export-trajectory` 和 `/config` 等命令的人类操作员账号。它独立于 `commands.allowFrom`，也独立于私信配对访问。
|
||||
设置仅 owner 命令/工具界面的显式 owner 允许列表。这是可以批准危险操作并运行 `/diagnostics`、`/export-trajectory` 和 `/config` 等命令的人类操作员账户。它独立于 `commands.allowFrom` 和私信配对访问权限。
|
||||
</ParamField>
|
||||
<ParamField path="channels.<channel>.commands.enforceOwnerForCommands" type="boolean" default="false">
|
||||
按渠道：让仅限所有者的命令在该表面上运行时需要**所有者身份**。当为 `true` 时，发送者必须匹配已解析的所有者候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生所有者元数据），或者在内部消息渠道上持有内部 `operator.admin` 作用域。渠道 `allowFrom` 中的通配符条目，或空的/未解析的所有者候选列表，**不足以**满足要求 —— 仅限所有者的命令会在该渠道上以封闭方式失败。如果你希望仅限所有者的命令只由 `ownerAllowFrom` 和标准命令允许列表约束，请保持此项关闭。
|
||||
按渠道：让仅 owner 命令要求在该界面上以 **owner 身份**运行。当为 `true` 时，发送者必须匹配已解析的 owner 候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生 owner 元数据），或在内部消息渠道上持有内部 `operator.admin` 作用域。渠道 `allowFrom` 中的通配符条目，或为空/未解析的 owner 候选列表，**不足以**满足要求，仅 owner 命令会在该渠道上默认失败关闭。如果你希望仅 owner 命令只由 `ownerAllowFrom` 和标准命令允许列表进行门控，请保持关闭。
|
||||
</ParamField>
|
||||
<ParamField path="commands.ownerDisplay" type='"raw" | "hash"'>
|
||||
控制所有者 id 在系统提示中的显示方式。
|
||||
控制 owner id 在系统提示中的显示方式。
|
||||
</ParamField>
|
||||
<ParamField path="commands.ownerDisplaySecret" type="string">
|
||||
可选地设置当 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。
|
||||
可选设置在 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。
|
||||
</ParamField>
|
||||
<ParamField path="commands.allowFrom" type="object">
|
||||
用于命令授权的按提供商允许列表。配置后，它是命令和指令的唯一授权来源（渠道允许列表/配对和 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；提供商特定键会覆盖它。
|
||||
按提供商设置的命令授权允许列表。配置后，它就是命令和指令的唯一授权来源（渠道允许列表/配对以及 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；提供商专用键会覆盖它。
|
||||
</ParamField>
|
||||
<ParamField path="commands.useAccessGroups" type="boolean" default="true">
|
||||
当未设置 `commands.allowFrom` 时，对命令强制执行允许列表/策略。
|
||||
@ -121,80 +121,80 @@ x-i18n:
|
||||
|
||||
当前事实来源：
|
||||
|
||||
- 核心内置命令来自 `src/auto-reply/commands-registry.shared.ts`
|
||||
- core 内置项来自 `src/auto-reply/commands-registry.shared.ts`
|
||||
- 生成的 dock 命令来自 `src/auto-reply/commands-registry.data.ts`
|
||||
- 插件命令来自插件 `registerCommand()` 调用
|
||||
- 在你的 Gateway 网关上的实际可用性仍取决于配置标志、渠道表面，以及已安装/已启用的插件
|
||||
- 你的 gateway 上的实际可用性仍取决于配置标志、渠道界面以及已安装/启用的插件
|
||||
|
||||
### 核心内置命令
|
||||
### Core 内置命令
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="会话和运行">
|
||||
- `/new [model]` 启动新会话；`/reset` 是重置别名。
|
||||
- `/reset soft [message]` 保留当前转录内容，丢弃复用的 CLI 后端会话 id，并在原位重新运行启动/系统提示加载。
|
||||
- `/reset soft [message]` 保留当前转录，丢弃复用的 CLI 后端会话 id，并就地重新运行启动/系统提示加载。
|
||||
- `/compact [instructions]` 压缩会话上下文。参见[压缩](/zh-CN/concepts/compaction)。
|
||||
- `/stop` 中止当前运行。
|
||||
- `/session idle <duration|off>` 和 `/session max-age <duration|off>` 管理线程绑定过期时间。
|
||||
- `/export-session [path]` 将当前会话导出为 HTML。别名：`/export`。
|
||||
- `/export-trajectory [path]` 请求 exec 批准，然后为当前会话导出 JSONL [轨迹包](/zh-CN/tools/trajectory)。当你需要某个 OpenClaw 会话的提示、工具和转录时间线时使用它。在群聊中，批准提示和导出结果会私下发送给所有者。别名：`/trajectory`。
|
||||
- `/export-trajectory [path]` 请求 exec 批准，然后为当前会话导出 JSONL [轨迹包](/zh-CN/tools/trajectory)。当你需要一个 OpenClaw 会话的提示、工具和转录时间线时使用它。在群聊中，批准提示和导出结果会私下发送给 owner。别名：`/trajectory`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="模型和运行控制">
|
||||
- `/think <level>` 设置思考级别。选项来自活动模型的提供商配置文件；常见级别包括 `off`、`minimal`、`low`、`medium` 和 `high`，自定义级别如 `xhigh`、`adaptive`、`max`，或二进制 `on` 仅在受支持时可用。别名：`/thinking`、`/t`。
|
||||
<Accordion title="模型和运行控件">
|
||||
- `/think <level>` 设置思考级别。选项来自活动模型的 provider profile；常见级别包括 `off`、`minimal`、`low`、`medium` 和 `high`，自定义级别如 `xhigh`、`adaptive`、`max` 或二进制 `on` 仅在支持的地方可用。别名：`/thinking`、`/t`。
|
||||
- `/verbose on|off|full` 切换详细输出。别名：`/v`。
|
||||
- `/trace on|off` 切换当前会话的插件跟踪输出。
|
||||
- `/trace on|off` 切换当前会话的插件追踪输出。
|
||||
- `/fast [status|on|off]` 显示或设置快速模式。
|
||||
- `/reasoning [on|off|stream]` 切换推理可见性。别名：`/reason`。
|
||||
- `/elevated [on|off|ask|full]` 切换提升模式。别名：`/elev`。
|
||||
- `/elevated [on|off|ask|full]` 切换 elevated 模式。别名：`/elev`。
|
||||
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` 显示或设置 exec 默认值。
|
||||
- `/model [name|#|status]` 显示或设置模型。
|
||||
- `/models [provider] [page] [limit=<n>|size=<n>|all]` 列出已配置/可凭证访问的提供商，或列出某个提供商的模型；添加 `all` 可浏览该提供商的完整目录。
|
||||
- `/queue <mode>` 管理队列行为（`steer`、`interrupt`、`followup`、`collect`、`steer-backlog`），以及 `debounce:2s cap:25 drop:summarize` 等选项。
|
||||
- `/models [provider] [page] [limit=<n>|size=<n>|all]` 列出已配置/可用认证的提供商，或某个提供商的模型；添加 `all` 可浏览该提供商的完整目录。
|
||||
- `/queue <mode>` 管理队列行为（`steer`、`followup`、`collect`、`steer-backlog`、`interrupt`）以及 `debounce:0.5s cap:25 drop:summarize` 等选项；`/queue default` 或 `/queue reset` 会清除会话覆盖。参见[命令队列](/zh-CN/concepts/queue)。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="设备发现和 Status">
|
||||
- `/help` 显示简短帮助摘要。
|
||||
- `/commands` 显示生成的命令目录。
|
||||
- `/tools [compact|verbose]` 显示当前智能体现在可以使用什么。
|
||||
- `/status` 显示执行/运行时 Status，包括 `Execution`/`Runtime` 标签，以及可用时的提供商用量/配额。
|
||||
- `/diagnostics [note]` 是针对 Gateway 网关 bug 和 Codex harness 运行的仅限所有者支持报告流程。它每次运行 `openclaw gateway diagnostics export --json` 前都会请求显式 exec 批准；不要用 allow-all 规则批准诊断。批准后，它会发送一份可粘贴报告，其中包含本地 bundle 路径、清单摘要、隐私说明和相关会话 id。在群聊中，批准提示和报告会私下发送给所有者。当活动会话使用 OpenAI Codex harness 时，同一批准还会将相关 Codex 反馈发送到 OpenAI 服务器，完成后的回复会列出 OpenClaw 会话 id、Codex 线程 id 和 `codex resume <thread-id>` 命令。参见[诊断导出](/zh-CN/gateway/diagnostics)。
|
||||
- `/crestodian <request>` 从所有者私信运行 Crestodian 设置和修复助手。
|
||||
- `/tools [compact|verbose]` 显示当前 agent 现在可以使用的内容。
|
||||
- `/status` 显示执行/运行时 Status，包括可用时的 `Execution`/`Runtime` 标签和提供商使用量/配额。
|
||||
- `/diagnostics [note]` 是用于 Gateway 网关 bug 和 Codex harness 运行的仅 owner 支持报告流程。它每次都会在运行 `openclaw gateway diagnostics export --json` 之前请求显式 exec 批准；不要使用允许所有规则批准 diagnostics。批准后，它会发送一份可粘贴的报告，其中包含本地包路径、清单摘要、隐私说明和相关会话 id。在群聊中，批准提示和报告会私下发送给 owner。当活动会话使用 OpenAI Codex harness 时，同一次批准还会将相关 Codex 反馈发送到 OpenAI 服务器，完成后的回复会列出 OpenClaw 会话 id、Codex 线程 id 和 `codex resume <thread-id>` 命令。参见 [Diagnostics Export](/zh-CN/gateway/diagnostics)。
|
||||
- `/crestodian <request>` 从 owner 私信运行 Crestodian 设置和修复助手。
|
||||
- `/tasks` 列出当前会话的活动/近期后台任务。
|
||||
- `/context [list|detail|json]` 解释上下文如何组装。
|
||||
- `/context [list|detail|json]` 说明上下文如何组装。
|
||||
- `/whoami` 显示你的发送者 id。别名：`/id`。
|
||||
- `/usage off|tokens|full|cost` 控制每条回复的用量页脚，或打印本地成本摘要。
|
||||
- `/usage off|tokens|full|cost` 控制每条回复的使用量页脚，或打印本地成本摘要。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Skills、允许列表、批准">
|
||||
- `/skill <name> [input]` 按名称运行一个 Skill。
|
||||
- `/skill <name> [input]` 按名称运行 skill。
|
||||
- `/allowlist [list|add|remove] ...` 管理允许列表条目。仅文本。
|
||||
- `/approve <id> <decision>` 解决 exec 批准提示。
|
||||
- `/btw <question>` 提出一个旁路问题，而不改变未来会话上下文。参见 [BTW](/zh-CN/tools/btw)。
|
||||
- `/btw <question>` 提出旁支问题，而不改变未来会话上下文。参见 [BTW](/zh-CN/tools/btw)。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="子智能体和 ACP">
|
||||
- `/subagents list|kill|log|info|send|steer|spawn` 管理当前会话的子智能体运行。
|
||||
<Accordion title="子 agent 和 ACP">
|
||||
- `/subagents list|kill|log|info|send|steer|spawn` 管理当前会话的子 agent 运行。
|
||||
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` 管理 ACP 会话和运行时选项。
|
||||
- `/focus <target>` 将当前 Discord 线程或 Telegram 话题/对话绑定到会话目标。
|
||||
- `/focus <target>` 将当前 Discord 线程或 Telegram 主题/对话绑定到会话目标。
|
||||
- `/unfocus` 移除当前绑定。
|
||||
- `/agents` 列出当前会话的线程绑定智能体。
|
||||
- `/kill <id|#|all>` 中止一个或所有正在运行的子智能体。
|
||||
- `/steer <id|#> <message>` 向正在运行的子智能体发送引导。别名：`/tell`。
|
||||
- `/agents` 列出当前会话的线程绑定 agent。
|
||||
- `/kill <id|#|all>` 中止一个或所有正在运行的子 agent。
|
||||
- `/steer <id|#> <message>` 向正在运行的子 agent 发送引导。别名：`/tell`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="仅所有者写入和管理">
|
||||
<Accordion title="Owner-only writes and admin">
|
||||
- `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅限所有者。需要 `commands.config: true`。
|
||||
- `/mcp show|get|set|unset` 读取或写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。仅限所有者。需要 `commands.mcp: true`。
|
||||
- `/plugins list|inspect|show|get|install|enable|disable` 检查或变更插件状态。`/plugin` 是别名。写入仅限所有者。需要 `commands.plugins: true`。
|
||||
- `/debug show|set|unset|reset` 管理仅运行时的配置覆盖。仅限所有者。需要 `commands.debug: true`。
|
||||
- `/restart` 在启用时重启 OpenClaw。默认：已启用；设置 `commands.restart: false` 可禁用。
|
||||
- `/plugins list|inspect|show|get|install|enable|disable` 检查或变更插件状态。`/plugin` 是别名。写入操作仅限所有者。需要 `commands.plugins: true`。
|
||||
- `/debug show|set|unset|reset` 管理仅运行时配置覆盖。仅限所有者。需要 `commands.debug: true`。
|
||||
- `/restart` 在启用时重启 OpenClaw。默认：启用；设置 `commands.restart: false` 可将其禁用。
|
||||
- `/send on|off|inherit` 设置发送策略。仅限所有者。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="语音、TTS、渠道控制">
|
||||
<Accordion title="Voice, TTS, channel control">
|
||||
- `/tts on|off|status|chat|latest|provider|limit|summary|audio|help` 控制 TTS。参见 [TTS](/zh-CN/tools/tts)。
|
||||
- `/activation mention|always` 设置群组激活模式。
|
||||
- `/bash <command>` 运行宿主 shell 命令。仅文本。别名：`! <command>`。需要 `commands.bash: true` 以及 `tools.elevated` 允许列表。
|
||||
- `/bash <command>` 运行主机 shell 命令。仅文本。别名：`! <command>`。需要 `commands.bash: true` 加上 `tools.elevated` 允许列表。
|
||||
- `!poll [sessionId]` 检查后台 bash 作业。
|
||||
- `!stop [sessionId]` 停止后台 bash 作业。
|
||||
|
||||
@ -203,7 +203,8 @@ x-i18n:
|
||||
|
||||
### 生成的停靠命令
|
||||
|
||||
停靠命令会将当前会话的回复路由切换到另一个已关联的渠道。有关设置、示例和故障排除，请参见 [渠道停靠](/zh-CN/concepts/channel-docking)。
|
||||
停靠命令会将当前会话的回复路由切换到另一个已关联的
|
||||
渠道。有关设置、示例和故障排除，请参见[渠道停靠](/zh-CN/concepts/channel-docking)。
|
||||
|
||||
停靠命令由支持原生命令的渠道插件生成。当前内置集合：
|
||||
|
||||
@ -212,112 +213,112 @@ x-i18n:
|
||||
- `/dock-slack`（别名：`/dock_slack`）
|
||||
- `/dock-telegram`（别名：`/dock_telegram`）
|
||||
|
||||
在直接聊天中使用停靠命令，可将当前会话的回复路由切换到另一个已关联的渠道。智能体会保留相同的会话上下文，但该会话之后的回复会发送给所选渠道对端。
|
||||
在直接聊天中使用停靠命令，将当前会话的回复路由切换到另一个已关联的渠道。智能体会保留相同的会话上下文，但该会话之后的回复会发送到所选的渠道对端。
|
||||
|
||||
停靠命令需要 `session.identityLinks`。源发送者和目标对端必须位于同一个身份组，例如 `["telegram:123", "discord:456"]`。如果 id 为 `123` 的 Telegram 用户发送 `/dock_discord`，OpenClaw 会在活动会话上存储 `lastChannel: "discord"` 和 `lastTo: "456"`。如果发送者未关联到 Discord 对端，该命令会返回设置提示，而不是落入普通聊天。
|
||||
停靠命令需要 `session.identityLinks`。来源发送者和目标对端必须在同一个身份组中，例如 `["telegram:123", "discord:456"]`。如果 id 为 `123` 的 Telegram 用户发送 `/dock_discord`，OpenClaw 会在活动会话上存储 `lastChannel: "discord"` 和 `lastTo: "456"`。如果发送者未关联到 Discord 对端，命令会回复设置提示，而不是落入普通聊天流程。
|
||||
|
||||
停靠只会更改活动会话路由。它不会创建渠道账号、授予访问权限、绕过渠道允许列表，也不会将转录历史移动到另一个会话。使用 `/dock-telegram`、`/dock-slack`、`/dock-mattermost` 或其他生成的停靠命令来再次切换路由。
|
||||
停靠只会更改活动会话路由。它不会创建渠道账号、授予访问权限、绕过渠道允许列表，或将转录历史移动到另一个会话。使用 `/dock-telegram`、`/dock-slack`、`/dock-mattermost` 或另一个生成的停靠命令，可再次切换路由。
|
||||
|
||||
### 内置插件命令
|
||||
|
||||
内置插件可以添加更多斜杠命令。此仓库中当前的内置命令：
|
||||
内置插件可以添加更多斜杠命令。此仓库中的当前内置命令：
|
||||
|
||||
- `/dreaming [on|off|status|help]` 切换记忆 Dreaming。参见 [Dreaming](/zh-CN/concepts/dreaming)。
|
||||
- `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对/设置流程。参见 [配对](/zh-CN/channels/pairing)。
|
||||
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` 临时启用高风险手机节点命令。
|
||||
- `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对/设置流程。参见[配对](/zh-CN/channels/pairing)。
|
||||
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` 临时授权高风险手机节点命令。
|
||||
- `/voice status|list [limit]|set <voiceId|name>` 管理 Talk 语音配置。在 Discord 上，原生命令名称是 `/talkvoice`。
|
||||
- `/card ...` 发送 LINE 富卡片预设。参见 [LINE](/zh-CN/channels/line)。
|
||||
- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` 检查和控制内置 Codex app-server harness。参见 [Codex harness](/zh-CN/plugins/codex-harness)。
|
||||
- 仅 QQBot 的命令：
|
||||
- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` 检查并控制内置 Codex 应用服务器 harness。参见 [Codex harness](/zh-CN/plugins/codex-harness)。
|
||||
- 仅 QQBot 命令：
|
||||
- `/bot-ping`
|
||||
- `/bot-version`
|
||||
- `/bot-help`
|
||||
- `/bot-upgrade`
|
||||
- `/bot-logs`
|
||||
|
||||
### 动态 Skill 命令
|
||||
### 动态 skill 命令
|
||||
|
||||
用户可调用的 Skills 也会暴露为斜杠命令：
|
||||
用户可调用的 skills 也会作为斜杠命令公开：
|
||||
|
||||
- `/skill <name> [input]` 始终作为通用入口点可用。
|
||||
- 当 Skill/插件注册时，Skills 也可能显示为类似 `/prose` 的直接命令。
|
||||
- 原生 Skill 命令注册由 `commands.nativeSkills` 和 `channels.<provider>.commands.nativeSkills` 控制。
|
||||
- 当 skill/plugin 注册它们时，skills 也可能显示为 `/prose` 这样的直接命令。
|
||||
- 原生 skill 命令注册由 `commands.nativeSkills` 和 `channels.<provider>.commands.nativeSkills` 控制。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="参数和解析器说明">
|
||||
- 命令在命令和参数之间接受可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。
|
||||
- `/new <model>` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配项，文本会被视为消息正文。
|
||||
- 如需完整的提供商使用情况细分，请使用 `openclaw status --usage`。
|
||||
<Accordion title="Argument and parser notes">
|
||||
- 命令接受命令与参数之间可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。
|
||||
- `/new <model>` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配，文本会被视为消息正文。
|
||||
- 如需完整的提供商用量明细，请使用 `openclaw status --usage`。
|
||||
- `/allowlist add|remove` 需要 `commands.config=true`，并遵循渠道 `configWrites`。
|
||||
- 在多账号渠道中，面向配置目标的 `/allowlist --account <id>` 和 `/config set channels.<provider>.accounts.<id>...` 也会遵循目标账号的 `configWrites`。
|
||||
- 在多账号渠道中，面向配置的 `/allowlist --account <id>` 和 `/config set channels.<provider>.accounts.<id>...` 也会遵循目标账号的 `configWrites`。
|
||||
- `/usage` 控制每条回复的用量页脚；`/usage cost` 会从 OpenClaw 会话日志打印本地费用摘要。
|
||||
- `/restart` 默认启用；设置 `commands.restart: false` 可禁用。
|
||||
- `/plugins install <spec>` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/归档、npm 包或 `clawhub:<pkg>`。
|
||||
- `/plugins enable|disable` 会更新插件配置，并可能提示重启。
|
||||
- `/restart` 默认启用；设置 `commands.restart: false` 可将其禁用。
|
||||
- `/plugins install <spec>` 接受与 `openclaw plugins install` 相同的插件 spec：本地路径/归档、npm 包，或 `clawhub:<pkg>`。
|
||||
- `/plugins enable|disable` 更新插件配置，并可能提示重启。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="渠道特定行为">
|
||||
- 仅 Discord 的原生命令：`/vc join|leave|status` 控制语音渠道（不能作为文本使用）。`join` 需要一个 guild 和已选择的语音/舞台渠道。需要 `channels.discord.voice` 和原生命令。
|
||||
- Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）需要启用有效线程绑定（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。
|
||||
<Accordion title="Channel-specific behavior">
|
||||
- 仅 Discord 原生命令：`/vc join|leave|status` 控制语音渠道（不能作为文本使用）。`join` 需要一个服务器以及所选的语音/stage 渠道。需要 `channels.discord.voice` 和原生命令。
|
||||
- Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）要求启用有效的线程绑定（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。
|
||||
- ACP 命令参考和运行时行为：[ACP 智能体](/zh-CN/tools/acp-agents)。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="详细 / trace / fast / reasoning 安全">
|
||||
- `/verbose` 用于调试和额外可见性；正常使用时保持**关闭**。
|
||||
- `/trace` 比 `/verbose` 更窄：它只显示插件拥有的 trace/debug 行，并保持普通详细工具噪声关闭。
|
||||
<Accordion title="Verbose / trace / fast / reasoning safety">
|
||||
- `/verbose` 用于调试和提供额外可见性；正常使用时保持**关闭**。
|
||||
- `/trace` 比 `/verbose` 范围更窄：它只显示插件拥有的 trace/debug 行，并关闭普通 verbose 工具杂音。
|
||||
- `/fast on|off` 会持久化会话覆盖。使用 Sessions UI 的 `inherit` 选项可清除它并回退到配置默认值。
|
||||
- `/fast` 与提供商相关：OpenAI/OpenAI Codex 在原生 Responses 端点上会将它映射到 `service_tier=priority`，而直接公共 Anthropic 请求，包括发送到 `api.anthropic.com` 的 OAuth 认证流量，会将它映射到 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。
|
||||
- 工具失败摘要在相关时仍会显示，但详细失败文本只会在 `/verbose` 为 `on` 或 `full` 时包含。
|
||||
- `/reasoning`、`/verbose` 和 `/trace` 在群组设置中有风险：它们可能泄露你本不打算暴露的内部 reasoning、工具输出或插件诊断。建议保持关闭，尤其是在群聊中。
|
||||
- `/fast` 是提供商特定的：OpenAI/OpenAI Codex 会在原生 Responses 端点上将其映射到 `service_tier=priority`，而直接的公共 Anthropic 请求，包括发送到 `api.anthropic.com` 的 OAuth 认证流量，会将其映射到 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。
|
||||
- 相关时仍会显示工具失败摘要，但只有在 `/verbose` 为 `on` 或 `full` 时才会包含详细失败文本。
|
||||
- `/reasoning`、`/verbose` 和 `/trace` 在群组环境中有风险：它们可能泄露你无意公开的内部推理、工具输出或插件诊断。建议保持关闭，尤其是在群聊中。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="模型切换">
|
||||
<Accordion title="Model switching">
|
||||
- `/model` 会立即持久化新的会话模型。
|
||||
- 如果智能体处于空闲状态，下一次运行会立即使用它。
|
||||
- 如果运行已处于活动状态，OpenClaw 会将实时切换标记为待处理，并且只在干净的重试点重启到新模型。
|
||||
- 如果工具活动或回复输出已经开始，待处理切换可能会保持排队，直到之后的重试机会或下一轮用户输入。
|
||||
- 在本地 TUI 中，`/crestodian [request]` 会从普通智能体 TUI 返回 Crestodian。这与消息渠道救援模式不同，也不会授予远程配置权限。
|
||||
- 如果智能体空闲，下一次运行会立即使用它。
|
||||
- 如果已有运行处于活动状态，OpenClaw 会将实时切换标记为待处理，并只会在干净的重试点重启进入新模型。
|
||||
- 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到之后的重试机会或下一次用户回合。
|
||||
- 在本地 TUI 中，`/crestodian [request]` 会从普通智能体 TUI 返回到 Crestodian。这不同于消息渠道救援模式，也不会授予远程配置权限。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="快速路径和内联快捷方式">
|
||||
- **快速路径：** 来自允许列表发送者的纯命令消息会被立即处理（绕过队列 + 模型）。
|
||||
- **群组提及门控：** 来自允许列表发送者的纯命令消息会绕过提及要求。
|
||||
- **内联快捷方式（仅限允许列表发送者）：** 某些命令嵌入普通消息时也能工作，并且会在模型看到剩余文本之前被剥离。
|
||||
- 示例：`hey /status` 会触发 Status 回复，剩余文本会继续走普通流程。
|
||||
<Accordion title="Fast path and inline shortcuts">
|
||||
- **快速路径：**来自允许列表发送者的纯命令消息会立即处理（绕过队列 + 模型）。
|
||||
- **群组提及门控：**来自允许列表发送者的纯命令消息会绕过提及要求。
|
||||
- **行内快捷方式（仅允许列表发送者）：**某些命令嵌入普通消息时也可使用，并会在模型看到剩余文本前被剥离。
|
||||
- 示例：`hey /status` 触发 Status 回复，剩余文本继续进入普通流程。
|
||||
- 当前：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
|
||||
- 未授权的纯命令消息会被静默忽略，内联 `/...` 标记会被视为纯文本。
|
||||
- 未授权的纯命令消息会被静默忽略，行内 `/...` token 会被视为纯文本。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Skill 命令和原生参数">
|
||||
- **Skill 命令：** `user-invocable` Skills 会暴露为斜杠命令。名称会被清洗为 `a-z0-9_`（最多 32 个字符）；冲突时会获得数字后缀（例如 `_2`）。
|
||||
- `/skill <name> [input]` 按名称运行 Skill（当原生命令限制阻止为每个 Skill 提供命令时很有用）。
|
||||
- 默认情况下，Skill 命令会作为普通请求转发给模型。
|
||||
- Skills 可以选择声明 `command-dispatch: tool`，将命令直接路由到工具（确定性，无模型）。
|
||||
<Accordion title="Skill commands and native arguments">
|
||||
- **Skill 命令：**`user-invocable` skills 会作为斜杠命令公开。名称会被清理为 `a-z0-9_`（最多 32 个字符）；冲突会获得数字后缀（例如 `_2`）。
|
||||
- `/skill <name> [input]` 按名称运行 skill（当原生命令限制阻止为每个 skill 创建命令时很有用）。
|
||||
- 默认情况下，skill 命令会作为普通请求转发给模型。
|
||||
- Skills 可以选择声明 `command-dispatch: tool`，将命令直接路由到工具（确定性、无模型）。
|
||||
- 示例：`/prose`（OpenProse 插件）— 参见 [OpenProse](/zh-CN/prose)。
|
||||
- **原生命令参数：** Discord 对动态选项使用自动补全（省略必需参数时使用按钮菜单）。当命令支持选项且你省略参数时，Telegram 和 Slack 会显示按钮菜单。动态选项会针对目标会话模型解析，因此模型特定选项（例如 `/think` 级别）会遵循该会话的 `/model` 覆盖。
|
||||
- **原生命令参数：**Discord 对动态选项使用自动补全（当你省略必需参数时使用按钮菜单）。Telegram 和 Slack 会在命令支持选项且你省略参数时显示按钮菜单。动态选项会根据目标会话模型解析，因此 `/think` 级别等模型特定选项会跟随该会话的 `/model` 覆盖。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## `/tools`
|
||||
|
||||
`/tools` 回答的是运行时问题，而不是配置问题：**这个智能体现在在这段对话中可以使用什么**。
|
||||
`/tools` 回答的是运行时问题，而不是配置问题：**这个智能体现在能在此对话中使用什么**。
|
||||
|
||||
- 默认 `/tools` 很紧凑，并针对快速浏览优化。
|
||||
- 默认 `/tools` 紧凑，并针对快速浏览优化。
|
||||
- `/tools verbose` 添加简短描述。
|
||||
- 支持参数的原生命令表面会暴露相同的模式开关：`compact|verbose`。
|
||||
- 结果限定于会话范围，因此更改智能体、渠道、线程、发送者授权或模型都可能改变输出。
|
||||
- `/tools` 包含运行时实际可达的工具，包括核心工具、已连接的插件工具和渠道拥有的工具。
|
||||
- 支持参数的原生命令表面会公开与 `compact|verbose` 相同的模式开关。
|
||||
- 结果限定在会话范围内，因此更改智能体、渠道、线程、发送者授权或模型都可能改变输出。
|
||||
- `/tools` 包含运行时实际可访问的工具，包括核心工具、已连接的插件工具，以及渠道拥有的工具。
|
||||
|
||||
对于配置文件和覆盖编辑，请使用 Control UI Tools 面板或配置/目录表面，而不是把 `/tools` 当作静态目录。
|
||||
对于配置文件和覆盖编辑，请使用 Control UI Tools 面板或配置/catalog 表面，而不要将 `/tools` 视为静态目录。
|
||||
|
||||
## 使用情况表面（哪里显示什么）
|
||||
## 用量表面（哪里显示什么）
|
||||
|
||||
- **提供商使用量/配额**（示例：“Claude 剩余 80%”）会在启用使用量跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口规范化为“剩余 %”；对于 MiniMax，仅剩余百分比字段会在显示前反转，并且 `model_remains` 响应优先使用聊天模型条目以及带模型标签的计划标签。
|
||||
- **Token/缓存行** 在 `/status` 中可以在实时会话快照稀疏时回退到最新转录用量条目。已有的非零实时值仍然优先，转录回退也可以恢复活动运行时模型标签，以及在存储总量缺失或更小时恢复更大的面向提示词的总量。
|
||||
- **执行与运行时：** `/status` 对有效沙箱路径报告 `Execution`，并对实际运行会话的对象报告 `Runtime`：`OpenClaw Pi Default`、`OpenAI Codex`、CLI 后端或 ACP 后端。
|
||||
- **每条回复 token/费用** 由 `/usage off|tokens|full` 控制（追加到普通回复）。
|
||||
- `/model status` 关注的是**模型/凭证/端点**，而不是使用量。
|
||||
- **提供商用量/配额**（示例：“Claude 剩余 80%”）在启用用量跟踪时，会显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口标准化为 `% left`；对于 MiniMax，仅剩余百分比字段会在显示前取反，`model_remains` 响应优先使用聊天模型条目加上带模型标签的计划标签。
|
||||
- **Token/cache 行**在 `/status` 中可在实时会话快照稀疏时回退到最新转录用量条目。已有的非零实时值仍优先，转录回退还可以在存储总数缺失或更小时恢复活动运行时模型标签和更大的面向提示的总数。
|
||||
- **执行与运行时：**`/status` 会为有效沙箱路径报告 `Execution`，并为实际运行会话的对象报告 `Runtime`：`OpenClaw Pi Default`、`OpenAI Codex`、CLI 后端或 ACP 后端。
|
||||
- **每条回复 token/费用**由 `/usage off|tokens|full` 控制（附加到普通回复）。
|
||||
- `/model status` 关注的是**模型/认证/端点**，不是用量。
|
||||
|
||||
## 模型选择（`/model`）
|
||||
|
||||
@ -337,13 +338,13 @@ x-i18n:
|
||||
说明：
|
||||
|
||||
- `/model` 和 `/model list` 显示紧凑的编号选择器（模型家族 + 可用提供商）。
|
||||
- 在 Discord 上，`/model` 和 `/models` 会打开带有提供商和模型下拉框以及 Submit 步骤的交互式选择器。
|
||||
- `/model <#>` 从该选择器中选择（并在可能时优先选择当前提供商）。
|
||||
- `/model status` 显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`，如果可用）。
|
||||
- 在 Discord 上，`/model` 和 `/models` 会打开交互式选择器，其中包含提供商和模型下拉框以及 Submit 步骤。
|
||||
- `/model <#>` 从该选择器中选择（并尽可能偏好当前提供商）。
|
||||
- `/model status` 显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`）（如果可用）。
|
||||
|
||||
## 调试覆盖
|
||||
## Debug 覆盖
|
||||
|
||||
`/debug` 允许你设置**仅运行时**的配置覆盖（内存中，不写入磁盘）。仅所有者可用。默认禁用；使用 `commands.debug: true` 启用。
|
||||
`/debug` 允许你设置**仅运行时**配置覆盖（内存中，不写入磁盘）。仅限所有者使用。默认禁用；用 `commands.debug: true` 启用。
|
||||
|
||||
示例：
|
||||
|
||||
@ -356,12 +357,12 @@ x-i18n:
|
||||
```
|
||||
|
||||
<Note>
|
||||
覆盖会立即应用到新的配置读取，但**不会**写入 `openclaw.json`。使用 `/debug reset` 清除所有覆盖并回到磁盘上的配置。
|
||||
覆盖会立即应用到新的配置读取，但**不会**写入 `openclaw.json`。使用 `/debug reset` 清除所有覆盖，并返回磁盘上的配置。
|
||||
</Note>
|
||||
|
||||
## 插件追踪输出
|
||||
## 插件跟踪输出
|
||||
|
||||
`/trace` 允许你切换**会话范围内的插件追踪/调试行**，而无需开启完整详细模式。
|
||||
`/trace` 允许你切换**会话范围的插件跟踪/调试行**，无需开启完整详细模式。
|
||||
|
||||
示例：
|
||||
|
||||
@ -373,16 +374,16 @@ x-i18n:
|
||||
|
||||
注意：
|
||||
|
||||
- 不带参数的 `/trace` 会显示当前会话的追踪状态。
|
||||
- `/trace on` 会为当前会话启用插件追踪行。
|
||||
- 不带参数的 `/trace` 会显示当前会话的跟踪状态。
|
||||
- `/trace on` 为当前会话启用插件跟踪行。
|
||||
- `/trace off` 会再次禁用它们。
|
||||
- 插件追踪行可以出现在 `/status` 中，也可以在正常助手回复之后作为后续诊断消息出现。
|
||||
- `/trace` 不会取代 `/debug`；`/debug` 仍然管理仅运行时的配置覆盖。
|
||||
- `/trace` 不会取代 `/verbose`；普通的详细工具/状态输出仍属于 `/verbose`。
|
||||
- 插件跟踪行可以出现在 `/status` 中，也可以在正常助手回复之后作为后续诊断消息出现。
|
||||
- `/trace` 不会取代 `/debug`；`/debug` 仍然管理仅运行时配置覆盖。
|
||||
- `/trace` 不会取代 `/verbose`；正常的详细工具/Status 输出仍属于 `/verbose`。
|
||||
|
||||
## 配置更新
|
||||
|
||||
`/config` 会写入你的磁盘配置（`openclaw.json`）。仅所有者可用。默认禁用；使用 `commands.config: true` 启用。
|
||||
`/config` 会写入你的磁盘配置（`openclaw.json`）。仅限所有者使用。默认禁用；用 `commands.config: true` 启用。
|
||||
|
||||
示例：
|
||||
|
||||
@ -400,7 +401,7 @@ x-i18n:
|
||||
|
||||
## MCP 更新
|
||||
|
||||
`/mcp` 会在 `mcp.servers` 下写入由 OpenClaw 管理的 MCP 服务器定义。仅所有者可用。默认禁用；使用 `commands.mcp: true` 启用。
|
||||
`/mcp` 会在 `mcp.servers` 下写入由 OpenClaw 管理的 MCP 服务器定义。仅限所有者使用。默认禁用；用 `commands.mcp: true` 启用。
|
||||
|
||||
示例：
|
||||
|
||||
@ -412,12 +413,12 @@ x-i18n:
|
||||
```
|
||||
|
||||
<Note>
|
||||
`/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 拥有的项目设置中。运行时适配器决定哪些传输协议实际可执行。
|
||||
`/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 拥有的项目设置中。运行时适配器决定实际可执行哪些传输协议。
|
||||
</Note>
|
||||
|
||||
## 插件更新
|
||||
|
||||
`/plugins` 允许操作员检查已发现的插件，并在配置中切换启用状态。只读流程可以使用 `/plugin` 作为别名。默认禁用；使用 `commands.plugins: true` 启用。
|
||||
`/plugins` 允许操作员检查已发现的插件，并在配置中切换启用状态。只读流程可以使用 `/plugin` 作为别名。默认禁用；用 `commands.plugins: true` 启用。
|
||||
|
||||
示例：
|
||||
|
||||
@ -430,45 +431,45 @@ x-i18n:
|
||||
```
|
||||
|
||||
<Note>
|
||||
- `/plugins list` 和 `/plugins show` 会基于当前工作区和磁盘配置执行真实的插件发现。
|
||||
- `/plugins enable|disable` 只更新插件配置；它不会安装或卸载插件。
|
||||
- 启用/禁用更改后，重启 Gateway 网关以应用它们。
|
||||
- `/plugins list` 和 `/plugins show` 会针对当前工作区加磁盘配置执行真实的插件发现。
|
||||
- `/plugins enable|disable` 只会更新插件配置；它不会安装或卸载插件。
|
||||
- 启用/禁用更改后，重启 Gateway 网关以应用更改。
|
||||
|
||||
</Note>
|
||||
|
||||
## 界面说明
|
||||
## 表面说明
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="每个界面的会话">
|
||||
- **文本命令**在普通聊天会话中运行（私信共享 `main`，群组有自己的会话）。
|
||||
<Accordion title="每个表面的会话">
|
||||
- **文本命令**在正常聊天会话中运行（私信共享 `main`，群组有自己的会话）。
|
||||
- **原生命令**使用隔离会话：
|
||||
- Discord：`agent:<agentId>:discord:slash:<userId>`
|
||||
- Slack：`agent:<agentId>:slack:slash:<userId>`（前缀可通过 `channels.slack.slashCommand.sessionPrefix` 配置）
|
||||
- Telegram：`telegram:slash:<userId>`（通过 `CommandTargetSessionKey` 定位聊天会话）
|
||||
- **`/stop`** 定位活动聊天会话，因此它可以中止当前运行。
|
||||
- Telegram：`telegram:slash:<userId>`（通过 `CommandTargetSessionKey` 指向聊天会话）
|
||||
- **`/stop`** 指向活动聊天会话，因此它可以中止当前运行。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Slack 细节">
|
||||
仍然支持 `channels.slack.slashCommand` 用于单个 `/openclaw` 风格命令。如果启用 `commands.native`，你必须为每个内置命令创建一个 Slack 斜杠命令（名称与 `/help` 相同）。Slack 的命令参数菜单会作为临时 Block Kit 按钮发送。
|
||||
`channels.slack.slashCommand` 仍支持单个 `/openclaw` 风格的命令。如果你启用 `commands.native`，则必须为每个内置命令创建一个 Slack 斜杠命令（名称与 `/help` 相同）。Slack 的命令参数菜单会以临时 Block Kit 按钮形式发送。
|
||||
|
||||
Slack 原生例外：注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 在 Slack 消息中仍然有效。
|
||||
Slack 原生例外：注册 `/agentstatus`（不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 在 Slack 消息中仍然可用。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## BTW 旁路问题
|
||||
## BTW 附带问题
|
||||
|
||||
`/btw` 是关于当前会话的快速**旁路问题**。
|
||||
`/btw` 是关于当前会话的快速**附带问题**。
|
||||
|
||||
与普通聊天不同：
|
||||
不同于普通聊天：
|
||||
|
||||
- 它使用当前会话作为背景上下文，
|
||||
- 它作为一次独立的**无工具**单次调用运行，
|
||||
- 它作为单独的**无工具**一次性调用运行，
|
||||
- 它不会改变未来的会话上下文，
|
||||
- 它不会写入转录历史，
|
||||
- 它会作为实时旁路结果发送，而不是普通助手消息。
|
||||
- 它会作为实时附带结果发送，而不是普通助手消息。
|
||||
|
||||
因此，当你希望在主任务继续进行时临时澄清某件事，`/btw` 会很有用。
|
||||
当你希望在主任务继续进行时获得临时澄清时，`/btw` 很有用。
|
||||
|
||||
示例：
|
||||
|
||||
@ -476,7 +477,7 @@ x-i18n:
|
||||
/btw what are we doing right now?
|
||||
```
|
||||
|
||||
请参阅 [BTW 旁路问题](/zh-CN/tools/btw)，了解完整行为和客户端 UX 细节。
|
||||
参见 [BTW 附带问题](/zh-CN/tools/btw) 了解完整行为和客户端 UX 细节。
|
||||
|
||||
## 相关内容
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user