OpenClaw配置文件完全拆解：参数详解、模板与排错速查

如果你已经在 Docker 或者 WSL 里把 OpenClaw 跑起来了，大概率会卡在同一个地方：文档让你改 config.json，社区教程也喊你改 config.json，但这份主配置文件里到底有哪些参数，每个参数分别管什么，却很少有人一次讲清楚。我从一次次翻配置、改配置、踩坑的过程里，把 OpenClaw 主配置文件的常用参数整理成了一份比较完整的清单，这篇就专门讲它：结构长什么样、参数怎么理解、一份能直接抄的模板，以及高频报错怎么排查。

适合看这篇的人很明确：正在部署 OpenClaw 的开发者，想把模型从在线 API 切换到本地 Ollama 的折腾党，把 OpenClaw 当机器人或者个人助理大脑、准备接 Slack、ROS2、智能家居的玩家。新手照着核对字段，基本不会改错；老手可以把后面那张问题速查表当手册用。

1. 在动手改配置之前，先搞清楚主配置文件到底管什么

1.1 主配置文件、技能文件、环境变量，三者各司其职

OpenClaw 的配置体系不是只有主配置文件这一层。我更喜欢用一个人来打比方：主配置文件是“中枢神经系统”，技能文件是“肌肉记忆”，环境变量是“外部插座”。

中枢神经系统决定了这个助手叫什么、有什么性格、默认用哪个模型、记忆怎么存、通过哪些渠道跟人说话、日志写到哪；肌肉记忆是 skills/ 目录下一份份带格式说明的 Markdown 文件，里面写着某个具体动作的触发条件、参数和操作步骤；外部插座则是部署时传入的 API Key、监听端口、数据目录这些和具体机器绑定的东西。三者的修改频率完全不同，主配置改得最勤，技能文件按需新增，环境变量基本只在部署阶段动。

理解了这个分层，遇到问题就多了一条判断路径：想让 OpenClaw 换个“人设”，改主配置里的 agent 块；想让 OpenClaw 学会一个具体操作，去写技能文件而不是改配置；想换一台机器部署，备份主配置和数据目录就够了。很多新手的误区是“什么东西都往主配置里塞”，最后配置文件变得又臭又长，一个 JSON 括号错了，整个服务起不来。

1.2 根级字段速览：一张表看懂配置骨架

不同版本的 OpenClaw 字段名可能会有细微差异，但根级结构大致是稳定的。我按实际使用频率列一张表，改配置之前先对着它找位置：

表格只是骨架，真正容易出问题的是每个块内部的具体键，后面我会逐块拆。第一段话先说结论：主配置文件本质上是“给 Agent 写的一份综合说明书”，它不存技能的具体实现，不存太多机器相关的东西，只做行为定义和资源接线。

1.3 改完配置怎么让它生效

配置文件不是改完保存就立刻生效。我遇到过不少用户在配置文件里加了半天参数，一问服务没重启，自然一点变化都没有。这里要看你的部署方式：

• Docker 部署：改完宿主机挂载出来的配置文件后，执行 docker restart <container>，容器内的进程才会重新读取；
• 二进制或源码部署：直接重启 openclaw 进程，或者向进程发送 SIGHUP 信号（部分版本支持热加载，但别赌这个）；
• 云平台部署：先确认挂载卷路径和配置文件路径一致，再重启服务。

比较稳妥的做法是：改完配置先做一次 JSON 语法校验，再重启，然后立刻看日志开头有没有“config loaded”之类的关键字。很多诡异问题都是“改了 A 文件，但程序读的是 B 文件”，排查时先用日志确认程序实际加载的路径。

2. 主配置文件参数逐项拆解：从身份到模型，再到工具

2.1 agent 块：名字、人格、系统提示词怎么配才不像机器人

agent 块是最有“产品感”的部分。我常用的结构是这样的：

json复制{
  "agent": {
    "name": "openclaw",
    "displayName": "小爪",
    "aiName": "OpenClaw",
    "description": "一个低调务实的个人助理",
    "systemPrompt": "你叫小爪，回答要简洁直接，默认用中文，不要客套，不要编造事实。",
    "personality": "简洁、直接、可靠",
    "knowledge": ["用户偏好：喜欢短回答", "工作场景：开发调试"]
  }
}

这里有几个重点要解释。name 是内部标识，一般用小写字母和下划线，最好别乱改，很多技能和日志会引用它；displayName 是展示给用户看的名字；aiName 则是在对话里 Agent 自我认知的名字。systemPrompt 是整份配置里性价比最高的参数，它直接决定 OpenClaw 的性格边界，写得好不好，比换模型还影响体验。

我的经验是系统提示词别写太长，更别写成万字小作文。OpenClaw 本身已经有基础行为模板，你在 systemPrompt 里只需要补充“这个场景下特有的要求”，比如回答长度、默认语言、需要规避的动作。写多了反而会占用上下文窗口，还会让模型在关键任务上失焦。personality 和 knowledge 不是所有版本都读取，但它们社区认可度很高，本质上是用结构化键值在辅助模型理解场景。

2.2 model 与 provider 块：模型路由、温度、长度、API 密钥

model 和 providers 经常放在一起说，一个负责“当前用谁”，一个负责“怎么连上谁”。我的最小配置长这样：

json复制{
  "model": {
    "provider": "anthropic",
    "name": "claude-sonnet-4-20250514",
    "temperature": 0.7,
    "maxTokens": 4096,
    "topP": 0.9,
    "stop": ["</answer>"]
  },
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-..."
    },
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "defaultModel": "qwen2.5:3b"
    }
  }
}

temperature 控制随机性，0.2 左右适合做工具调用和结构化输出，0.7 到 0.9 适合聊天和创意内容。maxTokens 是单次生成的最大 token 数，不是上下文窗口，别把它设得比模型上下文还大，否则接口会直接 400。stop 可以传字符串数组，模型生成到指定标记就会停下来，适合做流式输出时的结构化截断。

providers 支持多种模型服务，官方生态里 Anthropic 是默认，但也支持 OpenAI 兼容接口和 Ollama 这类本地服务。所以“OpenClaw 只能用接入 API 的方式使用算力吗”这个问题的答案是：不是。只要配置 ollama.baseUrl，再在 model.provider 里写 ollama，就能把本地模型接进来，后面我会给完整示例。这里需要提醒的是 API Key 别直接写进 Git 仓库，敏感配置建议用环境变量引用，例如 "apiKey": "${ANTHROPIC_API_KEY}"，很多版本支持这种占位写法。

2.3 memory 与 context 块：开多久、存多少、哪些该留

记忆是 OpenClaw 和普通脚本机器人拉开差距的地方。我的配置习惯是这样：

json复制{
  "memory": {
    "enabled": true,
    "backend": "sqlite",
    "maxEntries": 512,
    "summaryThreshold": 200,
    "vectorStore": {
      "enabled": false
    }
  }
}

enabled 是总开关，关掉之后 OpenClaw 每一轮对话都像第一次见面，适合完全隐私的场景。backend 是存储方式，本地部署常见 sqlite，数据就落在本地一个文件里；如果跑在云端，也可以接数据库服务。maxEntries 控制长期记忆最多保留多少条，超过之后会按策略淘汰旧条目，数值太大会拉高检索延迟，太小则什么都记不住。

summaryThreshold 值得单独说：当对话轮次或记忆条目超过这个阈值，OpenClaw 会触发摘要压缩，把旧对话浓缩成更短的内容，避免上下文被历史对话塞爆。这个参数非常实用，尤其你让它全天挂着、一直不重启时。vectorStore 是向量检索的开关，适合需要精确查“很久以前说过的一句话”的场景，但第一次用不建议开，因为要先构建索引，而且会明显增加资源占用。

2.4 skills 与 mcp 块：让 OpenClaw 有手有脚

技能是 OpenClaw 最灵活的部分。主配置里的 skills 块通常这样写：

json复制{
  "skills": {
    "enabled": true,
    "path": "./skills",
    "autoLoad": true,
    "permissions": {
      "allow": ["*"],
      "deny": ["shutdown", "rm"]
    }
  }
}

path 告诉 OpenClaw 去哪里找技能文件；autoLoad 决定启动时是否自动加载目录下所有技能。技能文件本身的格式是在 Markdown 顶部写一段 frontmatter，声明名称、描述、触发器、参数，然后在正文里写具体的执行逻辑。主配置只负责开关和权限，所以“技能不生效”时别急着改主配置，先看技能文件本身的 frontmatter 写没写对。

mcp 块里面配置的是外部服务器列表，全称是 Model Context Protocol，也就是一种让 Agent 调用外部工具的统一协议。典型配置：

json复制{
  "mcp": {
    "servers": [
      {
        "name": "home-assistant",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-home-assistant"]
      }
    ]
  }
}

每一个 MCP 服务器都是一个独立进程，OpenClaw 通过标准输入输出和它通信。想接智能家居、文件系统、数据库甚至 ROS2 机器人仿真，本质都是在 mcp.servers 里加一项，然后在技能文件里写明怎么用这个工具。我建议外部 MCP 服务器能少则少，每多一个进程，故障面和资源占用都会增加。

2.5 channels 块：把 OpenClaw 接到 Slack、Discord、本地终端

channels 负责消息渠道。我用过的配置模板：

json复制{
  "channels": {
    "slack": {
      "enabled": true,
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "autoJoin": true
    },
    "discord": {
      "enabled": false,
      "botToken": "..."
    },
    "terminal": {
      "enabled": true
    }
  }
}

每个渠道都靠 Token 鉴权。Slack 需要 Bot Token 和 App Token，一个用于发消息，一个用于接收 Socket Mode 事件；Discord 只用 Bot Token。autoJoin 决定机器人要不要自动加入新出现的频道，一般开发阶段建议关掉，避免在群里乱说话。terminal 是在人机交互界面上用的渠道，适合本地调试，一般默认开着就好。

这里有一条非常实用的经验：Token 不要直接出现在主配置文件里，因为主配置文件经常被拿去复制、分享、贴到 issue 里。把它改成 ${SLACK_BOT_TOKEN} 这种环境变量占位符，然后通过系统的环境变量传入，泄露风险会低很多。

2.6 logging 与 security 参数：排查用的灯，安全用的锁

日志参数平时不起眼，排查问题的时候就是命根子：

json复制{
  "logging": {
    "level": "debug",
    "format": "text",
    "file": "./logs/openclaw.log"
  },
  "security": {
    "allowedDomains": ["localhost"],
    "sandboxedSkills": true
  }
}

logging.level 从 error、warn、info、debug 到 trace，级别越高信息越细。我通常平时用 info，遇到问题临时改成 debug，查完立刻改回来，因为 debug 级别会写非常多的日志，磁盘占用很快。format 可以是文本也可以是 JSON，如果你后面想接日志采集系统，用 JSON 格式解析更省事。security.allowedDomains 限制 Agent 对哪些域名发请求，用于防止技能意外访问外网；sandboxedSkills 开启后，第三方技能会在受限环境里执行，这一点尤其重要，因为你不知道从社区下载的技能里写了什么命令。

3. 从零配好一份能跑的 OpenClaw：我常用的配置模板

3.1 最小可用配置：JSON 示例加逐行说明

如果你现在就要一份“改完就能启动”的配置，我给出下面这版。它不花哨，但足够跑通基础对话、技能加载和日志输出：

json复制{
  "agent": {
    "name": "openclaw",
    "displayName": "OpenClaw",
    "aiName": "OpenClaw",
    "systemPrompt": "你是 OpenClaw，回答简洁，默认中文。"
  },
  "model": {
    "provider": "anthropic",
    "name": "claude-sonnet-4-20250514",
    "temperature": 0.7,
    "maxTokens": 4096
  },
  "providers": {
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}"
    }
  },
  "channels": {
    "terminal": {
      "enabled": true
    }
  },
  "skills": {
    "enabled": true,
    "path": "./skills"
  },
  "logging": {
    "level": "debug",
    "file": "./logs/openclaw.log"
  }
}

这份配置里没有记忆、MCP、定时任务，只保证最核心的链路能跑通。启动后你应该先看到终端渠道起来，再用一句话测试对话。注意 providers.anthropic.apiKey 用了环境变量占位，启动前需要把 ANTHROPIC_API_KEY 设置到环境里；如果你在 Windows 上跑，可以用 PowerShell 执行 $env:ANTHROPIC_API_KEY="sk-ant-..." 再启动。

3.2 把本地 Ollama 与 Qwen2.5-3B 接进来，不依赖任何“云端算力”

很多人纠结 OpenClaw 是不是必须用在线 API。实际操作完全支持本地推理，我用 Ollama 跑过 Qwen2.5-3B，配置起来并不复杂。

第一步，安装 Ollama 并拉取模型，例如 ollama pull qwen2.5:3b；第二步，确认 Ollama 的接口地址，默认是 http://localhost:11434/v1，这个地址符合 OpenAI 兼容格式；第三步，在主配置里把 provider 和 model 指过去：

json复制{
  "model": {
    "provider": "ollama",
    "name": "qwen2.5:3b",
    "temperature": 0.3,
    "maxTokens": 2048
  },
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1"
    }
  }
}

这样 OpenClaw 的所有对话推理就都跑在了本地，数据不出机器。它的代价也很明显：3B 模型在复杂任务上的理解能力比大模型弱不少，工具调用容易翻车，适合日常简单问答，不适合那种高强度 Agent 任务。如果要跑更大的 7B、14B 模型，需要保证 CPU 和内存足够，否则响应速度会让你怀疑人生。我的建议是：把本地 Ollama 作为备用 provider，日常用在线模型，网络不可用时切到本地，而不是一上来就全本地。

3.3 Windows / WSL 部署时，配置文件的位置与挂载

Windows 下部署 OpenClaw，我的建议是本体放进 WSL，配置文件也放 WSL 侧，不要放在 C:\Users\... 下面让 Windows 进程直接读。原因很简单：两个文件系统的路径风格不同，Node 生态里经常有模块要解析绝对路径，在 Windows 下用 C:\xxx 路径，到 WSL 里就认不出来了。

很多人在 PowerShell 里会碰到“OpenClaw 无法安全验证 WSL 环境，请在 PowerShell 中运行 wsl -- status”这样的提示。这个报错本身不难处理，按顺序排查即可：

1. 打开 PowerShell，执行 wsl --status，看 WSL 内核版本和默认版本；
2. 如果版本太旧，执行 wsl --update 更新内核；
3. 执行 wsl --shutdown，然后重新进入 WSL 终端；
4. 确认默认版本是 2，如果还是 1，执行 wsl --set-default-version 2。

这个报错通常会连带导致 OpenClaw 起不来，因为它在启动阶段要探测 WSL 环境。配置文件挂载方面，用 Docker 部署时注意把 ./config.json 映射到容器里的 /app/config.json，路径一旦不一致，你改半天宿主机文件，容器里读的还是旧配置。

3.4 在 ROS2 / Gazebo 环境下做扩展

OpenClaw 这类助手在机器人仿真里有个很有意思的玩法：把它接到 ROS2 和 Gazebo 环境里，让它能感知仿真器的状态。社区里已经有 rosclaw 之类的尝试，核心思路不是改主配置，而是通过 MCP 服务器暴露 ROS2 接口，再写一个技能文件告诉 OpenClaw“你想知道机器人位置时，执行这条命令”。

配置层面你需要做两件事：在 mcp 里加一个 ROS2 相关的 MCP 服务器，或者在 skills.path 指向的目录里放一个调用 ros2 topic echo、ros2 service call 的技能文件。启动之后，OpenClaw 才能拿到仿真环境里的位姿、里程计、电池状态这些信息。不要指望主配置里有一个键叫 ros2，它没有，所有机器人扩展能力都来自工具和技能的组合。

4. 参数配错是常态：高频问题与排查经验

4.1 配置文件为空或启动直接报错怎么办

我见过太多“项目参数文件为空”的报错，第一反应别慌，先看两件事：文件大小是不是 0 字节，路径是不是被程序读错了。配置文件为空最常见的原因是安装脚本初始化失败，或者你复制模板时没保存成功。

第二步，做 JSON 语法校验。OpenClaw 主配置本质是 JSON，格式要求严格。很多教程会在示例里写注释，但严格模式下 JSON 不允许注释，复制进去就会解析失败。你可以用 Node.js 快速校验：

bash复制node -e "JSON.parse(require('fs').readFileSync('./config.json','utf8')); console.log('ok')"

如果校验报错，它会告诉你具体在哪一行。实际排查经验是：不要一次改太多键，每次只改一块，启动一次，确认前一块正常了再继续。配置文件一出错就要从最小可运行版本开始加回参数，这是最省时间的排错顺序。

4.2 模型请求失败：provider、baseUrl、apiKey 三件套

OpenClaw 能启动，但一对话就报错，90% 是模型请求那三件套没对准。第一个是 model.provider 和 providers 里的键名不一致，比如前面写了 provider: "anthropic"，后面的 provider 块里却叫 anthropic-api，自然是找不到。第二个是 baseUrl 写错，Ollama 的地址要带 /v1，漏掉就请求不到兼容接口。第三个是 apiKey 带了空格，或者环境变量没传进去。

再有一个坑是 maxTokens 设置得超过了模型上下文窗口。例如模型上下文只有 32768，你配了 "maxTokens": 100000，请求直接 400。正确的思路是先确认模型官方上下文的硬限制，然后把 maxTokens 控制在上下文窗口的一半以内，留出系统提示词和对话历史的余量。判断问题在哪一步，可以看日志：请求发出但超时，一般是地址问题；请求刚发出就返回 400，一般是参数问题；返回 401，则是密钥问题。

4.3 技能不加载、工具被拦，先查权限参数

“技能目录放了文件，但怎么喊都不触发”是很典型的问题。我在 2.4 里说过，先看技能文件本身：有没有 frontmatter，description 写没写清楚，触发条件够不够明确。Agent 是靠描述来决定什么时候调用技能的，如果描述模糊，它宁可不用。

排除了技能文件问题再看主配置：skills.enabled 是不是 true，skills.path 是不是指向了正确目录。还有一类问题藏得很深：skills.permissions.deny 里写了 ["*"]，可能是为了安全把所有命令都禁了，结果正常技能也被拦。排查办法很简单，把 logging.level 临时调到 debug，启动时看有没有加载技能的记录，调用时看有没有权限拦截日志。看到“skill not found”“permission denied”之类的关键字，再回配置里找对应键，比盲目试有效得多。

4.4 高频参数问题速查表

最后整理一份速查表，也是我平时排查时的备忘录：

这张表覆盖了我遇到过的绝大多数问题，但最后我还是想说一句：日志是最诚实的帮手。任何参数拿不准的时候，先开 debug 日志，看一次完整的启动过程，很多“看起来像玄学”的问题，其实就是路径、大小写、空格中的一个细节。

关于配置这件事，我最想说的其实是用“最小化原则”去管理它。我在实际项目里最开始恨不得把所有参数都填满，结果每次升级版本都要重新对照字段，维护成本极高。后来养成一个习惯：配置文件只放当前真正用到的块，用不到的保持默认，不写进 config；每块配置旁边留简短注释，但提交前记得把非标准 JSON 注释删掉；密钥一律用环境变量占位。这样无论是升级版本、迁移机器，还是把配置分享给同事，都会轻松很多。如果你正在配 OpenClaw，我建议你也从最小可用配置开始，跑通一条链路，再慢慢加记忆、加渠道、加技能。