启动与配置体系 —— openclaw.mjs、config.yaml 与环境变量管理
关键词：配置分层｜CLI 入口｜YAML 解析｜敏感信息隔离｜环境注入
一个工业级系统能否被可靠部署、灵活调优和安全运维，很大程度上取决于其配置管理能力。OpenClaw 作为支持多模型、多渠道、多租户的 AI 智能体网关，必须在“开箱即用”与“精细控制”之间找到平衡。
为此，OpenClaw 设计了一套三层配置体系，并通过统一的 CLI 入口 openclaw.mjs 实现灵活启动。本文将详解其启动逻辑、配置合并策略与安全实践。
一、CLI 入口：openclaw.mjs 的职责
OpenClaw 的主入口是一个 ESM 模块：openclaw.mjs。它不直接实现业务逻辑，而是扮演 “指挥官”角色：
核心任务
- 解析命令行参数（如
--config,--port,--debug） - 加载并合并配置（YAML + 环境变量 + 默认值）
- 初始化依赖（日志、数据库、渠道插件）
- 启动服务（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 的配置不是单一文件，而是一个分层叠加模型，优先级从低到高如下：
配置合并逻辑（伪代码）
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>
示例
此机制使得 OpenClaw 可无缝集成 Kubernetes Secrets、Docker
-e、或.env文件。
六、开发 vs 生产：配置差异化管理
推荐目录结构
openclaw/
├── config.yaml # 模板（不含密钥）
├── config.example.yaml # 示例文件（带注释）
├── .env.local # 本地开发密钥（.gitignore）
└── deployments/
├── prod.yaml # 生产结构（密钥留空）
└── docker-compose.yml # 注入环境变量结语：配置即契约，启动即承诺
OpenClaw 的启动与配置体系，体现了其工程严谨性：
- 通过分层配置，兼顾灵活性与一致性；
- 通过环境变量注入，实现安全与可移植；
- 通过 CLI 统一入口，降低使用门槛。
这套体系不仅服务于当前功能，更为未来支持动态重载、热更新、多租户隔离打下基础。
在下一篇文章中，我们将深入智能体引擎的核心——
run.ts，解析其如何实现多模型调度、上下文守护与故障转移。
下一篇预告：
第 5 篇：run.ts 上篇 —— 模型调度、账号轮询与上下文守护机制
您的 AI 助手，从此由您定义。若感兴趣可以浏览本书其他章节内容：
浙公网安备 33010602011771号