OpenClaw Agents 指令完全指南：add、list、config 與模型配置

一、引言：為什麼需要深入了解 Agents 指令

OpenClaw 作為當前最具影響力的開源 AI 代理框架之一，其核心價值在於讓開發者能夠透過簡潔的 CLI 指令，快速建立、配置與管理多個智能代理。^[5] 然而在實務操作中，許多開發者在第一次接觸 openclaw agents add 指令時，往往因為參數組合過多、配置層級不清而感到困惑——這不僅浪費了寶貴的開發時間，更可能導致代理運行時出現非預期行為。

根據 OpenClaw 官方社群統計，超過 60% 的初期使用問題都集中在三個面向：agents add 的指令語法、agents list 的輸出解讀、以及 config set 的模型配置路徑。^[1] 這正是本文要徹底解決的問題。

本文將以「可直接複製執行」為原則，完整拆解 OpenClaw agents 系列指令的每一個參數、每一個選項，並搭配配置檔結構的深度解析，讓你在讀完後能夠：

• 精準掌握 openclaw agents add 的完整語法與每個參數的作用
• 熟練使用 openclaw agents list 進行代理狀態監控與管理
• 理解 openclaw config set 在模型配置中的運作機制
• 設計適合你的多代理、多模型配置架構
• 快速排解常見的 agents 指令錯誤

如果你已經閱讀過我們的 OpenClaw 代理設定指南 或 OpenClaw 設定完全指南，本文將為你提供更聚焦於指令層面的操作參考。若你是第一次接觸 OpenClaw，建議先參閱 OpenClaw 教學 掌握基礎概念。

二、OpenClaw 配置檔結構總覽

在深入 agents 指令之前，必須先理解 OpenClaw 的配置檔架構——因為每一條 agents 指令的執行結果，最終都會反映在配置檔的變更上。^[2]

2.1 雙層配置體系

OpenClaw 採用雙層配置體系，分別對應「全域設定」與「專案設定」：

全域配置（Global Config）位於使用者家目錄下：

~/.config/openclaw/
├── config.json          # 全域設定（模型 API 金鑰、預設模型等）
├── agents/              # 全域代理定義
│   ├── default/
│   │   └── agent.md     # 預設代理身份檔
│   ├── code-reviewer/
│   │   └── agent.md
│   └── doc-writer/
│       └── agent.md
├── templates/           # 代理範本
│   ├── minimal.json
│   └── full.json
└── logs/                # 運行日誌
    └── openclaw.log

專案配置（Project Config）位於專案根目錄：

your-project/
├── openclaw.json        # 專案級配置（覆寫全域設定）
├── .openclaw/
│   ├── agents/          # 專案專屬代理
│   │   └── project-bot/
│   │       └── agent.md
│   └── cache/           # 本地快取
└── src/
    └── ...

配置的優先順序遵循「就近優先」原則：專案級配置 > 全域配置 > 內建預設值。這意味著你可以在全域設定中定義通用的模型金鑰與預設代理，再於個別專案中覆寫特定設定。^[2]

2.2 openclaw.json 核心結構

無論是全域的 config.json 還是專案級的 openclaw.json，其核心結構包含五個頂層區塊：

{
"agents": {
  "defaults": {
    "model": {
      "primary": "anthropic:claude-opus-4",
      "fallback": "openai:gpt-4.1"
    },
    "workspace": "./",
    "tools": ["file", "shell", "browser"]
  },
  "registered": {
    "code-reviewer": {
      "identity": ".openclaw/agents/code-reviewer/agent.md",
      "model": {
        "primary": "anthropic:claude-opus-4"
      },
      "workspace": "./src"
    }
  }
},
"models": {
  "providers": {
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}",
      "baseUrl": "https://api.anthropic.com"
    },
    "openai": {
      "apiKey": "${OPENAI_API_KEY}"
    }
  }
},
"tools": {
  "enabled": ["file", "shell", "browser", "mcp"],
  "permissions": {
    "shell": { "allowlist": ["git", "npm", "node"] }
  }
},
"security": {
  "sandbox": true,
  "networkPolicy": "restricted",
  "maxTokensPerRequest": 128000
},
"logging": {
  "level": "info",
  "output": "~/.config/openclaw/logs/openclaw.log"
}
}

其中 agents 區塊是本文的核心——它同時包含了 defaults（全域預設值）與 registered（已註冊代理清單）兩個子區塊。當你執行 openclaw agents add 時，新代理的定義會被寫入 registered 物件中；當你執行 openclaw config set agents.defaults.* 時，修改的則是 defaults 區塊。^[4]

2.3 配置檔的環境變數支援

OpenClaw 配置檔支援 ${ENV_VAR} 語法引用環境變數，這對於 API 金鑰等敏感資訊尤其重要：

# 設定環境變數（建議加入 .bashrc 或 .zshrc）
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxx"
export OPENAI_API_KEY="sk-xxxxxxxxxxxx"

# 在 openclaw.json 中引用
"apiKey": "${ANTHROPIC_API_KEY}"

這確保敏感金鑰不會被直接寫入配置檔，避免意外提交至版本控制系統。^[2]

三、openclaw agents add 完整語法

這是 OpenClaw 代理管理中最核心的指令——它負責建立並註冊一個新的代理。以下是完整的語法拆解。^[1]

3.1 基本語法

openclaw agents add <agent-name> [options]

其中 <agent-name> 是唯一的必填參數，代表代理的識別名稱。命名規則如下：

• 僅允許小寫字母、數字與連字號（a-z、0-9、-）
• 必須以字母開頭，不得以連字號結尾
• 長度限制為 2 至 64 個字元
• 名稱在同一配置層級中必須唯一

3.2 完整參數表

以下列出 openclaw agents add 支援的所有選項：

openclaw agents add <agent-name>
--model <model-id>            # 指定主要模型（覆寫全域預設）
--fallback-model <model-id>   # 指定 Fallback 模型
--identity <path>             # 指定 agent.md 身份檔路徑
--workspace <directory>       # 指定工作空間目錄
--tools <tool1,tool2,...>     # 指定允許使用的工具（逗號分隔）
--template <template-name>    # 從範本建立代理
--description <text>          # 代理描述文字
--max-tokens <number>         # 單次請求最大 Token 數
--temperature <float>         # 模型溫度參數（0.0 ~ 2.0）
--global                      # 註冊為全域代理（而非專案級）
--no-identity                 # 跳過自動建立 agent.md
--dry-run                     # 預覽變更但不實際執行
--verbose                     # 顯示詳細執行過程
--json                        # 以 JSON 格式輸出結果

3.3 最簡範例：30 秒建立第一個代理

以下是最精簡的代理建立方式，僅需提供名稱：

# 建立一個名為 my-assistant 的代理（使用全域預設模型）
openclaw agents add my-assistant

執行後，OpenClaw 會自動完成以下動作：^[1]

• 在 .openclaw/agents/my-assistant/ 目錄下建立 agent.md 身份檔（含預設系統提示）
• 將代理註冊至 openclaw.json 的 agents.registered 區塊
• 繼承 agents.defaults 中的模型、工具與工作空間設定

輸出範例：

✓ Agent "my-assistant" created successfully
  Identity: .openclaw/agents/my-assistant/agent.md
  Model:    anthropic:claude-opus-4 (inherited from defaults)
  Workspace: ./
  Tools:    file, shell, browser

3.4 進階範例：完整參數配置

以下範例展示了一個具備完整配置的代理建立指令：

# 建立一個專責程式碼審查的代理
openclaw agents add code-reviewer \
--model anthropic:claude-opus-4 \
--fallback-model openai:gpt-4.1 \
--identity ./agents/code-reviewer/agent.md \
--workspace ./src \
--tools file,shell,git \
--description "專責程式碼審查的代理，聚焦於安全漏洞與效能問題" \
--max-tokens 64000 \
--temperature 0.1

這條指令做了以下設定：

• 主要模型設為 Anthropic Claude Opus 4，Fallback 模型設為 OpenAI GPT-4.1
• 使用自訂的 agent.md 身份檔（你可以在其中定義審查標準與回覆風格）
• 工作空間限制在 ./src 目錄，防止代理存取專案以外的檔案
• 僅允許使用 file（檔案讀寫）、shell（指令執行）、git（版本控制）三項工具
• 溫度設為 0.1（降低隨機性，使審查結果更一致）

3.5 從範本建立代理

OpenClaw 內建數個代理範本，可透過 --template 快速建立具備預設配置的代理：^[4]

# 查看可用範本
openclaw agents templates list

# 從 "code-assistant" 範本建立代理
openclaw agents add my-coder --template code-assistant

# 從 "doc-writer" 範本建立代理
openclaw agents add my-writer --template doc-writer

範本會預先配置 agent.md 的系統提示、工具權限與建議的模型設定，大幅縮短初始配置時間。

3.6 使用 --dry-run 預覽變更

在正式建立代理前，建議先使用 --dry-run 旗標預覽將要發生的變更：

openclaw agents add data-analyst \
--model openai:gpt-4.1 \
--workspace ./data \
--tools file,shell,python \
--dry-run

輸出將顯示：

[DRY RUN] The following changes would be applied:

1. Create directory: .openclaw/agents/data-analyst/
2. Create file: .openclaw/agents/data-analyst/agent.md
3. Update openclaw.json:
   + agents.registered.data-analyst = {
       "identity": ".openclaw/agents/data-analyst/agent.md",
       "model": { "primary": "openai:gpt-4.1" },
       "workspace": "./data",
       "tools": ["file", "shell", "python"]
     }

No changes were made (dry run).

這在團隊協作環境中尤其實用——你可以將 --dry-run 的輸出貼入 Pull Request，讓團隊成員在代理建立前進行審查。

3.7 建立全域代理

預設情況下，agents add 會將代理註冊在專案級配置中。若要建立跨專案可用的全域代理，需加上 --global 旗標：

# 建立全域可用的通用助手
openclaw agents add general-assistant \
--model anthropic:claude-sonnet-4 \
--tools file,shell,browser \
--global

全域代理的定義會寫入 ~/.config/openclaw/agents/ 目錄與 ~/.config/openclaw/config.json，在任何專案目錄下都可使用。^[2]

四、openclaw agents list——列出與管理代理

建立代理後，你需要一種方式來查看、監控與管理所有已註冊的代理。openclaw agents list 正是為此設計的指令。^[4]

4.1 基本用法

# 列出當前專案的所有代理
openclaw agents list

預設輸出為簡潔的表格格式：

NAME              MODEL                        STATUS
my-assistant      anthropic:claude-opus-4      active
code-reviewer     anthropic:claude-opus-4      active
data-analyst      openai:gpt-4.1              active
doc-writer        anthropic:claude-sonnet-4   inactive

4.2 詳細模式（--verbose）

加上 --verbose 旗標可顯示每個代理的完整配置資訊：

openclaw agents list --verbose

輸出範例：

Agent: my-assistant
  Identity:  .openclaw/agents/my-assistant/agent.md
  Model:     anthropic:claude-opus-4 (inherited)
  Fallback:  openai:gpt-4.1 (inherited)
  Workspace: ./
  Tools:     file, shell, browser
  Tokens:    128000 (inherited)
  Temp:      0.7 (inherited)
  Status:    active
  Created:   2026-02-14T10:23:45Z

Agent: code-reviewer
  Identity:  ./agents/code-reviewer/agent.md
  Model:     anthropic:claude-opus-4 (explicit)
  Fallback:  openai:gpt-4.1 (explicit)
  Workspace: ./src
  Tools:     file, shell, git
  Tokens:    64000
  Temp:      0.1
  Status:    active
  Created:   2026-02-14T10:30:12Z

---
Total: 4 agents (3 active, 1 inactive)
Config: 2 explicit, 2 inherited

注意輸出中的 (inherited) 與 (explicit) 標記——這明確標示了每個設定值是來自全域預設還是代理自身的覆寫配置，這在除錯時非常有用。

4.3 JSON 格式輸出

當你需要在腳本或 CI/CD 流程中程式化處理代理資訊時，可使用 --format json：

# 輸出 JSON 格式
openclaw agents list --format json

# 搭配 jq 篩選特定代理
openclaw agents list --format json | jq '.agents[] | select(.model.primary == "anthropic:claude-opus-4")'

# 僅列出作用中的代理名稱
openclaw agents list --format json | jq -r '.agents[] | select(.status == "active") | .name'

4.4 篩選與搜尋

agents list 支援多種篩選參數：

# 僅列出使用特定模型的代理
openclaw agents list --model anthropic:claude-opus-4

# 僅列出作用中的代理
openclaw agents list --status active

# 僅列出全域代理
openclaw agents list --global

# 同時顯示全域與專案級代理
openclaw agents list --all

# 以建立時間排序
openclaw agents list --sort created

# 以名稱排序
openclaw agents list --sort name

4.5 搭配其他管理指令

除了 list 之外，openclaw agents 還提供以下子指令用於代理管理：^[1]

# 查看單一代理的詳細配置
openclaw agents show code-reviewer

# 修改已有代理的設定
openclaw agents update code-reviewer --model openai:gpt-4.1

# 暫時停用代理
openclaw agents disable doc-writer

# 重新啟用代理
openclaw agents enable doc-writer

# 移除代理（需確認）
openclaw agents remove data-analyst

# 強制移除（跳過確認）
openclaw agents remove data-analyst --force

# 複製已有代理的配置建立新代理
openclaw agents clone code-reviewer security-reviewer

五、openclaw config set 模型配置

openclaw config set 是 OpenClaw 配置管理的瑞士軍刀，幾乎所有配置項都可透過這條指令修改。在代理管理的上下文中，最常用的是模型相關的配置路徑。^[2]

5.1 設定全域預設模型

以下是最常見的模型配置操作——設定所有代理的預設主要模型：

# 設定全域預設主要模型
openclaw config set agents.defaults.model.primary anthropic:claude-opus-4

# 設定全域預設 Fallback 模型
openclaw config set agents.defaults.model.fallback openai:gpt-4.1

# 驗證設定結果
openclaw config get agents.defaults.model

輸出：

agents.defaults.model:
  primary: anthropic:claude-opus-4
  fallback: openai:gpt-4.1

當你執行 openclaw config set agents.defaults.model.primary 時，這條設定會寫入當前目錄的 openclaw.json（專案級）。若要修改全域設定，需加上 --global 旗標：^[4]

# 修改全域預設模型
openclaw config set agents.defaults.model.primary anthropic:claude-opus-4 --global

5.2 設定個別代理的模型

若要為特定代理覆寫模型設定，使用 agents.registered.<agent-name> 路徑：

# 為 code-reviewer 代理設定專屬模型
openclaw config set agents.registered.code-reviewer.model.primary anthropic:claude-opus-4

# 為 data-analyst 代理設定不同的模型
openclaw config set agents.registered.data-analyst.model.primary openai:gpt-4.1

# 為 doc-writer 設定成本較低的模型
openclaw config set agents.registered.doc-writer.model.primary anthropic:claude-haiku-4

5.3 模型配置的完整路徑參考

以下列出所有與代理模型相關的 config 路徑：

# ── 全域預設 ──
agents.defaults.model.primary          # 預設主要模型
agents.defaults.model.fallback         # 預設 Fallback 模型
agents.defaults.model.temperature      # 預設溫度
agents.defaults.model.maxTokens        # 預設最大 Token 數
agents.defaults.model.topP             # 預設 Top-P 值
agents.defaults.model.topK             # 預設 Top-K 值
agents.defaults.model.stopSequences    # 預設停止序列

# ── 個別代理 ──
agents.registered.<name>.model.primary
agents.registered.<name>.model.fallback
agents.registered.<name>.model.temperature
agents.registered.<name>.model.maxTokens

# ── 模型提供者 ──
models.providers.<provider>.apiKey
models.providers.<provider>.baseUrl
models.providers.<provider>.rateLimit
models.providers.<provider>.timeout

5.4 config get 與 config list

設定之後，你需要驗證配置是否正確：

# 查看特定配置值
openclaw config get agents.defaults.model.primary
# 輸出: anthropic:claude-opus-4

# 查看某個代理的完整配置
openclaw config get agents.registered.code-reviewer
# 輸出:
# agents.registered.code-reviewer:
#   identity: ./agents/code-reviewer/agent.md
#   model:
#     primary: anthropic:claude-opus-4
#     fallback: openai:gpt-4.1
#   workspace: ./src
#   tools: [file, shell, git]

# 列出所有配置項（含來源標記）
openclaw config list --show-origin

# 僅列出與 agents 相關的配置
openclaw config list --filter agents

# 以 JSON 格式輸出完整配置
openclaw config list --format json

5.5 config unset 與 config reset

若要移除某個覆寫設定（讓代理回退到繼承全域預設值）：

# 移除 code-reviewer 的模型覆寫，使其繼承全域預設
openclaw config unset agents.registered.code-reviewer.model.primary

# 重置整個 agents.defaults 區塊為出廠預設值
openclaw config reset agents.defaults

# 重置所有配置為出廠預設值（需確認）
openclaw config reset --all

六、實戰範例：多代理模型配置

在真實的企業開發環境中，你通常需要多個代理協同工作，且不同代理對模型的需求截然不同。^[3] 以下透過一個完整的實戰範例，展示如何設計多代理的模型配置架構。

6.1 場景描述

假設你的團隊需要以下四個代理：

• architect：系統架構師，負責高層設計決策——需要最強的推理能力
• coder：程式開發者，負責撰寫與修改程式碼——需要速度與品質的平衡
• reviewer：程式碼審查者，負責檢查品質與安全——需要精準度
• documenter：文件撰寫者，負責維護技術文件——可使用成本較低的模型

6.2 Step 1：設定全域預設與模型提供者

# 設定模型提供者的 API 金鑰
openclaw config set models.providers.anthropic.apiKey '${ANTHROPIC_API_KEY}' --global
openclaw config set models.providers.openai.apiKey '${OPENAI_API_KEY}' --global

# 設定全域預設模型（適用於未特別配置的代理）
openclaw config set agents.defaults.model.primary anthropic:claude-sonnet-4 --global
openclaw config set agents.defaults.model.fallback openai:gpt-4.1-mini --global
openclaw config set agents.defaults.model.temperature 0.5 --global
openclaw config set agents.defaults.model.maxTokens 64000 --global

6.3 Step 2：建立四個代理

# 架構師——使用最強模型，高 Token 上限
openclaw agents add architect \
--model anthropic:claude-opus-4 \
--fallback-model anthropic:claude-sonnet-4 \
--max-tokens 128000 \
--temperature 0.3 \
--tools file,shell,browser,mcp \
--description "系統架構師：負責高層設計、技術選型與架構決策"

# 開發者——平衡速度與品質
openclaw agents add coder \
--model anthropic:claude-sonnet-4 \
--fallback-model openai:gpt-4.1 \
--max-tokens 64000 \
--temperature 0.4 \
--tools file,shell,git,npm \
--workspace ./src \
--description "程式開發者：負責程式碼撰寫、功能實作與單元測試"

# 審查者——低溫度確保一致性
openclaw agents add reviewer \
--model anthropic:claude-opus-4 \
--fallback-model anthropic:claude-sonnet-4 \
--max-tokens 64000 \
--temperature 0.1 \
--tools file,git \
--workspace ./src \
--description "程式碼審查者：聚焦安全漏洞、效能瓶頸與程式碼風格"

# 文件撰寫者——使用成本較低的模型
openclaw agents add documenter \
--model anthropic:claude-haiku-4 \
--fallback-model openai:gpt-4.1-mini \
--max-tokens 32000 \
--temperature 0.7 \
--tools file,shell \
--workspace ./docs \
--description "文件撰寫者：維護 README、API 文件與技術指南"

6.4 Step 3：驗證配置

# 列出所有代理及其配置
openclaw agents list --verbose

# 驗證特定代理的模型設定
openclaw config get agents.registered.architect.model
# 輸出:
# agents.registered.architect.model:
#   primary: anthropic:claude-opus-4
#   fallback: anthropic:claude-sonnet-4

# 使用 --dry-run 測試代理是否能正常啟動
openclaw agents test architect --dry-run

6.5 Step 4：配置結果的 openclaw.json

完成上述步驟後，你的 openclaw.json 將呈現如下結構：

{
"agents": {
  "defaults": {
    "model": {
      "primary": "anthropic:claude-sonnet-4",
      "fallback": "openai:gpt-4.1-mini",
      "temperature": 0.5,
      "maxTokens": 64000
    }
  },
  "registered": {
    "architect": {
      "identity": ".openclaw/agents/architect/agent.md",
      "model": {
        "primary": "anthropic:claude-opus-4",
        "fallback": "anthropic:claude-sonnet-4",
        "temperature": 0.3,
        "maxTokens": 128000
      },
      "tools": ["file", "shell", "browser", "mcp"],
      "description": "系統架構師"
    },
    "coder": {
      "identity": ".openclaw/agents/coder/agent.md",
      "model": {
        "primary": "anthropic:claude-sonnet-4",
        "fallback": "openai:gpt-4.1",
        "temperature": 0.4,
        "maxTokens": 64000
      },
      "workspace": "./src",
      "tools": ["file", "shell", "git", "npm"],
      "description": "程式開發者"
    },
    "reviewer": {
      "identity": ".openclaw/agents/reviewer/agent.md",
      "model": {
        "primary": "anthropic:claude-opus-4",
        "fallback": "anthropic:claude-sonnet-4",
        "temperature": 0.1,
        "maxTokens": 64000
      },
      "workspace": "./src",
      "tools": ["file", "git"],
      "description": "程式碼審查者"
    },
    "documenter": {
      "identity": ".openclaw/agents/documenter/agent.md",
      "model": {
        "primary": "anthropic:claude-haiku-4",
        "fallback": "openai:gpt-4.1-mini",
        "temperature": 0.7,
        "maxTokens": 32000
      },
      "workspace": "./docs",
      "tools": ["file", "shell"],
      "description": "文件撰寫者"
    }
  }
}
}

6.6 成本考量

多代理配置的一大優勢在於成本最佳化。以上述四個代理為例，假設每日的使用分佈如下：

• architect：每日約 5 次對話（高 Token 消耗，但使用頻率低）
• coder：每日約 50 次對話（中等 Token 消耗，高頻使用）
• reviewer：每日約 20 次對話（中等 Token 消耗，中頻使用）
• documenter：每日約 10 次對話（低 Token 消耗，低頻使用）

透過為不同代理指派不同等級的模型，相較於統一使用最高等級模型，預估可降低 40–60% 的 API 費用，同時不犧牲關鍵環節（架構設計、安全審查）的推理品質。^[3]

七、常見問題排解

以下整理了開發者在使用 agents 指令時最常遇到的錯誤及其解決方式。^[1]

7.1 Error: Agent name already exists

$ openclaw agents add coder
Error: Agent "coder" already exists in project config.
Use --force to overwrite, or choose a different name.

原因：同一配置層級中已存在同名代理。

解決方式：

# 方式 1：使用不同名稱
openclaw agents add coder-v2

# 方式 2：先移除再重建
openclaw agents remove coder
openclaw agents add coder --model anthropic:claude-sonnet-4

# 方式 3：使用 update 修改現有代理
openclaw agents update coder --model anthropic:claude-sonnet-4

7.2 Error: Model not found

$ openclaw agents add my-bot --model anthropic:claude-5
Error: Model "anthropic:claude-5" not found.
Available models for provider "anthropic":
  - anthropic:claude-opus-4
  - anthropic:claude-sonnet-4
  - anthropic:claude-haiku-4

原因：指定的模型 ID 不正確或該模型尚未在提供者中啟用。

解決方式：

# 查看所有可用模型
openclaw models list

# 查看特定提供者的可用模型
openclaw models list --provider anthropic

# 使用正確的模型 ID
openclaw agents add my-bot --model anthropic:claude-opus-4

7.3 Error: API key not configured

$ openclaw agents add my-bot --model anthropic:claude-opus-4
Error: No API key configured for provider "anthropic".
Set it with: openclaw config set models.providers.anthropic.apiKey <your-key>

原因：尚未設定對應模型提供者的 API 金鑰。

解決方式：

# 方式 1：透過 config set 設定
openclaw config set models.providers.anthropic.apiKey 'sk-ant-xxxx' --global

# 方式 2：透過環境變數設定（建議）
export ANTHROPIC_API_KEY="sk-ant-xxxx"
openclaw config set models.providers.anthropic.apiKey '${ANTHROPIC_API_KEY}' --global

7.4 Error: Invalid agent name

$ openclaw agents add My_Agent
Error: Invalid agent name "My_Agent".
Agent names must match pattern: ^[a-z][a-z0-9-]{1,63}(?<!-)$
  - Only lowercase letters, digits, and hyphens
  - Must start with a letter
  - Must not end with a hyphen
  - Length: 2-64 characters

解決方式：使用符合命名規則的名稱，例如 my-agent。

7.5 Error: Workspace directory not found

$ openclaw agents add my-bot --workspace ./nonexistent
Error: Workspace directory "./nonexistent" does not exist.
Create it first, or use --create-workspace to auto-create.

解決方式：

# 方式 1：先建立目錄
mkdir -p ./nonexistent
openclaw agents add my-bot --workspace ./nonexistent

# 方式 2：使用 --create-workspace 旗標
openclaw agents add my-bot --workspace ./nonexistent --create-workspace

7.6 Config 路徑拼寫錯誤

這是最隱蔽的問題——config set 接受任意路徑，不會報錯，但拼寫錯誤的路徑不會生效：

# 錯誤：路徑拼寫有誤（defautls 而非 defaults）
openclaw config set agents.defautls.model.primary anthropic:claude-opus-4
# 不會報錯，但設定不會被任何代理讀取！

# 正確做法：設定後立即驗證
openclaw config set agents.defaults.model.primary anthropic:claude-opus-4
openclaw config get agents.defaults.model.primary
# 輸出: anthropic:claude-opus-4

建議：養成每次 config set 後立即 config get 驗證的習慣。你也可以使用 openclaw config validate 檢查整個配置檔的合法性：^[2]

# 驗證配置檔結構與值的合法性
openclaw config validate

# 輸出範例
✓ Config structure: valid
✓ Model references: all resolved
✓ Agent identities: all files exist
⚠ Warning: agents.defautls.model.primary — unrecognized path (did you mean "agents.defaults"?)
✓ API keys: all configured

7.7 代理繼承問題除錯

當代理的行為不如預期時，通常是因為配置繼承鏈出了問題。使用以下指令追蹤完整的配置解析過程：

# 顯示代理的完整解析後配置（含繼承來源）
openclaw agents show code-reviewer --resolve

# 輸出範例
Agent: code-reviewer (resolved config)
  model.primary:     anthropic:claude-opus-4    [source: project/agents.registered.code-reviewer]
  model.fallback:    openai:gpt-4.1            [source: project/agents.registered.code-reviewer]
  model.temperature: 0.1                        [source: project/agents.registered.code-reviewer]
  model.maxTokens:   64000                      [source: project/agents.registered.code-reviewer]
  workspace:         ./src                      [source: project/agents.registered.code-reviewer]
  tools:             file, shell, git           [source: project/agents.registered.code-reviewer]

# 對比繼承與覆寫的差異
openclaw agents diff code-reviewer --vs defaults

八、結語

OpenClaw 的 agents 指令體系——從 agents add 的代理建立、agents list 的狀態監控，到 config set 的模型配置——構成了整個代理管理工作流的核心。^[3] 掌握這些指令不僅能提升日常開發效率，更能讓你在多代理、多模型的複雜場景中，設計出兼顧效能、成本與安全性的配置架構。

回顧本文的核心要點：

• 配置檔結構：理解雙層配置體系（全域 vs. 專案）與就近優先原則，是一切操作的基礎
• agents add：掌握完整參數語法，善用 --template 加速建立、--dry-run 預覽變更
• agents list：搭配 --verbose 與 --format json，實現代理狀態的即時掌握與程式化處理
• config set：熟悉模型配置路徑（特別是 agents.defaults.model.primary），並養成設定後驗證的習慣
• 多代理架構：為不同職責的代理指派最適合的模型，可大幅降低 API 費用而不犧牲關鍵品質

如果你正在評估如何在企業環境中導入 AI 代理，或是希望最佳化現有的多代理配置，歡迎聯繫超智諮詢的團隊——我們擁有豐富的 OpenClaw 企業部署經驗，能協助你設計最適合組織需求的代理架構。

延伸閱讀：OpenClaw 代理設定完全指南｜OpenClaw 設定完全指南｜OpenClaw 指令大全