🎖️ 任务奖励 — 学完你能做到
能解释 Gateway、Agent、Skill 的关系，看懂 openclaw.json 配置的作用
📖 本章目标：理解 OpenClaw 的技术架构、运行逻辑与核心设计哲学
2.1 技术本质
OpenClaw 的技术本质是一套本地优先的 AI Agent 执行引擎，核心通过”网关调度 + LLM 决策 + 技能执行 + 分层记忆”的闭环架构，让 AI 从”对话式建议”升级为”系统级执行”。
三层架构概览
┌─────────────────────────────────────┐
│ LLM 大模型层（智能大脑） │
│ GPT-4 / Claude / Llama / Mistral │
└──────────────┬──────────────────────┘
│ 标准化接口
┌──────────────▼──────────────────────┐
│ 网关层 Gateway（神经中枢） │
│ 消息路由 | 技能调度 | 安全认证 | 状态 │
│ Node.js 常驻进程，监听端口 18789 │
└──────────────┬──────────────────────┘
│
┌──────────────▼──────────────────────┐
│ 渠道与执行层（手脚） │
│ Telegram / 飞书 / 微信 / Discord │
│ Skills：Shell | 文件 | 浏览器 | ... │
└─────────────────────────────────────┘2.2 核心运行逻辑：Agent 循环
OpenClaw 的核心是 Agent 循环（思考 → 行动 → 反馈 → 记忆）：
用户发送指令
↓
网关加载上下文
（SOUL + 记忆 + 技能清单）
↓
LLM 意图解析 & 任务规划
（生成工具调用指令，非自然语言回复）
↓
网关执行技能
（权限校验 → 沙箱隔离 → 执行）
↓
执行结果反馈给 LLM
（成功/失败、返回值、日志）
↓
任务完成？
是 → 生成最终结果，更新记忆
否 → LLM 调整规划，触发新一轮循环
（最大循环次数：默认约 20 次）2.3 三层架构详解
Gateway（网关层）— 神经中枢
基于 Node.js 构建的常驻守护进程，默认监听本地 WebSocket 端口 18789。
核心职责：
- 消息标准化（将各渠道格式统一）
- 会话路由（分发到对应 Agent）
- 技能调度（加载、执行、卸载 Skills）
- 安全认证（Token 认证、权限过滤）
- 状态维护（会话状态、记忆同步）
LLM 层 — 智能大脑
支持多种模型混合部署：
- 云端模型：GPT-4、Claude、Gemini 等
- 本地模型：Llama、Mistral、Qwen 等（通过 Ollama）
- 通过标准化接口与网关联动，用户可按需切换
渠道与执行层 — 手脚
- 交互渠道：Telegram、飞书、微信、Discord 等 20+ 平台
- Skills 插件：封装 Shell 执行、文件读写、浏览器驱动等能力
核心设计原则
| 原则 | 说明 |
|---|---|
| Loopback-First | Gateway 默认仅绑定 127.0.0.1，所有流量本地流转，杜绝外网攻击 |
| Security by Default | 所有执行操作需经过权限校验，仅授权技能可调用系统命令 |
| 单实例主机 | 每台主机仅运行一个 Gateway 实例，避免会话冲突 |
2.4 记忆系统：四层记忆架构
记忆是 OpenClaw 区别于普通聊天机器人的核心能力。
| 记忆层级 | 存储位置 | 生命周期 | 用途 |
|---|---|---|---|
| 即时记忆 | 当前对话上下文 | 会话内 | 当前任务的上下文理解 |
| 日常记忆 | memory/YYYY-MM-DD.md | 每日追加 | 今日+昨日交互记录 |
| 长期记忆 | MEMORY.md | 持久化 | 用户偏好、重要事项 |
| 向量记忆 | SQLite-vec | 持久化 | 语义搜索 + BM25混合检索 |
记忆自动管理机制
- Daily Logs：每日交互以 append-only 方式写入
memory/YYYY-MM-DD.md，会话启动时自动加载今日+昨日日志 - Pre-Compaction（预压缩）：会话 Token 接近上限（默认约 4000）时，Agent 静默将关键信息写入长期记忆，压缩上下文，避免溢出
- 向量检索：基于 SQLite-vec 存储，支持语义搜索 + 关键词 BM25 混合检索，精准召回历史信息
2.5 Agent 工作区结构
每个 Agent 拥有独立文件目录，所有配置以纯文本 Markdown/JSON 存储，人类可直接编辑：
workspace/
├── AGENTS.md # 身份定义、行为边界、回复规则
├── SOUL.md # 不可变人格内核
├── USER.md # 用户信息、偏好设置
├── MEMORY.md # 长期记忆存储
├── HEARTBEAT.md # 心跳、定时任务配置
├── memory/ # 每日日志文件夹
│ ├── 2026-03-01.md
│ └── 2026-03-02.md
├── skills/ # 工作区专属技能（最高优先级）
└── sessions.json # 会话状态数据2.6 Session 与用户识别
DM 配对认证（默认开启）
未知用户发送消息 → 返回6位一次性配对码
↓
管理员执行命令批准
↓
用户方可正常使用防止陌生人滥用 API 与功能
白名单机制（allowFrom）
预先指定用户 ID，直接跳过配对，支持多渠道：
telegram:123456789whatsapp:+8613800138000feishu:ou_xxxxxxx
群组隔离策略
- 每个群组独立 session，不读取长期记忆
- 默认
requireMention：仅 @机器人时响应 - 避免群聊泄露隐私、消耗 Token
2.7 设计哲学
| 哲学 | 说明 |
|---|---|
| Unix 哲学 | 小工具、可组合、文本流；CLI 是 Agent 连接世界的终极接口 |
| 极简主义 | 核心工具仅 4 个：Read / Write / Edit / Bash，减少 Token 消耗 |
| 反 MCP | 不依赖 Model Context Protocol，优先原生 CLI，更轻量、更稳定 |
| 自我扩展 | Agent 可自主编写、修复、重载 Skill，实现能力自我进化 |
| 本地优先 | 数据不出设备，隐私可控，拒绝云端绑架 |