本页内容

本页内容

代理协调

Agent 发送

openclaw agent 会从命令行运行一个单独的 agent 回合,而不需要传入聊天消息。可用于脚本化工作流、测试以及程序化投递。完整的标志和行为参考: Agent CLI 参考。

对于严格、短暂的 CI 或代码自动化场景,如果需要自行负责设置、清理、 输出投影以及进程状态,请使用 openclaw agent exec。

快速开始

  • 运行一个简单的代理回合

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

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

  • 从文件发送多行提示

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

    读取一个有效的 UTF-8 文件作为 agent 消息体。

  • 定位特定代理或会话

    bash
    # Target a specific agentopenclaw agent --agent ops --message "Summarize logs" # Target a phone number (derives session key)openclaw agent --to +15555550123 --message "Status update" # Reuse an existing sessionopenclaw agent --session-id abc123 --message "Continue the task" # Target an exact session keyopenclaw agent --session-key agent:ops:incident-42 --message "Summarize status"
  • 将回复发送到频道

    bash
    # Deliver to WhatsApp (default channel)openclaw agent --to +15555550123 --message "Report ready" --deliver # Deliver to Slackopenclaw 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> 目标为已配置的代理(使用其 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> 覆盖代理超时时间(默认 600,或配置值)
    --json 输出结构化 JSON

    行为

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

    示例

    bash
    # Simple turn with JSON outputopenclaw agent --to +15555550123 --message "Trace logs" --verbose on --json # Turn with a model overrideopenclaw agent --agent ops --model openai/gpt-5.4 --message "Summarize logs" # Turn with thinking levelopenclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium # Multiline prompt from a fileopenclaw agent --agent ops --message-file ./task.md # Exact session keyopenclaw agent --session-key agent:ops:incident-42 --message "Summarize status" # Bare key scoped to an agentopenclaw agent --agent ops --session-key incident-42 --message "Summarize status" # Deliver to a different channel than the sessionopenclaw agent --agent ops --message "Alert" --deliver --reply-channel telegram --reply-to "@admin"

    相关内容

    本页有帮助吗?