聊OpenClaw，绕不开的就是它那个主配置文件。很多人在部署阶段就被劝退了：软件装好了、进程也拉起来了，结果一跑起来，Agent要么不回复、要么回一句错一句，查来查去最后发现全是配置参数的锅。这篇我打算把主配置文件里的参数按类别拆开讲透，从身份人设到模型接入、从技能加载到并发控制，每个参数是什么、为什么要有、怎么调，一并说清楚。适合正在部署OpenClaw、或者已经把服务跑起来但始终没搞懂配置逻辑的朋友，对照着抄作业就行。
先说明一点：OpenClaw的主配置不是那种“填几个字段就完事”的简单清单，它承担了身份定义、运行时装配、外部交互三层的职责。你改一个参数，可能影响的是Agent的说话语气；再改一个参数，可能直接决定了它用哪块算力跑推理。所以把配置文件的逻辑吃透，比装好软件本身更重要。下面按章节展开。
1. 主配置文件的整体定位与设计思路
1.1 为什么OpenClaw要把“一切”都塞进一份配置文件
OpenClaw本质上是一个自托管的AI Agent运行时，它的设计思路是“配置驱动”，而不是“代码驱动”。也就是说，你日常要调整的行为，比如Agent叫什么名字、用哪个模型、能调用哪些技能、链接什么通道，全部通过主配置文件表达，而不是去改源码。这样做的第一个好处是环境可复制：换一台机器，把配置文件和技能目录一拷，服务就能以几乎一致的状态跑起来，不用担心代码被改乱。
第二个好处是多实例切换非常方便。我见过有人在一台服务器上同时跑三个OpenClaw实例，一个管家庭助理，一个管工作群机器人，一个做自动化实验。三者共用同一套代码，但每份配置各自独立，通过启动参数指定不同的配置文件，互不干扰。这就像同一套厨房设备，用不同的菜谱能做出完全不同的菜：代码是设备，配置是菜谱，设备不动，菜谱决定一切。
从加载逻辑上看，OpenClaw启动时会先解析主配置文件，然后按照配置去加载模型后端、技能插件和通道模块。如果某个模块的参数缺失，程序通常不会直接报错，而是默默套用内置默认值，这也是很多“配置看似没问题但行为诡异”的根源。所以理解这个机制之后你就会明白：配置文件里每一个键都不是随便写的，它们共同决定了Agent最终长什么样。
1.2 配置层级：先看懂顶层结构
主配置文件通常采用YAML格式，也支持JSON，但我强烈建议用YAML，因为它支持注释、嵌套结构清晰。第一次打开配置文件的人往往会懵，因为参数确实多。不要慌，顶层其实只有几个大块，先把树根摸清楚，叶子就好认了。
| 顶层键 | 职责范围 | 说明 |
|---|---|---|
agent | 身份与人格 | Agent名字、系统提示词、语言、时区 |
model | 模型接入 | 模型服务商、模型名、API地址、生成参数 |
skills | 技能系统 | 技能目录、加载策略、白名单、超时控制 |
channels | 外部通道 | 本地终端、桌面伴侣、Telegram等接入方式 |
runtime | 运行控制 | 并发数、任务超时、重试次数 |
storage | 存储设置 | 会话记录、缓存文件存放位置 |
logging | 日志配置 | 日志级别、输出位置 |
advanced | 高级选项 | 调试开关、实验性参数 |
配置的生效顺序也需要提前搞清楚：命令行参数优先级最高，其次是环境变量，再次是配置文件里显式填写的值，最后才是内置默认值。这个优先级链在实际排查时极其重要。比如你在配置文件里把model.temperature设成了0.7，但启动命令里通过环境变量覆盖成了0.2，那最终实际跑的是0.2。后面故障排查章节我会专门讲这个，先记住结论：改配置之前先确认你到底在改哪一层。
2. 参数分类详解：逐类说清每个参数的作用
2.1 身份与人格参数：Agent是怎么“开口”的
这一组参数解决的是“Agent是谁”的问题。最基础的是agent.name，它作为实例的唯一标识，多个实例同时运行时这个名字不能冲突。agent.description是给人看的简介，也会被一些通道展示出来，简单写清楚用途即可。
真正决定Agent行为风格的是agent.system_prompt。这个参数会作为系统级提示词，在每次请求时与用户消息一起发送给模型。它相当于Agent的“底层人设+工作守则”，你可以在这里规定角色定位、回答风格、禁忌事项、任务边界。我自己的习惯是写清楚“你是什么角色、能做什么、不能做什么、遇到不确定的事情怎么回应”，而不是写一堆空泛的口号。比如：
agent: name: home-assistant description: 家庭助理机器人 system_prompt: | 你是一个可靠的家庭助理，回答简洁、亲切。 当用户询问家电控制时，先确认设备名称再执行。 如果信息不足，明确说明缺少什么，不要猜测。 language: zh-CN timezone: Asia/Shanghailanguage参数控制默认回复语言，如果你主要用中文，就设置成zh-CN，不然模型很可能用英文回你。timezone影响时间相关功能的计算，比如定时任务、日志时间戳，设置错了会导致调度时间偏移。还有一个容易被忽略的是agent.temperature，有些版本会把它放在agent层级。temperature控制生成文本的随机性，取值0到1之间：工具调用、信息提取类任务建议0.2左右，越低越稳定；闲聊、创意写作可以提高到0.7以上。我最开始图省事把temperature设成0.9，结果Agent经常在工具调用参数上自由发挥，把好好的请求写成天马行空的格式，后来又调回0.3才正常。
2.2 模型接入参数：云端API与本地Ollama怎么选
模型接入是主配置里最核心的一块，因为Agent的“大脑”全靠这里。很多人问过一个问题：OpenClaw是不是只能通过接入云端API的方式来使用算力？答案是否定的。OpenClaw支持多种provider，包括OpenAI、Anthropic、OpenRouter等云服务，也支持通过Ollama接入本地模型。用本地模型的意义在于：数据不出机器、没有按token计费的压力、断网也能跑，代价是需要一台配置尚可的机器。
以把Qwen2.5-3B关联到OpenClaw为例，配置是这样的：
model: provider: ollama base_url: http://127.0.0.1:11434/v1 api_key: ollama model_name: qwen2.5:3b temperature: 0.4 max_tokens: 2048 stream: falseprovider填ollama，base_url指向Ollama服务的地址。因为Ollama提供了OpenAI兼容接口，所以api_key这一项随便填一个非空字符串即可，很多实现里填ollama就能通过校验。model_name必须与Ollama里实际拉取的模型标签一致，比如qwen2.5:3b，写错了会直接报model not found。temperature建议从0.4开始调，别一上来就用默认值。max_tokens要留意：3B模型的上下文窗口有限，填2048在多数场景下够用，填太大反而可能在长对话时爆上下文。
如果选云端API，provider就换成对应的服务商名称，填上真实的api_key。此时要注意base_url通常由官方SDK自动处理，不填反而更稳，手动填错多一个斜杠都会导致404。顺便说一句，用云端模型时rps_limit这个参数值得关注，它限制每秒请求数，防止并发任务多时把账号请求额度瞬间打满。本地模型通常不需要限流，你的瓶颈在显卡算力，不在接口配额。
2.3 技能与工具参数：配好OpenClaw的“手脚”
OpenClaw的skill机制是它区别于普通聊天机器人的关键。skill可以理解为Agent的“手脚”：一段脚本、一个命令行工具、一个外部API封装，都可以作为技能加载。主配置文件里负责这部分的是skills块。
skills: enabled: true auto_load: true timeout: 30 paths: - ./skills allowlist: [] denylist: []enabled是总开关，auto_load决定启动时是否自动扫描技能目录。如果你有很多技能但只想用一部分，就把auto_load设为false，然后在allowlist里逐个列出技能名。这里有个安全考量：allowlist和denylist不是摆设。OpenClaw的技能一旦被调用，就拥有与主进程相当的权限，所以涉及文件删除、网络请求、系统命令等高危操作的技能，我建议默认不加载，真正需要时再在allowlist里显式开启。
timeout给每个技能调用设置了超时上限，单位秒。有些技能比如调用外部API，可能因为网络原因迟迟不返回，没有超时控制的话整个任务会一直卡住。max_concurrent控制技能并发数，默认值一般够用，但如果你的技能里有大量IO操作，可以适当调高；如果技能里跑的是CPU密集型任务，调太高反而把主进程拖垮。
技能的目录结构也有讲究。每个技能通常是一个独立文件夹，里面包含描述文件（说明技能用途和参数）和实现文件。主配置里的paths只负责指向技能根目录，具体加载哪些技能由描述文件决定。技能命名不要用中文，不排除新版本已经修复，但我在某些系统上确实遇到过中文路径导致的编码问题，用英文命名省心得多。
2.4 运行、并发与外部桥接参数
runtime块解决的是“Agent怎么跑”的问题。max_concurrency控制同时处理的任务数量，你可以把它理解为餐厅的桌位数：桌位太少，客人排队；桌位太多，厨师忙不过来。默认值通常比较保守，如果你跑的是本地模型，并发太高会导致显存溢出，建议从1或2开始往上加，观察显存占用再定。task_timeout是单个任务的超时时间，和技能的timeout不同，这个管的是整个任务链路，防止模型推理或技能组合流程整体卡死。
OpenClaw的channels块也很关键，它决定外部世界怎么联系Agent。最基础的是local通道，也就是在终端里直接对话，适合测试。Windows下用的桌面伴侣程序对应companion通道，需要设置channels.companion.enabled和通信端口。此外还有Telegram、WebSocket等通道，每类通道的参数大同小异，核心是enabled开关、认证token、回调地址。
如果你打算把OpenClaw接到机器人仿真环境，比如ROS2 Humble加Gazebo的组合，需要关注的是channels.ros2或transport.bridge_url这类桥接参数。OpenClaw在这个场景里通常扮演决策层，通过WebSocket或消息总线把决策指令发给仿真环境。此时bridge_url不要填127.0.0.1，如果仿真是独立容器或另一台机器，必须填实际可达的地址，否则指令发不出去。这块配置看似边缘，但真做具身智能实验的人会天天跟它打交道。
3. 实操部署：从零配置一份能用的主配置
3.1 Windows环境部署与配置文件的“正确位置”
Windows下部署OpenClaw，最常见的方式是先装WSL2，在里面跑Linux环境，因为OpenClaw的依赖对Linux的支持最完整。先确认Node.js已安装，建议用LTS版本，去官网下载安装包即可。接着在PowerShell里执行：
wsl --status这个命令用来检查WSL2的状态。如果你看到类似“无法安全验证”或者发行版状态异常的提示，通常是因为WSL内核组件没更新或者发行版没有完成初始化，执行一下wsl --update，然后重启终端就可以了。这套流程本身不复杂，但很多人卡在这一步就开始怀疑人生，实际上只是WSL版本太老。
进入Ubuntu子系统之后，把OpenClaw仓库克隆到本地，进入项目根目录执行依赖安装。安装完先跑一遍初始化命令生成配置模板，它会在当前用户的home目录下创建.openclaw文件夹，主配置文件一般位于~/.openclaw/openclaw.yaml。这里有个小坑：生成模板时如果当前目录没有写权限，初始化会静默失败或者把文件写到别的地方。我吃过这个亏，建议初始化前先确认路径权限。
3.2 一份最小可用配置，以及如何验证它
配置模板生成后，不要急着堆参数，先写一份最小配置把链路跑通。以下配置可以直接用，模型部分以本地Ollama为例，先把ollama pull qwen2.5:3b执行完再启动：
agent: name: my-agent system_prompt: "你是一个乐于助人的助手，回答尽量简洁。" language: zh-CN timezone: Asia/Shanghai model: provider: ollama base_url: http://127.0.0.1:11434/v1 api_key: ollama model_name: qwen2.5:3b temperature: 0.3 max_tokens: 1024 skills: enabled: true auto_load: true timeout: 30 paths: - ./skills runtime: max_concurrency: 2 task_timeout: 60 channels: local: enabled: true然后执行：
openclaw config validate这个命令会检查配置文件格式和必填项。之后再用openclaw config show查看实际生效的配置，确认模型参数和技能目录已经被正确加载。一切正常就启动：
openclaw start --config ~/.openclaw/openclaw.yaml第一次跑的时候，建议把max_tokens控制在512到1024之间。说实话，刚开始调试阶段模型根本不需要回复长文，调小一点既能省显存，也能让首响应变快。链路跑通之后再逐步放大，比一开始就把参数拉满然后遇到各种奇怪问题要好处理得多。
3.3 手机Termux部署时配置文件的差异
有人想在安卓手机上通过Termux部署OpenClaw，这在“轻量使用”和“尝鲜”场景下完全可行。先安装Termux，然后在里面装Node.js和Git，再按官方步骤安装OpenClaw。配置文件的格式和内容与服务器端基本一致，差异主要在两点：一是模型推荐用本地Ollama或者远程API，手机本地跑大模型受硬件限制比较明显；二是通道配置不要开公网入口，用local通道就够了，最多加一个WebSocket供局域网内调试。
配置文件的存放路径同样是~/.openclaw/openclaw.yaml，编辑工具直接使用Termux里的vim或nano。有一个经验值得分享：安卓后台进程容易被系统回收，OpenClaw跑在Termux里会被杀掉，建议配合tmux会话运行，或者用Termux自身的服务管理机制让进程常驻。不然你配置得再完美，手机锁屏半小时后进程就没了，体验非常糟糕。
4. 常见问题与排查技巧实录
4.1 改完配置不生效：先确认优先级和生效机制
这是问得最多的一类问题。典型的场景是：我把model.temperature从0.7改成了0.2，重启服务后测了几次，感觉生成结果还是那么“飘”，仔细一查发现配置根本没生效。原因通常有三个：一是启动时指定了另一份配置文件，你改的是模板文件，不是实际加载的那份；二是环境变量覆盖了你配置里的值；三是进程没有真正重启，旧配置还驻留在内存里。
排查方法和思路比背参数更重要。第一，执行openclaw config show，看程序实际读到的参数是什么，和你的预期是否一致；第二，检查启动命令里有没有通过环境变量或命令行参数覆盖配置；第三，改完配置后彻底停止进程再启动，而不是热重载糊弄过去。如果这三个点都排除了还是不生效，再考虑配置文件是否因为语法错误被静默忽略。记住OpenClaw的层级优先级：命令行参数 > 环境变量 > 配置文件 > 内置默认值，以后遇到“不生效”的问题，心里先过一遍这条链。
4.2 “配置文件为空”与默认值陷阱：必填项不能省
有朋友遇到过“项目参数文件为空”的报错，其实不是整个文件真的一片空白，常见情况是模板生成后很多字段缺失或为空，程序没报错，直接套用了默认值。比如agent.name没填，多个任务之间可能出现会话串号；model.provider没填，程序会连默认provider，然后因为没配对应key而反复报错。OpenClaw对缺失的处理策略偏“宽容”，这既是优点也是坑。
我的建议是：至少把三类必填项补齐再启动：agent.name、model.provider、model.model_name。其它参数可以先不填，但这三个缺失会导致系统行为不可控。还有人说“界面里没有自定义参数栏”，看不到某个参数设置选项。这不代表功能不存在，而是因为主配置里大量参数并没有暴露在UI面板中，需要直接编辑YAML文件，改完再重启。这类参数比如各种超时阈值、技能白名单、底层流式开关，都属于“配置文件专属”，别指望在面板里找到。
4.3 模型调用失败：参数对不上的典型报错
模型调用失败是部署初期的重灾区，通过观察报错信息可以快速定位。
| 报错特征 | 大概率原因 | 处理办法 |
|---|---|---|
| 401 Unauthorized | api_key错误或缺失 | 检查配置里api_key是否填了有效值 |
| 404 Not Found | base_url多/少斜杠，或model_name错误 | 校准base_url，核对模型标签 |
| model not found | Ollama里没有拉取该模型 | 执行ollama pull qwen2.5:3b |
| context length exceeded | max_tokens超出模型上下文限制 | 调小max_tokens或开启上下文裁剪 |
| timeout | 网络不通或模型推理太慢 | 检查网络，调大task_timeout，换小模型 |
特别提一下本地Ollama场景：很多人把base_url填成http://127.0.0.1:11434，漏了末尾的/v1，OpenClaw走的是OpenAI兼容接口，路径后缀必须匹配。还有api_key这一项，虽然Ollama默认不校验，但OpenClaw的客户端库通常要求非空，填一个ollama占位即可。
4.4 Windows Companion 与扩展场景的配置注意点
如果要使用Windows桌面伴侣程序，主配置里要显式开启对应通道。常见配置是：
channels: companion: enabled: true port: 8765 token: "换成一段足够长的随机字符串"token是伴侣程序与主服务之间的认证凭证，必须设置，而且要足够随机。不要图省事写123456，否则局域网内任何能连到该端口的人都能直接操作你的Agent。设置完成后，桌面伴侣在连接时填写对应的端口和token，就可以把OpenClaw变成一个有图形窗口的本地助手。
接ROS2仿真时还需要注意一点：bridge_url要填仿真环境实际可达的地址。Gazebo跑在本机，填localhost没问题；如果Gazebo跑在Docker容器里，要填宿主机在容器网络中的IP；如果仿真是独立机器，就填那台机器的局域网IP。为了排查这类问题，我习惯先把advanced.debug开关打开，这样桥接层的收发消息会打到日志里，能确认指令到底有没有发出去、发到了哪里。
配置OpenClaw主配置文件，说到底是把一个复杂Agent系统收敛成几个清晰的决策：身份怎么定、大脑用什么、手脚有哪些、门开在哪里。我自己实际用下来体会最深的一点是：配置要从小到大慢慢加，先让它能说话，再让它做事情，最后才谈得上并发和优化。一头扎进参数海洋里，反而容易迷失。
最后分享一个小技巧：把已经调通的主配置提交到Git仓库里，每次改动前先commit，出问题可以快速回滚；同时准备一个base.yaml作为公共模板，本机差异用环境变量覆盖，这样多台设备的配置统一管理，既不重复也不混乱。你按这份文档把配置逐行捋一遍，遇到问题先看生效优先级，再用config show确认实际值，绝大多数坑都能躲过去。
