概念

Config 是 OpenClaw 的「設定檔」— 定義所有行為。

主要設定檔：~/.openclaw/openclaw.json

Config 結構總覽

{
  // Gateway 設定
  "gateway": { ... },
  
  // Agent 設定
  "agents": { ... },
  
  // Channel 設定（Telegram/WhatsApp/...）
  "channels": { ... },
  
  // 訊息路由
  "bindings": [ ... ],
  
  // Session 管理
  "session": { ... },
  
  // 工具設定
  "tools": { ... },
  
  // Cron 設定
  "cron": { ... },
  
  // Browser 設定
  "browser": { ... }
}

核心設定區塊

1. Gateway

{
  "gateway": {
    "port": 18789,              // HTTP port
    "auth": "secret-token",     // API 認證
    "heartbeat": {
      "enabled": true,
      "intervalMinutes": 30
    }
  }
}

2. Agents

{
  "agents": {
    // 預設值（所有 agent 繼承）
    "defaults": {
      "model": "anthropic/claude-opus-4-5",
      "workspace": "~/.openclaw/workspace",
      "timeoutSeconds": 600,
      "compaction": { "enabled": true }
    },
    
    // Agent 列表
    "list": [
      {
        "id": "my-assistant",
        "name": "Nova",
        "model": { "primary": "anthropic/claude-opus-4-5" },
        "workspace": "~/.openclaw/workspace-main"
      },
      {
        "id": "dev-agent",
        "name": "Elizabeth",
        "model": { "primary": "openai-codex/gpt-5.2-codex" },
        "workspace": "~/.openclaw/workspace-dev"
      }
    ]
  }
}

Agent 繼承鏈： agent-specific → agents.defaults → built-in defaults

3. Channels

{
  "channels": {
    "telegram": {
      "enabled": true,
      "accounts": {
        "default": {
          "token": "env:TELEGRAM_BOT_TOKEN"
        }
      },
      "allowFrom": ["9876543210"],
      "groupPolicy": "mention-only"
    },
    
    "whatsapp": {
      "enabled": true,
      "account": "personal",
      "allowFrom": ["+1234567890"]
    }
  }
}

env: prefix： 從環境變數讀取敏感值，不要把 token 直接寫在 config

4. Bindings（路由規則）

{
  "bindings": [
    {
      "agentId": "my-assistant",
      "match": {
        "channel": "whatsapp",
        "from": "+1234567890"
      }
    },
    {
      "agentId": "dev-agent",
      "match": {
        "channel": "telegram",
        "chatType": "private"
      }
    },
    {
      "agentId": "dev-agent",
      "match": {
        "channel": "telegram",
        "chatType": "group",
        "chatId": "-1001234567890"
      }
    }
  ]
}

匹配順序： 第一個符合的規則生效

5. Tools

{
  "tools": {
    "allow": ["exec", "read", "write", "edit", "browser", "message"],
    "deny": [],
    
    "exec": {
      "host": "sandbox",
      "security": "allowlist",
      "timeout": 1800
    },
    
    "browser": {
      "enabled": true,
      "defaultProfile": "openclaw"
    }
  }
}

CLI 操作 Config

# 查看完整 config
openclaw config get

# 查看特定路徑
openclaw config get agents.defaults.model

# 設定值
openclaw config set agents.defaults.model "anthropic/claude-sonnet-4-5"

# 重新載入（需要 restart）
openclaw gateway restart

環境變數

# 敏感資料放 ~/.openclaw/.env
TELEGRAM_BOT_TOKEN=123456:ABC...
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

# 在 config 中用 env: prefix 引用
"token": "env:TELEGRAM_BOT_TOKEN"

驗證 Config

# 檢查 config 格式
openclaw config validate

# 查看 schema
openclaw config schema

💡 關鍵洞察

單一真相來源
- 所有設定都在 openclaw.json
- 不要直接改 jobs.json（會被覆蓋）
- 用 CLI 或 tool call 修改
環境變數保護敏感資訊
- Token、API key 不要寫在 config
- 用 env:VAR_NAME 引用
- 或放在 ~/.openclaw/.env
Bindings 決定路由
- 訊息進來 → 匹配 binding → 找 agent
- 沒匹配 → 用 default agent
- 順序重要（第一個符合的生效）
修改後需要 restart
- openclaw gateway restart
- 或用 gateway.config.patch tool

🔗 核心檔案

主設定：~/.openclaw/openclaw.json
環境變數：~/.openclaw/.env
Schema 文檔：/opt/homebrew/lib/node_modules/openclaw/docs/gateway/configuration.md

明天： Context 管理（workspace files, project context）

Day 8: Config 系統（openclaw.json, agents, bindings）