Skip to main content
這個單元解決什麼問題OpenClaw 把 agent 的人格、記憶、心跳、工具慣例用一組存在工作區的 Markdown 檔組裝起來，讓 agent 在每次 session 啟動時「讀自己的靈魂」才開始工作。本單元從倉庫實際檔案出發，解剖它的由來與定位、Gateway 執行迴圈、心跳（heartbeat）排程、記憶系統，以及各自訂 md 檔的確切職責；無法從倉庫直接確認的細節以官方文件為準。讀完這個單元，你能把 OpenClaw 的架構說清楚，並判斷它的設計思路是否適合你自己的 harness 建設。

​
學習目標

  • 能說清 OpenClaw 的由來（Warelay、Clawdbot、Moltbot、OpenClaw）與它想解決的問題：讓 agent 在使用者已在用的通訊管道上「真的做事」
  • 能描述 Gateway 控制平面的角色，以及 heartbeat 排程如何觸發定期 agent turn
  • 能逐一說出工作區標準 md 檔（AGENTS.md、BOOTSTRAP.md、HEARTBEAT.md、IDENTITY.md、MEMORY.md、SOUL.md、TOOLS.md、USER.md）各自的職責與載入時機
  • 能用一句生活比喻概括這個系統的本質
  • 能評估 OpenClaw 的「harness 可視化」設計是否能套到你自己的 agent 設定

​
1. 由來與定位

OpenClaw 不是橫空出世。它有一段可追溯的演化路徑，名字本身就是這個故事： 這條命名軸記錄的是一段快速更名史，而非漫長演化：作者 Peter Steinberger 以 Warelay 之名首次發布（2025-11），以 Clawdbot 廣為人知，2026-01-27 因 Anthropic 商標投訴改名 Moltbot，三天後（2026-01-30）再改為 OpenClaw 並在 GitHub 開源（VISION.md 截至 2026-05）。 它要解決的問題很直白：絕大多數 AI 助理都要求使用者「切到新介面」，而 OpenClaw 反過來，要在使用者既有的通訊管道（WhatsApp、Telegram、Slack、Discord 等 20+ 個平台）上直接執行真實任務。換句話說，它不是另一個對話框 UI，而是一個貼在使用者既有對話流的個人助理 daemon。 定位上屬於「local-first 個人 agent harness」：以 TypeScript 寫成，理由是「廣為人知、迭代快、易讀易改」這三個工程圈的共識（VISION.md）。在 agent 外殼的分類上，它屬於「單機自託管、多管道路由、plugin 可擴展」這一型：核心保持精簡，可選能力以 plugin 形式交付，避免核心膨脹。
「local-first」的工程意涵預設在你的本機跑、預設存取你的本機資源、預設使用你已有的工具。代價是：沒有企業級 SLA、沒有團隊共用基礎設施、沒有統一審計。如果你需要這些，要看 05-3 NemoClaw 的硬化外殼模式；OpenClaw 本體不解決這個問題。

​
2. 核心技術：Gateway 控制平面與執行迴圈

OpenClaw 整個系統的心臟是一個常駐在本機的 Gateway 控制平面。它不是 agent 本身，而是「管理所有 agent、session、channel、tool、event 的總線」。把這層從 agent 邏輯中抽離出來，是 OpenClaw 設計上最關鍵的決定：整合層可以變，agent 邏輯不必跟著重寫。 Gateway 的核心職責可以拆成四塊：
  1. 多管道路由（multi-channel routing）：每條入站管道進來的訊息，會被路由到隔離的 agent 實例，各自擁有獨立的工作區與 session，互不污染
  2. 多 agent 隔離：每個 agent 是一個獨立的「人」，擁有自己的工作區、自己的 session、自己的記憶，彼此不共享上下文
  3. 工具與權限管理：哪個 agent 可以呼叫哪個 tool、由誰授權、是否走沙箱，在這層統一決定
  4. 事件匯流排：所有事件（使用者訊息、heartbeat tick、cron 觸發、tool 回傳）都進入同一條匯流排，agent 透過它知道「現在該做什麼」
在這之上，OpenClaw 提供了**心跳機制（heartbeat）**讓 agent 可以在沒有使用者訊息的情況下週期性被喚醒。預設間隔 30 分鐘，使用 Anthropic OAuth/token 驗證時預設為 1 小時（heartbeat 文件 截至 2026-05）。 心跳 turn 的預設 prompt 是這句：
這句 prompt 本身就是設計說明：心跳不是「讓 agent 自己去發想任務」，而是「讀 HEARTBEAT.md 上明確寫的任務清單，沒事就回 HEARTBEAT_OK 結束這輪」。HEARTBEAT.md 留空時，OpenClaw 甚至會跳過模型呼叫，連一次 LLM 推論都不發起（heartbeat 文件）。
heartbeat 與 cron 的分工heartbeat 是 main session 的週期性 turn，不建立背景任務記錄；cron 是用來建立獨立背景任務記錄（ACP runs、subagents）的機制。混淆這兩個會讓你以為「心跳也能跑長任務」而失望：心跳的本質是 session 內的週期性喚醒，跑長任務要靠 cron 派出去的獨立子代理。

​
3. 系統結構：各組件如何串起來

OpenClaw 預設把 agent 的「生活範圍」放在 ~/.openclaw/workspace 這個目錄，這是 file tool 的相對路徑根。可以在 openclaw.json 裡覆寫。
~/.openclaw/
openclaw.json · 工作區設定（路徑、模型、sandbox 選項）
workspace/ · agent 的工作目錄
AGENTS.md · 操作指令與記憶使用規則
SOUL.md · 人格、語氣、邊界
IDENTITY.md · 名字、屬性、emoji、avatar
USER.md · 關於使用者的資料
TOOLS.md · 本地工具慣例備注
HEARTBEAT.md · 心跳任務清單
MEMORY.md · 長期記憶精煉層
BOOTSTRAP.md · 一次性首次啟動儀式（完成後刪除）
logs/ · Gateway 與各 agent 的日誌
幾個關鍵設計點要先釐清：
  • 工作區不是沙箱。工作區只是 agent 的工作目錄；沒有啟用 agents.defaults.sandbox 之前，agent 用絕對路徑仍可觸及主機檔案系統。把它當作「agent 預設的『家』」，不是「agent 的牢籠」。
  • bootstrap 是儀式。全新工作區會被 Gateway 植入標準 md 檔與一份 BOOTSTRAP.md；agent 會在首次啟動時用一問一答的方式與使用者共同填寫 IDENTITY.md 與 SOUL.md，完成後刪除 BOOTSTRAP.md（bootstrapping 文件）。這個「自己決定自己是誰」的儀式不是裝飾，是 OpenClaw 設計哲學的核心：agent 的身份由使用者與 agent 共同協商，不寫死在程式碼裡。
  • plugin 透過 skills/ 目錄載入。技能以 ~/.openclaw/workspace/skills/<skill>/SKILL.md 形式存放；集中市集為 ClawHub（clawhub.ai，截至 2026-05 依 README 所述，市集現況與營運狀態請以官方頁面為準）。
  • 安全模型預設是寬鬆的。main session 代表你本人，預設有全主機存取權限；非 main session（群組、管道進來的）可透過 openclaw.json 設為 Docker / SSH / OpenShell 沙箱，限制工具集。
main session 的全主機權限是設計選擇，不是 bugOpenClaw 預設信任「你本人透過 main session 下達的指令」。這個假設在你的工作流裡成立，在「共享群組裡的別人透過管道叫你的 agent」場景就不成立。後者的場景請務必在 openclaw.json 把對應 session 設為沙箱模式，否則 prompt injection 進來時 agent 會拿全主機權限執行任意指令。

​
4. 自訂 md 檔逐一解剖

OpenClaw 工作區的所有 md 檔都不是「寫好玩的」，每個都有明確的職責與載入時機。以下職責均來自倉庫 docs/concepts/agent-workspace.md 與 docs/reference/templates/（截至 2026-05）： 幾個常被混淆的對照：
  • SOUL.md vs USER.md：前者是「我是誰、我怎麼說話」，後者是「你是誰、你喜歡什麼」。前者是 agent 的，後者是你的。
  • AGENTS.md vs SOUL.md：AGENTS.md 是操作政策（「先做 A 再做 B、遇到 X 就呼叫 Y 工具」），SOUL.md 是人格層（「語氣直白、結論先行、不用 emoji」）。一個管「做什麼」，一個管「是怎樣的人」。
  • MEMORY.md vs memory/YYYY-MM-DD.md：MEMORY.md 是精煉後的長期事實（「使用者住在台中、研究領域是精準畜牧 AI」），日誌檔是當天的詳細記錄。MEMORY.md 超出 bootstrap 預算時會被自動截斷，日誌檔則完整保留。
  • TOOLS.md vs skills/：TOOLS.md 是環境專屬的備注（「我的攝影機叫 front_door，SSH 別名 lab」），skills/ 是可分享的可重用程序。先把這兩層分開，之後升級 skill 或換機器時才不會把個人基礎設施洩漏出去。
一個工作區的 bootstrap 過程全新安裝後，第一次啟動 Gateway：
1

植入範本

自動植入 AGENTS.md、SOUL.md、USER.md、IDENTITY.md、TOOLS.md、HEARTBEAT.md、MEMORY.md 範本與 BOOTSTRAP.md
2

一問一答建立身份

agent 讀到 BOOTSTRAP.md，依序問你：「你希望我叫你什麼？」（寫入 USER.md）「你希望我自稱什麼、什麼 creature、用什麼 emoji？」（寫入 IDENTITY.md）「我的語氣與邊界？」（寫入 SOUL.md）
3

儀式結束

全部確認後，刪除 BOOTSTRAP.md，session 正常開始
這個過程為什麼重要：因為接下來每次 session 啟動，agent 都會從這幾份檔案「重新長出」自己的人格與對你的理解。如果這幾份檔案是空的、矛盾的或過時的，每次 session 開頭的行為就會漂移。

​
5. 該學什麼：OpenClaw 把哪些 harness 概念外顯成可讀檔案

OpenClaw 最大的設計貢獻不是它的模型支援或工具集，而是把通常埋在 system prompt 或程式碼裡的 harness 概念全部外顯成可讀、可 diff 的 md 檔。這件事在工程上的意義跟在產品設計上的意義是同樣的：把隱性設定變成顯性資產。 與 01-6 Harness Engineering 單元對位： 幾個值得內化的設計教訓：
  • lean core + plugin：OpenClaw 的核心只保留「必須的」東西，技能、管道、政策都透過 plugin / md 檔擴展。核心膨脹是軟體腐敗的開始，harness 也一樣。
  • 環境專屬與共享行為切開：TOOLS.md（你的攝影機叫什麼）與 SOUL.md（這個 agent 的人格）分開管理，你把 SOUL.md 與 skills/ 分享給別人時，不會洩漏你的基礎設施。
  • 儀式不是裝飾：BOOTSTRAP.md 強制 agent 與使用者坐下來談「我們是誰、我們要怎麼合作」，這比寫在文件裡的「default persona」更能產生實際的約束效果。
  • 心跳的「沒事就回 OK」是省錢設計：留空 HEARTBEAT.md 時連模型呼叫都跳過，這是給「裝了但暫時不用」的場景留的零成本開關。

​
6. 一句生活比喻

OpenClaw 像一個有自己「生活手冊」的合租室友：它在冰箱上貼了一張便條告訴自己「我是誰、我怎麼說話」（SOUL.md），冰箱裡留著昨天的剩菜標籤（MEMORY.md），廚房計時器每隔半小時響一次提醒「該看一下爐子沒」（HEARTBEAT.md），門口有個本子專門記「這台攝影機叫什麼、那台 SSH 怎麼連」（TOOLS.md），而它每晚睡著前都會翻一下本日筆記決定哪些要寫進長期記憶（每天的 memory/YYYY-MM-DD.md 精煉成 MEMORY.md）。人不是它，它是人 + 環境的共同組裝，而這本人手冊就是那個環境。

​
動手做

1

本機安裝並觀察 bootstrap

在本機 clone OpenClaw 後跑 openclaw onboard --install-daemon，觀察工作區被植入哪些 md 檔，以及 bootstrap 儀式如何一問一答地建立 IDENTITY.md 與 SOUL.md。完成後檢查 BOOTSTRAP.md 是否真的被刪除。
2

改 HEARTBEAT.md 並觀察心跳 turn

在 ~/.openclaw/workspace/HEARTBEAT.md 加入一條「每半小時檢查我的 GitHub 有沒有新的 issue 標記為我」的任務，觀察 30 分鐘後的心跳 turn 是否正確執行並回覆 HEARTBEAT_OK 或實際動作。
3

閱讀倉庫的範本目錄

直接讀 docs/reference/templates/ 下的 SOUL.md、AGENTS.md、MEMORY.md 範本，比對你本機 bootstrap 產生的版本差異；這個 diff 就是「預設 vs 你的客製化」邊界。

​
常見誤區

  • 把 SOUL.md 寫成企業手冊：冗長的規則牆讓 token 成本上升，且 agent 遵從度下降（高優先層太長會被模型忽略或稀釋）。短而有行為效果的指令才有用，建議不超過一頁 A4。
  • 把大量詳細日誌塞進 MEMORY.md：MEMORY.md 是精煉層，不是日誌；詳細記錄應寫入 memory/YYYY-MM-DD.md，否則觸發 bootstrap 截斷後會遺失重要資訊。
  • 忘記 BOOTSTRAP.md 需要手動刪除：儀式完成後若不刪除，每次啟動都會重走一遍首次設定流程（agent 看到 BOOTSTRAP.md 就當作「首次啟動」處理）。
  • main session 預設全主機權限：見第 3 節的 Warning；把「群組 / 陌生人管道」與「main session」混淆，是 OpenClaw 最常見的暴露點，prompt injection 進來時 agent 會拿全主機權限執行任意指令。
  • 把 plugin 當成「裝越多越好」：OpenClaw 的 skill 越多，每個 session 注入的上下文越多、token 成本越高；只裝你會實際用到的，並定期審查。

​
自我檢核

通過本單元的標準
  1. 不看文件，能否說出 SOUL.md、IDENTITY.md、MEMORY.md 三個檔案的差異，以及它們各自在哪個時機載入？
  2. 能否解釋 heartbeat 與 cron job 的分工，以及為何心跳 turn 不建立背景任務記錄？
  3. 能否用一句話向同事說明「OpenClaw 把什麼東西藏在工作區的 md 檔裡」？
  4. 你現在的 agent 設定（不管是 Claude Code、Codex、Cursor 還是其他），有沒有任何一段是「散落在 system prompt 字串裡、不可版控」的操作程序？這段能不能也外顯成一個 md 檔？

​
來源與延伸閱讀

事實主張依官方文件，快變動項標註截至 2026-05。