装好 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/.openclawTermux$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_KEYsk-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 时你可以先看它声明了哪些环境变量再决定是否启用心里有数。MCPModel Context Protocol配置是升级版的操作能力。它允许 OpenClaw 通过 MCP 协议接入外部工具服务比如操作文件系统、读取数据库、调用设计工具等。示例配置mcp_servers: filesystem: command: npx args: - -y - modelcontextprotocol/server-filesystem - .这里我插一句MCP 服务器对网络和运行环境要求比较高如果你在某些受限网络环境下部署npx下载依赖可能会很慢甚至失败。这就解释了为什么很多人在离线整合包里使用 MCP 会碰到各种奇怪问题——本质上不是 OpenClaw 的问题而是 MCP 服务器依赖没有预置完整。3. 分平台实操从 Windows 整合包到飞牛 NAS3.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] DescriptionOpenClaw Gateway Afternetwork.target [Service] Useropenclaw WorkingDirectory/home/openclaw EnvironmentOPENCLAW_DATA_DIR/home/openclaw/.openclaw EnvironmentSILICONFLOW_API_KEYsk-xxxx EnvironmentMODELSCOPE_API_KEYsk-xxxx ExecStart/usr/local/bin/openclaw gateway start Restartalways RestartSec10 [Install] WantedBymulti-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_KEYsk-xxxx - MODELSCOPE_API_KEYsk-xxxx - OPENCLAW_LOG_LEVELinfo理解了 Linux 那套逻辑后Docker 部署其实更容易。因为配置文件全部映射在宿主机上你可以直接用 NAS 的文件管理器编辑不用进容器。一个容易犯错的地方是容器内路径和宿主机路径的映射。./data:/root/.openclaw表示宿主机上data目录对应容器内的/root/.openclaw。所以你在宿主机上看到的配置文件路径是./data/config.yaml但在容器内日志里打印的路径是/root/.openclaw/config.yaml。这两个其实指的是同一个文件。如果你在宿主机上找不到日志里写的路径别慌检查一下映射关系。Docker 部署还多了一个配置方法环境变量覆盖。OpenClaw 支持用OPENCLAW_*前缀的环境变量覆盖配置文件中的字段。比如OPENCLAW_LOG_LEVELdebug等效于在配置里把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文件夹再重启服务多半就好了。这个细节写在官方文档的角落不特别注意很难发现。