Shell Tool 是 OpenClaw 從“會(huì)聊天”變成“能改項(xiàng)目、跑測(cè)試、查日志”的關(guān)鍵能力。

但 shell 也是最容易被誤用的工具。

因?yàn)橐粭l命令可能只是讀?。?/p>

rg "TODO" .

也可能會(huì)修改文件、刪除目錄、啟動(dòng)服務(wù)、寫(xiě)入數(shù)據(jù)庫(kù)，甚至長(zhǎng)期占用進(jìn)程。

所以理解 Shell Tool，重點(diǎn)不是“能不能執(zhí)行命令”，而是：

命令在哪里執(zhí)行？
輸出如何返回？
長(zhǎng)任務(wù)如何管理？
權(quán)限和 approval 如何介入？
什么時(shí)候應(yīng)該用 process，而不是反復(fù)輪詢(xún)？

先說(shuō)結(jié)論：exec 負(fù)責(zé)啟動(dòng)，process 負(fù)責(zé)管理長(zhǎng)任務(wù)

OpenClaw 的 shell 能力 主要分成兩層：

exec
  啟動(dòng)命令，返回前臺(tái)輸出，或把長(zhǎng)任務(wù)轉(zhuǎn)為后臺(tái) session

process
  管理后臺(tái) session：list、poll、log、write、send-keys、kill、clear

典型流程是：

模型決定需要 shell
  ↓
OpenClaw 檢查工具 policy、host、sandbox、approval
  ↓
exec 啟動(dòng)命令
  ↓
短命令直接返回 stdout/stderr/exit code
  ↓
長(zhǎng)命令返回 running + sessionId + tail
  ↓
process 后續(xù)讀取日志、發(fā)送輸入或終止

exec 不是只讀工具

官方文檔明確提醒：exec 是 mutating shell surface。即使禁用了 write、edit、apply_patch，也不代表 exec 只讀。

原因很簡(jiǎn)單：

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

這些都可以通過(guò) shell 改變系統(tǒng)狀態(tài)。

所以不要把“只允許 exec”理解成安全。

host：命令到底在哪運(yùn)行

exec 的 host 可以是：

auto
sandbox
gateway
node

默認(rèn) auto 的含義是：

如果當(dāng)前 session 有 sandbox runtime
  走 sandbox

否則
  走 gateway host

這點(diǎn)非常重要。官方文檔也強(qiáng)調(diào)：sandboxing 默認(rèn)是關(guān)閉的。如果沒(méi)有開(kāi)啟 sandbox，host=auto 會(huì)解析到 Gateway host。

所以排查 shell 行為時(shí)先問(wèn)：

當(dāng)前命令跑在 sandbox 里，還是宿主機(jī)上？
workdir 是哪里？
是否顯式 host=node？
是否啟用了 elevated？

輸出讀?。簊tdout、stderr、tail 和 exit code

短命令通常直接返回：

stdout
stderr
exit code
duration

長(zhǎng)命令如果超過(guò) yieldMs，會(huì)被轉(zhuǎn)到后臺(tái)，并返回：

status: running
sessionId
short tail

之后使用：

process poll
  讀取新增輸出，并報(bào)告是否退出

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

process list
  查看當(dāng)前 agent 的后臺(tái) session

注意：后臺(tái) session 在內(nèi)存里，不是永久任務(wù)數(shù)據(jù)庫(kù)。Gateway 重啟后會(huì)丟失。

長(zhǎng)任務(wù)不要用 sleep 循環(huán)模擬調(diào)度

官方文檔非常明確：如果任務(wù)是“現(xiàn)在開(kāi)始的長(zhǎng)任務(wù)”，啟動(dòng)一次，然后用自動(dòng) completion wake 或 process 管理。

如果任務(wù)是“以后再做”或“定時(shí)做”，應(yīng)該用 cron，而不是：

sleep 3600 && do-something

或者讓 Agent 反復(fù) poll。

合理做法是：

長(zhǎng)構(gòu)建 / 長(zhǎng)測(cè)試
  exec background 或 yieldMs
  process poll/log 查看狀態(tài)

未來(lái)任務(wù) / 定時(shí)任務(wù)
  cron / automation

TTY 和 stdin

有些 CLI 需要 TTY 或交互輸入。

這時(shí)可以：

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

但不要讓 Agent 盲目輸入密碼、驗(yàn)證碼或不可審計(jì)內(nèi)容。遇到登錄、審批、2FA 這類(lèi)動(dòng)作，應(yīng)交給人工確認(rèn)或?qū)ｉT(mén)工具。

權(quán)限和 approvals

Shell 的安全由多層控制：

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

當(dāng) approvals 需要人工確認(rèn)時(shí)，exec 可能先返回：

status: approval-pending
approval id

批準(zhǔn)后才會(huì)真正執(zhí)行。

一個(gè)真實(shí)場(chǎng)景

用戶說(shuō)：

跑一下測(cè)試，失敗的話幫我定位原因。

合理鏈路：

1. exec: npm test，yieldMs=1000
2. 命令轉(zhuǎn)后臺(tái)，得到 sessionId
3. process poll：讀取失敗輸出
4. exec: rg 失敗測(cè)試名
5. read/edit/apply_patch：必要時(shí)修改文件
6. exec: npm test -- targeted
7. 總結(jié)改動(dòng)和驗(yàn)證結(jié)果

不要一開(kāi)始就跑危險(xiǎn)命令，也不要在測(cè)試還運(yùn)行時(shí)開(kāi)啟第二個(gè)重復(fù)測(cè)試。

常見(jiàn)誤解

誤解一：exec 是只讀查詢(xún)工具

不是。它可以修改文件和系統(tǒng)狀態(tài)。

誤解二：background session 會(huì)永久保存

不會(huì)。它是內(nèi)存態(tài)，Gateway 重啟會(huì)丟失。

誤解三：長(zhǎng)任務(wù)應(yīng)該不停 poll

不應(yīng)該。用 completion wake、process 讀取，未來(lái)任務(wù)用 cron。

誤解四：allowlist 可以放心加解釋器

不建議把 Python、Node、Bash 這類(lèi)解釋器當(dāng)普通 safe bin。它們可以加載任意代碼，通常需要更嚴(yán)格 approval。

最后總結(jié)

Shell Tool 的核心是“可控執(zhí)行”。

一句話總結(jié)：exec 啟動(dòng)命令，process 管理長(zhǎng)任務(wù)，approval 和 sandbox 限制風(fēng)險(xiǎn)，日志和 exit code 負(fù)責(zé)驗(yàn)證結(jié)果。

本節(jié)作業(yè)

1. 寫(xiě)出一個(gè)短命令和一個(gè)長(zhǎng)命令分別應(yīng)該如何調(diào)用。
2. 解釋 host=auto 在 sandbox 開(kāi)啟/關(guān)閉時(shí)的差異。
3. 設(shè)計(jì)一個(gè)測(cè)試失敗排查流程，至少包含 exec 和 process poll。
4. 列出三個(gè)不應(yīng)該自動(dòng)執(zhí)行的 shell 命令。

到此這篇關(guān)于OpenClaw中Shell Tool使用教學(xué):命令執(zhí)行、輸出讀取和長(zhǎng)任務(wù)管理的文章就介紹到這了,更多相關(guān)OpenClaw Shell Tool用法內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！

最新評(píng)論