基础配置详解

OpenClaw 的配置文件是 ~/.openclaw/openclaw.json，JSON 格式。

运行 openclaw onboard 向导会自动生成初始配置。

1. 文件目录结构

bash

~/.openclaw/
  openclaw.json       # 主配置文件
  workspace/          # 默认工作空间（Agent 行为文件）
    AGENTS.md
    SOUL.md
    USER.md
  workspace-work/     # 多 Agent 时的其他工作空间
  knowledge/          # RAG 知识库文档
  logs/               # 日志文件

2. 最小可用配置

json

{
  "models": {
    "defaults": {
      "model": "anthropic/claude-sonnet-4-5"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456789:ABCdef..."
    }
  }
}

3. 完整配置结构速查

json

{
  "models": {
    "defaults": { "model": "anthropic/claude-sonnet-4-5" }
  },
  "agents": {
    "defaults": {
      "heartbeat": { "every": "30m" },
      "requestTimeout": 120000,
      "maxRetries": 3
    }
  },
  "channels": {
    "telegram": { "enabled": true, "botToken": "xxx" }
  },
  "cron": { "enabled": true, "maxConcurrentRuns": 2 },
  "browser": { "enabled": true, "defaultProfile": "openclaw" },
  "gateway": { "port": 18789, "host": "127.0.0.1" },
  "dashboard": { "enabled": true },
  "messages": { "responsePrefix": "[{model}] " }
}

除 models.defaults.model 外，其他字段都有默认值，加什么改什么。

4. 敏感信息管理

不要把 API Key 直接写在 JSON 里。用环境变量引用：

json

{
  "models": {
    "providers": {
      "my-provider": {
        "apiKey": "${MY_API_KEY}"
      }
    }
  }
}

设置环境变量后，配置里的 ${MY_API_KEY} 会被自动替换，Key 不会明文出现在配置文件中：

bash

# 设置（加密存储在 OpenClaw 内部）
openclaw env set MY_API_KEY sk-xxx
 
# 列出已设置的变量（值被隐藏）
openclaw env list
 
# 删除变量
openclaw env unset MY_API_KEY

5. 常用配置命令

bash

openclaw status              # 查看状态（模型、渠道、Agent 列表）
openclaw dashboard           # 打开控制面板（浏览器）
openclaw gateway restart     # 重启网关（改完配置后必须执行）
openclaw gateway stop        # 停止网关
openclaw logs --follow       # 实时查看日志
openclaw logs --level error  # 只看错误日志
openclaw doctor              # 自动诊断配置问题
openclaw doctor --fix        # 尝试自动修复

6. 常见配置问题排查

JSON 语法错误（最常见）

配置改完重启后报错，先验证 JSON 是否合法：

bash

# 用 Node.js 验证
node -e "require(process.env.HOME + '/.openclaw/openclaw.json')"
 
# 或用 Python
python3 -m json.tool ~/.openclaw/openclaw.json

常见 JSON 错误：

尾部多余逗号：{ "a": 1, } → 改为 { "a": 1 }
忘记闭合括号：层级嵌套深时容易漏
字符串用了单引号：JSON 只允许双引号

Windows 路径问题

Windows 下配置文件在 C:\Users\你的用户名\.openclaw\openclaw.json。

WSL2 内路径写法不同：/root/.openclaw/openclaw.json

配置改了但不生效

确认执行了 openclaw gateway restart
执行 openclaw status 确认 Gateway 正在运行
查看日志确认加载成功：openclaw logs --follow

配置文件损坏后恢复

bash

# 备份并重新生成
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
openclaw onboard   # 重新运行向导生成干净配置

改完配置必须 restart：openclaw gateway restart 让新配置生效。