为什么要做多环境配置管理

在 OpenClaw 项目进入“能跑起来”之后，最先遇到的工程化问题往往不是功能，而是配置：

• 开发环境（dev）：本地调试，依赖 mock、日志更详细、可能使用内网资源。
• 测试环境（test/staging）：验证集成与回归，依赖共享中间件，配置更接近生产。
• 生产环境（prod）：强调稳定与安全，敏感信息严格管理，开关默认保守。

如果没有一套清晰的多环境策略，常见事故包括：

1. 把测试数据库地址带到生产，造成数据污染。
2. 调试日志/调试开关忘关，导致性能下降或泄露信息。
3. 临时改配置没记录，团队成员机器行为不一致，“在我这儿是好的”。

本篇 OpenClaw教程 将聚焦：开发/测试/生产的切换策略、配置分层覆盖、配置注入到代码、敏感信息管理、容器/CI 中的落地方式。你可以直接按步骤把它落到你的 OpenClaw 工程里。

目标：建立可预测的“配置分层 + 环境切换”模型

建议在 OpenClaw 中采用以下配置优先级（从低到高）：

1. 默认配置（仓库内，适用于所有环境）
2. 环境配置（dev/test/prod，各自一份）
3. 本地开发覆盖（个人私有，不提交 Git）
4. 运行时注入（环境变量/启动参数/密钥系统，优先级最高）

这样可以做到：

• 绝大多数配置可追溯（在仓库里）
• 个别开发者差异可隔离（本地覆盖）
• 生产敏感项不落盘（运行时注入）

目录与文件组织建议（可直接套用）

推荐在 OpenClaw 项目中建立如下结构：

• config/

  • default.yml
  • dev.yml
  • test.yml
  • prod.yml
  • local.yml（可选，git ignore）
• .env（可选，本地开发使用，git ignore）

• scripts/

  • run-dev.sh
  • run-test.sh
  • run-prod.sh

并在 .gitignore 中加入：

• config/local.yml
• .env

配置命名规范

建议统一使用：

• 环境名：dev / test / prod
• 环境变量：OPENCLAW_ENV
• 配置注入前缀：OPENCLAW_（避免污染系统变量）

配置内容怎么写：从“可运行”到“可治理”

下面给出一份较完整的配置示例（以 YAML 为例）。你可以根据 OpenClaw 实际模块增减字段。

config/default.yml

• 放“所有环境都需要，但有合理默认值”的项
• 不要写任何密码/密钥

示例（片段）：

• app.name: 服务名
• app.port: 默认端口
• log.level: 默认日志级别
• db.host/db.port/db.name: 可给默认，但不写账号密码
• feature.xxx: 功能开关默认关闭

config/dev.yml

开发环境通常特征：

• 日志更详细：debug
• 开启 swagger / 调试页面
• 连接本地 DB 或容器 DB
• 允许 mock

建议写入：

• log.level: debug
• feature.mock: true
• security.cors: *（仅 dev）

config/test.yml

测试环境特征：

• 更接近生产
• 允许更高的可观测性，但不要泄露敏感信息
• 通常对接共享中间件

建议写入：

• log.level: info
• feature.mock: false
• observability.tracing: true

config/prod.yml

生产环境特征：

• 最小权限、最少暴露
• 不在文件里保存敏感信息
• 默认关闭开发功能

建议写入：

• log.level: warn
• feature.mock: false
• security.cors: https://your-domain.com

config/local.yml（可选）

用于个人覆盖（例如你的本地端口、你的临时 DB 地址）。

注意：local.yml 永不提交仓库。

环境切换：用一个变量决定“加载哪套配置”

推荐只用一个入口变量：

• OPENCLAW_ENV=dev|test|prod

加载策略（强烈建议固定）

应用启动时按顺序加载：

1. config/default.yml
2. config/{OPENCLAW_ENV}.yml（若不存在则报错或回退到 dev，建议报错）
3. config/local.yml（如果存在）
4. 环境变量注入（OPENCLAW_ 前缀）
5. 启动参数注入（可选，但优先级应最高）

这样能保证：同一个环境下，任何机器的行为一致；差异只会来自明确的注入层。

配置注入：把环境变量映射到配置树

多环境管理的核心是：生产的关键项必须能从运行时注入。常见注入来源：

• 容器环境变量（K8s Deployment、Docker Compose）
• CI/CD 平台变量（GitHub Actions、GitLab CI）
• 密钥管理（K8s Secret、Vault 等）

建议的映射规则

为了让注入规则可预测，可以采用“下划线映射层级”的约定：

• 配置键：db.password
• 环境变量：OPENCLAW_DB_PASSWORD

层级分隔：

• . → _

示例清单（建议你在项目 README 固化）：

• OPENCLAW_APP_PORT → app.port
• OPENCLAW_DB_HOST → db.host
• OPENCLAW_DB_USER → db.user
• OPENCLAW_DB_PASSWORD → db.password
• OPENCLAW_REDIS_URL → redis.url
• OPENCLAW_LOG_LEVEL → log.level

数据类型处理建议

环境变量天然是字符串，建议在加载阶段做类型转换：

• app.port、db.port：转 int
• feature.mock：支持 true/false/1/0
• timeouts.xxx：支持 1000ms/5s 这类人类可读格式（如你有解析器）

如果暂时不做复杂解析，至少要保证布尔、整数转换正确，避免出现“端口是字符串导致框架不识别”的问题。

在 OpenClaw 代码里如何“拿到配置”：注入而不是到处读取

配置管理落地的关键不是“能读到文件”，而是“业务代码不关心配置从哪来”。因此建议在 OpenClaw 的工程结构里引入一个配置门面（Config Provider）。

建议的代码结构

• internal/config/loader：负责加载与合并
• internal/config/schema：定义结构（可选，但强烈推荐）
• internal/app：只接收一个配置对象

推荐做法：启动时构建 Config，再注入到各模块

启动流程（伪步骤）：

1. 读取 OPENCLAW_ENV
2. 加载默认配置
3. 合并环境配置
4. 合并本地覆盖（如果存在）
5. 合并环境变量注入
6. 校验配置（必填项、范围、合法值）
7. 把最终 Config 对象注入到：DB、缓存、HTTP Server、任务调度器等

这样做的收益：

• 你能在启动时一次性报出“缺少 DB_PASSWORD”，而不是运行半小时后某个请求才报错。
• 单元测试能直接构造 Config 对象，不必依赖外部文件。

配置校验：让错误在启动时失败（Fail Fast）

多环境最大的问题是“看起来启动了，但某个配置不对”。建议对以下内容做校验：

必填项

• 生产环境必须提供：db.user、db.password、security.jwt_secret 等
• 某些开关开启时必须提供：例如 observability.tracing=true 时必须提供 tracing.endpoint

合法值范围

• log.level 只能是：debug/info/warn/error
• app.port 必须是 1~65535

环境约束

• OPENCLAW_ENV=prod 时禁止：feature.mock=true
• OPENCLAW_ENV=prod 时禁止：security.cors=*

把这些约束写成明确的启动检查，能把“人为失误”直接挡在发布前。

实操：本地开发、测试环境、生产环境的启动方式

下面给出三套推荐启动方式，你可以按团队习惯选一种或组合。

方式 A：脚本化（最直观，团队易统一）

建立：scripts/run-dev.sh：

• 设置 OPENCLAW_ENV=dev
• 可选：加载 .env
• 启动服务

同理 run-test.sh、run-prod.sh。

优点：

• 新同学一条命令就跑起来
• 环境切换明显，减少口头约定

方式 B：Docker Compose（适合含 DB/Redis 的本地开发）

做法要点：

• Compose 文件里写 environment: OPENCLAW_ENV=dev
• DB/Redis 用容器启动，应用通过服务名连接
• 敏感项可放 .env（本地）或直接写在 Compose 的 env（仅本地）

关键建议：

• 本地 Compose 可以允许弱密码，但测试/生产绝不要复用

方式 C：Kubernetes（生产/测试常用）

建议把配置分为：

• ConfigMap：非敏感项（如 log.level、feature.*、app.port）
• Secret：敏感项（如 db.password、jwt_secret）

在 Deployment 中注入：

• OPENCLAW_ENV=prod
• OPENCLAW_DB_PASSWORD 来自 Secret

并且将 config/prod.yml 保持“无敏感信息”，只定义开关与默认行为。

敏感信息管理：不要把“密码”当配置文件的一部分

在 OpenClaw 多环境实践里，敏感信息建议遵循三条硬规则：

1. 仓库里不出现明文密码（包括历史提交）。
2. 生产密码不落盘（用 Secret/密钥系统注入）。
3. 最小暴露：日志中禁止打印完整连接串、禁止打印密钥。

推荐模式：文件里只放“键”，值由运行时注入

例如配置里写：

• db.user: openclaw
• db.password: ${OPENCLAW_DB_PASSWORD}（或留空，强制注入）

如果你的配置系统不支持占位符，也可以在校验阶段要求：prod 必须由环境变量提供 OPENCLAW_DB_PASSWORD。

常见坑与排查清单（按优先级）

1）环境切换不生效

排查：

• OPENCLAW_ENV 是否真正传入进程（容器里用 printenv 看）
• 是否写错环境名（如 production vs prod）
• 加载顺序是否被覆盖（比如先注入后加载文件导致被文件覆盖）

建议：

• 启动时打印一条“当前环境 + 配置来源摘要”（不要打印敏感值）

2）本地跑正常，测试环境失败

排查：

• local.yml 是否藏了关键配置（例如你本地有密码，测试没有）
• 是否缺少必填校验导致“隐性依赖”

建议：

• 在 CI 上跑一次 OPENCLAW_ENV=test 的启动校验（不必真正提供外部依赖）

3）生产出现调试日志或调试开关

排查：

• prod.yml 是否继承了 dev 的某些配置
• 运行时注入是否把 OPENCLAW_LOG_LEVEL=debug 带进生产

建议：

• 对 prod 环境增加强约束：debug 不允许启动

一套可直接复用的“落地步骤清单”

你可以按以下顺序在 OpenClaw 项目中实施，多人协作时也容易分工：

1. 建立 config 目录与四类文件：default/dev/test/prod + 可选 local
2. 确定 OPENCLAW_ENV：只允许 dev/test/prod，并在启动时打印当前值
3. 实现配置加载与合并顺序：default → env → local → env vars → args
4. 实现环境变量映射规则：OPENCLAW_ 前缀 + _ 分隔层级
5. 加入配置校验：必填、范围、环境约束（尤其 prod）
6. 把 Config 注入到模块：数据库/缓存/HTTP/队列，不在业务代码里到处读环境变量
7. 把敏感信息移出文件：改用 Secret/CI 变量注入，并检查日志不泄露
8. 写启动脚本或容器编排：让环境切换成为一条命令

做到以上 8 步，你的 OpenClaw 项目基本就拥有了“可控、可审计、可迁移”的多环境配置管理能力：开发体验不受影响，测试环境一致性更强，生产安全边界清晰。

小结：多环境的本质是“分层覆盖 + 强约束”

OpenClaw 的多环境配置不是把配置文件复制三份这么简单，而是要建立一条稳定的链路：

• 分层：默认/环境/本地/运行时
• 覆盖：越靠近运行时优先级越高
• 校验：错误尽早暴露
• 注入：业务模块只接收最终 Config
• 安全：敏感项永远在运行时注入

按本文方法落地后，你会发现：环境切换变得可预测，发布风险显著下降，排障速度也会更快——这正是从“能用”走向“可维护”的关键一步，也是 OpenClaw教程 进入实战阶段必须补齐的工程能力。