学习目标

深入了解 OpenClaw 的配置系统，学会用多种方式精确控制小龙虾的行为，让它完全按你的想法工作。

概念解释

配置就像”小龙虾的工作手册”。你在这本手册里写清楚：用什么 AI 大脑、连哪些聊天工具、谁可以跟它聊天、能不能上网搜索……小龙虾就严格照着手册做事。

最妙的是——手册改了，小龙虾马上按新规矩来，不需要把它送回学校重新培训。这就是配置的威力：改一行字，效果立刻不同。

动手做

第一步：认识四种修改配置的方式

OpenClaw 提供了四种方式来修改配置，就像你可以用遥控器、手机 App、语音助手或者直接按电视按钮来换台一样——目的相同，方式不同：

方式	命令/操作	适合场景
交互式向导	openclaw configure	不确定要改什么，想一步步选
命令行单条修改	openclaw config set/get/unset	知道具体要改哪一项，精确快速
浏览器图形界面	打开 http://127.0.0.1:18789 的 Config 标签页	喜欢点点点的图形界面操作
直接编辑文件	用记事本打开 ~/.openclaw/openclaw.json	批量修改，或者想看看完整配置

四种方式改的都是同一个配置文件，效果完全一样。选你觉得最顺手的方式就行。

第二步：用 openclaw configure 修改配置（交互式向导）

如果你不确定配置项叫什么名字，用交互式向导最省心。它就像填表一样，一步步问你，你选就行：

openclaw configure

运行后，向导会引导你修改模型、渠道、网页搜索等配置。

如果只想改某一个部分，可以用 --section 参数指定：

openclaw configure --section model       # 只改模型配置
openclaw configure --section channels    # 只改渠道配置
openclaw configure --section web         # 只改网页搜索配置

这样就不会被其他配置项打扰，直奔主题。

第三步：用 openclaw config 命令精确控制

当你知道要改什么的时候，用命令行单条操作更快、更精确。

查看配置信息：

openclaw config file              # 看配置文件在哪里

这会告诉你配置文件的具体路径（通常是 ~/.openclaw/openclaw.json）。

openclaw config get agents.defaults.model.primary   # 看当前用的什么模型

就像查字典一样，输入”路径”，它返回对应的值。

修改单个配置项：

openclaw config set agents.defaults.model.primary "deepseek/deepseek-chat"

一句话搞定，不需要打开任何编辑器。

小贴士： 配置项的路径是用 . 连接的层级结构，比如 agents.defaults.model.primary，从左到右就像一层层打开文件夹。

验证配置是否正确：

openclaw config validate

这个命令会检查你的配置格式有没有写错。如果配置有语法问题，它会告诉你错在哪里。养成改完配置跑一下这个命令的好习惯。

删除一个配置项：

openclaw config unset agents.defaults.model.primary

删除后，该配置项会恢复为默认值。

查看完整的配置结构说明：

如果你不确定某个配置项的路径怎么写，可以查看官方文档的配置参考：https://docs.openclaw.ai/config

或者用这个命令验证你的配置是否合法：

openclaw config validate

第四步：了解配置文件的结构

虽然大部分时候用命令行操作就够了，但了解一下配置文件长什么样，遇到问题时心里有底。

用记事本打开 ~/.openclaw/openclaw.json，你会看到类似这样的结构：

{
  // Agent（AI 助手）配置
  agents: {
    defaults: {
      model: { primary: "deepseek/deepseek-chat" },  // 主模型
      workspace: "~/.openclaw/workspace",              // 工作目录
    },
  },

  // 渠道配置
  channels: {
    telegram: {
      botToken: "你的token",
      dmPolicy: "open",
    },
  },

  // Gateway（网关）配置
  gateway: {
    port: 18789,   // 端口号
  },
}

几个要点：

• 文件格式是 JSON5，跟普通 JSON 类似，但支持注释（用 //）和更灵活的写法
• 顶层分为几个大块：agents（AI 助手）、channels（渠道）、gateway（网关）、skills（技能）等
• 每个大块下面还有更细的配置项，层级关系用缩进表示

不需要全部记住！ 大部分时候用 openclaw configure 向导或 openclaw config set 命令就行。了解文件结构主要是为了出问题时能看懂、能排查。

第五步：配置热重载——改了立刻生效

这是 OpenClaw 配置系统最贴心的设计：修改配置文件后，Gateway 会自动检测并热重载（Hot Reload），不需要重启！

打个比方：就像你在餐厅改了菜单，服务员会自动拿新菜单去点菜，不需要关门重新开张。

改了以下内容 → 立即生效，不用重启：

• 换 AI 模型
• 修改渠道配置（比如 Telegram 的设置）
• 添加或删除 Skill
• 调整网页搜索设置

改了以下内容 → 需要重启 Gateway 才能生效：

• 修改端口号
• 修改认证方式

如果不确定改完是否需要重启，可以运行：

openclaw gateway status

它会告诉你当前 Gateway 的运行状态。

如果改坏了配置导致启动失败怎么办？ 别慌，运行：

openclaw doctor              # 诊断问题，像医生一样帮你找病因
openclaw config validate     # 检查配置格式是否正确

openclaw doctor 会自动检测常见问题并给出修复建议。config validate 会精确告诉你配置文件哪一行写错了。两个命令配合使用，基本能解决所有配置问题。

常用的 config 命令速查

你想做什么	终端命令
打开交互式配置向导	openclaw configure
只改模型配置	openclaw configure --section model
只改渠道配置	openclaw configure --section channels
看配置文件在哪	openclaw config file
查看某个配置项的值	openclaw config get <路径>
修改某个配置项	openclaw config set <路径> <值>
删除某个配置项	openclaw config unset <路径>
检查配置格式	openclaw config validate
查看完整配置结构	openclaw config schema
诊断问题	openclaw doctor

检查你的成果

完成以上练习后，你应该做到：

• 能用 openclaw config get 查看任意配置项的值
• 能用 openclaw config set 修改单个配置项
• 知道配置文件在哪里（~/.openclaw/openclaw.json）
• 知道大部分配置修改后不需要重启（热重载）
• 知道配置出问题时该用哪些命令排查

常见失败排查

1. config set 报错”路径不存在”

原因： 配置项的路径拼写错误，或者这个配置项在当前版本中不存在。

解决： 运行 openclaw config schema 查看完整的配置结构，确认正确的路径写法。注意路径中的每个层级要用 . 连接，拼写要完全匹配。

2. 改了配置但没生效

原因： 大部分配置会热重载，但有些需要重启 Gateway。

解决： 先运行 openclaw gateway status 查看 Gateway 状态。如果你改的是端口号或认证方式，需要重启 Gateway。如果是其他配置，等待几秒让热重载完成。

3. 配置文件格式错误导致启动失败

原因： 手动编辑配置文件时，JSON5 格式写错了（比如漏了逗号、多了引号、括号不匹配）。

解决： 运行 openclaw config validate，它会精确告诉你哪一行、哪一列出了问题。修复后再次验证。如果不确定怎么修，可以用 openclaw configure 向导重新设置，它会自动生成正确格式的配置。

挑战任务

用 openclaw config get agents.defaults.model.primary 查看当前使用的模型，然后用 openclaw config set 把模型切换成另一个模型（比如从 deepseek/deepseek-chat 切换到 openai/gpt-4o-mini）。切换完成后，打开浏览器控制台（http://127.0.0.1:18789），发一条消息，验证新模型是否已经生效。