English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Fundamentals

代理執行環境

OpenClaw 執行單一嵌入式代理程式執行環境 - 每個 Gateway 一個代理程式程序，並有自己的工作區、啟動檔案和工作階段儲存區。本頁說明該執行環境合約：工作區必須包含哪些內容、會注入哪些檔案，以及工作階段如何依據它啟動。

工作區（必需）

OpenClaw 使用單一代理程式工作區目錄（agents.defaults.workspace）作為代理程式在工具與上下文中的唯一工作目錄（cwd）。

建議：使用 openclaw setup 在缺少時建立 ~/.openclaw/openclaw.json，並初始化工作區檔案。

完整工作區版面配置 + 備份指南：代理程式工作區

如果已啟用 agents.defaults.sandbox，非主要工作階段可以使用 agents.defaults.sandbox.workspaceRoot 底下的逐工作階段工作區覆寫此設定（請參閱 Gateway 設定）。

啟動檔案（已注入）

在 agents.defaults.workspace 內，OpenClaw 預期有這些可由使用者編輯的檔案：

  • AGENTS.md - 操作指示 +「記憶」
  • SOUL.md - 人格、界線、語氣
  • TOOLS.md - 使用者維護的工具備註（例如 imsg、sag、慣例）
  • BOOTSTRAP.md - 一次性首次執行儀式（完成後刪除）
  • IDENTITY.md - 代理程式名稱/氛圍/emoji
  • USER.md - 使用者資料 + 偏好的稱呼方式

在新工作階段的第一輪中，OpenClaw 會將這些檔案的內容注入到系統提示詞的專案上下文中。

空白檔案會被略過。大型檔案會以標記修剪並截斷，讓提示詞保持精簡（請讀取檔案以取得完整內容）。

如果檔案遺失，OpenClaw 會注入單一「檔案遺失」標記行（且 openclaw setup 會建立安全的預設範本）。

BOOTSTRAP.md 只會為全新工作區建立（沒有其他啟動檔案存在）。在它待處理期間，OpenClaw 會將它保留在專案上下文中，並加入系統提示詞啟動指引以進行初始儀式，而不是將它複製到使用者訊息中。如果你在完成儀式後刪除它，之後重新啟動時不應重新建立。

若要完全停用啟動檔案建立（用於預先填入內容的工作區），請設定：

{ agents: { defaults: { skipBootstrap: true } } }

內建工具

核心工具（read/exec/edit/write 與相關系統工具）一律可用，並受工具政策約束。apply_patch 是選用項目，且由 tools.exec.applyPatch 控制。TOOLS.md 不會控制有哪些工具存在；它是關於 你 希望如何使用這些工具的指引。

Skills

OpenClaw 會從這些位置載入 Skills（優先順序由高到低）：

  • 工作區：<workspace>/skills
  • 專案代理程式 Skills：<workspace>/.agents/skills
  • 個人代理程式 Skills：~/.agents/skills
  • 受管理/本機：~/.openclaw/skills
  • 隨附（隨安裝提供）
  • 額外 Skills 資料夾：skills.load.extraDirs

Skills 可由設定/env 控制（請參閱 Gateway 設定 中的 skills）。

執行環境邊界

嵌入式代理程式執行環境建構於 Pi 代理程式核心之上（模型、工具與提示詞管線）。工作階段管理、探索、工具接線和通道傳遞，是 OpenClaw 在該核心之上的自有層。

工作階段

工作階段逐字稿會以 JSONL 儲存在：

  • ~/.openclaw/agents/<agentId>/sessions/&lt;SessionId&gt;.jsonl

工作階段 ID 是穩定的，並由 OpenClaw 選定。 不會讀取其他工具留下的舊版工作階段資料夾。

串流時導引

當佇列模式為 steer 時，傳入訊息會被注入目前的執行。已排入佇列的導引會在目前 assistant 回合完成執行其工具呼叫之後、下一次 LLM 呼叫之前送達。Pi 會針對 steer 一次耗盡所有待處理導引訊息；舊版 queue 則在每個模型邊界耗盡一則訊息。導引不再跳過目前 assistant 訊息中剩餘的工具呼叫。

當佇列模式為 followup 或 collect 時，傳入訊息會被保留到目前回合結束，然後新的代理程式回合會以排入佇列的酬載開始。請參閱佇列與導引佇列，了解模式與邊界行為。

區塊串流會在 assistant 區塊完成後立即傳送；它預設為關閉（agents.defaults.blockStreamingDefault: "off"）。 透過 agents.defaults.blockStreamingBreak 調整邊界（text_end 與 message_end；預設為 text_end）。 使用 agents.defaults.blockStreamingChunk 控制軟性區塊分塊（預設為 800-1200 個字元；優先使用段落分隔，其次為換行；最後才是句子）。 使用 agents.defaults.blockStreamingCoalesce 合併串流區塊，以減少單行垃圾訊息（傳送前以閒置為基礎合併）。非 Telegram 通道需要明確設定 *.blockStreaming: true 才能啟用區塊回覆。 詳細工具摘要會在工具啟動時發出（無 debounce）；Control UI 會在可用時透過代理程式事件串流工具輸出。 更多詳細資訊：串流 + 分塊。

模型參照

設定中的模型參照（例如 agents.defaults.model 和 agents.defaults.models）會透過在第一個 / 處分割來解析。

  • 設定模型時使用 provider/model。
  • 如果模型 ID 本身包含 /（OpenRouter 風格），請包含提供者前綴（範例：openrouter/moonshotai/kimi-k2）。
  • 如果省略提供者，OpenClaw 會先嘗試別名，接著針對該精確模型 ID 嘗試唯一的已設定提供者相符項，最後才退回到已設定的預設提供者。如果該提供者不再公開已設定的預設模型，OpenClaw 會退回到第一個已設定的提供者/模型，而不是顯示過時且已移除提供者的預設值。

設定（最小）

至少請設定：

  • agents.defaults.workspace
  • channels.whatsapp.allowFrom（強烈建議）

下一步：群組聊天 🦞

相關