OpenClaw �� 你的配置文件,可能从来都没看全过.

今天我把OpenClaw从5.20升到了5.26，每次升级成功我都习惯先打开配置文件看一眼。

这次一看，好家伙，plugins那块又多了几个安全控制选项，cron.maxConcurrentRuns默认值从1改成了8。

然后我就想，用了这么久的OpenClaw，好像从来没有正儿八经聊过它的配置文件长啥样。

今天就来干这个事。

配置文件在 ~/.openclaw/openclaw.json，格式是JSON。

{  // 这是注释，JSON5支持  "gateway": { "port": 18789 },  "agents": {    "defaults": {      "model": "anthropic/claude-sonnet-4-6",  // 尾逗号也支持    },  },}

如果这个文件不存在，OpenClaw就用安全默认值启动。所以你其实可以什么都不配就跑起来。但想连QQ、改模型、加定时任务，就得往里写。

整个配置文件大概分这么几大块：

channels    → 渠道agents      → Agent行为models      → 模型提供商mcp         → MCP服务器skills      → 技能plugins     → 插件browser     → 浏览器gateway     → 网关hooks       → Webhook钩子logging     → 日志diagnostics → 诊断cron        → 定时任务update      → 更新env         → 环境变量

每一个都是可选的。不写，系统就用默认值。

我第一次看这个列表的时候有点懵，这么多模块从哪下手？别一次看完，用到哪个学哪个就行。

先聊agents。

这块控制的是你Agent的默认行为，用哪个模型、工作目录在哪、要不要心跳。

我的配置大概长这样：

{  "agents": {    "defaults": {      "workspace": "~/.openclaw/workspace",      "model": {        "primary": "anthropic/claude-sonnet-4-6",        "fallbacks": ["openai/gpt-5.4"]      },      "heartbeat": {        "every": "30m",        "target": "last"      }    }  }}

workspace就是工作目录，Agent读写文件都在这下面。我把公众号文章、研究笔记都扔里面，方便Agent直接调。

model分primary和fallbacks。主力模型挂了自动切备用，不用你手动换。以前用OpenRouter的时候经常遇到500错误，有了fallback链至少不会卡死在那。

heartbeat就是心跳，每隔30分钟Agent会主动检查一次。这个我单独写过文章，就不展开了。

如果你有多个Agent，可以用agents.list配不同的角色：

{  "agents": {    "list": [      { "id": "main", "default": true },      { "id": "writer", "skills": ["mp-pipeline"] },      { "id": "locked-down", "skills": [] }    ]  }}

每个Agent可以有自己的技能列表、工作目录、模型。main处理日常对话，writer专门写公众号，locked-down什么都不让干——适合给不信任的渠道用。

再来看channels

这是大多数新手第一个接触的模块。要把OpenClaw接到QQ、Telegram、WhatsApp，都在这里配。

每个渠道一个配置块，结构大同小异：

{  "channels": {    "qqbot": {      "enabled": true,      "appId": "xxx",      "botToken": "xxx"    },    "telegram": {      "enabled": true,      "botToken": "123:abc",      "dmPolicy": "pairing",      "allowFrom": ["tg:123"]    }  }}

这里有个东西容易搞混——dmPolicy。pairing模式就是陌生人发消息过来，Agent会发一个配对码，对方确认了才能聊。allowlist更严，只有你写在allowFrom列表里的人能说话。open就是谁都能聊，我一般临时测试用一下，用完马上改回去。disabled就是直接把私聊关了。

我的习惯是：主力渠道用pairing，临时测试用open。别长期开着open，不然你都不知道谁在跟你的Agent聊天。

browser模块配的是浏览器的连接方式。

OpenClaw本身不带浏览器，它需要连到一个已经运行的Chrome实例。

{  "browser": {    "enabled": true,    "defaultProfile": "user",    "tabCleanup": {      "enabled": true,      "idleMinutes": 120,      "maxTabsPerSession": 8    }  }}

defaultProfile有两个选项：user连你正在用的Chrome，openclaw用OpenClaw自己启动的无头浏览器。我一般用user，因为有些网站需要登录态，用openclaw profile就得重新登录。

tabCleanup自动关闲置标签。我之前遇到过Agent开了十几个标签页不关，内存直接爆了。有了这个，2小时没用的标签自动关，省心很多。

还有一个容易被忽略的——ssrfPolicy。默认情况下，Agent不能用浏览器访问你的内网地址（192.168.x.x、127.0.0.1之类的）。这是安全设计，防止恶意skill偷你内网的东西。如果你确实需要（比如访问本地部署的服务），再手动打开。

{  "browser": {    "ssrfPolicy": {      // 默认禁止访问内网      // 需要的话手动开：      // "dangerouslyAllowPrivateNetwork": true    }  }}

models是OpenClaw最灵活也最容易踩坑的地方。

{  "models": {    "mode": "merge",    "providers": {      "my-custom-provider": {        "baseUrl": "https://api.example.com/v1",        "models": [{ "id": "gpt-4" }]      }    }  }}

mode有两个选项：merge和replace。merge会把你的自定义provider合并到内置列表里，replace会完全替换掉内置列表。绝大多数人用merge就够了。

自定义provider有什么用？两种场景：你用了某个代理服务，baseUrl不是官方的；或者你本地跑了一个Ollama模型，想通过OpenClaw调它。这两个都需要在models.providers里配。

之前写过模型配置的教程，这里就不展开了，记住模型ID的格式是 provider/model，比如 anthropic/claude-sonnet-4-6，别写反了。

skills模块控制Agent能调用哪些技能。

{  "skills": {    "allowBundled": ["gemini", "peekaboo"],    "entries": {      "weather": { "enabled": true },      "sag": { "enabled": false }    }  }}

allowBundled只控制内置技能的白名单，你自己装的第三方技能不受这个限制。我之前以为allowBundled是所有技能的总开关，搞混了好一阵。

entries里可以禁用某个技能（enabled: false），也可以给技能传API Key：

{  "skills": {    "entries": {      "qveris-official": {        "apiKey": { "source": "env", "provider": "default", "id": "QVERIS_API_KEY" }      }    }  }}

API Key不硬编码在配置文件里，而是从环境变量读。换机器的时候只要配环境变量就行，不用改配置文件。

plugins是OpenClaw里最复杂也最重要的模块，没有之一。

{  "plugins": {    "enabled": true,    "allow": ["search", "memory", "browser"],    "bundledDiscovery": "compat",    "deny": [],    "entries": {      "search": {        "enabled": true,        "hooks": {          "allowPromptInjection": false,          "allowConversationAccess": false        }      }    }  }}

先说说bundledDiscovery，这个字段坑过不少人。allowlist是严格模式，所有插件都得在allow列表里才能加载。compat是兼容模式，allow列表只控制非内置插件，内置插件自动发现。如果你是旧版升上来的，默认是compat。如果你从头开始配，建议直接用allowlist，更安全。

entries里每个插件都可以单独控制：allowPromptInjection防提示注入，allowConversationAccess是否允许插件读你的聊天内容，allowModelOverride是否允许插件换模型。

我第一次看到这些选项的时候，觉得”至于吗”。后来装了一个社区插件，它偷偷换了个垃圾模型给我跑，输出质量直接崩了。从那以后，非信任插件一律锁死这些权限。

gateway配的是OpenClaw的Web服务本身。

{  "gateway": {    "port": 18789,    "bind": "loopback",    "auth": {      "mode": "token",      "token": "***"    },    "controlUi": {      "enabled": true,      "basePath": "/openclaw"    }  }}

bind控制监听范围。loopback只监听本机，最安全。lan监听局域网，家里几台设备都能连。tailnet只监听Tailscale网络。我平时用loopback，需要远程访问的时候切tailnet。

auth.mode推荐用token或trusted-proxy。none等于裸奔，千万别在生产环境用。

{  "cron": {    "enabled": true,    "maxConcurrentRuns": 8,    "sessionRetention": "24h",    "retry": {      "maxAttempts": 3,      "backoffMs": [30000, 60000, 300000],      "retryOn": ["rate_limit", "overloaded", "network", "timeout"]    }  }}

最后聊一个很多人忽略的东西——环境变量。

OpenClaw支持三种方式管理环境变量。

第一种，在配置文件的env块里写：

{  "env": {    "OPENAI_API_KEY": "sk-...",    "QVERIS_API_KEY": "xxx"  }}

第二种，从系统环境变量导入：

{  "env": {    "shellEnv": {      "enabled": true,      "timeoutMs": 15000    }  }}

开启后OpenClaw会自动从你的shell配置里读环境变量。

第三种，在配置中引用环境变量：

{  "skills": {    "entries": {      "qveris-official": {        "apiKey": { "source": "env", "provider": "default", "id": "QVERIS_API_KEY" }      }    }  }}

我的建议就一句：API Key不要硬编码在配置文件里。用环境变量管理，配置文件里只引用变量名。这样你分享配置文件的时候，不会不小心把Key也分享出去。

说到分享配置文件，再扯几个踩过的坑。

改了配置不生效？大部分配置是热生效的，但有些配置（比如gateway.port、auth.mode）改了必须重启网关。不确定的话直接重启最保险。

JSON格式错了启动不了。OpenClaw对配置校验很严格，多一个逗号少一个引号都不行。启动不了的时候跑一下 openclaw doctor，它会告诉你哪里错了。

每次大版本升级，我都会打开配置文件看一眼。不知道这些变化，可能你的配置就跟新版本不搭了。

以上，如果觉得不错，随手点个赞、在看、转发三连吧～谢谢你看我的文章，我们，下次再见。

文章内容基于OpenClaw版本2026.5.26。