openclaw agent

通过 Gateway 网关运行一轮智能体。如果 Gateway 网关请求失败，则回退到嵌入式智能体；传入 --local 可从一开始就强制执行嵌入式运行。

至少传入一个会话选择器：--to、--session-key、--session-id 或 --agent。

相关内容：智能体发送工具

选项

• -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）
• --verbose <on|off>：持久保存会话的详细输出级别
• --channel <channel>：投递渠道；省略时使用主会话渠道
• --reply-to <target>：覆盖投递目标
• --reply-channel <channel>：覆盖投递渠道
• --reply-account <id>：覆盖投递账号
• --local：直接运行嵌入式智能体（在预加载插件注册表后）
• --deliver：将回复发送回所选渠道/目标
• --timeout <seconds>：覆盖智能体超时时间（默认为 600 秒或 agents.defaults.timeoutSeconds）；0 表示禁用超时
• --json：输出 JSON

示例

openclaw agent --to +15555550123 --message "status update" --deliveropenclaw agent --agent ops --message "Summarize logs"openclaw agent --agent ops --message-file ./task.mdopenclaw 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 mediumopenclaw agent --to +15555550123 --message "Trace logs" --verbose on --jsonopenclaw 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 编码的文件会被拒绝。
• 斜杠命令（例如 /compact）无法通过 --message 运行。CLI 会拒绝此类命令，并指引你改用对应的一级命令（压缩操作使用 openclaw sessions compact <key>）。
• --local 和嵌入式回退运行均为一次性运行：本次运行打开的内置 MCP loopback 资源和预热的 Claude stdio 会话会在回复后关闭，因此脚本调用不会留下本地子进程继续运行。使用 Gateway 网关的运行则会在运行中的 Gateway 网关进程内保留由其管理的 MCP loopback 资源。
• 同时使用 --agent、--channel 和 --to 时，会话路由遵循渠道的规范接收方和 session.dmScope。具有稳定的仅出站接收方身份的渠道使用由提供商管理的会话，该会话与智能体的主会话隔离。--reply-channel 和 --reply-account 仅影响投递。
• --session-key 用于选择显式会话键。带智能体前缀的键必须采用 agent:<agent-id>:<session-key> 格式；同时提供两者时，--agent 必须与键中的智能体 ID 匹配。提供 --agent 时，不带前缀且并非哨兵值的键归属于该智能体；否则归属于已配置的默认智能体。例如，--agent ops --session-key incident-42 会路由至 agent:ops:incident-42。仅当未提供 --agent 时，字面键 global 和 unknown 才保持无作用域状态。
• --json 会保留 stdout 用于输出 JSON 响应；Gateway 网关、插件和嵌入式回退的诊断信息会写入 stderr，以便脚本直接解析 stdout。
• 嵌入式回退 JSON 包含 meta.transport: "embedded" 和 meta.fallbackFrom: "gateway"，便于脚本检测回退运行。
• 如果 Gateway 网关接受了运行，但 CLI 在等待最终回复时超时，嵌入式回退会使用全新的 gateway-fallback-* 会话/运行 ID，并报告 meta.fallbackReason: "gateway_timeout" 及回退会话字段，而不会与 Gateway 网关管理的记录争用或静默替换原始会话。
• SIGTERM/SIGINT 会中断正在等待的、由 Gateway 网关支持的请求；如果 Gateway 网关已接受运行，CLI 还会在退出前针对该运行 ID 发送 chat.abort。--local 和嵌入式回退运行会收到相同信号，但不会发送 chat.abort。如果内部运行去重键已存在该会话的活动运行，响应会报告 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 投递状态

使用 --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：来自持久投递或预检验证的小写蛇形命名原因。已知值包括 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 参考
• 智能体运行时