openclaw agent 命令用于通过 Gateway 向指定 Agent 发送一条消息并触发单次回合，可选择将回复投递回原渠道或覆盖的渠道。必须提供消息（-m）和至少一个会话选择器（--to / --session-key / --session-id / --agent）；使用 --local 强制嵌入模式，--json 输出 JSON 供脚本解析，投递状态字段可区分 sent / suppressed / partial_failed / failed。

OpenClaw agent 命令：通过 Gateway 发送单次 Agent 回合

通过 Gateway 运行一次 Agent 回合（使用 --local 可切换为嵌入模式，跳过 Gateway）。使用 --agent <id> 直接指定已配置的 Agent。

至少需要传递一个会话选择器：

--to <dest>
--session-key <key>
--session-id <id>
--agent <id>

选项

选项	说明
`-m, --message <text>`	必需：消息体
`-t, --to <dest>`	用于派生会话键的收件人
`--session-key <key>`	显式会话键，影响路由
`--session-id <id>`	显式会话 ID
`--agent <id>`	Agent ID，会覆盖路由绑定
`--model <id>`	本次运行的模型覆盖（`provider/model` 或模型 ID）
`--thinking <level>`	Agent 思考级别（`off`, `minimal`, `low`, `medium`, `high`，以及 provider 支持的 `xhigh`, `adaptive`, `max` 等）
`--verbose <on\|off>`	为该会话持久化详细级别
`--channel <channel>`	投递渠道，省略则使用主会话渠道
`--reply-to <target>`	投递目标覆盖
`--reply-channel <channel>`	投递渠道覆盖
`--reply-account <id>`	投递账号覆盖
`--local`	直接运行嵌入的 Agent（先加载插件注册表）
`--deliver`	将回复发送回所选渠道/目标
`--timeout <seconds>`	覆盖 Agent 超时（默认 600 秒或配置值）
`--json`	输出 JSON 格式

示例

bash

# 通过 Gateway 发送消息，并投递回复
openclaw agent --to +15555550123 --message "status update" --deliver

# 直接指定 Agent
openclaw agent --agent ops --message "Summarize logs"

# 覆盖模型
openclaw agent --agent ops --model openai/gpt-5.4 --message "Summarize logs"

# 显式会话键
openclaw agent --session-key agent:ops:incident-42 --message "Summarize status"

# 结合 --agent 和 --session-key（带 Agent 前缀）
openclaw agent --agent ops --session-key incident-42 --message "Summarize status"

# 指定会话 ID 和思考级别
openclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium

# 启用详细和 JSON 输出
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

注意事项

Gateway 模式在 Gateway 请求失败时会回退到嵌入 Agent。使用 --local 可强制从一开始就使用嵌入执行。
--local 仍会先预加载插件注册表，因此嵌入运行时仍可使用插件提供的 providers、tools 和 channels。
--local 和嵌入回退运行视为一次性运行。为该本地进程打开的捆绑 MCP loopback 资源和 Claude stdio session 在回复后会被回收，脚本化调用不会保持本地子进程存活。
Gateway 支持的运行会将 Gateway 拥有的 MCP loopback 资源留在正在运行的 Gateway 进程下；旧客户端仍可能发送历史清理标志，但 Gateway 会将其作为兼容性 no-op 接受。
--channel、--reply-channel 和 --reply-account 影响回复投递，不影响会话路由。
--session-key 选择显式会话键。Agent 前缀键必须使用 agent:<agent-id>:<session-key> 格式，并且同时提供 --agent 时，其值必须匹配键中的 Agent ID。单独的非哨兵键在提供了 --agent 时限定到该 Agent，否则限定到配置的默认 Agent；例如 --agent ops --session-key incident-42 路由到 agent:ops:incident-42。字面值 global 和 unknown 仅在未提供 --agent 时保持不限范围；此时嵌入回退和存储拥有权使用配置的默认 Agent。
--json 保持 stdout 只用于 JSON 响应。Gateway、插件和嵌入回退的诊断信息路由到 stderr，方便脚本直接解析 stdout。
嵌入回退 JSON 包含 meta.transport: "embedded" 和 meta.fallbackFrom: "gateway"，以便脚本区分回退运行与 Gateway 运行。
如果 Gateway 接受了 Agent 运行但 CLI 等待最终回复超时，嵌入回退会使用全新的显式 gateway-fallback-* 会话/运行 ID，并报告 meta.fallbackReason: "gateway_timeout" 及回退会话字段。这避免了与 Gateway 拥有的对话锁竞争，也不会静默替换原始路由的对话会话。
对于 Gateway 支持的运行，SIGTERM 和 SIGINT 会中断等待的 CLI 请求。如果 Gateway 已接受该运行，CLI 在退出前还会对该接受的运行 ID 发送 chat.abort。本地的 --local 运行和嵌入回退运行会收到相同的中止信号，但不发送 chat.abort。如果重复的 --run-id 在原始 Agent 运行仍处于活跃状态时到达 Gateway，重复响应会报告 status: "in_flight"，非 JSON CLI 会打印 stderr 诊断而不是空回复。对于外部 cron/systemd 包装脚本，建议设置外层硬杀伤后备，例如 timeout -k 60 600 openclaw agent ...，以便监督进程在关闭无法耗尽时仍然能够回收进程。
当此命令触发 models.json 重新生成时，SecretRef 管理的提供商凭据会以非密文标记形式持久化（例如环境变量名称、secretref-env:ENV_VAR_NAME 或 secretref-managed），而不是解析后的密钥明文。
标记写入以来源为权威：OpenClaw 从活跃的来源配置快照中持久化标记，而不是从解析的运行时密钥值中获取。

JSON 投递状态

当使用 --json --deliver 时，CLI JSON 响应可能包含顶层 deliveryStatus，方便脚本区分已发送、抑制、部分失败和失败：

json

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

deliveryStatus.status 的取值：

sent：已发送
suppressed：有意不发送（例如消息发送钩子取消，或没有可见结果）；这是终端无重试结果
partial_failed：至少一个 payload 成功发送，但后续 payload 失败
failed：未完成任何可靠发送或投递预检失败

Gateway 支持的 CLI 响应也会保留原始 Gateway 结果形状，同一对象位于 result.deliveryStatus。

常见字段：

requested：对象存在时始终为 true
attempted：可靠发送路径运行后为 true；预检失败或没有可见 payload 时为 false
succeeded：true、false 或 "partial"；"partial" 与 status: "partial_failed" 配对
reason：小写蛇形字符串，来自可靠投递或预检验证。已知值包括 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：部分失败时，至少一个 payload 在错误前已发送时为 true
error：布尔值，失败或部分失败时为 true
errorMessage：仅当捕获到底层投递错误消息时包含。预检失败携带 error 和 reason，但没有 errorMessage
payloadOutcomes：可选的每个 payload 结果，包含 index、status、reason、resultCount、error、stage、sentBeforeError 或钩子元数据（如果有）

常见问题

openclaw agent 怎么发送消息并获取回复？

使用 --to 或 --agent 指定目标，加上 --message 提供消息内容，然后添加 --deliver 让回复投递到原渠道。如果不加 --deliver，回复只在 CLI 输出中打印（非 JSON 时）。若需脚本解析，加上 --json。

openclaw agent --deliver 投递失败怎么办？

检查 deliveryStatus 对象中的 status 和 reason 字段。常见原因包括：unknown_channel（渠道未配置）、invalid_delivery_target（目标格式错误）、no_visible_result（Agent 没有返回可见内容）。确保启用了相应的渠道插件，且目标账号已配对。

openclaw agent --local 和默认网关模式有什么区别？

默认模式通过运行中的 Gateway 进程来执行 Agent 回合，Gateway 负责管理会话和 MCP 资源。--local 则直接在本进程内嵌入运行 Agent（加载插件注册表），不依赖 Gateway，适合快速测试或离线场景，但是一次性运行，临时资源会在回复后释放。

OpenClaw agent 命令：通过 Gateway 发送单次 Agent 回合 ​

选项 ​

示例 ​

注意事项 ​

JSON 投递状态 ​

相关文档 ​

常见问题 ​

openclaw agent 怎么发送消息并获取回复？ ​

openclaw agent --deliver 投递失败怎么办？ ​

openclaw agent --local 和默认网关模式有什么区别？ ​