🦞OpenClaw ClawBook

核心概念

理解这些核心抽象，掌握 OpenClaw 的架构设计。

Gateway

核心进程

  • OpenClaw 的单一常驻进程，绑定在可配置端口（默认 127.0.0.1:18789）
  • 管理所有渠道连接（WhatsApp、Telegram、Discord 等），是消息路由的中枢
  • 通过 WebSocket 协议与客户端通信（macOS App、CLI、Web Control UI、Mobile Node）
  • 提供 HTTP 服务器，承载 Web Control UI 和 Canvas 画布
  • 支持热重载配置——修改 openclaw.json 后大多数设置自动生效，无需重启
  • 健康检查、诊断：openclaw gateway status、openclaw doctor

Channel

消息渠道

  • 内置支持：WhatsApp（Baileys）、Telegram（grammY）、Discord、Slack、Signal、iMessage
  • 插件扩展：Mattermost、Feishu、Google Chat、MS Teams、Matrix 等
  • 每个渠道支持多帐号（accountId），一台 Gateway 可服务多个手机号 / Bot
  • DM 策略可选：pairing（配对审批）、allowlist（白名单）、open（全开放）、disabled（关闭）
  • 群聊支持 @提及激活，可配置 mentionPatterns
  • 支持图片、音频、文档等多媒体消息收发

Agent

AI 运行时

  • 内嵌 Pi 编程 Agent 运行时（基于 pi-mono），会话管理由 OpenClaw 控制
  • 每个 Agent 拥有独立的工作区（workspace）、状态目录（agentDir）、会话存储
  • 工作区包含引导文件：AGENTS.md（指令）、SOUL.md（人格）、USER.md（用户画像）、TOOLS.md（工具说明）等
  • 首次会话自动注入引导文件内容到 Agent 上下文
  • 可通过 openclaw agents add 创建新的隔离 Agent

Session

会话管理

  • 会话是 Agent 与用户交互的基本单元，存储为 JSONL 格式
  • 作用域可配置：main（共享）、per-peer、per-channel-peer、per-account-channel-peer
  • DM 默认合并到 Agent 的 main 会话，群聊自动隔离
  • 支持自动重置：按时间段、空闲超时等策略重新开始会话
  • 上下文窗口接近上限时自动压缩（compaction），压缩前触发记忆刷盘
  • 转录文件路径：~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl

Skill

能力包

  • 遵循 AgentSkills 规范的目录，包含 SKILL.md（YAML frontmatter + 指令说明）
  • 三级加载：bundled（随安装）→ ~/.openclaw/skills（本地共享）→ workspace/skills（工作区优先）
  • 通过 metadata.openclaw 门控：要求二进制、环境变量、配置开关等条件满足才加载
  • ClawHub（clawhub.com）社区 Skill 仓库，可安装 / 更新 / 同步
  • Skill 在会话开始时快照，变更在下次新会话或热加载后生效
  • 第三方 Skill 应视为不受信代码，使用前请审查

Tool

Agent 的操作接口

  • 内置核心工具：read（读文件）、write（写文件）、edit（编辑）、exec（执行命令）等
  • Tool 可通过策略控制：allow / deny 列表，逐工具授权
  • 可选 Docker 沙箱隔离执行，减少工具操作的影响范围
  • elevated 模式可跳过沙箱在宿主机执行（需授权）
  • memory_search / memory_get 提供记忆语义检索
  • sessions_send 可跨渠道发送消息

Provider

模型提供商

  • 支持 Anthropic（Claude 系列）、OpenAI、Google（Gemini）、OpenRouter、Ollama 等
  • 配置格式：provider/model（如 anthropic/claude-sonnet-4-5）
  • 支持 API Key 和 OAuth 两种认证方式
  • Auth Profile 轮换：遇到速率限制时自动切换到下一个 Key
  • 模型故障转移（failover）：主模型失败时自动切换到 fallback
  • 在 /model 聊天命令中可实时切换模型

Multi-Agent

多 Agent 路由

  • 一个 Gateway 可同时运行多个隔离 Agent，各有独立工作区、会话、认证
  • 通过 bindings 配置确定性路由：按渠道、帐号、发送者等维度分发消息
  • 路由优先级：peer 精确匹配 > parentPeer > guildId+roles > accountId > channel > 默认 Agent
  • 支持每 Agent 独立的沙箱、工具策略、模型选择
  • openclaw agents add / openclaw agents list --bindings 管理 Agent
  • 不同的人可共享同一台 Gateway 服务器，数据完全隔离

Memory

记忆系统

  • 记忆以 Markdown 文件存储在工作区：MEMORY.md（长期）、memory/YYYY-MM-DD.md（每日）
  • 向量语义搜索（sqlite-vec 加速），支持混合 BM25 + 向量检索
  • Embedding 提供商可选：OpenAI、Gemini、Voyage、Mistral、Ollama、本地 GGUF
  • Compaction 前自动触发记忆刷盘（silent agentic turn）
  • 可选 QMD 后端（BM25 + 向量 + reranking）
  • 支持 MMR 去重和时间衰减排序

架构总览

┌───────────────────────────────────────────────┐
│                   Gateway                      │
│         (WebSocket + HTTP, :18789)              │
├──────────┬────────────┬───────────┬────────────┤
│ WhatsApp │  Telegram  │  Discord  │ iMessage…  │  ← Channels
├──────────┴────────────┴───────────┴────────────┤
│              Bindings (路由规则)                  │
├────────────────┬──────────────────┬─────────────┤
│   Agent "home" │  Agent "work"    │  Agent …    │  ← 隔离 Agent
│   ┌──────────┐ │  ┌──────────┐   │             │
│   │ Sessions │ │  │ Sessions │   │             │
│   │ Skills   │ │  │ Skills   │   │             │
│   │ Memory   │ │  │ Memory   │   │             │
│   │ Tools    │ │  │ Tools    │   │             │
│   └──────────┘ │  └──────────┘   │             │
├────────────────┴──────────────────┴─────────────┤
│           Providers (Anthropic, OpenAI…)         │
└─────────────────────────────────────────────────┘
│           ↕           ↕           ↕              │
│       macOS App      CLI     Control UI  Nodes   │  ← 客户端

Gateway 是唯一进程，管理所有渠道连接和客户端。通过 Bindings 将消息路由到对应 Agent，每个 Agent 独立维护工作区、会话和记忆。