完整搜尋頁面 →

Agent 實務(三):維運 agent harness(以 OpenClaw 為實例)

如何日常運行 agent:工作階段、權限、skills、記憶、排程、復原與可觀測性?

閱讀約 13 分鐘更新於 資料查核於 English

建立一個 agent 循環是一回事,讓 agent 持續好用好幾個月是另一回事。一旦 agent 依自己的排程運行、與多個通道對話並保有記憶,問題就變了:這是哪一段對話?誰可以要求什麼?指令在哪裡執行?重啟後什麼會留下來?出了問題我要怎麼知道?

系列順序: 一 · Agent 如何運作 → 二 · Skills 與 harness → 三 · 維運 agent harness。

下面每一節先說明通用的維運原則,再說明一個開源 harness OpenClaw 如何實作(以標示為 在 OpenClaw 中 的引用段落呈現)。OpenClaw 是實例,不是主題:同樣的問題適用於任何常駐的 agent 執行系統。與版本相關的指令及確切的文件快照,在現行選項。

重點

  • 把運行中的 agent 當作一項服務,有八個維運面向:工作階段、工具、權限、skills、記憶、排程、復原與可觀測性。
  • 把常被混在一起的三個問題分開:誰可以提出要求、哪些行動可以執行,以及這些行動在哪裡執行。
  • 核准提示可以減少意外,但它不是身分驗證邊界,也不是沙箱。
  • 記憶、壓縮、檢查點與 skills 是不同的機制,要分開診斷。
  • 排程需要重複處理政策與寄送紀錄,不能只有計時器。
  • 任何重啟之後,agent 都應先重新檢查現況再繼續,因為它的操作紀錄可能落後於實際發生的事。
  • 記錄足夠的結構化事件(執行、工作階段、工具呼叫、核准、結果、寄送),這樣不必翻對話紀錄就能回答「發生了什麼事?」

維運面向一覽

面向它回答的問題出問題時要檢查什麼
工作階段這則訊息屬於哪段對話與歷史?工作階段鍵、重設政策、待處理輪次的佇列
工具這個 agent 有哪些行動可用?該工作階段實際生效的工具清單,而非設定檔中的清單
權限誰可以提出要求?哪些行動需要核准?寄件者存取權、工具政策、核准紀錄
執行邊界行動實際在哪裡執行?主機、沙箱或遠端裝置;掛載的檔案
Skills有哪些程序可用?是哪個版本?來源優先序、啟用條件、版本
記憶與情境每一輪開始時,agent 知道什麼?載入的記憶檔、壓縮摘要
排程沒有人傳訊息時,什麼在執行?工作定義、執行歷史、寄送結果
復原與可觀測性中斷之後會怎樣?我們怎麼知道?結構化日誌、執行識別碼、重啟紀錄

追蹤一個請求如何通過系統

常駐的 harness 通常有一個長時間運行的 gateway,從各通道(聊天應用程式、網頁介面、終端機)接收訊息,把每則訊息導向一個工作階段(session),並在帶有一組工具的工作區(workspace)中,為該工作階段執行 agent 循環。依序追蹤一個請求經過這些階段,是定位失敗最快的方法:通道可能已連線,模型存取卻失敗;模型能回答,執行環境卻缺少必要指令;skill 已安裝,卻不符合啟用條件。「機器人在線上」無法區分這些情況。

聊天請求經 Gateway 進入 agent 執行系統、工作區與工作階段,再跨越執行邊界產生可檢查的結果。
圖 1 — 依 OpenClaw 架構文件 [1] 整理的原創簡化教學圖。官方文件描述的是 WebSocket 訊息;本圖則標示操作者應在哪裡查看任務狀態與權限。

在 OpenClaw 中: Gateway 是串接通道、用戶端與執行操作的常駐服務;工作階段識別對話與執行歷史;工作區保存檔案;skills 提供程序,工具提供行動;已配對的 node 可以暴露另一台裝置的能力。文件將 agent 循環描述為每個工作階段內序列化的一次執行:接收輸入、組成情境、模型推論、工具執行、串流輸出與持久化。[1, 11]

工作階段:身分、順序與重設

原則。 每則進來的訊息必須恰好對應到一個工作階段,而且同一個工作階段內的輪次不能交錯。兩個同時進行的輪次寫入同一份歷史,會把它弄壞。要有意識地決定工作階段何時結束:永不重設的工作階段會累積過時的情境;重設太頻繁,又會忘記進行中的工作。

需要決定的事: 寄件者與通道如何對應到工作階段(每個私訊一個、每個群組一個,或每個討論串一個);在輪次進行中又收到訊息時怎麼辦(排隊、合併,或中斷);以及重設政策(手動、每日,或閒置一段時間後)。

在 OpenClaw 中: 輪次會先依工作階段序列化,再配置全域容量,而且每次執行都會記錄寫入者宣告(writer claim),讓被取代的執行不能提交過時的對話資料。工作階段預設會一直重複使用,直到重設;操作者可以依聊天類型或通道,選擇在設定的時刻每日重設,或在閒置若干分鐘後重設,也可以用 /new 或 /reset 手動開始新的工作階段。排程執行等背景事件,不計入閒置重設的活動。[11, 12]

工具、權限與執行邊界

原則。 三個問題必須有各自的答案:

  1. 誰可以提出要求? 寄件者的身分驗證與配對,決定誰的訊息能到達 agent。
  2. 哪些行動可以執行? 工具政策決定某個工作階段有哪些工具;核准政策決定哪些呼叫需要人工說「可以」。
  3. 它們在哪裡執行? 在 gateway 主機上、沙箱裡,或已配對的遠端裝置上。這決定一個成功的行動最多能造成多大的損害。

通過身分驗證的寄件者,只是通過了第一關。這並不表示他要求 agent 讀取的網頁中,每一句指令都具有權威;工具擷取回來的內容是資料,而間接提示詞注入正是越過這條界線的標準手法。[17] 核准提示能減少意外執行,但一旦核准,指令就以它所在之處的完整權限運行。因此,最小權限存在於執行邊界與限定範圍的憑證中,而不是在提示詞裡。

第一次部署的實用政策: 唯讀工具不需核准;寫入限制在單一工作區;任何會寄送、發布、刪除或花錢的行動都要先核准;機密由工具持有,絕不貼進提示詞或 skills;凡是會瀏覽不受信任內容的 agent,都放進沙箱。

在 OpenClaw 中: 文件把一個 Gateway 視為一個信任邊界:通過驗證的呼叫者就是受信任的操作者,同一個 Gateway 上的多個 agent 或工作階段,並不會隔離彼此敵對的使用者。執行核准在執行主機上強制進行,並綁定已核准指令的確切脈絡(工作目錄、引數清單、解析後的執行檔),但文件明確說明,它們不是針對個別使用者的身分驗證邊界,也不是唯讀政策。工具可用性與指令核准是分開的設定。沙箱預設關閉;啟用後,工具執行會移到沙箱後端,Gateway 仍留在主機上。[4, 5, 13]

Skills:可用性、優先序與版本

原則。 對 agent 使用的每個 skill,你應該能回答:載入的是哪一份副本、來自哪個來源、是哪個版本,以及它在這裡是否具備執行資格(所需的執行檔、檔案與憑證,在執行發生的地方是否存在)。當兩個來源定義了同名的 skill,由優先序規則決定;在除錯「我改了卻沒有效果」之前,先弄清楚這條規則。Skills 如何組織與測試,請見第二篇。

在 OpenClaw 中: 檔案式 skills 從一份文件列出的來源清單載入,其中工作區 skills 的優先序最高,內建 skills 接近最低;同名衝突時,由最高的來源勝出。Skills 可以用啟用條件管控,CLI 會列出符合條件的 skills,並檢查缺少的先備條件。檔案式 skills、受管理的函式庫版本與 Workshop 學得的 skills,各自遵循不同的更新規則,所以執行中的工作階段可能不會立刻看到剛改過的檔案。[2, 6]

記憶與情境:每一輪開始時 agent 知道什麼

原則。 把四件事分開。情境是目前這次請求裡的內容。壓縮用摘要取代較舊的輪次,讓長工作階段放得進視窗。記憶跨工作階段攜帶挑選過的事實。檢查點記錄執行進度,讓工作可以續作。有用的記憶條目是持久、有來源、有日期的(「優先使用原始論文;觀察於 2026-11-03」);尚未確認的猜測不應變成永久事實,改變後的偏好則應取代舊的,而不是與它並存。關於外部世界的證據(「星期二無法連到來源 B」)不是偏好,會過期。

在 OpenClaw 中: 記憶分成不同角色的檔案:USER.md 放穩定的偏好與指示,MEMORY.md 放持久的非個人資料事實與決策,按日期命名的 memory/YYYY-MM-DD.md 放日常觀察,新的工作階段會載入近期的每日筆記。壓縮會摘要較舊的輪次、保持近期訊息完整、讓每個工具呼叫與其結果成對,並把完整歷史留在磁碟上;它只改變模型接下來看到的內容。[7, 14]

排程:沒有人傳訊息時的工作

原則。 週期性工作需要的不只是計時器。排程之前先寫下:時區、輸入範圍、輸出目的地、在既有工作階段(帶有其情境)還是全新的工作階段中執行、預算、輸入缺失時的行為,以及重複處理政策。排程器可能觸發兩次,也可能工作成功之後寄送卻失敗。為每次執行設定穩定的週期鍵(例如預定的那一週加上來源集合的版本),保存產物識別與寄送收據,並在寄送前檢查是否已有收據。把執行與寄送記為兩個獨立的結果:「執行了但無法寄送」與「根本沒有執行」,修正方式不同。

先手動驗證工作,再排程為只產生草稿,檢查第一次執行,最後才允許寄送。

在 OpenClaw 中: 排程工作、webhook 與其他觸發條件,統一以 automations 管理,它會持久保存工作、喚醒 agent,並把輸出送到通道、webhook 或不送出;各工作有自己的執行歷史。早期版本有獨立的 heartbeat 監控;現行文件說明如何把這些監控遷移成一般的 automation 工作。[8, 9]

復原:中斷、重啟與升級

原則。 假設任何步驟都可能被中斷:行程重啟、逾時、連線中斷。復原有兩條規則。第一,中斷之後,agent 應先檢查目前的狀態(檔案、行程、外部紀錄)再繼續,因為保存的紀錄可能落後於實際發生的事。第二,結果未知的行動不能盲目重複;先比對狀態,或使用冪等鍵。升級是有計畫的中斷:依文件的方法備份狀態、閱讀遷移說明、盡可能先升級測試用的實例,並重跑固定的驗收任務。換掉執行檔不一定能還原狀態遷移,所以要保留可還原的備份。

在 OpenClaw 中: Gateway 正常停止時,會為每個執行中的根工作階段寫下一個小標記;啟動時,Gateway 會對 agent 送出一則輸入,請它在繼續之前先檢查目前的檔案、行程、子 agent 與外部動作。子執行不會自行恢復。更新指南要求在重大更新之前先備份並驗證,並區分套件更新、狀態遷移與復原。[10, 12]

可觀測性:回答「發生了什麼事?」

原則。 對話紀錄不是日誌。對每一次執行,把下列內容記錄為結構化事件:執行識別碼、工作階段、觸發來源(訊息、排程、webhook)、模型與設定、每個工具呼叫及其參數(機密已遮蔽)、核准決定、錯誤、token 與成本用量、最終狀態,以及寄送結果。有了這些欄位,多數維運問題都可以用一次查詢回答:昨晚哪些執行失敗、哪個工具最慢、哪些核准最頻繁、哪個工作重複寄送。OpenTelemetry 維護了生成式 AI 遙測的語意慣例(針對模型用戶端與 MCP 的 span、指標與事件),如果你已經在用追蹤,這是個合理的起始詞彙。[16]

在 OpenClaw 中: Gateway 會寫入滾動的日誌檔,每行一個 JSON 物件,並支援遮蔽;openclaw logs 可以持續查看這些日誌,包括遠端查看。工作階段可以用 JSON 列出;在聊天中,/status 顯示情境用量與模型,/context list 顯示系統提示詞裡有什麼。某次執行的等待結果會回報其狀態,並且在可用時,附上確認回覆已送達來源對話的收據。openclaw doctor 會執行健康檢查與引導式修復。[11, 12, 15]

學得的程序就是程式變更

有些 harness 能根據經驗撰寫或修訂自己的 skills。把學得的程序當作 pull request 看待:審閱它的範圍、與先前的失敗比較,重跑一個相關請求、一個不相關請求與一個先前失敗的案例,並保留回復的途徑。好的教訓是「PDF 無法取得時,保留已驗證的中繼資料並標明缺少的結果」;壞的教訓是從一次成功的執行推論出「永遠信任這個網站」。這一切都不會改變模型的權重。

在 OpenClaw 中: Skill Workshop 在每次變更前都會保存先前的版本,並支援復原;提案模式讓背景學習把草稿存起來供審閱,而不是直接套用。[6]

從症狀開始診斷

症狀先檢查要避免什麼
訊息一直沒有到達任何一次執行通道存取權、配對、路由、gateway 狀態在確認訊息有送達之前就改寫 skill
找不到某個 skill選取的工作區、來源優先序、啟用條件以為安裝就等於啟用
指令在主機上能用,在任務中卻失敗實際的執行主機、相依套件、掛載的檔案為了補上缺少的執行檔,授予過大的權限
舊的指令一直出現工作階段選擇、skill 版本與更新規則改了另一份同名的副本
Agent 忘記某個決定已保存的記憶、壓縮摘要、載入上限每次提示都重複整份對話紀錄
排程工作產生重複的輸出執行歷史、觸發識別、寄送收據對不確定的寄送盲目重試

這些是除錯假設;請在日誌與實際生效的設定中確認。

維運檢查清單

第一次執行前: 一位使用者、一個工作區、一組模型連線;寫下工具政策;決定是否使用沙箱;機密由工具持有;一個有已知正確輸出的小型驗收任務(第一篇的論文摘要就很適合)。

排程之前: 任務手動執行即可通過;已定義重複處理政策與週期鍵;已在私人通道測試寄送;已設定預算;失敗通知會送到真人手上。

每週: 閱讀失敗的執行與核准紀錄;清理或取代過時的記憶;審閱學得或更新過的 skills;確認磁碟、日誌與成本都在預期範圍內。

每次升級前: 已驗證的備份;已閱讀版本與遷移說明;在新版本上重跑驗收任務;已確認回復途徑。

現行選項,查核日期 2026 年 11 月 6 日

查核了什麼。 OpenClaw 的官方文件,來源提交為 27f243756a45f02724b70597803571e2f0e1d020(2026 年 11 月 6 日的 main 分支;套件版本 2026.11.1,同時也是最新穩定發行標籤,另有標記為 2026.11.5 的 beta)。本文先前的版本使用提交 34bc643;比對被引用的頁面後,其間的變動不大(快速入門現在會詢問是否讓 Gateway 在背景持續運行,並新增 openclaw gateway start,它會等到就緒;被隱藏、不讓模型自動選擇的 skill,現在可以出現在 $ 選單中;回復時會保留之後獨立的變更)。以下指令已對照文件檢查;本文沒有實際執行經過驗證的 OpenClaw 部署。使用前請先確認你安裝的版本。[1–15]

程式碼 · Bash · 10 行
openclaw --version
openclaw gateway status
openclaw dashboard
openclaw skills list --eligible
openclaw skills check
openclaw security audit
openclaw sessions --json
openclaw automations list --all
openclaw logs --follow
openclaw doctor

dashboard 負責開啟網頁介面,不能驗證任務。skills check 回報缺少的先備條件。security audit 回報設定上的疑慮,不代表已證明每個外掛與工作流程都安全。automations list 顯示已啟用的工作,加上 --all 則包含已停用的;openclaw cron 仍保留為別名。這些指令都不會安裝第三方 skill 或建立排程。[2, 3, 8, 12, 15]

第一個 skill。 若要試用第二篇的 paper-digest skill,把它放進工作區的 skills/ 目錄,確認它被列為符合啟用條件,明確要求使用一次,再送出一個不相關的請求,確認它沒有被套用。[2]

延伸閱讀

參考文獻

OpenClaw 參考文獻 1–15 是固定在來源提交 27f2437(2026 年 11 月 6 日)的官方文件。它們描述的是該快照;請查閱你所安裝版本的文件。

  1. OpenClaw contributors, “Gateway architecture.” 文件.
  2. OpenClaw contributors, “Skills” and skills CLI reference. 載入與更新、CLI.
  3. OpenClaw contributors, “Getting started.” 文件.
  4. OpenClaw contributors, “Security.” 文件.
  5. OpenClaw contributors, “Sandboxing.” 文件.
  6. OpenClaw contributors, “Skill Workshop.” 文件.
  7. OpenClaw contributors, “Memory overview.” 文件.
  8. OpenClaw contributors, “Automations” and automations CLI reference. 文件、CLI.
  9. OpenClaw contributors, “Heartbeat migration.” 文件.
  10. OpenClaw contributors, “Updating.” 文件.
  11. OpenClaw contributors, “Agent loop.” 文件.
  12. OpenClaw contributors, “Session management” and sessions CLI reference. 文件、CLI.
  13. OpenClaw contributors, “Exec approvals.” 文件.
  14. OpenClaw contributors, “Compaction.” 文件.
  15. OpenClaw contributors, “Gateway logging,” logs CLI and doctor CLI references. 日誌、logs CLI、doctor CLI.
  16. OpenTelemetry contributors, “Semantic Conventions for Generative AI,” 儲存庫,查閱日期 2026-11-06。 儲存庫.
  17. OWASP Gen AI Security Project, “LLM01:2025 Prompt Injection,” OWASP Top 10 for LLM Applications 2025。 條目.
  18. Anthropic, “Effective harnesses for long-running agents,” 2025-11-26。 文章.
  • #agents
  • #operations
  • #harness
  • #openclaw