openclaw agent¶

通过 Gateway 运行一个代理回合。显式的 --local 标志和 agent exec 是嵌入式执行路径。

由 Gateway 支持的回合属于操作员输入。代理的 exec 子进程如果携带 OPENCLAW_SHELL=exec，就不能使用此命令向另一个会话报告； 请改用其归属会话工具或正常的子代理完成。这 不会改变操作员终端使用或独立的嵌入式执行路径。

至少传递一个会话选择器：--to、--session-key、--session-id 或 --agent。显式空白或仅包含空白字符的选择器值会在本地或 Gateway 分发之前被拒绝，即使另一个选择器提供了有效目标。对于未使用的选择器，应省略而不是传递空值。

当 --session-id 在某个代理的存储分区中找到现有会话时，即使 session.store 使用一个固定的 JSON 定位器，且存储的键为 global 或 unknown，它也会保留该代理。

已完成的回合以 0 退出。错误、超时和取消结果在写入任何文本或 JSON 结果之后以 1 退出。收到 SIGINT 或 SIGTERM 时，则保留下面描述的特定信号退出状态。

相关：Agent send tool

agent exec¶

openclaw agent exec 在不连接 Gateway 的情况下运行一个嵌入式代理回合。它是 CI 和编码自动化推荐的无头入口点，因为它负责设置、清理、输出投影和进程状态。

openclaw agent exec "Run the focused tests and fix failures"
openclaw agent exec --message-file task.md --cwd ./repo
cat task.md | openclaw agent exec --message-file - --json

默认情况下，该命令会创建一个临时状态目录，并在确认清理后将其删除，包括已接受的数据库工作和该运行的数据库资源。它针对你普通的 OpenClaw 配置运行，因此已配置的提供商、凭据和 agentRuntime 执行框架选择与其他地方完全一样适用。--cwd 默认为进程工作目录，并作为代理工作区和工具工作目录传递。

配置以三部分分层，完全在内存中：exec 组合运行配置，并将其发布为当前进程的运行时配置，而不是将副本写入磁盘。Exec 默认值仅在你的配置未设置某项设置时适用：跳过工作区引导文件，关闭代理沙箱，选择 coding 工具配置文件，将文件系统工具限制在 --cwd，并且 exec 在无头回合所需的完整执行策略下运行。你的配置中设置的任何内容都优先于这些默认值，因此已配置沙箱、shell 环境变量或工具配置文件永远不会被降级，并且当你的配置启用沙箱时，exec 主机路由仍与沙箱保持一致。调用本身始终最后胜出：运行范围限定为 --cwd，并且从不进行引导。

当你的工具策略启用 browser 时，本地浏览器控制无需 Gateway 即可工作。显式 Gateway 或节点路由以及沙箱限制仍然适用；参见 Node browser proxy。

使用 --state-dir <dir> 保留会话和其他运行状态。该目录必须已经存在，并且命令永远不会创建或删除它。保留的状态目录需要独占所有权：当 Gateway 或另一个嵌入式写入者拥有它时，exec 拒绝启动，然后在整个运行期间持有状态锁。对于隔离的临时状态，省略 --state-dir，或者先用 openclaw gateway stop 停止 Gateway。

当 exec 使用环境配置或固定配置时，已安装插件仍从操作员的普通插件根目录解析，而会话和其他运行状态使用临时目录。在这些模式下，--state-dir 仅控制运行状态；对于由已安装插件提供的已配置提供商、通道或执行框架，它不是必需的。

为了可复现的运行，请固定配置而不是继承它。--config <path> 针对恰好该配置文件运行，通过正常加载器读取，因此 JSON5 语法和 $include 相对于它解析；缺失或无效文件会使运行失败，而不是回退到默认值，存在但无法解析的环境配置也是如此。--isolated 完全忽略环境配置，仅使用上述 exec 默认值。对于 CI，两者都是正确选择，因为继承操作员状态会使运行依赖于机器。

默认使用已存储的凭据，因此文件夹范围的运行可以访问与 CLI 其余部分相同的登录。传递 --auth-env-only 可将运行限制为进程环境中已存在的提供商密钥。该模式完全不加载配置，并且与 --config 组合会被拒绝而不是被静默忽略，因为配置会同时通过多个表面提供提供商凭据：inline keys and secret headers、env 块和登录 shell 导入。它还会跳过 OpenClaw 身份验证配置文件以及外部 Codex、Claude 或其他 CLI 凭据存储。提供商身份验证变量仍可用于模型身份验证，但会从代理启动的主机命令中省略。

在干净安装且没有 Codex 插件的情况下，OpenAI API 密钥运行使用内置 OpenClaw 运行时。隐式 Codex 偏好不要求在 --auth-env-only 可以运行之前安装原生执行框架。显式配置的 Codex 运行时或现有 Codex 会话固定仍需要该执行框架。

使用可重复标志选择主模型和有序回退链：

openclaw agent exec "Implement the change" \
  --model openai/gpt-6-astra \
  --fallback anthropic/claude-sonnet-4-6 \
  --fallback google/gemini-3.1-pro-preview

仅对于此命令，显式 --fallback 值与显式 --model 一起保持有效。其他代理入口点保留其现有规则：用户选择的模型会禁用已配置的回退。

在比较本地或较小模型时，显式选择一次性工具表面：

openclaw agent exec "Inspect this repository" \
  --model ollama/qwen3.5:9b \
  --code-mode code \
  --local-model-lean \
  --json

--code-mode direct 禁用 Code Mode，auto 使用模型能力元数据，code 为支持工具的运行强制使用通用 Code Mode 界面。--local-model-lean 移除高延迟和通道依赖的工具，并为隔离运行启用有界的 Tool Search 默认值。

agent exec 的超时默认为 600 秒；这不会更改现有嵌入式 agent --local 默认值。成功运行退出 0，任何模型或结果错误退出 1，超时退出 2。失败包括 meta.error、中止的运行、耗尽的模型回退、错误停止原因以及任何错误负载。

如果在运行错误或超时后清理失败，原始结果和退出码会被保留，清理失败通过 stderr 报告。成功运行后的清理失败退出 1。

不确定的运行时清理会保留临时状态以供检查，并保留任何 已获取的状态锁，直到该进程退出。在针对保留状态重试运行之前， 检查报告的清理失败。

普通输出仅将最终助手文本写入 stdout。诊断信息使用 stderr。--json 将 stdout 保留给此稳定信封：

{
  "ok": true,
  "status": "ok",
  "final": "The focused tests pass.",
  "payloads": [{ "text": "The focused tests pass." }],
  "usage": { "input": 120, "output": 8, "total": 128 },
  "costUsd": 0.0021,
  "codeModeEngaged": false,
  "assistantTurns": 2,
  "bridgeCalls": { "search": 1, "describe": 0, "call": 3 },
  "toolSummary": { "calls": 2, "tools": ["read", "write"], "totalToolTimeMs": 48 },
  "model": "gpt-6-astra",
  "provider": "openai",
  "sessionId": "019..."
}

status 为 ok、error 或 timeout。usage 在不可用时省略。失败的信封会添加 error: { message, kind }；如果失败发生在模型选择之前，model 和 provider 为 null。

运行统计字段是附加的，可能不存在：

• costUsd：记录的每次调用 USD 成本之和，保留请求定价层级和重试模型价格，包括缓存读取/写入。当每次调用成本不完整时，仅可使用固定价格估算；分层估算会被省略，而不是将合并用量按一次请求计价。成本不可用时省略。
• codeModeEngaged：仅当 Code Mode 实际拥有该运行的模型工具界面时为 true。仅 tools.codeMode.enabled=true 并不能保证启用，拥有其原生工具界面的测试框架始终读取 false，因为 OpenClaw Code Mode 从不拥有它们的工具。
• assistantTurns：运行中已完成的助手/提供商往返次数；如果没有完成则省略。
• bridgeCalls：内部工具搜索/Code Mode 桥接调用计数（search/describe/call）。这些对提供商不可见；外部工具调用保留在完整运行元数据的 meta.toolSummary.calls 中。
• toolSummary：来自嵌入式运行的外部模型可见工具调用计数、工具名称、失败和总工具时间。

代理运行统计字段出现在 openclaw agent --json 响应的 meta.agentMeta 上；外部工具摘要仍位于 meta.toolSummary。

Code Mode 模型矩阵¶

从源代码检出，针对任何显式模型引用运行有界评估矩阵：

pnpm qa:code-mode-models -- --model ollama/qwen3.5:9b

重复 --model 以比较模型，或使用 --mode、--task 和 --repetitions 缩小选择范围。基础任务和文件工作流任务通过隔离的 agent exec 调用运行；下文中的 Gateway 任务使用一次性 Gateway 并显式选择 OpenClaw 代理运行时。每个单元格记录模型/提供商身份、计时、结果状态、失败类别、工具活动和任务特定的正确性检查。

默认仍为两个任务（read 和 dependent-read-write）、三种模式和三次重复：每个模型 18 个单元格。扩展任务是可选的，因此默认模型调用预算不会增加：

上述三个文件工作流任务要求精确的最终答案和匹配的 result.txt。对于给定重复次数，输入是确定性的，并且跨模型/模式相同。提示词请求文件工具和读回，但预言机验证结果和聚合工具执行，而不是完整调用跟踪：它无法证明分页策略、实际并发、依赖顺序或读回。这些需要单独的运行时/轨迹证明。

预览一个六单元格的 direct/Code Mode 对比，无需构建或调用任何模型：

pnpm qa:code-mode-models -- --model ollama/qwen3.5:9b \
  --mode direct --mode code --repetitions 1 \
  --task large-result-reduction --task parallel-independent-reads \
  --task dependent-chain --dry-run

仅在明确打算运行模型时移除 --dry-run；可能会产生提供商费用。试运行会写入计划和空的规范证据，而不是通过的任务结果。离线测试框架覆盖通过 pnpm test extensions/qa-lab/src/code-mode-model-matrix.test.ts 运行，并使用一个无提供商调用的合成 CLI；它不是实时 Code Mode 性能证据。

输出目录包含规范 QA Lab qa-evidence.json。summary.json 和 results.jsonl 是辅助的聚合和逐单元工件；manifest.json 记录请求的矩阵和源标识。

每个摘要组保留通过率、首次通过/最终成功、失败类别和 p50WallMs。其可加 metrics 对象将助手轮次、外部工具调用、bridge 搜索/描述/工具调用以及报告的美元成本汇总为 { samples, total, p50 }。只有存在的信封值才计为样本；缺失遥测不是零（无样本时 total 和 p50 为 null）。观察到的零仍保持为零。中位数在偶数计数时使用上中位样本，与现有墙钟时间摘要一致。所有重复，包括带有遥测的失败重复，均计入。

对于返回 agent 信封的单元格，elapsedMs 测量夹具准备之后的 agent 进程和效果验证。测试框架错误单元格则测量尝试的单元格，包括异常之前的任何设置。两者都不包含矩阵构建，也都不只是 guest 执行时间。测试框架不报告不可观察的阶段计时、重叠、缩减比例或推断的加速。在计时/计数之前比较正确性，检查缺失样本计数，并在提供时保留原始逐单元 usage/costUsd/bridgeCalls。

这是仅用于评估的证据，不是 CI 或发布门禁。结果不会改变模型能力、运行时路由、回退或修复策略。

配对性能工作负载¶

这些可选工作负载将 Code Mode 与常规 OpenClaw 工具暴露进行比较。 --mode direct 明确禁用 Code Mode 并保留常规 Tool Search； --mode code 启用它。两个实验臂使用相同的 prompt、种子输入、允许的工具、模型和 thinking 设置。它们拒绝 --mode auto，固定 OpenClaw 运行时，禁用 fast mode，并跳过后续访谈。OpenAI 模型在此使用 OpenClaw，而不是其原生 agent 测试框架。

性能选择需要两个处理臂，并且不能与仅 code 访谈任务混合。构建的工件在每波之后重新哈希；漂移会停止准入并暂缓比较，同时保留观察。

针对一个干净的、已构建的运行时预览八个单元格：

pnpm qa:code-mode-models -- --model openai/gpt-5.6-sol \
  --mode direct --mode code --executor node --repetitions 1 \
  --task repo-invoice-repair --task invoice-reconciliation \
  --task batch-settlement-recovery --task fanout-dependency \
  --thinking low --timeout 600 --concurrency 2 \
  --max-cells 8 --max-tokens 1000000 \
  --max-known-cost-usd 25 --max-wall-seconds 3600 \
  --runtime-dir ../frozen-runtime \
  --output-dir artifacts/code-mode/paired-preview --dry-run

以下冻结运行时要求适用。实时运行时使用新的输出目录。--keep-state 保留一次性工作区和状态以供检查；运行器还会捕获每个工作负载的命名交付物及其哈希。

默认调度在配对之间交替起始臂。--schedule 接受一个由 {model, task, repetition, firstMode} 条目组成的 JSON 数组，其中 firstMode 为 direct 或 code。条目必须匹配所选清单，并要求两种模式。对于比较，保持调度固定。--concurrency 限制根单元格，而不是后代。限制会准入完整的配对波次；token、已知成本和墙钟限制会停止新波次，同时已准入的工作完成。缺失的使用量或价格会使观察到的总量成为下界，因此这些不是硬性支出上限。未开始的单元格在调度和摘要中仍然可见。

mode-comparison.json 按模型、任务、种子、源/构建、prompt/夹具指纹和设置对结果进行配对。逐单元核算包括父级和后代输入、缓存读取/写入以及输出，并与运行时总量对账。缺失的使用量或价格保持不可用，绝不视为零。失败尝试保留在运营总量中。成功配对差值要求两个臂均通过并完成测量；观察到的错误计数包括有意探测，不是修复轮次计数。任务延迟排除启动和访谈。

自动完成意味着工件/效果检查通过。最终响应准确性和执行完整性需要针对保留的转录、命令、回执和文件进行单独裁定。正确的工件可能伴随虚假的测试声明。临时工作区和文件工具限制不能隔离广泛的 shell 访问：从独立能力和效率比较中排除重用同级解决方案或基准答案的运行。Fanout 检查证明依赖完成并强制并发限制；它们不能证明每个独立启动都先于收集。检查编排跟踪和测量的子并发以验证该调度声明。在报告聚合节省之前，报告正确性、缺失性和排除项；所选工作负载组合不能确立通用 token、成本或速度收益。

Gateway 任务与后续访谈¶

同一矩阵可以运行一个一次性构建的 Gateway，然后在同一对话的新运行中对 agent 进行访谈。这些任务为可选启用，并且需要 --mode code。Gateway 任务支持显式的 Anthropic、Google 或 OpenAI 模型引用，并配合相应的提供商凭据。上述默认矩阵保持不变。

先构建干净的基线和候选检出。对两者使用相同的测试框架、模型、prompts、fixture、思考设置、超时和重复次数：

pnpm qa:code-mode-models -- --model openai/gpt-5.6-luna --mode code \
  --task invoices-auto-retention --task inventory-join --repetitions 1 \
  --thinking low --runtime-dir ../baseline \
  --output-dir artifacts/code-mode/baseline --allow-failures

pnpm qa:code-mode-models -- --model openai/gpt-5.6-luna --mode code \
  --task invoices-auto-retention --task inventory-join --repetitions 1 \
  --thinking low --runtime-dir ../candidate \
  --output-dir artifacts/code-mode/candidate \
  --baseline-results artifacts/code-mode/baseline/results.jsonl --allow-failures

--runtime-dir 使用现有构建产物而不重新构建。它要求一个干净的已提交检出，并且两个构建戳都匹配该提交并记录干净的构建输入。对于具有来源能力戳写入器的修订版本，请在干净检出中运行 pnpm build 以刷新过期或较旧的戳。没有这些写入器的历史修订版本不支持作为冻结运行时；仅重新构建它们无法添加此来源信息。矩阵记录源和产物哈希，当配对单元格或其工作负载指纹不同时拒绝比较。添加 --model 以使用另一个模型，并重复任务选择器以包含更多场景。失败的试验仍保留在结果中；--allow-failures 仅改变命令的退出状态。

每个 Gateway 拥有临时 home、状态、工作区、配置和一个空闲回环端口。进程仅接收其选定的提供商密钥和所需的主机路径。合成插件工具实现 fixture 导出和变更回执；自动化和进程操作使用真实内置功能。Operator Gateway、已存储的 operator 凭据、真实通道和真实设备均不使用。每个场景仅暴露其所需工具。Gateway 目录预检在任何付费模型调用之前检查 fixture 可用性；缺失的能力属于测试框架失败，而不是模型任务失败。

每个单元格的产物包括实际的任务/访谈转录、工具效果回执、检查项和已脱敏诊断信息。任务回执在访谈之前捕获；独立的任务和访谈回执文件与完整台账一起保留该边界。进程辅助程序的确切写入源字节是其工作负载指纹的一部分。JavaScript 契约任务验证声明发现、运行时输入验证以及依赖的文件操作序列，包括通过 wait 完成。预览完整性检查使用已探测引用的观察元数据；缺失或冲突的元数据仍保持未知。除非明确要求发布，否则将转录保留在本地。关于样本覆盖范围、新鲜度、生命周期、限制和重试安全性的访谈声明必须对照这些记录进行审查：仅结构化答案不足以证明理解。当先前结果引用确实被观察到时，它会在访谈的新准入运行中接受测试；它不得成为持久对话状态。

Gateway 行分别记录启动、任务和访谈计时。其普通的 assistantTurns、usage 和 costUsd 描述任务；访谈测量是独立的。缺失的成本或使用量仍不可用。摘要和比较输出也将观察到的任务行为检查与访谈一致性检查分开；两者都不能替代对访谈的人工评估。原始的总体通过标志和比较差异仍要求完全成功。taskBehavior.deltas 在配对的任务行为检查均通过且请求的模型身份已验证时，报告仅任务差异，即使访谈存在不一致标志。缺失的跟踪或检查结果仍不可用，并且所有原始失败均保留。这些是观察结果，而不是统计速度保证。

agent exec 选项¶

• [message]：位置参数提示文本
• --message-file <path>：从文件读取 UTF-8 提示；- 读取标准输入
• --cwd <dir>：同时设置代理工作区和工具工作目录
• --state-dir <dir>：使用现有状态目录而不删除它
• --config <path>：针对此配置文件运行，而不是环境配置（支持 JSON5 和 $include）
• --isolated：忽略环境配置，仅使用 exec 默认值
• --model <provider/model>：显式主模型
• --code-mode <mode>：选择 direct、auto 或强制 code 工具模式
• --local-model-lean：使用缩减的本地模型工具集
• --thinking <level>：单次运行的思考级别
• --fallback <provider/model>：有序回退模型；可重复使用，且需要 --model
• --auth-env-only：仅使用环境变量中的提供商密钥；完全跳过已存储凭据、外部 CLI 凭据和配置
• --no-auth-env-only：允许使用已存储和外部 CLI 凭据（默认）
• --timeout <seconds>：以秒为单位的截止时间（默认 600；0 表示禁用）
• --json：输出稳定的 JSON 信封

选项¶

• -m, --message <text>：消息正文
• --message-file <path>：从 UTF-8 文件读取消息正文
• -t, --to <dest>：用于派生会话密钥的收件人
• --session-key <key>：用于路由的显式会话密钥
• --session-id <id>：显式会话 ID
• --agent <id>：代理 ID；覆盖路由绑定
• --model <id>：本次运行的模型覆盖（provider/model 或模型 ID）
• --thinking <level>：代理思考级别（off、minimal、low、medium、high，以及提供商/运行时支持的级别，例如 xhigh、adaptive、max 或 ultra）
• --verbose <on|off>：为会话持久化详细级别
• --channel <channel>：投递通道；省略时使用主会话通道
• --reply-to <target>：投递目标覆盖
• --reply-channel <channel>：投递通道覆盖
• --reply-account <id>：投递账户覆盖
• --local：直接运行嵌入式代理（在插件注册表预加载之后）
• --deliver：将回复发送回所选通道/目标
• --timeout <seconds>：覆盖此命令的代理轮次截止时间（默认 600，或 agents.defaults.timeoutSeconds）；0 禁用整体截止时间。600 秒回退值属于此 CLI 命令，而不是普通 Gateway 轮次，后者的默认值为 48 小时。
• --json：输出 JSON

使用 OpenClaw 托管代理循环的 Gateway 命令会在可选内存刷新和压缩之前返回其已完成的回复。该工作拥有自己的会话所有者，并使用命令的剩余时间。同一会话中的新轮次会在开始推理之前取消并结算它。一次性 --local 命令会跳过可选的轮次后工作；必需的检查点和压缩仍会在该循环中的推理之前发生。通用 CLI 后端在命令返回之前保留其现有的主机压缩；原生后端保留其自身的压缩策略。取消、重启和会话所有权变更继续隔离活动写入者。

示例¶

openclaw agent --to +15555550123 --message "status update" --deliver
openclaw agent --agent ops --message "Summarize logs"
openclaw agent --agent ops --message-file ./task.md
openclaw agent --agent ops --model openai/gpt-5.4 --message "Summarize logs"
openclaw agent --session-key agent:ops:incident-42 --message "Summarize status"
openclaw agent --agent ops --session-key incident-42 --message "Summarize status"
openclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium
openclaw agent --to +15555550123 --message "Trace logs" --verbose on --json
openclaw agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"
openclaw agent --agent ops --message "Run locally" --local

备注¶

• 必须且只能传递 --message 或 --message-file 之一。--message-file 会去除开头的 UTF-8 BOM 并保留多行内容；它会拒绝不是有效 UTF-8 的文件。大于 4 MiB 的文件会在分发前被拒绝。
• --message 不会运行通道斜杠命令分发器。已识别的 $skill-name 引用以及开头的 /skill-name [input] 是范围受限的例外：OpenClaw 会将它们展开为模型指令，以便在操作前读取该技能。其他以斜杠开头的消息保持正常的代理轮次行为；/compact 会被拒绝，并指向 openclaw sessions compact <key>。
• --local 运行是一次性的：为该运行打开的捆绑 MCP 环回资源和预热 Claude stdio 会话会在回复后回收，因此脚本调用不会留下正在运行的本地子进程。Gateway 支持的运行则改为在正在运行的 Gateway 进程下保留 Gateway 拥有的 MCP 环回资源。
• --local 要求独占拥有已配置的状态目录。当 Gateway 或另一个 agent --local 运行拥有该目录时，它会拒绝启动，然后在整个嵌入式轮次期间持有相同的状态锁。不带 --local 运行以使用活动 Gateway，或先用 openclaw gateway stop 停止它。
• 使用 --local 的独立嵌入式执行在重启恢复待处理时，拒绝复用现有主会话。通过健康的 Gateway 运行该轮次，或在那里使用 /new 或 /reset 重置它；独立的嵌入式进程无法安全地协调该恢复所有者与 Gateway 扫描器。
• 同时使用 --agent、--channel 和 --to 时，会话路由遵循通道的规范收件人和 session.dmScope。具有稳定仅出站收件人身份的通道使用由提供商拥有的会话，该会话与代理的主会话隔离。--reply-channel 和 --reply-account 仅影响投递。
• --session-key 选择显式会话密钥。带代理前缀的密钥必须使用 agent:<agent-id>:<session-key>，当同时提供时，--agent 必须与密钥的代理 ID 匹配。裸非哨兵密钥在提供 --agent 时限定到 --agent，否则限定到已配置的默认代理；例如 --agent ops --session-key incident-42 路由到 agent:ops:incident-42。字面密钥 global 和 unknown 仅在未提供 --agent 时保持无作用域。
• --json 将 stdout 保留给 JSON 响应；Gateway、插件和 --local 诊断信息输出到 stderr，以便脚本直接解析 stdout。
• 在瞬时握手重试耗尽后，Gateway 超时或连接关闭会使命令失败；CLI 绝不会静默地以嵌入式方式重新运行该轮次。传输丢失具有歧义性——Gateway 可能已接受并且可能仍会完成该轮次——因此 stderr 提示建议在重试或使用 --local 重新运行之前检查 openclaw gateway status 和会话转录，以避免两次执行该轮次。当 Gateway 在传输错误之前已接受运行时，提示会指明已接受的运行 ID，并且 --json 失败会保留规范的 ok: false 信封，其中包含 runId 和 origin: "gateway" 字段，以及 error.type/error.message。
• SIGTERM/SIGINT 会中断等待中的 Gateway 支持请求；如果 Gateway 已接受该运行，CLI 还会在退出前为该运行 ID 发送 chat.abort。--local 运行会收到相同信号，但不会发送 chat.abort。在 Unix 上，启动包装器会保留运行时子进程的实际终止信号，包括关闭升级后的 SIGKILL；shell 将 SIGINT 和 SIGTERM 报告为状态 130 和 143。显式数值返回保持数值，包括已处理的关闭返回 0。Windows 保留其数值终止行为。如果内部运行去重键已为此会话拥有活动运行，响应会报告 status: "in_flight"，非 JSON CLI 会打印 stderr 诊断信息，而不是空回复。对于外部 cron/systemd 包装器，请保留硬终止后备措施，例如 timeout -k 60 600 openclaw agent ...，以便在关闭无法完成排空时，监督程序可以回收该进程。
• 当此命令触发 models.json 重新生成时，SecretRef 管理的提供商凭据会作为非机密标记持久化（例如环境变量名、secretref-env:ENV_VAR_NAME 或 secretref-managed），绝不会持久化已解析的机密明文。标记写入来自活动源配置快照，而不是已解析的运行时机密值。

JSON 故障¶

失败会保留 CLI 错误信封：ok: false 和 error.type: "cli_error"。当 Gateway 返回了运行 ID 时，信封还会包含顶层 runId 和 origin: "gateway"。这包括没有新的接受响应时的缓存最终错误，以及接受后发生的超时或连接丢失。

origin 标识该运行的 Gateway 归属；它不能证明运行失败或停止。在传输丢失后，重试前请检查会话记录。省略来源证明表示 CLI 未观察到 Gateway 运行标识，而不是没有发生运行。没有 Gateway 运行 ID 的本地错误和拒绝会省略这些字段。仅本地生成的幂等性密钥不构成 Gateway 来源证明。

JSON 投递状态¶

使用 --json --deliver 时，CLI JSON 响应会包含顶层 deliveryStatus，以便脚本区分已投递、已抑制、部分成功和失败的发送：

{
  "payloads": [{ "text": "Report ready", "mediaUrl": null }],
  "meta": { "durationMs": 1200 },
  "deliveryStatus": {
    "requested": true,
    "attempted": true,
    "status": "sent",
    "succeeded": true,
    "resultCount": 1
  }
}

由 Gateway 支持的 CLI 响应还会在 result.deliveryStatus 中保留原始 Gateway 结果结构。

deliveryStatus.status 的取值之一为：

通用字段：

• requested：当该对象存在时始终为 true。
• attempted：一旦持久化发送路径已运行则为 true；预检失败或没有可见载荷时为 false。
• succeeded：为 true、false 或 "partial"；"partial" 与 status: "partial_failed" 配对。
• reason：来自持久化投递或预检验证的小写 snake-case 原因。已知值包括 cancelled_by_message_sending_hook、no_visible_payload、no_visible_result、channel_resolved_to_internal、unknown_channel、invalid_delivery_target 和 no_delivery_target；失败的持久化发送也可能报告失败阶段。由于该集合可能扩展，请将未知值视为不透明值。
• resultCount：可用时，为通道发送结果的数量。
• sentBeforeError：当部分失败在出错前已发送至少一个载荷时为 true。
• error：对于失败或部分失败的发送为 true。
• errorMessage：仅在捕获到底层投递错误消息时存在。预检失败会携带 error/reason，但没有 errorMessage。
• payloadOutcomes：可选的逐载荷结果，可用时包含 index、status、reason、resultCount、error、stage、sentBeforeError 或钩子元数据。

相关¶

• CLI 参考
• Agent 运行时