Agent 发送

openclaw agent 从命令行运行单个 agent 轮次，无需入站聊天消息。可用于脚本化工作流、测试和编程式交付。完整标志和行为参考：Agent CLI 参考。

对于需要自行管理设置、清理、输出呈现和进程状态的严格、临时性 CI 或编码自动化，请使用 openclaw agent exec。

快速开始¶

1. 运行一个简单的 agent 轮次

openclaw agent --agent main --message "What is the weather today?"

通过 Gateway 发送消息并打印回复。

2. 从文件发送多行提示

openclaw agent --agent ops --message-file ./task.md

将有效的 UTF-8 文件读取为 agent 消息正文。

3. 指定特定的 agent 或会话

# Target a specific agent
openclaw agent --agent ops --message "Summarize logs"

# Target a phone number (derives session key)
openclaw agent --to +15555550123 --message "Status update"

# Reuse an existing session
openclaw agent --session-id abc123 --message "Continue the task"

# Target an exact session key
openclaw agent --session-key agent:ops:incident-42 --message "Summarize status"

4. 将回复投递到频道

# Deliver to WhatsApp (default channel)
openclaw agent --to +15555550123 --message "Report ready" --deliver

# Deliver to Slack
openclaw agent --agent ops --message "Generate report" \
  --deliver --reply-channel slack --reply-to "#reports"

标志¶

标志	描述
`--message <text>`	要发送的内联消息
`--message-file <path>`	从有效的 UTF-8 文件中读取消息（最大 4 MiB）
`--to <dest>`	从目标（电话号码、聊天 ID）派生会话密钥
`--session-key <key>`	使用显式会话密钥
`--agent <id>`	指定已配置的 agent（使用其 `main` 会话）
`--session-id <id>`	按 ID 复用现有会话
`--model <id>`	为本次运行覆盖模型（`provider/model` 或模型 ID）
`--local`	强制使用本地嵌入式运行时（跳过 Gateway）
`--deliver`	将回复发送到聊天频道
`--channel <name>`	投递频道；与 `--agent` + `--to` 一起使用时，也适用于 DM 作用域
`--reply-to <target>`	覆盖投递目标
`--reply-channel <name>`	覆盖投递频道
`--reply-account <id>`	覆盖投递账户 ID
`--thinking <level>`	为所选模型配置文件设置思考级别
`--verbose <on\\|full\\|off>`	持久化会话的详细级别（`full` 还记录工具输出）
`--timeout <seconds>`	覆盖 agent 超时（默认 600，或配置值）
`--json`	输出结构化 JSON

行为¶

默认情况下，CLI 会通过 Gateway 运行。添加 --local 可强制在当前机器上使用嵌入式运行时。
必须且只能传入 --message 或 --message-file 之一。文件消息会在移除可选的 UTF-8 BOM 后保留多行内容。大于 4 MiB 的文件会在分发前被拒绝。
在短暂的握手重试之后，如果 Gateway 超时或连接关闭，命令将失败并在 stderr 中给出提示；CLI 绝不会静默地在嵌入式运行时中重跑该轮次。Gateway 可能仍会完成已接受的轮次，因此在重试或使用 --local 重跑之前，请确认 Gateway 和会话状态。
会话选择：--to 派生会话密钥（群组/频道目标保持隔离；直接聊天归并为 main）。当 --agent、--channel 和 --to 一起使用时，路由遵循该频道的规范接收者和 session.dmScope。稳定的纯出站身份使用由提供方拥有的会话，与 agent 的主会话隔离。
--session-key 选择一个显式键。以 agent 为前缀的键必须使用 agent:<agent-id>:<session-key> 格式，并且当同时提供两者时，--agent 必须与该 agent ID 匹配。未加前缀的非哨兵键在提供 --agent 时作用域限定到该 agent；例如，--agent ops --session-key incident-42 路由到 agent:ops:incident-42。如果不提供 --agent，未加前缀的非哨兵键作用域限定到已配置的默认 agent。仅当未提供 --agent 时，字面量 global 和 unknown 才保持无作用域。
--reply-channel 和 --reply-account 仅影响投递。
思考级别和详细级别标志会持久化到会话存储中。
输出：默认纯文本，或使用 --json 输出结构化数据负载和元数据。
使用 --json --deliver 时，JSON 会包含已发送、已抑制、部分发送和失败发送的投递状态。参见 JSON 投递状态。

示例¶

# Simple turn with JSON output
openclaw agent --to +15555550123 --message "Trace logs" --verbose on --json

# Turn with a model override
openclaw agent --agent ops --model openai/gpt-5.4 --message "Summarize logs"

# Turn with thinking level
openclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium

# Multiline prompt from a file
openclaw agent --agent ops --message-file ./task.md

# Exact session key
openclaw agent --session-key agent:ops:incident-42 --message "Summarize status"

# Bare key scoped to an agent
openclaw agent --agent ops --session-key incident-42 --message "Summarize status"

# Deliver to a different channel than the session
openclaw agent --agent ops --message "Alert" --deliver --reply-channel telegram --reply-to "@admin"