diff --git a/docs/zh-CN/concepts/messages.md b/docs/zh-CN/concepts/messages.md index 9a9bc623c..5b4870e49 100644 --- a/docs/zh-CN/concepts/messages.md +++ b/docs/zh-CN/concepts/messages.md @@ -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..historyLimit`（设置为 `0` 可禁用）。 +指令剥离只应用于**当前消息**部分，因此历史记录保持完整。包装历史记录的渠道应将 `CommandBody`（或 `RawBody`）设置为原始消息文本，并将 `Body` 保持为组合后的提示。历史缓冲区可通过 `messages.groupChat.historyLimit`（全局默认）以及按渠道覆盖项配置，例如 `channels.slack.historyLimit` 或 `channels.telegram.accounts..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..responsePrefix` 和 `channels..accounts..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..silentReply` 和 `surfaces..silentReplyRewrite` 可以按 surface 覆盖它们。 -当父会话有一个或多个待处理的已生成子智能体运行时，所有 surface 上的裸静默回复都会被丢弃，而不是被改写，因此父会话会保持安静，直到子完成事件投递真实回复。 +当父会话有一个或多个待处理的已生成子智能体运行时，裸静默回复会在所有 surface 上被丢弃，而不是被改写，因此父会话会保持安静，直到子完成事件投递真实回复。 ## 相关 diff --git a/docs/zh-CN/concepts/queue.md b/docs/zh-CN/concepts/queue.md index c70e61a89..0d9513f59 100644 --- a/docs/zh-CN/concepts/queue.md +++ b/docs/zh-CN/concepts/queue.md @@ -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:`）入队，以保证每个会话同一时间只有一个活跃运行。 -- 然后，每个会话运行会被排入一个**全局通道**（默认 `main`），因此整体并行度受 `agents.defaults.maxConcurrent` 限制。 -- 启用详细日志时，如果排队运行在启动前等待超过约 2s，会发出一条简短通知。 -- 输入中指示器仍会在入队时立即触发（如果渠道支持），因此在等待轮到我们期间，用户体验保持不变。 +- 感知 lane 的 FIFO 队列按可配置的并发上限排空每个 lane（未配置的 lane 默认为 1；main 默认为 4，subagent 为 8）。 +- `runEmbeddedPiAgent` 按**会话键**（lane `session:`）入队，以保证每个会话只有一个活跃运行。 +- 每个会话运行随后会被排入一个**全局 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 ` 作为独立命令，以保存当前会话的模式。 -- 选项可以组合：`/queue collect debounce:2s cap:25 drop:summarize` +对于模式选择，OpenClaw 按以下顺序解析： + +1. 内联或已存储的每会话 `/queue` 覆盖。 +2. `messages.queue.byChannel.`。 +3. `messages.queue.mode`。 +4. 默认 `steer`。 + +对于选项，内联或已存储的 `/queue` 选项优先于配置。然后会应用渠道特定 debounce（`messages.queue.debounceMsByChannel`）、插件 debounce 默认值、全局 `messages.queue` 选项以及内置默认值。`cap` 和 `drop` 是全局/会话选项，不是按渠道配置键。 + +## 每会话覆盖 + +- 发送 `/queue ` 作为独立命令，为当前会话存储模式。 +- 选项可以组合：`/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) diff --git a/docs/zh-CN/gateway/config-agents.md b/docs/zh-CN/gateway/config-agents.md index b999b95d5..1676138a2 100644 --- a/docs/zh-CN/gateway/config-agents.md +++ b/docs/zh-CN/gateway/config-agents.md @@ -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 '' --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`；`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/"].params.thinking`。 -Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设置为 `false` 可禁用它。 -Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adaptive` 思考。 +Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/"].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 -- `mode: "cache-ttl"` 启用修剪流程。 -- `ttl` 控制修剪在多久之后可以再次运行（从上次缓存触碰后计算）。 -- 修剪会先软修剪过大的工具结果，然后在需要时硬清除更旧的工具结果。 +- `mode: "cache-ttl"` 启用剪除过程。 +- `ttl` 控制剪除多久可以再次运行（从上次缓存触碰后开始计算）。 +- 剪除会先软裁剪过大的工具结果，然后在需要时硬清除更旧的工具结果。 -**软修剪**会保留开头 + 结尾，并在中间插入 `...`。 +**软裁剪**保留开头 + 结尾，并在中间插入 `...`。 -**硬清除**会用占位符替换整个工具结果。 +**硬清除**将整个工具结果替换为占位符。 注意： -- 图片块永远不会被修剪/清除。 -- 比例基于字符（近似），不是精确 token 数。 -- 如果助手消息少于 `keepLastAssistants` 条，则跳过修剪。 +- 图像块永远不会被裁剪/清除。 +- 比率按字符计算（近似），不是精确的令牌数。 +- 如果 assistant 消息少于 `keepLastAssistants` 条，则跳过剪除。 -参见 [会话修剪](/zh-CN/concepts/session-pruning) 了解行为详情。 +行为详情参见[会话剪除](/zh-CN/concepts/session-pruning)。 ### 分块流式传输 @@ -635,12 +643,12 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adapti ``` - 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。 -- 渠道覆盖：`channels..blockStreamingCoalesce`（以及每个账号的变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 -- `humanDelay`：分块回复之间的随机暂停。`natural` = 800-2500ms。每个智能体覆盖：`agents.list[].humanDelay`。 +- 渠道覆盖：`channels..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)。 ### `agents.defaults.sandbox` -嵌入式智能体的可选沙箱隔离。完整指南请参见[沙箱隔离](/zh-CN/gateway/sandboxing)。 +嵌入式智能体的可选沙箱隔离。完整指南见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 ```json5 { @@ -757,7 +765,7 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 `adapti } ``` - + **后端：** @@ -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:"` 被阻止，除非你显式设置 +**容器默认使用 `network: "none"`** — 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义桥接网络）。 +`"host"` 会被阻止。默认情况下 `"container:"` 会被阻止，除非你显式设置 `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=` - `--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=` 更改；设置为 `0` 可使用 Chromium 的 默认进程限制。 - - 当 `noSandbox` 启用时，另加 `--no-sandbox`。 - - 默认值是容器镜像基线；使用带有自定义 - 入口点的自定义浏览器镜像来更改容器默认值。 + - 启用 `noSandbox` 时还会加上 `--no-sandbox`。 + - 默认值是容器镜像基线；要更改容器默认值，请使用带自定义 + 入口点的自定义浏览器镜像。 @@ -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 绑定层级顺序。 -### 每个智能体的访问配置文件 +### 每智能体访问配置档 @@ -1111,7 +1120,7 @@ scripts/sandbox-browser-setup.sh # optional browser image -有关优先级详细信息，请参见 [多智能体沙箱与工具](/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 - **`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.` 对话记录归档的保留时间。默认值为 `pruneAfter`；设置为 `false` 可禁用。 - - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会先移除最旧的产物/会话。 - - `highWaterBytes`：预算清理后的可选目标。默认值为 `maxDiskBytes` 的 `80%`。 + - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。运行时会为生产规模上限使用较小高水位缓冲执行批量清理写入；`openclaw sessions cleanup --enforce` 会立即应用上限。 + - `rotateBytes`：已弃用并被忽略；`openclaw doctor --fix` 会从旧配置中移除它。 + - `resetArchiveRetention`：`*.reset.` 转录归档的保留期。默认值为 `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` 禁用；提供商可以覆盖） @@ -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..ackReaction`、`channels..accounts..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.`。 +- 配置多个 Talk 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的一个键。 +- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容性，并会自动迁移到 `talk.providers.`。 - 语音 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`）。 --- diff --git a/docs/zh-CN/gateway/configuration-examples.md b/docs/zh-CN/gateway/configuration-examples.md index 18eaf3fa6..f7abc2804 100644 --- a/docs/zh-CN/gateway/configuration-examples.md +++ b/docs/zh-CN/gateway/configuration-examples.md @@ -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)，了解更深入的设置说明。 ## 相关内容 diff --git a/docs/zh-CN/help/faq.md b/docs/zh-CN/help/faq.md index ec682a5a1..d4b9ed668 100644 --- a/docs/zh-CN/help/faq.md +++ b/docs/zh-CN/help/faq.md @@ -1,76 +1,76 @@ --- read_when: - - 解答常见的设置、安装、新手引导或运行时支持问题 - - 在深入调试前先对用户报告的问题进行分诊 + - 回答常见的设置、安装、新手引导或运行时支持问题 + - 在深入调试前初步排查用户报告的问题 summary: 关于 OpenClaw 设置、配置和使用的常见问题 title: 常见问题 x-i18n: - generated_at: "2026-04-28T11:55:37Z" + generated_at: "2026-04-29T21:52:59Z" model: gpt-5.5 provider: openai - source_hash: b95bbc31c42d69d2aed142bdfba6b77ac203eb557765a864a2d3b6bd67e4d3ff + source_hash: e6f6a8b549962a57b98760ba40ba4579dad319c9ccd411560c030ee80799d11b source_path: help/faq.md workflow: 16 --- -Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, multi-agent, OAuth/API keys, model failover). For runtime diagnostics, see [Troubleshooting](/zh-CN/gateway/troubleshooting). For the full config reference, see [Configuration](/zh-CN/gateway/configuration). +快速解答，以及面向真实环境设置（本地开发、VPS、多智能体、OAuth/API key、模型故障转移）的深入故障排除。运行时诊断请参见 [故障排除](/zh-CN/gateway/troubleshooting)。完整配置参考请参见 [配置](/zh-CN/gateway/configuration)。 -## First 60 seconds if something is broken +## 最初的六十秒：如果出现故障 -1. **Quick status (first check)** +1. **快速 Status（第一项检查）** ```bash openclaw status ``` - Fast local summary: OS + update, gateway/service reachability, agents/sessions, provider config + runtime issues (when gateway is reachable). + 快速本地摘要：OS + 更新、Gateway 网关/服务可达性、智能体/会话、提供商配置 + 运行时问题（当 Gateway 网关可达时）。 -2. **Pasteable report (safe to share)** +2. **可粘贴报告（可安全分享）** ```bash openclaw status --all ``` - Read-only diagnosis with log tail (tokens redacted). + 只读诊断，包含日志尾部（令牌已遮蔽）。 -3. **Daemon + port state** +3. **守护进程 + 端口状态** ```bash openclaw gateway status ``` - Shows supervisor runtime vs RPC reachability, the probe target URL, and which config the service likely used. + 显示 supervisor 运行时与 RPC 可达性、探测目标 URL，以及服务可能使用了哪个配置。 -4. **Deep probes** +4. **深度探测** ```bash openclaw status --deep ``` - Runs a live gateway health probe, including channel probes when supported - (requires a reachable gateway). See [Health](/zh-CN/gateway/health). + 运行实时 Gateway 网关健康探测，包括支持时的渠道探测 + （需要可达的 Gateway 网关）。请参见 [健康检查](/zh-CN/gateway/health)。 -5. **Tail the latest log** +5. **跟踪最新日志** ```bash openclaw logs --follow ``` - If RPC is down, fall back to: + 如果 RPC 不可用，请回退到： ```bash tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" ``` - File logs are separate from service logs; see [Logging](/zh-CN/logging) and [Troubleshooting](/zh-CN/gateway/troubleshooting). + 文件日志与服务日志是分开的；请参见 [日志](/zh-CN/logging) 和 [故障排除](/zh-CN/gateway/troubleshooting)。 -6. **Run the doctor (repairs)** +6. **运行 Doctor（修复）** ```bash openclaw doctor ``` - 修复/迁移配置/状态 + 运行健康检查。参见 [Doctor](/zh-CN/gateway/doctor)。 + 修复/迁移配置和状态，并运行健康检查。请参见 [Doctor](/zh-CN/gateway/doctor)。 7. **Gateway 网关快照** @@ -79,83 +79,71 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, openclaw health --verbose # shows the target URL + config path on errors ``` - 向正在运行的 Gateway 网关请求完整快照（仅 WS）。参见 [健康状态](/zh-CN/gateway/health)。 + 向正在运行的 Gateway 网关请求完整快照（仅 WS）。请参见 [健康检查](/zh-CN/gateway/health)。 ## 快速开始和首次运行设置 -首次运行问答 —— 安装、新手引导、认证路由、订阅、初始故障 —— +首次运行问答 —— 安装、新手引导、鉴权路径、订阅、初始故障 —— 位于 [首次运行常见问题](/zh-CN/help/faq-first-run)。 ## 什么是 OpenClaw？ - - OpenClaw 是一个运行在你自己设备上的个人 AI 助手。它会在你已经使用的消息界面上回复（WhatsApp、Telegram、Slack、Mattermost、Discord、Google Chat、Signal、iMessage、WebChat，以及 QQ Bot 等内置渠道插件），并且在支持的平台上还能提供语音 + 实时 Canvas。**Gateway 网关**是常驻的控制平面；助手才是产品本身。 + + OpenClaw 是一个运行在你自己设备上的个人 AI 助手。它会在你已经使用的消息界面上回复（WhatsApp、Telegram、Slack、Mattermost、Discord、Google Chat、Signal、iMessage、WebChat，以及 QQ Bot 等内置渠道插件），并且还可以在受支持平台上提供语音 + 实时 Canvas。**Gateway 网关**是常驻控制平面；助手才是产品本身。 - OpenClaw 不只是“Claude 包装器”。它是一个**本地优先的控制平面**，让你可以在**自己的硬件**上运行一个 - 强大的助手，并能从你已经使用的聊天应用访问它，同时具备 - 有状态会话、记忆和工具，而无需把工作流的控制权交给托管的 - SaaS。 + OpenClaw 不只是“Claude 包装器”。它是一个**本地优先控制平面**，让你可以在**自己的硬件**上运行有能力的助手，并通过你已经使用的聊天应用访问它，拥有有状态会话、记忆和工具，而无需把工作流控制权交给托管式 SaaS。 亮点： - - **你的设备，你的数据：**在任何你想要的位置运行 Gateway 网关（Mac、Linux、VPS），并将 - 工作区 + 会话历史保留在本地。 - - **真实渠道，而不是网页沙箱：**WhatsApp/Telegram/Slack/Discord/Signal/iMessage/等， - 以及支持平台上的移动语音和 Canvas。 - - **模型无关：**使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，并支持按智能体路由 - 和故障转移。 - - **仅本地选项：**如果你愿意，可以运行本地模型，让**所有数据都保留在你的设备上**。 - - **多智能体路由：**按渠道、账号或任务拆分智能体，每个智能体都有自己的 - 工作区和默认设置。 - - **开源且可改造：**检查、扩展和自托管，不受供应商锁定。 + - **你的设备，你的数据：**在任何你想要的位置运行 Gateway 网关（Mac、Linux、VPS），并将工作区 + 会话历史保留在本地。 + - **真实渠道，而不是 Web 沙箱：**WhatsApp/Telegram/Slack/Discord/Signal/iMessage/等，以及受支持平台上的移动端语音和 Canvas。 + - **模型无关：**使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，并支持按智能体路由和故障转移。 + - **仅本地选项：**运行本地模型，这样如果你愿意，**所有数据都可以留在你的设备上**。 + - **多智能体路由：**按渠道、账号或任务拆分不同智能体，每个都有自己的工作区和默认配置。 + - **开源且可改造：**检查、扩展并自行托管，无需被供应商锁定。 文档：[Gateway 网关](/zh-CN/gateway)、[渠道](/zh-CN/channels)、[多智能体](/zh-CN/concepts/multi-agent)、 [记忆](/zh-CN/concepts/memory)。 - - 适合作为开始的项目： + + 适合开始的项目： - - 构建网站（WordPress、Shopify 或简单静态站点）。 - - 原型设计移动应用（大纲、页面、API 计划）。 + - 构建一个网站（WordPress、Shopify，或简单的静态站点）。 + - 原型化一个移动应用（大纲、屏幕、API 计划）。 - 整理文件和文件夹（清理、命名、打标签）。 - - 连接 Gmail，并自动生成摘要或后续跟进。 + - 连接 Gmail，并自动生成摘要或跟进事项。 - 它可以处理大型任务，但当你把任务拆成多个阶段并 - 使用子智能体并行工作时，效果最好。 + 它可以处理大型任务，但当你把任务拆成阶段，并使用子智能体并行工作时，效果最好。 - - 日常收益通常体现在： + + 日常收益通常像这样： - **个人简报：**汇总你关心的收件箱、日历和新闻。 - **研究和起草：**快速研究、摘要，以及邮件或文档的初稿。 - - **提醒和后续跟进：**由 cron 或心跳驱动的提醒和检查清单。 - - **浏览器自动化：**填写表单、收集数据，以及重复执行网页任务。 - - **跨设备协作：**从手机发送任务，让 Gateway 网关在服务器上运行，并在聊天中取回结果。 + - **提醒和跟进事项：**由 cron 或 Heartbeat 驱动的提醒和清单。 + - **浏览器自动化：**填写表单、收集数据，以及重复执行 Web 任务。 + - **跨设备协同：**从手机发送任务，让 Gateway 网关在服务器上运行，并在聊天中拿回结果。 - - 可以，用于**调研、资格筛选和起草**。它可以扫描网站、生成候选名单、 - 总结潜在客户，并撰写外联或广告文案草稿。 + + 可以，用于**研究、资格筛选和起草**。它可以扫描站点、构建候选清单、总结潜在客户，并撰写外联或广告文案草稿。 - 对于**外联或广告投放**，请保留人工审核环节。避免垃圾信息，遵守当地法律和 - 平台政策，并在发送前审核所有内容。最安全的模式是让 - OpenClaw 起草，由你批准。 + 对于**外联或广告投放**，请让人类参与审核。避免垃圾信息，遵守当地法律和平台政策，并在发送前审核所有内容。最安全的模式是让 OpenClaw 起草，由你批准。 文档：[安全](/zh-CN/gateway/security)。 - - OpenClaw 是**个人助理**和协调层，而不是 IDE 替代品。在仓库内最快的直接编码循环中使用 - Claude Code 或 Codex。当你需要持久记忆、跨设备访问和工具编排时使用 OpenClaw。 + + OpenClaw 是一个**个人助手**和协同层，而不是 IDE 替代品。要在代码库内获得最快的直接编码循环，请使用 Claude Code 或 Codex。需要持久记忆、跨设备访问和工具编排时，使用 OpenClaw。 优势： @@ -163,7 +151,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - **多平台访问**（WhatsApp、Telegram、TUI、WebChat） - **工具编排**（浏览器、文件、调度、钩子） - **常驻 Gateway 网关**（运行在 VPS 上，从任何地方交互） - - 用于本地浏览器/屏幕/摄像头/执行的**节点** + - 用于本地浏览器/屏幕/摄像头/exec 的 **Nodes** 展示：[https://openclaw.ai/showcase](https://openclaw.ai/showcase) @@ -173,46 +161,44 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, ## Skills 和自动化 - - 使用托管覆盖，而不是编辑仓库副本。将你的更改放在 `~/.openclaw/skills//SKILL.md` 中（或通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加文件夹）。优先级是 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`，因此托管覆盖仍会优先于内置 Skills，而无需触碰 git。如果你需要全局安装该 Skill，但只对部分智能体可见，请将共享副本保留在 `~/.openclaw/skills` 中，并用 `agents.defaults.skills` 和 `agents.list[].skills` 控制可见性。只有值得上游合并的编辑才应放在仓库中并作为 PR 发出。 + + 使用托管覆盖，而不是编辑代码库副本。将你的更改放在 `~/.openclaw/skills//SKILL.md` 中（或通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加文件夹）。优先级为 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`，因此托管覆盖仍会在不触碰 git 的情况下优先于内置 Skills。如果你需要全局安装该 Skill，但只让某些智能体可见，请将共享副本放在 `~/.openclaw/skills` 中，并使用 `agents.defaults.skills` 和 `agents.list[].skills` 控制可见性。只有适合上游的编辑才应放入代码库并以 PR 形式提交。 - 可以。通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加额外目录（最低优先级）。默认优先级是 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`。`clawhub` 默认安装到 `./skills`，OpenClaw 会在下一次会话中将其视为 `/skills`。如果该 Skill 只应对特定智能体可见，请配合使用 `agents.defaults.skills` 或 `agents.list[].skills`。 + 可以。通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加额外目录（最低优先级）。默认优先级为 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`。`clawhub` 默认安装到 `./skills`，OpenClaw 会在下一个会话中将其视为 `/skills`。如果该 Skill 只应对某些智能体可见，请搭配 `agents.defaults.skills` 或 `agents.list[].skills` 使用。 - 当前支持的模式是： + 目前支持的模式是： - **Cron 作业**：隔离作业可以为每个作业设置 `model` 覆盖。 - - **子智能体**：将任务路由到使用不同默认模型的独立智能体。 - - **按需切换**：随时使用 `/model` 切换当前会话模型。 + - **子智能体**：将任务路由到具有不同默认模型的独立智能体。 + - **按需切换**：使用 `/model` 随时切换当前会话模型。 - 请参阅 [Cron 作业](/zh-CN/automation/cron-jobs)、[多智能体路由](/zh-CN/concepts/multi-agent) 和 [Slash 命令](/zh-CN/tools/slash-commands)。 + 请参见 [Cron 作业](/zh-CN/automation/cron-jobs)、[多智能体路由](/zh-CN/concepts/multi-agent) 和 [斜杠命令](/zh-CN/tools/slash-commands)。 - - 对长任务或并行任务使用**子智能体**。子智能体在自己的会话中运行， - 返回摘要，并让你的主聊天保持响应。 + + 对长任务或并行任务使用**子智能体**。子智能体在自己的会话中运行，返回摘要，并让你的主聊天保持响应。 - 让你的机器人“为此任务生成一个子智能体”，或使用 `/subagents`。 - 在聊天中使用 `/status` 查看 Gateway 网关当前正在做什么（以及它是否繁忙）。 + 让你的机器人“spawn a sub-agent for this task”，或使用 `/subagents`。 + 在聊天中使用 `/status` 查看 Gateway 网关当前正在做什么（以及它是否忙碌）。 - Token 提示：长任务和子智能体都会消耗 token。如果担心成本，可以通过 `agents.defaults.subagents.model` 为子智能体设置 - 更便宜的模型。 + 令牌提示：长任务和子智能体都会消耗令牌。如果你关心成本，请通过 `agents.defaults.subagents.model` 为子智能体设置更便宜的模型。 文档：[子智能体](/zh-CN/tools/subagents)、[后台任务](/zh-CN/automation/tasks)。 - - 使用线程绑定。你可以将 Discord 线程绑定到子智能体或会话目标，这样该线程中的后续消息会停留在绑定的会话上。 + + 使用线程绑定。你可以将 Discord 线程绑定到子智能体或会话目标，使该线程中的后续消息保持在绑定的会话上。 基本流程： - - 使用带有 `thread: true` 的 `sessions_spawn` 生成（也可选择 `mode: "session"` 以便持久跟进）。 - - 或者使用 `/focus ` 手动绑定。 + - 使用带有 `thread: true` 的 `sessions_spawn` 生成（也可选择 `mode: "session"` 以进行持久跟进）。 + - 或使用 `/focus ` 手动绑定。 - 使用 `/agents` 检查绑定状态。 - 使用 `/session idle ` 和 `/session max-age ` 控制自动取消聚焦。 - 使用 `/unfocus` 分离该线程。 @@ -220,22 +206,22 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, 必需配置： - 全局默认值：`session.threadBindings.enabled`、`session.threadBindings.idleHours`、`session.threadBindings.maxAgeHours`。 - - Discord 覆盖：`channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours`。 + - Discord 覆盖项：`channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours`。 - 生成时自动绑定：设置 `channels.discord.threadBindings.spawnSubagentSessions: true`。 - 文档：[子智能体](/zh-CN/tools/subagents)、[Discord](/zh-CN/channels/discord)、[配置参考](/zh-CN/gateway/configuration-reference)、[Slash 命令](/zh-CN/tools/slash-commands)。 + 文档：[子智能体](/zh-CN/tools/subagents)、[Discord](/zh-CN/channels/discord)、[配置参考](/zh-CN/gateway/configuration-reference)、[斜杠命令](/zh-CN/tools/slash-commands)。 - - 先检查解析出的请求方路由： + + 先检查解析出的请求者路由： - 完成模式的子智能体投递会优先使用任何已绑定线程或会话路由（如果存在）。 - - 如果完成来源只携带渠道，OpenClaw 会回退到请求方会话存储的路由（`lastChannel` / `lastTo` / `lastAccountId`），这样直接投递仍可能成功。 - - 如果既没有绑定路由，也没有可用的存储路由，直接投递可能失败，结果会回退到排队会话投递，而不是立即发布到聊天。 - - 无效或过期的目标仍可能强制回退到队列或导致最终投递失败。 - - 如果子级最后一条可见助手回复是精确的静默 token `NO_REPLY` / `no_reply`，或正好是 `ANNOUNCE_SKIP`，OpenClaw 会有意抑制公告，而不是发布过期的早前进度。 - - 如果子级仅在工具调用后超时，公告可以将其压缩为简短的部分进度摘要，而不是重放原始工具输出。 + - 如果完成来源只携带渠道，OpenClaw 会回退到请求者会话存储的路由（`lastChannel` / `lastTo` / `lastAccountId`），这样直接投递仍可成功。 + - 如果既没有绑定路由，也没有可用的已存储路由，直接投递可能失败，结果会回退到排队会话投递，而不是立即发布到聊天中。 + - 无效或过期的目标仍可能强制队列回退，或导致最终投递失败。 + - 如果子会话最后一条可见助手回复正好是静默令牌 `NO_REPLY` / `no_reply`，或正好是 `ANNOUNCE_SKIP`，OpenClaw 会有意抑制通知，而不是发布过期的较早进度。 + - 如果子会话只在工具调用后超时，通知可以将其折叠为简短的部分进度摘要，而不是重放原始工具输出。 调试： @@ -247,15 +233,14 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - - Cron 在 Gateway 网关进程内部运行。如果 Gateway 网关没有持续运行， - 计划作业就不会运行。 + + Cron 在 Gateway 网关进程内运行。如果 Gateway 网关没有持续运行，定时作业就不会运行。 检查清单： - - 确认 cron 已启用（`cron.enabled`），且未设置 `OPENCLAW_SKIP_CRON`。 + - 确认 cron 已启用（`cron.enabled`），并且没有设置 `OPENCLAW_SKIP_CRON`。 - 检查 Gateway 网关是否 24/7 运行（没有睡眠/重启）。 - - 验证该作业的时区设置（`--tz` 与主机时区）。 + - 验证作业的时区设置（`--tz` 与主机时区）。 调试： @@ -264,21 +249,21 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, openclaw cron runs --id --limit 50 ``` - 文档：[Cron 作业](/zh-CN/automation/cron-jobs)、[自动化与任务](/zh-CN/automation)。 + 文档：[Cron 作业](/zh-CN/automation/cron-jobs)、[自动化和任务](/zh-CN/automation)。 - + 先检查投递模式： - - `--no-deliver` / `delivery.mode: "none"` 表示不应发生运行器回退发送。 - - 缺少或无效的公告目标（`channel` / `to`）表示运行器跳过了出站投递。 - - 渠道认证失败（`unauthorized`、`Forbidden`）表示运行器尝试投递，但凭据阻止了它。 - - 静默的隔离结果（仅 `NO_REPLY` / `no_reply`）会被视为有意不可投递，因此运行器也会抑制排队的回退投递。 + - `--no-deliver` / `delivery.mode: "none"` 表示不应期待 runner fallback 发送。 + - 缺少或无效的公告目标（`channel` / `to`）表示 runner 跳过了出站投递。 + - 渠道凭证失败（`unauthorized`、`Forbidden`）表示 runner 尝试投递，但凭证阻止了它。 + - 静默隔离结果（仅 `NO_REPLY` / `no_reply`）会被视为有意不可投递，因此 runner 也会抑制队列中的 fallback 投递。 - 对于隔离的 Cron 任务，当聊天路由可用时，智能体仍然可以用 `message` - 工具直接发送。`--announce` 只控制智能体尚未发送的最终文本所走的运行器 - 回退路径。 + 对于隔离的 cron 任务，当聊天路由可用时，智能体仍然可以使用 `message` + 工具直接发送。`--announce` 只控制智能体尚未发送的最终文本的 runner + fallback 路径。 调试： @@ -291,22 +276,23 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - + 这通常是实时模型切换路径，而不是重复调度。 - 当活动运行抛出 `LiveSessionModelSwitchError` 时，隔离的 Cron 可以持久化运行时模型交接并重试。 - 重试会保留切换后的提供商/模型；如果该切换携带了新的认证配置覆盖，Cron + 隔离的 cron 可以持久化运行时模型交接，并在活动运行抛出 + `LiveSessionModelSwitchError` 时重试。重试会保留切换后的 + 提供商/模型，如果切换携带了新的凭证配置覆盖，cron 也会在重试前将其持久化。 相关选择规则： - - 适用时，Gmail 钩子模型覆盖优先。 + - Gmail 钩子模型覆盖在适用时优先。 - 然后是每个任务的 `model`。 - - 然后是任何已存储的 Cron 会话模型覆盖。 - - 然后是普通的智能体/默认模型选择。 + - 然后是任何已存储的 cron 会话模型覆盖。 + - 然后是正常的智能体/默认模型选择。 - 重试循环是有上限的。初次尝试加上 2 次切换重试之后， - Cron 会中止，而不是无限循环。 + 重试循环有边界。初始尝试加上 2 次切换重试后， + cron 会中止，而不是无限循环。 调试： @@ -335,38 +321,38 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, ``` 原生 `openclaw skills install` 会写入活动工作区的 `skills/` - 目录。仅当你想发布或同步自己的 Skills 时，才需要安装单独的 `clawhub` CLI。 - 如需在多个智能体之间共享安装，请将 Skill 放在 `~/.openclaw/skills` - 下；如果你想缩小哪些智能体可以看到它，请使用 `agents.defaults.skills` 或 - `agents.list[].skills`。 + 目录。仅当你想发布或同步自己的 Skills 时，才安装单独的 + `clawhub` CLI。若要在多个智能体间共享安装，请将 Skill 放在 + `~/.openclaw/skills` 下；如果想限制哪些智能体可见，请使用 + `agents.defaults.skills` 或 `agents.list[].skills`。 - + 可以。使用 Gateway 网关调度器： - - **Cron 任务**用于计划任务或重复任务（重启后仍会保留）。 - - **Heartbeat** 用于“主会话”周期性检查。 - - **隔离任务**用于发布摘要或投递到聊天的自主智能体。 + - **Cron 任务** 用于计划任务或重复任务（重启后仍会保留）。 + - **Heartbeat** 用于“主会话”的周期性检查。 + - **隔离任务** 用于发布摘要或投递到聊天的自主智能体。 - 文档：[Cron 任务](/zh-CN/automation/cron-jobs)、[自动化与任务](/zh-CN/automation)、 + 文档：[Cron 任务](/zh-CN/automation/cron-jobs)、[自动化和任务](/zh-CN/automation)、 [Heartbeat](/zh-CN/gateway/heartbeat)。 - - 不能直接运行。macOS Skills 受 `metadata.openclaw.os` 加必需二进制文件限制，并且 Skills 只有在 **Gateway 网关主机**上符合条件时才会出现在系统提示中。在 Linux 上，仅限 `darwin` 的 Skills（如 `apple-notes`、`apple-reminders`、`things-mac`）不会加载，除非你覆盖该门控。 + + 不能直接运行。macOS Skills 受 `metadata.openclaw.os` 加所需二进制文件限制，并且 Skills 只有在 **Gateway 网关主机** 上符合条件时才会出现在系统提示中。在 Linux 上，仅限 `darwin` 的 Skills（如 `apple-notes`、`apple-reminders`、`things-mac`）不会加载，除非你覆盖该限制。 你有三种受支持的模式： **选项 A - 在 Mac 上运行 Gateway 网关（最简单）。** - 在存在 macOS 二进制文件的地方运行 Gateway 网关，然后从 Linux 以[远程模式](#gateway-ports-already-running-and-remote-mode)连接，或通过 Tailscale 连接。由于 Gateway 网关主机是 macOS，Skills 会正常加载。 + 在存在 macOS 二进制文件的位置运行 Gateway 网关，然后从 Linux 通过[远程模式](#gateway-ports-already-running-and-remote-mode)或 Tailscale 连接。由于 Gateway 网关主机是 macOS，Skills 会正常加载。 **选项 B - 使用 macOS 节点（无需 SSH）。** - 在 Linux 上运行 Gateway 网关，配对一个 macOS 节点（菜单栏应用），并在 Mac 上将 **Node Run Commands** 设置为 “Always Ask” 或 “Always Allow”。当所需二进制文件存在于节点上时，OpenClaw 可以将仅适用于 macOS 的 Skills 视为符合条件。智能体通过 `nodes` 工具运行这些 Skills。如果你选择 “Always Ask”，在提示中批准 “Always Allow” 会将该命令加入允许列表。 + 在 Linux 上运行 Gateway 网关，配对一个 macOS 节点（菜单栏应用），并在 Mac 上将 **Node Run Commands** 设置为“Always Ask”或“Always Allow”。当节点上存在所需二进制文件时，OpenClaw 可以将仅限 macOS 的 Skills 视为符合条件。智能体通过 `nodes` 工具运行这些 Skills。如果选择“Always Ask”，在提示中批准“Always Allow”会将该命令添加到允许列表。 **选项 C - 通过 SSH 代理 macOS 二进制文件（高级）。** - 将 Gateway 网关保留在 Linux 上，但让所需 CLI 二进制文件解析为在 Mac 上运行的 SSH 包装器。然后覆盖 Skill 以允许 Linux，使其保持符合条件。 + 保持 Gateway 网关在 Linux 上运行，但让所需的 CLI 二进制文件解析为在 Mac 上运行的 SSH 包装器。然后覆盖 Skill 以允许 Linux，使其保持符合条件。 1. 为该二进制文件创建 SSH 包装器（示例：Apple Notes 的 `memo`）： @@ -396,15 +382,16 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, 选项： - - **自定义 Skill / 插件：**最适合可靠的 API 访问（Notion/HeyGen 都有 API）。 - - **浏览器自动化：**无需代码即可使用，但速度较慢，也更脆弱。 + - **自定义 Skill / 插件：** 最适合可靠的 API 访问（Notion/HeyGen 都有 API）。 + - **浏览器自动化：** 无需代码即可工作，但速度较慢且更脆弱。 如果你想按客户保留上下文（代理机构工作流），一个简单模式是： - 每个客户一个 Notion 页面（上下文 + 偏好 + 活跃工作）。 - - 让智能体在会话开始时获取该页面。 + - 要求智能体在会话开始时获取该页面。 - 如果你想要原生集成，请提交功能请求，或构建一个面向这些 API 的 Skill。 + 如果你想要原生集成，请提交功能请求，或构建一个面向这些 API + 的 Skill。 安装 Skills： @@ -413,48 +400,48 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, openclaw skills update --all ``` - 原生安装会落在活动工作区的 `skills/` 目录中。对于跨智能体共享的 Skills，请将它们放在 `~/.openclaw/skills//SKILL.md`。如果只有部分智能体应看到某个共享安装，请配置 `agents.defaults.skills` 或 `agents.list[].skills`。有些 Skills 需要通过 Homebrew 安装二进制文件；在 Linux 上，这意味着 Linuxbrew（参见上方的 Homebrew Linux 常见问题条目）。参见 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 和 [ClawHub](/zh-CN/tools/clawhub)。 + 原生安装会落在活动工作区的 `skills/` 目录中。若要在多个智能体间共享 Skills，请将它们放在 `~/.openclaw/skills//SKILL.md`。如果只有部分智能体应看到共享安装，请配置 `agents.defaults.skills` 或 `agents.list[].skills`。某些 Skills 需要通过 Homebrew 安装的二进制文件；在 Linux 上，这意味着 Linuxbrew（参见上方 Homebrew Linux 常见问题条目）。参见 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 和 [ClawHub](/zh-CN/tools/clawhub)。 - - 使用内置的 `user` 浏览器配置文件，它会通过 Chrome DevTools MCP 附加： + + 使用内置的 `user` 浏览器配置文件，它通过 Chrome DevTools MCP 附加： ```bash openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot ``` - 如果你想使用自定义名称，请创建一个显式的 MCP 配置文件： + 如果想使用自定义名称，请创建显式 MCP 配置文件： ```bash openclaw browser create-profile --name chrome-live --driver existing-session openclaw browser --browser-profile chrome-live tabs ``` - 这条路径可以使用本地主机浏览器或已连接的浏览器节点。如果 Gateway 网关在其他地方运行，请在浏览器机器上运行节点主机，或改用远程 CDP。 + 此路径可以使用本地主机浏览器或已连接的浏览器节点。如果 Gateway 网关在其他位置运行，请在浏览器机器上运行节点主机，或改用远程 CDP。 `existing-session` / `user` 的当前限制： - - 操作由引用驱动，而不是由 CSS 选择器驱动 - - 上传需要 `ref` / `inputRef`，且目前一次支持一个文件 + - 操作由 ref 驱动，而不是由 CSS selector 驱动 + - 上传需要 `ref` / `inputRef`，并且目前一次支持一个文件 - `responsebody`、PDF 导出、下载拦截和批量操作仍需要托管浏览器或原始 CDP 配置文件 -## 沙箱隔离和内存 +## 沙箱隔离和记忆 - - 有。参见[沙箱隔离](/zh-CN/gateway/sandboxing)。对于 Docker 专用设置（完整 Gateway 网关运行在 Docker 中或沙箱镜像），请参见 [Docker](/zh-CN/install/docker)。 + + 有。参见[沙箱隔离](/zh-CN/gateway/sandboxing)。对于 Docker 专用设置（在 Docker 中运行完整 Gateway 网关或沙箱镜像），参见 [Docker](/zh-CN/install/docker)。 - 默认镜像以安全优先，并以 `node` 用户运行，因此不包含系统包、Homebrew 或内置浏览器。 - 如需更完整的设置： + 默认镜像以安全优先，并作为 `node` 用户运行，因此它不 + 包含系统包、Homebrew 或内置浏览器。若要获得更完整的设置： - - 使用 `OPENCLAW_HOME_VOLUME` 持久化 `/home/node`，让缓存得以保留。 + - 使用 `OPENCLAW_HOME_VOLUME` 持久化 `/home/node`，以便缓存保留。 - 使用 `OPENCLAW_DOCKER_APT_PACKAGES` 将系统依赖烘焙进镜像。 - 通过内置 CLI 安装 Playwright 浏览器： `node /app/node_modules/playwright-core/cli.js install chromium` @@ -464,12 +451,12 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - - 可以，前提是你的私有流量是**私信**，公共流量是**群组**。 + + 可以，前提是你的私密流量是 **私信**，公开流量是 **群组**。 - 使用 `agents.defaults.sandbox.mode: "non-main"`，让群组/渠道会话（非主键）在配置的沙箱后端中运行，而主私信会话仍留在主机上。如果你没有选择后端，Docker 是默认后端。然后通过 `tools.sandbox.tools` 限制沙箱隔离会话中可用的工具。 + 使用 `agents.defaults.sandbox.mode: "non-main"`，这样群组/渠道会话（非主键）会在配置的沙箱后端中运行，而主私信会话仍保留在主机上。如果你不选择后端，Docker 是默认后端。然后通过 `tools.sandbox.tools` 限制沙箱隔离会话中可用的工具。 - 设置演练 + 示例配置：[群组：个人私信 + 公共群组](/zh-CN/channels/groups#pattern-personal-dms-public-groups-single-agent) + 设置演练 + 示例配置：[群组：个人私信 + 公开群组](/zh-CN/channels/groups#pattern-personal-dms-public-groups-single-agent) 关键配置参考：[Gateway 网关配置](/zh-CN/gateway/config-agents#agentsdefaultssandbox) @@ -478,98 +465,100 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, 将 `agents.defaults.sandbox.docker.binds` 设置为 `["host:path:mode"]`（例如 `"/home/user/src:/src:ro"`）。全局绑定和每智能体绑定会合并；当 `scope: "shared"` 时，会忽略每智能体绑定。对任何敏感内容使用 `:ro`，并记住绑定会绕过沙箱文件系统边界。 - OpenClaw 会根据规范化路径和通过最深已存在祖先解析出的规范路径来验证绑定源。这意味着即使最后一个路径片段尚不存在，符号链接父级逃逸仍会失败关闭，并且允许根检查在符号链接解析后仍然适用。 + OpenClaw 会同时根据规范化路径和通过最深已存在祖先解析出的规范路径来验证绑定源。这意味着即使最后一个路径段尚不存在，符号链接父目录逃逸仍会失败关闭，并且允许根检查仍会在符号链接解析后适用。 - 示例和安全说明见[沙箱隔离](/zh-CN/gateway/sandboxing#custom-bind-mounts)和[沙箱 vs 工具策略 vs 提权](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check)。 + 参见[沙箱隔离](/zh-CN/gateway/sandboxing#custom-bind-mounts)和[沙箱 vs 工具策略 vs 提权](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check)，获取示例和安全说明。 - - OpenClaw 内存只是智能体工作区中的 Markdown 文件： + + OpenClaw 记忆只是智能体工作区中的 Markdown 文件： - `memory/YYYY-MM-DD.md` 中的每日笔记 - - `MEMORY.md` 中整理后的长期笔记（仅主会话/私有会话） + - `MEMORY.md` 中的精选长期笔记（仅主/私密会话） - OpenClaw 还会运行**静默预压缩内存刷新**，提醒模型在自动压缩之前写入持久笔记。 - 这只会在工作区可写时运行（只读沙箱会跳过）。参见[内存](/zh-CN/concepts/memory)。 + OpenClaw 还会运行一次**静默的压缩前记忆刷新**，提醒模型 + 在自动压缩前写入持久笔记。它只会在工作区可写时运行（只读沙箱会跳过）。参见[记忆](/zh-CN/concepts/memory)。 - - 要求机器人**将事实写入内存**。长期笔记应放在 `MEMORY.md`， - 短期上下文则进入 `memory/YYYY-MM-DD.md`。 + + 要求机器人**将事实写入记忆**。长期笔记应放在 `MEMORY.md`， + 短期上下文放入 `memory/YYYY-MM-DD.md`。 这仍是我们正在改进的领域。提醒模型存储记忆会有帮助； - 它会知道该怎么做。如果它一直忘记，请确认 Gateway 网关在每次运行时都使用同一个工作区。 + 它会知道该怎么做。如果它仍然忘记，请确认 Gateway 网关每次运行都使用同一个 + 工作区。 - 文档：[内存](/zh-CN/concepts/memory)、[Agent 工作区](/zh-CN/concepts/agent-workspace)。 + 文档：[记忆](/zh-CN/concepts/memory)、[Agent 工作区](/zh-CN/concepts/agent-workspace)。 - - 内存文件存在磁盘上，并会一直保留，直到你删除它们。限制来自你的 - 存储空间，而不是模型。**会话上下文**仍受模型上下文窗口限制， - 因此长对话可能会压缩或截断。这就是内存搜索存在的原因，它只会将相关部分拉回上下文。 + + 记忆文件位于磁盘上，并会保留到你删除它们为止。限制来自你的 + 存储空间，而不是模型。**会话上下文**仍受模型 + 上下文窗口限制，因此长对话可能会被压缩或截断。这就是 + 记忆搜索存在的原因，它只会把相关部分拉回上下文。 - 文档：[内存](/zh-CN/concepts/memory)、[上下文](/zh-CN/concepts/context)。 + 文档：[记忆](/zh-CN/concepts/memory)、[上下文](/zh-CN/concepts/context)。 - - 只有在你使用 **OpenAI embeddings** 时才需要。Codex OAuth 覆盖聊天/补全， - 但**不会**授予 embeddings 访问权限，因此**使用 Codex 登录（OAuth 或 - Codex CLI 登录）**对语义记忆搜索没有帮助。OpenAI embeddings - 仍然需要真实的 API 密钥（`OPENAI_API_KEY` 或 `models.providers.openai.apiKey`）。 + + 仅当你使用 **OpenAI 嵌入**时才需要。Codex OAuth 覆盖聊天/补全， + 但**不会**授予嵌入访问权限，因此**使用 Codex 登录（OAuth 或 + Codex CLI 登录）**对语义记忆搜索没有帮助。OpenAI 嵌入 + 仍然需要真实的 API key（`OPENAI_API_KEY` 或 `models.providers.openai.apiKey`）。 - 如果你没有显式设置提供商，OpenClaw 会在能够解析 API 密钥时自动选择提供商 - （凭证配置档、`models.providers.*.apiKey` 或环境变量）。如果能解析到 OpenAI 密钥， - 它会优先选择 OpenAI；否则如果能解析到 Gemini 密钥，就选择 Gemini， - 然后是 Voyage，再然后是 Mistral。如果没有可用的远程密钥，记忆搜索会保持禁用， - 直到你完成配置。如果你已经配置并提供了本地模型路径，OpenClaw - 会优先选择 `local`。当你显式设置 + 如果你没有显式设置提供商，OpenClaw 会在能够解析 API key 时自动选择提供商 + （auth profiles、`models.providers.*.apiKey` 或环境变量）。 + 如果能解析到 OpenAI key，它会优先使用 OpenAI；否则如果能解析到 Gemini key， + 则使用 Gemini；然后是 Voyage，再然后是 Mistral。如果没有可用的远程 key，记忆 + 搜索会保持禁用，直到你完成配置。如果你配置了本地模型路径且该路径存在， + OpenClaw 会优先使用 `local`。显式设置 `memorySearch.provider = "ollama"` 时支持 Ollama。 如果你更想保持本地运行，请设置 `memorySearch.provider = "local"`（并可选设置 - `memorySearch.fallback = "none"`）。如果你想使用 Gemini embeddings，请设置 + `memorySearch.fallback = "none"`）。如果你想使用 Gemini 嵌入，请设置 `memorySearch.provider = "gemini"` 并提供 `GEMINI_API_KEY`（或 - `memorySearch.remote.apiKey`）。我们支持 **OpenAI、Gemini、Voyage、Mistral、Ollama 或 local** embedding - 模型 - 设置详情见 [Memory](/zh-CN/concepts/memory)。 + `memorySearch.remote.apiKey`）。我们支持 **OpenAI、Gemini、Voyage、Mistral、Ollama 或本地**嵌入 + 模型 - 设置详情请参见 [Memory](/zh-CN/concepts/memory)。 -## 磁盘上的内容位置 +## 内容在磁盘上的位置 - - 不会 - **OpenClaw 的状态是本地的**，但**外部服务仍然会看到你发送给它们的内容**。 + + 不会 - **OpenClaw 的状态是本地的**，但**外部服务仍会看到你发送给它们的内容**。 - **默认本地：** 会话、记忆文件、配置和工作区位于 Gateway 网关主机上 （`~/.openclaw` + 你的工作区目录）。 - **必要时远程：** 你发送给模型提供商（Anthropic/OpenAI 等）的消息会进入 - 它们的 API，而聊天平台（WhatsApp/Telegram/Slack 等）会将消息数据存储在它们的 - 服务器上。 - - **你控制占用范围：** 使用本地模型会让提示词留在你的机器上，但渠道 + 它们的 API，聊天平台（WhatsApp/Telegram/Slack 等）会在它们的 + 服务器上存储消息数据。 + - **你控制占用范围：** 使用本地模型会把提示词保留在你的机器上，但渠道 流量仍会经过该渠道的服务器。 - 相关：[Agent 工作区](/zh-CN/concepts/agent-workspace)，[Memory](/zh-CN/concepts/memory)。 + 相关：[Agent 工作区](/zh-CN/concepts/agent-workspace)、[Memory](/zh-CN/concepts/memory)。 所有内容都位于 `$OPENCLAW_STATE_DIR` 下（默认：`~/.openclaw`）： - | 路径 | 用途 | + | 路径 | 用途 | | --------------------------------------------------------------- | ------------------------------------------------------------------ | - | `$OPENCLAW_STATE_DIR/openclaw.json` | 主配置（JSON5） | - | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | 旧版 OAuth 导入（首次使用时复制到凭证配置档） | - | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | 凭证配置档（OAuth、API 密钥，以及可选的 `keyRef`/`tokenRef`） | - | `$OPENCLAW_STATE_DIR/secrets.json` | `file` SecretRef 提供商的可选文件后备密钥载荷 | - | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | 旧版兼容文件（静态 `api_key` 条目已清理） | - | `$OPENCLAW_STATE_DIR/credentials/` | 提供商状态（例如 `whatsapp//creds.json`） | - | `$OPENCLAW_STATE_DIR/agents/` | 每个智能体的状态（agentDir + 会话） | - | `$OPENCLAW_STATE_DIR/agents//sessions/` | 对话历史与状态（按智能体） | - | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | 会话元数据（按智能体） | + | `$OPENCLAW_STATE_DIR/openclaw.json` | 主配置（JSON5） | + | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | 旧版 OAuth 导入（首次使用时复制到 auth profiles） | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Auth profiles（OAuth、API keys，以及可选的 `keyRef`/`tokenRef`） | + | `$OPENCLAW_STATE_DIR/secrets.json` | 用于 `file` SecretRef 提供商的可选文件型密钥载荷 | + | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | 旧版兼容文件（静态 `api_key` 条目会被清理） | + | `$OPENCLAW_STATE_DIR/credentials/` | 提供商状态（例如 `whatsapp//creds.json`） | + | `$OPENCLAW_STATE_DIR/agents/` | 每智能体状态（agentDir + sessions） | + | `$OPENCLAW_STATE_DIR/agents//sessions/` | 对话历史和状态（按智能体） | + | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | 会话元数据（按智能体） | 旧版单智能体路径：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移）。 @@ -582,9 +571,9 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - **工作区（按智能体）**：`AGENTS.md`、`SOUL.md`、`IDENTITY.md`、`USER.md`、 `MEMORY.md`、`memory/YYYY-MM-DD.md`、可选的 `HEARTBEAT.md`。 - 小写的根目录 `memory.md` 仅作为旧版修复输入；当两个文件都存在时，`openclaw doctor --fix` - 可以将它合并进 `MEMORY.md`。 - - **状态目录（`~/.openclaw`）**：配置、渠道/提供商状态、凭证配置档、会话、日志， + 小写根文件 `memory.md` 仅作为旧版修复输入；当两个文件都存在时，`openclaw doctor --fix` + 可以将它合并到 `MEMORY.md`。 + - **状态目录（`~/.openclaw`）**：配置、渠道/提供商状态、auth profiles、会话、日志， 以及共享 Skills（`~/.openclaw/skills`）。 默认工作区是 `~/.openclaw/workspace`，可通过以下方式配置： @@ -595,42 +584,42 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, } ``` - 如果机器人重启后“忘记”了内容，请确认 Gateway 网关每次启动时都使用同一个 + 如果机器人在重启后“忘记”了，请确认 Gateway 网关每次启动时使用的是同一个 工作区（并记住：远程模式使用的是 **Gateway 网关主机的** - 工作区，而不是你本地笔记本电脑上的工作区）。 + 工作区，而不是你本地笔记本的工作区）。 - 提示：如果你想要持久的行为或偏好，请让机器人**把它写入 + 提示：如果你想要持久化某个行为或偏好，请让机器人**将其写入 AGENTS.md 或 MEMORY.md**，而不是依赖聊天历史。 - 参见 [Agent 工作区](/zh-CN/concepts/agent-workspace) 和 [Memory](/zh-CN/concepts/memory)。 + 请参见 [Agent 工作区](/zh-CN/concepts/agent-workspace) 和 [Memory](/zh-CN/concepts/memory)。 - 将你的 **Agent 工作区** 放进**私有** git 仓库，并备份到某个 + 将你的 **Agent 工作区**放入**私有** git 仓库，并备份到某个 私有位置（例如 GitHub 私有仓库）。这会捕获记忆 + AGENTS/SOUL/USER - 文件，并让你稍后恢复助手的“思维”。 + 文件，并让你之后可以恢复助手的“心智”。 - 不要提交 `~/.openclaw` 下的任何内容（凭证、会话、令牌或加密密钥载荷）。 + **不要**提交 `~/.openclaw` 下的任何内容（凭证、会话、令牌或加密的密钥载荷）。 如果你需要完整恢复，请分别备份工作区和状态目录 - （见上面的迁移问题）。 + （请参见上面的迁移问题）。 文档：[Agent 工作区](/zh-CN/concepts/agent-workspace)。 - - 参见专用指南：[卸载](/zh-CN/install/uninstall)。 + + 请参见专门指南：[卸载](/zh-CN/install/uninstall)。 可以。工作区是**默认 cwd** 和记忆锚点，不是硬性沙箱。 - 相对路径会在工作区内解析，但除非启用沙箱隔离，绝对路径可以访问其他 + 相对路径会在工作区内解析，但除非启用了沙箱隔离，绝对路径可以访问其他 主机位置。如果你需要隔离，请使用 - [`agents.defaults.sandbox`](/zh-CN/gateway/sandboxing) 或每智能体的沙箱设置。如果你 - 希望某个仓库成为默认工作目录，请将该智能体的 - `workspace` 指向仓库根目录。OpenClaw 仓库只是源代码；除非你有意让 - 智能体在其中工作，否则请保持工作区独立。 + [`agents.defaults.sandbox`](/zh-CN/gateway/sandboxing) 或按智能体配置沙箱设置。如果你 + 想让某个仓库成为默认工作目录，请将该智能体的 + `workspace` 指向仓库根目录。OpenClaw 仓库只是源代码；除非你有意让智能体在其中工作， + 否则请保持工作区独立。 示例（将仓库作为默认 cwd）： @@ -647,15 +636,15 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - 会话状态由 **Gateway 网关主机**拥有。如果你处于远程模式，你关心的会话存储在远程机器上，而不是你的本地笔记本电脑上。参见 [会话管理](/zh-CN/concepts/session)。 + 会话状态由 **Gateway 网关主机**拥有。如果你处于远程模式，你关心的会话存储位于远程机器上，而不是你的本地笔记本上。请参见[会话管理](/zh-CN/concepts/session)。 ## 配置基础 - - OpenClaw 会从 `$OPENCLAW_CONFIG_PATH` 读取可选的 **JSON5** 配置（默认：`~/.openclaw/openclaw.json`）： + + OpenClaw 从 `$OPENCLAW_CONFIG_PATH` 读取可选的 **JSON5** 配置（默认：`~/.openclaw/openclaw.json`）： ``` $OPENCLAW_CONFIG_PATH @@ -666,10 +655,10 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - 非 loopback 绑定**需要有效的 Gateway 网关鉴权路径**。实际含义是： + 非 loopback 绑定**需要有效的 Gateway 网关身份验证路径**。实际上这意味着： - - 共享密钥鉴权：令牌或密码 - - `gateway.auth.mode: "trusted-proxy"` 位于正确配置的身份感知反向代理之后 + - shared-secret auth：令牌或密码 + - 位于正确配置的身份感知反向代理之后的 `gateway.auth.mode: "trusted-proxy"` ```json5 { @@ -685,26 +674,26 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, 注意： - - `gateway.remote.token` / `.password` 本身**不会**启用本地 Gateway 网关鉴权。 - - 只有当 `gateway.auth.*` 未设置时，本地调用路径才可以将 `gateway.remote.*` 用作回退。 - - 对于密码鉴权，请改为设置 `gateway.auth.mode: "password"` 加 `gateway.auth.password`（或 `OPENCLAW_GATEWAY_PASSWORD`）。 - - 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但无法解析，解析会以关闭方式失败（不会用远程回退掩盖）。 - - 共享密钥 Control UI 设置通过 `connect.params.auth.token` 或 `connect.params.auth.password` 进行鉴权（存储在应用/UI 设置中）。带身份的模式（例如 Tailscale Serve 或 `trusted-proxy`）则使用请求头。避免将共享密钥放入 URL。 - - 使用 `gateway.auth.mode: "trusted-proxy"` 时，同主机 loopback 反向代理需要显式设置 `gateway.auth.trustedProxy.allowLoopback = true`，并在 `gateway.trustedProxies` 中加入 loopback 条目。 + - `gateway.remote.token` / `.password` 本身**不会**启用本地 Gateway 网关身份验证。 + - 仅当 `gateway.auth.*` 未设置时，本地调用路径才可以将 `gateway.remote.*` 用作兜底。 + - 对于密码身份验证，请改为设置 `gateway.auth.mode: "password"` 加 `gateway.auth.password`（或 `OPENCLAW_GATEWAY_PASSWORD`）。 + - 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置且未解析，解析会失败关闭（不会被远程兜底掩盖）。 + - Shared-secret Control UI 设置通过 `connect.params.auth.token` 或 `connect.params.auth.password`（存储在应用/UI 设置中）进行身份验证。Tailscale Serve 或 `trusted-proxy` 等携带身份的模式改用请求头。避免将 shared secrets 放在 URL 中。 + - 使用 `gateway.auth.mode: "trusted-proxy"` 时，同主机 loopback 反向代理需要显式设置 `gateway.auth.trustedProxy.allowLoopback = true`，并在 `gateway.trustedProxies` 中添加 loopback 条目。 - OpenClaw 默认强制执行 Gateway 网关鉴权，包括 loopback。在普通默认路径中，这意味着令牌鉴权：如果没有配置显式鉴权路径，Gateway 网关启动会解析为令牌模式并自动生成一个令牌，将其保存到 `gateway.auth.token`，因此**本地 WS 客户端必须鉴权**。这会阻止其他本地进程调用 Gateway 网关。 + OpenClaw 默认强制执行 Gateway 网关身份验证，包括 loopback。在普通默认路径中，这意味着令牌身份验证：如果没有配置显式身份验证路径，Gateway 网关启动会解析为令牌模式并自动生成一个令牌，保存到 `gateway.auth.token`，因此**本地 WS 客户端必须进行身份验证**。这会阻止其他本地进程调用 Gateway 网关。 - 如果你更喜欢其他鉴权路径，可以显式选择密码模式（或者，对于身份感知反向代理，选择 `trusted-proxy`）。如果你**确实**想开放 loopback，请在配置中显式设置 `gateway.auth.mode: "none"`。Doctor 随时可以为你生成令牌：`openclaw doctor --generate-gateway-token`。 + 如果你偏好不同的身份验证路径，可以显式选择密码模式（或者，对于身份感知反向代理，选择 `trusted-proxy`）。如果你**确实**想开放 loopback，请在配置中显式设置 `gateway.auth.mode: "none"`。Doctor 可随时为你生成令牌：`openclaw doctor --generate-gateway-token`。 - + Gateway 网关会监视配置并支持热重载： - - `gateway.reload.mode: "hybrid"`（默认）：热应用安全更改，对关键更改执行重启 + - `gateway.reload.mode: "hybrid"`（默认）：热应用安全变更，关键变更则重启 - 也支持 `hot`、`restart`、`off` @@ -729,16 +718,16 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - - `web_fetch` 无需 API 密钥即可工作。`web_search` 取决于你选择的 + + `web_fetch` 无需 API key 即可工作。`web_search` 取决于你选择的 提供商： - - Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Perplexity 和 Tavily 等 API 后备提供商需要各自正常的 API 密钥设置。 - - Ollama Web 搜索不需要密钥，但它会使用你配置的 Ollama 主机，并且需要 `ollama signin`。 - - DuckDuckGo 不需要密钥，但它是非官方的基于 HTML 的集成。 - - SearXNG 不需要密钥/可自托管；配置 `SEARXNG_BASE_URL` 或 `plugins.entries.searxng.config.webSearch.baseUrl`。 + - Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Perplexity 和 Tavily 等 API 支持的提供商需要按常规方式设置 API key。 + - Ollama Web 搜索不需要 key，但它使用你配置的 Ollama 主机，并且需要 `ollama signin`。 + - DuckDuckGo 不需要 key，但它是非官方的基于 HTML 的集成。 + - SearXNG 不需要 key/可自托管；配置 `SEARXNG_BASE_URL` 或 `plugins.entries.searxng.config.webSearch.baseUrl`。 - **推荐：** 运行 `openclaw configure --section web` 并选择一个提供商。 + **推荐：** 运行 `openclaw configure --section web` 并选择提供商。 环境变量替代项： - Brave：`BRAVE_API_KEY` @@ -781,68 +770,68 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, } ``` - provider 专属的 Web 搜索配置现在位于 `plugins.entries..config.webSearch.*` 下。 - 旧版 `tools.web.search.*` provider 路径仍会临时加载以保持兼容，但不应再用于新配置。 - Firecrawl Web 获取回退配置位于 `plugins.entries.firecrawl.config.webFetch.*` 下。 + 提供商特定的 Web 搜索配置现在位于 `plugins.entries..config.webSearch.*` 下。 + 旧版 `tools.web.search.*` 提供商路径仍会临时加载以保持兼容性，但不应在新配置中使用。 + Firecrawl Web 抓取回退配置位于 `plugins.entries.firecrawl.config.webFetch.*` 下。 注意： - 如果你使用允许列表，请添加 `web_search`/`web_fetch`/`x_search` 或 `group:web`。 - - `web_fetch` 默认启用（除非明确禁用）。 - - 如果省略 `tools.web.fetch.provider`，OpenClaw 会从可用凭证中自动检测第一个就绪的获取回退 provider。当前内置 provider 是 Firecrawl。 - - 守护进程会从 `~/.openclaw/.env`（或服务环境）读取环境变量。 + - `web_fetch` 默认启用（除非显式禁用）。 + - 如果省略 `tools.web.fetch.provider`，OpenClaw 会从可用凭证中自动检测第一个就绪的抓取回退提供商。目前内置提供商是 Firecrawl。 + - 守护进程从 `~/.openclaw/.env`（或服务环境）读取环境变量。 文档：[Web 工具](/zh-CN/tools/web)。 - + `config.apply` 会替换**整个配置**。如果你发送的是部分对象，其他所有内容 都会被移除。 - 当前的 OpenClaw 会防护很多意外覆盖： + 当前的 OpenClaw 会防止许多意外覆盖： - - OpenClaw 负责的配置写入会在写入前验证完整的变更后配置。 - - 无效或破坏性的 OpenClaw 负责写入会被拒绝，并保存为 `openclaw.json.rejected.*`。 - - 如果直接编辑导致启动或热重载中断，Gateway 网关会恢复最后已知可用的配置，并将被拒绝的文件保存为 `openclaw.json.clobbered.*`。 - - 恢复后，主 agent 会收到启动警告，避免它再次盲目写入有问题的配置。 + - OpenClaw 拥有的配置写入会在写入前验证完整的变更后配置。 + - 无效或破坏性的 OpenClaw 拥有写入会被拒绝，并保存为 `openclaw.json.rejected.*`。 + - 如果直接编辑破坏了启动或热重载，Gateway 网关会恢复最后已知可用配置，并将被拒绝的文件保存为 `openclaw.json.clobbered.*`。 + - 恢复后，主智能体会收到启动警告，以免再次盲目写入错误配置。 恢复： - - 检查 `openclaw logs --follow` 中是否有 `Config auto-restored from last-known-good`、`Config write rejected:` 或 `config reload restored last-known-good config`。 - - 查看活动配置旁边最新的 `openclaw.json.clobbered.*` 或 `openclaw.json.rejected.*`。 - - 如果恢复后的活动配置可用，就保留它，然后仅用 `openclaw config set` 或 `config.patch` 复制回预期键名。 + - 查看 `openclaw logs --follow` 中的 `Config auto-restored from last-known-good`、`Config write rejected:` 或 `config reload restored last-known-good config`。 + - 检查活动配置旁最新的 `openclaw.json.clobbered.*` 或 `openclaw.json.rejected.*`。 + - 如果恢复后的活动配置可用，请保留它，然后仅使用 `openclaw config set` 或 `config.patch` 复制回预期键名。 - 运行 `openclaw config validate` 和 `openclaw doctor`。 - 如果没有最后已知可用配置或被拒绝的载荷，请从备份恢复，或重新运行 `openclaw doctor` 并重新配置渠道/模型。 - 如果这不是预期行为，请提交 bug，并附上你最后已知的配置或任何备份。 - - 本地编码 agent 通常可以根据日志或历史记录重建可用配置。 + - 本地编码智能体通常可以从日志或历史记录中重建可用配置。 - 避免： + 避免方法： - - 小改动使用 `openclaw config set`。 - - 交互式编辑使用 `openclaw configure`。 - - 当你不确定确切路径或字段形状时，先使用 `config.schema.lookup`；它会返回一个浅层 schema 节点以及直接子项摘要，方便继续深入查看。 - - 部分 RPC 编辑使用 `config.patch`；仅将 `config.apply` 用于完整配置替换。 - - 如果你在 agent 运行中使用仅限所有者的 `gateway` 工具，它仍会拒绝写入 `tools.exec.ask` / `tools.exec.security`（包括会规范化到相同受保护执行路径的旧版 `tools.bash.*` 别名）。 + - 对小改动使用 `openclaw config set`。 + - 对交互式编辑使用 `openclaw configure`。 + - 当你不确定确切路径或字段形状时，先使用 `config.schema.lookup`；它会返回一个浅层 schema 节点以及用于下钻的直接子项摘要。 + - 对部分 RPC 编辑使用 `config.patch`；仅将 `config.apply` 用于完整配置替换。 + - 如果你在智能体运行中使用仅限所有者的 `gateway` 工具，它仍会拒绝写入 `tools.exec.ask` / `tools.exec.security`（包括会规范化到相同受保护 exec 路径的旧版 `tools.bash.*` 别名）。 文档：[配置](/zh-CN/cli/config)、[配置](/zh-CN/cli/configure)、[Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)、[Doctor](/zh-CN/gateway/doctor)。 - 常见模式是**一个 Gateway 网关**（例如 Raspberry Pi）加上**节点**和 **agent**： + 常见模式是**一个 Gateway 网关**（例如 Raspberry Pi）加上**节点**和**智能体**： - **Gateway 网关（中央）：**拥有渠道（Signal/WhatsApp）、路由和会话。 - - **节点（设备）：**Mac/iOS/Android 作为外设连接，并暴露本地工具（`system.run`、`canvas`、`camera`）。 - - **Agents（工作器）：**用于特殊角色的独立大脑/工作区（例如 “Hetzner 运维”、“个人数据”）。 - - **子 agent：**当你需要并行处理时，从主 agent 派生后台工作。 - - **TUI：**连接到 Gateway 网关并切换 agent/会话。 + - **节点（设备）：**Mac/iOS/Android 作为外设连接，并公开本地工具（`system.run`、`canvas`、`camera`）。 + - **智能体（工作器）：**为特殊角色提供独立的大脑/工作区（例如“Hetzner 运维”、“个人数据”）。 + - **子智能体：**当你需要并行处理时，从主智能体派生后台工作。 + - **TUI：**连接到 Gateway 网关并切换智能体/会话。 - 文档：[节点](/zh-CN/nodes)、[远程访问](/zh-CN/gateway/remote)、[多 Agent 路由](/zh-CN/concepts/multi-agent)、[子 agent](/zh-CN/tools/subagents)、[TUI](/zh-CN/web/tui)。 + 文档：[节点](/zh-CN/nodes)、[远程访问](/zh-CN/gateway/remote)、[多智能体路由](/zh-CN/concepts/multi-agent)、[子智能体](/zh-CN/tools/subagents)、[TUI](/zh-CN/web/tui)。 - + 可以。这是一个配置选项： ```json5 @@ -856,19 +845,19 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, } ``` - 默认值为 `false`（有头模式）。无头模式在某些网站上更容易触发反机器人检查。参见[浏览器](/zh-CN/tools/browser)。 + 默认值是 `false`（有界面）。无头模式更可能触发某些网站的反机器人检查。参见[浏览器](/zh-CN/tools/browser)。 - 无头模式使用**同一个 Chromium 引擎**，适用于大多数自动化（表单、点击、抓取、登录）。主要差异： + 无头模式使用**相同的 Chromium 引擎**，适用于大多数自动化场景（表单、点击、抓取、登录）。主要区别： - - 没有可见的浏览器窗口（如果需要视觉内容，请使用截图）。 - - 一些网站对无头模式下的自动化更严格（CAPTCHA、反机器人）。 + - 没有可见的浏览器窗口（如果需要视觉信息，请使用截图）。 + - 某些网站对无头模式下的自动化更严格（CAPTCHA、反机器人）。 例如，X/Twitter 经常会阻止无头会话。 将 `browser.executablePath` 设置为你的 Brave 二进制文件（或任何基于 Chromium 的浏览器），然后重启 Gateway 网关。 - 完整配置示例见[浏览器](/zh-CN/tools/browser#use-brave-or-another-chromium-based-browser)。 + 在[浏览器](/zh-CN/tools/browser#use-brave-or-another-chromium-based-browser)中查看完整配置示例。 @@ -876,27 +865,27 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - Telegram 消息由 **Gateway 网关**处理。Gateway 网关运行 agent，并且 - 仅在需要节点工具时才通过 **Gateway WebSocket** 调用节点： + Telegram 消息由 **Gateway 网关**处理。Gateway 网关运行智能体，并且 + 只有在需要节点工具时，才会通过 **Gateway WebSocket** 调用节点： - Telegram → Gateway 网关 → Agent → `node.*` → 节点 → Gateway 网关 → Telegram + Telegram → Gateway 网关 → 智能体 → `node.*` → 节点 → Gateway 网关 → Telegram - 节点看不到入站 provider 流量；它们只接收节点 RPC 调用。 + 节点不会看到入站提供商流量；它们只接收节点 RPC 调用。 - + 简短回答：**将你的电脑配对为节点**。Gateway 网关在其他地方运行，但它可以 - 通过 Gateway WebSocket 调用你本地机器上的 `node.*` 工具（屏幕、摄像头、系统）。 + 通过 Gateway WebSocket 在你的本地机器上调用 `node.*` 工具（屏幕、摄像头、系统）。 典型设置： - 1. 在始终在线的主机（VPS/家用服务器）上运行 Gateway 网关。 + 1. 在始终在线的主机（VPS/家庭服务器）上运行 Gateway 网关。 2. 将 Gateway 网关主机和你的电脑放在同一个 tailnet 中。 3. 确保 Gateway WS 可访问（tailnet 绑定或 SSH 隧道）。 - 4. 在本地打开 macOS 应用，并以**通过 SSH 远程**模式（或直接 tailnet） - 连接，这样它就能注册为节点。 - 5. 在 Gateway 网关上批准节点： + 4. 在本地打开 macOS 应用，并使用**通过 SSH 远程**模式（或直接 tailnet） + 连接，以便它注册为节点。 + 5. 在 Gateway 网关上批准该节点： ```bash openclaw devices list @@ -905,14 +894,14 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, 不需要单独的 TCP 桥接；节点通过 Gateway WebSocket 连接。 - 安全提醒：配对 macOS 节点会允许在该机器上执行 `system.run`。只 - 配对你信任的设备，并阅读[安全](/zh-CN/gateway/security)。 + 安全提醒：配对 macOS 节点允许在该机器上执行 `system.run`。只 + 配对你信任的设备，并查看[安全](/zh-CN/gateway/security)。 文档：[节点](/zh-CN/nodes)、[Gateway 网关协议](/zh-CN/gateway/protocol)、[macOS 远程模式](/zh-CN/platforms/mac/remote)、[安全](/zh-CN/gateway/security)。 - + 检查基础项： - Gateway 网关正在运行：`openclaw gateway status` @@ -922,82 +911,83 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, 然后验证认证和路由： - 如果你使用 Tailscale Serve，请确保 `gateway.auth.allowTailscale` 设置正确。 - - 如果你通过 SSH 隧道连接，请确认本地隧道已启动，并指向正确端口。 + - 如果你通过 SSH 隧道连接，请确认本地隧道已启动并指向正确端口。 - 确认你的允许列表（私信或群组）包含你的账号。 文档：[Tailscale](/zh-CN/gateway/tailscale)、[远程访问](/zh-CN/gateway/remote)、[渠道](/zh-CN/channels)。 - + 可以。没有内置的“机器人到机器人”桥接，但你可以用几种 - 可靠方式把它们连接起来： + 可靠方式连接起来： **最简单：**使用两个机器人都能访问的普通聊天渠道（Telegram/Slack/WhatsApp）。 - 让机器人 A 向机器人 B 发送消息，然后让机器人 B 像平常一样回复。 + 让机器人 A 向机器人 B 发送消息，然后让机器人 B 像往常一样回复。 - **CLI 桥接（通用）：**运行一个脚本，用 - `openclaw agent --message ... --deliver` 调用另一个 Gateway 网关，目标是另一个机器人 - 监听的聊天。如果某个机器人在远程 VPS 上，请通过 SSH/Tailscale 将你的 CLI 指向该远程 Gateway 网关 + **CLI 桥接（通用）：**运行一个脚本，使用 + `openclaw agent --message ... --deliver` 调用另一个 Gateway 网关，并以另一个机器人 + 监听的聊天为目标。如果一个机器人在远程 VPS 上，请通过 SSH/Tailscale 将你的 CLI 指向该远程 Gateway 网关 （参见[远程访问](/zh-CN/gateway/remote)）。 - 示例模式（在可以访问目标 Gateway 网关的机器上运行）： + 示例模式（从可以访问目标 Gateway 网关的机器运行）： ```bash openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to ``` - 提示：添加防护，避免两个机器人无限循环（仅提及、渠道 - 允许列表，或“不要回复机器人消息”规则）。 + 提示：添加保护规则，避免两个机器人无限循环（仅在提及时回复、渠道 + 允许列表，或“不回复机器人消息”规则）。 - 文档：[远程访问](/zh-CN/gateway/remote)、[Agent CLI](/zh-CN/cli/agent)、[Agent 发送](/zh-CN/tools/agent-send)。 + 文档：[远程访问](/zh-CN/gateway/remote)、[智能体 CLI](/zh-CN/cli/agent)、[智能体发送](/zh-CN/tools/agent-send)。 - - 不需要。一个 Gateway 网关可以托管多个 agent，每个 agent 都有自己的工作区、模型默认值 - 和路由。这是常规设置，并且比每个 agent 运行一个 VPS 便宜、简单得多。 + + 不需要。一个 Gateway 网关可以托管多个智能体，每个智能体都有自己的工作区、模型默认值 + 和路由。这是常规设置，比每个智能体运行一个 VPS 便宜且简单得多。 - 只有在需要强隔离（安全边界）或差异很大且不想共享的配置时，才使用单独的 VPS。否则，保留一个 Gateway 网关并 - 使用多个 agent 或子 agent。 + 只有在你需要强隔离（安全边界）或非常不同且不想共享的 + 配置时，才使用单独的 VPS。否则，保留一个 Gateway 网关并 + 使用多个智能体或子智能体。 - - 有，节点是从远程 Gateway 网关访问你笔记本的一等方式，而且它们 - 解锁的不只是 shell 访问。Gateway 网关在 macOS/Linux（Windows 通过 WSL2）上运行，并且 - 很轻量（小型 VPS 或 Raspberry Pi 级别的机器就可以；4 GB RAM 足够），所以常见 + + 有。节点是从远程 Gateway 网关访问你的笔记本的一等方式，并且 + 解锁的不只是 shell 访问。Gateway 网关运行在 macOS/Linux（Windows 通过 WSL2）上，并且 + 很轻量（小型 VPS 或 Raspberry Pi 级别的机器即可；4 GB RAM 足够），因此常见 设置是一个始终在线的主机加上作为节点的笔记本。 - **不需要入站 SSH。**节点主动连接到 Gateway WebSocket，并使用设备配对。 - - **更安全的执行控制。**`system.run` 受该笔记本上的节点允许列表/批准控制。 - - **更多设备工具。**节点除了 `system.run` 之外，还暴露 `canvas`、`camera` 和 `screen`。 - - **本地浏览器自动化。**将 Gateway 网关保留在 VPS 上，但通过笔记本上的节点主机在本地运行 Chrome，或通过 Chrome MCP 连接到主机上的本地 Chrome。 + - **更安全的执行控制。**`system.run` 由该笔记本上的节点允许列表/批准机制控制。 + - **更多设备工具。**节点除了 `system.run` 之外，还公开 `canvas`、`camera` 和 `screen`。 + - **本地浏览器自动化。**将 Gateway 网关保留在 VPS 上，但通过笔记本上的节点主机在本地运行 Chrome，或通过 Chrome MCP 附加到主机上的本地 Chrome。 - SSH 适合临时 shell 访问，但节点更适合持续的 agent 工作流和 - 设备自动化。 + SSH 适合临时 shell 访问，但对于持续的智能体工作流和 + 设备自动化，节点更简单。 文档：[节点](/zh-CN/nodes)、[节点 CLI](/zh-CN/cli/nodes)、[浏览器](/zh-CN/tools/browser)。 - 不会。除非你有意运行隔离的配置档案（参见[多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)），否则每台主机只应运行**一个 Gateway 网关**。节点是连接到 - Gateway 网关的外设（iOS/Android 节点，或 macOS 菜单栏应用中的“节点模式”）。对于无头节点 - 主机和 CLI 控制，参见[节点主机 CLI](/zh-CN/cli/node)。 + 不会。除非你有意运行隔离的配置文件（参见[多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)），否则每台主机只应运行**一个 Gateway 网关**。节点是连接 + 到 Gateway 网关的外设（iOS/Android 节点，或菜单栏应用中的 macOS“节点模式”）。关于无头节点 + 主机和 CLI 控制，请参见[节点主机 CLI](/zh-CN/cli/node)。 对 `gateway`、`discovery` 和 `canvasHost` 的更改需要完整重启。 - + 有。 - `config.schema.lookup`：在写入前检查一个配置子树，包括其浅层 schema 节点、匹配的 UI 提示和直接子项摘要 - `config.get`：获取当前快照 + 哈希 - - `config.patch`：安全的部分更新（大多数 RPC 编辑的首选）；可行时热重载，必要时重启 - - `config.apply`：验证并替换完整配置；可行时热重载，必要时重启 - - 仅限所有者的 `gateway` 运行时工具仍会拒绝重写 `tools.exec.ask` / `tools.exec.security`；旧版 `tools.bash.*` 别名会规范化到相同的受保护执行路径 + - `config.patch`：安全的部分更新（大多数 RPC 编辑的首选）；尽可能热重载，必要时重启 + - `config.apply`：验证 + 替换完整配置；尽可能热重载，必要时重启 + - 仅限所有者的 `gateway` 运行时工具仍会拒绝重写 `tools.exec.ask` / `tools.exec.security`；旧版 `tools.bash.*` 别名会规范化到相同的受保护 exec 路径 @@ -1014,7 +1004,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - 最小步骤： + 最少步骤： 1. **在 VPS 上安装并登录** @@ -1029,27 +1019,27 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - 在 Tailscale 管理控制台中启用 MagicDNS，让 VPS 拥有稳定名称。 4. **使用 tailnet 主机名** - SSH：`ssh user@your-vps.tailnet-xxxx.ts.net` - - Gateway 网关 WS：`ws://your-vps.tailnet-xxxx.ts.net:18789` + - Gateway WS：`ws://your-vps.tailnet-xxxx.ts.net:18789` - 如果你想在不使用 SSH 的情况下访问控制界面，请在 VPS 上使用 Tailscale Serve： + 如果你想在不使用 SSH 的情况下访问 Control UI，请在 VPS 上使用 Tailscale Serve： ```bash openclaw gateway --tailscale serve ``` - 这会让 Gateway 网关绑定到 loopback，并通过 Tailscale 暴露 HTTPS。请参阅 [Tailscale](/zh-CN/gateway/tailscale)。 + 这会让 Gateway 网关绑定到 loopback，并通过 Tailscale 暴露 HTTPS。参见 [Tailscale](/zh-CN/gateway/tailscale)。 - Serve 会暴露 **Gateway 网关控制界面 + WS**。节点通过同一个 Gateway 网关 WS 端点连接。 + Serve 会暴露 **Gateway 网关 Control UI + WS**。节点通过同一个 Gateway WS 端点连接。 推荐设置： 1. **确保 VPS + Mac 位于同一个 tailnet**。 2. **在远程模式下使用 macOS 应用**（SSH 目标可以是 tailnet 主机名）。 该应用会隧道转发 Gateway 网关端口，并作为节点连接。 - 3. **在 Gateway 网关上批准该节点**： + 3. **在 Gateway 网关上批准节点**： ```bash openclaw devices list @@ -1060,9 +1050,9 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - - 如果你只需要第二台笔记本电脑上的**本地工具**（屏幕/摄像头/执行），请将其添加为 - **节点**。这样可以保持单个 Gateway 网关，并避免重复配置。本地节点工具 + + 如果你只需要第二台笔记本上的**本地工具**（屏幕/摄像头/执行），请将它添加为 + **节点**。这样可以保留单个 Gateway 网关，并避免重复配置。本地节点工具 目前仅支持 macOS，但我们计划将其扩展到其他操作系统。 只有在需要**强隔离**或两个完全独立的机器人时，才安装第二个 Gateway 网关。 @@ -1076,14 +1066,14 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - OpenClaw 会读取父进程（shell、launchd/systemd、CI 等）的环境变量，并额外加载： + OpenClaw 会从父进程（shell、launchd/systemd、CI 等）读取环境变量，并额外加载： - 当前工作目录中的 `.env` - 来自 `~/.openclaw/.env` 的全局备用 `.env`（也就是 `$OPENCLAW_STATE_DIR/.env`） - 两个 `.env` 文件都不会覆盖已有的环境变量。 + 两个 `.env` 文件都不会覆盖现有环境变量。 - 你也可以在配置中定义内联环境变量（仅在进程环境中缺失时应用）： + 你也可以在配置中定义内联环境变量（仅在进程环境变量缺失时应用）： ```json5 { @@ -1094,15 +1084,15 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, } ``` - 完整的优先级和来源请参阅 [/environment](/zh-CN/help/environment)。 + 完整优先级和来源请参见 [/environment](/zh-CN/help/environment)。 - + 两种常见修复方式： - 1. 将缺失的键放入 `~/.openclaw/.env`，这样即使服务没有继承你的 shell 环境也能读取。 - 2. 启用 shell 导入（可选便利功能）： + 1. 将缺失的键放入 `~/.openclaw/.env`，这样即使服务未继承你的 shell 环境变量，也能读取它们。 + 2. 启用 shell 导入（可选的便捷功能）： ```json5 { @@ -1115,18 +1105,18 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, } ``` - 这会运行你的登录 shell，并且只导入缺失的预期键名（绝不覆盖）。等价的环境变量： + 这会运行你的登录 shell，并仅导入缺失的预期键名（绝不覆盖）。对应的环境变量： `OPENCLAW_LOAD_SHELL_ENV=1`、`OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`。 - - `openclaw models status` 报告的是是否启用了 **shell 环境导入**。“Shell env: off” + + `openclaw models status` 报告的是是否启用了 **shell 环境变量导入**。“Shell env: off” **不**表示你的环境变量缺失，它只表示 OpenClaw 不会自动加载 你的登录 shell。 - 如果 Gateway 网关作为服务运行（launchd/systemd），它不会继承你的 shell - 环境。可以通过以下任一方式修复： + 如果 Gateway 网关作为服务（launchd/systemd）运行，它不会继承你的 shell + 环境变量。任选以下一种方式修复： 1. 将令牌放入 `~/.openclaw/.env`： @@ -1135,7 +1125,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, ``` 2. 或启用 shell 导入（`env.shellEnv.enabled: true`）。 - 3. 或将其添加到你的配置 `env` 块中（仅在缺失时应用）。 + 3. 或将它添加到你的配置 `env` 块（仅在缺失时应用）。 然后重启 Gateway 网关并重新检查： @@ -1143,8 +1133,8 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, openclaw models status ``` - Copilot 令牌会从 `COPILOT_GITHUB_TOKEN`（以及 `GH_TOKEN` / `GITHUB_TOKEN`）读取。 - 请参阅 [/concepts/model-providers](/zh-CN/concepts/model-providers) 和 [/environment](/zh-CN/help/environment)。 + Copilot 令牌从 `COPILOT_GITHUB_TOKEN` 读取（也支持 `GH_TOKEN` / `GITHUB_TOKEN`）。 + 参见 [/concepts/model-providers](/zh-CN/concepts/model-providers) 和 [/environment](/zh-CN/help/environment)。 @@ -1152,15 +1142,15 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, ## 会话和多个聊天 - - 将 `/new` 或 `/reset` 作为独立消息发送。请参阅[会话管理](/zh-CN/concepts/session)。 + + 将 `/new` 或 `/reset` 作为独立消息发送。参见[会话管理](/zh-CN/concepts/session)。 - 会话可以在 `session.idleMinutes` 后过期，但这**默认禁用**（默认值为 **0**）。 - 将其设置为正值即可启用空闲过期。启用后，空闲期之后的**下一条** + 会话可以在 `session.idleMinutes` 之后过期，但这**默认禁用**（默认值为 **0**）。 + 将它设为正值即可启用空闲过期。启用后，空闲期之后的**下一条** 消息会为该聊天键启动一个新的会话 ID。 - 这不会删除转录记录，只是启动一个新会话。 + 这不会删除转录记录，只会开始一个新会话。 ```json5 { @@ -1172,41 +1162,40 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - - 可以，通过**多智能体路由**和**子智能体**实现。你可以创建一个协调者 - 智能体，以及几个拥有各自工作区和模型的工作智能体。 + + 可以，通过**多智能体路由**和**子智能体**实现。你可以创建一个协调 + 智能体，以及多个拥有各自工作区和模型的工作智能体。 - 不过，这最好看作一个**有趣的实验**。它会消耗大量 token，且通常 - 不如使用一个带有独立会话的机器人高效。我们设想的典型模型是： - 一个你与之对话的机器人，并用不同会话处理并行工作。该 - 机器人也可以在需要时生成子智能体。 + 不过，这最好被视为一个**有趣的实验**。它会消耗大量 token，并且通常 + 不如使用一个带独立会话的机器人高效。我们设想的典型模型是一个你与之对话的 + 机器人，并为并行工作使用不同会话。这个机器人也可以在需要时生成子智能体。 文档：[多智能体路由](/zh-CN/concepts/multi-agent)、[子智能体](/zh-CN/tools/subagents)、[智能体 CLI](/zh-CN/cli/agents)。 - + 会话上下文受模型窗口限制。长聊天、大型工具输出或大量 文件都可能触发压缩或截断。 有帮助的做法： - - 让机器人总结当前状态并写入文件。 + - 要求机器人总结当前状态并写入文件。 - 在长任务前使用 `/compact`，切换主题时使用 `/new`。 - - 将重要上下文保存在工作区，并让机器人读回。 + - 将重要上下文保存在工作区中，并要求机器人读回。 - 对长时间或并行工作使用子智能体，让主聊天保持更小。 - 如果经常发生这种情况，请选择上下文窗口更大的模型。 - + 使用 reset 命令： ```bash openclaw reset ``` - 非交互式完全重置： + 非交互式完整重置： ```bash openclaw reset --scope full --yes --non-interactive @@ -1220,50 +1209,50 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, 注意： - - 如果新手引导发现已有配置，也会提供**重置**。请参阅[新手引导（CLI）](/zh-CN/start/wizard)。 - - 如果你使用了配置文件（`--profile` / `OPENCLAW_PROFILE`），请重置每个状态目录（默认是 `~/.openclaw-`）。 - - 开发重置：`openclaw gateway --dev --reset`（仅限开发；会清除开发配置 + 凭证 + 会话 + 工作区）。 + - 如果新手引导发现已有配置，也会提供**重置**。参见[新手引导（CLI）](/zh-CN/start/wizard)。 + - 如果你使用了配置档（`--profile` / `OPENCLAW_PROFILE`），请重置每个状态目录（默认是 `~/.openclaw-`）。 + - 开发重置：`openclaw gateway --dev --reset`（仅开发用；会清除开发配置 + 凭证 + 会话 + 工作区）。 - - 使用以下任一方式： + + 使用以下方式之一： - - **压缩**（保留对话，但总结较早的轮次）： + - **压缩**（保留对话，但总结较早轮次）： ``` /compact ``` - 或使用 `/compact ` 指导总结。 + 或使用 `/compact ` 指导摘要。 - - **重置**（为同一聊天键创建新的会话 ID）： + - **重置**（为同一个聊天键创建新的会话 ID）： ``` /new /reset ``` - 如果它持续发生： + 如果持续发生： - - 启用或调整**会话剪枝**（`agents.defaults.contextPruning`）以修剪旧工具输出。 + - 启用或调整**会话裁剪**（`agents.defaults.contextPruning`），以裁剪旧工具输出。 - 使用上下文窗口更大的模型。 - 文档：[压缩](/zh-CN/concepts/compaction)、[会话剪枝](/zh-CN/concepts/session-pruning)、[会话管理](/zh-CN/concepts/session)。 + 文档：[压缩](/zh-CN/concepts/compaction)、[会话裁剪](/zh-CN/concepts/session-pruning)、[会话管理](/zh-CN/concepts/session)。 - - 这是提供商验证错误：模型输出了缺少必需 - `input` 的 `tool_use` 块。这通常表示会话历史已过期或损坏（经常发生在长线程 + + 这是提供商验证错误：模型发出了一个没有必需 + `input` 的 `tool_use` 块。它通常表示会话历史已过时或损坏（常见于长线程 或工具/架构变更之后）。 - 修复：使用 `/new`（独立消息）启动新会话。 + 修复：使用 `/new`（独立消息）开始一个全新会话。 - - 心跳默认每 **30m** 运行一次（使用 OAuth 认证时为 **1h**）。可以调整或禁用： + + Heartbeat 默认每 **30m** 运行一次（使用 OAuth 认证时为 **1h**）。调整或禁用它们： ```json5 { @@ -1278,18 +1267,18 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, ``` 如果 `HEARTBEAT.md` 存在但实际上为空（只有空行和类似 - `# Heading` 的 Markdown 标题），OpenClaw 会跳过心跳运行以节省 API 调用。 - 如果文件缺失，心跳仍会运行，由模型决定要做什么。 + `# Heading` 的 markdown 标题），OpenClaw 会跳过 Heartbeat 运行以节省 API 调用。 + 如果该文件缺失，Heartbeat 仍会运行，并由模型决定做什么。 - 每个智能体的覆盖使用 `agents.list[].heartbeat`。文档：[心跳](/zh-CN/gateway/heartbeat)。 + 每个智能体的覆盖项使用 `agents.list[].heartbeat`。文档：[Heartbeat](/zh-CN/gateway/heartbeat)。 - 不需要。OpenClaw 在**你自己的账号**上运行，所以如果你在群组中，OpenClaw 就能看到它。 - 默认情况下，群组回复会被阻止，直到你允许发送者（`groupPolicy: "allowlist"`）。 + 不需要。OpenClaw 运行在**你自己的账号**上，所以如果你在群组中，OpenClaw 就能看到它。 + 默认情况下，在你允许发送者之前（`groupPolicy: "allowlist"`），群组回复会被阻止。 - 如果你只想让**你**能够触发群组回复： + 如果你只希望**你**能够触发群组回复： ```json5 { @@ -1305,7 +1294,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - 选项 1（最快）：跟踪日志并在群组中发送一条测试消息： + 选项 1（最快）：跟踪日志并在群组中发送测试消息： ```bash openclaw logs --follow --json @@ -1327,45 +1316,45 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, 两种常见原因： - - 提及门控已开启（默认）。你必须 @提及机器人（或匹配 `mentionPatterns`）。 - - 你配置了 `channels.whatsapp.groups`，但没有包含 `"*"`，且该群组未加入允许列表。 + - 提及门控已开启（默认）。你必须 @mention 机器人（或匹配 `mentionPatterns`）。 + - 你配置了 `channels.whatsapp.groups` 但没有配置 `"*"`，并且该群组未加入允许列表。 - 请参阅[群组](/zh-CN/channels/groups)和[群组消息](/zh-CN/channels/group-messages)。 + 参见[群组](/zh-CN/channels/groups)和[群组消息](/zh-CN/channels/group-messages)。 - - 默认情况下，直接聊天会折叠到主会话。群组/渠道有自己的会话键，Telegram 话题 / Discord 线程是独立会话。请参阅[群组](/zh-CN/channels/groups)和[群组消息](/zh-CN/channels/group-messages)。 + + 默认情况下，直接聊天会折叠到主会话。群组/渠道拥有自己的会话键，Telegram 话题 / Discord 线程是独立会话。参见[群组](/zh-CN/channels/groups)和[群组消息](/zh-CN/channels/group-messages)。 - 没有硬性限制。几十个（甚至几百个）都可以，但要注意： + 没有硬性限制。几十个（甚至几百个）都可以，但需要注意： - **磁盘增长：**会话 + 转录记录位于 `~/.openclaw/agents//sessions/` 下。 - **Token 成本：**更多智能体意味着更多并发模型使用。 - - **运维开销：**每个智能体的认证配置文件、工作区和渠道路由。 + - **运维开销：**每个智能体的认证配置档、工作区和渠道路由。 - 建议： + 提示： - - 每个智能体保留一个**活动**工作区（`agents.defaults.workspace`）。 - - 如果磁盘增长，请清理旧会话（删除 JSONL 或存储条目）。 - - 使用 `openclaw doctor` 查找零散工作区和配置文件不匹配。 + - 每个智能体保留一个**活跃**工作区（`agents.defaults.workspace`）。 + - 如果磁盘增长，请裁剪旧会话（删除 JSONL 或存储条目）。 + - 使用 `openclaw doctor` 查找零散工作区和配置档不匹配。 - - 可以。使用 **多智能体路由** 来运行多个隔离的智能体，并按 - 渠道/账号/对端路由入站消息。Slack 支持作为渠道，并且可以绑定到特定智能体。 + + 可以。使用 **多智能体路由** 运行多个隔离的智能体，并按 + 渠道/账号/对等方路由入站消息。Slack 支持作为渠道，并可绑定到特定智能体。 - 浏览器访问能力很强，但并不是“能做人类能做的一切”——反机器人、CAPTCHA 和 MFA - 仍然可能阻止自动化。要获得最可靠的浏览器控制，请在主机上使用本地 Chrome MCP， + 浏览器访问能力很强，但并不是“人类能做什么它就能做什么”——反机器人、验证码和 MFA + 仍可能阻止自动化。若要获得最可靠的浏览器控制，请在主机上使用本地 Chrome MCP， 或在实际运行浏览器的机器上使用 CDP。 最佳实践设置： - - 常驻运行的 Gateway 网关主机（VPS/Mac mini）。 + - 常驻 Gateway 网关主机（VPS/Mac mini）。 - 每个角色一个智能体（绑定）。 - - 绑定到这些智能体的 Slack 渠道。 + - Slack 渠道绑定到这些智能体。 - 需要时通过 Chrome MCP 或节点使用本地浏览器。 文档：[多智能体路由](/zh-CN/concepts/multi-agent)、[Slack](/zh-CN/channels/slack)、 @@ -1383,7 +1372,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - `gateway.port` 控制 WebSocket + HTTP（Control UI、钩子等）的单个复用端口。 + `gateway.port` 控制 WebSocket + HTTP（Control UI、钩子等）的单一复用端口。 优先级： @@ -1394,9 +1383,9 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - 因为“running”是**监督器**视角（launchd/systemd/schtasks）。连接探测是 CLI 实际连接到 Gateway 网关 WebSocket。 + 因为 “running” 是**监督器**视角（launchd/systemd/schtasks）。连接探测是 CLI 实际连接到 Gateway 网关 WebSocket。 - 使用 `openclaw gateway status` 并信任这些行： + 使用 `openclaw gateway status`，并信任这些行： - `Probe target:`（探测实际使用的 URL） - `Listening:`（端口上实际绑定的内容） @@ -1405,7 +1394,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - 你正在编辑一个配置文件，而服务正在使用另一个配置文件运行（通常是 `--profile` / `OPENCLAW_STATE_DIR` 不匹配）。 + 你正在编辑一个配置文件，而服务运行的是另一个配置文件（通常是 `--profile` / `OPENCLAW_STATE_DIR` 不匹配）。 修复： @@ -1413,7 +1402,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, openclaw gateway install --force ``` - 请从你希望服务使用的同一个 `--profile` / 环境中运行该命令。 + 请在你希望服务使用的同一 `--profile` / 环境下运行该命令。 @@ -1424,8 +1413,8 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - - 设置 `gateway.mode: "remote"` 并指向远程 WebSocket URL，可选择使用共享密钥远程凭据： + + 设置 `gateway.mode: "remote"` 并指向远程 WebSocket URL，也可以选择配置共享密钥远程凭证： ```json5 { @@ -1442,38 +1431,38 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, 注意： - - `openclaw gateway` 仅在 `gateway.mode` 为 `local` 时启动（或你传入覆盖标志）。 + - `openclaw gateway` 仅在 `gateway.mode` 为 `local` 时启动（或你传入覆盖标志时）。 - macOS 应用会监视配置文件，并在这些值变化时实时切换模式。 - - `gateway.remote.token` / `.password` 只是客户端侧的远程凭据；它们本身不会启用本地 Gateway 网关认证。 + - `gateway.remote.token` / `.password` 只是客户端侧远程凭证；它们本身不会启用本地 Gateway 网关认证。 - - 你的 Gateway 网关认证路径与 UI 的认证方法不匹配。 + + 你的 Gateway 网关认证路径与 UI 的认证方式不匹配。 事实（来自代码）： - - Control UI 会将令牌保存在当前浏览器标签页会话和所选 Gateway 网关 URL 的 `sessionStorage` 中，因此同一标签页刷新仍可继续工作，而不会恢复长期存在的 localStorage 令牌持久化。 - - 在 `AUTH_TOKEN_MISMATCH` 时，当 Gateway 网关返回重试提示（`canRetryWithDeviceToken=true`、`recommendedNextStep=retry_with_device_token`）时，受信任客户端可以使用缓存的设备令牌尝试一次有界重试。 - - 该缓存令牌重试现在会复用与设备令牌一起存储的缓存已批准作用域。显式 `deviceToken` / 显式 `scopes` 调用方仍会保留其请求的作用域集合，而不是继承缓存作用域。 - - 在该重试路径之外，连接认证优先级为：显式共享令牌/密码优先，其次是显式 `deviceToken`，然后是已存储设备令牌，最后是引导令牌。 + - Control UI 会把当前浏览器标签页会话和所选 Gateway 网关 URL 的令牌保存在 `sessionStorage` 中，因此同一标签页刷新仍可继续工作，而无需恢复长期存在的 localStorage 令牌持久化。 + - 在 `AUTH_TOKEN_MISMATCH` 时，当 Gateway 网关返回重试提示（`canRetryWithDeviceToken=true`、`recommendedNextStep=retry_with_device_token`）时，受信任客户端可以用缓存的设备令牌尝试一次有界重试。 + - 该缓存令牌重试现在会复用与设备令牌一起存储的缓存已批准作用域。显式 `deviceToken` / 显式 `scopes` 调用方仍会保留自己请求的作用域集合，而不是继承缓存作用域。 + - 在该重试路径之外，连接认证优先级是：显式共享令牌/密码优先，然后是显式 `deviceToken`，然后是已存储设备令牌，最后是引导令牌。 - 引导令牌作用域检查带有角色前缀。内置引导操作员允许列表只满足操作员请求；节点或其他非操作员角色仍需要其自身角色前缀下的作用域。 修复： - - 最快：`openclaw dashboard`（打印并复制仪表盘 URL，尝试打开；如果是无头环境则显示 SSH 提示）。 + - 最快：`openclaw dashboard`（打印并复制仪表板 URL，尝试打开；若为无头环境则显示 SSH 提示）。 - 如果你还没有令牌：`openclaw doctor --generate-gateway-token`。 - 如果是远程，先建隧道：`ssh -N -L 18789:127.0.0.1:18789 user@host`，然后打开 `http://127.0.0.1:18789/`。 - 共享密钥模式：设置 `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` 或 `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`，然后在 Control UI 设置中粘贴匹配的密钥。 - - Tailscale Serve 模式：确保 `gateway.auth.allowTailscale` 已启用，并且你打开的是 Serve URL，而不是绕过 Tailscale 身份标头的原始 loopback/tailnet URL。 - - 受信代理模式：确保你是通过已配置的身份感知代理访问，而不是原始 Gateway 网关 URL。同主机 loopback 代理还需要 `gateway.auth.trustedProxy.allowLoopback = true`。 - - 如果一次重试后仍然不匹配，请轮换/重新批准已配对设备令牌： + - Tailscale Serve 模式：确保已启用 `gateway.auth.allowTailscale`，并且你打开的是 Serve URL，而不是会绕过 Tailscale 身份标头的原始 loopback/tailnet URL。 + - 受信任代理模式：确保你是通过已配置的身份感知代理访问，而不是原始 Gateway 网关 URL。同主机 loopback 代理还需要 `gateway.auth.trustedProxy.allowLoopback = true`。 + - 如果一次重试后仍不匹配，请轮换/重新批准已配对设备令牌： - `openclaw devices list` - `openclaw devices rotate --device --role operator` - - 如果该轮换调用显示被拒绝，请检查两件事： - - 已配对设备会话只能轮换它们**自己的**设备，除非它们还拥有 `operator.admin` - - 显式 `--scope` 值不能超过调用方当前的操作员作用域 - - 仍然卡住？运行 `openclaw status --all` 并按照[故障排除](/zh-CN/gateway/troubleshooting)操作。认证详情见[仪表盘](/zh-CN/web/dashboard)。 + - 如果该轮换调用显示被拒绝，请检查两点： + - 已配对设备会话只能轮换其**自己的**设备，除非它们还具有 `operator.admin` + - 显式 `--scope` 值不能超过调用方当前操作员作用域 + - 仍然卡住？运行 `openclaw status --all` 并按照[故障排除](/zh-CN/gateway/troubleshooting)操作。认证详情请参阅[仪表板](/zh-CN/web/dashboard)。 @@ -1485,7 +1474,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - 在该主机上启动 Tailscale（使其拥有 100.x 地址），或 - 切换到 `gateway.bind: "loopback"` / `"lan"`。 - 注意：`tailnet` 是显式设置。`auto` 优先选择 loopback；当你想要仅限 tailnet 的绑定时，请使用 `gateway.bind: "tailnet"`。 + 注意：`tailnet` 是显式设置。`auto` 优先使用 loopback；当你需要仅 tailnet 绑定时，请使用 `gateway.bind: "tailnet"`。 @@ -1502,8 +1491,8 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, 快速设置（推荐）： - 每个实例使用 `openclaw --profile ...`（自动创建 `~/.openclaw-`）。 - - 在每个配置文件中设置唯一的 `gateway.port`（或为手动运行传入 `--port`）。 - - 安装每个配置文件专属服务：`openclaw --profile gateway install`。 + - 在每个配置文件配置中设置唯一的 `gateway.port`（或在手动运行时传入 `--port`）。 + - 安装每个配置文件对应的服务：`openclaw --profile gateway install`。 配置文件还会为服务名称添加后缀（`ai.openclaw.`；旧版 `com.openclaw.*`、`openclaw-gateway-.service`、`OpenClaw Gateway ()`）。 完整指南：[多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。 @@ -1512,8 +1501,8 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, Gateway 网关是一个 **WebSocket 服务器**，它期望第一条消息 - 是 `connect` 帧。如果收到任何其他内容，它会以 **代码 1008** - （策略违规）关闭连接。 + 是 `connect` 帧。如果收到其他任何内容，它会以 **代码 1008**（策略违规） + 关闭连接。 常见原因： @@ -1527,7 +1516,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, 2. 不要在普通浏览器标签页中打开 WS 端口。 3. 如果启用了认证，请在 `connect` 帧中包含令牌/密码。 - 如果你使用的是 CLI 或 TUI，URL 应如下所示： + 如果你使用 CLI 或 TUI，URL 应类似于： ``` openclaw tui --url ws://:18789 --token @@ -1550,7 +1539,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, 你可以通过 `logging.file` 设置稳定路径。文件日志级别由 `logging.level` 控制。控制台详细程度由 `--verbose` 和 `logging.consoleLevel` 控制。 - 最快的日志跟踪： + 最快查看日志尾部： ```bash openclaw logs --follow @@ -1562,7 +1551,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - Linux：`journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager` - Windows：`schtasks /Query /TN "OpenClaw Gateway ()" /V /FO LIST` - 更多内容见[故障排除](/zh-CN/gateway/troubleshooting)。 + 更多信息请参阅[故障排除](/zh-CN/gateway/troubleshooting)。 @@ -1574,14 +1563,14 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, openclaw gateway restart ``` - 如果你手动运行 Gateway 网关，`openclaw gateway --force` 可以收回端口。见 [Gateway 网关](/zh-CN/gateway)。 + 如果你手动运行 Gateway 网关，`openclaw gateway --force` 可以收回端口。请参阅 [Gateway 网关](/zh-CN/gateway)。 有**两种 Windows 安装模式**： - **1) WSL2（推荐）：** Gateway 网关在 Linux 内运行。 + **1) WSL2（推荐）：** Gateway 网关在 Linux 内部运行。 打开 PowerShell，进入 WSL，然后重启： @@ -1591,7 +1580,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, openclaw gateway restart ``` - 如果你从未安装服务，请在前台启动它： + 如果你从未安装服务，请在前台启动： ```bash openclaw gateway run @@ -1628,11 +1617,11 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, 常见原因： - - 模型认证未加载到 **Gateway 网关主机** 上（检查 `models status`）。 + - 模型认证未在 **Gateway 网关主机**上加载（检查 `models status`）。 - 渠道配对/允许列表阻止回复（检查渠道配置 + 日志）。 - - WebChat/Dashboard 打开时没有正确令牌。 + - WebChat/Dashboard 已打开但没有正确的令牌。 - 如果你是远程访问，请确认隧道/Tailscale 连接已启动，并且 + 如果你在远程环境，请确认隧道/Tailscale 连接已建立，并且 Gateway 网关 WebSocket 可访问。 文档：[渠道](/zh-CN/channels)、[故障排除](/zh-CN/gateway/troubleshooting)、[远程访问](/zh-CN/gateway/remote)。 @@ -1640,11 +1629,11 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - 这通常意味着 UI 失去了 WebSocket 连接。检查： + 这通常意味着 UI 丢失了 WebSocket 连接。检查： 1. Gateway 网关在运行吗？`openclaw gateway status` 2. Gateway 网关健康吗？`openclaw status` - 3. UI 是否有正确的令牌？`openclaw dashboard` + 3. UI 是否有正确的 token？`openclaw dashboard` 4. 如果是远程访问，隧道/Tailscale 链接是否已连通？ 然后跟踪日志： @@ -1653,12 +1642,12 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, openclaw logs --follow ``` - 文档：[控制台](/zh-CN/web/dashboard)、[远程访问](/zh-CN/gateway/remote)、[故障排除](/zh-CN/gateway/troubleshooting)。 + 文档：[控制面板](/zh-CN/web/dashboard)、[远程访问](/zh-CN/gateway/remote)、[故障排除](/zh-CN/gateway/troubleshooting)。 - - 从日志和渠道状态开始： + + 从日志和渠道 Status 开始： ```bash openclaw channels status @@ -1667,17 +1656,17 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, 然后匹配错误： - - `BOT_COMMANDS_TOO_MUCH`：Telegram 菜单条目过多。OpenClaw 已经会裁剪到 Telegram 限制并用更少命令重试，但仍然需要删掉一些菜单条目。减少插件/skill/自定义命令，或者如果你不需要菜单，则停用 `channels.telegram.commands.native`。 - - `TypeError: fetch failed`、`Network request for 'setMyCommands' failed!` 或类似网络错误：如果你在 VPS 上或位于代理后面，请确认允许出站 HTTPS，并且 DNS 可以解析 `api.telegram.org`。 + - `BOT_COMMANDS_TOO_MUCH`：Telegram 菜单条目过多。OpenClaw 已经会裁剪到 Telegram 限制并用更少命令重试，但仍有一些菜单条目需要删除。减少插件/skill/自定义命令，或者如果不需要菜单，请禁用 `channels.telegram.commands.native`。 + - `TypeError: fetch failed`、`Network request for 'setMyCommands' failed!` 或类似网络错误：如果你在 VPS 上或位于代理后面，请确认允许出站 HTTPS，并且 DNS 可解析 `api.telegram.org`。 - 如果 Gateway 网关是远程的，请确保你查看的是 Gateway 网关主机上的日志。 + 如果 Gateway 网关是远程的，请确保你正在查看 Gateway 网关主机上的日志。 文档：[Telegram](/zh-CN/channels/telegram)、[渠道故障排除](/zh-CN/channels/troubleshooting)。 - - 先确认 Gateway 网关可访问，并且智能体可以运行： + + 先确认 Gateway 网关可访问，且智能体可以运行： ```bash openclaw status @@ -1685,14 +1674,14 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, openclaw logs --follow ``` - 在 TUI 中，使用 `/status` 查看当前状态。如果你希望在聊天 + 在 TUI 中，使用 `/status` 查看当前状态。如果你期望在聊天 渠道中收到回复，请确保已启用投递（`/deliver on`）。 文档：[TUI](/zh-CN/web/tui)、[斜杠命令](/zh-CN/tools/slash-commands)。 - + 如果你安装了服务： ```bash @@ -1700,8 +1689,8 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, openclaw gateway start ``` - 这会停止/启动**受监督的服务**（macOS 上的 launchd，Linux 上的 systemd）。 - 当 Gateway 网关作为守护进程在后台运行时使用此方式。 + 这会停止/启动**受监管服务**（macOS 上的 launchd，Linux 上的 systemd）。 + 当 Gateway 网关作为守护进程在后台运行时使用它。 如果你是在前台运行，请用 Ctrl-C 停止，然后运行： @@ -1713,25 +1702,25 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - + - `openclaw gateway restart`：重启**后台服务**（launchd/systemd）。 - `openclaw gateway`：为当前终端会话在**前台**运行 Gateway 网关。 - 如果你安装了服务，请使用 gateway 命令。当你想要一次性的前台运行时， + 如果你安装了服务，请使用 Gateway 网关命令。当你想进行一次性的前台运行时， 使用 `openclaw gateway`。 - - 使用 `--verbose` 启动 Gateway 网关，以获取更多控制台详情。然后检查日志文件中的渠道认证、模型路由和 RPC 错误。 + + 使用 `--verbose` 启动 Gateway 网关，以获取更多控制台细节。然后检查日志文件中的渠道认证、模型路由和 RPC 错误。 ## 媒体和附件 - - 智能体发出的出站附件必须包含一行 `MEDIA:`（单独成行）。参见 [OpenClaw 助手设置](/zh-CN/start/openclaw)和[智能体发送](/zh-CN/tools/agent-send)。 + + 智能体发出的出站附件必须包含一行 `MEDIA:`（单独一行）。参见 [OpenClaw 助手设置](/zh-CN/start/openclaw)和[智能体发送](/zh-CN/tools/agent-send)。 CLI 发送： @@ -1741,12 +1730,12 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, 还要检查： - - 目标渠道支持出站媒体，并且没有被允许列表阻止。 - - 文件在提供商的大小限制内（图片会被调整到最大 2048px）。 - - `tools.fs.workspaceOnly=true` 会将本地路径发送限制在工作区、临时/媒体存储和通过沙箱验证的文件中。 - - `tools.fs.workspaceOnly=false` 允许 `MEDIA:` 发送智能体已可读取的主机本地文件，但仅限媒体和安全的文档类型（图片、音频、视频、PDF 和 Office 文档）。纯文本和疑似密钥的文件仍会被阻止。 + - 目标渠道支持出站媒体，且没有被 allowlist 阻止。 + - 文件在提供商的大小限制内（图像会调整到最大 2048px）。 + - `tools.fs.workspaceOnly=true` 会将本地路径发送限制在工作区、临时/媒体存储和通过沙箱验证的文件内。 + - `tools.fs.workspaceOnly=false` 允许 `MEDIA:` 发送智能体已经可以读取的主机本地文件，但仅限媒体和安全的文档类型（图像、音频、视频、PDF 和 Office 文档）。纯文本和类似密钥的文件仍会被阻止。 - 参见[图片](/zh-CN/nodes/images)。 + 参见[图像](/zh-CN/nodes/images)。 @@ -1755,44 +1744,45 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - 将入站私信视为不受信任的输入。默认设置旨在降低风险： + 将入站私信视为不可信输入。默认设置旨在降低风险： - - 支持私信的渠道默认行为是**配对**： + - 支持私信的渠道上的默认行为是**配对**： - 未知发送者会收到配对码；bot 不会处理他们的消息。 - 使用以下命令批准：`openclaw pairing approve --channel [--account ] ` - - 待处理请求上限为**每个渠道 3 个**；如果没有收到代码，请检查 `openclaw pairing list --channel [--account ]`。 - - 公开开放私信需要显式选择加入（`dmPolicy: "open"` 和允许列表 `"*"`）。 + - 待处理请求上限为**每个渠道 3 个**；如果未收到代码，请检查 `openclaw pairing list --channel [--account ]`。 + - 公开开放私信需要显式选择启用（`dmPolicy: "open"` 和 allowlist `"*"`）。 运行 `openclaw doctor` 以显示有风险的私信策略。 - - 不是。提示词注入关注的是**不受信任的内容**，而不只是哪些人可以给 bot 发私信。 - 如果你的助手读取外部内容（Web 搜索/抓取、浏览器页面、电子邮件、 - 文档、附件、粘贴的日志），这些内容可能包含试图劫持模型的指令。 - 即使**你是唯一发送者**，这也可能发生。 + + 不是。提示注入关注的是**不可信内容**，不只是哪些人能私信 bot。 + 如果你的助手读取外部内容（Web 搜索/抓取、浏览器页面、邮件、 + 文档、附件、粘贴的日志），这些内容可能包含试图 + 劫持模型的指令。即使**只有你一个发送者**，这也可能发生。 - 最大风险出现在启用工具时：模型可能被诱骗去泄露上下文或代表你调用工具。 - 通过以下方式降低影响范围： + 最大风险出现在启用工具时：模型可能被诱导代表你 + 外泄上下文或调用工具。通过以下方式降低影响范围： - - 使用只读或停用工具的“阅读器”智能体来总结不受信任的内容 + - 使用只读或禁用工具的“reader”智能体来总结不可信内容 - 对启用工具的智能体关闭 `web_search` / `web_fetch` / `browser` - - 也将解码后的文件/文档文本视为不受信任：OpenResponses - `input_file` 和媒体附件提取都会将提取出的文本包裹在 - 明确的外部内容边界标记中，而不是传递原始文件文本 - - 沙箱隔离和严格的工具允许列表 + - 同样将解码后的文件/文档文本视为不可信：OpenResponses + `input_file` 和媒体附件提取都会把提取的文本包裹在 + 显式外部内容边界标记中，而不是传递原始文件文本 + - 沙箱隔离和严格的工具 allowlist 详情：[安全](/zh-CN/gateway/security)。 - - 是的，对于大多数设置来说应当如此。用单独的账号和电话号码隔离 bot - 可以在出问题时降低影响范围。这也让你更容易轮换 - 凭证或撤销访问权限，而不影响你的个人账号。 + + 对大多数设置来说，是的。用单独账号和电话号码隔离 bot， + 可以在出现问题时降低影响范围。这也让你更容易轮换 + 凭证或撤销访问，而不影响你的个人账号。 - 从小范围开始。只给它实际需要的工具和账号访问权限，之后如有需要再扩展。 + 从小范围开始。只授予实际需要的工具和账号访问权限， + 如有需要之后再扩展。 文档：[安全](/zh-CN/gateway/security)、[配对](/zh-CN/channels/pairing)。 @@ -1801,8 +1791,8 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, 我们**不**建议让它完全自主处理你的个人消息。最安全的模式是： - - 将私信保持在**配对模式**或严格的允许列表中。 - - 如果你希望它代表你发送消息，请使用**单独的号码或账号**。 + - 将私信保持在**配对模式**或严格的 allowlist 中。 + - 如果你想让它代表你发送消息，请使用**单独号码或账号**。 - 让它起草，然后在**发送前批准**。 如果你想实验，请在专用账号上进行并保持隔离。参见 @@ -1810,16 +1800,16 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - - 可以，**前提是**该智能体只用于聊天且输入可信。更小的档位 - 更容易受到指令劫持，因此对于启用工具的智能体 - 或读取不受信任内容时应避免使用。如果必须使用更小的模型，请锁定 + + 可以，**前提是**智能体仅用于聊天，且输入可信。较小档位的模型 + 更容易受到指令劫持，因此不要将它们用于启用工具的智能体， + 或用于读取不可信内容。如果必须使用较小模型，请锁定 工具并在沙箱中运行。参见[安全](/zh-CN/gateway/security)。 - 配对码**只会**在未知发送者给 bot 发消息并且 - 已启用 `dmPolicy: "pairing"` 时发送。`/start` 本身不会生成代码。 + 只有当未知发送者给 bot 发送消息且启用了 + `dmPolicy: "pairing"` 时，才会发送配对码。`/start` 本身不会生成代码。 检查待处理请求： @@ -1827,12 +1817,12 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, openclaw pairing list telegram ``` - 如果你想立即访问，请将你的发送者 ID 加入允许列表，或为该账号设置 `dmPolicy: "open"`。 + 如果你想立即访问，请将你的发送者 ID 加入 allowlist，或为该账号设置 `dmPolicy: "open"`。 - 不会。默认 WhatsApp 私信策略是**配对**。未知发送者只会收到配对码，其消息**不会被处理**。OpenClaw 只回复它收到的聊天，或你显式触发的发送。 + 不会。默认 WhatsApp 私信策略是**配对**。未知发送者只会收到配对码，其消息**不会被处理**。OpenClaw 只会回复它收到的聊天，或回复你显式触发的发送。 使用以下命令批准配对： @@ -1846,19 +1836,18 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, openclaw pairing list whatsapp ``` - 向导电话号码提示：它用于设置你的**允许列表/所有者**，以便允许你自己的私信。它不会用于自动发送。如果你在个人 WhatsApp 号码上运行，请使用该号码并启用 `channels.whatsapp.selfChatMode`。 + 向导电话号码提示：它用于设置你的 **allowlist/owner**，以允许你自己的私信。它不会用于自动发送。如果你在个人 WhatsApp 号码上运行，请使用该号码并启用 `channels.whatsapp.selfChatMode`。 -## 聊天命令、中止任务，以及“它停不下来” +## 聊天命令、中止任务以及“它停不下来” - 大多数内部消息或工具消息只会在该会话启用 **verbose**、**trace** 或 **reasoning** - 时出现。 + 大多数内部或工具消息只会在该会话启用 **verbose**、**trace** 或 **reasoning** 时出现。 - 在你看到它的聊天中修复： + 在看到它的聊天中修复： ``` /verbose off @@ -1866,9 +1855,9 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, /reasoning off ``` - 如果仍然很吵，请检查 Control UI 中的会话设置，并将 verbose - 设为**继承**。还要确认你没有使用在配置中将 `verboseDefault` 设为 - `on` 的 bot 配置文件。 + 如果仍然很嘈杂，请检查 Control UI 中的会话设置，并将 verbose + 设置为**继承**。还要确认你没有使用配置中将 `verboseDefault` 设为 + `on` 的 bot profile。 文档：[思考和详细输出](/zh-CN/tools/thinking)、[安全](/zh-CN/gateway/security#reasoning-verbose-output-in-groups)。 @@ -1901,7 +1890,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, 这些是中止触发词（不是斜杠命令）。 - 对于后台进程（来自 exec 工具），你可以让智能体运行： + 对于后台进程（来自 exec 工具），你可以要求智能体运行： ``` process action:kill sessionId:XXX @@ -1909,15 +1898,15 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, 斜杠命令概览：参见[斜杠命令](/zh-CN/tools/slash-commands)。 - 大多数命令必须作为以 `/` 开头的**独立**消息发送，但少数快捷命令（例如 `/status`）也可由允许列表中的发送者内联使用。 + 大多数命令必须作为以 `/` 开头的**独立**消息发送，但少数快捷命令（如 `/status`）也可供 allowlist 中的发送者内联使用。 - - OpenClaw 默认阻止**跨提供商**消息。如果某个工具调用绑定到 - Telegram，除非你明确允许，否则它不会发送到 Discord。 + + OpenClaw 默认阻止**跨提供商**消息发送。如果工具调用绑定到 + Telegram，除非你显式允许，否则它不会发送到 Discord。 - 为智能体启用跨提供商消息： + 为智能体启用跨提供商消息发送： ```json5 { @@ -1936,16 +1925,16 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - - 队列模式控制新消息如何与正在进行的运行交互。使用 `/queue` 更改模式： + + 队列模式控制新消息如何与正在进行的 run 交互。使用 `/queue` 更改模式： - - `steer` - 新消息重定向当前任务 + - `steer` - 在当前 run 的下一个模型边界排队引导 - `followup` - 一次运行一条消息 - - `collect` - 批处理消息并一次性回复（默认） - - `steer-backlog` - 立即引导，然后处理积压消息 - - `interrupt` - 中止当前运行并重新开始 + - `collect` - 批量收集消息并一次回复 + - `steer-backlog` - 现在引导，然后处理积压 + - `interrupt` - 中止当前 run 并重新开始 - 你可以为 followup 模式添加类似 `debounce:2s cap:25 drop:summarize` 的选项。 + 默认模式是 `steer`。你可以为 followup 模式添加 `debounce:0.5s cap:25 drop:summarize` 等选项。参见[命令队列](/zh-CN/concepts/queue)。 @@ -1953,17 +1942,17 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, ## 其他 - - 在 OpenClaw 中，凭据和模型选择是分开的。设置 `ANTHROPIC_API_KEY`（或在认证配置文件中存储 Anthropic API 密钥）会启用身份验证，但实际的默认模型取决于你在 `agents.defaults.model.primary` 中配置的内容（例如 `anthropic/claude-sonnet-4-6` 或 `anthropic/claude-opus-4-6`）。如果你看到 `No credentials found for profile "anthropic:default"`，这表示 Gateway 网关在正在运行的智能体预期的 `auth-profiles.json` 中找不到 Anthropic 凭据。 + + 在 OpenClaw 中，凭证和模型选择是分开的。设置 `ANTHROPIC_API_KEY`（或在身份验证配置文件中存储 Anthropic API 密钥）会启用身份验证，但实际的默认模型是你在 `agents.defaults.model.primary` 中配置的任何模型（例如 `anthropic/claude-sonnet-4-6` 或 `anthropic/claude-opus-4-6`）。如果你看到 `No credentials found for profile "anthropic:default"`，这表示 Gateway 网关在正在运行的智能体预期的 `auth-profiles.json` 中找不到 Anthropic 凭证。 --- -仍然卡住？在 [Discord](https://discord.com/invite/clawd) 提问，或发起 [GitHub discussion](https://github.com/openclaw/openclaw/discussions)。 +仍然卡住？在 [Discord](https://discord.com/invite/clawd) 提问，或发起 [GitHub 讨论](https://github.com/openclaw/openclaw/discussions)。 ## 相关内容 -- [首次运行常见问题](/zh-CN/help/faq-first-run) — 安装、新手引导、凭证、订阅、早期故障 -- [Models 常见问题](/zh-CN/help/faq-models) — 模型选择、故障转移、认证配置文件 -- [故障排除](/zh-CN/help/troubleshooting) — 按症状优先的排查 +- [首次运行常见问题](/zh-CN/help/faq-first-run) — 安装、新手引导、身份验证、订阅、早期故障 +- [Models 常见问题](/zh-CN/help/faq-models) — 模型选择、故障转移、身份验证配置文件 +- [故障排除](/zh-CN/help/troubleshooting) — 按症状优先的分诊 diff --git a/docs/zh-CN/tools/slash-commands.md b/docs/zh-CN/tools/slash-commands.md index 66c8f0cd6..75a8371c7 100644 --- a/docs/zh-CN/tools/slash-commands.md +++ b/docs/zh-CN/tools/slash-commands.md @@ -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 聊天命令使用 `! `（`/bash ` 是别名）。 -当对话或线程绑定到 ACP 会话时，普通后续文本会路由到该 ACP harness。Gateway 网关管理命令仍然保持本地处理：`/acp ...` 始终会到达 OpenClaw ACP 命令处理器，并且只要该表面的命令处理已启用，`/status` 加 `/unfocus` 就会保持本地处理。 +当某个对话或线程绑定到 ACP 会话时，普通后续文本会路由到该 ACP harness。Gateway 网关管理命令仍然保持本地处理：`/acp ...` 始终到达 OpenClaw ACP 命令处理器，并且只要该界面启用了命令处理，`/status` 加 `/unfocus` 就保持本地处理。 有两个相关系统： @@ -27,16 +27,16 @@ x-i18n: `/think`、`/fast`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/exec`、`/model`、`/queue`。 - - 指令会在模型看到消息前从消息中移除。 - - 在普通聊天消息中（不是仅包含指令的消息），它们会被视为“内联提示”，并且**不会**持久化会话设置。 - - 在仅包含指令的消息中（消息只包含指令），它们会持久化到会话并回复确认。 - - 指令只会应用于**已授权发送者**。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则授权来自渠道允许列表/配对，以及 `commands.useAccessGroups`。未授权发送者的指令会被视为纯文本。 + - 指令会在模型看到消息之前从消息中移除。 + - 在普通聊天消息中（不是仅指令消息），它们会被视为“内联提示”，并且**不会**持久化会话设置。 + - 在仅指令消息中（消息只包含指令），它们会持久化到会话，并回复确认。 + - 指令只会应用于**已授权发送者**。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则授权来自渠道允许列表/配对以及 `commands.useAccessGroups`。未授权发送者的指令会被当作普通文本处理。 - 仅限允许列表/已授权发送者：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 + 仅限允许列表中/已授权的发送者：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 - 它们会立即运行，在模型看到消息前被移除，剩余文本会继续走正常流程。 + 它们会立即运行，在模型看到消息之前被移除，剩余文本会继续走正常流程。 @@ -69,19 +69,19 @@ x-i18n: ``` - 启用在聊天消息中解析 `/...`。在没有原生命令的表面（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams）上，即使你将其设置为 `false`，文本命令仍然可用。 + 启用在聊天消息中解析 `/...`。在没有原生命令的界面上（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams），即使你将此项设置为 `false`，文本命令仍然可用。 - 注册原生命令。自动：对 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 应用中管理，不会自动移除。 - 在支持时原生注册 **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"`）。 启用 `! ` 来运行主机 shell 命令（`/bash ` 是别名；需要 `tools.elevated` 允许列表）。 - 控制 bash 在切换到后台模式前等待多久（`0` 表示立即后台运行）。 + 控制 bash 在切换到后台模式之前等待多久（`0` 表示立即转入后台）。 启用 `/config`（读取/写入 `openclaw.json`）。 @@ -90,28 +90,28 @@ x-i18n: 启用 `/mcp`（读取/写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 配置）。 - 启用 `/plugins`（插件发现/Status，以及安装和启用/停用控制）。 + 启用 `/plugins`（插件发现/Status，以及安装 + 启用/禁用控件）。 启用 `/debug`（仅运行时覆盖）。 - 启用 `/restart` 以及 Gateway 网关重启工具操作。 + 启用 `/restart` 以及 gateway 重启工具操作。 - 为仅限所有者的命令/工具表面设置显式所有者允许列表。这是可以批准危险操作并运行 `/diagnostics`、`/export-trajectory` 和 `/config` 等命令的人类操作员账号。它独立于 `commands.allowFrom`，也独立于私信配对访问。 + 设置仅 owner 命令/工具界面的显式 owner 允许列表。这是可以批准危险操作并运行 `/diagnostics`、`/export-trajectory` 和 `/config` 等命令的人类操作员账户。它独立于 `commands.allowFrom` 和私信配对访问权限。 - 按渠道：让仅限所有者的命令在该表面上运行时需要**所有者身份**。当为 `true` 时，发送者必须匹配已解析的所有者候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生所有者元数据），或者在内部消息渠道上持有内部 `operator.admin` 作用域。渠道 `allowFrom` 中的通配符条目，或空的/未解析的所有者候选列表，**不足以**满足要求 —— 仅限所有者的命令会在该渠道上以封闭方式失败。如果你希望仅限所有者的命令只由 `ownerAllowFrom` 和标准命令允许列表约束，请保持此项关闭。 + 按渠道：让仅 owner 命令要求在该界面上以 **owner 身份**运行。当为 `true` 时，发送者必须匹配已解析的 owner 候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生 owner 元数据），或在内部消息渠道上持有内部 `operator.admin` 作用域。渠道 `allowFrom` 中的通配符条目，或为空/未解析的 owner 候选列表，**不足以**满足要求，仅 owner 命令会在该渠道上默认失败关闭。如果你希望仅 owner 命令只由 `ownerAllowFrom` 和标准命令允许列表进行门控，请保持关闭。 - 控制所有者 id 在系统提示中的显示方式。 + 控制 owner id 在系统提示中的显示方式。 - 可选地设置当 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。 + 可选设置在 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。 - 用于命令授权的按提供商允许列表。配置后，它是命令和指令的唯一授权来源（渠道允许列表/配对和 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；提供商特定键会覆盖它。 + 按提供商设置的命令授权允许列表。配置后，它就是命令和指令的唯一授权来源（渠道允许列表/配对以及 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；提供商专用键会覆盖它。 当未设置 `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 内置命令 - `/new [model]` 启动新会话；`/reset` 是重置别名。 - - `/reset soft [message]` 保留当前转录内容，丢弃复用的 CLI 后端会话 id，并在原位重新运行启动/系统提示加载。 + - `/reset soft [message]` 保留当前转录，丢弃复用的 CLI 后端会话 id，并就地重新运行启动/系统提示加载。 - `/compact [instructions]` 压缩会话上下文。参见[压缩](/zh-CN/concepts/compaction)。 - `/stop` 中止当前运行。 - `/session idle ` 和 `/session max-age ` 管理线程绑定过期时间。 - `/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`。 - - - `/think ` 设置思考级别。选项来自活动模型的提供商配置文件；常见级别包括 `off`、`minimal`、`low`、`medium` 和 `high`，自定义级别如 `xhigh`、`adaptive`、`max`，或二进制 `on` 仅在受支持时可用。别名：`/thinking`、`/t`。 + + - `/think ` 设置思考级别。选项来自活动模型的 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= security= ask= node=` 显示或设置 exec 默认值。 - `/model [name|#|status]` 显示或设置模型。 - - `/models [provider] [page] [limit=|size=|all]` 列出已配置/可凭证访问的提供商，或列出某个提供商的模型；添加 `all` 可浏览该提供商的完整目录。 - - `/queue ` 管理队列行为（`steer`、`interrupt`、`followup`、`collect`、`steer-backlog`），以及 `debounce:2s cap:25 drop:summarize` 等选项。 + - `/models [provider] [page] [limit=|size=|all]` 列出已配置/可用认证的提供商，或某个提供商的模型；添加 `all` 可浏览该提供商的完整目录。 + - `/queue ` 管理队列行为（`steer`、`followup`、`collect`、`steer-backlog`、`interrupt`）以及 `debounce:0.5s cap:25 drop:summarize` 等选项；`/queue default` 或 `/queue reset` 会清除会话覆盖。参见[命令队列](/zh-CN/concepts/queue)。 - `/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 ` 命令。参见[诊断导出](/zh-CN/gateway/diagnostics)。 - - `/crestodian ` 从所有者私信运行 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 ` 命令。参见 [Diagnostics Export](/zh-CN/gateway/diagnostics)。 + - `/crestodian ` 从 owner 私信运行 Crestodian 设置和修复助手。 - `/tasks` 列出当前会话的活动/近期后台任务。 - - `/context [list|detail|json]` 解释上下文如何组装。 + - `/context [list|detail|json]` 说明上下文如何组装。 - `/whoami` 显示你的发送者 id。别名：`/id`。 - - `/usage off|tokens|full|cost` 控制每条回复的用量页脚，或打印本地成本摘要。 + - `/usage off|tokens|full|cost` 控制每条回复的使用量页脚，或打印本地成本摘要。 - - `/skill [input]` 按名称运行一个 Skill。 + - `/skill [input]` 按名称运行 skill。 - `/allowlist [list|add|remove] ...` 管理允许列表条目。仅文本。 - `/approve ` 解决 exec 批准提示。 - - `/btw ` 提出一个旁路问题，而不改变未来会话上下文。参见 [BTW](/zh-CN/tools/btw)。 + - `/btw ` 提出旁支问题，而不改变未来会话上下文。参见 [BTW](/zh-CN/tools/btw)。 - - - `/subagents list|kill|log|info|send|steer|spawn` 管理当前会话的子智能体运行。 + + - `/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 ` 将当前 Discord 线程或 Telegram 话题/对话绑定到会话目标。 + - `/focus ` 将当前 Discord 线程或 Telegram 主题/对话绑定到会话目标。 - `/unfocus` 移除当前绑定。 - - `/agents` 列出当前会话的线程绑定智能体。 - - `/kill ` 中止一个或所有正在运行的子智能体。 - - `/steer ` 向正在运行的子智能体发送引导。别名：`/tell`。 + - `/agents` 列出当前会话的线程绑定 agent。 + - `/kill ` 中止一个或所有正在运行的子 agent。 + - `/steer ` 向正在运行的子 agent 发送引导。别名：`/tell`。 - + - `/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` 设置发送策略。仅限所有者。 - + - `/tts on|off|status|chat|latest|provider|limit|summary|audio|help` 控制 TTS。参见 [TTS](/zh-CN/tools/tts)。 - `/activation mention|always` 设置群组激活模式。 - - `/bash ` 运行宿主 shell 命令。仅文本。别名：`! `。需要 `commands.bash: true` 以及 `tools.elevated` 允许列表。 + - `/bash ` 运行主机 shell 命令。仅文本。别名：`! `。需要 `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 [duration]|disarm` 临时启用高风险手机节点命令。 +- `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对/设置流程。参见[配对](/zh-CN/channels/pairing)。 +- `/phone status|arm [duration]|disarm` 临时授权高风险手机节点命令。 - `/voice status|list [limit]|set ` 管理 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 [input]` 始终作为通用入口点可用。 -- 当 Skill/插件注册时，Skills 也可能显示为类似 `/prose` 的直接命令。 -- 原生 Skill 命令注册由 `commands.nativeSkills` 和 `channels..commands.nativeSkills` 控制。 +- 当 skill/plugin 注册它们时，skills 也可能显示为 `/prose` 这样的直接命令。 +- 原生 skill 命令注册由 `commands.nativeSkills` 和 `channels..commands.nativeSkills` 控制。 - - - 命令在命令和参数之间接受可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。 - - `/new ` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配项，文本会被视为消息正文。 - - 如需完整的提供商使用情况细分，请使用 `openclaw status --usage`。 + + - 命令接受命令与参数之间可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。 + - `/new ` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配，文本会被视为消息正文。 + - 如需完整的提供商用量明细，请使用 `openclaw status --usage`。 - `/allowlist add|remove` 需要 `commands.config=true`，并遵循渠道 `configWrites`。 - - 在多账号渠道中，面向配置目标的 `/allowlist --account ` 和 `/config set channels..accounts....` 也会遵循目标账号的 `configWrites`。 + - 在多账号渠道中，面向配置的 `/allowlist --account ` 和 `/config set channels..accounts....` 也会遵循目标账号的 `configWrites`。 - `/usage` 控制每条回复的用量页脚；`/usage cost` 会从 OpenClaw 会话日志打印本地费用摘要。 - - `/restart` 默认启用；设置 `commands.restart: false` 可禁用。 - - `/plugins install ` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/归档、npm 包或 `clawhub:`。 - - `/plugins enable|disable` 会更新插件配置，并可能提示重启。 + - `/restart` 默认启用；设置 `commands.restart: false` 可将其禁用。 + - `/plugins install ` 接受与 `openclaw plugins install` 相同的插件 spec：本地路径/归档、npm 包，或 `clawhub:`。 + - `/plugins enable|disable` 更新插件配置，并可能提示重启。 - - - 仅 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`）。 + + - 仅 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)。 - - - `/verbose` 用于调试和额外可见性；正常使用时保持**关闭**。 - - `/trace` 比 `/verbose` 更窄：它只显示插件拥有的 trace/debug 行，并保持普通详细工具噪声关闭。 + + - `/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` 在群组环境中有风险：它们可能泄露你无意公开的内部推理、工具输出或插件诊断。建议保持关闭，尤其是在群聊中。 - + - `/model` 会立即持久化新的会话模型。 - - 如果智能体处于空闲状态，下一次运行会立即使用它。 - - 如果运行已处于活动状态，OpenClaw 会将实时切换标记为待处理，并且只在干净的重试点重启到新模型。 - - 如果工具活动或回复输出已经开始，待处理切换可能会保持排队，直到之后的重试机会或下一轮用户输入。 - - 在本地 TUI 中，`/crestodian [request]` 会从普通智能体 TUI 返回 Crestodian。这与消息渠道救援模式不同，也不会授予远程配置权限。 + - 如果智能体空闲，下一次运行会立即使用它。 + - 如果已有运行处于活动状态，OpenClaw 会将实时切换标记为待处理，并只会在干净的重试点重启进入新模型。 + - 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到之后的重试机会或下一次用户回合。 + - 在本地 TUI 中，`/crestodian [request]` 会从普通智能体 TUI 返回到 Crestodian。这不同于消息渠道救援模式，也不会授予远程配置权限。 - - - **快速路径：** 来自允许列表发送者的纯命令消息会被立即处理（绕过队列 + 模型）。 - - **群组提及门控：** 来自允许列表发送者的纯命令消息会绕过提及要求。 - - **内联快捷方式（仅限允许列表发送者）：** 某些命令嵌入普通消息时也能工作，并且会在模型看到剩余文本之前被剥离。 - - 示例：`hey /status` 会触发 Status 回复，剩余文本会继续走普通流程。 + + - **快速路径：**来自允许列表发送者的纯命令消息会立即处理（绕过队列 + 模型）。 + - **群组提及门控：**来自允许列表发送者的纯命令消息会绕过提及要求。 + - **行内快捷方式（仅允许列表发送者）：**某些命令嵌入普通消息时也可使用，并会在模型看到剩余文本前被剥离。 + - 示例：`hey /status` 触发 Status 回复，剩余文本继续进入普通流程。 - 当前：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。 - - 未授权的纯命令消息会被静默忽略，内联 `/...` 标记会被视为纯文本。 + - 未授权的纯命令消息会被静默忽略，行内 `/...` token 会被视为纯文本。 - - - **Skill 命令：** `user-invocable` Skills 会暴露为斜杠命令。名称会被清洗为 `a-z0-9_`（最多 32 个字符）；冲突时会获得数字后缀（例如 `_2`）。 - - `/skill [input]` 按名称运行 Skill（当原生命令限制阻止为每个 Skill 提供命令时很有用）。 - - 默认情况下，Skill 命令会作为普通请求转发给模型。 - - Skills 可以选择声明 `command-dispatch: tool`，将命令直接路由到工具（确定性，无模型）。 + + - **Skill 命令：**`user-invocable` skills 会作为斜杠命令公开。名称会被清理为 `a-z0-9_`（最多 32 个字符）；冲突会获得数字后缀（例如 `_2`）。 + - `/skill [input]` 按名称运行 skill（当原生命令限制阻止为每个 skill 创建命令时很有用）。 + - 默认情况下，skill 命令会作为普通请求转发给模型。 + - Skills 可以选择声明 `command-dispatch: tool`，将命令直接路由到工具（确定性、无模型）。 - 示例：`/prose`（OpenProse 插件）— 参见 [OpenProse](/zh-CN/prose)。 - - **原生命令参数：** Discord 对动态选项使用自动补全（省略必需参数时使用按钮菜单）。当命令支持选项且你省略参数时，Telegram 和 Slack 会显示按钮菜单。动态选项会针对目标会话模型解析，因此模型特定选项（例如 `/think` 级别）会遵循该会话的 `/model` 覆盖。 + - **原生命令参数：**Discord 对动态选项使用自动补全（当你省略必需参数时使用按钮菜单）。Telegram 和 Slack 会在命令支持选项且你省略参数时显示按钮菜单。动态选项会根据目标会话模型解析，因此 `/think` 级别等模型特定选项会跟随该会话的 `/model` 覆盖。 ## `/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: ``` -覆盖会立即应用到新的配置读取，但**不会**写入 `openclaw.json`。使用 `/debug reset` 清除所有覆盖并回到磁盘上的配置。 +覆盖会立即应用到新的配置读取，但**不会**写入 `openclaw.json`。使用 `/debug reset` 清除所有覆盖，并返回磁盘上的配置。 -## 插件追踪输出 +## 插件跟踪输出 -`/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: ``` -`/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 拥有的项目设置中。运行时适配器决定哪些传输协议实际可执行。 +`/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 拥有的项目设置中。运行时适配器决定实际可执行哪些传输协议。 ## 插件更新 -`/plugins` 允许操作员检查已发现的插件，并在配置中切换启用状态。只读流程可以使用 `/plugin` 作为别名。默认禁用；使用 `commands.plugins: true` 启用。 +`/plugins` 允许操作员检查已发现的插件，并在配置中切换启用状态。只读流程可以使用 `/plugin` 作为别名。默认禁用；用 `commands.plugins: true` 启用。 示例： @@ -430,45 +431,45 @@ x-i18n: ``` -- `/plugins list` 和 `/plugins show` 会基于当前工作区和磁盘配置执行真实的插件发现。 -- `/plugins enable|disable` 只更新插件配置；它不会安装或卸载插件。 -- 启用/禁用更改后，重启 Gateway 网关以应用它们。 +- `/plugins list` 和 `/plugins show` 会针对当前工作区加磁盘配置执行真实的插件发现。 +- `/plugins enable|disable` 只会更新插件配置；它不会安装或卸载插件。 +- 启用/禁用更改后，重启 Gateway 网关以应用更改。 -## 界面说明 +## 表面说明 - - - **文本命令**在普通聊天会话中运行（私信共享 `main`，群组有自己的会话）。 + + - **文本命令**在正常聊天会话中运行（私信共享 `main`，群组有自己的会话）。 - **原生命令**使用隔离会话： - Discord：`agent::discord:slash:` - Slack：`agent::slack:slash:`（前缀可通过 `channels.slack.slashCommand.sessionPrefix` 配置） - - Telegram：`telegram:slash:`（通过 `CommandTargetSessionKey` 定位聊天会话） - - **`/stop`** 定位活动聊天会话，因此它可以中止当前运行。 + - Telegram：`telegram:slash:`（通过 `CommandTargetSessionKey` 指向聊天会话） + - **`/stop`** 指向活动聊天会话，因此它可以中止当前运行。 - 仍然支持 `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 消息中仍然可用。 -## 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 细节。 ## 相关内容