概述
openclaw agent 通过 Gateway 运行一次 Agent turn，适合脚本化调用。默认走 Gateway，失败时自动回退到嵌入式 Agent；用 --local 强制直接走嵌入式。
openclaw agent --to <dest> --message <text> [options]至少需要提供一个会话选择器：--to、--session-id、--agent 三选一。
选项
| 选项 | 说明 |
|---|---|
-m, --message <text> | 必填，消息正文 |
-t, --to <dest> | 收件人，用于推导 session key |
--session-id <id> | 显式指定 session id |
--agent <id> | 目标 agent id，覆盖路由 binding |
--model <id> | 本次运行的模型覆盖（provider/model 或 model id） |
--thinking <level> | thinking 级别：off、minimal、low、medium、high，以及 provider 支持的 xhigh、adaptive、max |
--verbose <on|off> | 为该会话持久化 verbose 级别 |
--channel <channel> | 投递渠道（省略则用主会话渠道） |
--reply-to <target> | 投递目标覆盖 |
--reply-channel <channel> | 投递渠道覆盖 |
--reply-account <id> | 投递账号覆盖 |
--local | 直接运行嵌入式 Agent（跳过 Gateway） |
--deliver | 将回复发回所选渠道/目标 |
--timeout <seconds> | 覆盖 Agent 超时（默认 600 或配置值） |
--json | 输出 JSON |
--channel、--reply-channel、--reply-account影响回复投递，不影响会话路由。
示例
# 向指定号码发消息并投递回复
openclaw agent --to +15555550123 --message "status update" --deliver
# 指定 agent 运行
openclaw agent --agent ops --message "Summarize logs"
# 指定 agent + 模型覆盖
openclaw agent --agent ops --model openai/gpt-5.4 --message "Summarize logs"
# 指定 session + thinking 级别
openclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium
# 开启 verbose，输出 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" --localGateway vs 嵌入式模式
| 模式 | 触发方式 | 特点 |
|---|---|---|
| Gateway 模式（默认） | 正常调用 | Gateway 拥有 MCP loopback 资源，持续运行 |
| 嵌入式回退 | Gateway 请求失败时自动触发 | 单次运行，结束后退出本地子进程 |
--local 强制嵌入式 | 显式传 --local | 仍预加载插件注册表，provider/tool/channel 可用 |
嵌入式回退的 JSON 标识字段：
meta.transport: "embedded"meta.fallbackFrom: "gateway"
Gateway 超时后回退时额外包含：
meta.fallbackReason: "gateway_timeout"- 使用独立的
gateway-fallback-*session/run id，避免与 Gateway 原有 transcript 冲突
JSON 投递状态（--json --deliver）
{
"payloads": [{ "text": "Report ready", "mediaUrl": null }],
"meta": { "durationMs": 1200 },
"deliveryStatus": {
"requested": true,
"attempted": true,
"status": "sent",
"succeeded": true,
"resultCount": 1
}
}deliveryStatus.status 取值
| 值 | 含义 |
|---|---|
sent | 投递成功 |
suppressed | 有意不发送（如 hook 取消，或无可见结果），终态不重试 |
partial_failed | 至少一条 payload 发送成功，后续 payload 失败 |
failed | 无持久发送完成，或投递预检失败 |
常用字段
| 字段 | 说明 |
|---|---|
requested | 对象存在时始终为 true |
attempted | 持久发送路径执行后为 true；预检失败或无可见 payload 时为 false |
succeeded | true / false / "partial"（"partial" 对应 partial_failed） |
reason | 小写下划线原因码，如 cancelled_by_message_sending_hook、no_visible_payload、unknown_channel 等 |
resultCount | 渠道发送结果数量 |
sentBeforeError | 部分失败时是否已发出至少一条 payload |
error | 失败或部分失败时为 true |
errorMessage | 底层错误信息（仅在捕获到时包含；预检失败只有 error+reason） |
payloadOutcomes | 可选的逐 payload 结果（含 index、status、reason、stage 等） |
Gateway 响应中同一对象也可在 result.deliveryStatus 访问。