附錄 B：配置文件詳解

OpenClaw 的配置系統靈活而強大，本附錄基於官方文檔詳細解析各個配置項。

參考來源：OpenClaw Configuration

配置文件位置

OpenClaw 讀取可選的 JSON5 配置文件：

~/.openclaw/openclaw.json          # 主配置文件
~/.openclaw/.env                   # 環境變量文件

如果配置文件不存在，OpenClaw 使用安全默認值。

配置文件結構概覽

json5

{
  agents: { ... },           // Agent 配置
  channels: { ... },         // 渠道配置
  gateway: { ... },          // 網關配置
  session: { ... },          // 會話配置
  messages: { ... },         // 消息配置
  tools: { ... },            // 工具配置
  skills: { ... },           // 技能配置
  cron: { ... },             // 定時任務配置
  hooks: { ... },            // Webhook 配置
  bindings: [...],           // 綁定規則
  env: { ... },              // 環境變量
}

一、Agent 配置（agents）

1.1 默認配置（agents.defaults）

json5

{
  agents: {
    defaults: {
      // 工作空間路徑
      workspace: "~/.openclaw/workspace",
      
      // 模型配置
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"]
      },
      
      // 模型目錄（用於 /model 命令）
      models: {
        "anthropic/claude-sonnet-4-5": {
          alias: "Sonnet"
        },
        "openai/gpt-5.2": {
          alias: "GPT"
        }
      },
      
      // 圖片最大尺寸（像素）
      imageMaxDimensionPx: 1200,
      
      // 心跳配置
      heartbeat: {
        every: "30m",        // 30分鐘、2小時等
        target: "last",      // last | whatsapp | telegram | discord | none
        directPolicy: "allow" // allow | block
      },
      
      // 沙盒配置
      sandbox: {
        mode: "non-main",    // off | non-main | all
        scope: "agent"       // session | agent | shared
      },
      
      // 工具配置
      tools: {
        enabled: true,
        profile: "full"
      }
    }
  }
}

配置項說明：

配置項	類型	默認值	說明
`workspace`	string	~/.openclaw/workspace	Agent 工作目錄
`model.primary`	string	-	主模型，格式：provider/model
`model.fallbacks`	array	[]	回退模型列表
`imageMaxDimensionPx`	number	1200	圖片轉錄/工具圖片縮放尺寸
`heartbeat.every`	string	-	心跳間隔（如 30m, 2h）
`sandbox.mode`	string	off	沙盒模式

1.2 多 Agent 配置（agents.list）

json5

{
  agents: {
    list: [
      {
        id: "home",
        default: true,
        workspace: "~/.openclaw/workspace-home",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"]
        }
      },
      {
        id: "work",
        workspace: "~/.openclaw/workspace-work",
        model: {
          primary: "anthropic/claude-opus-4-6"
        }
      }
    ]
  }
}

二、渠道配置（channels）

2.1 通用 DM 策略配置

所有渠道共享相同的 DM 策略模式：

json5

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",      // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"],    // 僅用於 allowlist/open
    },
    
    whatsapp: {
      enabled: true,
      allowFrom: ["+15555550123"],
      groups: {
        "*": {
          requireMention: true
        }
      }
    },
    
    discord: {
      enabled: true,
      botToken: "${DISCORD_BOT_TOKEN}",
      dmPolicy: "pairing",
      allowFrom: ["discord:123"]
    },
    
    slack: {
      enabled: true,
      botToken: "${SLACK_BOT_TOKEN}",
      dmPolicy: "pairing"
    }
  }
}

DM 策略選項：

策略	說明
`pairing`	未知發送者收到一次性配對碼，需要批准
`allowlist`	僅 allowFrom 中的發送者
`open`	允許所有入站 DM（需要 allowFrom: ["*"]）
`disabled`	忽略所有 DM

2.2 羣聊提及門控

json5

{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"]
        }
      }
    ]
  },
  
  channels: {
    whatsapp: {
      groups: {
        "*": {
          requireMention: true
        }
      }
    }
  }
}

三、網關配置（gateway）

json5

{
  gateway: {
    port: 18789,
    bind: "loopback",           // loopback | lan | tailnet | auto | custom
    auth: {
      mode: "token",            // token | password
      token: "${OPENCLAW_GATEWAY_TOKEN}",
      password: "${OPENCLAW_GATEWAY_PASSWORD}",
      allowTailscale: true
    },
    tailscale: {
      mode: "off",              // off | serve | funnel
      resetOnExit: false
    },
    reload: {
      mode: "hybrid",           // hybrid | hot | restart | off
      debounceMs: 300
    }
  }
}

綁定地址選項：

值	說明
`loopback`	僅本地訪問（127.0.0.1）
`lan`	局域網可訪問
`tailnet`	Tailscale 網絡
`auto`	自動檢測
`custom`	自定義地址

熱重載模式：

模式	行爲
`hybrid`	熱應用安全更改，自動重啓關鍵更改（默認）
`hot`	僅熱應用安全更改，需要重啓時記錄警告
`restart`	任何配置更改都重啓網關
`off`	禁用文件監視

四、會話配置（session）

json5

{
  session: {
    dmScope: "per-channel-peer",  // main | per-peer | per-channel-peer | per-account-channel-peer
    
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0
    },
    
    reset: {
      mode: "daily",            // daily | idle | manual
      atHour: 4,
      idleMinutes: 120
    }
  }
}

DM 範圍選項：

值	說明
`main`	共享會話
`per-peer`	每個對等方獨立會話
`per-channel-peer`	每個渠道-對等方獨立會話（推薦多用戶）
`per-account-channel-peer`	每個賬戶-渠道-對等方獨立會話

五、消息配置（messages）

json5

{
  messages: {
    groupChat: {
      mentionPatterns: ["@openclaw"]
    }
  }
}

六、工具配置（tools）

json5

{
  tools: {
    profile: "full",              // messaging | default | coding | full | all
    enabled: true,
    web: {
      search: {
        apiKey: "${BRAVE_API_KEY}"
      }
    }
  }
}

工具配置文件：

Profile	說明
`messaging`	僅聊天，無工具
`default`	基礎工具集
`coding`	編程工具集
`full`	完整工具集
`all`	所有工具

七、技能配置（skills）

json5

{
  skills: {
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/nano-banana-pro/apiKey"
        }
      }
    }
  }
}

八、定時任務配置（cron）

json5

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000
    }
  }
}

九、Webhook 配置（hooks）

json5

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    mappings: [
      {
        match: {
          path: "gmail"
        },
        action: "agent",
        agentId: "main",
        deliver: true
      }
    ]
  }
}

十、綁定配置（bindings）

json5

{
  bindings: [
    {
      agentId: "home",
      match: {
        channel: "whatsapp",
        accountId: "personal"
      }
    },
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "biz"
      }
    }
  ]
}

十一、環境變量配置（env）

json5

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-..."
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000
    }
  }
}

環境變量來源（按優先級）：

父進程環境變量
當前工作目錄的 .env 文件
~/.openclaw/.env 文件（全局回退）

都不覆蓋已存在的環境變量。

十二、配置分割（$include）

使用 $include 組織大型配置：

json5

// ~/.openclaw/openclaw.json
{
  gateway: {
    port: 18789
  },
  agents: {
    $include: "./agents.json5"
  },
  broadcast: {
    $include: [
      "./clients/a.json5",
      "./clients/b.json5"
    ]
  }
}

規則：

單文件：替換包含的對象
文件數組：按順序深度合併（後面的優先）
同級鍵：在 include 後合併（覆蓋包含的值）
嵌套 include：支持最多 10 層深度
相對路徑：相對於包含文件解析

十三、環境變量替換

在配置字符串值中引用環境變量：

json5

{
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}"
    }
  },
  models: {
    providers: {
      custom: {
        apiKey: "${CUSTOM_API_KEY}"
      }
    }
  }
}

規則：

僅匹配大寫名稱：[A-Z_][A-Z0-9_]*
缺失/空變量在加載時拋出錯誤
使用 $${VAR} 轉義爲字面量輸出
在 $include 文件中同樣有效
內聯替換："${BASE}/v1" → "https://api.example.com/v1"

十四、SecretRef 憑證

支持 SecretRef 對象的字段：

json5

{
  models: {
    providers: {
      openai: {
        apiKey: {
          source: "env",
          provider: "default",
          id: "OPENAI_API_KEY"
        }
      }
    }
  },
  
  skills: {
    entries: {
      "nano-banana-pro": {
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/nano-banana-pro/apiKey"
        }
      }
    }
  },
  
  channels: {
    googlechat: {
      serviceAccountRef: {
        source: "exec",
        provider: "vault",
        id: "channels/googlechat/serviceAccount"
      }
    }
  }
}

source 類型：

env：環境變量
file：文件內容
exec：命令執行輸出

十五、完整配置示例

15.1 最小配置

json5

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace"
    }
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"]
    }
  }
}

15.2 本地開發配置

json5

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "ollama/llama3.2"
      }
    }
  },
  gateway: {
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token",
      token: "dev-token"
    }
  }
}

15.3 服務器部署配置

json5

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"]
      }
    }
  },
  
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "pairing"
    }
  },
  
  gateway: {
    port: 18789,
    bind: "lan",
    auth: {
      mode: "password",
      password: "${GATEWAY_PASSWORD}"
    }
  },
  
  session: {
    dmScope: "per-channel-peer"
  }
}

15.4 多 Agent 配置

json5

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5"
      }
    },
    list: [
      {
        id: "home",
        default: true,
        workspace: "~/.openclaw/workspace-home"
      },
      {
        id: "work",
        workspace: "~/.openclaw/workspace-work",
        model: {
          primary: "anthropic/claude-opus-4-6"
        }
      }
    ]
  },
  
  bindings: [
    {
      agentId: "home",
      match: {
        channel: "whatsapp",
        accountId: "personal"
      }
    },
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "biz"
      }
    }
  ]
}

十六、配置編輯方式

交互式嚮導

bash

openclaw onboard          # 完整設置嚮導
openclaw configure        # 配置嚮導

CLI 命令

bash

openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset tools.web.search.apiKey
openclaw config file      # 查看配置文件路徑
openclaw config validate  # 驗證配置

Web 控制檯

打開 http://127.0.0.1:18789，使用 Config 標籤頁。

直接編輯

直接編輯 ~/.openclaw/openclaw.json，網關會自動應用更改。

十七、嚴格驗證

OpenClaw 只接受完全匹配 schema 的配置。未知鍵、格式錯誤的類型或無效值會導致網關拒絕啓動。

驗證失敗時：

網關不會啓動
只有診斷命令可用（openclaw doctor, openclaw logs, openclaw health, openclaw status）
運行 openclaw doctor 查看具體問題
運行 openclaw doctor --fix 應用修復

十八、熱重載說明

支持熱應用的配置

類別	字段	需要重啓？
渠道	`channels.*`	否
Agent & 模型	`agent`, `agents`, `models`, `routing`	否
自動化	`hooks`, `cron`, `agent.heartbeat`	否
會話 & 消息	`session`, `messages`	否
工具 & 媒體	`tools`, `browser`, `skills`, `audio`, `talk`	否
UI & 其他	`ui`, `logging`, `identity`, `bindings`	否

需要重啓的配置

類別	字段
網關服務器	`gateway.*`（端口、綁定、認證、Tailscale、TLS、HTTP）
基礎設施	`discovery`, `canvasHost`, `plugins`

例外：gateway.reload 和 gateway.remote 更改不會觸發重啓。

提示：本配置詳解基於 OpenClaw 官方文檔整理，完整參考請訪問 docs.openclaw.ai/gateway/configuration。

附錄 B：配置文件詳解 ​

配置文件位置 ​

配置文件結構概覽 ​

一、Agent 配置（agents） ​

1.1 默認配置（agents.defaults） ​

1.2 多 Agent 配置（agents.list） ​

二、渠道配置（channels） ​

2.1 通用 DM 策略配置 ​

2.2 羣聊提及門控 ​

三、網關配置（gateway） ​

四、會話配置（session） ​

五、消息配置（messages） ​

六、工具配置（tools） ​

七、技能配置（skills） ​

八、定時任務配置（cron） ​

九、Webhook 配置（hooks） ​

十、綁定配置（bindings） ​

十一、環境變量配置（env） ​

十二、配置分割（$include） ​

十三、環境變量替換 ​

十四、SecretRef 憑證 ​

十五、完整配置示例 ​

15.1 最小配置 ​

15.2 本地開發配置 ​

15.3 服務器部署配置 ​

15.4 多 Agent 配置 ​

十六、配置編輯方式 ​

交互式嚮導 ​

CLI 命令 ​

Web 控制檯 ​

直接編輯 ​

十七、嚴格驗證 ​

十八、熱重載說明 ​

支持熱應用的配置 ​

需要重啓的配置 ​

附錄 B：配置文件詳解

配置文件位置

配置文件結構概覽

一、Agent 配置（agents）

1.1 默認配置（agents.defaults）

1.2 多 Agent 配置（agents.list）

二、渠道配置（channels）

2.1 通用 DM 策略配置

2.2 羣聊提及門控

三、網關配置（gateway）

四、會話配置（session）

五、消息配置（messages）

六、工具配置（tools）

七、技能配置（skills）

八、定時任務配置（cron）

九、Webhook 配置（hooks）

十、綁定配置（bindings）

十一、環境變量配置（env）

十二、配置分割（$include）

十三、環境變量替換

十四、SecretRef 憑證

十五、完整配置示例

15.1 最小配置

15.2 本地開發配置

15.3 服務器部署配置

15.4 多 Agent 配置

十六、配置編輯方式

交互式嚮導

CLI 命令

Web 控制檯

直接編輯

十七、嚴格驗證

十八、熱重載說明

支持熱應用的配置

需要重啓的配置