Key Findings
  • OpenClaw 教學 代理（Agent）是具備身份、技能與獨立工作空間的自治單元，與傳統聊天機器人有本質上的區別——代理能自主規劃、調用工具並持續追蹤任務狀態[1]
  • 透過 openclaw agents add 指令，開發者可在 30 秒內建立一個全新代理，並立即為其指定模型、身份設定與工作空間[5]
  • 每個代理的 agent.md 身份檔案決定了其系統提示、人格特質與行為邊界，是 OpenClaw 代理設計最核心的配置層[2]
  • 模型配置支援 Primary / Fallback 雙層機制，搭配 Per-Agent 覆寫，可實現成本與品質的精細平衡[3]
  • Workspace 工作空間隔離機制確保每個代理僅能存取被授權的檔案與目錄，是 OpenClaw 安全模型的基石[7]

在 OpenClaw 的世界裡，「代理」（Agent）不僅僅是一個回答問題的聊天介面——它是一個具備獨立身份、專屬技能組合與隔離工作空間的自治實體。[6] 你可以將代理想像為團隊中的一位專業成員：它知道自己是誰、擅長什麼、被允許做什麼、以及在哪個環境中工作。

本文是 OpenClaw 系列的第二十篇，專門聚焦於 OpenClaw 代理的建立、配置與管理。無論你是第一次接觸 OpenClaw 的新手，還是已經在生產環境中運行多個代理的進階用戶，這份指南都將提供從零到一的完整路徑：從 agents add 的第一步開始，逐步深入 agent.md 身份設定、模型選擇與 Fallback 策略、Workspace 安全配置，直至進階的權限控管與多代理管理技巧。

一、什麼是 OpenClaw 代理？

在深入設定流程之前，有必要先釐清 OpenClaw 代理的本質——它與傳統聊天機器人（Chatbot）之間的差異，遠大於多數人的想像。

1.1 代理 vs. 聊天機器人：本質差異

傳統聊天機器人是被動的：它接收一則訊息，回覆一則訊息，然後等待下一則輸入。它沒有記憶（或僅有有限的會話記憶），不會主動規劃行動，也無法使用外部工具。聊天機器人本質上是一個「問答機器」。

OpenClaw 代理則截然不同。一個完整的 OpenClaw Agent 具備以下五項核心特質：[1]

簡而言之，聊天機器人是「回答者」，而 OpenClaw 代理是「執行者」。當你告訴代理「幫我重構這個模組並撰寫測試」，它會自行讀取程式碼、分析結構、進行修改、執行測試並回報結果——這一連串行動無需你逐步指示。[4]

1.2 OpenClaw 代理架構總覽

在 OpenClaw 的架構中，代理是最核心的運作單元。每個代理由四個層次組成：

理解這四個層次至關重要，因為後續所有的設定操作，本質上都是在配置這四個維度。[1]

1.3 何時需要建立自訂代理？

OpenClaw 安裝完成後，會自帶一個預設代理（Default Agent）。對於一般性的任務——程式碼問答、文件查詢、簡單的腳本撰寫——預設代理通常就已足夠。然而，以下情境建議建立自訂代理：

二、建立第一個代理

接下來進入實作。我們將使用 openclaw agents add 指令，從零開始建立一個 OpenClaw 代理。[5]

2.1 前置條件

在建立代理之前，請確認以下條件已經滿足：

你可以透過以下指令快速驗證環境是否就緒：

openclaw doctor

如果所有檢查都通過（顯示綠色勾號），即可開始建立代理。

2.2 使用 agents add 指令

建立新代理的核心指令是 openclaw agents add。最簡單的用法只需要一個代理名稱：[5]

openclaw agents add code-reviewer

執行後，OpenClaw 會完成以下動作：

如果你想在建立代理的同時指定模型與工作目錄，可以使用完整參數：

openclaw agents add code-reviewer \
  --model claude-opus-4-6 \
  --workspace ~/projects/my-app \
  --description "專責程式碼審查的 AI 代理"

這條指令一次完成了代理建立、模型綁定與工作空間設定。

2.3 互動式建立流程

如果你偏好引導式操作，可以不帶任何參數執行 agents add：

openclaw agents add

系統會進入互動模式，逐步詢問以下資訊：

互動式流程特別適合新手，因為系統會在每個步驟提供預設值與說明文字，降低配置錯誤的風險。

2.4 驗證代理建立成功

代理建立完成後，使用以下指令確認它已正確註冊：

openclaw agents list

你應該能看到類似以下的輸出：

Name             Model               Workspace          Status
─────────────────────────────────────────────────────────────────
default          claude-opus-4-6     ~/                 active
code-reviewer    claude-opus-4-6     ~/projects/my-app  ready
data-analyst     claude-sonnet-4-6   ~/data             ready

其中 active 表示當前正在使用的代理，ready 表示已配置完成但尚未啟動。[5]

三、agent.md 身份設定

如果說 agents add 是代理的「出生」，那麼 agent.md 就是代理的「靈魂」。這個 Markdown 格式的身份檔案，定義了代理如何理解自己的角色、如何與用戶互動、以及在什麼邊界內行動。[2]

3.1 agent.md 的位置與結構

每個代理的 agent.md 存放在其專屬目錄下：

~/.openclaw/agents/code-reviewer/agent.md

一個典型的 agent.md 包含以下區塊：

# Code Reviewer Agent

## Role
你是一位資深的軟體工程師，專精於程式碼品質審查。
你的審查範圍涵蓋：程式邏輯、安全漏洞、效能瓶頸、
可維護性與命名規範。

## Behavior Guidelines
- 提供具體、可行的改善建議，而非模糊的批評
- 對每個發現的問題標註嚴重程度：Critical / Warning / Info
- 引用業界最佳實踐（如 OWASP、Clean Code）作為論據
- 在審查完畢後提供總結摘要與整體評分（1-10）

## Constraints
- 不修改原始程式碼，僅提供建議
- 不執行任何可能影響生產環境的指令
- 審查範圍限於 Workspace 內的檔案

## Output Format
使用 Markdown 表格呈現發現清單，欄位包含：
檔案路徑、行號、嚴重程度、問題描述、改善建議

3.2 撰寫有效的系統提示

agent.md 的內容會被注入為代理的系統提示（System Prompt），因此撰寫品質直接影響代理的行為表現。以下是幾項關鍵原則：[2]

3.3 動態變數與模板語法

OpenClaw 的 agent.md 支援動態變數注入，允許你在身份設定中引用執行時的環境資訊：

# Data Analyst Agent

## Context
當前日期：{{current_date}}
工作目錄：{{workspace_path}}
代理名稱：{{agent_name}}

## Role
你是一位資料分析師，負責分析 {{workspace_path}}
目錄下的所有資料檔案。分析結果應以當前日期
（{{current_date}}）作為報告時間戳記。

這些變數會在代理啟動時被自動替換為實際值，使得同一份 agent.md 模板可以在不同環境中複用。[2]

3.4 多語言身份設定

OpenClaw 代理的身份設定完全支援多語言。如果你的使用場景以繁體中文為主，可以直接用中文撰寫 agent.md：

# 技術文件撰寫代理

## 角色定義
你是超智諮詢的技術文件專員。你負責將工程團隊的
技術實作轉化為清晰、結構化的繁體中文技術文件。

## 行為規範
- 使用台灣慣用的繁體中文術語
- 技術名詞首次出現時附註英文原文
- 程式碼區塊保持原文，不翻譯變數名稱
- 每篇文件必須包含目錄、摘要與參考資料

用代理的目標語言撰寫身份設定，能有效引導模型生成更地道、更符合語境的輸出。

四、模型配置

模型是代理的「大腦」，選擇正確的模型對代理的效能、成本與回應品質有決定性影響。OpenClaw 提供了三層模型配置機制，從全域預設到個別代理覆寫，確保最大的靈活性。[3]

4.1 全域預設模型

全域預設模型透過 agents.defaults.model.primary 設定，適用於所有未單獨指定模型的代理：

openclaw config set agents.defaults.model.primary claude-opus-4-6

這是最基礎的設定。當你建立一個新代理而未指定 --model 參數時，該代理會自動繼承此全域預設值。[3]

4.2 Fallback 備援模型

在生產環境中，依賴單一模型是危險的。API 限流、服務中斷、供應商維護窗口都可能導致代理突然無法運作。Fallback 機制解決了這個問題：

openclaw config set agents.defaults.model.fallbacks \
  '["claude-sonnet-4-6", "gpt-4o", "gemini-2.5-pro"]'

當 Primary 模型不可用時，系統會依序嘗試 Fallback 清單中的模型，直到找到第一個可用的為止。整個切換過程對用戶透明，代理的對話不會中斷。[3]

4.3 Per-Agent 模型覆寫

不同代理對模型的需求可能天差地遠。一個進行深度程式碼分析的代理需要最強大的推理能力，而一個只負責格式檢查的代理用輕量模型就足夠了。OpenClaw 允許為每個代理單獨覆寫模型設定：

openclaw config set agents.code-reviewer.model.primary claude-opus-4-6
openclaw config set agents.format-checker.model.primary claude-haiku-4

Per-Agent 設定的優先級高於全域預設。也就是說，如果 code-reviewer 代理有自己的 model.primary，它會忽略 agents.defaults.model.primary 的值。

你也可以直接在 openclaw.json 中以 JSON5 格式撰寫完整的模型配置：

{
  agents: {
    defaults: {
      model: {
        primary: "claude-opus-4-6",
        fallbacks: ["claude-sonnet-4-6", "gpt-4o"]
      }
    },
    "code-reviewer": {
      model: {
        primary: "claude-opus-4-6",
        // 代碼審查需要最高推理能力，不降級
        fallbacks: ["claude-opus-4-6"]
      }
    },
    "quick-helper": {
      model: {
        primary: "claude-haiku-4",
        fallbacks: ["gpt-4o-mini"]
      }
    }
  }
}

4.4 模型選擇實務建議

根據任務類型選擇合適的模型，是 OpenClaw 代理配置中最具商業價值的優化手段。以下是經過驗證的配置建議：

一個有效的經驗法則是：如果任務的輸出品質在兩個模型之間差異不超過 10%，優先選擇成本較低的模型。[3]

五、Workspace 工作空間

Workspace 是 OpenClaw 代理安全模型的核心。它定義了代理能夠存取的檔案系統範圍，是防止代理越權操作的第一道防線。[7]

5.1 預設 Workspace

如果未為代理指定 Workspace，OpenClaw 使用全域預設值：

openclaw config set agents.defaults.workspace "~/"

將預設 Workspace 設定為使用者家目錄（~/）意味著代理可以存取家目錄下的所有檔案。這在個人開發機上通常是可接受的，但在多人共用的伺服器環境中，應該縮小範圍。

5.2 Per-Agent Workspace

為每個代理設定獨立的 Workspace 是最佳實踐：[1]

openclaw config set agents.code-reviewer.workspace "~/projects/my-app"
openclaw config set agents.data-analyst.workspace "~/data/analytics"

這確保了 code-reviewer 代理只能存取 ~/projects/my-app 目錄下的檔案，無法讀取 ~/data/analytics 中的資料——即使用戶在對話中要求它這麼做。

5.3 Workspace 安全意涵

Workspace 的安全意涵不可低估。CrowdStrike 的研究報告指出，AI 代理的檔案系統存取權限是最常見的安全風險之一。[7] 以下幾點值得特別注意：

5.4 多 Workspace 配置

某些進階場景中，代理可能需要存取多個不相鄰的目錄。OpenClaw 支援為單一代理設定多個 Workspace 路徑：

{
  agents: {
    "full-stack-dev": {
      workspace: [
        "~/projects/frontend",
        "~/projects/backend",
        "~/projects/shared-libs"
      ]
    }
  }
}

代理將能存取所有列出的目錄，但仍無法存取未被列出的路徑。這在全端開發場景中特別有用，因為前端、後端與共用函式庫通常位於不同的目錄結構中。

六、代理管理指令

OpenClaw 提供了一套完整的 CLI 指令來管理代理的生命週期。[5]

6.1 列出所有代理

openclaw agents list

此指令顯示所有已註冊的代理，包含名稱、模型、Workspace 與狀態。你也可以使用 --verbose 旗標獲取更詳細的資訊：

openclaw agents list --verbose

詳細模式會額外顯示每個代理的 Fallback 模型清單、最後一次活動時間、累計 Token 消耗量等資訊。

6.2 切換活躍代理

在任何時刻，只有一個代理處於「活躍」（active）狀態。切換活躍代理的指令是：

openclaw agents switch code-reviewer

切換後，所有後續的對話都會由 code-reviewer 代理處理，使用其專屬的身份設定、模型與 Workspace。

6.3 刪除代理

移除不再需要的代理：

openclaw agents delete code-reviewer

系統會要求確認，並在刪除前提示是否需要備份 agent.md 與相關設定。刪除操作會從 openclaw.json 中移除代理的註冊記錄，並刪除其專屬目錄。

注意：預設代理（default）無法被刪除，這是 OpenClaw 的安全設計——確保系統在任何時刻都至少有一個可用的代理。[5]

6.4 重新命名代理

如果你想修改代理的名稱而不影響其配置，可以使用 rename 指令：

openclaw agents rename code-reviewer senior-reviewer

此操作會更新 openclaw.json 中的代理註冊名稱，並將檔案系統中的目錄從 ~/.openclaw/agents/code-reviewer/ 重新命名為 ~/.openclaw/agents/senior-reviewer/，所有配置與歷史記錄保持不變。

6.5 匯出與匯入代理配置

在團隊協作場景中，你可能需要將代理配置分享給其他成員。OpenClaw 支援代理配置的匯出與匯入：

// 匯出代理設定為 JSON 檔案
openclaw agents export code-reviewer > code-reviewer-config.json

// 從 JSON 檔案匯入代理設定
openclaw agents import code-reviewer-config.json

匯出的檔案包含 agent.md 內容、模型設定與 Workspace 配置，但不包含認證資訊（API Key），確保分享配置時不會洩漏機密。

七、進階配置

OpenClaw 代理的基礎配置已能滿足大多數使用場景。但在生產環境或高安全性需求的場景下，你需要更精細的控制。[1]

7.1 Timeout 設定

代理在執行長時間任務（如大型程式碼庫分析、複雜的多步驟工作流程）時，可能會遇到逾時問題。OpenClaw 允許在全域與 Per-Agent 層級設定 Timeout：

// 全域 Timeout（單位：秒）
openclaw config set agents.defaults.timeout 300

// Per-Agent Timeout
openclaw config set agents.code-reviewer.timeout 600

對於需要處理大型專案的代理，建議將 Timeout 設定為 10 分鐘（600 秒）以上。預設值通常是 120 秒，對於簡單任務足夠，但對於深度分析任務可能不足。

7.2 Allowlist 與 Blocklist

透過 Allowlist（允許清單）與 Blocklist（阻擋清單），你可以精細控制代理能夠執行的操作類型：[7]

{
  agents: {
    "code-reviewer": {
      permissions: {
        // 只允許讀取檔案與執行 git 指令
        allowlist: [
          "file:read",
          "shell:git *"
        ],
        // 明確禁止寫入與刪除
        blocklist: [
          "file:write",
          "file:delete",
          "shell:rm *",
          "shell:sudo *"
        ]
      }
    }
  }
}

Blocklist 的優先級高於 Allowlist。也就是說，即便某項操作出現在 Allowlist 中，只要它同時出現在 Blocklist 中，就會被阻擋。這種「預設拒絕，明確允許」的設計模式，是安全配置的業界最佳實踐。

7.3 Auto-Approve 設定

預設情況下，代理在執行敏感操作（如 Shell 指令、檔案寫入）前會要求用戶確認。在信任的環境中，你可以為特定代理啟用自動核准，以提升效率：

openclaw config set agents.code-reviewer.autoApprove '["file:read", "shell:git diff *"]'

此設定表示 code-reviewer 代理在讀取檔案與執行 git diff 指令時不需要用戶確認，但其他操作仍需手動核准。

安全警告：除非你完全理解 Auto-Approve 的風險，否則不建議對寫入操作或 Shell 執行啟用自動核准。一個被指令注入攻擊（Prompt Injection）影響的代理，若擁有自動核准的寫入權限，可能造成嚴重的安全事故。[7]

7.4 執行權限與安全沙箱

OpenClaw 提供了多層次的執行權限控制：

{
  agents: {
    "untrusted-agent": {
      sandbox: true,
      shell: {
        allowlist: ["git", "npm test", "python -m pytest"]
      },
      network: {
        allowlist: ["api.github.com", "registry.npmjs.org"]
      }
    }
  }
}

八、模型 Fallback 策略

模型 Fallback 不僅僅是一個「備胎」機制——設計得當的 Fallback 策略能在成本、延遲與可靠性之間取得最佳平衡。[3]

8.1 Fallback 鏈的運作原理

當代理發送推理請求時，OpenClaw 的模型路由器依以下順序處理：

需要注意的是，Fallback 切換僅發生在模型層級的錯誤（如 API 不可用）。如果 Primary 模型成功回應但內容品質不佳，Fallback 不會被觸發——品質控制需要透過其他機制（如 Evaluation Hooks）處理。

8.2 成本優化策略

Fallback 鏈的模型順序直接影響成本。一個常見的策略是「由強到弱」排列：

// 策略 A：品質優先
{
  model: {
    primary: "claude-opus-4-6",        // 最強推理
    fallbacks: ["claude-sonnet-4-6", "gpt-4o"]  // 逐步降級
  }
}

// 策略 B：成本優先
{
  model: {
    primary: "claude-sonnet-4-6",      // 性價比最高
    fallbacks: ["gpt-4o", "claude-haiku-4"]  // 逐步降低成本
  }
}

在生產環境中，多數團隊選擇策略 B——以中階模型作為 Primary，將高階模型的預算保留給真正需要深度推理的代理。根據實測數據，這種配置可降低 35–50% 的整體 Token 成本，而輸出品質的下降通常不超過 5–8%。[3]

8.3 延遲考量

Fallback 切換不是即時的——每次切換至少引入一次完整的 API 往返延遲（通常 1–3 秒）。如果 Fallback 鏈較長（例如有 4–5 個備援模型），最壞情況下用戶可能需要等待 10–15 秒才能收到回覆。

為了控制延遲，建議：

openclaw config set agents.defaults.model.fallbackTimeout 10

此設定表示每個 Fallback 模型最多等待 10 秒，超時則嘗試下一個。

8.4 跨供應商 Fallback

OpenClaw 的一大優勢是模型無關性（Model Agnostic）。你可以在 Fallback 鏈中混合不同供應商的模型，實現供應商層級的容錯：

{
  model: {
    primary: "claude-opus-4-6",          // Anthropic
    fallbacks: [
      "gpt-4o",                          // OpenAI
      "gemini-2.5-pro",                  // Google
      "claude-sonnet-4-6"               // Anthropic (另一個模型)
    ]
  }
}

這確保即便某個供應商的整個服務出現故障，代理仍能透過其他供應商的模型繼續運作。對於關鍵業務應用，跨供應商 Fallback 是不可妥協的配置。[3]

九、實戰範例：完整的代理配置工作流程

為了將前述所有概念串聯起來，以下提供一個完整的實戰範例——為一個軟體開發團隊設定三個專業代理。

9.1 場景描述

你的團隊正在開發一個全端 Web 應用程式，需要三個角色：

9.2 逐步設定

首先，建立三個代理：

openclaw agents add architect \
  --model claude-opus-4-6 \
  --workspace ~/projects/my-app \
  --description "系統架構師——負責設計決策與技術選型"

openclaw agents add developer \
  --model claude-sonnet-4-6 \
  --workspace ~/projects/my-app \
  --description "全端開發者——負責程式碼實作"

openclaw agents add reviewer \
  --model claude-opus-4-6 \
  --workspace ~/projects/my-app \
  --description "程式碼審查員——負責品質把關與安全掃描"

接著，為審查者代理設定權限限制，確保它不會直接修改程式碼：

openclaw config set agents.reviewer.permissions.blocklist \
  '["file:write", "file:delete", "shell:rm *"]'

最後，為開發者代理設定自動核准常用操作，以提升開發效率：

openclaw config set agents.developer.autoApprove \
  '["file:read", "file:write", "shell:npm *", "shell:git *"]'

9.3 完整的 openclaw.json 配置

完成上述設定後，openclaw.json 中與代理相關的部分看起來類似如下：

{
  agents: {
    defaults: {
      model: {
        primary: "claude-sonnet-4-6",
        fallbacks: ["gpt-4o", "claude-haiku-4"]
      },
      workspace: "~/",
      timeout: 180
    },
    architect: {
      model: {
        primary: "claude-opus-4-6",
        fallbacks: ["gpt-4o", "gemini-2.5-pro"]
      },
      workspace: "~/projects/my-app",
      timeout: 600
    },
    developer: {
      model: {
        primary: "claude-sonnet-4-6",
        fallbacks: ["gpt-4o"]
      },
      workspace: "~/projects/my-app",
      autoApprove: ["file:read", "file:write", "shell:npm *", "shell:git *"]
    },
    reviewer: {
      model: {
        primary: "claude-opus-4-6",
        fallbacks: ["claude-opus-4-6"]
      },
      workspace: "~/projects/my-app",
      permissions: {
        blocklist: ["file:write", "file:delete", "shell:rm *"]
      }
    }
  }
}

十、常見問題（FAQ）

Q1：建立代理後可以修改其名稱嗎？

可以。使用 openclaw agents rename <old-name> <new-name> 指令即可重新命名代理。所有配置與歷史記錄都會保留，只有名稱與對應的檔案系統目錄會變更。[5]

Q2：代理的數量有上限嗎？

OpenClaw 本身對代理數量沒有硬性限制。然而，每個代理都會佔用一定的磁碟空間（主要是 agent.md 與歷史記錄），且管理過多代理會增加配置的認知負擔。實務上，建議單一使用者維護不超過 10–15 個活躍代理，超過此數量時考慮使用 Agent Teams 進行分組管理。[1]

Q3：如何在代理之間共享 agent.md 模板？

目前 OpenClaw 尚未內建模板共享機制。推薦的做法是將常用的 agent.md 範本存放在版本控制系統（如 Git）中，建立新代理後再手動複製或使用 agents import 匯入。社群中也有開發者建立了 agent.md 的公開模板庫，可以直接參考引用。

Q4：Per-Agent 模型設定覆蓋了全域預設，但 Fallback 也會被覆蓋嗎？

是的。Per-Agent 的模型設定是「完整覆蓋」，而非「合併」。如果你為某個代理設定了 model.primary 但未設定 model.fallbacks，該代理將沒有 Fallback 模型（不會繼承全域預設的 Fallback 清單）。因此，建議在覆寫模型設定時，同時設定 Primary 與 Fallback。[3]

Q5：Workspace 可以指定為網路路徑（如 NFS 掛載點）嗎？

技術上可行，但不建議。OpenClaw 的檔案操作假設本機檔案系統的延遲特性，網路檔案系統可能導致意外的逾時或效能問題。如果必須使用網路儲存，建議適當增加 Timeout 值，並在 agent.md 中提醒代理避免頻繁的小檔案讀寫操作。

Q6：刪除代理後，其對話歷史還能恢復嗎？

不能。openclaw agents delete 會刪除代理的所有資料，包含對話歷史。如果你可能需要這些記錄，請在刪除前使用 agents export 備份。或者，改用 agents archive 將代理封存而非刪除——封存的代理不會出現在 agents list 中，但資料仍保留在磁碟上。[5]

Q7：如何讓代理在啟動時自動載入特定的 context 檔案？

在 agent.md 中，你可以使用 {{file:path/to/context.md}} 語法引入外部檔案的內容。這些檔案會在代理啟動時被讀取並注入系統提示中。注意，引入的檔案路徑相對於代理的 Workspace 根目錄。[2]

Q8：OpenClaw 代理支援哪些模型供應商？

截至 2026 年 2 月，OpenClaw 官方支援 Anthropic（Claude 系列）、OpenAI（GPT 系列）、Google（Gemini 系列）、Mistral、Cohere 等主流供應商。此外，透過 OpenAI 相容 API 格式，你也可以連接自行託管的開源模型（如 Llama、Qwen 等）。[3]

Q9：代理的 autoApprove 設定是否支援正則表達式？

目前支援 glob 風格的模式匹配（如 shell:git *），但不支援完整的正則表達式。如果你需要更複雜的匹配邏輯，建議透過 Blocklist 進行反向控制——先允許廣泛的操作類別，再透過 Blocklist 排除特定的危險操作。

Q10：如何監控代理的 Token 消耗量？

使用 openclaw agents stats <agent-name> 可以查看指定代理的 Token 消耗統計，包含每日、每週與每月的使用量。若需要更細粒度的監控，建議搭配 OpenClaw 的 Webhook 功能，將 Token 消耗事件發送至外部監控平台（如 Grafana 或 Datadog）。[1]