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

# 后台 exec 和 process 工具

OpenClaw 通过 `exec` 工具运行 shell 命令，并将长时间运行的任务保存在内存中。`process` 工具用于管理这些后台会话。

## exec 工具

参数：

| 参数               | 描述                                                                                             |
| ---------------- | ---------------------------------------------------------------------------------------------- |
| `command`        | 必需。要运行的 Shell 命令。                                                                              |
| `workdir`        | 工作目录；省略则使用默认 cwd。                                                                              |
| `env`            | 为命令设置的额外环境变量。                                                                                  |
| `yieldMs`        | 在转入后台前等待的毫秒数（默认 10000）。                                                                        |
| `background`     | 立即在后台运行。                                                                                       |
| `timeoutSeconds` | 超时时间（以秒为单位，默认为 `tools.exec.timeoutSeconds`）；超时后终止进程。将 `timeoutSeconds` 设置为 0 可禁用此次 exec 进程的超时。 |
| `pty`            | 在可用时于伪终端中运行（需要 TTY 的 CLI、编码代理）。                                                                |
| `elevated`       | 如果启用／允许提升模式，则在沙箱外运行（默认使用 `gateway`，或者当 exec 目标为 `node` 时使用 `node`）。                            |
| `host`           | Exec 目标：`auto`、`sandbox`、`gateway` 或 `node`。                                                   |
| `node`           | 与 `host: "node"` 配合使用的 Node id／名称。                                                             |

行为：

* 前台运行会直接返回保留的输出，并在更早的输出超过聚合上限时予以说明。
* 在后台运行时（显式运行或因 `yieldMs` 超时），工具会返回 `status: "running"`、`sessionId` 以及简短的输出尾部。
* 后台运行和 `yieldMs` 运行会继承 `tools.exec.timeoutSeconds`，除非此次调用传入了明确的 `timeoutSeconds`。
* 输出会一直保存在内存中，直到会话被轮询或清除，但受每个会话的聚合上限限制。
* 已完成的会话会在配置的 TTL 后过期。注册表最多还会保留 50 个已完成会话，以及总计 2,000,000 个保留的输出字符，并优先驱逐最早的记录。即使最新完成的会话记录单独超过全局限制，仍会保留其达到上限的每个会话聚合输出。
* 如果不允许使用 `process` 工具，`exec` 会同步运行，并忽略 `yieldMs`／`background`。
* 生成的 exec 命令会接收 `OPENCLAW_SHELL=exec`，以便执行上下文感知的 shell／配置文件规则。
* 对于现在启动的长时间运行任务：启动一次，并在命令产生输出或失败时依赖自动完成唤醒（启用时）。
* 如果自动完成唤醒不可用，或者需要确认一个成功退出且没有输出的命令，请使用 `process` 进行轮询。
* 不要使用 `sleep` 循环或重复轮询来模拟提醒或延迟后续操作——应使用 cron 处理未来的任务。

### 环境变量覆盖

| Variable                                 | Effect                                                  |
| ---------------------------------------- | ------------------------------------------------------- |
| `OPENCLAW_BASH_YIELD_MS`                 | 后台运行前的默认等待时间（毫秒）。默认 10000，限制在 10–120000 之间。             |
| `OPENCLAW_BASH_MAX_OUTPUT_CHARS`         | 内存中的总输出字符上限。默认 200000，限制在 1000–200000 之间。               |
| `OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS` | 每个流的待处理标准输出／标准错误上限。默认 30000，限制在 1000–200000 之间，并受总上限限制。 |
| `OPENCLAW_BASH_JOB_TTL_MS`               | 已完成会话的 TTL（毫秒），限制在 1 分钟至 3 小时之间。                        |
| `OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS`    | 可写后台会话在被标记为可能正在等待输入前的无输出空闲阈值。默认 15000。                  |

### 配置（优先于环境变量覆盖）

| Key                                   | Default | Effect                           |
| ------------------------------------- | ------- | -------------------------------- |
| `tools.exec.backgroundMs`             | 10000   | 与 `OPENCLAW_BASH_YIELD_MS` 相同。   |
| `tools.exec.timeoutSeconds`           | 1800    | 每次调用的默认超时时间。                     |
| `tools.exec.cleanupMs`                | 1800000 | 与 `OPENCLAW_BASH_JOB_TTL_MS` 相同。 |
| `tools.exec.notifyOnExit`             | true    | 后台 exec 退出时，将系统事件加入队列，并请求发送心跳。   |
| `tools.exec.notifyOnExitEmptySuccess` | false   | 对于无输出且成功完成的后台运行，同样加入完成事件。        |

## 子进程桥接

在 exec/process 工具之外启动长时间运行的子进程（CLI 重启、网关辅助进程）时，请附加子进程桥接辅助程序，以便终止信号能够转发，并在退出/出错时分离监听器。这样可以避免在 systemd 上产生孤儿进程，并保持跨平台的关闭行为一致。

## process 工具

操作：

| 操作          | 作用                                   |
| ----------- | ------------------------------------ |
| `list`      | 运行中 + 已完成的会话。                        |
| `poll`      | 提取某个会话的新输出（也会报告退出状态）。                |
| `log`       | 读取汇总输出和输入恢复提示。支持 `offset` + `limit`。 |
| `write`     | 发送 stdin（`data`，可选 `eof`）。           |
| `send-keys` | 向基于 PTY 的会话发送显式按键标记或字节。              |
| `submit`    | 向基于 PTY 的会话发送 Enter/回车。              |
| `paste`     | 发送字面文本，可选择包裹在 bracketed paste 模式中。   |
| `kill`      | 终止后台会话。                              |
| `clear`     | 从内存中移除已完成的会话。                        |
| `remove`    | 如果正在运行则终止，否则如果已完成则清除。                |

说明：

* 仅会列出/持久化后台会话——仅存于内存中，不会写入磁盘。进程重启后会话将丢失。
* 重置或删除会话只会清除已完成的后台进程；其他会话、显式共享作用域以及正在运行的进程不受影响。
* 正在运行的后台会话会阻止协作式主机挂起和安全的 Gateway 重启，直到进程所有者确认其确实已退出。
* `process remove` 可以在请求终止后立即隐藏正在运行的会话；在确认进程退出之前，挂起和重启仍会被阻止。
* 只有运行 `process poll`/`log` 且工具结果被记录后，会话日志才会保存到聊天记录中。
* `process` 按代理划分作用域；它只能看到由该代理启动的会话。
* 当自动完成唤醒不可用时，使用 `poll`/`log` 获取状态、日志或完成确认。
* 恢复交互式 CLI 之前使用 `log`，以便同时查看当前记录、stdin 状态和输入等待提示。
* 需要输入或干预时，使用 `write`/`send-keys`/`submit`/`paste`/`kill`。
* `process list` 会包含一个派生的 `name`（命令动词 + 目标），便于快速扫描。
* 仅当会话仍有可写入的 stdin，且空闲时间超过输入等待阈值（默认为 15000 毫秒，`OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS`）时，`process list`、`poll` 和 `log` 才会报告 `waitingForInput`。
* `process log` 使用基于行的 `offset`/`limit`。两者均省略时，它会返回最后 200 行并附带分页提示。设置 `offset` 而未设置 `limit` 时，它会从 `offset` 返回到末尾（不会限制为 200 行）。
* `process poll` 和 `process log` 会区分因聚合保留上限而丢弃的输出，以及仅因待处理缓冲区或保留尾部而被省略的输出。被丢弃的输出无法恢复；分页日志只能查看保留的部分。
* `poll` 的 `timeout` 最多等待指定的毫秒数后返回；超过 30000 的值会被限制为 30000。
* 轮询用于按需获取状态，而不是用于循环等待调度。如果工作应在稍后执行，请使用 cron。

## 示例

运行一个长任务并稍后轮询：

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }
```

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "poll", "sessionId": "<id>" }
```

在发送输入前检查一个交互式会话：

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "log", "sessionId": "<id>" }
```

立即在后台启动：

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "exec", "command": "npm run build", "background": true }
```

发送 stdin：

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }
```

发送 PTY 按键：

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }
```

提交当前行：

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
```

粘贴字面文本：

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }
```

## 相关

* [Exec 工具](/tools/exec)
* [Exec 审批](/tools/exec-approvals)