# OpenClaw 系统架构设计文档

> 项目：https://github.com/openclaw/openclaw
> 文档版本：1.0
> 创建日期：2026-02-06

---

## 目录

- [1. 概述](#1-概述)
- [2. 项目整体结构](#2-项目整体结构)
- [3. 核心架构设计](#3-核心架构设计)
  - [3.1 CLI 命令系统](#31-cli-命令系统)
  - [3.2 网关架构](#32-网关架构)
  - [3.3 消息通道系统](#33-消息通道系统)
  - [3.4 媒体管道](#34-媒体管道)
  - [3.5 基础设施层](#35-基础设施层)
- [4. 关键设计模式](#4-关键设计模式)
  - [4.1 依赖注入](#41-依赖注入)
  - [4.2 状态管理](#42-状态管理)
  - [4.3 消息路由机制](#43-消息路由机制)
  - [4.4 配置系统](#44-配置系统)
  - [4.5 钩子系统](#45-钩子系统)
- [5. 插件扩展机制](#5-插件扩展机制)
  - [5.1 插件类型](#51-插件类型)
  - [5.2 插件 API](#52-插件-api)
  - [5.3 通道插件](#53-通道插件)
  - [5.4 插件运行时](#54-插件运行时)
- [6. 路与会话管理](#6-路由与会话管理)
  - [6.1 路由解析](#61-路由解析)
  - [6.2 会话管理](#62-会话管理)
  - [6.3 会话持久化](#63-会话持久化)
- [7. 模块间关系](#7-模块间关系)
- [8. 通信协议](#8-通信协议)
  - [8.1 Gateway Protocol](#81-gateway-protocol)
  - [8.2 ACP (Agent Client Protocol)](#82-acp-agent-client-protocol)
- [9. 认证与安全](#9-认证与安全)
  - [9.1 设备配对](#91-设备配对)
  - [9.2 Gateway 认证](#92-gateway-认证)
  - [9.3 SSRF 防护](#93-ssrf-防护)
- [10. 测试策略](#10-测试策略)
- [11. 构建与部署](#11-构建与部署)
- [12. 编码规范](#12-编码规范)
- [13. 附录：代码示例](#13-附录代码示例)

---

## 1. 概述

OpenClaw 是一个多平台消息聚合与 AI Agent 平台，支持 WhatsApp、Telegram、Discord、Slack、Signal、iMessage 等多个消息通道，以及多种 AI 模型提供者。

### 1.1 核心特性

- **多通道支持**：通过插件化架构支持十多种消息平台
- **Gateway 架构**：集中式的 WebSocket 网关服务所有客户端
- **插件系统**：可扩展的插件机制（通道、模型提供者、内存等）
- **灵活路由**：基于绑定的智能消息路由
- **会话管理**：持久化的会话存储和历史记录
- **媒体处理**：完整的媒体上传、存储和处理管道

### 1.2 技术栈

- **语言**：TypeScript (ESM)
- **运行时**：Node 22+，支持 Bun
- **包管理**：pnpm（保持 npm 兼容性）
- **测试**：Vitest + V8 覆盖率
- **Lint/Format**：Oxlint + Oxfmt
- **协议**：WebSocket (JSON)，HTTP (REST + OpenAI 兼容)

---

## 2. 项目整体结构

### 2.1 主要目录

```
openclaw/
├── src/
│   ├── cli/                  # CLI 入口和命令系统
│   ├── commands/             # 命令实现
│   ├── gateway/              # Gateway 服务器
│   ├── channels/             # 通道系统
│   ├── providers/            # AI 模型提供者
│   ├── agents/               # Agent 运行时
│   ├── media/                # 媒体管道
│   ├── infra/                # 基础设施
│   ├── config/               # 配置系统
│   ├── plugins/              # 插件系统
│   ├── plugin-sdk/           # 插件开发 SDK
│   ├── routing/              # 路由系统
│   ├── acp/                  # Agent Client Protocol
│   ├── pairing/              # 设备配对
│   ├── hooks/                # 生命周期钩子
│   ├── terminal/             # 终端输出工具
│   ├── logging/              # 日志系统
│   └── ...
├── extensions/               # 扩展插件（工作区包）
├── apps/                     # 移动应用和 macOS 应用
├── ui/                       # Web UI (dien)
├── docs/                     # 文档
├── skills/                   # 内置技能
└── openclaw.mjs             # CLI 入口点
```

### 2.2 程序入口

```
openclaw.mjs (编译缓存入口)
    └─> src/index.ts
          └─> buildProgram()
                ├─> createProgramContext()
                └─> registerProgramCommands()
```

### 2.3 包导出

```json
{
  "exports": {
    ".": "./dist/index.js",
    "./plugin-sdk": "./dist/plugin-sdk/index.js",
    "./cli-entry": "./openclaw.mjs"
  }
}
```

---

## 3. 核心架构设计

### 3.1 CLI 命令系统

#### 3.1.1 命令注册表模式

CLI 基于 `commander`，采用注册表模式进行命令注册：

```typescript
// src/cli/program/command-registry.ts
export const commandRegistry: CommandRegistration[] = [
  { id: "setup", register: ({ program }) => registerSetupCommand(program) },
  { id: "onboard", register: ({ program }) => registerOnboardCommand(program) },
  { id: "config", register: ({ program }) => registerConfigCli(program) },
  { id: "memory", register: ({ program }) => registerMemoryCli(program) },
  { id: "agent", register: ({ program, ctx }) => registerAgentCommands(program, ctx) },
  // ... 更多命令
];
```

#### 3.1.2 命令分类

| 类别     | 模块            | 示例命令                       |
| -------- | --------------- | ------------------------------ |
| 核心命令 | `src/commands/` | `agent`, `send`, `message`     |
| 配置命令 | `src/config/`   | `config set/get/apply`         |
| 通道命令 | Sub CLI         | `channels status/login/logout` |
| Gateway  | Sub CLI         | `gateway run/stop`             |
| Daemon   | Sub CLI         | `daemon start/stop`            |
| 节点     | Sub CLI         | `nodes list/status`            |

#### 3.1.3 路由机制

```typescript
// src/cli/program/routing.ts
export type RouteSpec = {
  match: (path: string[]) => boolean;
  loadPlugins?: boolean; // 是否加载插件以解析命令
  run: (argv: string[]) => Promise<boolean>;
};
```

路由机制允许快速解析某些命令路径，例如网关模式下直接启动而无需加载所有插件。

---

### 3.2 网关架构

#### 3.2.1 网关启动入口

```
src/gateway/server.impl.ts
  └─> startGatewayServer(port, opts): Promise<GatewayServer>
```

#### 3.2.2 核心子系统

| 子系统     | 实现路径                              | 职责                  |
| ---------- | ------------------------------------- | --------------------- |
| 协议验证   | `src/gateway/protocol/`               | Ajv 验证所有 JSON 帧  |
| 方法处理器 | `src/gateway/server-methods/`         | 各个 gateway 方法实现 |
| 运行时状态 | `src/gateway/server-runtime-state.ts` | 服务器状态、缓冲区    |
| 通道管理   | `src/gateway/server-channels.ts`      | 通道启停              |
| 事件处理   | `src/gateway/server-chat.ts`          | Agent 事件和广播      |
| WebSocket  | `src/gateway/server-ws-runtime.ts`    | WS 连接和帧分发       |
| 配置重载   | `src/gateway/config-reload.ts`        | 监听配置变更          |
| 启动/停止  | `src/gateway/server-close.ts`         | 优雅关闭              |
| 协议定义   | `src/gateway/protocol/`               | 请求/事件帧模式       |

#### 3.2.3 网关启动流程

```
startGatewayServer()
  ├─> 加载配置 (loadConfig)
  ├─> 加载插件 (loadGatewayPlugins)
  │     ├─> 注册插件钩子
  │     ├─> 注册通道插件
  │     └─> 注册自定义 Gateway 方法
  ├─> 创建运行时状态 (createGatewayRuntimeState)
  │     ├─> HTTP 服务器
  │     ├─> WebSocket 服务器
  │     ├─> Canvas Host (a2ui, 端口 18793)
  │     └─> 协议验证 (AJV)
  ├─> 注册状态恢复
  ├─> 注册方法处理器 (coreGatewayHandlers + plugin 处理器)
  ├─> 启动通道 (startChannels)
  ├─> 启动 Cron 服务 (buildGatewayCronService)
  ├─> 配置重载监听 (startGatewayConfigReloader)
  └─> 返回 GatewayServer 实例
```

#### 3.2.4 HTTP 端点

默认端口：`18789`

| 端点                   | 方法      | 用途               |
| ---------------------- | --------- | ------------------ |
| `/ws`                  | WebSocket | 控制和事件流       |
| `/v1/gateway/*`        | POST      | 增量 API 方法      |
| `/v1/chat/completions` | POST      | OpenAI 兼容        |
| `/v1/responses`        | POST      | OpenResponses 兼容 |
| `/media/*`             | GET/PUT   | 媒体服务           |

---

### 3.3 消息通道系统

#### 3.3.1 通道插件化

所有通道必须实现 `ChannelPlugin` 接口：

```typescript
export type ChannelPlugin<ResolvedAccount, Probe, Audit> = {
  id: ChannelId;
  meta: ChannelMeta;
  capabilities: ChannelCapabilities;
  config: ChannelConfigAdapter<ResolvedAccount>;
  configSchema?: ChannelConfigSchema;
  setup?: ChannelSetupAdapter;
  pairing?: ChannelPairingAdapter;
  security?: ChannelSecurityAdapter<ResolvedAccount>;
  groups?: ChannelGroupAdapter;
  mentions?: ChannelMentionAdapter;
  outbound?: ChannelOutboundAdapter;
  status?: ChannelStatusAdapter<ResolvedAccount, Probe, Audit>;
  gatewayMethods?: string[];
  gateway?: ChannelGatewayAdapter<ResolvedAccount>;
  auth?: ChannelAuthAdapter;
  elevated?: ChannelElevatedAdapter;
  commands?: ChannelCommandAdapter;
  streaming?: ChannelStreamingAdapter;
  threading?: ChannelThreadingAdapter;
  messaging?: ChannelMessagingAdapter;
  agentPrompt?: ChannelAgentPromptAdapter;
  directory?: ChannelDirectoryAdapter;
  resolver?: ChannelResolverAdapter;
  actions?: ChannelMessageActionAdapter;
  heartbeat?: ChannelHeartbeatAdapter;
  agentTools?: ChannelAgentToolFactory | ChannelAgentTool[];
};
```

#### 3.3.2 核心适配器

| 适配器                    | 接口                               | 职责       |
| ------------------------- | ---------------------------------- | ---------- |
| `ChannelConfigAdapter`    | `listAccountIds`, `resolveAccount` | 配置解析   |
| `ChannelOutboundAdapter`  | `sendText`, `sendMedia`            | 消息发送   |
| `ChannelGatewayAdapter`   | `startAccount`, `stopAccount`      | 网关启停   |
| `ChannelStatusAdapter`    | `snapshots`, `probe`, `audit`      | 状态探查   |
| `ChannelGroupAdapter`     | `resolveGroup`                     | 群组上下文 |
| `ChannelSecurityAdapter`  | `resolveDMPolicy`                  | 安全策略   |
| `ChannelDirectoryAdapter` | `listGroups`, `listPeers`          | 用户目录   |
| `ChannelAuthAdapter`      | `login`                            | 登录流程   |

#### 3.3.3 内置通道

| 通道         | 实现目录                    |
| ------------ | --------------------------- |
| WhatsApp Web | `src/web/`, `src/whatsapp/` |
| Telegram     | `src/telegram/`             |
| Discord      | `src/discord/`              |
| Slack        | `src/slack/`                |
| Signal       | `src/signal/`               |
| iMessage     | `src/imessage/`             |
| LINE         | `src/line/`                 |
| Google Chat  | `src/googlechat/`           |
| MS Teams     | `src/msteams/`              |

#### 3.3.4 扩展通道

位于 `extensions/*/`：

- `bluebubbles` / `matrix` / `msteams` (extension)
- `tton` / `zalo` / `zalouser`
- `nostr` / `mattermost`
- `nextcloud-talk` / `feishu`

---

### 3.4 媒体管道

#### 3.4.1 核心组件

| 文件           | 职责                                         |
| -------------- | -------------------------------------------- |
| `mime.ts`      | MIME 类型检测（magic number + content type） |
| `parse.ts`     | 消息媒介提取（文本、图片、音频等）           |
| `store.ts`     | 磁盘存储，文件命名 `{original}---{uuid}.ext` |
| `fetch.ts`     | HTTP/HTTPS 远程获取                          |
| `host.ts`      | HTTP 服务，鉴权和 Headers                    |
| `image-ops.ts` | 图片调整大小 (JPEG)                          |
| `audio.ts`     | 音频转换、兼容性检查                         |
| `server.ts`    | HTTP 服务配置                                |

#### 3.4.2 存储结构

```
~/.openclaw/media/
├── inbound/    # 接收的媒体
└── outbound/   # 发送的媒体
```

#### 3.4.3 媒体处理流程

```
入站:
  消息媒介提取
      ↓
  MIME 检测 (magic number)
      ↓
  保存到磁盘 (store.ts)
      ↓
  生成内部 URL

出站:
  媒体上传/处理
      ↓
  MIME 检测
      ↓
  压缩/转换 (可选)
      ↓
  保存到磁盘
      ↓
  通过 HTTP 端点服务
```

---

### 3.5 基础设施层

#### 3.5.1 端口管理

`src/infra/ports.ts`

| 功能                       | 说明               |
| -------------------------- | ------------------ |
| `checkPortAvailability`    | 检查端口是否可用   |
| `killPortOccupyingProcess` | 杀死占用端口的进程 |
| `autoDetectAvailablePort`  | 自动检测可用端口   |
| `DEFAULT_PORT`             | 默认端口 18789     |

#### 3.5.2 SSRF 防护

`src/infra/net/ssrf.ts`

解析主机名并验证是否为安全的内部地址。

#### 3.5.3 事件系统

| 表件                   | 事件类型     |
| ---------------------- | ------------ |
| `diagnostic-events.ts` | 诊断事件     |
| `heartbeat-events.ts`  | 心跳事件     |
| `system-events.ts`     | 系统事件队列 |
| `channel-activity.ts`  | 通道活动跟踪 |

#### 3.5.4 出站传送

`src/infra/outbound/deliver.ts`

支持三种传送模式：

- `single` - 单通道
- `gateway` - 通过网关
- `mixed` - 混合模式

---

## 4. 关键设计模式

### 4.1 依赖注入

#### 4.1.1 CLI 依赖

```typescript
// src/cli/deps.ts
export type CliDeps = {
  sendMessageWhatsApp: typeof sendMessageWhatsApp;
  sendMessageTelegram: typeof sendMessageTelegram;
  sendMessageDiscord: typeof sendMessageDiscord;
  sendMessageSlack: typeof sendMessageSlack;
  sendMessageSignal: typeof sendMessageSignal;
  sendMessageIMessage: typeof sendMessageIMessage;
};

export function createDefaultDeps(): CliDeps {
  return {
    sendMessageWhatsApp,
    sendMessageTelegram,
    sendMessageDiscord,
    sendMessageSlack,
    sendMessageSignal,
    sendMessageIMessage,
  };
}
```

#### 4.1.2 插件运行时依赖

```typescript
// src/plugins/runtime/types.ts
export type PluginRuntime = {
  version: string;
  config: { loadConfig, writeConfigFile };
  system: { enqueueSystemEvent, runCommandWithTimeout };
  media: { loadWebMedia, detectMime, mediaKindFromMime, ... };
  tts: { textToSpeechTelephony };
  tools: { createMemoryGetTool, createMemorySearchTool, ... };
  channel: {
    text: { chunkByNewline, chunkMarkdownText, ... };
    reply: { dispatchReplyWithBufferedBlockDispatcher, ... };
    routing: { resolveAgentRoute };
    pairing: { buildPairingReply, ... };
    network: { fetchRemoteMedia, saveMediaBuffer };
    activity: { record, get };
    session: { resolveStorePath, ... };
    // 各通道特定函数...
  };
  logging: { shouldLogVerbose, getChildLogger };
  state: { resolveStateDir };
};
```

---

### 4.2 状态管理

#### 4.2.1 配置状态

```typescript
// 配置加载流程
loadConfig() → parseConfigJson5() → validateConfigObject() → migrateLegacyConfig()
```

配置文件位置：`~/.openclaw/config.json5`

#### 4.2.2 配置监听和重载

`src/gateway/config-reload.ts`

监听配置文件变更，触发网关状态更新。

#### 4.2.3 通道状态

```typescript
// src/gateway/server-channels.ts
type ChannelRuntime = {
  id: string;
  accountId: string;
  status: Snapshot;
  stop?: () => Promise<void>;
  // ...
};
```

#### 4.2.4 会话状态

会话存储位置：`~/.openclaw/sessions/{channel}/{accountId}/{session}.jsonl`

会话键格式：`session/{agentId}/{channel}/{accountId}/{peer}`

---

### 4.3 消息路由机制

#### 4.3.1 路由解析

```typescript
// src/routing/resolve-route.ts
export type ResolveAgentRouteInput = {
  cfg: OpenClawConfig;
  channel: string;
  accountId?: string | null;
  peer?: RoutePeer | null;
  parentPeer?: RoutePeer | null;
  guildId?: string | null;
  teamId?: string | null;
};

export type ResolvedAgentRoute = {
  agentId: string;
  channel: string;
  accountId: string;
  sessionKey: string;
  mainSessionKey: string;
  matchedBy:
    | "binding.peer"
    | "binding.peer.parent"
    | "binding.guild"
    | "binding.team"
    | "binding.account"
    | "binding.channel"
    | "default";
};
```

#### 4.3.2 路由匹配优先级

```
1. peer (具体用户/组)
2. thread parent peer (继承)
3. guildId (Discord 服务器)
4. teamId (Slack/Teams)
5. account (非通配符)
6. account (通配符)
7. default (默认代理)
```

#### 4.3.3 会话键构建

```typescript
// src/routing/session-key.ts
export function buildAgentSessionKey(params: {
  agentId: string;
  channel: string;
  accountId?: string | null;
  peer?: RoutePeer | null;
  dmScope?: "main" | "per-peer" | "per-channel-peer" | "per-account-channel-peer";
  identityLinks?: Record<string, string[]>;
}): string;
```

---

### 4.4 配置系统

#### 4.4.1 配置模块

```
src/config/
├── types.agent-defaults.ts
├── types.agents.ts
├── types.auth.ts
├── types.base.ts
├── types.browser.ts
├── types.channels.ts
├── types.openclaw.ts
├── types.cron.ts
├── types.sandbox.ts
├── types.memory.ts
├── types.models.ts
├── types.node-host.ts
├── types.tts.ts
├── types.tools.ts
├── types.whatsapp.ts
├── types.imessage.ts
├── types.slack.ts
├── ... (更多通道配置)
├── config.ts (主导出)
└── ...
```

#### 4.4.2 验证机制

使用 Zod 进行模式验证：

```typescript
validateConfigObject(config): ValidationResult
validateConfigObjectWithPlugins(config, plugins): ValidationResult
```

#### 4.4.3 配置迁移

`migrateLegacyConfig()` - 处理旧配置版本的自动迁移。

---

### 4.5 钩子系统

#### 4.5.1 钩子类型

```typescript
// src/hooks/types.ts
export type HookEntry = {
  name: string;
  handler: HookHandler;
  priority?: number;
};

export type HookEvent =
  | "before_agent_start"
  | "after_agent_start"
  | "before_message_send"
  | "after_message_send"
  | "message_received"
  | "tool_called"
  | "config_changed"
  // ... 更多钩子
};
```

#### 4.5.2 钩子注册方式

- 插件通过 `api.registerHook()` 注册
- 优先级按 `priority` 数值排序

---

## 5. 插件扩展机制

### 5.1 插件类型

| 类型       | 说明              | 示例                   |
| ---------- | ----------------- | ---------------------- |
| `memory`   | 内存/向量存储插件 | LanceDB                |
| `channel`  | 通道插件          | Matrix, Zalo           |
| `provider` | 模型提供者插件    | 自定义 OpenAI 兼容 API |

### 5.2 插件 API

```typescript
// src/plugins/types.ts
export type OpenClawPluginDefinition = {
  id?: string;
  name?: string;
  description?: string;
  version?: string;
  kind?: PluginKind; // "channel" | "memory" | "provider" | ...
  configSchema?: OpenClawPluginConfigSchema;
  register?: (api: OpenClawPluginApi) => void | Promise<void>;
  activate?: (api: OpenClawPluginApi) => void | Promise<void>;
};
```

### 5.3 通道插件

参见 [3.3.1 节](#331-通道插件化)。

### 5.4 插件运行时

插件通过 `OpenClawPluginApi.runtime` 访问运行时 API，参见 [4.1.2 节](#412-插件运行时依赖)。

---

## 6. 路由与会话管理

### 6.1 路由解析

详见 [4.3.1 节](#431-路由解析)。

### 6.2 会话结构

```
~/.openclaw/sessions/
└── {channel}/
    └── {accountId}/
        └── {session}.jsonl (JSONL 格式)
```

每行包含：

- `role`: "user" | "assistant"
- `content`: 消息内容
- `timestamp`: 时间戳
- `meta`: 元数据

### 6.3 会话 API

```typescript
loadSessionStore(sessionPath): Promise<Session>
saveSessionStore(sessionPath, session): Promise<void>
updateLastRoute(channel, accountId, route): Promise<void>
```

---

## 7. 模块间关系

### 7.1 CLI 层

```
openclaw.mjs
  └─> src/index.ts
        ├─> createDefaultDeps()
        ├─> buildProgram()
        │     ├─> createProgramContext()
        │     └─> registerProgramCommands()
        │           ├─> registerSetupCommand()
        │           ├─> registerOnboardCommand()
        │           ├─> registerConfigCli()
        │           ├─> registerAgentCommands()
        │           ├─> registerSubCliCommands()
        │           └─> ...
        └─> 程序解析 → 各命令处理器
```

### 7.2 Gateway 层

```
startGatewayServer()
  ├─> 配置加载 (loadConfig)
  ├─> 插件加载 (loadGatewayPlugins)
  │     ├─> 插件注册表
  │     └─> 通道插件 (listChannelPlugins)
  ├─> 运行时状态 (createGatewayRuntimeState)
  │     ├─> HTTP 服务器
  │     ├─> WebSocket 服务器
  │     ├─> Canvas Host (a2ui)
  │     └─> 协议验证 (AJV)
  ├─> 方法处理器
  ├─> 事件广播
  ├─> 通道管理器
  ├─> Cron 服务
  ├─> 节点注册
  └─> 配置重载
```

### 7.3 消息流转

```
入站:
  平台消息 → 通道适配器 → Gateway 事件 → 路由解析 → Agent 执行 → 出站

出站:
  CLI/Web/App → Gateway 方法 → 根据路由分发 → 通道适配器 → 平台
```

---

## 8. 通信协议

### 8.1 Gateway Protocol

详见 `docs/concepts/architecture.md` 和 `docs/gateway/protocol.md`。

核心帧类型：

```typescript
export type GatewayFrame =
  | RequestFrame // {type:"req", id, method, params}
  | ResponseFrame // {type:"res", id, ok, payload|error}
  | EventFrame; // {type:"event", event, payload, seq?, stateVersion?}
```

#### 事件类型

- `agent` - Agent 执行事件
- `chat` - 聊天更新
- `presence` - 在线状态
- `health` - 健康状态
- `heartbeat` - 心跳
- `cron` - Cron 任务
- `tick` - 定时脉冲

#### 常用 Gateway 方法

| 方法              | 功能         |
| ----------------- | ------------ |
| `health`          | 健康检查     |
| `status`          | 状态查询     |
| `send`            | 发送消息     |
| `agent`           | 启动 Agent   |
| `channels.list`   | 列出通道账户 |
| `channels.status` | 通道状态     |
| `channels.login`  | 通道登录     |

### 8.2 ACP (Agent Client Protocol)

位于 `src/acp/`，用于 Agent 与客户端的通信。

---

## 9. 认证与安全

### 9.1 设备配对

新建设备 ID 需要配对批准：

- 本地连接：自动批准
- 远程连接：需要显式批准
- 挑战签名：防止劫持

设备令牌存储在 `~/.openclaw/device-tokens.json`。

### 9.2 Gateway 认证

```typescript
// src/config/auth.ts
export type GatewayAuth = {
  token?: string; // Bearer Token 检查
  allowed?: string[]; // 允许的设备 ID
};
```

### 9.3 SSRF 防护

`src/infra/net/ssrf.ts` - 防止服务器端请求伪造。

---

## 10. 测试策略

### 10.1 测试框架

- **框架**：Vitest
- **覆盖率**：V8
- **阈值**：70% (线/分/函数/语句)

### 10.2 测试类型

| 类型     | 后缀            | 说明         |
| -------- | --------------- | ------------ |
| 单元测试 | `*.test.ts`     | 功能单元测试 |
| E2E 测试 | `*.e2e.test.ts` | 端到端测试   |

### 10.3 测试命令

```bash
pnpm test                 # 运行所有测试
pnpm test:coverage        # 运行测试并生成覆盖率报告
pnpm test:live            # 运行 Live 测试 (需要真实凭证)
```

---

## 11. 构建与部署

### 11.1 构建命令

```bash
pnpm build        # 完整构建
pnpm tsgo         # TypeScript 类型检查
pnpm check        # Lint + Format
```

### 11.2 macOS 应用打包

```bash
scripts/package-mac-app.sh
```

### 11.3 发布流程

详解见 `docs/platforms/mac/release.md` 和 `docs/reference/RELEASING.md`。

发布通道：

- **stable**: 版本标签 (v2026.2.4) + npm tag `latest`
- **beta**: 预发布标签 (v2026.2.4-beta.N) + npm tag `beta`
- **dev**: main 分支头部 (无标签)

---

## 12. 编码规范

### 12.1 语言与风格

- **语言**：TypeScript (ESM)
- **严格类型**：避免 `any`
- **格式化**：Oxlint + Oxfmt
- **文件大小**：目标 < ~700 LOC

### 12.2 命名规范

- **产品/文档标题**：OpenClaw (大写)
- **CLI 命令**：openclaw (小写)
- **包/二进制名**：openclaw (小写)
- **配置键**：openclaw (小写)

### 12.3 代码注释

为复杂或非显而易见的逻辑添加简短注释。

### 12.4 终端输出

- **进度条**：`src/cli/progress.ts` (osc-progress + @clack/prompts)
- **表格**：`src/terminal/table.ts` (ANSI 安全换行)

### 12.5 多 Agent 安全

- 不创建/应用/删除 git stash 除非明确要求
- 不删除/修改 git worktree 除非明确要求
- 尊重其他 Agent 的工作

---

## 13. 附录：代码示例

### 13.1 注册插件钩子

```typescript
export default function register(api: OpenClawPluginApi) {
  api.on("before_agent_start", async (event, ctx) => {
    console.log("Agent starting:", ctx.agentId);
    return {
      systemPrompt: "Custom system prompt...",
      prependContext: "Extended context...\n",
    };
  });

  api.on("message_received", async (event, ctx) => {
    console.log("Received:", event.content);
  });
}
```

### 13.2 注册自定义命令

```typescript
api.registerCommand({
  name: "tts",
  description: "Text to speech",
  acceptsArgs: true,
  requireAuth: true,
  handler: async (ctx) => {
    const text = ctx.args || "";
    // ... 处理 tts 并回复
    return { text: `Speaking: ${text}` };
  },
});
```

### 13.3 注册通道

```typescript
api.registerChannel({
  id: "mychannel" as ChannelId,
  meta: {
    id: "mychannel" as ChannelId,
    label: "My Channel",
    selectionLabel: "My Channel",
    docsPath: "/channels/mychannel",
    blurb: "My custom channel implementation",
  },
  capabilities: {
    chatTypes: ["dm", "group"],
    media: true,
    reactions: true,
    reply: true,
  },
  config: {
    listAccountIds: (cfg) => Object.keys(cfg.mychannel?.accounts ?? {}),
    resolveAccount: (cfg, accountId) => cfg.mychannel?.accounts?.[accountId] ?? {},
    defaultAccountId: (cfg) => "default",
  },
  outbound: {
    deliveryMode: "gateway",
    sendText: async (ctx) => {
      // 发送文本到平台
      return { ok: true };
    },
  },
  gatewayMethods: ["mychannel.send"],
  gateway: {
    startAccount: async (ctx) => {
      // 启动通道监听器
    },
    stopAccount: async (ctx) => {
      // 停止通道监听器
    },
  },
});
```

### 13.4 使用插件 SDK

```typescript
import {
  registerTool,
  resolveAgentRoute,
  loadConfig,
  dispatchReplyWithBufferedBlockDispatcher,
} from 'openclaw/plugin-sdk';

export default function register(api: OpenClawPluginApi) {
  const tool = {
    type: 'function',
    name: 'mytool',
    description: 'My custom tool',
    parameters: {
      type: 'object',
      properties: {},
      additionalProperties: false,
    },
    handler: async ({ accountId, messageChannel, agentId, ... }) => {
      // 处理工具
      return {
        success: true,
        content: [],
        data: undefined,
      };
    },
  };
  api.registerTool(tool);
}
```

---

## 参考资料

- [Gateway Architecture](/docs/concepts/architecture.md)
- [Gateway Protocol](/docs/gateway/protocol.md)
- [提交 PR 指南](/docs/help/submitting-a-pr.md)
- [提交 Issue 指南](/docs/help/submitting-an-issue.md)
- [测试文档](/docs/testing.md)
- [发布文档](/docs/reference/RELEASING.md)
- [macOS 发布](/docs/platforms/mac/release.md)

---

**文档结束**