聊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填ollamabase_url指向Ollama服务的地址。因为Ollama提供了OpenAI兼容接口所以api_key这一项随便填一个非空字符串即可很多实现里填ollama就能通过校验。model_name必须与Ollama里实际拉取的模型标签一致比如qwen2.5:3b写错了会直接报model not found。temperature建议从0.4开始调别一上来就用默认值。max_tokens要留意3B模型的上下文窗口有限填2048在多数场景下够用填太大反而可能在长对话时爆上下文。如果选云端APIprovider就换成对应的服务商名称填上真实的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 Unauthorizedapi_key错误或缺失检查配置里api_key是否填了有效值404 Not Foundbase_url多/少斜杠或model_name错误校准base_url核对模型标签model not foundOllama里没有拉取该模型执行ollama pull qwen2.5:3bcontext length exceededmax_tokens超出模型上下文限制调小max_tokens或开启上下文裁剪timeout网络不通或模型推理太慢检查网络调大task_timeout换小模型特别提一下本地Ollama场景很多人把base_url填成http://127.0.0.1:11434漏了末尾的/v1OpenClaw走的是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确认实际值绝大多数坑都能躲过去。