第1课 OpenClaw 配置文件#

为什么需要了解这个#

当你刚开始使用 OpenClaw 时，一切都"开箱即用"——使用默认设置。但迟早你会想要修改一些东西：连接聊天工具、选择其他 AI 模型、设置定时任务。为此存在一个配置文件——一个保存了所有助手参数的文件。

就像一个遥控器：一个文件——你就能控制 OpenClaw 的所有行为。

什么是 openclaw.json#

openclaw.json 是一个 JSON5 格式的文本文件（增强版 JSON，允许写注释和在最后一个元素后面加逗号）。它描述了所有设置：连接了哪些聊天工具、使用哪个 AI 模型、哪些工具可用等等。

它在哪里#

文件位于：

~/.openclaw/openclaw.json

~ 是什么意思？ 这是你用户"主目录"的缩写。在 Mac 上是 /Users/你的用户名/，在 Linux 上是 /home/你的用户名/。

如果文件不存在——这是正常的！OpenClaw 会使用默认设置运行。

如何编辑设置#

你有四种方式修改设置。选择你觉得最方便的：

方式1：设置向导（最简单）#

在终端中运行：

openclaw onboard

这是一个交互式助手，会问你问题并自动创建正确的配置文件。

要快速配置特定部分：

openclaw configure

方式2：终端命令（一行搞定）#

如果需要修改某个具体设置：

# 查看当前值
openclaw config get agents.defaults.workspace

# 设置新值
openclaw config set agents.defaults.heartbeat.every "2h"

# 删除设置
openclaw config unset tools.web.search.apiKey

方式3：网页界面#

在浏览器中打开：

http://127.0.0.1:18789

进入 Config 标签页——那里有方便的表单和字段，以及"原始" JSON 编辑器。

方式4：直接编辑文件#

用任何文本编辑器打开 ~/.openclaw/openclaw.json 文件，修改所需的参数。

配置文件长什么样#

以下是一个最小配置文件的示例：

// ~/.openclaw/openclaw.json
{
  // 智能体设置
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace"
    }
  },

  // 连接聊天工具
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"]
    }
  }
}

注释（以 // 开头的行）是给你看的提示。OpenClaw 会忽略它们。

热重载——这是什么，怎么工作#

热重载（hot reload）是指 OpenClaw 自动检测到你修改了配置文件，并无需重启就应用更改。你不需要停止再重新启动程序！

重载模式#

哪些更改立即生效（无需重启）#

• 聊天工具设置 (channels)
• 智能体和模型设置 (agents, models)
• 自动化 (hooks, cron, heartbeat)
• 会话和消息
• 工具和媒体

哪些更改需要重启#

• Gateway 服务器设置 (gateway.* —— 端口、地址、认证)
• 基础设施 (discovery, plugins)

环境变量#

你可以使用环境变量来代替在配置文件中直接写入密钥——它们是单独存储的特殊命名值。

OpenClaw 从以下位置读取环境变量：

• 当前文件夹中的 .env 文件
• ~/.openclaw/.env 文件

在配置中使用的示例：

{
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}"
    }
  }
}

这里 ${OPENCLAW_GATEWAY_TOKEN} 会被替换为环境变量的实际值。

检查配置#

如果你在配置文件中犯了错误，OpenClaw 不会启动，并会显示具体哪里出了问题。要查找和修复问题：

# 显示问题
openclaw doctor

# 自动修复
openclaw doctor --fix

本课总结#

• openclaw.json 是 OpenClaw 的主配置文件，位于 ~/.openclaw/
• 有 4 种编辑方式：向导、命令、网页界面、直接编辑
• 热重载允许大多数设置无需重启即可更改
• 密钥最好保存在环境变量中（.env 文件）
• 如果出了问题——openclaw doctor 会帮你找到并修复错误

下一课：选择 AI 模型