折騰了好幾天，總算把 OpenClaw 2026年3月的大更新全部摸透了。這次升級一口氣加入了非常多實用功能——Inline 檔案附件、巢狀 Sub-Agent 擴展到5層、獨立 Thinking Level、不同模型指定、沙箱工具政策，還有 /btw 側話功能。舊文已經有點跟不上了，所以乾脆重寫一篇升級版，把新舊功能全部串起來講。

趁記憶還熱的時候整理出來，希望幫大家省點時間。

如果你之前看過我的舊文，這次升級主要有幾個大方向：

下文會逐一展開每個功能，順便把之前沒講清楚的部分補上。

先說 sessions_spawn，這是我最常用的核心工具。

sessions_spawn 的核心概念很簡單：主 Agent 派遣一個子 Agent 去執行特定任務，任務完成後結果自動通知回來。

有點像現實生活中的包工程——你把任務交給分包商，他做完後向你匯報。

sessions_spawn({
  task: "Research the latest AI trends",
  label: "research-task",
  agentId: "researcher",  // 可選：指定另一個 agent
  runTimeoutSeconds: 300
})
// 返回: { status: "accepted", runId, childSessionKey }

非阻塞設計：預設情況下，sessions_spawn 是非阻塞的——呼叫後立即返回，不會卡住等你。任務會在後台執行，完成後 OpenClaw 會自動把結果發佈到你的聊天頻道。

隔離環境：每個子 Agent 都在獨立的工作環境中運行，有自己的 context window 和工具執行權限。子 Agent 裡跑壞了什麼，都不會影響主 Agent。

巢狀深度擴展（重要更新！）：之前子 Agent 只能往下延伸一層（maxSpawnDepth = 1），或者支援簡單的兩層結構（Orchestrator Pattern，maxSpawnDepth = 2）。現在深度擴展到 1-5 層：

工具政策也按深度分層：

• Depth 1（Leaf，maxSpawnDepth=1）：無 Session Tools
• Depth 1（Orchestrator，maxSpawnDepth>=2）：可使用 sessions_spawn、subagents、sessions_list、sessions_history
• Depth 2（Leaf Worker）：無任何 Session Tools，sessions_spawn 永遠被拒絕

官方建議 depth 2 是大多數場景的最佳選擇，再深反而容易失控。

.Cascade Stop：停止父節點會級聯停止所有子節點——/stop 停止所有 depth-1 並級聯到 depth-2，/subagents kill <id> 停止特定 sub-agent 並級聯其子節點。

自動歸檔：子 Agent 任務完成後 60 分鐘會自動歸檔（可用 cleanup: "delete" 立即歸檔）。Auto-archive 平等適用於 depth-1 和 depth-2 sessions。

v2026.3.2 新增——這個功能我特別喜歡！

之前要把本地檔案交給子 Agent 處理，得靠外部檔案系統中轉。現在可以直接附加在 sessions_spawn 裡：

sessions_spawn({
  task: "分析這些文件",
  attachments?: [{
    name: string;           // 檔案名
    content: string;         // utf8 或 base64 編碼內容
    encoding?: "utf8" | "base64";
    mimeType?: string;
  }],
  attachAs?: { mountPath?: string }  // 預留給未來掛載實作
})

行為說明：

• 檔案被物化到子工作區的 .openclaw/attachments/<uuid>/ 目錄
• 每個檔案返回一個 sha256 收據
• 僅支援 subagent runtime，ACP（外部程式碼助理）會拒絕此參數
• 轉錄內容會被脫敏（redaction）
• 可透過 tools.sessions_spawn.attachments 配置大小限制

實際應用場景：比如我要讓子 Agent 分析一份 PDF 報告和一個 CSV 數據文件，直接附加進去就行，不用先上傳到某個地方再路徑分享。

根據我的經驗，sessions_spawn 最適合這些情況：

• 一次性後台任務：比如讓 AI 去研究某個題目，你不想等，繼續做其他事
• 需要隔離環境的工作：怕代碼執行污染當前會話
• 簡單的任務委派：不需要來回協商，分包商做完直接交貨
• 需要攜帶本地檔案的分析任務：現在有 Inline 附件更方便了

如果說 sessions_spawn 是包工程，那 sessions_send 就是即時通訊。

sessions_send 允許兩個獨立的 Agent 之間直接對話，可以一問一答，可以來回協商，不限層級。

// 同步呼叫（等待回覆）
const result = sessions_send({
  sessionKey: "agent:todd:discord:channel:1471456455025623211",
  message: "Hey Todd — Master wants you to say hello",
  timeoutSeconds: 30
})
// 返回: { runId, status: "ok", reply: "Done — waved at Master." }

// 異步呼叫（fire-and-forget）
sessions_send({
  sessionKey: "agent:researcher:main",
  message: "Start research on AI trends",
  timeoutSeconds: 0
})

sessionKey：目標會話的標識符。格式是 agent:<agentId>:<key>，比如 agent:researcher:main 指的是 researcher 這個 Agent 的主會話。這個 key 是穩定的，Gateway 重啟後依然有效。

timeoutSeconds：這個參數決定了行為模式：

• timeoutSeconds = 0：fire-and-forget，發完就跑，不等回覆
• timeoutSeconds > 0：同步等待，最長等 N 秒

message：傳送的訊息內容。

sessions_send 支援來回對話。設定 timeoutSeconds > 0 後，雙方可以進行多次 exchange，最大回合數現在可以配置了：

{
  session: {
    agentToAgent: {
      maxPingPongTurns: 3  // 範圍 0-5，預設 5
    }
  }
}

回覆關鍵字：

• REPLY_SKIP — 停止 ping-pong 循環
• ANNOUNCE_SKIP — 在 announce 步驟保持沉默

sessions_send 回傳狀態：

{ runId, status: "ok", reply }           // 成功
{ runId, status: "timeout", error }      // 等待超時（Run 繼續，可用 sessions_history 取結果）
{ runId, status: "error", error }        // Run 失敗

sessions_send 不是預設開啟的。你需要在配置中明確啟用：

{
  "tools": {
    "agentToAgent": {
      "enabled": true,
      "allow": ["main", "researcher", "coder"]
    }
  }
}

這個 allow list 指定了哪些 Agent 可以相互通訊。安全起見，建議只開啟你需要的組合。

選 sessions_spawn 的場景：

• 任務明確，做完就結束
• 需要隔離環境
• 需要攜帶本地檔案
• 不需要來回協商

選 sessions_send 的場景：

• 需要雙向溝通
• 任務可能跨多輪協商
• 需要穩定的會話狀態（比如 Gateway 重啟後要能恢復）

實際應用中，我不會把它們當非此即彼的選擇。

比如一個典型的流程可能是：主 Agent 用 sessions_send 向研究 Agent 請求數據（對等通訊），研究 Agent 收到後用 sessions_spawn 派遣子 Agent 去抓取網頁（父子委派），子 Agent 完成後把結果發回給研究 Agent，研究 Agent 再回覆給主 Agent。

根據不同的使用需求，我總結了三種常用的架構模式。

Main Agent (depth 0)
  └── Orchestrator Sub-Agent (depth 1, maxSpawnDepth=2)
        ├── Worker Sub-Agent A (depth 2)
        ├── Worker Sub-Agent B (depth 2)
        └── Worker Sub-Agent C (depth 2)

這是最常用的模式，適合任務明確、獨立性強的場景。主 Agent 扮演協調者，把任務拆分後委派給專業的子 Agent。

優點是簡單直接，缺點是 LLM 決定何時 spawn——這意味著流程是「非確定性」的，同樣的輸入可能產生不同的執行順序。

Main Agent (depth 0)
  ├─ sessions_send → Specialist A (persistent agent)
  │     └─ sessions_spawn → subagent A1
  └─ sessions_send → Specialist B (persistent agent)
        └─ sessions_spawn → subagent B2

這個模式適合更複雜的協作場景。主 Agent 通過 sessions_send 與同層級的持久化 Agent 溝通，每個持久化 Agent 可以進一步委派任務給自己的子 Agent。

好處是可以繞過單層級限制（因為 persistent agent spawn 的子 agent 不算在主 Agent 的深度裡），壞處是配置複雜度直線上升。

如果你需要的是確定性的流程控制——比如 code → review → test → deploy 這種嚴格的流水線——sessions_spawn 和 sessions_send 都不夠用。

這時候推薦用 Lobster，這是 OpenClaw 內建的工作流引擎：

• 步驟依序運行，數據以 JSON 格式傳遞
• 支援審批閘道（停下來等你確認）
• 支援恢復 tokens（中斷後可以繼續）
• 支援巢狀和迴圈

適合 CI/CD 類的任務，或者任何需要 machine-driven 而非 LLM-driven 流程的場景。

這次升級讓 Sub-Agent 的 Thinking Level 可以獨立於 Main Agent 設定了。

之前子 Agent 的思考深度只能跟著主 Agent 走，現在可以自己定義：

// 優先級：sessions_spawn > agents.list > agents.defaults
{
  agents: {
    defaults: {
      subagents: {
        thinking: "medium"  // 全域 Sub-Agent 預設
      }
    },
    list: [
      {
        id: "researcher",
        subagents: {
          thinking: "high"  // 研究 Agent 的子 Agent 預設 high
        }
      }
    ]
  }
}

三個級別： low、medium、high

實際應用策略：

複雜研究任務的 Orchestrator 可設為 high thinking，簡單的網頁搜尋 Agent 可設為 low thinking，大幅節省成本。

每個 Sub-Agent 現在可以使用不同模型了！

{
  agents: {
    defaults: {
      subagents: {
        model: "openai/gpt-5.4-mini"  // 全域 Sub-Agent 預設模型
      }
    },
    list: [
      {
        id: "worker",
        subagents: {
          model: "openai/gpt-5.4-nano"  // 特定 Agent 的 Sub-Agent 預設模型
        }
      }
    ]
  }
}

優先級： sessions_spawn({ model: "..." }) > agents.list[].subagents.model > agents.defaults.subagents.model

v2026.3.22 新增模型支援： GPT-5.4-mini、GPT-5.4-nano（專為 Sub-Agent 層級優化）

成本優化策略： Main Orchestrator 保持 Claude Opus 4.6，簡單的 Worker Sub-Agent 使用 GPT-5.4-mini/nano，省下大量成本。

每個 Agent 現在可以獨立配置 sandbox 和 tools 政策，實現真正的隔離。

{
  agents: {
    list: [
      {
        id: "personal",
        sandbox: { mode: "off" },  // 不沙箱化
        // 無工具限制
      },
      {
        id: "family",
        sandbox: { mode: "all", scope: "agent" },
        tools: {
          allow: ["read"],
          deny: ["exec", "write", "edit", "apply_patch", "browser", "canvas", "nodes", "cron"]
        }
      }
    ]
  }
}

Session Tools 可見性分層：

{
  tools: {
    sessions: {
      visibility: "tree"  // "self" | "tree" | "agent" | "all"
    }
  },
  agents: {
    defaults: {
      sandbox: {
        sessionToolsVisibility: "spawned"  // 沙箱 session 的額外限制
      }
    }
  }
}

實際應用場景：

• 家庭群組專用 Agent：沙箱隔離 + 嚴格工具政策，只允許讀取，拒絕寫入和危險工具
• 個人 Agent：不沙箱化，無工具限制，完全信任

v2026.3.22 新增——這個功能太實用了！

在主要對話過程中突然想到一個小問題，以前的做法是要麼打斷當前任務（不好），要麼等結束後再問（容易忘）。現在直接 /btw ：

使用方式： /btw <問題>

特性：

• 不存入主要 context（不打斷當前工作）
• 不使用工具
• 不消耗過多 token
• 回答後返回主對話，彷彿沒發生過

這簡直就是「打斷自己問自己」的完美解法。

v2026.3.22 新增——解決了困擾我很久的問題。

如果每天執行 20-40 個 cron 任務，一週累積 140-280 個 session 記錄，一個月超過 1000 個，每個都佔用 token 配額和載入時間。

現在可以設定自動清理：

{
  session: {
    maintenance: {
      pruneAfter: "24h"  // cron session 多久後被清理
    }
  }
}

另外 cron 重試策略也升級了：失敗的 cron 現在有指數退避重試（30 秒遞增到最多 60 分鐘）。

每個 agentId（像 researcher、coder）都代表一個完整的「大腦」：

• 獨立 Workspace：擁有自己的 AGENTS.md、SOUL.md、USER.md
• 獨立狀態目錄：認證配置、模型註冊、per-agent 配置
• 獨立會話存儲：聊天歷史和路由狀態
• 持續運行：不像子 Agent 那樣 60 分鐘後歸檔

{
  "agents": {
    "list": [
      { "id": "researcher", "workspace": "~/.openclaw/workspace-research" },
      { "id": "coder", "workspace": "~/.openclaw/workspace-code" }
    ]
  }
}

多 Agent 系統的安全設計非常重要，OpenClaw 的原則是隔離優先於便利：

1. agentToAgent 預設關閉：所有跨 Agent 通訊都需要明確 opt-in
2. 子 Agent 無法隨意 spawn：深度限制預防失控的 Agent 樹
3. 工具權限可配置：用沙箱和工具政策限制危險工具（如 exec、write）的訪問
4. Send Policy：可按 channel/chatType 配置發送規則

我的建議是：不要因為嫌麻煩就開放所有權限。用多少開多少，減少攻擊面。

子 Agent 的執行環境是隔離的，崩潰不會影響主 Agent。不過你也收不到詳細的錯誤信息——只會收到一個 announce step 告知任務失敗。

可以。全域並發上限是 8 個。不過也要注意，你的 LLM API 有 rate limit 的問題，別把配額一次性用光了。

sessions_spawn 的 UUID-based 會話 key 會丟失。如果需要重啟後恢復，請用 sessions_send 搭配 persistent agent。

官方建議 depth 2 為最佳實踐，5 層只在特殊需求下使用。層級越深，工具政策越嚴格（depth 2 的 Leaf Worker 幾乎沒有任何 Session Tools）。但要小心設計，別讓自己都不知道哪個 Agent 在做什麼。

老實說，這塊體驗還不夠好。我的建議是：

1. 先用 sessions_send + timeoutSeconds > 0 做同步測試
2. 確認邏輯正確後，再切換到非阻塞模式
3. 善用 label 參數標記不同任務，方便識別

根據社群文件，OpenClaw 正在推進一個更正式的協調層：

• 共享任務列表（dependencies、blocked、claimed states）
• 每個 Agent 的信箱用於異步 P2P 和廣播訊息

在 Teams 功能上線前，基於檔案的狀態共享 + sessions_send 仍是穩定的選項。

2026年3月的這波更新讓 OpenClaw 的 Multi-Agent 系統成熟了非常多。Inline 檔案附件、巢狀深度擴展、獨立 Thinking、不同模型分配，這些功能加起來幾乎可以應對所有常見的協作場景。

總結一下我的選擇邏輯：

• 需要委派任務、任務結果簡單 → sessions_spawn
• 需要來回協商、或需要穩定會話 → sessions_send
• 需要嚴格的流水線控制 → Lobster Workflow
• 複雜研究任務 → Orchestrator(high thinking) + Workers(low thinking)，模型分層省成本
• 突然想到的小問題 → /btw 側話不打斷

希望這篇升級版幫你省點踩坑的時間。如果有問題，歡迎留言交流。

更新時間：2026-03-30