配置文件详解

OpenClaw 的所有行为——用哪个模型、连哪些渠道、多久心跳一次——都由一个 JSON5 配置文件控制。本附录逐项解读每个配置块，帮你理解"这个字段是干什么的"以及"什么时候需要改它"。

不想手写配置？ 推荐使用 OpenClaw 配置生成器可视化生成配置，再对照本附录微调。

配置文件位置

~/.openclaw/openclaw.json          # 主配置文件（JSON5 格式）
~/.openclaw/.env                   # 环境变量文件（存放 API Key 等）

配置文件不存在也能运行——OpenClaw 会使用安全默认值。可以通过 openclaw config file 确认实际路径。

配置文件整体结构

{
  agents: { ... },           // 智能体：模型、工作区、心跳
  channels: { ... },         // 渠道：Telegram / QQ / 飞书等
  gateway: { ... },          // 网关：端口、认证、热重载
  session: { ... },          // 会话：隔离策略、自动重置
  messages: { ... },         // 消息：群聊提及规则
  tools: { ... },            // 工具：启用级别、搜索配置
  skills: { ... },           // 技能：启用与凭证
  cron: { ... },             // 定时任务：并发、日志
  hooks: { ... },            // Webhook：外部事件触发
  bindings: [...],           // 绑定：Agent 与渠道的映射
  env: { ... },              // 环境变量：API Key 等
  commands: { ... },         // 斜杠命名配置
}

Agent 配置

Agent 是 OpenClaw 的核心——每个 Agent 有自己的模型、工作区和行为设置。

1.默认配置（agents.defaults）

所有 Agent 共享的默认值，单个 Agent 可以覆盖。

{
  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,     // 图片缩放上限（像素）

      // 心跳：Agent 定期主动发消息
      heartbeat: {
        every: "30m",                // 间隔：30m / 2h / 1d
        target: "last",              // 发给谁：last（最近对话） | 指定渠道 | none
        directPolicy: "allow"        // 是否允许直接消息：allow | block
      },

      // 沙盒：隔离工具执行环境
      sandbox: {
        mode: "non-main",            // off | non-main（非主 Agent 隔离） | all
        scope: "agent"               // session | agent | shared
      },

      // 工具
      tools: {
        enabled: true,
        profile: "full"
      }
    }
  }
}

配置项速查：

配置项	类型	默认值	什么时候改
`workspace`	string	~/.openclaw/workspace	想把工作文件放到别的目录
`model.primary`	string	—	换主模型（格式 `provider/model`）
`model.fallbacks`	array	[]	主模型挂了自动切换到备选
`imageMaxDimensionPx`	number	1200	图片太大占 Token，可以调小
`heartbeat.every`	string	—	调整 Agent 主动问候的频率
`sandbox.mode`	string	off	安全敏感场景建议开 `all`

2.多 Agent 配置（agents.list）

一个 OpenClaw 实例可以运行多个 Agent——比如"家庭助手"和"工作助手"用不同模型：

{
  agents: {
    list: [
      {
        id: "home",
        default: true,                         // 默认 Agent
        workspace: "~/.openclaw/workspace-home",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"]
        }
      },
      {
        id: "work",
        workspace: "~/.openclaw/workspace-work",
        model: {
          primary: "anthropic/claude-opus-4-6"  // 工作用更强的模型
        }
      }
    ]
  }
}

多 Agent 需要配合绑定配置，指定哪个 Agent 响应哪个渠道。

渠道配置

渠道决定了 OpenClaw 连接哪些聊天平台、谁能跟它说话。

1.渠道与 DM 策略

每个渠道可以独立设置"谁能私聊"策略：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",           // 私聊策略（见下表）
      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`	仅白名单内的用户可私聊	小团队
`open`	允许所有人私聊（需 `allowFrom: ["*"]`）	公开服务
`disabled`	忽略所有私聊	仅群聊场景

2.群聊提及门控

群聊中，Agent 默认不会响应每条消息——需要被 @ 提及才会回复：

{
  agents: {
    list: [{
      id: "main",
      groupChat: {
        mentionPatterns: ["@openclaw", "openclaw"]  // 触发词
      }
    }]
  },
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true }   // 所有群都要 @
      }
    }
  }
}

网关配置

网关是 OpenClaw 的后台服务进程，所有消息收发都经过它。

{
  gateway: {
    port: 18789,                      // 监听端口
    bind: "loopback",                 // 绑定地址
    auth: {
      mode: "token",                  // 认证方式
      token: "${OPENCLAW_GATEWAY_TOKEN}",
      password: "${OPENCLAW_GATEWAY_PASSWORD}",
      allowTailscale: true            // Tailscale 连接免认证
    },
    tailscale: {
      mode: "off",                    // off | serve | funnel
      resetOnExit: false
    },
    reload: {
      mode: "hybrid",                // 配置变更时的重载策略
      debounceMs: 300
    }
  }
}

绑定地址——决定谁能连：

值	能访问的范围	安全性
`loopback`	仅本机（127.0.0.1）	最安全（默认）
`lan`	局域网内所有设备	需配合认证
`tailnet`	Tailscale 虚拟网络	端到端加密
`auto`	自动检测	—
`custom`	自定义地址	取决于配置

热重载模式——改了配置要不要重启：

模式	行为	选择建议
`hybrid`	安全更改热应用，关键更改自动重启	推荐（默认）
`hot`	仅热应用，需要重启时只记日志	不想被打断
`restart`	任何改动都重启	追求一致性
`off`	不监听配置文件变化	手动管理

网关管理查看。

会话配置

会话决定了"谁和谁的对话算同一个上下文"。

{
  session: {
    dmScope: "per-channel-peer",      // 会话隔离粒度

    threadBindings: {                 // 线程绑定（Discord/Slack 等有线程的平台）
      enabled: true,
      idleHours: 24,                  // 线程空闲多久后解绑
      maxAgeHours: 0                  // 0 = 不限最大年龄
    },

    reset: {                          // 自动重置会话
      mode: "daily",                  // daily | idle | manual
      atHour: 4,                      // daily 模式：每天几点重置（24h 制）
      idleMinutes: 120                // idle 模式：空闲多久重置
    }
  }
}

会话隔离粒度——影响"谁和谁共享记忆"：

值	隔离方式	适用场景
`main`	所有人共享一个会话	单用户
`per-peer`	每人一个会话	简单多用户
`per-channel-peer`	每个平台的每人一个会话	多平台多用户（推荐）
`per-account-channel-peer`	每个账号×平台×用户	多 Agent 多平台

工具配置

控制 Agent 能使用哪些工具（搜索、编程、文件操作等）。

{
  tools: {
    profile: "full",                  // 工具集级别
    enabled: true,
    web: {
      search: {
        apiKey: "${BRAVE_API_KEY}"    // Web 搜索需要的 API Key
      }
    }
  }
}

工具集级别——从少到多：

Profile	包含的工具	适用场景
`messaging`	仅聊天，无工具	纯对话
`default`	基础工具集	日常使用
`coding`	编程工具集	开发者
`full`	完整工具集	全功能（推荐）
`all`	所有工具（含实验性）	尝鲜

技能配置

安装技能后，部分技能需要在配置中填入 API Key 才能启用。

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

技能管理用 clawhub CLI。

定时任务配置

控制 Cron 任务的全局行为。

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,             // 最多同时执行几个任务
    sessionRetention: "24h",          // 任务会话保留时长
    runLog: {
      maxBytes: "2mb",                // 日志文件大小上限
      keepLines: 2000                 // 保留最近多少行
    }
  }
}

Webhook 配置

让外部服务（Gmail、GitHub、IoT 传感器等）通过 HTTP 触发 Agent 执行任务。

{
  hooks: {
    enabled: true,
    token: "shared-secret",           // 鉴权 Token（调用方需携带）
    path: "/hooks",                   // Webhook 路径前缀
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    mappings: [
      {
        match: { path: "gmail" },     // 匹配 /hooks/gmail
        action: "agent",
        agentId: "main",
        deliver: true                 // 处理结果投递到渠道
      }
    ]
  }
}

例如收到 Gmail 新邮件通知后，Agent 自动摘要并推送到 Telegram。

斜杠命令配置

{
  commands: {
    native: "auto",
    nativeSkills: "auto",
    text: true,
    bash: false,
    bashForegroundMs: 2000,
    config: false,
    debug: false,
    restart: false,
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

参数说明

commands.native

默认值："auto"
核心作用：注册各平台的「原生命令」（如Discord/Telegram的原生斜杠命令）。
auto 逻辑：
- Discord/Telegram：自动开启原生命令注册；
- Slack：自动关闭（需手动在Slack后台添加斜杠命令后才生效）；
- 无原生命令支持的平台（如WhatsApp）：忽略该配置。
自定义覆盖：可通过 channels.[平台].commands.native（如channels.discord.commands.native）按平台单独配置，值支持布尔值（true/false）或 "auto"。
特殊规则：设为false时，启动OpenClaw会清除Discord/Telegram上已注册的原生命令；Slack命令需在Slack应用后台手动管理，不会被自动删除。

commands.nativeSkills

默认值："auto"
核心作用：当平台支持时，注册「技能类原生命令」（专属技能的斜杠命令）。
auto 逻辑：
- Discord/Telegram：自动开启技能原生命令注册；
- Slack：自动关闭（Slack需为每个技能手动创建斜杠命令）。
自定义覆盖：可通过 channels.[平台].commands.nativeSkills（如channels.telegram.commands.nativeSkills）按平台单独配置，值支持布尔值或 "auto"。

commands.text

默认值：true
核心作用：开启聊天消息中 /xxx 格式文本命令的解析功能。
特殊规则：
- 对无原生命令支持的平台（WhatsApp/WebChat/Signal/iMessage/Google Chat/MS Teams），即使将该值设为false，文本命令仍会生效（跨平台兼容性兜底）。

commands.bash

默认值：false
核心作用：启用 ! <命令> 语法执行主机Shell命令（/bash <命令> 是其别名）。
依赖条件：需在 tools.elevated 配置中设置允许执行的Shell命令白名单（高危操作，需严格管控）。
权限限制：仅主机管理员可使用。

commands.bashForegroundMs

默认值：2000（单位：毫秒）
核心作用：控制bash命令在前台运行的时长，超时后自动切换到后台模式。
特殊值：设为0时，bash命令会立即转入后台运行（无前台交互时长）。

commands.config

默认值：false
核心作用：启用 /config 命令，该命令可直接读写OpenClaw的核心配置文件 openclaw.json。
风险提示：生产环境建议保持false，避免配置被误修改。

commands.debug

默认值：false
核心作用：启用 /debug 命令，该命令可在运行时临时覆盖配置（仅对当前运行周期生效，重启后恢复）。
使用场景：仅用于调试，生产环境需关闭。

commands.restart

默认值：false（配置示例中显式设为false）
核心作用：控制是否启用 /restart 命令（用于重启OpenClaw服务）。
补充说明：该配置未在原文单独解释，默认关闭以避免误触发服务重启。

commands.allowFrom

默认值：无（可选配置，示例中已配置）
核心作用：按平台设置命令/指令的授权白名单，是优先级最高的授权规则。
生效规则：
- 配置后，该白名单会成为命令/指令授权的唯一来源，频道白名单/配对机制、commands.useAccessGroups 均会被忽略；
- "*" 代表全局默认规则，平台专属key（如示例中的discord）会覆盖全局规则；
- 示例解析："*": ["user1"] 表示全局仅user1可使用命令；discord: ["user:123"] 表示Discord平台仅ID为123的用户可使用命令（覆盖全局）。

commands.useAccessGroups

默认值：true
核心作用：当未配置 commands.allowFrom 时，强制执行「频道白名单/配对机制/访问组策略」的命令授权规则。
生效规则：若配置了 commands.allowFrom，该配置会被直接忽略。

绑定配置

多 Agent 场景下，绑定决定"哪个渠道的消息由哪个 Agent 处理"。

{
  bindings: [
    {
      agentId: "home",
      match: {
        channel: "whatsapp",
        accountId: "personal"         // 个人 WhatsApp → home Agent
      }
    },
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "biz"              // 工作 WhatsApp → work Agent
      }
    }
  ]
}

环境变量

API Key 等敏感信息不要直接写在配置文件里——放在 .env 文件或环境变量中，配置文件通过 ${VAR} 引用。

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",  // 直接设值（不推荐，建议用 .env）
    vars: {
      GROQ_API_KEY: "gsk-..."         // 额外变量
    },
    shellEnv: {
      enabled: true,                  // 从 shell 环境继承变量
      timeoutMs: 15000
    }
  }
}

环境变量加载优先级（先找到的优先）：

父进程环境变量（如 systemd 传入的）
当前工作目录的 .env 文件
~/.openclaw/.env 文件（全局兜底）

已存在的环境变量不会被覆盖。

高级特性

以下特性在配置较复杂时才会用到，初学者可以跳过。

1.配置分割（$include）

配置文件太长？用 $include 拆分成多个文件：

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: {
    $include: "./agents.json5"        // 单文件：整体替换
  },
  broadcast: {
    $include: [
      "./clients/a.json5",           // 多文件：按顺序深度合并
      "./clients/b.json5"
    ]
  }
}

合并规则：

单文件引入：替换当前对象
多文件引入：按顺序深度合并，后面的优先
同级键：合并后覆盖被引入的值
嵌套引入：最多 10 层
路径：相对于当前文件解析

2.环境变量替换

配置中的字符串值可以引用环境变量：

{
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}"     // 整个值来自变量
    }
  },
  models: {
    providers: {
      custom: {
        baseUrl: "${API_BASE}/v1"            // 内联拼接
      }
    }
  }
}

注意事项：

变量名仅匹配大写字母+下划线：[A-Z_][A-Z0-9_]*
变量不存在或为空时，加载报错（防止误配置）
转义：$${VAR} 输出字面量 ${VAR}
在 $include 文件中同样有效

3.SecretRef 凭证

对安全要求更高的场景，可以用 SecretRef 从外部系统获取凭证：

{
  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",              // 从命令输出读取（如 Vault）
        provider: "vault",
        id: "channels/googlechat/serviceAccount"
      }
    }
  }
}

source 类型：

类型	来源	适用场景
`env`	环境变量	简单场景（默认推荐）
`file`	文件内容	K8s Secret 挂载
`exec`	命令执行输出	HashiCorp Vault 等密钥管理器

安全相关详见第三章守护龙虾。

完整配置示例

不知道怎么开始？找一个和你情况最接近的模板，复制后修改。

最小配置——刚装好，能用就行

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

本地开发——用本地模型，不花钱

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

服务器部署——远程访问 + 模型回退

{
  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"                // 每人独立会话
  }
}

多 Agent——家庭 + 工作分开

{
  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" } }
  ]
}

配置编辑方式

四种方式修改配置，选最顺手的：

方式	命令 / 操作	适合
交互式向导	`openclaw onboard` 或 `openclaw configure`	初次配置
CLI 命令	`openclaw config set/get/unset`	改单个值
Web 控制台	打开 `http://127.0.0.1:18789` → Config 标签	可视化操作
直接编辑文件	编辑 `~/.openclaw/openclaw.json`	批量修改

# CLI 示例
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                            # 验证是否合法

注意事项

严格验证

OpenClaw 只接受完全匹配 schema 的配置。写错字段名、值类型不对、多了未知的键——网关都会拒绝启动。

遇到启动失败时：

运行 openclaw doctor 查看具体哪里出错
运行 openclaw doctor --fix 自动修复
此时只有诊断命令可用：openclaw doctor、openclaw logs、openclaw health、openclaw status

热重载范围

改了配置不一定要重启。大部分配置改了立刻生效，只有网关核心参数需要重启：

不用重启（热生效）	需要重启
渠道 `channels.*`	网关端口、绑定、认证 `gateway.*`
Agent / 模型 `agents.` `models.`	插件 `plugins`
定时任务 `cron` / Webhook `hooks`	服务发现 `discovery`
会话 / 消息 / 工具 / 技能 / 日志	—

例外：gateway.reload 和 gateway.remote 改动不触发重启。

提示：本配置详解基于 OpenClaw 官方文档整理。配置项可能随版本更新，完整参考请访问 OpenClaw Configuration。

最后编辑时间：2026/03/16 09:16

配置文件位置​

配置文件整体结构​

Agent 配置​

1.默认配置（agents.defaults）​

2.多 Agent 配置（agents.list）​

渠道配置​

1.渠道与 DM 策略​

2.群聊提及门控​

网关配置​

会话配置​

工具配置​

技能配置​

定时任务配置​

Webhook 配置​

斜杠命令配置​

绑定配置​

环境变量​

高级特性​

1.配置分割（$include）​

2.环境变量替换​

3.SecretRef 凭证​

完整配置示例​

最小配置——刚装好，能用就行​

本地开发——用本地模型，不花钱​

服务器部署——远程访问 + 模型回退​

多 Agent——家庭 + 工作分开​

配置编辑方式​

注意事项​

严格验证​

热重载范围​