> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 智能体发送

`openclaw agent` 从命令行运行单个智能体轮次，无需入站聊天消息。可将其用于脚本化工作流、测试和程序化投递。完整标志和行为参考：
[智能体 CLI 参考](/zh-CN/cli/agent)。

## 快速开始

<Steps>
  <Step title="运行一个简单的智能体轮次">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw agent --agent main --message "What is the weather today?"
    ```

    通过 Gateway 网关发送消息并打印回复。
  </Step>

  <Step title="从文件发送多行提示">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw agent --agent ops --message-file ./task.md
    ```

    将有效的 UTF-8 文件作为智能体消息正文读取。
  </Step>

  <Step title="指定特定智能体或会话">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    # 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"
    ```
  </Step>

  <Step title="将回复投递到渠道">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    # 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"
    ```
  </Step>
</Steps>

## 标志

| 标志                          | 描述                                      |
| --------------------------- | --------------------------------------- |
| `--message <text>`          | 要发送的内联消息                                |
| `--message-file <path>`     | 从有效的 UTF-8 文件读取消息                       |
| `--to <dest>`               | 从目标（电话、聊天 ID）派生会话键                      |
| `--session-key <key>`       | 使用显式会话键                                 |
| `--agent <id>`              | 指定已配置的智能体（使用其 `main` 会话）                |
| `--session-id <id>`         | 按 ID 复用现有会话                             |
| `--model <id>`              | 本次运行的模型覆盖（`provider/model` 或模型 ID）      |
| `--local`                   | 强制使用本地嵌入式运行时（跳过 Gateway 网关）             |
| `--deliver`                 | 将回复发送到聊天渠道                              |
| `--channel <name>`          | 投递渠道（discord、slack、telegram、whatsapp 等） |
| `--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 后保留多行内容。
* 如果 Gateway 网关请求失败，CLI 会**回退**到本地嵌入式运行；Gateway 网关超时会使用新的会话回退，而不是与原始转录竞争。
* 会话选择：`--to` 派生会话键（群组/渠道目标会保留隔离；直接聊天会折叠为 `main`）。
* `--session-key` 选择显式键。带智能体前缀的键必须使用 `agent:<agent-id>:<session-key>`，并且同时提供 `--agent` 时，它必须匹配该智能体 ID。未带哨兵的裸键会在提供 `--agent` 时限定到该智能体；例如，`--agent ops --session-key incident-42` 会路由到 `agent:ops:incident-42`。如果没有 `--agent`，未带哨兵的裸键会限定到已配置的默认智能体。字面值 `global` 和 `unknown` 仅在未提供 `--agent` 时保持未限定；嵌入式回退路径会将这些哨兵会话解析到已配置的默认智能体。
* `--channel`、`--reply-channel` 和 `--reply-account` 影响回复投递，而不是会话路由。
* 思考和详细标志会持久化到会话存储中。
* 输出：默认是纯文本，或使用 `--json` 输出结构化载荷 + 元数据。
* 使用 `--json --deliver` 时，JSON 会包含已发送、已抑制、部分发送和发送失败的投递状态。参见
  [JSON 投递状态](/zh-CN/cli/agent#json-delivery-status)。

## 示例

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 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"

# Legacy 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"
```

## 相关

<CardGroup cols={2}>
  <Card title="智能体 CLI 参考" href="/zh-CN/cli/agent" icon="terminal">
    完整的 `openclaw agent` 标志和选项参考。
  </Card>

  <Card title="子智能体" href="/zh-CN/tools/subagents" icon="users">
    后台子智能体生成。
  </Card>

  <Card title="会话" href="/zh-CN/concepts/session" icon="comments">
    会话键如何工作，以及 `--to`、`--agent` 和 `--session-id` 如何解析它们。
  </Card>

  <Card title="斜杠命令" href="/zh-CN/tools/slash-commands" icon="slash">
    智能体会话内使用的原生命令目录。
  </Card>
</CardGroup>