概念

Agent 是 OpenClaw 的「大腦」— 接收訊息、用 LLM 思考、執行工具、產生回覆。

一個 Agent 的生命週期：

接收訊息 → Gateway 路由到正確的 agent
組裝 context → 載入 session 歷史 + workspace 檔案
LLM 推論 → 送給模型（Claude/GPT）處理
工具執行 → 如果模型要求，執行 exec/browser/message 等
串流回覆 → 邊想邊回覆給用戶

Agent Loop（核心迴圈）

訊息進來
    ↓
Session Lock（鎖定 session，避免並發）
    ↓
組裝 System Prompt
    ↓
呼叫 LLM
    ↓
工具呼叫？ ─── 是 ──→ 執行工具 ──→ 結果回 LLM
    │
    否
    ↓
串流回覆
    ↓
儲存到 Session 歷史

核心代碼

1. Agent 執行入口

// 簡化的 agent loop 邏輯
async function runAgent(session, message) {
  // 1. 組裝 prompt
  const systemPrompt = buildSystemPrompt({
    workspace: session.workspace,
    skills: loadSkills(),
    bootstrapFiles: ['AGENTS.md', 'SOUL.md', 'TOOLS.md']
  });
  
  // 2. 準備對話歷史
  const messages = [
    { role: 'system', content: systemPrompt },
    ...session.history,
    { role: 'user', content: message }
  ];
  
  // 3. 呼叫 LLM（支援 streaming）
  const stream = await llm.chat(messages, {
    model: session.model,
    tools: availableTools
  });
  
  // 4. 處理回應
  for await (const chunk of stream) {
    if (chunk.type === 'tool_call') {
      const result = await executeTool(chunk.tool, chunk.args);
      messages.push({ role: 'tool', content: result });
      // 繼續讓 LLM 處理工具結果
    } else {
      yield chunk.text; // 串流文字給用戶
    }
  }
}

關鍵點：

Agent 是一個「迴圈」，可能執行多次工具
Session 記錄所有對話歷史
Streaming 讓用戶看到「正在思考」

2. Session 鎖定機制

// 每個 session 同時只能有一個 run
const sessionLane = `session:agent:${agentId}:${sessionKey}`;

await withLock(sessionLane, async () => {
  // 只有拿到鎖才能執行
  await runAgentLoop(session, message);
});

為什麼需要鎖？

避免兩則訊息同時修改同一個 session
確保對話歷史順序正確
防止工具執行衝突

3. Queue 模式（處理連續訊息）

// 當 agent 正在處理時，新訊息怎麼辦？
const queueMode = config.queue.mode;

switch (queueMode) {
  case 'collect':
    // 收集起來，等當前 run 結束再一起處理
    queue.push(newMessage);
    break;
    
  case 'steer':
    // 中斷當前工具，注入新訊息
    abortCurrentToolCalls();
    injectMessage(newMessage);
    break;
    
  case 'followup':
    // 等當前 run 結束，新訊息開始新的 run
    waitForCurrentRun();
    startNewRun(newMessage);
    break;
}

💡 關鍵洞察

Agent = LLM + Tools + Memory
- LLM 負責「思考」
- Tools 負責「行動」
- Session 負責「記憶」
串流很重要
- 不是等全部想完才回覆
- 邊想邊說，用戶體驗更好
- 也讓你知道「agent 還活著」
一個 session 同時只有一個 run
- 這是設計決策，不是 bug
- 避免複雜的並發問題
- Queue 機制處理連續訊息
工具執行是可中斷的
- steer 模式可以中斷當前工具
- 讓用戶能「打斷」agent

🔗 核心檔案

Agent 核心：/opt/homebrew/lib/node_modules/openclaw/dist/agent-*.js
Session 管理：session 狀態在 ~/.openclaw/agents/<agentId>/sessions/
文檔：/opt/homebrew/lib/node_modules/openclaw/docs/concepts/agent-loop.md

明天： Session 機制（isolated vs main）

Day 2: Agent 系統（處理訊息的核心邏輯）