OpenClaw 环境变量与配置文件拆分技巧

2026-01-30 · 7 分钟基础配置

概述

随着 OpenClaw 功能的增加，单一配置文件会变得越来越庞大。本文将介绍如何利用 $include 指令拆分配置、使用环境变量管理敏感信息，以及 .env 文件的加载顺序。

JSON5 配置格式

OpenClaw 的主配置文件位于 ~/.openclaw/openclaw.json，采用 JSON5 格式，相比标准 JSON 更加灵活：

// ~/.openclaw/openclaw.json
{
  // JSON5 支持注释
  name: "我的 OpenClaw 实例",  // 键名可以不加引号

  // 支持尾逗号
  models: [
    "claude-3-opus",
    "gpt-4",
  ],
}

JSON5 的主要优势：

支持单行和多行注释
键名无需引号
允许尾逗号
字符串支持多行

$include 指令：配置文件拆分

当配置变得复杂时，$include 指令能将不同功能模块拆分到独立文件中：

// ~/.openclaw/openclaw.json（主配置）
{
  "$include": ["./models.json", "./channels.json", "./skills.json"],

  session: {
    scope: "per-channel-peer"
  }
}

// ~/.openclaw/models.json
{
  "models": {
    "primary": {
      "provider": "anthropic",
      "model": "claude-3-opus"
    }
  }
}

// ~/.openclaw/channels.json
{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "${DISCORD_BOT_TOKEN}"
    }
  }
}

嵌套深度限制

$include 支持嵌套引用，但最多10 层：

// 文件 A 引用 B，B 引用 C... 最多 10 层
// a.json → b.json → c.json → ... (最多 10 层)

超过 10 层会触发循环检测错误，避免无限递归。

环境变量替换

配置文件中可以使用 ${VAR_NAME} 语法引用环境变量：

{
  "channels": {
    "discord": {
      "token": "${DISCORD_BOT_TOKEN}"
    }
  },
  "models": {
    "primary": {
      "apiKey": "${ANTHROPIC_API_KEY}"
    }
  }
}

重要限制：变量名必须全部大写，使用下划线分隔。以下写法不合法：

// 错误示范
"${myToken}"        // 小写字母不合法
"${discord-token}"  // 连字符不合法

正确写法：

// 正确示范
"${MY_TOKEN}"
"${DISCORD_TOKEN}"

env.vars 内联配置

除了引用外部环境变量，还可以在配置文件中直接定义变量：

{
  "env": {
    "vars": {
      "LOG_LEVEL": "debug",
      "MAX_TOKENS": "4096",
      "CUSTOM_PROMPT_DIR": "/opt/openclaw/prompts"
    }
  }
}

内联变量同样可以在配置的其他位置通过 ${} 引用。

.env 文件加载顺序

OpenClaw 按以下优先级加载 .env 文件（后加载的会覆盖先加载的同名变量）：

父进程环境变量（最低优先级）
当前工作目录的 .env 文件
~/.openclaw/.env 文件（最高优先级）

# ~/.openclaw/.env
ANTHROPIC_API_KEY=sk-ant-xxxxx
OPENAI_API_KEY=sk-xxxxx
DISCORD_BOT_TOKEN=MTIzNDU2Nzg5.xxxxx

安全提示：确保 .env 文件的权限设置为 600，仅限当前用户读取。

chmod 600 ~/.openclaw/.env

配置验证与修复

OpenClaw 提供内置的配置检查工具：

# 验证配置文件语法和引用完整性
openclaw doctor

# 自动修复常见配置问题
openclaw doctor --fix

openclaw doctor 会检查：

JSON5 语法是否正确
$include 引用的文件是否存在
环境变量是否已定义
必填字段是否齐全

实用技巧

按环境分离配置

// ~/.openclaw/openclaw.json
{
  "$include": [
    "./base.json",
    "./${OPENCLAW_ENV:-production}.json"  // 根据环境加载不同配置
  ]
}

敏感信息集中管理

将所有 API 密钥放在 .env 文件中，配置文件只使用变量引用：

// 配置文件中不出现任何明文密钥
{
  "models": {
    "apiKey": "${ANTHROPIC_API_KEY}"
  },
  "channels": {
    "discord": { "token": "${DISCORD_BOT_TOKEN}" }
  }
}

故障排查

配置文件加载失败？

运行 openclaw doctor 检查 JSON5 语法
确认 $include 路径使用相对路径（相对于主配置文件）

环境变量未生效？

确认变量名全部大写
检查 .env 文件的加载顺序，确认没有被覆盖
重启 OpenClaw 服务使新变量生效