Key Findings
  • OpenClaw 的所有設定集中於 ~/.openclaw/openclaw.json 這個 JSON5 格式檔案，支援註解與尾隨逗號，是整個代理系統的「控制面板」[1]
  • 模型設定採用 Primary + Fallback 雙層機制——當主要模型（如 Claude Opus 4.6）不可用時，系統自動降級至備援模型，確保代理不中斷[4]
  • Gateway 模式分為 local（僅本機存取）與 remote（遠端連線），切換一條指令即可完成[5]
  • 所有敏感參數（API Key、Gateway Token）建議透過 CLI openclaw config set 寫入，避免手動編輯導致語法錯誤[3]

一、openclaw.json：你的代理控制面板

OpenClaw 的設計哲學是「單一設定檔，管理一切」。無論你要調整模型、新增通訊渠道、修改 Gateway 行為，還是設定安全權限，所有配置都匯聚在同一個檔案中。[1]

1.1 檔案位置

預設路徑為 ~/.openclaw/openclaw.json。你也可以透過環境變數 OPENCLAW_CONFIG_PATH 指定自訂路徑，但實務上極少需要這麼做。[2]

第一次執行 openclaw onboard 時，系統會自動建立此檔案並寫入初始設定。如果你是全新安裝，不需要手動建立它。

1.2 JSON5 格式

openclaw.json 採用 JSON5 格式，這是標準 JSON 的超集，允許：[8]

這意味著你可以直接用文字編輯器開啟並加上註解，讓團隊成員也能理解每項設定的用途。不過，官方更推薦使用 CLI 指令來修改設定，以避免手動編輯造成的語法錯誤。[3]

二、模型設定：Primary 與 Fallback

模型設定是 OpenClaw 最常被調整的部分。它決定了你的 AI 代理使用哪個大型語言模型來「思考」。[4]

2.1 設定主要模型

使用以下指令設定你的主要模型：

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

OpenClaw 支援多家模型供應商，包括 Anthropic（Claude 系列）、OpenAI（GPT 系列）、Google（Gemini 系列）等。設定模型名稱時，請參照各供應商的模型識別碼。

2.2 設定備援模型（Fallback）

備援模型在主要模型不可用（例如 API 限流、服務中斷）時自動啟用：

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

備援清單按順序嘗試：第一個可用的模型會被選中。在生產環境中，強烈建議設定至少一個備援模型，以確保代理的持續運作。

2.3 模型認證

每個模型供應商需要獨立的 API 金鑰或 OAuth 認證。使用以下指令管理認證：

// 使用 API 金鑰
openclaw models auth setup-token --provider anthropic

// 使用 OAuth（互動式授權）
openclaw models auth login --provider openai

認證資訊儲存在 ~/.openclaw/auth-profiles.json 中，與主設定檔分離，降低意外洩漏的風險。[6]

三、Gateway 模式設定

Gateway 是 OpenClaw 的中樞，所有訊息都經過它路由。[5] Gateway 模式決定了你的代理能被誰存取。

3.1 Local 模式（預設）

預設的 local 模式僅允許本機（127.0.0.1）連線，適合個人開發與測試：

openclaw config set gateway.mode local

在這個模式下，Web UI 位於 http://127.0.0.1:18789，只有你自己的電腦能存取。

3.2 Remote 模式

當你需要從手機、其他裝置或外部網路存取 OpenClaw 時，切換為 remote 模式：

openclaw config set gateway.mode remote

切換後需要設定 Gateway Token 以防止未授權存取：

openclaw doctor --generate-gateway-token

安全提醒：遠端模式下務必搭配 TLS（HTTPS）與強密碼 Token，否則你的整台電腦將暴露在網路上。[6]

3.3 Port 設定

預設 Port 為 18789。如果與其他服務衝突，可以自訂：

openclaw config set gateway.port 28789

四、Workspace 與代理設定

Workspace 是 OpenClaw 管理代理記憶與狀態的邏輯單元。每個 Workspace 可以有獨立的代理設定。

4.1 預設 Workspace 路徑

openclaw config set agents.defaults.workspace ~/my-workspace

Workspace 目錄包含代理的上下文記憶、對話歷史與工具呼叫記錄。不同專案可以使用不同的 Workspace，讓代理在各專案之間保持獨立的知識脈絡。

4.2 Timeout 設定

代理的執行時間上限由 timeoutSeconds 控制：

openclaw config set agents.defaults.timeoutSeconds 300

預設值通常足以應對大多數任務。但如果你的代理需要執行長時間操作（例如大型程式碼庫掃描、複雜的瀏覽器自動化流程），可能需要調高此值。

五、常用設定指令速查表

用途指令
查看所有設定openclaw config get
查看特定設定openclaw config get agents.defaults.model
設定主要模型openclaw config set agents.defaults.model.primary MODEL_ID
設定備援模型openclaw config set agents.defaults.model.fallbacks '["MODEL_A","MODEL_B"]'
切換 Gateway 模式openclaw config set gateway.mode local|remote
修改 Portopenclaw config set gateway.port PORT
設定 Workspaceopenclaw config set agents.defaults.workspace PATH
移除設定openclaw config unset KEY
驗證設定檔openclaw config validate

所有 config set 指令都會立即寫入 openclaw.json，但部分設定（如 Gateway 模式）需要重啟 Gateway 才能生效。[3]

六、安全最佳實踐

OpenClaw 是一個能存取你整台電腦的代理。設定不當可能帶來嚴重的安全風險。[6][7]

  1. 永遠不要將 openclaw.json 推送到 Git：設定檔可能包含敏感的 Token 與路徑資訊
  2. 使用 CLI 而非手動編輯：openclaw config set 會自動驗證格式與值的合法性
  3. Remote 模式必須搭配 Token：沒有 Token 的遠端 Gateway 等於將電腦控制權公開在網路上
  4. 定期輪換 API 金鑰：每 90 天更新一次模型供應商的 API 金鑰
  5. 最小權限原則：只啟用代理實際需要的 Skills 與 Hooks，減少攻擊面

結語

OpenClaw 的設定系統以「一個檔案管理一切」為核心理念，將複雜的分散式代理架構簡化為直觀的鍵值對。[1] 掌握 openclaw.json 的結構與 config set 指令，你就掌握了整個代理系統的控制權。

如果你在設定過程中遇到問題，可以參閱我們的《OpenClaw 疑難排解指南》，或使用 openclaw doctor --fix 讓系統自動修復常見的設定錯誤。