跳轉到主要內容
OpenClaw 透過 exec 工具執行 shell 命令，並將長時間執行的工作保留在記憶體中。process 工具會管理這些背景工作階段。

​
exec 工具

參數：
參數說明
command必填。要執行的 shell 命令。
workdir工作目錄；省略時使用預設 cwd。
env命令的額外環境變數。
yieldMs背景化前等待的毫秒數（預設 10000）。
background立即在背景執行。
timeout逾時秒數（預設 tools.exec.timeoutSec）；到期時終止程序。設定 timeout: 0 可停用該次呼叫的 exec 程序逾時。
pty可用時在偽終端機中執行（需要 TTY 的命令列介面、程式撰寫代理）。
elevated如果已啟用/允許提升模式，則在沙箱外執行（預設為 gateway，或當 exec 目標為 node 時使用 node）。
hostExec 目標：auto、sandbox、gateway 或 node。
node節點 ID/名稱，搭配 host: "node" 使用。
行為：
  • 前景執行會直接傳回輸出。
  • 當背景化時（明確指定或透過 yieldMs 逾時），工具會傳回 status: "running" + sessionId 以及簡短的輸出尾端。
  • 背景化和 yieldMs 執行會繼承 tools.exec.timeoutSec，除非該次呼叫傳入明確的 timeout。
  • 輸出會保留在記憶體中，直到工作階段被輪詢或清除。
  • 如果不允許使用 process 工具，exec 會同步執行並忽略 yieldMs/background。
  • 產生的 exec 命令會收到 OPENCLAW_SHELL=exec，用於具備情境感知的 shell/profile 規則。
  • 對於現在開始的長時間工作：只啟動一次，並在命令產生輸出或失敗後，仰賴自動完成喚醒（若已啟用）。
  • 如果自動完成喚醒不可用，或你需要確認一個乾淨結束但沒有輸出的命令是否靜默成功，請使用 process 輪詢。
  • 不要用 sleep 迴圈或重複輪詢來模擬提醒或延遲後續動作 —— 未來工作請使用排程。

​
環境覆寫

變數效果
OPENCLAW_BASH_YIELD_MS背景化前的預設等待時間（毫秒）。預設 10000，限制在 10-120000。
OPENCLAW_BASH_MAX_OUTPUT_CHARS記憶體內輸出上限（字元）。
OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS每個串流的待處理 stdout/stderr 上限（字元）。
OPENCLAW_BASH_JOB_TTL_MS已完成工作階段的 TTL（毫秒），限制在 1 分鐘到 3 小時。
OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS可寫入背景工作階段被標記為可能正在等待輸入前的閒置輸出門檻。預設 15000。

​
設定（優先於環境覆寫）

鍵預設效果
tools.exec.backgroundMs10000與 OPENCLAW_BASH_YIELD_MS 相同。
tools.exec.timeoutSec1800每次呼叫的預設逾時。
tools.exec.cleanupMs1800000與 OPENCLAW_BASH_JOB_TTL_MS 相同。
tools.exec.notifyOnExittrue當背景化的 exec 結束時，將系統事件排入佇列並請求心跳偵測。
tools.exec.notifyOnExitEmptySuccessfalse也為沒有輸出的成功背景執行排入完成事件。

​
子程序橋接

在 exec/process 工具外產生長時間執行的子程序時（命令列介面重新啟動、閘道輔助程式），請附加子程序橋接輔助程式，讓終止訊號能轉送，並在結束/錯誤時卸離監聽器。這可避免 systemd 上出現孤兒程序，並讓各平台的關閉行為保持一致。

​
process 工具

動作：
動作效果
list執行中 + 已完成的工作階段。
poll擷取工作階段的新輸出（也會回報結束狀態）。
log讀取彙總輸出和輸入復原提示。支援 offset + limit。
write傳送 stdin（data，可選 eof）。
send-keys將明確的按鍵 token 或位元組傳送到以 PTY 為基礎的工作階段。
submit將 Enter/歸位字元傳送到以 PTY 為基礎的工作階段。
paste傳送純文字，可選擇包在 bracketed paste 模式中。
kill終止背景工作階段。
clear從記憶體中移除已完成的工作階段。
remove若正在執行則終止，否則在已完成時清除。
注意事項：
  • 只有背景化的工作階段會被列出/持久保留 —— 僅在記憶體中，不會寫入磁碟。程序重新啟動後工作階段會遺失。
  • 只有在你執行 process poll/log 且工具結果被記錄時，工作階段記錄才會儲存到聊天歷史。
  • process 以每個代理為範圍；它只看得到該代理啟動的工作階段。
  • 當自動完成喚醒不可用時，使用 poll/log 取得狀態、記錄或完成確認。
  • 在復原互動式命令列介面前使用 log，讓目前逐字稿、stdin 狀態和輸入等待提示能一起顯示。
  • 需要輸入或介入時，使用 write/send-keys/submit/paste/kill。
  • process list 包含衍生的 name（命令動詞 + 目標），便於快速掃描。
  • process list、poll 和 log 只會在工作階段仍有可寫入的 stdin，且閒置時間超過輸入等待門檻時，回報 waitingForInput（預設 15000 ms，OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS）。
  • process log 使用以行為基礎的 offset/limit。兩者都省略時，會傳回最後 200 行並附上分頁提示。設定 offset 但未設定 limit 時，會從 offset 傳回到結尾（不限制為 200）。
  • poll 的 timeout 最多等待指定毫秒數後傳回；超過 30000 的值會被限制為 30000。
  • 輪詢用於隨需狀態，而不是等待迴圈排程。如果工作應該稍後發生，請使用排程。

​
範例

執行長工作並稍後輪詢： 
{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }

{ "tool": "process", "action": "poll", "sessionId": "<id>" }
在傳送輸入前檢查互動式工作階段： 
{ "tool": "process", "action": "log", "sessionId": "<id>" }
立即在背景啟動： 
{ "tool": "exec", "command": "npm run build", "background": true }
傳送 stdin： 
{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }
傳送 PTY 按鍵： 
{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }
送出目前行： 
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
貼上純文字： 
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

​
相關