OpenClaw 進程監控指南：實現可靠的生命週期管理

你有沒有遇過這種情況？在開發長運行的後台任務或 CLI 工具時，最頭痛的就是進程（Process）管理。有時候進程殺不掉，有時候超時處理亂七八糟，甚至還會留下孤兒進程。

這篇文章要聊聊我們如何透過 PTY 與進程監管（Process Supervision）來解決這些問題，讓你的系統運行得更穩。

1. 問題與目標

我們需要為跨多個場景的長運行命令執行提供一個可靠的生命週期管理：

• exec 前台執行
• exec 後台執行
• process 後續動作（poll, log, send-keys, paste, submit, kill, remove）
• CLI agent runner 的子進程

目標不只是支援 PTY，而是要確保所有權、取消機制、超時和清理都是可預測的，不再依賴不安全的進程匹配啟發式算法。

2. 範圍與界限

• 將實作保持在 src/process/supervisor 內部。
• 不要為此建立新的 package。
• 在可行範圍內保持與目前行為的相容性。
• 不要將範圍擴大到終端回放或 tmux 風格的會話持久化。

3. 此分支已實作的內容

Supervisor 基礎已就緒

• Supervisor 模組已在 src/process/supervisor/* 就位。
• Exec runtime 和 CLI runner 已經透過 supervisor 的 spawn 和 wait 進行路由。
• Registry 的最終化（finalization）是冪等的。

此階段完成的內容

1. 明確的 PTY 命令契約

• SpawnInput 現在是 src/process/supervisor/types.ts 中的一個 discriminated union。
• PTY 運行現在要求使用 ptyCommand，而不是重複使用通用的 argv。
• Supervisor 不再於 src/process/supervisor/supervisor.ts 中透過 argv join 來重新構建 PTY 命令字串。
• Exec runtime 現在直接在 src/agents/bash-tools.exec-runtime.ts 中傳遞 ptyCommand。

2. 進程層類型解耦

• Supervisor 類型不再從 agents 導入 SessionStdin。
• 進程本地的 stdin 契約定義在 src/process/supervisor/types.ts (ManagedRunStdin)。
• Adapter 現在僅依賴於進程層級的類型：
  • src/process/supervisor/adapters/child.ts
  • src/process/supervisor/adapters/pty.ts

3. 進程工具生命週期所有權改進

• src/agents/bash-tools.process.ts 現在會先透過 supervisor 請求取消。
• process kill/remove 在 supervisor 查找不到時，會使用 process-tree 回退機制來終止進程。
• remove 透過在請求終止後立即刪除運行的 session 條目，保持了確定的刪除行為。

4. 單一來源的 Watchdog 預設值

• 在 src/agents/cli-watchdog-defaults.ts 中添加了共享的預設值。
• src/agents/cli-backends.ts 使用這些共享預設值。
• src/agents/cli-runner/reliability.ts 使用相同的共享預設值。

5. 廢棄 Helper 清理

• 從 src/agents/bash-tools.shared.ts 中移除了未使用的 killSession helper 路徑。

6. 新增直接 Supervisor 路徑測試

• 新增 src/agents/bash-tools.process.supervisor.test.ts，涵蓋透過 supervisor 取消來進行 kill 和 remove 的路由。

7. 可靠性缺口修復完成

• src/agents/bash-tools.process.ts 在 supervisor 查找不到時，現在會回退到真實的 OS 層級進程終止。
• src/process/supervisor/adapters/child.ts 現在針對預設的取消/超時 kill 路徑使用 process-tree 終止語義。
• 在 src/process/kill-tree.ts 中新增了共享的 process-tree 工具。

8. 新增 PTY 契約邊緣情況覆蓋

• 為逐字 PTY 命令轉發和空命令拒絕新增了 src/process/supervisor/supervisor.pty-command.test.ts。
• 為 child adapter 取消中的 process-tree kill 行為新增了 src/process/supervisor/adapters/child.test.ts。

4. 剩餘差距與決策

可靠性狀態

此階段要求的兩個可靠性缺口現已關閉：

• process kill/remove 在 supervisor 查找不到時，現在有真實的 OS 終止回退機制。
• child 取消/超時現在針對預設 kill 路徑使用 process-tree kill 語義。
• 已為這兩種行為新增回歸測試。

持久性與啟動對齊

重啟行為現在被明確定義為僅限記憶體內的生命週期。

• reconcileOrphans() 在 src/process/supervisor/supervisor.ts 中按設計保持為 no-op。
• 進程重啟後不會恢復活動中的運行。
• 這個界限是此實作階段刻意設定的，以避免部分持久化帶來的風險。

維護性後續

1. src/agents/bash-tools.exec-runtime.ts 中的 runExecProcess 仍然承擔多項職責，可以在後續拆分為專注的 helper。

5. 實作計畫

要求可靠性和契約項目的實作階段已完成。

已完成：

• process kill/remove 回退真實終止
• child adapter 預設 kill 路徑的 process-tree 取消
• 回退 kill 和 child adapter kill 路徑的回歸測試
• 明確 ptyCommand 下的 PTY 命令邊緣情況測試
• 設計上 reconcileOrphans() 為 no-op 的明確記憶體內重啟界限

可選後續：

• 將 runExecProcess 拆分為專注的 helper，且不產生行為偏差

6. 檔案映射

Process supervisor

• src/process/supervisor/types.ts 已更新，包含 discriminated spawn input 和進程本地 stdin 契約。
• src/process/supervisor/supervisor.ts 已更新，使用明確的 ptyCommand。
• src/process/supervisor/adapters/child.ts 與 src/process/supervisor/adapters/pty.ts 已與 agent 類型解耦。
• src/process/supervisor/registry.ts 冪等最終化保持不變並保留。

Exec 與進程整合

• src/agents/bash-tools.exec-runtime.ts 已更新，明確傳遞 PTY 命令並保留回退路徑。
• src/agents/bash-tools.process.ts 已更新，透過 supervisor 取消，並帶有真實的 process-tree 回退終止。
• src/agents/bash-tools.shared.ts 移除了直接的 kill helper 路徑。

CLI 可靠性

• src/agents/cli-watchdog-defaults.ts 作為共享基準新增。
• src/agents/cli-backends.ts 與 src/agents/cli-runner/reliability.ts 現在使用相同的預設值。

7. 此階段的驗證執行

單元測試：

pnpm vitest src/process/supervisor/registry.test.ts
pnpm vitest src/process/supervisor/supervisor.test.ts
pnpm vitest src/process/supervisor/supervisor.pty-command.test.ts
pnpm vitest src/process/supervisor/adapters/child.test.ts
pnpm vitest src/agents/cli-backends.test.ts
pnpm vitest src/agents/bash-tools.exec.pty-cleanup.test.ts
pnpm vitest src/agents/bash-tools.process.poll-timeout.test.ts
pnpm vitest src/agents/bash-tools.process.supervisor.test.ts
pnpm vitest src/process/exec.test.ts

E2E 目標：

pnpm vitest src/agents/cli-runner.test.ts
pnpm vitest run src/agents/bash-tools.exec.pty-fallback.test.ts src/agents/bash-tools.exec.background-abort.test.ts src/agents/bash-tools.process.send-keys.test.ts

類型檢查備註：

• 在此 repo 中使用 pnpm build（以及用於完整 lint/docs 門禁的 pnpm check）。提到 pnpm tsgo 的舊備註已過時。

8. 保留的運作保證

• Exec 環境硬化行為保持不變。
• 審核與白名單流程保持不變。
• 輸出淨化和輸出上限保持不變。
• PTY adapter 仍然保證在強制 kill 和 listener 銷毀時完成等待結算。

9. 完成的定義

1. Supervisor 是受管運行的生命週期所有者。
2. PTY spawn 使用明確的命令契約，不進行 argv 重建。
3. 進程層對於 supervisor stdin 契約沒有 agent 層的類型依賴。
4. Watchdog 預設值為單一來源。
5. 針對性的單元測試和 e2e 測試保持綠燈。
6. 重啟持久性界限已明確記錄或完全實作。

10. 總結

該分支現在具有一致且更安全的監管形態：

• 明確的 PTY 契約
• 更乾淨的進程分層
• 進程操作由 supervisor 驅動的取消路徑
• supervisor 查找不到時的真實回退終止
• child-run 預設 kill 路徑的 process-tree 取消
• 統一的 watchdog 預設值
• 明確的記憶體內重啟界限（此階段重啟時不進行孤兒進程對齊）

如果你在實作過程中遇到任何問題，隨時找 AI Setup Assistant 聊聊！

下一步

• 查看 Process Supervisor 原始碼
• 了解 CLI Watchdog 配置