适用版本： OpenClaw v2026.3

核心概念

A

ACP (Agent Communication Protocol)

OpenClaw 定义的 Agent 通信协议，统一不同 LLM 后端的接口。定义了 ensureSession、runTurn、cancel 等核心方法。

Agent

AI 助手的运行时实体，包含 LLM 调用、工具执行、状态管理等能力。区别于单纯的 LLM，Agent 具有工具、记忆、规划等"躯壳"。

Auth Provider

认证提供者，支持 Token、Password、Tailscale 等多种认证方式。

B

Backup

数据备份机制，支持定时备份、手动备份、增量备份等方式。

C

Channel

消息渠道，如 WhatsApp、Telegram、Slack 等。每个渠道通过 Channel Plugin 实现与 OpenClaw 的集成。

Channel Plugin

渠道插件，实现 ChannelPlugin 接口，负责消息的收发和标准化。

Config Snapshot

配置快照，在启动时加载并固化，保证请求处理过程中配置一致性。

Control Plane

控制平面，Gateway 作为控制平面协调所有子系统的运行。

Cron

定时任务系统，支持类似 cron 表达式的定时触发。

D

DM (Direct Message)

私信，用户与 Agent 的一对一对话。

DM Policy

私信策略，控制谁可以与 Agent 对话。选项包括 open（任何人）、pairing（需配对）。

E

Embedded Mode

嵌入式模式，Agent 运行时与 Gateway 同进程，零通信开销。

Enriched Message

增强消息，在 NormalizedMessage 基础上添加了元数据（如配对状态、群组信息）。

G

Gateway

OpenClaw 的控制中心，负责协调 Session、Agent、Channel 等子系统。

H

Hook

生命周期钩子，允许在特定事件（如消息接收、Turn 开始）时执行自定义逻辑。

L

LLM (Large Language Model)

大语言模型，如 GPT-4、Claude、Gemini 等。是 Agent 的"大脑"。

M

Method

WebSocket API 的方法名，如 sessions.list、message.send 等。

Message Normalizer

消息标准化器，将不同渠道的消息格式转换为统一的 NormalizedMessage。

N

NormalizedMessage

标准化消息格式，包含 id、channelId、senderId、text、attachments 等统一字段。

P

Pairing

配对机制，用户需要先与 Agent 配对才能发送消息。

Pi Agent

嵌入式 Agent 运行时，基于 @mariozechner/pi-* 包实现，与 Gateway 同进程。

Plugin

插件，扩展 OpenClaw 能力的模块，可以是 Channel Plugin、Tool、Hook 等。

Provider

LLM 提供商，如 OpenAI、Anthropic、Google 等。

R

RPCE

远程过程调用错误 (Remote Procedure Call Error)，在方法调用失败时返回。

S

Sandbox

沙箱模式，限制 Agent 可执行的操作，提高安全性。

Session

会话，代表一个对话上下文。每个 Session 有唯一的 sessionKey。

Session Key

会话键，格式通常为 channelId:identifier，如 whatsapp:+1234567890。

Session Router

会话路由器，决定消息应该路由到哪个 Session。

Session Scope

会话范围，决定如何创建 Session。选项包括 per-sender（每人一个）、global（全局）、per-group（每群一个）。

Sidecar

辅助服务，如 Browser Control、Gmail Watcher 等，与 Gateway 一起启动。

Skill

技能包，封装一组工具、提示词和配置，提供特定能力。

Subagent

子 Agent，由主 Agent 创建，用于处理特定子任务。

T

Tool

工具，Agent 可调用的能力，如查询天气、执行代码、发送消息等。

Tool Context

工具上下文，包含 sessionKey、agentId、sandboxed、abortSignal 等信息。

Transcript

对话历史，记录 Session 中的所有消息。

Turn

一次对话回合，从用户发送消息到 Agent 回复完成的过程。

W

WebSocket

Gateway 使用的主要通信协议，支持双向实时通信。

架构术语

分层架构

┌─────────────────────────────────┐
│  渠道层 (Channels)              │  ← 消息入口/出口
├─────────────────────────────────┤
│  会话层 (Sessions)              │  ← 状态管理
├─────────────────────────────────┤
│  Agent 层 (Agents)              │  ← AI 处理
├─────────────────────────────────┤
│  Gateway 层 (Gateway)           │  ← 控制平面
└─────────────────────────────────┘

设计模式

策略模式 (Strategy Pattern)

用于认证系统，不同认证方式作为不同策略实现。

插件模式 (Plugin Pattern)

用于 Channel 和 Tool 系统，核心稳定，扩展灵活。

观察者模式 (Observer Pattern)

用于事件系统和 Hook 机制。

适配器模式 (Adapter Pattern)

用于 LLM 后端，将不同 API 适配为统一的 ACP 接口。

配置术语

YAML

配置文件格式，使用缩进表示层级关系。

环境变量

操作系统级别的变量，用于存储敏感信息，优先级高于配置文件。

热更新

不重启服务的情况下更新配置。

系列索引： OpenClaw 源码解析：目录索引