启动与配置体系 —— openclaw.mjs、config.yaml 与环境变量管理

关键词：配置分层｜CLI 入口｜YAML 解析｜敏感信息隔离｜环境注入

一个工业级系统能否被可靠部署、灵活调优和安全运维，很大程度上取决于其配置管理能力。OpenClaw 作为支持多模型、多渠道、多租户的 AI 智能体网关，必须在“开箱即用”与“精细控制”之间找到平衡。

为此，OpenClaw 设计了一套三层配置体系，并通过统一的 CLI 入口 openclaw.mjs 实现灵活启动。本文将详解其启动逻辑、配置合并策略与安全实践。

一、CLI 入口：openclaw.mjs 的职责

OpenClaw 的主入口是一个 ESM 模块：openclaw.mjs。它不直接实现业务逻辑，而是扮演 “指挥官”角色：

核心任务

1. 解析命令行参数（如 --config, --port, --debug）
2. 加载并合并配置（YAML + 环境变量 + 默认值）
3. 初始化依赖（日志、数据库、渠道插件）
4. 启动服务（HTTP API + WebSocket + 渠道监听器）

启动示例

# 基础启动
pnpm openclaw start

# 指定配置文件
pnpm openclaw start --config ./prod.yaml

# 调试模式（输出详细日志）
pnpm openclaw start --debug

# 仅启动 Web UI（不加载渠道）
pnpm openclaw ui

 所有子命令（start, ui, chat, skill）均由同一入口分发，确保行为一致。

二、配置分层：三重覆盖机制

OpenClaw 的配置不是单一文件，而是一个分层叠加模型，优先级从低到高如下：

image

配置合并逻辑（伪代码）

const finalConfig = merge(
  defaults,               // L1
  loadYaml('config.yaml'),// L2
  loadAgentConfig(agentId),// L3
  parseEnvVars()          // L4 (最高优先级)
)

优势：

• 开发者可全局设 API Key，但为测试 Agent 单独指定 GPT-4
• 运维可通过环境变量临时调整端口，无需改文件

三、config.yaml 结构示例

一个典型的 config.yaml 包含以下核心区块：

# 网络与服务
server:
  port: 3000
  host: "0.0.0.0"
  corsOrigins: ["https://localhost:5173"]

# 认证配置（多模型支持）
authProfiles:
  openai:
    type: "openai"
    key: "${OPENAI_API_KEY}"  # 支持变量引用
    organization: "org-xxx"
  anthropic:
    type: "anthropic"
    key: "${ANTHROPIC_API_KEY}"

# 默认智能体行为
defaultAgent:
  model: "gpt-4o"
  maxContextTokens: 128000
  memory:
    enabled: true
    vectorWeight: 0.7

# 渠道配置
channels:
  whatsapp:
    enabled: true
    accounts:
      - phone: "+1234567890"
        sessionPath: "./sessions/wa_1234567890.json"
  telegram:
    enabled: false

注意：API Key 使用 ${VAR_NAME} 引用环境变量，而非硬编码。

四、安全实践：敏感信息绝不硬编码

OpenClaw 严格遵循 “配置即代码，密钥即环境” 原则：

1. 禁止明文存储密钥

• config.yaml 中所有密钥字段必须使用 ${ENV_VAR} 占位符
• 启动时自动替换：${OPENAI_API_KEY} → process.env.OPENAI_API_KEY

2. .gitignore 强制保护

项目模板包含：

config.yaml
sessions/
.env.local

确保本地配置不会误提交到 Git。

3. 会话文件加密（可选）

• WhatsApp 凭据（creds.json）可启用 AES 加密
• 密钥由 OPENCLAW_SESSION_SECRET 提供

4. 权限最小化

• Docker 镜像以非 root 用户运行
• 文件系统只读挂载（除 sessions/ 和 logs/ 外）

安全不是功能，而是默认状态。

五、环境变量注入：支持任意字段覆盖

OpenClaw 允许通过环境变量覆盖任意配置路径，规则为：

OPENCLAW_<SECTION>_<SUBSECTION>_<KEY>

示例

image

此机制使得 OpenClaw 可无缝集成 Kubernetes Secrets、Docker -e、或 .env 文件。

六、开发 vs 生产：配置差异化管理

image

推荐目录结构

openclaw/
├── config.yaml                 # 模板（不含密钥）
├── config.example.yaml         # 示例文件（带注释）
├── .env.local                  # 本地开发密钥（.gitignore）
└── deployments/
    ├── prod.yaml               # 生产结构（密钥留空）
    └── docker-compose.yml      # 注入环境变量

结语：配置即契约，启动即承诺

OpenClaw 的启动与配置体系，体现了其工程严谨性：

• 通过分层配置，兼顾灵活性与一致性；
• 通过环境变量注入，实现安全与可移植；
• 通过 CLI 统一入口，降低使用门槛。

这套体系不仅服务于当前功能，更为未来支持动态重载、热更新、多租户隔离打下基础。

在下一篇文章中，我们将深入智能体引擎的核心——run.ts，解析其如何实现多模型调度、上下文守护与故障转移。

下一篇预告： 第 5 篇：run.ts 上篇 —— 模型调度、账号轮询与上下文守护机制