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. 最后总结改动和验证结果

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

常见误解

误解一：exec 是只读查询工具
事实并非如此。它可以修改文件和系统状态。

误解二：background session 会永久保存
不会。它是内存态的，Gateway 重启就会丢失。

误解三：长任务应该不停 poll
没必要。应该用 completion wake、process 读取，未来任务则用 cron。

误解四：allowlist 可以放心添加解释器
不建议把 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 命令。