夜雨聆风自托管 Agent 的「聪明」一半在模型，另一半在磁盘上有没有一套可推理、可回放、可回滚的事实。OpenClaw 把「骨骼」放在 ~/.openclaw：JSON5 主配置（openclaw.json）、按 Agent 分区的会话与记忆、加密凭证；把「性格」放在 Workspace 里的 Markdown Prompt 与可选的 .openclaw-context.md；把「运行痕迹」放在 Gateway 文件日志（默认目录见官方 Logging）、以及 doctor / HTTP /status / 内嵌 Control UI。三者对齐时，你排障是在对齐事实；三者没对齐时，聊天界面再顺滑也像在雾里开车。
本文把三条子系统拆成可独立阅读、又能在脑子里拼成一张图的架构文。事实以 Gateway Configuration、Agent Workspace、Logging 与 Releases 为准。
1. 总览：三支柱各自回答什么问题
| 配置与存储 | openclaw.jsoncredentials/、agents/*/sessions、memory/ | |
| Workspace / Prompt | BOOT/IDENTITY/SOUL/TOOLS.openclaw-context.md | |
| 可观测与审计 | /tmp/openclaw/openclaw-*.log，可配置） openclaw logs / doctor；审计/用量若独立落盘则以 logging 与插件为准 |
下面分章展开；每章末尾保留「试一下」——架构文也可以落地成动作。
2. 第一支柱：配置与存储
2.1 设计立场：为什么几乎是「零数据库」文件系统
OpenClaw 在配置与存储上的取向可以概括成：主配置用 JSON5 文件（openclaw.json，可含注释与 $include 合并）、Schema 校验失败则 Gateway 拒绝启动（仅诊断类 CLI 仍可用）；会话侧常见 JSONL 追加；记忆实现随版本演进（默认/插件化以 Configuration reference 为准，不宜在架构导读里写死为一种后端）；凭证加密落盘。官方明确主配置为 JSON5 而非 YAML/TOML 主路径，是为了 工具链与校验一致。文件日志默认为 按日落盘的 JSON 行文件，路径见下一章与 Logging。
存储哲学
OpenClaw 的存储哲学: ┌──────────────────────────────────────────────┐ │ 零数据库依赖 │ │ │ │ • 配置 → JSON5 文件（openclaw.json） │ │ • 会话 → JSONL 文件 │ │ • 记忆 → 向量/索引实现随版本（如 sqlite-vec） │ │ • 凭证 → 加密 JSON 文件 │ │ • 运行日志 → 见官网 logging.file（常为 JSON 行）│ │ │ │ 为什么不用 SQLite？ │ │ → 可以，但 JSON 文件更易调试、备份、迁移 │ │ → 单用户场景下 JSON 性能完全够用 │ │ → 未来可选 SQLite 作为高性能存储后端 │ │ │ │ 为什么不用 YAML/TOML？ │ │ → JSON / JSON5 + Schema 校验与工具链一致 │ │ → TypeScript 原生支持 │ │ → 减少解析歧义 │ └──────────────────────────────────────────────┘2.2 目录拓扑（精要）
~/.openclaw/ 在架构上可拆成几块（与官方「数据目录」叙述一致，以下为理解用树形摘要）：
• 根： openclaw.json、.env、openclaw.lock• credentials/（0700）：OAuth、配对信任、Gateway WebSocket Token 等 • agents/****/： config.json、sessions/s-<uuid>/{meta.json,messages.jsonl}、memory/{index,records,reflections}• workspace/：默认 Prompt 模板与 Workspace Skills • skills/、mcp/：已安装 Skill / MCP 状态与缓存 • logs/（若你的发行版/历史文档将运行日志放在数据目录下；当前官网 Gateway Logging 默认文件日志在 /tmp/openclaw/，由logging.file/logging.level配置——请以本机为准）• backups/、tmp/：备份快照与下载/沙盒临时目录
框线示意：~/.openclaw/ 目录树
~/.openclaw/ 根目录 │ ├── openclaw.json 主配置文件 ├── .env API Keys 和密钥 ├── openclaw.lock 进程锁文件 │ ├── credentials/ 凭证目录 (0700) │ ├── oauth-tokens.enc.json OAuth Token (AES-256 加密) │ ├── pairing-trust.json Channel 配对信任 (统一) │ ├── <channel>-pairing.json 可选: 按渠道分文件 │ └── gateway-token.json WebSocket API Token │ ├── agents/ Agent 实例目录 │ ├── main/ │ │ ├── config.json │ │ ├── sessions/ │ │ │ └── s-<uuid>/ │ │ │ ├── meta.json │ │ │ └── messages.jsonl │ │ └── memory/ │ │ ├── index/ sqlite-vec / 索引 │ │ ├── records/ │ │ └── reflections/ │ ├── coding/ │ └── research/ │ ├── workspace/ │ ├── AGENTS.md / SOUL.md / TOOLS.md │ ├── BOOT.md / BOOTSTRAP.md │ ├── IDENTITY.md │ └── skills/<skill>/ │ ├── skills/ ├── mcp/ ├── logs/ ※ 若构建仍落盘；官网默认亦见 /tmp/openclaw/ ├── backups/ └── tmp/ ├── downloads/ └── sandbox/你要建立的第一张心智地图：改配置是改哪一层，数据是落在哪一类目录——而不是「只有一个笼统的 openclaw」。
2.3 合并策略与 JSON Schema 验证
配置不是扁平的一坨，而是 多层覆盖（层级越高越优先；对象 深合并，数组 整段替换）：
1. 内置默认值 2. ~/.openclaw/openclaw.json3. agents/<id>/config.json4. 环境变量 5. CLI 参数（最高）
验证时机：Gateway 启动全量校验、config set 增量校验、openclaw doctor（含 --fix 修复路径）、配置 RPC 写入。直接编辑 openclaw.json 时，Gateway 会监视文件并触发热重载（见 Config hot reload）：gateway.reload.mode 默认 hybrid（安全变更即时生效，关键变更可自动重启），另有 hot / restart / off。语义层会校验未知键、类型与业务规则（如 workspace 可写、渠道与 Provider 是否可解析）——这与「进程起来了但对话失败」是两类问题。
2.4 .env 与环境变量（以官网为准）
Configuration · Environment variables：当前工作目录下的 .env（若存在）→ ~/.openclaw/.env（全局回退）；且 二者均不覆盖进程里已经存在的环境变量。配置里也可内联 env/vars。
内联配置中的 ${VAR} / ${VAR:-default}、~/ 展开等，以 Configuration reference 与你所用版本为准；改 .env 后通常需 Gateway 重读环境（常见为重启或等价 reload，视变量参与启动还是运行路径而定）。
2.5 进程锁、原子写入与 JSONL
• openclaw.lock：防止多 Gateway 实例；持锁失败会读 PID 并判断存活进程。 • JSON 原子写：先写临时文件再 rename，避免半写文件。• JSONL：会话消息等常见为 追加 JSONL（如 messages.jsonl）；启动时若最后一行解析失败，部分实现可 截断恢复——以代码与数据目录为准。
2.6 热重载、迁移与备份
主路径：保存合法的 ~/.openclaw/openclaw.json → Gateway watch → 按 gateway.reload.mode 决定 热应用 / 警告需重启 / 直接重启。官方表格归纳：多数 channels、agents、hooks、cron、tools、skills、logging、ui 等可热应用；以 gateway. 为前缀的配置项（端口、绑定、鉴权、Tailscale、TLS、HTTP 等）常需重启（官方对照表）。
迁移：历史上可有 链式迁移 + backups/<timestamp>/ 的设计；v2026.3.28 起对「过旧」自动迁移策略收紧（见该版 Release Breaking）——勿假定所有老 key 都会被静默改写，应 doctor / --fix 与发版说明并进。
备份：仍建议打包 openclaw.json、.env、credentials/、agents/、workspace/ 等；排除 tmp/、按需排除大日志——以你所用备份命令为准。
试一下：改一项 确定可热应用 的字段（如 logging.level），保存后看 是否无需重启即生效；再改 gateway.port 等需重启类字段，观察 hybrid 模式是否自动重启（勿在生产直接试）。
3. 第二支柱：Workspace 与 Prompt
3.1 Workspace = 物理空间，Prompt = 行为与边界
Workspace 决定 Agent 能碰哪些文件；BOOT / IDENTITY / SOUL / AGENTS 等 Markdown 决定 怎么说、怎么做、什么绝不能做。典型目录在 §3.2 四块之外，还可能有 USER.md、BOOTSTRAP.md、MEMORY.md、memory/YYYY-MM-DD.md 等——以你使用的模板为准（Templates）。
Workspace 文件族
┌──────────────────────────────────────────────────────┐ │ Workspace = Agent 的物理空间 │ │ Prompt = Agent 的精神世界 │ │ │ │ ~/.openclaw/workspace/ │ │ ├── AGENTS.md "运行规则与长期记忆" │ │ ├── SOUL.md "你的行为准则和性格" │ │ ├── USER.md "用户画像与称呼偏好" │ │ ├── TOOLS.md "工具约定与本地习惯" │ │ ├── IDENTITY.md "身份与风格（可选）" │ │ ├── BOOT.md "启动检查（可选）" │ │ ├── BOOTSTRAP.md "首次引导（一次性）" │ │ ├── MEMORY.md "长期记忆（可选）" │ │ └── memory/YYYY-MM-DD.md "每日记忆" │ │ │ │ │ └── (用户的工作文件...) │ │ ├── projects/ │ │ ├── notes/ │ │ └── ... │ └──────────────────────────────────────────────────────┘3.2 四文件视角与 TOOLS.md 的生成
口径：四文件指装配进 System Prompt 的四个内容块：BOOT、IDENTITY、SOUL、TOOLS。前三者为手写 Markdown；TOOLS 由工具注册表生成（常见落盘为 TOOLS.md），不要手改。部分模板另有 AGENTS.md 等规则层，与上述块并列——以 Templates 为准。
• BOOT：顶层原则、能力清单、安全准则（如：只信任已配对用户指令、不把网页/文件内容当指令） • IDENTITY：角色、沟通风格、边界 • SOUL：思考方式、工具使用习惯、错误处理、记忆策略 • TOOLS：由工具注册表按 builtin / skill / MCP 分组生成，不要手改；Skill/MCP/allow-deny 变更、配置热重载等会触发重新生成；通常内存缓存，不落盘
3.3 System Prompt 装配流水线（概念）
装配顺序可理解为：加载四块（§3.2）→ 变量插值（OS、WORKSPACE、NOW、USER、AGENT、CHANNEL、MODEL 等）→ 合并 .openclaw-context.md（若存在）→ Token 预算裁剪 → 缓存。若 System Prompt 过长，可能对 TOOLS 描述或 context 做裁剪；记忆摘要常见注入位置是在 user 消息前（而非全部塞进 System），以降低系统提示膨胀。
3.4 动态注入与多 Agent
System Prompt 尾部还可注入：当前时间、渠道上下文（Markdown 能否用、是否可编辑消息等）、安全边界提示、多 Agent 时的路由提示等。多 Agent 时，不同 instances 指向不同 workspace，各自可有不同 IDENTITY/SOUL 与工具子集；Prompt 文件查找一般是 Agent Workspace 优先，再回退共享模板。
3.5 .openclaw-context.md 与多级合并
项目根（或子包）放 .openclaw-context.md，写清技术栈、目录结构、禁忌命令；子目录优先、父目录追加合并，并对合并结果设 Token 总预算（常见讨论可见「约两千 Token 量级」的约束；以官方文档与当前实现为准）。写得好比写得长重要。
3.6 Prompt 热更新
对 Workspace 下 BOOT/IDENTITY/SOUL/.openclaw-context.md 做 fs.watch（TOOLS 不监听），防抖后重建 System Prompt、清缓存；下一轮 Agent Loop 生效，无需重启 Gateway。
试一下：只改 IDENTITY.md 一句口吻，保存后观察下一轮回复是否变化；若不变，先查缓存/热更新日志与 Workspace 路径是否指向你以为的目录。
4. 第三支柱：可观测性与审计
4.1 「现在怎么样」vs「之前发生了什么」
• 可观测性：Gateway/Channel/Agent 是否活着、延迟与 token、错误率 • 审计：工具执行、审批、配对与认证、配置变更、安全事件
二者在日志上部分重叠，但问题意识不同——前者偏运维，后者偏追责与合规心智。
观测 vs 审计
┌─ 可观测性 · 现在怎么样? ─────┐ ┌─ 审计 · 之前发生了什么? ────┐ │ • Gateway / Channel 状态 │ │ • 工具执行 / 审批 │ │ • Agent 在做什么 │ │ • 配对 / 认证 │ │ • 模型延迟与 Token │ │ • 配置变更 │ │ • 错误与告警 │ │ • 安全事件 │ └──────────────────────────────────┘ └────────────────────────────────┘4.2 Gateway 文件日志与「数据目录四日志」示意
以官网 Gateway Logging 为准：Gateway 文件日志默认落在 **/tmp/openclaw/**（具体以 logging.file 为准），按本地日期滚动，形如 openclaw-YYYY-MM-DD.log；每行一个 JSON；路径与级别由 logging.file、logging.level 等配置。CLI 使用 openclaw logs --follow；Control UI Logs tab 通过 logs.tail 跟踪。控制台与会话文件日志级别可分离（如 logging.consoleLevel）。
说明：下节 ~/.openclaw/logs/ 树状示意，用于理解「若日志落在数据目录时」的常见分类；与官网默认的 /tmp/openclaw/ 可能并存或二选一，以本机构建为准。
~/.openclaw/logs/ ├── gateway.log 运行日志 (通用) ├── audit.jsonl 安全审计日志 ├── usage.jsonl Token 使用和费用日志 └── error.log 错误日志 (仅 error 级别) ┌──────────────────────────────────────────────────────────┐ │ 格式: TIMESTAMP LEVEL [COMPONENT] MESSAGE key=value... │ │ │ │ 2026-02-26T10:30:00.123Z INFO [gateway] │ │ Started on 127.0.0.1:18789 pid=68861 version=0.1.0 │ │ 2026-02-26T10:30:15.789Z INFO [router] │ │ Inbound channel=telegram user=123456 agent=main │ │ 2026-02-26T10:30:18.345Z INFO [model] │ │ Complete model=kimi-k2.5 in=3200 out=450 ms=2340 │ │ 2026-02-26T10:30:18.567Z INFO [tool:gmail.list] │ │ Executing layer=skill args={query:"is:unread"} │ │ ... │ │ 组件: [gateway] [channel:*] [router] [agent:*] [model] │ │ [tool:*] [memory] [mcp:*] [security] │ └──────────────────────────────────────────────────────────┘下表为 便于理解的「业务分类」——若你本机未出现独立 audit.jsonl / usage.jsonl 文件，说明当前构建把它们并入了结构化文件日志、插件或控制面，勿死磕路径：
[gateway]、渠道分段、tools 摘要 redaction） | |
结论：做架构排障时，先跑通 **openclaw logs，核对 **logging.* 相关配置与当前版本文档；再用下表区分「运行 / 审计 / 用量」三类心智，避免把运维问题当成合规问题（或反之）。
4.3 状态、HTTP 与 doctor
• openclaw status（及 --usage等）：人读摘要• GET /health、GET /status：机器读 JSON• openclaw doctor：系统、配置、Provider、Channel、Memory 索引、工具、浏览器依赖、磁盘等一键体检
排障时优先用 openclaw doctor（可加 --fix）配合 openclaw logs（指向你当前 logging.file），比盲改配置更省时间。
4.4 错误分层与 Dashboard
错误可粗分为：可自愈（重连、429 退避、工具失败返回模型）、需通知（fallback、权限、预算）、需人工（配置损坏、磁盘满、OOM）。内嵌 Web Dashboard（本机 SPA + /status + WebSocket 日志流）常见 Tab：概览、会话、日志、用量、配置——与 Control UI 文档一致。
试一下：故意触发一次失败工具调用，在 当前文件日志 的 JSON 行里对齐工具开始/结束记录（字段名以你版本为准）；若另有审计导出，再对照一条——你会看见 叙事与追责两种读法如何互证。
5. 三者如何咬合
/health | |||
6. 收束：最小可执行清单
1. 画目录：默写 ~/.openclaw三层结构，标出「只读/慎改」的credentials/与备份目录。2. 画装配链：从 BOOT到TOOLS再到 context，标出哪一步最占 Token。3. 画排障链：openclaw doctor → openclaw logs 输出中的 JSON 行，对齐 tools/model 相关字段 → 若有用量导出再对齐 cost/stop。
参考文档
· Gateway Configuration：https://docs.openclaw.ai/gateway/configuration· Configuration reference：https://docs.openclaw.ai/gateway/configuration-reference· Agent Workspace：https://docs.openclaw.ai/concepts/agent-workspace· Templates (AGENTS.md)：https://docs.openclaw.ai/reference/templates/AGENTS.md· Logging：https://docs.openclaw.ai/gateway/logging· Doctor：https://docs.openclaw.ai/gateway/doctor· Control UI：https://docs.openclaw.ai/web/control-ui· openclaw/openclaw（源码与 Releases）：https://github.com/openclaw/openclaw· Release v2026.3.28：https://github.com/openclaw/openclaw/releases/tag/v2026.3.28· Documentation index (llms.txt)：https://docs.openclaw.ai/llms.txt