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 重启后，这些 session 会全部丢失。
长任务不要用 sleep 循环模拟调度
官方文档明确指出：如果任务是“从现在开始执行的长任务”，启动一次即可，然后通过自动 completion wake 或 process 来跟踪。
如果任务是“以后执行”或“定时触发”，应使用 cron，而不是靠：
sleep 3600 && do-something
或者让 Agent 反复轮询。
合理的设计方案是：
长构建 / 长测试 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 负责验证结果。
本节作业
- 写出一个短命令和一个长命令分别应该如何调用。
- 解释
host=auto在 sandbox 开启/关闭时的差异。 - 设计一个测试失败排查流程，至少包含
exec和process poll。 - 列出三个不应该自动执行的 shell 命令。