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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• 在 目錄下建立 身份檔（含預設系統提示）
• 將代理註冊至 的 區塊
• 繼承 中的模型、工具與工作空間設定

輸出範例：

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

這條指令做了以下設定：

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

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

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

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

輸出將顯示：

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

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

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

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

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

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

輸出範例：

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

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

支援多種篩選參數：

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

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

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

輸出：

當你執行 時，這條設定會寫入當前目錄的 （專案級）。若要修改全域設定，需加上 旗標：^[4]

若要為特定代理覆寫模型設定，使用 路徑：

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

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

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

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

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

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

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

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

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

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

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

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

解決方式：

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

解決方式：

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

解決方式：

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

解決方式：

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

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

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

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

回顧本文的核心要點：

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

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

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