装好 OpenClaw 只是把事情做完了一半，真正的分水岭在配置。很多人启动成功后，卡在“不知道去哪改模型”“skill 装了没反应”“微信一接入就报错”这类问题上，翻遍文档也找不到靠谱答案。这篇手册不打算复述官方文档，就按我实际部署过 Windows 整合包、Linux 原生、Docker、Termux 这些环境后的经验来写，把配置文件的位置、核心字段、修改技巧和坑一次性讲清楚。
这篇内容适合三类人：刚把 OpenClaw 装起来、但对配置体系一脸懵的新手；已经能跑通基础对话、想调整模型和技能的老手；以及计划在 NAS、安卓 Termux 这类特殊环境部署、需要理解配置如何适配的玩家。老规矩，先讲设计思路，再逐个拆字段，然后给分平台实操，最后是问题排查，保证你能跟着一步步搞定。
1. 动手之前，先理解 OpenClaw 的配置体系
1.1 配置文件到底在哪里：不同部署方式的路径差异
OpenClaw 的配置文件路径是我见过被问得最多的问题。这不能怪用户，因为不同部署方式下，配置目录真的不一样。毕竟是开源项目，安装途径太多，官方也没法统一成一个路径。
我自己实际遇到过的情况是这样的：
- Windows 离线整合包：配置文件通常在整合包解压目录下的
data\openclaw\config.yaml，或者%USERPROFILE%\.openclaw\config.yaml。整合包作者有时会改默认数据目录，所以最靠谱的确认方法是看启动脚本或启动日志里打印的“config loaded from”那行。 - Linux 原生安装：配置文件在
~/.openclaw/config.yaml，数据目录默认在~/.openclaw/data/。 - Docker / NAS（飞牛、群晖等）：配置文件放在挂载卷里，比如
/vol1/docker/openclaw/config/config.yaml，具体路径看你 compose 文件里把哪个目录映射到了容器内的/root/.openclaw。 - Termux 原生部署：无 proot 的轻量方案下，配置在
$PREFIX/var/lib/openclaw/config.yaml，和 Linux 的用户目录套路不一样。
我把这些整理成了一张对照表，方便你对号入座：
| 部署方式 | 常见配置路径 | 配置目录说明 |
|---|---|---|
| Windows 离线整合包 | 整合包目录\data\openclaw\ | 便携式数据目录，跟着解压位置走 |
| Windows 手动安装 | %USERPROFILE%.openclaw\ | 用户主目录下隐藏文件夹 |
| Linux 原生 | ~/.openclaw/ | 当前系统用户目录下 |
| Docker 容器 | 宿主机挂载目录 | 容器内映射到 /root/.openclaw |
| Termux | $PREFIX/var/lib/openclaw/ | Termux 专属数据空间 |
注意：不管哪种环境，OpenClaw 都支持用环境变量
OPENCLAW_DATA_DIR手动指定数据目录。如果你改了位置，记得把原来的目录迁移过去，否则历史会话记录和数据会找不到。
1.2 配置格式：YAML 还是 JSON？先搞清楚再改
OpenClaw 支持 YAML 和 JSON 两种配置格式，默认是 YAML。我的建议是：能用 YAML 就别换 JSON。
原因很简单。YAML 的缩进结构对“配置树”的表达非常友好，而且可以写注释。不要小看注释，配置项多了之后，没有注释的 JSON 就是一团乱麻。我自己在config.yaml里每个板块顶部都会写一行说明，比如“# 模型供应商，新增前先申请 API Key”，三个月后回来看，省下的时间不可估量。
JSON 也不是一无是处。有些自动化脚本用程序生成配置时，JSON 更不容易写错。但从人力维护的角度的讲，YAML 是绝对主流。你要做的第一件事，就是确认当前配置文件的格式和后缀名一致，别出现文件名叫config.yaml里面却是 JSON 语法的情况——这种情况还真不少，因为你从其它地方复制了一段配置，粘贴时没注意格式。
另一个容易踩的坑是缩进。YAML 不允许用 Tab 缩进，必须用空格。我见过一个人排查了半小时“配置没生效”，最后发现是编辑器自动把空格转成了 Tab。建议你在编辑器里开启“空白字符显示”，或者在保存前用openclaw config validate检查一下。
1.3 热加载机制与“改了没生效”的原因
OpenClaw 的配置不是全部热加载的。这个认知特别关键，能帮你少走很多弯路。
目前实测下来的行为是：
- 日志级别、部分渠道参数：修改后保存文件即可生效，网关会监听配置文件变化。
- 模型供应商、Gateway 模型切换、技能权限调整：需要重启 gateway 进程，或者执行
openclaw gateway restart。 - 新增 MCP 服务：必须完整重启 OpenClaw 主进程，因为 MCP 服务在启动阶段就要建立握手连接。
常常有人改完配置后发现没效果，就怀疑自己改错了。实际上大概率只是没有重启对应服务。所以我养成了一个习惯：每次改完配置，先执行openclaw config validate验证语法，再执行openclaw gateway restart重启网关，最后用openclaw doctor检查整体健康状态。
记住这个铁三角：改配置 → 校验语法 → 重启服务。任何一步缺失，都可能让你白忙一场。
2. 核心配置项逐个拆解：模型、网关与技能
2.1 全局配置：数据目录、日志级别与安全开关
拿到一份 OpenClaw 配置，最先要看的是全局配置段。这部分相当于整个程序的基础设置，我常用的配置模板如下：
version: 1 data_dir: ~/.openclaw/data log_level: info sandbox: enabled: true allow_network: false max_memory_mb: 512这里有几个点值得展开说。
data_dir是数据目录，所有会话记录、向量索引、技能缓存都存在这里。如果你在跑多个 OpenClaw 实例，或者准备迁移服务器，改这个字段是必须的。尤其是 Docker 部署，这个目录要对应到宿主机挂载卷，否则容器一重建数据就全丢了。
log_level是日志级别，可选值有 debug、info、warning、error。平时用 info 就够，排查问题时切到 debug 会输出非常详细的信息，包括每次 API 请求的耗时、命中了哪条技能规则、消息在哪个环节滞留。但 debug 日志量很大，跑一天能到几百 MB，排查完记得切回去。
sandbox是技能沙箱配置，很多人会忽略这个。它控制技能代码能接触到什么资源。allow_network: false会让所有技能无法发起外部网络请求，这对安全很重要——因为你加载的 skill 可能是第三方写的，你不知道它会在后台做什么。我的建议是：除非某个技能确实需要联网，否则保持默认关闭。
2.2 Gateway 模型配置：Agents 与 Model Provider 的关系
模型配置是 OpenClaw 配置的灵魂。不夸张地讲，一半以上的配置问题都出在这里。首先要理解两个概念：Provider 和 Gateway。
Provider 是模型供应商，比如 OpenAI、硅基流动、魔塔（ModelScope）、智谱等。每个 Provider 定义了 API 地址、鉴权方式和可用的模型列表。Gateway 则是 OpenClaw 内部的消息网关，它决定哪个 Agent 使用哪个 Provider 的哪个模型来响应用户消息。
我常用的多供应商配置大概长这样：
providers: - id: siliconflow type: openai_compatible base_url: https://api.siliconflow.cn/v1 api_key_env: SILICONFLOW_API_KEY models: - Qwen/Qwen2.5-72B-Instruct - deepseek-ai/DeepSeek-V3 - id: modelscope type: openai_compatible base_url: https://api.modelscope.cn/v1 api_key_env: MODELSCOPE_API_KEY models: - qwen-max - qwen-plus gateway: agent: default model: Qwen/Qwen2.5-72B-Instruct provider: siliconflow fallback_models: - provider: modelscope model: qwen-max划几个重点。
第一，api_key_env填的是环境变量名，不是密钥本身。我强烈建议不要把 API Key 直接写进配置文件。原因很现实：配置文件可能被同步到 git 仓库、被截图发到群里、或者被日志工具捕获。而环境变量只存在于你的系统环境中，泄露面小得多。配置好之后，在启动 OpenClaw 前先导出变量：
export SILICONFLOW_API_KEY=sk-xxxxxxxxxxxxWindows 下对应的是setx SILICONFLOW_API_KEY "sk-xxxxxxxxxxxx"或直接在系统环境变量里加。
第二，base_url一定要填对。很多供应商的 API 兼容 OpenAI 格式，但路径可能不同，有的以/v1结尾，有的不带。填错了，请求会直接 404 或者 401。一个可用的经验法则：先在终端里用 curl 测试一下这个地址能否正常响应鉴权请求，确认没问题再填进配置。
第三，fallback_models是容灾配置。OpenClaw 支持在主模型不可用时自动切换备用模型。这个真的很有用，供应商的 API 偶尔会限流或崩溃，配置了故障转移至少不会让整个服务瘫掉。
2.3 渠道配置：微信、飞书、Telegram 等通过 channel 接入
OpenClaw 的渠道配置采用 channel 插件模式。你想接入哪个 IM 平台，就在配置里启用对应的 channel。这里以最常用的微信为例：
channels: wechat: type: wechat enabled: true plugin_dir: ./plugins/wechat scan_qr: true login_timeout: 60这里有个很关键的现实问题要提醒你：微信这类个人号接入并不稳定。官方 plugin 走的是个人微信网页版协议，账号存在被服务端风控的风险。你在网上看到有人报“触发了服务端风控或会话残留”，就是这类问题。
什么叫“会话残留”？简单说就是上一次会话没有正常退出，服务端还保留着登录态，导致新会话无法建立或者被判定为异常登录。我的处理经验是：
- 配置里开启
scan_qr，用扫码方式登录，不要用自动登录。 - 如果出现登录异常，先把微信插件目录下的 session 缓存删除，也就是
plugins/wechat/session/里的文件，再重新扫码。 - 控制消息频率。个人号短时间高频发送消息，非常容易被风控。如果你做的场景需要大量推送，建议用企业微信或飞书渠道替代个人微信。
飞书和 Telegram 的配置类似，只是type字段不同，分别对应feishu和telegram。飞书还支持通过开放平台创建应用的方式接入，这种方式比个人微信稳定得多，适合做正式的生产级机器人。
2.4 Skills 与 MCP：让 OpenClaw 具备“动手能力”
如果说渠道是 OpenClaw 的感官，那 skills 就是它的手脚。配置技能板块，是我觉得 OpenClaw 最有趣的部分。
每个技能本质上是一个包含代码和配置的目录，OpenClaw 通过配置来决定：这个技能是否启用、能跑多久、有没有访问权限。我的常用配置长这样：
skills: - name: web_search enabled: true max_runtime: 60 env: SEARCH_API_KEY_ENV: TAVILY_API_KEY - name: shell_exec enabled: false注意几个关键词。
max_runtime是技能最大运行时间，单位秒。有些技能执行耗时很长，比如要抓取整个网页，默认 30 秒可能不够。但也不要设置得太长，一个运行 10 分钟的技能会阻塞网关的响应能力，让所有用户都跟着等。
env是传给技能的环境变量。设计上很合理——技能需要的密钥由主配置统一管理，而不是写死在技能代码里。这样的好处是：从社区下载第三方 skill 时，你可以先看它声明了哪些环境变量再决定是否启用，心里有数。
MCP（Model Context Protocol）配置是升级版的操作能力。它允许 OpenClaw 通过 MCP 协议接入外部工具服务，比如操作文件系统、读取数据库、调用设计工具等。示例配置：
mcp_servers: filesystem: command: npx args: - -y - "@modelcontextprotocol/server-filesystem" - "."这里我插一句：MCP 服务器对网络和运行环境要求比较高，如果你在某些受限网络环境下部署，npx下载依赖可能会很慢甚至失败。这就解释了为什么很多人在离线整合包里使用 MCP 会碰到各种奇怪问题——本质上不是 OpenClaw 的问题，而是 MCP 服务器依赖没有预置完整。
3. 分平台实操：从 Windows 整合包到飞牛 NAS
3.1 Windows 离线整合包：便携目录与一键校验
先说 Windows 离线整合包。很多人图省事下载整合包，解压就能用。但整合包最大的问题是：你不太清楚它把配置放在了哪个具体路径，而且不同作者打包的方式可能不一样。
我的建议是，拿到整合包后不要急着双击启动，先做两步。
第一步，看目录结构。整合包里通常会有start.bat或启动OpenClaw.vbs之类的脚本，用记事本打开，里面很可能有一行set OPENCLAW_DATA_DIR=...。这就是它的数据目录设置。如果脚本里没有显式设置，配置大概率在%USERPROFILE%\.openclaw下。
第二步，执行一次配置校验。在整合包目录下打开 PowerShell，运行：
.\openclaw.exe config validate如果提示语法错误，它会明确告诉你哪一行有问题。如果提示配置文件不存在，说明你还没初始化，运行.\openclaw.exe config init就能生成默认配置。
Windows 下还有一个高频报错：could not safely verify the WSL2 environment。这个错误并不是配置语法有问题，而是 OpenClaw 在启动时需要检查 WSL2 环境是否可用，但系统里可能没安装 WSL2 或者版本太旧。解决办法是：
wsl --update wsl --set-default-version 2如果根本没装 WSL，也可以跳过这个检查，在配置里设置wsl_verify: false。注意，这样做有前提：你用的功能不依赖 WSL2。如果整合包依赖 WSL2 的 Linux 兼容层，强行跳过会导致后续功能异常。稳妥的做法是先把 WSL2 装好。
3.2 Linux 原生部署：用户目录下的配置文件
在 Linux 服务器上部署 OpenClaw，配置逻辑最清晰。安装完成并执行初始化后，配置会生成在~/.openclaw/config.yaml。
我用一台 Ubuntu 服务器部署时，整个流程是这样的。
先用普通用户执行初始化：
openclaw config init然后编辑配置。这一步要特别注意权限，因为 OpenClaw 会读取 API Key 环境变量，而这些变量不应该写在全局的/etc/profile里。我习惯为 OpenClaw 创建一个独立的 systemd service，在 service 文件里指定环境变量：
[Unit] Description=OpenClaw Gateway After=network.target [Service] User=openclaw WorkingDirectory=/home/openclaw Environment=OPENCLAW_DATA_DIR=/home/openclaw/.openclaw Environment=SILICONFLOW_API_KEY=sk-xxxx Environment=MODELSCOPE_API_KEY=sk-xxxx ExecStart=/usr/local/bin/openclaw gateway start Restart=always RestartSec=10 [Install] WantedBy=multi-user.target这样配置的好处是，环境变量只对 OpenClaw 服务生效，系统其他用户看不到，也不会泄露到 shell 的历史记录里。
配置改完后，依次执行：
openclaw config validate sudo systemctl daemon-reload sudo systemctl restart openclaw sudo systemctl status openclaw这里再分享一个实用小技巧：OpenClaw 启动时会打印当前生效的配置摘要，包括数据目录、启用的渠道和模型供应商列表。如果你不确定服务到底加载了什么配置，看启动日志比翻文件还快。
3.3 Docker 部署（飞牛/群晖 NAS）：用环境变量覆盖配置
在 NAS 上跑 OpenClaw 是现在的热门玩法，毕竟 NAS 24 小时开机，非常适合跑这类常驻服务。飞牛、群晖都支持 Docker，配置逻辑也类似。
我的docker-compose.yml里核心配置是这样写的：
services: openclaw: image: openclaw/openclaw:latest container_name: openclaw restart: unless-stopped ports: - "8080:8080" volumes: - ./data:/root/.openclaw environment: - OPENCLAW_DATA_DIR=/root/.openclaw - SILICONFLOW_API_KEY=sk-xxxx - MODELSCOPE_API_KEY=sk-xxxx - OPENCLAW_LOG_LEVEL=info理解了 Linux 那套逻辑后，Docker 部署其实更容易。因为配置文件全部映射在宿主机上，你可以直接用 NAS 的文件管理器编辑，不用进容器。
一个容易犯错的地方是：容器内路径和宿主机路径的映射。./data:/root/.openclaw表示宿主机上data目录对应容器内的/root/.openclaw。所以你在宿主机上看到的配置文件路径是./data/config.yaml，但在容器内日志里打印的路径是/root/.openclaw/config.yaml。这两个其实指的是同一个文件。如果你在宿主机上找不到日志里写的路径，别慌，检查一下映射关系。
Docker 部署还多了一个配置方法：环境变量覆盖。OpenClaw 支持用OPENCLAW_*前缀的环境变量覆盖配置文件中的字段。比如OPENCLAW_LOG_LEVEL=debug等效于在配置里把log_level改为 debug。这个机制对容器化部署特别友好。
3.4 Termux 原生部署：无 proot 的轻量配置思路
Termux 上跑 OpenClaw，属于比较硬核的玩法了。很多教程会让你装 proot 来模拟完整 Linux 环境，但那样体积大、性能差。无 proot 的原生部署方案，配置上要注意的东西不太一样。
首先，配置路径是$PREFIX/var/lib/openclaw/，不是~/.openclaw。这是因为 Termux 的可写目录范围和标准 Linux 不同，OpenClaw 检测到 Termux 环境时会自动适配到这个路径。
其次，Termux 的内存和存储空间有限，配置里建议做几处调整：
log_level: warning gateway: max_workers: 2 skills: - name: shell_exec enabled: false mcp_servers: {}max_workers: 2限制并发 worker 数量，避免内存爆炸。log_level: warning减少日志写入，延长存储寿命。关掉不需要的 skill 和 MCP 服务，省的不仅是内存，还有安装依赖的时间。
Termux 下启动命令也略有不同：
termux-wake-lock openclaw gateway starttermux-wake-lock是 Termux 的保活命令，防止手机息屏后进程被系统杀掉。这个和配置无关，但跑在 Termux 上基本必用。
4. 高频问题排查与避坑记录
4.1 改了配置不生效：检查这三步
配置不生效，九成是下面三个原因之一。我自己排障时就是按这个顺序检查的。
第一步，确认改对了文件。听起来像废话，但我真的遇到过有人同时存在~/.openclaw/config.yaml和整合包目录下两个配置文件，改了半天改的是不生效的那个。先执行openclaw config show，它会打印当前实际加载的配置路径。
第二步，确认语法没问题。执行openclaw config validate，有任何 YAML 缩进错误或字段拼写错误都会在这里暴露。
第三步，确认服务重启了。如果改的是模型供应商、技能权限这类需要重启才能生效的字段，只保存文件没用。跑一下openclaw gateway restart，再看日志确认重启完成。
4.2 “could not safely verify the WSL2 environment”怎么处理
这个报错在 Windows 上很常见，我前面也提到了。再补充一些细节。
OpenClaw 在 Windows 上默认会调用wsl.exe来验证 WSL2 环境是否正常，验证内容包括内核版本、默认版本设置。如果系统里 WSL 功能没有完全启用，就会出现“无法安全验证”的提示。
处理方式有两种。推荐优先解决 WSL 本身：
wsl --install wsl --update wsl --set-default-version 2执行完可能需要重启电脑。如果你确定不需要 WSL 相关功能，再考虑第二个方式：在配置文件中加：
system: wsl_verify: false把验证关掉，绕开这个检查。但关闭前一定想清楚，你后续是否要使用任何依赖 WSL2 的能力。如果只是做简单的模型对话和 IM 接入，关闭影响不大。
4.3 微信插件触发风控或会话残留
接入微信渠道的朋友碰到的问题最多。报错信息里出现“ilinkai 服务端风控”或者“会话残留”，翻译成人话就是：你的个人微信号被微信服务端判定为“非正常客户端”，或者上一次登录会话没有被清理干净。
解决办法，按顺序操作：
- 先停止 OpenClaw 网关。
- 删除微信插件下的 session 缓存目录，通常是
plugins/wechat/session/。 - 在配置中确认
scan_qr: true，重新启动网关，用手机扫二维码登录。 - 登录成功后，不要马上发大量消息。先发一条测试消息，等自然回复后再继续。
如果频繁被风控，说明你的使用行为已经触发了阈值。这时候最靠谱的解决方案是更换渠道，比如走企业微信或飞书，而不是继续和风控机制纠缠。个人号本来就承担着很重的人工客服和社交功能，大规模自动化操作确实容易触碰红线。
4.4 模型请求 401 或超时：先从 provider 配置查起
模型请求报 401 Unauthorized，几乎可以确定是 API Key 没传对。注意，OpenClaw 是从环境变量读取 Key 的，配置里的api_key_env只是指定了“去哪个环境变量里取”，所以你要检查的不仅仅是配置文件，还有环境变量本身有没有设置成功。
排查命令：
echo $SILICONFLOW_API_KEY如果输出为空，说明环境变量没设置。如果输出正常，再看环境变量名拼写和配置里api_key_env是否完全一致，大小写都不能差。
连接超时的问题通常出在两个地方。一是base_url填错了，请求发到了错误地址，被拒绝或超时；二是网络到供应商服务不可达。遇到超时，先 curl 测试一下服务商的接口连通性。注意，如果实测中某些服务对网络环境比较敏感，那就要从网络链路和代理层面排查，但这块本文不展开。
4.5 日志配置文件：不要被 logback.xml 带偏方向
搜索 OpenClaw 相关配置时，很容易被带偏到 logback.xml 这些 Java 项目的配置上。OpenClaw 本身不是 Java 项目，不需要也不使用 logback.xml。
OpenClaw 的日志由统一配置管理，级别就是我在 2.1 节里说的log_level字段。如果你想调整日志的输出格式、按天滚动写入之类的功能，请直接编辑配置文件里的日志相关段落，而不是去创建 XML 文件。
有一个例外情况要注意：如果你在部署时顺便启用了 Nginx 反向代理做访问控制，那么 Nginx 的日志配置又是另一套事情了，但那是 Nginx 的配置文件，和 OpenClaw 没有关系。
4.6 常用配置命令速查表
最后把我实际使用频率最高的配置相关命令整理成了一张表。建议你存到本地，排障的时候顺手就能用。
| 命令 | 作用 | 使用时机 |
|---|---|---|
openclaw config init | 生成默认配置 | 首次部署 |
openclaw config show | 显示当前生效配置路径和摘要 | 不确定改的是哪个文件时 |
openclaw config validate | 校验配置语法 | 每次改完配置后必做 |
openclaw doctor | 健康检查，包括环境、网络、配置完整性 | 启动失败或功能异常时 |
openclaw gateway restart | 重启网关服务 | 修改模型、渠道、技能配置后 |
openclaw --version | 查看版本号 | 排查版本兼容性问题 |
每次动配置之前先备份，这句话我说了无数遍，但还是要再唠叨一次。配置是在不断试错的过程中完善的，有备份才能放心大胆地改。我现在每次修改前都会执行一句cp config.yaml config.yaml.bak.$(date +%Y%m%d)，几秒钟的事，却能避免很多让人崩溃的场面。
最后再分享一个小技巧。如果你在配置阶段反复折腾，始终觉得有些行为不符合预期，不一定是配置写错了，也可能是缓存惹的祸。OpenClaw 会缓存部分技能元数据和模型列表。当你新增了一个模型或技能，但配置里怎么改都没反应时，清一下缓存目录里的cache文件夹，再重启服务，多半就好了。这个细节写在官方文档的角落，不特别注意很难发现。
