架构核心概念与配置管理（打地基）

适用版本： OpenClaw v2026.4.11（stable） 验证日期： 2026-04-12 目标读者： 已跑通第 1 篇环境，想理解 OpenClaw 到底怎么运转、怎么配 难度： ⭐⭐ 入门偏中 适合首次阅读： 是——本篇是后续所有教程的认知地基

目标

理解 OpenClaw 的架构全貌和配置管理体系。

这篇不写代码，只做一件事：把地基打好。后续教程涉及的频道、技能、自动化，全部建立在这些概念之上。搞清楚这层，后面每一步都会快很多。

学完后你应该能做到

1. 画出 OpenClaw 核心组件的关系，说清每个组件的职责
2. 知道改哪个文件、配哪个字段，能让 OpenClaw 接上你的模型
3. 区分「必须先做」和「以后再说」的配置项，不在第一天就过度工程化
4. 理解多模型路由、自动故障转移的配置逻辑
5. 知道 Hermes 项目有哪些值得借鉴的设计思路（可选阅读）

前置条件

• 已完成第 1 篇《5 分钟跑通 OpenClaw 最小可用环境》
• openclaw daemon status 显示运行中

最小配置路径

如果你赶时间，这篇的必做部分只有前两章：

步骤	内容	必要性
读完第一章	理解核心架构组件	✅ 必做
读完第二章	配置管理：openclaw.json、SOUL.md、模型接入	✅ 必做
第三章	多模型路由与故障转移	📌 可选——只用一个模型的话跳过
第四章	Hermes 启发	🔬 进阶——首次阅读可跳过

---

一、架构核心概念

📖 本节性质：OpenClaw 的基础架构事实。

整体分层

text
┌─────────────────────────────────────────────┐
│                  Channels                   │
│   Telegram · Discord · Slack · WhatsApp …  │
├─────────────────────────────────────────────┤
│                  Gateway                    │
│   路由 · 会话管理 · 策略执行 · 工具注册      │
├─────────────────────────────────────────────┤
│              Agent Runtime                  │
│   LLM 调用 · 工具执行 · 流式响应 · Failover  │
├─────────────────────────────────────────────┤
│               Workspace                     │
│   配置 · 记忆 · 技能 · 插件 · 会话存储       │
└─────────────────────────────────────────────┘
        ↑ 运行在你的 Node（设备）上

五个概念，逐个拆解。

1. Gateway — 控制平面

单进程守护进程（Daemon），整个 OpenClaw 的神经中枢。职责：

• 接收所有频道的消息，路由到 Agent Runtime
• 管理会话生命周期
• 执行安全策略（DM 策略、群组提及规则、工具沙箱）
• 注册和调度工具、技能、插件

默认监听 127.0.0.1:18789（WebSocket），控制台（Dashboard）也跑在这个端口上。

bash
# 查看 Gateway 状态
openclaw daemon status

💡 建议： Gateway 是单点，挂了所有频道都断。生产环境建议用 systemd 或 pm2 做进程守护，确保异常退出后自动重启。具体方案见第 10 篇《部署运维、性能优化与成本控制》。

2. Agent Runtime — 执行核心

每条消息到达 Gateway 后，会交给 Agent Runtime 处理。它负责：

• 调用 LLM（通过 provider/model 路由到对应提供商）
• 执行工具链（文件读写、命令执行、网页浏览等）
• 流式返回响应
• Provider 失败时自动 Key 轮转和模型降级

Agent Runtime 不直接暴露给用户，你通过 agents.defaults 配置来控制它的行为（用哪个模型、允许哪些工具、沙箱策略）。

💡 建议： 复杂任务（代码审查、长文分析）用强模型，简单任务（闲聊、查天气）用轻量模型。第三章「多模型路由」会讲怎么配。

3. Workspace — 数据根目录

~/.openclaw/ 就是 Workspace，所有持久化数据都在这里：

bash
~/.openclaw/
├── openclaw.json      # 主配置文件（JSON5 格式）
├── workspace/         # Agent 工作区
│   ├── SOUL.md        # AI 人格定义
│   └── ...
├── skills/            # 已安装的技能
├── plugins/           # 已安装的插件
├── sessions/          # 会话持久化（JSONL 格式）
├── memory/            # 长期记忆存储
└── logs/              # 运行日志

💡 建议： Workspace 目录包含会话记录和可能的凭证信息。建议目录权限设为 700（仅当前用户可读写），备份策略见第 10 篇《部署运维、性能优化与成本控制》。

4. Session — 会话隔离

每个「对话上下文」是一个 Session。关键特性：

• 按频道隔离：Telegram 和 Discord 上的对话互不干扰
• 按用户隔离：同一频道中不同用户各自独立（由 session.dmScope 控制粒度）
• 持久化为 JSONL：树状结构存储在 sessions/ 目录
• 上下文管理：对话过长时自动裁剪，防止超出模型 Token 上限

bash
# 查看当前活跃会话
ls ~/.openclaw/sessions/

💡 建议： Session 文件会随时间增长。可以通过 session.threadBindings.maxAgeHours 配置线程最大存活时间来自动清理。

5. Node — 设备节点

运行 OpenClaw 的每一台设备就是一个 Node。支持的设备类型：

类型	说明
服务器 / VPS	主力 Node，7x24 运行 Gateway
macOS	菜单栏 Companion App，支持 Voice Wake
Windows	桌面 Companion App
iOS / Android	移动端 Companion，本地执行拍照、录屏等操作

Companion App 不运行 Gateway，而是连接到你的主力 Node，把设备本地能力（摄像头、屏幕、文件系统）暴露给 Agent。

💡 建议： 只在一台机器上跑 Gateway。多台设备通过 Companion App 连接过来，形成「一个大脑 + 多个手脚」的架构。

---

二、配置管理体系

📖 本节性质：OpenClaw 的配置机制（事实）+ 日常配置建议。

配置优先级 ✅ 必做：理解这个规则

OpenClaw 的配置来自三个层级，优先级从高到低：

环境变量（最高）  >  openclaw.json  >  内置默认值

同一个配置项，环境变量永远覆盖配置文件。这意味着：

• 敏感信息（API Key）放环境变量
• 结构化配置（频道、路由、策略）放 openclaw.json
• 不需要改的就用默认值

openclaw.json 核心结构 ✅ 必做：知道骨架

OpenClaw 使用 JSON5 格式（支持注释和尾逗号），配置文件位于 ~/.openclaw/openclaw.json：

json5
{
  // Agent 配置：模型选择、技能、沙箱
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",  // provider/model 格式
        fallbacks: [],  // 降级模型列表
      },
    },
  },

  // 频道接入：Telegram、Slack、Discord 等
  channels: {},

  // Gateway 服务配置
  gateway: {
    port: 18789,
    reload: { mode: "hybrid" },  // 默认热重载
  },

  // 会话管理
  session: {},

  // 定时任务
  cron: { jobs: [] },

  // 自定义 Provider（内置 Provider 无需配置）
  models: {
    providers: {},
  },
}

不需要一次写全。OpenClaw 对每个字段都有合理默认值，只覆盖你需要改的部分。如果配置文件不存在，OpenClaw 用安全默认值启动。

⚠️ 版本说明： openclaw.json 的字段结构在严格校验模式下工作——未知字段、类型错误或非法值会导致 Gateway 拒绝启动。升级版本后如果遇到启动失败，请查阅对应版本的 release notes。

几个要点：

• 模型 ID 使用 provider/model 格式，例如 anthropic/claude-sonnet-4-6、openai/gpt-5.4、deepseek/deepseek-chat
• 内置 Provider（Anthropic、OpenAI、Google、DeepSeek 等）开箱即用，只需配环境变量；自定义 Provider 才需要写 models.providers
• 配置热重载：默认 hybrid 模式下，大部分配置修改后自动生效，无需重启 Gateway；只有基础设施级变更（Gateway 端口、插件加载等）才需要重启

SOUL.md ✅ 必做：至少创建一份

bash
vim ~/.openclaw/workspace/SOUL.md

SOUL.md 定义 AI 的人格和行为准则，类似 system prompt，但跨会话持久生效：

markdown
你是一个专注效率的技术助手。
回复默认用中文，技术术语保留英文。
除非用户明确要求，否则不要输出代码注释。

OpenClaw 还会自动维护用户画像，在交互中学习你的偏好并更新。一般不需要手动编辑，但可以随时查看和修正。

💡 建议： SOUL.md 控制在 20 行以内。太长会占用上下文窗口，影响每轮对话的有效信息量。更深入的人格定制见第 6 篇《记忆系统、SOUL 与个性化进化》。

版本锁定 🏭 生产建议

OpenClaw 使用日期版本号（如 v2026.4.11），分 stable / beta / dev 三个通道。生产环境建议锁定 stable 版本：

bash
# 查看当前版本
openclaw --version

# ⚠️ 请替换：把版本号换成你要锁定的实际版本
npm install -g [email protected]

升级前先在测试环境验证，避免新版本引入的 breaking change 影响正在运行的自动化任务。版本策略详见第 10 篇《部署运维、性能优化与成本控制》。

---

三、多模型路由与故障转移

📖 本节性质：OpenClaw 的配置能力（事实）+ 最佳实践建议。

📌 可选章节： 如果你现在只用一个模型，可以跳过本章，等需要时再回来。

为什么需要多模型

三个理由，按重要性排序：

1. 高可用 — 一个提供商挂了或限流了，自动切到另一个
2. 成本优化 — 简单任务用便宜模型，复杂任务用强模型
3. 能力互补 — 代码用 Claude，翻译用 DeepSeek，各取所长

配置主模型和降级模型

在 agents.defaults.model 中设置主模型和降级链：

json5
{
  agents: {
    defaults: {
      model: {
        // 主模型：日常请求走这个
        primary: "anthropic/claude-sonnet-4-6",
        // 降级链：主模型不可用时按顺序尝试
        fallbacks: [
          "deepseek/deepseek-chat",
          "openai/gpt-5.4-mini",
        ],
      },
    },
  },
}

工作流程：请求优先发往主模型，如果不可用则按 fallbacks 数组顺序依次尝试，全部失败才返回错误。

⚠️ 版本说明： 模型 ID 使用 provider/model 格式。可用的 provider 和 model 列表随版本更新，以 openclaw models list 命令输出为准。

API Key 配置

环境变量设置所有 Key，内置 Provider 会自动识别：

bash
# ⚠️ 请替换：把下面的 Key 换成你的真实值
export ANTHROPIC_API_KEY="sk-ant-xxx"
export OPENAI_API_KEY="sk-xxx"
export DEEPSEEK_API_KEY="sk-xxx"

只配一个就够。多模型是可选的进阶配置。

Key 轮转与自动故障转移（Failover）

OpenClaw 支持同一个 Provider 配置多个 API Key，在遇到限流（429）时自动轮转：

bash
# 方式一：逗号分隔列表
export ANTHROPIC_API_KEYS="sk-ant-key1,sk-ant-key2,sk-ant-key3"

# 方式二：编号后缀
export ANTHROPIC_API_KEY_1="sk-ant-key1"
export ANTHROPIC_API_KEY_2="sk-ant-key2"

Key 轮转的优先级：OPENCLAW_LIVE_<PROVIDER>_KEY → _KEYS 列表 → _KEY_* 编号 → 主 _KEY。

故障转移分两层：

1. 同 Provider 内：遇到限流（429）自动切换到下一个 Key
2. 跨 Provider：当前 Provider 所有 Key 都失败后，切换到 fallbacks 中的下一个模型

💡 建议： 非限流错误（认证失败、服务器错误）不会触发 Key 轮转，会直接报错。如果频繁遇到 Key 失效，先检查 Key 是否过期或余额耗尽。

添加自定义 Provider

内置 Provider（Anthropic、OpenAI、Google、DeepSeek 等）开箱即用。如果要接入非内置的提供商（如 Moonshot、SiliconFlow、自建中转），在 models.providers 中配置：

json5
{
  models: {
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",  // 引用环境变量
        api: "openai-completions",      // API 协议类型
        models: [
          { id: "kimi-k2.5", name: "Kimi K2.5" },
        ],
      },
    },
  },
}

配置完成后就可以在 agents.defaults.model 中使用 moonshot/kimi-k2.5 了。

按技能选模型

在技能的 SKILL.md Frontmatter 中指定偏好模型：

markdown
---
name: code-reviewer
description: 代码审查助手
preferred-model: anthropic/claude-opus-4-6
---

代码审查这类高推理任务自动使用更强的模型，其他任务继续走默认路由。技能开发详见第 5 篇《写你的第一个自定义技能》。

💡 建议： 先不急着给每个技能都指定模型。跑一段时间后，根据控制台（Dashboard）的用量统计，针对 Token 消耗最高的技能做针对性优化。

---

四、从 Hermes 借鉴的设计启发

📖 本节性质：借鉴 Hermes 项目的设计理念，属于进阶参考。

🔬 进阶章节： 首次阅读可以跳过。等你的 OpenClaw 跑稳了，再回来看会更有感觉。

2026 年 Nous Research 开源的 Hermes Agent（GitHub 40K+ star）提出了一套不同于 OpenClaw 的 Agent 哲学：OpenClaw 偏向「Agent 是需要编排的系统」，Hermes 偏向「Agent 是需要培育的心智」。

以下三条设计理念值得 OpenClaw 用户借鉴。

4.1 单 Gateway 多平台，核心逻辑不感知渠道

Hermes 和 OpenClaw 都采用「单 Gateway 进程服务所有频道」的架构，Hermes 更进一步强调所有平台共享同一套斜杠命令和行为逻辑，渠道差异只在协议适配层处理。

对 OpenClaw 用户的启发：在写技能或配置 Agent 行为时，不要针对特定渠道做分支逻辑。如果你发现某个技能「只在 Telegram 上好用，在 Slack 上不行」，说明技能本身耦合了渠道细节，应该修技能而不是加 if-else。

可以在 AGENTS.md 里写一条约束提醒 Agent 遵守：

markdown
## 核心路径约束

Agent Runtime 不感知消息来自哪个渠道。
- 不要在业务逻辑中按渠道类型分支
- 渠道特有的格式化只在投递层处理
- 如果一个工具在不同渠道表现不同，说明这个工具需要修复

💡 建议： 这条原则的价值在你扩展到 3 个以上渠道后体现——遵守它的 workspace 加新渠道几乎零改动。

4.2 Agent 自主维护记忆，而不是用户手动整理

Hermes 的核心差异化在于其持久记忆系统：基于 FTS5 全文检索 + LLM 摘要的跨会话记忆，加上 Atropos 强化学习框架让 Agent 从交互中自我改进。Agent 会主动提醒自己持久化知识（nudge），而不是等用户告诉它「记住这个」。

OpenClaw 也有记忆系统（第 6 篇《记忆系统、SOUL 与个性化进化》详细展开），但默认偏被动。借鉴 Hermes 的思路，你可以：

• 在 SOUL.md 中加一条规则：「每次对话结束前，主动判断是否有值得记住的信息，有则写入记忆」
• 配合第 7 篇《生产级记忆架构与自动化记忆维护》的自动化维护，让记忆系统「活起来」

4.3 技能从经验中自动生成和改进

Hermes 能在交互过程中自动创建技能——当它发现自己反复执行某个模式时，会把这个模式提炼成一个可复用的 Skill。下次遇到类似任务直接调用，不再从头推理。

OpenClaw 的技能系统（第 4 篇《技能（Skills）与工具生态 · ClawHub 实战》和第 5 篇《写你的第一个自定义技能》）目前以手动创建为主。但你可以借鉴这个思路：

• 观察 Agent 重复执行的操作模式
• 把高频模式提炼成 SKILL.md
• 在 SOUL.md 中鼓励 Agent 建议新技能

借鉴小结

Hermes 设计	对 OpenClaw 的启发	落地位置
单 Gateway 多平台，行为一致	技能和 Agent 逻辑不感知渠道	AGENTS.md 核心路径约束
Agent 自主维护记忆	在 SOUL.md 中加主动记忆规则	SOUL.md + 记忆自动化
技能从经验中自动生成	观察高频模式，提炼成 SKILL.md	skills/ 目录

💡 建议： 不必一次全上。先把第一条（核心路径约束）写进 AGENTS.md，它是零成本的架构原则。记忆和技能自动化等跑稳基础环境后再逐步引入。

---

常见误区

误区	正确做法
第一天就把多模型、多 Profile、Key 轮转全配上	先只配一个模型 + 默认值跑通，后续按需逐步添加
把 API Key 写进 openclaw.json	放环境变量，详见第 9 篇《安全最佳实践（重磅章节）》
SOUL.md 写了上百行	控制在 20 行以内，太长占上下文窗口，影响对话质量
以为改了配置必须重启 Gateway	默认 hybrid 热重载模式下大部分配置自动生效；只有端口、插件等基础设施变更才需要 openclaw daemon restart
用 sudo npm install -g 安装 OpenClaw	用 nvm 管理 Node，避免全局权限问题
多台机器各跑一个 Gateway	只在一台主力机器跑 Gateway，其他设备用 Companion App 连接
模型 ID 写成 "claude-sonnet-4"	必须使用 provider/model 格式："anthropic/claude-sonnet-4-6"

---

验证清单

bash
# 1. 理解 Workspace 结构
ls ~/.openclaw/
# 应该看到 openclaw.json、workspace/、sessions/、skills/ 等

# 2. 配置文件语法正确（JSON5 兼容检查）
openclaw daemon status
# 如果配置有语法错误，daemon 会拒绝启动并报告具体位置

# 3. 模型配置生效
openclaw chat "你现在用的是什么模型？请说出 provider/model 格式的模型名称。"

# 4. SOUL.md 已创建
cat ~/.openclaw/workspace/SOUL.md

# 5. 守护进程（Daemon）运行正常
openclaw daemon status

---

常见问题

Q: 改了 openclaw.json 但没生效？

大部分配置在默认的 hybrid 热重载模式下会自动生效，无需重启。如果改的是端口、插件等基础设施配置，需要 openclaw daemon restart。环境变量修改后需要先 source ~/.zshrc 再重启。

Q: 怎么验证故障转移（Failover）是否正常工作？

临时把主模型的 API Key 改成无效值，发送一条消息。如果收到回复且日志显示切换到了 fallbacks 中的模型，说明 Failover 生效。测试完记得改回来。

Q: 本地模型（Ollama）能作为 fallback 吗？

可以。把 Ollama 配置为自定义 Provider（在 models.providers 中添加），然后在 fallbacks 数组末尾加上对应的 provider/model ID。本地模型延迟低且免费，适合做最后兜底。

Q: SOUL.md 和频道的行为配置冲突了怎么办？

SOUL.md 是全局人格，作用于所有会话。频道级的配置（如 dmPolicy、群组行为规则）控制的是访问策略，两者层面不同，一般不会冲突。如果你需要不同频道展现不同 Agent 风格，可以配置多个 Agent（通过 agents.list[]）。

---

下一步

地基打好了，接下来去第 3 篇《消息渠道（Channels）与交互体验优化》，接入 Telegram、飞书等频道，让 OpenClaw 真正能在你的日常工具里回复消息。