1
                     "我发了一条消息给 OpenClaw"
2

3
┌─────────────────────────────────────────────────────────────┐
4
│                      EXTERNAL WORLD                          │
5
│                                                               │
6
│   WhatsApp  Telegram  Discord  iMessage  Signal  Slack  ...  │
7
│      │         │         │         │        │       │        │
8
│      └─────────┴─────────┴─────────┴────────┴───────┘        │
9
│                            │                                  │
10
│                  ┌─────────▼─────────┐                        │
11
│                  │   CHANNELS 层     │  ← 消息 I/O 层         │
12
│                  │  (src/channels/)  │    每个 channel 负责    │
13
│                  │  + extensions/    │    connect/monitor/     │
14
│                  │                   │    send/receive         │
15
│                  └─────────┬─────────┘                        │
16
│                            │                                  │
17
│                  ┌─────────▼─────────┐                        │
18
│                  │   GATEWAY 层       │  ← 控制面              │
19
│                  │  (src/gateway/)   │    消息路由             │
20
│                  │                   │    鉴权与授权           │
21
│                  │  ┌─────────────┐  │    WebSocket RPC 协议   │
22
│                  │  │  Protocol   │  │                        │
23
│                  │  └─────────────┘  │                        │
24
│                  └─────────┬─────────┘                        │
25
│                            │                                  │
26
│          ┌─────────────────┼─────────────────┐               │
27
│          │                 │                 │               │
28
│   ┌──────▼──────┐  ┌───────▼───────┐  ┌──────▼──────┐       │
29
│   │   AGENTS    │  │   COMMANDS    │  │    HOOKS    │       │
30
│   │ (src/agents)│  │ (src/commands)│  │ (src/hooks) │       │
31
│   │             │  │               │  │             │       │
32
│   │ Agent 运行时 │  │ Agent 命令     │  │ 生命周期切面  │       │
33
│   │ Model 选择  │  │ 对话执行       │  │ 消息/工具拦截 │       │
34
│   │ Provider对接│  │               │  │ 回复编辑     │       │
35
│   └──────┬──────┘  └───────────────┘  └──────┬──────┘       │
36
│          │                                   │              │
37
│          │         ┌──────────┐              │              │
38
│          ├────────>│  TOOLS   │<─────────────┘              │
39
│          │         │(src/tools)│                              │
40
│          │         │ 工具注册  │                              │
41
│          │         │ 工具发现  │                              │
42
│          │         │ 工具执行  │                              │
43
│          │         │ MCP 桥接 │                              │
44
│          │         └──────────┘                              │
45
│          │                                                   │
46
│          │  ┌───────────────┐                                │
47
│          ├─>│   SESSIONS    │  ← 对话状态                    │
48
│          │  │ (src/sessions)│    session key 路由            │
49
│          │  └───────────────┘                                │
50
│          │                                                   │
51
│          │  ┌───────────────┐                                │
52
│          └─>│   MEMORY      │  ← 长期记忆                    │
53
│             │ (src/memory)  │    MEMORY.md 文件              │
54
│             └───────────────┘                                │
55
│                                                               │
56
│  ┌────────────────────────────────────────────────────────┐  │
57
│  │              PLUGIN SYSTEM  (贯穿所有层)                 │  │
58
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │  │
59
│  │  │ Plugin SDK   │  │   Registry   │  │   Loader     │  │  │
60
│  │  │ (对外的接口)  │  │  (插件注册表) │  │  (插件加载器) │  │  │
61
│  │  └──────────────┘  └──────────────┘  └──────────────┘  │  │
62
│  └────────────────────────────────────────────────────────┘  │
63
│                                                               │
64
│  ┌────────────────────────────────────────────────────────┐  │
65
│  │              CONFIGURATION  (贯穿所有层)                 │  │
66
│  │  Zod Schema → IO → Validation → Legacy Migration        │  │
67
│  └────────────────────────────────────────────────────────┘  │
68
│                                                               │
69
│  ┌────────────────────────────────────────────────────────┐  │
70
│  │              CLI + DAEMON  (驱动层)                      │  │
71
│  │  entry.ts → CLI 命令路由 → Daemon 进程管理               │  │
72
│  └────────────────────────────────────────────────────────┘  │
73
└─────────────────────────────────────────────────────────────┘

1
1. 用户在 WhatsApp 里发送 "帮我查一下天气"
2

3
2. WhatsApp Channel (extensions/whatsapp)
4
   ├── monitor 线程收到 webhook
5
   ├── 解析消息：文本、sender、chat id
6
   ├── check allowFrom / allowlist
7
   └── 通过 Gateway protocol 转发消息
8

9
3. Gateway (src/gateway/)
10
   ├── 收到 RPC 请求：agent.call
11
   ├── verify auth (token / device identity)
12
   ├── 根据 session key 路由到正确的 Agent
13
   └── 转发给 Agent
14

15
4. Agent (src/agents/)
16
   ├── resolve agent config (model, workspace, skills)
17
   ├── load session history (transcript)
18
   ├── resolve tool plan (哪些 tools 可用)
19
   ├── 调用 AI model API
20
   │   ├── system prompt + history + user message
21
   │   ├── model 决定调用 web_search tool
22
   │   ├── Agent 执行 tool → 获得天气信息
23
   │   └── model 生成最终回复
24
   └── 返回 reply + session update
25

26
5. Gateway
27
   ├── 收到 agent 回复
28
   ├── hooks：before-agent-reply（可以编辑/拦截）
29
   └── 通过 WhatsApp Channel 发回
30

31
6. WhatsApp Channel
32
   ├── 格式化消息（Markdown → WhatsApp 格式）
33
   └── send API → 用户收到回复

1
// 1. 确保这是主模块（不是被 import 的）
2
if (!isMainModule({ currentFile, wrapperEntryPairs: [...] })) {
3
  // 被作为依赖 import 了 → 什么都不做
4
} else {
5
  // 2. 设置进程元数据
6
  process.title = "openclaw";
7
  ensureOpenClawExecMarkerOnProcess();
8
  installProcessWarningFilter();
9

10
  // 3. 启用编译缓存（加速后续 require）
11
  enableOpenClawCompileCache({ installRoot });
12

13
  // 4. 处理 --profile / --dev 等环境切换
14
  const parsed = parseCliProfileArgs(process.argv);
15

16
  // 5. 处理版本快速路径（--version / -V）
17
  if (!tryHandleRootVersionFastPath(process.argv)) {
18
    // 6. 真正的 CLI 入口
19
    await runMainOrRootHelp(process.argv);
20
  }
21
}

1
openclaw
2
├── onboard          # 首次配置向导
3
├── gateway          # Gateway 管理 (start/stop/restart/status)
4
├── agent            # Agent 交互
5
├── agents           # Agent 管理 (add/list/delete/bind/identity)
6
├── channels         # 渠道管理
7
├── plugins          # 插件管理 (install/uninstall/list/update)
8
├── secrets          # 密钥管理
9
├── dashboard        # 打开 Web 控制面板
10
├── doctor           # 诊断修复
11
└── cron             # 定时任务

1
export type GatewayService = {
2
  label: string;
3
  stage: (args) => Promise<void>;     // 准备配置
4
  install: (args) => Promise<void>;   // 安装服务
5
  uninstall: (args) => Promise<void>; // 卸载服务
6
  stop: (args) => Promise<void>;      // 停止服务
7
  restart: (args) => Promise<...>;    // 重启服务
8
  isLoaded: (args) => Promise<boolean>;
9
  readCommand: (env) => Promise<...>;
10
  readRuntime: (env) => Promise<...>;
11
};

1
export async function runBootOnce(params): Promise<BootRunResult> {
2
  // 1. 加载 workspace 下的 BOOT.md 文件
3
  const result = await loadBootFile(params.workspaceDir);
4
  if (result.status === "missing" || result.status === "empty") {
5
    return { status: "skipped", reason: result.status };
6
  }
7
  // 2. 构建 boot prompt，让 Agent 执行 BOOT.md 中的指令
8
  const message = buildBootPrompt(result.content);
9
  // 3. 创建临时 session，运行 agent
10
  // 4. 保存当前 session 快照（boot 后恢复）
11
  // 5. 执行 agent 命令
12
  await agentCommand({ message, sessionKey, ... });
13
  // 6. 恢复 session mapping
14
  await restoreMainSessionMapping(mappingSnapshot);
15
}

1
1. Explicit token (--token 参数直接传入)
2
2. Explicit password (--password 参数)
3
3. Config-based credential (openclaw.json 中的 gateway.token)
4
4. Device identity (设备指纹，loopback 连接自动启用)

1
export function ensureExplicitGatewayAuth(params) {
2
  // URL overrides are untrusted redirects
3
  // Never allow an override to silently reuse implicit credentials
4
  if (params.urlOverride && !hasExplicitAuth) {
5
    throw new Error("gateway url override requires explicit credentials");
6
  }
7
}

1
Client                    Gateway
2
  │── WS Connect ───────────>│
3
  │── Hello ────────────────>│  { clientName, version, platform, scopes, deviceIdentity }
4
  │<── Hello Ok ─────────────│  { version, features: { methods[] } }
5
  │── Request ──────────────>│  { method: "agent.call", params: {...} }
6
  │<── Response ─────────────│  { result: {...} }

1
sessionKey = "agentId:channelId:accountId:chatType:chatId:threadId"
2

3
示例：
4
"main:telegram:mybot:direct:12345678:"
5
"coding:discord:myserver:channel:87654321:thread_001"

1
export function parseAgentSessionKey(sessionKey: string) {
2
  const parts = sessionKey.split(":");
3
  return { agentId, channelId, accountId, chatType, chatId, threadId };
4
}

1
┌─────────────────────────────────────────────┐
2
│  External Channel Plugins (ClawHub/npm)     │  社区/第三方维护
3
├─────────────────────────────────────────────┤
4
│  Bundled Channel Plugins (extensions/)       │  随 OpenClaw 发布的可选渠道
5
│  Telegram, Discord, iMessage, Matrix 等      │
6
├─────────────────────────────────────────────┤
7
│  Built-in Channels (src/channels/)           │  核心内置
8
│  WhatsApp, Slack, Signal, WebChat 等         │
9
└─────────────────────────────────────────────┘

1
// src/channels/plugins/types.plugin.ts 和 types.core.ts
2
export type ChannelPlugin = {
3
  id: ChannelId;                    // telegram, whatsapp, discord...
4
  meta: ChannelMeta;                // 名称、描述、版本
5

6
  messaging?: ChannelMessagingAdapter;     // 收发消息
7
  pairing?: ChannelPairingAdapter;         // 设备配对（如 WhatsApp 扫码）
8
  security?: ChannelSecurityAdapter;       // DM/allowFrom/mention 规则
9
  threading?: ChannelThreadingAdapter;     // 线程/话题管理
10
  outbound?: ChannelOutboundAdapter;       // 出站格式化
11

12
  agentTools?: ChannelAgentTool[];         // 注册给 Agent 的工具
13
  messageToolDiscovery?: ChannelMessageToolDiscovery; // message tool schema 扩展
14
};

1
1. Telegram API → webhook/长轮询 → 解析 Update 对象
2
2. 消息解析 → 文本/图片选最高分辨率/语音下载/文件下载
3
3. 安全检查 → allowFrom / group @mention 检查 / DM policy
4
4. 构建 Internal Message → channelId, accountId, sessionKey, senderId, messageId

1
1. Agent 执行完毕 → reply
2
2. before-agent-reply hook → 可以编辑/拦截/替换回复
3
3. Channel outbound adapter → Markdown → 各平台的特定格式
4
4. Send → 调用平台 API 发送

1
// 每个 channel 可独立配置安全策略：
2
config.channels.whatsapp.allowFrom = ["+15555550123"];  // 白名单
3
config.channels.whatsapp.groups["*"].requireMention = true; // 群聊必须 @bot

1
Agent
2
├── Identity（身份）
3
│   ├── id: "main" | "coding" | "personal" | ...
4
│   └── system prompt
5
├── Model（模型）
6
│   ├── primary: "claude-sonnet-4-6"
7
│   ├── fallbacks: ["gpt-5.5", ...]
8
│   └── params (temperature, max_tokens, thinking)
9
├── Workspace（工作空间）
10
│   ├── workspaceDir: ~/.openclaw/agents/<id>/workspace
11
│   ├── MEMORY.md
12
│   └── skills files
13
├── Skills（技能）
14
│   └── skill filter: ["coding", "general"]
15
└── Provider（提供商）
16
    ├── auth profile
17
    └── API endpoint

1
export function resolveSessionAgentId(params: {
2
  sessionKey?: string;
3
  config?: OpenClawConfig;
4
  agentId?: string;
5
}): string {
6
  const defaultAgentId = resolveDefaultAgentId(params.config ?? {});
7
  const explicitAgentId = normalizeAgentId(params.agentId);
8
  const parsed = parseAgentSessionKey(normalizedSessionKey);
9
  return explicitAgentId ?? (parsed?.agentId ? normalizeAgentId(parsed.agentId) : defaultAgentId);
10
}

1
// Provider 插件接口（简化版）
2
type ProviderPlugin = {
3
  id: string;                        // "openai-codex", "anthropic", ...
4
  catalog: ProviderCatalogContext;   // 注册 model 列表
5
  auth: ProviderAuthMethod;          // api-key | oauth | env | external-cli
6
  runtime: ProviderRuntime;          // 实际的 API 调用（createChatCompletion 等）
7
  model?: {
8
    normalizeToolSchemas?: ...;      // tool schema 格式转换（各家不同）
9
    streaming?: ...;                 // 流式输出策略
10
    thinking?: ...;                  // extended thinking 策略
11
  };
12
};

1
1. 解析 Agent 配置 (model, workspace, skills)
2
2. 加载 session 历史 (transcript)
3
3. 确定可用的 tools (tool plan)
4
4. 构建 system prompt (base + memory + skills + ...)
5
5. 调用 model API（可能多轮 tool calling）:
6
   model 回复 → 如果调用了 tool → 执行 tool → 把结果发回 model → 继续
7
6. 保存 transcript
8
7. deliver reply 到 channel

1
openclaw.json (~/.openclaw/openclaw.json)
2
        │
3
┌───────▼──────────┐  Types Layer: 30+ 个类型文件
4
│    类型定义        │  types.openclaw.ts, types.agents.ts, types.channels.ts, ...
5
└───────┬──────────┘
6
        │
7
┌───────▼──────────┐  Schema Layer: Zod 验证
8
│    Zod Schema     │  zod-schema.core.ts, zod-schema.agents.ts, ...
9
└───────┬──────────┘
10
        │
11
┌───────▼──────────┐  IO Layer: 读写、merge patch、redact snapshot
12
│       IO          │  io.ts, merge-patch.ts, redact-snapshot.ts
13
└───────┬──────────┘
14
        │
15
┌───────▼──────────┐  Validation Layer: 运行时验证
16
│    Validation     │  validation.ts, schema.ts
17
└──────────────────┘

1
export const agentModelSchema = z.object({
2
  primary: z.string().optional(),
3
  fallbacks: z.array(z.string()).optional(),
4
});
5
// z.infer<typeof agentModelSchema> → 得到 TypeScript 类型

1
脱敏前：{ channels: { telegram: { botToken: "123456:ABC-DEF1234ghijk" } } }
2
脱敏后：{ channels: { telegram: { botToken: "123***hijk" } } }

1
  npm 包 / 本地目录 / ClawHub / Git URL
2
         │
3
         ▼
4
  ① Discovery — 扫描所有可能位置，只收集候选，不加载代码
5
         │
6
         ▼
7
  ② Manifest 验证 — 解析 openclaw.plugin.json
8
         │
9
         ▼
10
  ③ Install — 下载、解压、安全检查（如需要）
11
         │
12
         ▼
13
  ④ Loader — 动态 import() JS 代码
14
         │
15
         ▼
16
  ⑤ Registry — 将插件的能力注册到全局注册表
17
         │
18
         ▼
19
  ⑥ Runtime — 插件 API 可用，hooks/tools 生效

1
type PluginRegistry = {
2
  plugins: LoadedPlugin[];
3
  channels?: ChannelPlugin[];
4
  providers?: ProviderRegistration[];
5
  tools?: ToolDescriptor[];
6
  commands?: PluginCommandDef[];
7
  hooks?: HookRegistration[];
8
  httpRoutes?: HttpRouteRegistration[];
9
  sessionExtensions?: SessionExt[];
10
  agentEventSubscriptions?: AgentEvent[];
11
  runtimeLifecycles?: Lifecycle[];
12
  sessionSchedulerJobs?: SchedulerJob[];
13
};

1
         definePlugin()
2
              │
3
   ┌──────────┼──────────────┐
4
   │          │              │
5
   ▼          ▼              ▼
6
provider    channel         tool
7
注册模型    注册渠道         注册新工具
8
认证方式    消息收发         到 Agent
9
API 调用   安全策略
10

11
   ┌──────────┼──────────────┐
12
   │          │              │
13
   ▼          ▼              ▼
14
memory      hook          cli-command
15
记忆后端   运行时切面      新的 CLI 命令
16
嵌入模型   事件拦截         终端操作
17

18
   ┌──────────┼──────────────┐
19
   │          │              │
20
   ▼          ▼              ▼
21
http-route  session-ext   compaction
22
HTTP 端点   Session 扩展   对话压缩策略

1
type ProviderPluginDefinition = {
2
  id: string;                           // "openai-codex", "anthropic", ...
3
  catalog(context): ProviderCatalogResult;   // 注册 model 列表
4
  auth: ProviderAuthMethod;             // "api-key" | "oauth" | "env" | "external-cli"
5
  runtime: ProviderRuntime;             // createChatCompletion, streaming, ...
6
  normalizeResolvedModel?(context): string; // 简写 → 完整 model ID
7
  normalizeToolSchemas?(context): ToolSchema[]; // tool schema 格式适配
8
};

1
type ToolOwnerRef =
2
  | { kind: "core" }
3
  | { kind: "plugin"; pluginId: string }
4
  | { kind: "channel"; channelId: string }
5
  | { kind: "mcp"; serverId: string };
6

7
type ToolExecutorRef =
8
  | { kind: "core"; executorId: string }
9
  | { kind: "plugin"; pluginId: string; toolName: string }
10
  | { kind: "channel"; channelId: string; actionId: string }
11
  | { kind: "mcp"; serverId: string; toolName: string };

1
type ToolAvailabilitySignal =
2
  | { kind: "always" }                                   // 永远可用
3
  | { kind: "auth"; providerId: string }                  // 有 auth 时可用
4
  | { kind: "config"; path: string[]; check: "exists" }   // 有某配置时可用
5
  | { kind: "env"; name: string }                         // 有环境变量时可用
6
  | { kind: "plugin-enabled"; pluginId: string }          // 某插件启用时可用
7
  | { kind: "context"; key: string; equals?: JsonPrimitive }; // 上下文匹配时可用

1
    消息到达
2
       │
3
       ▼
4
  [message:received]  ← 消息到达时
5
       │
6
       ▼
7
  [agent:bootstrap]   ← Agent 首次启动
8
       │
9
       ▼
10
  [before-agent-start] ← Agent 开始执行前
11
       │
12
       ▼
13
  Agent 执行中...
14
       │
15
       ▼
16
  [before-tool-call]  ← 每个 tool 调用前
17
       │
18
       ▼
19
  [compaction]        ← 对话压缩时
20
       │
21
       ▼
22
  [before-agent-reply] ← 回复发送前（可编辑！）
23
       │
24
       ▼
25
  [message:sent]      ← 消息已发送
26
       │
27
       ▼
28
  [agent:finalize]    ← Agent 结束

1
// Hook 通过 Plugin 注册
2
definePlugin({
3
  id: "my-hooks",
4
  hooks: [
5
    {
6
      event: "before-agent-reply",
7
      handler: async (ctx) => {
8
        // 可以修改 ctx.reply
9
        ctx.reply = `[安全声明] ${ctx.reply}`;
10
        return { action: "continue" };
11
      },
12
    },
13
  ],
14
});

1
  Tool 来源: Core / Plugin / Channel / MCP
2
        │
3
        ▼
4
  Tool Registry (descriptors) → 所有工具的注册表
5
        │
6
        ▼
7
  Tool Plan (visible + hidden) → 根据动态可用性筛选
8
        │
9
        ▼
10
  Tool Execution (execute) → 实际的工具执行

1
type ToolDescriptor = {
2
  readonly name: string;                // "web_search", "exec", "message", ...
3
  readonly description: string;         // 给 AI model 看的描述
4
  readonly inputSchema: JsonObject;     // 输入参数的 JSON Schema
5
  readonly owner: ToolOwnerRef;         // 谁拥有这个工具
6
  readonly executor?: ToolExecutorRef;  // 谁执行这个工具（可能不同于 owner！）
7
  readonly availability?: ToolAvailabilityExpression; // 动态可用性条件
8
};

1
  OpenClaw 作为 MCP Client → 连接 External MCP Server (外部工具/数据源)
2
  OpenClaw 作为 MCP Server → 被 Other MCP Client 连接

1
  ┌─────────────────────────────┐
2
  │        MEMORY (长期)        │
3
  │  用户偏好、身份、持续任务    │
4
  │  永久（直到显式修改/删除）    │
5
  │  MEMORY.md / Memory 插件    │
6
  └──────────────┬──────────────┘
7
                 │
8
  ┌──────────────▼──────────────┐
9
  │       SESSION (短期)        │
10
  │  本轮/近几轮的对话消息        │
11
  │  Agent 执行期间 + 对话窗口   │
12
  │  Session Store (JSON 文件)   │
13
  └─────────────────────────────┘

1
export const CANONICAL_ROOT_MEMORY_FILENAME = "MEMORY.md";

1
~/.openclaw/
2
  ├── openclaw.json              # Gateway auth (gateway.token)
3
  └── agents/<id>/agent/
4
      └── auth-profiles.json     # Agent 的 AI 模型 API keys

1
// ❌ 危险：直接写在配置里
2
channels.telegram.botToken = "123456:ABC-DEF1234ghijk"
3

4
// ✅ 安全：引用外部 secret
5
channels.telegram.botToken = { $secretRef: "telegram/bot-token" }

1
{
2
  "sandbox": {
3
    "mode": "docker",              // docker | local
4
    "docker": {
5
      "networkMode": "none",       // 隔离网络
6
      "readOnlyRootfs": true,      // 只读文件系统
7
      "mounts": [...]              // 只有显式 mount 的路径可写
8
    }
9
  }
10
}

1
Approval Handler:
2
├── Native Route → 推送到手机 App
3
├── CLI Route → 终端交互式输入
4
├── Web Route → Web Control UI 弹窗
5
└── Auto-Approve → 配置的白名单自动批准

1
{
2
  "channels": {
3
    "whatsapp": {
4
      "allowFrom": ["+15555550123"]   // 只有这个用户能触发 Agent
5
    }
6
  },
7
  "tools": {
8
    "deny": ["exec:rm-rf"]   // 禁止特定命令
9
  }
10
}

1
                   Gateway (Linux/macOS 服务器)
2
                        │
3
       ┌────────────────┼──────────────────┐
4
       │                │                  │
5
  macOS App         iOS Node          Android Node
6
(SwiftUI)          (SwiftUI)         (Kotlin/Jetpack)
7
       │                │                  │
8
       └────────────────┼──────────────────┘
9
                        │
10
               WebSocket RPC
11
          (与 CLI 同样的 Gateway Protocol)

1
1. 手机 App 上点击 "Pair with Gateway"
2
2. Gateway 生成配对码（显示在 CLI 或 Web UI）
3
3. 手机扫码或手动输入
4
4. 通过安全配对协议交换 credential
5
5. 配对成功 → 手机成为 Gateway 的一个 "Node"

1
Agent 生成 Canvas JSON 描述
2
  → 移动端 App 渲染原生 UI 组件
3
    → 用户交互（滑动、点击、输入）
4
      → 交互结果返回给 Agent

1
const log = createSubsystemLogger("gateway/boot");
2
const log = createSubsystemLogger("plugins/runtime");
3
const log = createSubsystemLogger("channels/telegram");