OpenClaw中Shell Tool使用教学:命令执行、输出读取和长任务管理

Shell Tool 是 OpenClaw 从“会聊天”变成“能改项目、跑测试、查日志”的关键能力。

不过，shell 也是最容易被误用的工具，没有之一。

一条命令可能只是在做简单的文本搜索：

rg "TODO" .

但也可能瞬间修改文件、删除目录、启动服务、写入数据库，甚至长期占用一个进程。

所以理解 Shell Tool，重点不在于“能不能执行命令”，而是要弄清楚几个核心问题：

命令到底在哪里执行？
输出是怎么返回的？
长任务又该如何管理？
权限和 approval 在什么时候介入？
以及，什么时候该用 process，而不是反复轮询？

先说结论：exec 负责启动，process 负责管理长任务

OpenClaw 的 shell 能力，本质上分成了两个清晰层次：

exec
  启动命令，返回前台输出，或者把长任务转为后台 session

process
  管理后台 session：包括 list、poll、log、write、send-keys、kill、clear

典型的执行流程如下：

模型决定需要 shell
  ↓
OpenClaw 检查工具 policy、host、sandbox、approval
  ↓
exec 启动命令
  ↓
短命令直接返回 stdout/stderr/exit code
  ↓
长命令返回 running + sessionId + tail
  ↓
后续通过 process 读取日志、发送输入或终止任务

exec 不是只读工具

官方文档明确提醒过：exec 是 mutating shell surface。即便是禁用了 write、edit、apply_patch，也绝不意味着 exec 就是只读的。

原因很简单：

echo "x" > file.txt
rm -rf build
python migrate.py
npm install

这些操作都能通过 shell 改变系统状态。

所以千万别把“只允许 exec”理解成安全。这是两码事。

host：命令究竟跑在哪里

exec 的 host 可以有多种选择：

auto
sandbox
gateway
node

默认 auto 的含义其实很直观：

如果当前 session 有 sandbox runtime
  就走 sandbox

否则
  就走 gateway host

这一点至关重要。官方文档也强调过：sandboxing 默认是关闭的。如果没有开启 sandbox，host=auto 最终会解析到 Gateway host。

所以排查 shell 行为的时候，不妨先问自己几个问题：

当前命令是跑在 sandbox 里，还是直接跑在宿主机上？
workdir 是哪里？
有没有显式指定 host=node？
是否启用了 elevated？

输出读取：stdout、stderr、tail 和 exit code

短命令通常直接返回：

stdout
stderr
exit code
duration

长命令如果超过了 yieldMs，就会被转到后台，并返回：

status: running
sessionId
short tail

之后就可以使用：

process poll
  读取新增输出，并报告是否退出

process log
  读取聚合日志，支持 offset/limit

process list
  查看当前 agent 的后台 session

有一点需要特别留意：后台 session 是保存在内存里的，不是永久任务数据库。Gateway 一旦重启，它们就会丢失。

长任务不要用 sleep 循环模拟调度

官方文档说得非常明确：如果任务是“现在开始的长任务”，启动一次就好，然后用自动 completion wake 或 process 来管理。

如果任务是“以后再做”或者“定时执行”，应该用 cron，而不是靠：

sleep 3600 && do-something

或者让 Agent 反复去 poll。

合理的做法应该是：

长构建 / 长测试
  exec background 或 yieldMs
  通过 process poll/log 查看状态

未来任务 / 定时任务
  使用 cron / automation

TTY 和 stdin

有些 CLI 工具确实需要 TTY 或交互式输入。

这种情况下，可以尝试：

exec pty: true
process write
process send-keys
process submit
process paste

但有一点必须警惕：不要让 Agent 盲目输入密码、验证码，或者其他不可审计的内容。遇到登录、审批、2FA 这类操作，最好交给人工确认，或者用专门的工具来处理。

权限和 approvals

Shell 的安全是由多层机制共同保障的：

tool policy
sandbox
host selection
exec approvals
allowlist / safe bins
ask fallback
OS filesystem permission

当 approvals 需要人工确认时，exec 可能会先返回：

status: approval-pending
approval id

等到批准之后，命令才会真正执行。

一个真实场景

用户说：

跑一下测试，失败的话帮我定位原因。

合理的执行链路应该是：

1. exec: npm test，yieldMs=1000
2. 命令转入后台，获得 sessionId
3. process poll：读取失败输出
4. exec: rg 失败测试名
5. read/edit/apply_patch：必要时修改文件
6. exec: npm test -- targeted
7. 最后总结改动和验证结果

不要一开始就贸然跑危险命令，也不要在测试还在运行时再开启第二个重复测试。

常见误解

事实并非如此。它可以修改文件和系统状态。

不会。它是内存态的，Gateway 重启就会丢失。

没必要。应该用 completion wake、process 读取，未来任务则用 cron。

不建议把 Python、Node、Bash 这类解释器当成普通 safe bin。它们可以加载任意代码，通常需要更严格的 approval 机制。

最后总结

Shell Tool 的核心在于“可控执行”。

一句话总结就是：exec 启动命令，process 管理长任务，approval 和 sandbox 限制风险，日志和 exit code 负责验证结果。

1. 写出一个短命令和一个长命令分别应该如何调用。
2. 解释 host=auto 在 sandbox 开启/关闭时的差异。
3. 设计一个测试失败排查流程，至少包含 exec 和 process poll。
4. 列出三个不应该自动执行的 shell 命令。