Day 05 / 共 20 天 · 第 1 周收官

配置系统与 workspace

昨天走通了消息的七站旅程——但"用哪个模型、连哪些渠道、什么人设"这些都由谁决定？答案是配置。今天看配置怎么加载（env 优先级链 + openclaw.json）、workspace 工作区是什么、bootstrap 文件如何塑造助理。收官第 1 周，为下周进"大脑"铺好底。

📍 你在整门课的位置（第 1 周收官）
Day1 全景→ Day2 入口启动→ Day3 Gateway→ Day4 消息旅程→ Day5 配置· W2 大脑· W3 技能/渠道· W4 安全/部署
L01

两类配置

🤔 痛点：密钥和功能开关，能塞一个文件里吗？ 你想把配置全写进一个文件方便管理，但密钥（模型 API key、渠道 token）一旦进了 openclaw.json 又被你提交到 git，就等于把家门钥匙贴上网。可功能配置（连哪些渠道、用什么模型）又确实需要结构化、能进版本库。
💡 本质：敏感的走 env，结构化的走 json，各归各位 就像"钱包（密钥）随身带、家具清单（功能配置）贴墙上"。env 管密钥/部署开关（不进库），openclaw.json 管渠道/模型/agent（可进库）。两者用一条优先级链拼起来（L02）。
  • 环境变量（env）：适合密钥、部署级开关（如 OPENCLAW_GATEWAY_TOKEN）。
  • 配置文件 openclaw.json：适合结构化配置（渠道、模型、agent、绑定）。
读法：两类互补：敏感/部署相关走 env（不进版本库），结构化功能配置走 json。openclaw.json 里还能有一个 env 块作为兜底。配置代码在 src/config/（config.ts、config-paths.ts、paths.ts、schema 等）。
L02

env 优先级链

.env.example 明确了 env 解析顺序（前者覆盖后者）：

# 优先级从高到低：
process env  >  ./.env  >  ~/.openclaw/.env  >  openclaw.json 的 env 块
为什么要"优先级链"？ 同一个变量可能在多处定义，得有规矩决定谁说了算。顺序设计得很合理：命令行/进程环境最高（临时覆盖最方便）→ 项目本地 ./.env（这个仓库/项目专属）→ 用户全局 ~/.openclaw/.env（你所有项目共享，daemon 用）→ 配置文件兜底。越"就近、越临时"的优先级越高。这样你能全局配一次默认，又能在特定场景临时覆盖——和技能的"就近覆盖"（Day 11）、配置的层叠是同一种思想。
同名变量：左边赢（优先级高 → 低） process env命令行/进程·最临时 ./.env本项目专属 ~/.openclaw/.env用户全局·daemon 用 openclaw.jsonenv 块·兜底 已存在的非空 process env 不会被 dotenv 覆盖（见 .env.example 注释）
env 优先级链：越"就近、越临时"的越优先。全局配默认，特定场景临时覆盖。
L03

openclaw.json

主配置文件，默认 ~/.openclaw/openclaw.json（OPENCLAW_CONFIG_PATH 可改）。结构化配置各功能域，例如：

{
  "gateway": { "bind": "loopback", "auth": { "token": "..." } },
  "agents": { "defaults": { "model": { "fallbacks": [...] } } },   // Day 07
  "channels": { "telegram": {...}, "slack": {...} },               // Day 13-14
  "messages": { "tts": {...} }                                     // Day 15
}
读法：你在前几天见到的配置键（gateway.bind、agents.defaults.model.fallbacks、channels.slack、messages.tts）都住在这里。有完整 schema 校验（src/config/ 里大量 schema 测试）——配错了会报错并提示。扩展的 configSchema（Day 12）也会并入总 schema。
⚠️ 常见误解：以为"改了 openclaw.json 就是最终生效值"。其实 env 优先级链在它之上（L02）——你在 ./.env 里设的同名变量会盖过 json 里的 env 块。所以"明明 json 写了却不生效"多半是被更高优先级的 env 覆盖了。
L04

目录约定

环境变量默认含义
OPENCLAW_STATE_DIR~/.openclaw状态目录（配置、auth、沙箱注册表等）
OPENCLAW_CONFIG_PATH~/.openclaw/openclaw.json主配置文件
OPENCLAW_WORKSPACE_DIR（见 L05）工作区
读法：~/.openclaw/ 是助理的"家目录"，放它的状态；部署时（Day 20）把它挂成持久卷 /data，机器重建数据不丢。路径解析在 src/config/config-paths.ts / paths.ts。
L05

workspace 工作区

workspace 是什么？ workspace（工作区）是助理"干活的目录"——它读写文件、放记忆、放项目专属技能/扩展都在这里。好比给助理一个"办公桌+文件柜"。为什么要单独一个工作区（而非到处乱放）？①安全：沙箱可以只挂载这个目录（Day 16 的 workspaceAccess），限制助理只能碰这里；②隔离：不同工作区可以是不同项目/身份，各有各的记忆和技能；③清晰：助理的一切产出集中一处，好管理好备份。Day 11 的 workspace 技能、Day 10 的 MEMORY.md 都住在工作区里。
L06

bootstrap 文件（塑造人设）

工作区里有一组特殊的 bootstrap 文件（src/agents/workspace.ts 里定义了 DEFAULT_SOUL_FILENAME="SOUL.md"、DEFAULT_MEMORY_FILENAME="MEMORY.md"、DEFAULT_BOOTSTRAP_FILENAME="BOOTSTRAP.md" 等），每次运行注入系统提示（Day 09）：

📝 举个例子：改一个 markdown 就换了人设 在 workspace 写 SOUL.md：你是一只毒舌但靠谱的助理，回答简短、爱吐槽。
→ 下次它回复"北京天气？"时：晴，25°C。出门吧，别赖床了。
把 SOUL.md 换成 你是温柔耐心的管家 → 同样问题变成 今天北京晴朗宜人，气温 25°C，适合外出，注意补水哦。没改一行代码，人格就变了。
文件作用
SOUL.md助理的性格/语气（读到就"入戏"）
USER.md你是谁、你的偏好
MEMORY.md长期记忆（Day 10）
AGENTS.md / TOOLS.md / IDENTITY.md行为准则 / 工具说明 / 身份
BOOTSTRAP.md / HEARTBEAT.md启动引导 / 心跳
读法：改这几个 markdown 文件，就能重塑助理的人格、记忆、行为——无需改代码。SOUL.md 定性格、USER.md 让它认识你、MEMORY.md 是它记住的事。单文件上限 2MB（MAX_WORKSPACE_BOOTSTRAP_FILE_BYTES），有字符预算防撑爆上下文。这就是"配置即人格"——OpenClaw 把助理的灵魂放在你能编辑的文件里。
L07

密钥与脱敏

💥 错误驱动：没有脱敏机制会出什么事故？ 设想没有这套保护：你把 OPENAI_API_KEY=sk-真实密钥 直接写进 openclaw.json，随手 git commit && git push 到公开仓库。几分钟内爬虫就扫到你的 key，有人拿去狂刷 API，第二天你收到一张几千美元的账单。这类事故在 GitHub 上天天发生。下面这套机制就是逐层堵住这个坑：

配置里难免有密钥（模型 API key、渠道 token）。OpenClaw 的处理（Day 17 详讲）：

  • 密钥优先放 env（不进 json、不进版本库）。
  • SecretRef 语法 source:provider:id（src/secrets/）——配置里存"引用"而非明文。
  • Web UI 编辑配置时脱敏往返（redact-snapshot.ts）：密钥用哨兵替换，写回时从磁盘还原。
  • detect-secrets 预提交钩子防密钥误提交仓库。
读法：配置系统从头到尾都在防"密钥泄露"——不明文存、不明文传、不误提交。这呼应 Day 17 的安全纵深。第 1 周结束，你已见到 OpenClaw"默认安全"的一贯姿态。
L08

第 1 周收官 🎓

🧠 第 1 周（入门与全景）你已掌握

  • Day 01 个人助理定位、五件套、控制平面、内嵌 Pi 内核
  • Day 02 启动链：openclaw.mjs → entry.ts → runCli（Commander）+ onboard 向导
  • Day 03 Gateway 控制平面：bind 安全、拉起渠道、WebSocket JSON-RPC、角色作用域
  • Day 04 一条消息的七站旅程（进→路由→想+做→出）
  • Day 05 配置：env 优先级链 + openclaw.json + workspace + bootstrap 人设 + 密钥脱敏

你现在有了 OpenClaw 的完整全局图：它是什么、怎么启动、控制平面怎么协调、消息怎么流转、配置怎么塑造它。第 2 周钻进"大脑"——内嵌的 Pi 内核、故障转移、执行循环、提示词、记忆。

🎵 记忆口诀（配置系统一句话） "密钥走 env、功能走 json、干活在 workspace、人格在 SOUL、就近的优先"——配置就像公司报销制度：公司有默认规则（json/全局 env），部门能覆盖（项目 .env），越靠近你的规则越说了算。

✋ 动手

cd /Users/bitmart/work/codes/github/openclaw
head -30 .env.example                          # env 优先级链
ls src/config/ | grep -iE 'paths|config\.ts'
sed -n '25,33p' src/agents/workspace.ts        # bootstrap 文件名
明天预告 · Day 06（第2周开始）：LLM 层与 Pi 内核——正式揭开"OpenClaw 不自己写 LLM 循环、而内嵌 Pi"的真相，看 streamFn 抽象和装饰器中间件。
← Day 04 消息旅程 Day 06 · LLM 层与 Pi 内核 →