Agent 執行環境

OpenClaw 執行一個從 pi-mono 衍生的單一嵌入式 agent 執行環境。

工作區（必要）

OpenClaw 使用單一的 agent 工作區目錄（agents.defaults.workspace）作為工具和上下文的唯一工作目錄（cwd）。

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

完整的工作區結構 + 備份指南：Agent workspace

如果啟用了 agents.defaults.sandbox，非主要 session 可以在 agents.defaults.sandbox.workspaceRoot 下使用 per-session 工作區（請參閱 Gateway configuration）。

引導檔案（注入式）

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

  • AGENTS.md — 操作指令 + 「記憶」
  • SOUL.md — 人格、邊界、語調
  • TOOLS.md — 使用者維護的工具筆記（例如 imsg、sag、慣例）
  • BOOTSTRAP.md — 一次性的首次執行儀式（完成後刪除）
  • IDENTITY.md — agent 名稱/風格/emoji
  • USER.md — 使用者檔案 + 偏好稱呼

在新 session 的第一個回合，OpenClaw 會將這些檔案的內容直接注入 agent 上下文中。

空白檔案會被跳過。大型檔案會被修剪並截斷，附上標記讓提示詞保持精簡（想看完整內容請自行讀取檔案）。

如果某個檔案不存在，OpenClaw 會注入一行「檔案缺失」標記（而 openclaw setup 會建立安全的預設範本）。

BOOTSTRAP.md 只在全新工作區（沒有其他引導檔案存在時）才會建立。完成儀式後刪除它，之後重啟時不會再重新建立。

要完全停用引導檔案的建立（適用於預先準備好的工作區），設定：

{ agent: { skipBootstrap: true } }

內建工具

核心工具（read/exec/edit/write 及相關系統工具）始終可用，受工具原則限制。apply_patch 是可選的，受 tools.exec.applyPatch 控制。TOOLS.md 不會決定哪些工具存在，它只是你對工具使用方式的指引。

Skills

OpenClaw 從三個位置載入 skills（名稱衝突時，工作區優先）：

  • 內建（隨安裝提供）
  • 受管理/本地：~/.openclaw/skills
  • 工作區：<workspace>/skills

Skills 可以透過設定/環境變數來控制（請參閱 Gateway configuration 中的 skills）。

pi-mono 整合

OpenClaw 重用了 pi-mono 程式碼庫的部分元件（模型/工具），但 session 管理、探索和工具接線都由 OpenClaw 自己負責。

  • 不使用 pi-coding agent 執行環境。
  • 不會參考 ~/.pi/agent 或 <workspace>/.pi 的設定。

Sessions

Session 對話記錄以 JSONL 格式儲存在：

  • ~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl

Session ID 是穩定的，由 OpenClaw 選定。 舊版 Pi/Tau 的 session 資料夾不會被讀取。

串流中的即時轉向

當佇列模式為 steer 時，入站訊息會被注入到當前執行中。佇列在每次工具呼叫後檢查；如果有排隊的訊息，當前助理訊息中剩餘的工具呼叫會被跳過（工具結果標記為「Skipped due to queued user message.」），然後排隊的使用者訊息會在下一次助理回覆前注入。

當佇列模式為 followup 或 collect 時，入站訊息會被保留到當前回合結束，然後以排隊的 payload 啟動新的 agent 回合。請參閱 Queue 瞭解模式 + debounce/上限行為。

區塊串流在助理區塊完成後立即發送；預設關閉（agents.defaults.blockStreamingDefault: "off"）。 透過 agents.defaults.blockStreamingBreak 調整邊界（text_end vs message_end；預設為 text_end）。 透過 agents.defaults.blockStreamingChunk 控制軟性區塊分段（預設 800-1200 字元；優先段落分隔，其次換行，最後句子）。 透過 agents.defaults.blockStreamingCoalesce 合併串流區段，減少單行訊息的干擾（基於閒置的合併後再發送）。非 Telegram 頻道需要明確設定 *.blockStreaming: true 才能啟用區塊回覆。 Verbose 工具摘要在工具開始時就會發出（無 debounce）；Control UI 在可用時透過 agent 事件串流工具輸出。 更多細節：Streaming + chunking。

模型引用

設定中的模型引用（例如 agents.defaults.model 和 agents.defaults.models）以第一個 / 為分隔符解析。

  • 設定模型時使用 provider/model 格式。
  • 如果模型 ID 本身包含 /（OpenRouter 風格），需要加上 provider 前綴（例如：openrouter/moonshotai/kimi-k2）。
  • 省略 provider 時，OpenClaw 會把輸入視為別名或預設 provider 的模型（只在模型 ID 不含 / 時有效）。

設定（最低要求）

至少需要設定：

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

下一篇：Group Chats

arrow_back
上一頁
Architecture
下一頁
Agent Loop
arrow_forward