架构 on SkySeraph

CC源码剖析 #01 · 整体架构概览：目录结构与模块划分

Fri, 01 May 2026 08:00:00 +0800

基于 2026-03-31 公开的源码快照，~512,000 行代码

一、项目背景

Claude Code 源码于 2026 年 3 月 31 日通过 npm 包中的 .map 文件意外暴露，指向 Anthropic R2 存储桶中未经混淆的 TypeScript 源码。此镜像仅用于教育、安全研究和软件供应链分析。

语言：TypeScript（strict 模式）
运行时：Bun
终端 UI：React + Ink
规模：约 1,900 个文件，512,000+ 行代码

二、顶层目录结构

C:\dev\claude\claude-code\
├── src/ # 全部业务逻辑
├── .vscode/ # VSCode 调试配置
├── README.md # 研究背景文档（非官方）
└── package.json

三、`src/` 模块全景图

3.1 核心运行模块

目录	文件数(估)	核心职责
`tools/`	~40	Tool 定义、注册、执行（FileEdit/Bash/Grep 等）
`commands/`	~50	Slash Commands 实现（/commit /review /diff 等）
`coordinator/`	-	多 Agent 任务编排与协调
`assistant/`	-	会话历史、Session 管理
`buddy/`	-	Companion 对话伙伴（sprite/prompt）

3.2 通信层

目录	核心职责
`bridge/`	最重要：IDE（VSCode/JetBrains）与 CLI 之间的双向通信
`remote/`	远程会话管理
`server/`	服务端模式

3.3 任务与状态

目录	核心职责
`tasks/`	Task 的创建、执行、状态追踪
`state/`	状态管理
`memdir/`	内存目录与会话持久化（~Memory 功能核心）
`skills/`	Skill 加载与执行系统

3.4 UI 与交互

目录	核心职责
`ink/`	Ink（React for CLI）渲染封装
`components/`	~140 个 Ink UI 组件
`screens/`	全屏 UI（Doctor/REPL/Resume）
`entrypoints/`	各端点初始化（CLI/VSCode/Remote）

3.5 生态扩展

目录	核心职责
`plugins/`	插件系统
`mcp/`	Model Context Protocol 服务连接
`services/`	API/OAuth/LSP/Analytics 等外部集成

3.6 其他

目录	说明
`hooks/`	React 生命周期钩子
`types/`	核心 TypeScript 类型定义
`schemas/`	Zod 配置模式验证
`migrations/`	配置迁移
`keybindings/`	快捷键配置
`vim/`	Vim 模式支持
`voice/`	语音输入
`upstreamproxy/`	代理配置
`native-ts/`	原生 TS 工具函数
`outputStyles/`	输出样式
`bootstrap/`	启动初始化

四、最关键模块详解

4.1 `tools/` — 工具系统（Agent 的"手"）

Claude Code 的 Agent 通过 Tool 与外界交互。每个 Tool 都是一个自包含模块：

CC源码剖析 #02 · 入口点解析：从 CLI 到 REPL

Fri, 01 May 2026 08:00:00 +0800

基于 2026-03-31 公开的源码快照，~512,000 行代码

一、整体启动流程

Claude Code 的启动链路非常清晰：

main.tsx（入口）
 ├── Commander.js CLI 解析
 ├── 并行预加载（MDM配置/Keychain/API预连接/GrowthBook）
 ├── Ink React 渲染
 │ ├── commands.ts 注册 Slash Commands
 │ ├── tools.ts 注册 Tool
 │ ├── QueryEngine 初始化
 │ └── REPL.tsx 主交互界面

二、`main.tsx` — 入口编排

文件：src/main.tsx，约 4,000 行

2.1 启动顺序

第一步：模块加载前的副作用（必须先执行）

1
2
3
4


// 这些副作用必须在所有 import 之前执行
profileCheckpoint('main_tsx_entry');
startMdmRawRead(); // 并行读取 MDM 配置（macOS 企业配置）
startKeychainPrefetch(); // 并行读取 Keychain（OAuth + API Key）

这三个调用 firing 了三个独立子进程并行获取配置数据，为后续初始化节省 ~65ms。

CC源码剖析 #03 · Bridge 模块：主进程与渲染进程的通信机制

Fri, 01 May 2026 08:00:00 +0800

基于 2026-03-31 公开的源码快照，~512,000 行代码

一、Bridge 在整个架构中的位置

Bridge 是 Claude Code 最复杂的模块，负责 IDE 扩展（VSCode/JetBrains）与 CLI 进程之间的双向通信。

┌─────────────────────────────────────────────────────────────┐
│ Claude.ai Web │
│ (Remote Control UI) │
└──────────────────────────┬──────────────────────────────────┘
 │ WebSocket / HTTPS
┌──────────────────────────▼──────────────────────────────────┐
│ Bridge Module │
│ src/bridge/ │
│ ├── bridgeMain.ts # 主循环：轮询 + 会话管理 │
│ ├── bridgeApi.ts # REST API 客户端 │
│ ├── replBridge.ts # REPL ↔ Bridge 桥接核心 │
│ ├── replBridgeTransport.ts # WebSocket 传输层 │
│ ├── bridgeMessaging.ts # 消息协议 + 类型守卫 │
│ ├── sessionRunner.ts # 子进程 Spawn 管理 │
│ └── jwtUtils.ts # JWT 刷新 + 心跳 │
└────┬────────────────────┬──────────────────────────────────┘
 │ │
┌────▼────────┐ ┌─────▼────────┐
│ VSCode 扩展 │ │ JetBrains 扩展│
│ (TypeScript)│ │ (Kotlin) │
└────┬────────┘ └─────┬────────┘
 │ IPC(UDS) │ IPC(UDS)
┌────▼────────────────────▼────┐
│ CLI 主进程 (claude) │
│ src/main.tsx │
│ ├── launchRepl() │
│ └── REPL.tsx │
└─────────────────────────────┘

二、三种 Spawn Mode（会话隔离策略）

Mode	行为	适用场景
`single-session`	每个工作请求独占 cwd，结束后销毁	临时任务
`worktree`	每个会话分配独立 git worktree	持久服务器，多会话并行
`same-dir`	多会话共享同一目录（可互相覆盖）	轻量多会话

关键文件：src/bridge/types.ts:69

CC源码剖析 #04 · 多阶段任务编排器

Fri, 01 May 2026 08:00:00 +0800

基于 2026-03-31 公开的源码快照，~512,000 行代码

一、Coordinator 模式定位

Coordinator 是 Claude Code 的多 Agent 并行编排模式，通过 COORDINATOR_MODE Feature Flag 激活。

当用户任务需要多路并行研究、验证时，Coordinator 派生出多个 Worker Agent，各自独立工作，结果汇总到 Coordinator。

用户输入
 │
 ▼
┌─────────────┐
│ Coordinator │ ←── Feature Flag: COORDINATOR_MODE
│ (主 Agent) │
└──────┬──────┘
 │ parallel launch
 ├──────────────┐
 │ │
 ▼ ▼
┌──────────┐ ┌──────────┐
│ Worker A │ │ Worker B │
│ Research │ │ Research │
└────┬─────┘ └────┬─────┘
 │ │
 │ task-notification (结果)
 ▼ ▼
┌──────────────┐
│ Coordinator │ ←── 合成结果，发给用户
│ (汇总统筹) │
└──────────────┘

二、核心工具集

Coordinator 通过四个核心 Tool 管理 Worker 生命周期：

CC源码剖析 #05 · Tools 系统：工具定义、注册与执行

Fri, 01 May 2026 08:00:00 +0800

基于 2026-03-31 公开的源码快照，~512,000 行代码

一、Tool 在 Agent 架构中的位置

Tool 是 Agent 与外界交互的接口。每个 Tool 是一个自包含模块，包含输入 Schema、权限模型和执行逻辑。

LLM 决定调用 Tool
 │
 ▼
 Tool.call(args, context, canUseTool, parentMessage, onProgress)
 │
 ├─ Zod Schema 验证输入
 ├─ Permission 检查
 ├─ 执行逻辑
 └─ 返回 ToolResult + 新消息

二、Tool 基类定义

文件：src/Tool.ts，约 1,500 行

2.1 核心类型签名

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61


export type Tool<
 Input extends AnyObject = AnyObject, // Zod 输入 Schema
 Output = unknown,
 P extends ToolProgressData = ToolProgressData,
> = {
 // 可选别名（用于工具重命名后的向后兼容）
 aliases?: string[]

 // 工具调用入口
 call(
 args: z.infer<Input>,
 context: ToolUseContext,
 canUseTool: CanUseToolFn,
 parentMessage: AssistantMessage,
 onProgress?: ToolCallProgress<P>,
 ): Promise<ToolResult<Output>>

 // 生成工具描述（用于 prompt）
 description(
 input: z.infer<Input>,
 options: {
 isNonInteractiveSession: boolean
 toolPermissionContext: ToolPermissionContext
 tools: Tools
 },
 ): Promise<string>

 // Zod 输入 Schema
 readonly inputSchema: Input

 // 可选 JSON Schema（用于 MCP 工具）
 readonly inputJSONSchema?: ToolInputJSONSchema

 // 并发安全性
 isConcurrencySafe(input: z.infer<Input>): boolean

 // 是否启用
 isEnabled(): boolean

 // 是否只读
 isReadOnly(input: z.infer<Input>): boolean

 // 是否破坏性（删除/覆盖）
 isDestructive?(input: z.infer<Input>): boolean

 // 用户提交新消息时的行为
 interruptBehavior?(): 'cancel' | 'block'

 // 是否为搜索/读取操作（决定 UI 折叠显示）
 isSearchOrReadCommand?(input: z.infer<Input>): {
 isSearch: boolean
 isRead: boolean
 isList?: boolean
 }

 // 是否延迟加载（需要 ToolSearch 预热）
 readonly shouldDefer?: boolean

 // 是否始终加载（turn 1 就出现）
 readonly alwaysLoad?: boolean
}

2.2 ToolResult 结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


export type ToolResult<T> = {
 data: T
 // 可选：工具执行过程中产生的新消息
 newMessages?: (
 | UserMessage
 | AssistantMessage
 | AttachmentMessage
 | SystemMessage
 )[]
 // 内容替换状态（用于工具结果预算）
 contextModifier?: (context: ToolUseContext) => ToolUseContext
 // MCP 协议元数据
 mcpMeta?: {
 _meta?: Record<string, unknown>
 structuredContent?: Record<string, unknown>
 }
}

2.3 ToolUseContext — 执行上下文

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


export type ToolUseContext = {
 options: {
 commands: Command[]
 debug: boolean
 mainLoopModel: string
 tools: Tools
 verbose: boolean
 thinkingConfig: ThinkingConfig
 mcpClients: MCPServerConnection[]
 mcpResources: Record<string, ServerResource[]>
 isNonInteractiveSession: boolean
 agentDefinitions: AgentDefinitionsResult
 maxBudgetUsd?: number
 customSystemPrompt?: string
 appendSystemPrompt?: string
 querySource?: QuerySource
 refreshTools?: () => Tools
 }
 abortController: AbortController
 readFileState: FileStateCache
 getAppState(): AppState
 setAppState(f: (prev: AppState) => AppState): void
 // ... 50+ 字段
 messages: Message[]
}

三、Tool 注册中心

文件：src/tools.ts，约 800 行

CC源码剖析 #06 · Skills 加载与执行机制

Fri, 01 May 2026 08:00:00 +0800

基于 2026-03-31 公开的源码快照，~512,000 行代码

一、Skill 定位：用户自定义 Agent 能力扩展

Skill 是用户通过 Markdown 文件定义的命令，本质是一个带 frontmatter 的 prompt 模板。

用户执行 /my-skill arg1 arg2
 │
 ▼
Skill 定义文件（Markdown + frontmatter）
 │
 ├─ name: "my-skill"
 ├─ description: "..."
 ├─ arguments: [...]
 ├─ prompt: "模板内容 + {{arg1}} {{arg2}}"
 └─ tools?: [...] ← 可选：允许使用的工具列表
 │
 ▼
LLM 处理 prompt → 返回结果

Skills 与 Tools 的区别：

特性	Skill	Tool
定义方式	Markdown 文件	TypeScript 代码
编写门槛	低（无需编程）	高（需要编码）
执行方式	LLM 处理 prompt	直接执行逻辑
灵活性	受 prompt 限制	可实现任意逻辑

二、Skill 文件格式

2.1 Frontmatter 结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


---
name: "skill-name" # Skill 标识符
description: "What this skill does and when to use it"
# 触发短语：用户可用这些短语激活 skill
whenToUse: "When the user asks about X or wants to Y"
arguments: # 可选：参数定义
 - name: arg1
 description: Description
 required: true
 - name: arg2
 description: Description
 default: "default value"
tools: # 可选：允许使用的工具
 - Read
 - Edit
 - Bash
---

2.2 Prompt 模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


---
name: "code-review"
description: "Review code for bugs and style issues"
whenToUse: "User asks for a review or wants to check code quality"
---

# Code Review Skill

Review the following code for:
1. Security vulnerabilities
2. Performance issues
3. Style consistency

Code to review:
{{code}}

2.3 参数替换

1
2
3
4
5
6


// {{arg}} 替换为用户输入的参数值
// {{arg|default}} 提供默认值

substituteArguments(prompt, args)
// "Fix the bug in {{file}}" + { file: "auth.ts" }
// → "Fix the bug in auth.ts"

三、加载体系

文件：src/skills/loadSkillsDir.ts，约 600 行

CC源码剖析 #07 · MCP 协议：多工具协调

Fri, 01 May 2026 08:00:00 +0800

基于 2026-03-31 公开的源码快照，~512,000 行代码

一、MCP 在架构中的位置

MCP（Model Context Protocol）是 Claude Code 连接外部工具服务的协议，类似于 Language Server Protocol（LSP），但用于 AI 工具调用。

Claude Code (Client)
 │
 ├─ MCP 协议（HTTPS/WebSocket/stdio）
 │
 ▼
┌─────────────────────────┐
│ MCP Servers │
│ • 文件系统服务器 │
│ • Git 服务器 │
│ • 数据库服务器 │
│ • 搜索服务器 │
│ • 自定义服务器 │
└─────────────────────────┘

二、MCP 配置格式

文件：src/services/mcp/types.ts

2.1 配置作用域（ConfigScope）

1
2
3
4
5
6
7
8
9


const ConfigScopeSchema = z.enum([
 'local', // 本地项目 .mcp.json
 'user', // 用户全局 ~/.claude/mcp.json
 'project', // 项目配置
 'dynamic', // 动态配置
 'enterprise', // 企业托管
 'claudeai', // Claude.ai 内置
 'managed', // 企业托管
])

2.2 传输类型（Transport）

1
2
3
4
5
6
7
8


const TransportSchema = z.enum([
 'stdio', // 标准输入输出（本地进程）
 'sse', // Server-Sent Events（HTTPS）
 'sse-ide', // IDE 专用 SSE
 'http', // HTTP
 'ws', // WebSocket
 'sdk', // SDK 内部传输
])

2.3 服务器配置类型

Stdio 配置（本地进程）：

CC源码剖析 #08 · 消息传递：inbound/outbound 架构

Fri, 01 May 2026 08:00:00 +0800

基于 2026-03-31 公开的源码快照，~512,000 行代码

一、消息系统概述

Claude Code 的消息系统是其核心——负责用户输入、LLM 输出、工具调用结果之间的流转。

用户输入
 │
 ▼
┌─────────┐
│ Message │ ← discriminated union: user/assistant/system
└────┬────┘
 │
 ├─→ normalizeMessagesForAPI() → Anthropic API
 │ │
 │ ▼
 │ API Response
 │ │
 ├─→ Tool Call 循环
 │ │
 │ ▼
 │ Tool 执行
 │ │
 └─→ 渲染到 REPL UI

二、消息类型体系

文件：src/utils/messages.ts

2.1 核心消息类型

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


// UserMessage — 用户输入
type UserMessage = {
 type: 'user'
 message: {
 content: ContentBlock[] // text/image/tool_use
 }
 origin?: MessageOrigin
 isMeta?: boolean
 toolUseResult?: boolean // 工具执行结果
 isCompactSummary?: boolean
}

// AssistantMessage — LLM 输出
type AssistantMessage = {
 type: 'assistant'
 message: {
 content: ContentBlock[] // text/thinking/tool_use
 }
 isVirtual?: boolean // 虚拟消息（REPL 内部调用）
 stopReason?: string
 usage?: Usage
}

// SystemMessage — 系统消息
type SystemMessage =
 | SystemLocalCommandMessage // /命令输出
 | SystemApiErrorMessage // API 错误
 | SystemBridgeStatusMessage // Bridge 状态
 | SystemPermissionRetryMessage // 权限重试
 | SystemInformationalMessage // 信息提示

2.2 特殊消息类型

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// ProgressMessage — 长时间运行工具的进度
type ProgressMessage = {
 type: 'progress'
 data: ToolProgressData | HookProgress
}

// AttachmentMessage — 附件（图片/文件）
type AttachmentMessage = {
 type: 'attachment'
 attachment: Attachment
}

2.3 ContentBlock 类型

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


type ContentBlock =
 | TextBlock
 | ThinkingBlock
 | ToolUseBlock
 | RedactedThinkingBlock

// ToolUseBlock — 工具调用
type ToolUseBlock = {
 type: 'tool_use'
 id: string
 name: string // Bash/FileEdit/Grep...
 input: object // 工具参数
 type: 'input JSON'
}

// ToolResultBlock — 工具结果
type ToolResultBlock = {
 type: 'tool_result'
 toolUseId: string
 content: ContentBlock[]
 isError?: boolean
}

三、消息规范化（Normalization）

3.1 `normalizeMessagesForAPI`

1
2
3
4
5
6
7


// 将内部 Message[] 转换为 Anthropic API 格式
normalizeMessagesForAPI(
 messages: Message[],
 systemPrompt: string,
 tools: Tool[],
 toolChoice?: ToolChoice
): Promise<APIMessage[]>

3.2 规范化规则

1
2
3
4
5


// 1. 虚拟消息（isVirtual）过滤掉
// 2. 工具调用合并到 tool_use
// 3. 结果转为 tool_result
// 4. thinking block 处理（保留/删除）
// 5. Token 计数更新

3.3 消息裁剪

1
2
3
4
5


// 当消息过长时触发 compact
partialCompactConversation(
 messages: Message[],
 direction: 'pre' | 'post'
): Promise<Message[]>

四、inbound/outbound 架构

4.1 inbound（入站消息）

来自用户、工具执行、系统事件的消息：

CC源码剖析 #09 · 权限系统：PermissionCallbacks 与安全边界

Fri, 01 May 2026 08:00:00 +0800

基于 2026-03-31 公开的源码快照，~512,000 行代码

一、权限系统定位

权限系统是 Claude Code 的安全保障层——决定 Agent 在执行敏感操作前是否需要用户确认。

Tool.call()
 │
 ├─→ canUseTool(toolName, input) ─→ Permission 检查
 │ │
 │ ├─ alwaysAllow → 直接执行
 │ ├─ alwaysDeny → 拒绝
 │ ├─ auto 模式 → 检查历史决策
 │ └─ ask 模式 → 弹出确认对话框
 │
 └─→ 执行 Tool Logic

二、权限模式

文件：src/types/permissions.ts

2.1 模式类型

1
2
3
4
5
6


type PermissionMode =
 | 'default' // 使用用户配置的默认模式
 | 'auto' // 自动批准已知安全操作
 | 'ask' // 每次都询问用户
 | 'reject' // 拒绝所有危险操作
 | 'bypass' // 绕过（需要特殊标志）

2.2 CLI 参数

1
2
3


claude --permission-mode=auto # 自动模式
claude --permission-mode=ask # 每次询问
claude --AllowedTools=Read,Bash # 白名单工具

2.3 权限模式来源

1
2
3
4
5
6
7
8


// 优先级（从高到低）：
// 1. CLI 参数 --permission-mode
// 2. 会话缓存的 auto 模式状态
// 3. 全局配置默认值

initialPermissionModeFromCLI()
 ?? checkAutoModeEnabledStateIfCached()
 ?? getDefaultPermissionMode()

三、权限规则（Permission Rules）

3.1 规则类型

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


interface ToolPermissionRulesBySource {
 [source: string]: {
 tool: string
 allow?: boolean
 deny?: boolean
 }
}

// 规则来源：
// - alwaysAllowRules: 始终允许
// - alwaysDenyRules: 始终拒绝
// - alwaysAskRules: 始终询问

3.2 规则示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# 用户配置 (.claude/permissions.yml)
always_allow:
 - tool: "Read"
 paths: ["src/**"]

always_deny:
 - tool: "Bash"
 commands: ["rm -rf /"]

always_ask:
 - tool: "Bash"
 commands: ["rm *"]

3.3 规则匹配

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


// 规则匹配逻辑
getPermissionDecision(
 toolName: string,
 input: object,
 context: ToolPermissionContext
): 'allow' | 'deny' | 'ask'

// 匹配顺序：
// 1. alwaysDenyRules → deny
// 2. alwaysAllowRules → allow
// 3. alwaysAskRules → ask
// 4. 权限模式决定

四、canUseTool 检查

4.1 接口签名

1
2
3
4
5


type CanUseToolFn = (
 toolName: string,
 input: object,
 context: ToolPermissionContext,
) => Promise<PermissionResult>

4.2 检查流程

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


async function canUseTool(
 toolName: string,
 input: object,
 context: ToolPermissionContext,
): Promise<PermissionResult> {
 // 1. 检查 bypass 模式
 if (context.mode === 'bypass') {
 return { granted: true }
 }

 // 2. 检查 alwaysAllow
 if (matchesAlwaysAllow(toolName, input, context)) {
 return { granted: true }
 }

 // 3. 检查 alwaysDeny
 if (matchesAlwaysDeny(toolName, input, context)) {
 return { granted: false, reason: 'blocked' }
 }

 // 4. 检查权限模式
 if (context.mode === 'auto') {
 // 查历史决策
 return checkAutoHistory(toolName, input)
 }

 if (context.mode === 'ask') {
 // 弹出 UI 对话框
 return showPermissionDialog(toolName, input)
 }

 return { granted: false, reason: 'default_deny' }
}

五、自动模式（Auto Mode）

5.1 历史决策

Auto 模式维护一个本地决策缓存：

CC源码剖析 #10 · 状态管理：memdir 与会话持久化

Fri, 01 May 2026 08:00:00 +0800

基于 2026-03-31 公开的源码快照，~512,000 行代码

一、memdir 定位

memdir（Memory Directory）是 Claude Code 的会话持久化与记忆系统——负责在会话之间保存上下文，让 Agent 能够"记住"之前的对话内容。

会话开始
 │
 ├─→ 读取 MEMORY.md
 │ │
 │ ▼
 │ 系统提示 + 记忆内容
 │
 ├─→ 会话进行中...
 │
 └─→ 会话结束
 │
 ├─→ 更新 MEMORY.md（新增记忆）
 ├─→ 保存会话记录
 └─→ 保存会话元数据

二、目录结构

文件：src/memdir/paths.ts

2.1 路径解析

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


export function getMemoryBaseDir(): string {
 // 优先级：
 // 1. CLAUDE_CODE_REMOTE_MEMORY_DIR 环境变量（CCR 远程模式）
 // 2. ~/.claude（默认配置目录）
}

// 内存目录布局
~/.claude/
└── memory/
 └── projects/
 └── {sanitized-cwd}/
 └── memory/
 ├── MEMORY.md # 主入口
 ├── {topic}.md # 主题记忆文件
 └── {session}/ # 按会话的记录

2.2 路径安全验证

1
2
3
4
5
6
7
8


// SECURITY: 验证内存路径，防止路径遍历攻击
function validateMemoryPath(raw: string | undefined): string | undefined {
 // 拒绝：
 // - 相对路径（可能被解释为 CWD 相对）
 // - 根目录（"/", "C:"）
 // - UNC 路径（\\server\share）
 // - 含 null 字节
}

2.3 开关控制

1
2
3
4
5
6
7


export function isAutoMemoryEnabled(): boolean {
 // 1. CLAUDE_CODE_DISABLE_AUTO_MEMORY = 1 → 关闭
 // 2. CLAUDE_CODE_SIMPLE (--bare) → 关闭
 // 3. CCR 无持久化 → 关闭
 // 4. settings.json autoMemoryEnabled
 // 5. 默认：开启
}

三、MEMORY.md 入口

文件：src/memdir/memdir.ts

CC源码剖析 #11 · 插件系统：Plugin 架构与生命周期

Fri, 01 May 2026 08:00:00 +0800

基于 2026-03-31 公开的源码快照，~512,000 行代码

一、插件系统定位

插件系统是 Claude Code 的扩展生态层——允许第三方通过 Markdown 文件和配置文件提供 Skills、Hooks、MCP 服务器等能力。

用户安装插件
 │
 ▼
┌─────────────────────────────────────┐
│ Plugin Manager │
│ ├── loadPluginCommands() │
│ ├── loadPluginHooks() │
│ ├── loadPluginMcpServers() │
│ └── loadPluginAgents() │
└─────────────────────────────────────┘
 │
 ├─→ Skill Commands（/plugin-name）
 ├─→ Hooks（sessionStart/turnEnd...）
 ├─→ MCP Servers
 └─→ Agent Definitions

二、插件类型

2.1 内置插件（Built-in）

文件：src/plugins/builtinPlugins.ts

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// 内置插件 vs Skills：
// - Skills: 单个 Markdown 文件
// - 内置插件: 多组件（skills + hooks + MCP servers）

// 插件 ID 格式：{name}@builtin
export function isBuiltinPluginId(pluginId: string): boolean {
 return pluginId.endsWith('@builtin')
}

// 注册内置插件
export function registerBuiltinPlugin(
 definition: BuiltinPluginDefinition,
): void {
 BUILTIN_PLUGINS.set(definition.name, definition)
}

2.2 市场插件（Marketplace）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


// 从插件市场安装
// 插件市场：plugins.claude.com

interface MarketplacePlugin {
 id: string // name@marketplace
 name: string
 version: string
 description: string
 skills: SkillDefinition[]
 hooks: HookDefinition[]
 mcpServers?: McpServerConfig[]
}

2.3 项目插件

1
2


// 项目本地的 .claude/plugins/ 目录
// 对项目成员可见

三、插件生命周期

3.1 加载流程

启动时
 │
 ├─→ initBuiltinPlugins() // 初始化内置插件
 ├─→ loadAllPluginsCacheOnly() // 加载已安装插件（缓存）
 ├─→ initializeVersionedPlugins() // 版本管理
 │
 └─→ cleanupOrphanedPluginVersionsInBackground() // 清理旧版本

运行时
 │
 ├─→ 动态加载新插件
 ├─→ 插件更新检查
 └─→ 插件卸载处理

3.2 生命周期阶段

阶段	函数	说明
Init	`initBuiltinPlugins()`	注册内置插件
Load	`loadAllPluginsCacheOnly()`	加载插件列表
Enable	`enablePlugin(id)`	启用插件
Disable	`disablePlugin(id)`	禁用插件
Uninstall	`uninstallPlugin(id)`	卸载插件

四、插件加载器

文件：src/utils/plugins/pluginLoader.ts

CC源码剖析 #12 · 跨进程通信：RemoteBridge 与远程模式

Fri, 01 May 2026 08:00:00 +0800

基于 2026-03-31 公开的源码快照，~512,000 行代码

一、远程模式定位

远程模式允许 Claude Code 通过 Bridge 与远程运行的 CLI 实例通信，使得 IDE 可以在本地但 Agent 执行在远程。

本地 IDE (VSCode)
 │
 │ UDS IPC
 │
┌───▼──────────┐
│ Bridge Main │ ← 本地桥接进程
└───┬──────────┘
 │ WebSocket / HTTPS
 │
┌───▼──────────┐
│ Remote CLI │ ← 远程机器上运行
│ (REPL) │
└───────────────┘

二、RemoteBridge 架构

文件：src/bridge/remoteBridgeCore.ts

2.1 核心组件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


interface RemoteBridgeCore {
 // 连接管理
 connect(sessionId: string): Promise<void>
 disconnect(): Promise<void>

 // 消息传递
 sendMessage(msg: SDKMessage): void
 onMessage(handler: (msg: SDKMessage) => void): void

 // 状态同步
 syncState(): Promise<State>
 onStateChange(handler: (state: State) => void): void
}

2.2 传输协议

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// 支持多种传输方式
type Transport =
 | 'websocket' // WebSocket 连接
 | 'ssh' // SSH 隧道
 | 'http' // HTTP 流（stream-json）

// 传输选择逻辑：
// 1. 优先 WebSocket（低延迟）
// 2. SSH（企业防火墙环境）
// 3. HTTP（最后兜底）

三、SSH 会话

文件：src/ssh/createSSHSession.ts

CC源码剖析 #13 · Task 执行引擎：从创建到完成的完整流程

Fri, 01 May 2026 08:00:00 +0800

基于 2026-03-31 公开的源码快照，~512,000 行代码

一、Task 系统定位

Task 是 Claude Code 的后台任务执行单元——允许 Agent 派生子任务并行工作，结果汇总到主会话。

主会话（Main REPL）
 │
 ├─→ TaskCreateTool → 创建后台任务
 │ │
 │ ▼
 │ ┌──────────┐
 │ │ Task │ ← 后台运行
 │ └────┬─────┘
 │ │
 │ │ task-notification
 │ ▼
 └────── Agent 结果汇总

二、Task 类型体系

文件：src/tasks/types.ts

2.1 Task 类型列表

1
2
3
4
5
6
7
8


export type TaskState =
 | LocalShellTaskState // 本地 Shell 任务
 | LocalAgentTaskState // 本地 Agent 任务
 | RemoteAgentTaskState // 远程 Agent 任务
 | InProcessTeammateTaskState // 进程内队友任务
 | LocalWorkflowTaskState // 本地工作流任务
 | MonitorMcpTaskState // MCP 监控任务
 | DreamTaskState // 背景做梦任务

2.2 Task 状态

1
2
3
4
5
6
7


type TaskStatus =
 | 'pending' // 等待执行
 | 'running' // 执行中
 | 'completed' // 完成
 | 'failed' // 失败
 | 'killed' // 被停止
 | 'paused' // 暂停

2.3 后台任务判断

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 判断任务是否显示在后台任务指示器
export function isBackgroundTask(task: TaskState): boolean {
 if (task.status !== 'running' && task.status !== 'pending') {
 return false
 }
 // 前台任务（isBackgrounded === false）不显示
 if ('isBackgrounded' in task && task.isBackgrounded === false) {
 return false
 }
 return true
}

三、Task 创建

3.1 TaskCreateTool

文件：src/tools/TaskCreateTool/TaskCreateTool.ts

CC源码剖析 #14 · Hook 系统：生命周期拦截点

Fri, 01 May 2026 08:00:00 +0800

基于 2026-03-31 公开的源码快照，~512,000 行代码

一、Hook 系统定位

Hook 系统是 Claude Code 的生命周期拦截点——允许外部代码（插件、本地脚本）在特定事件发生时介入并修改行为。

用户输入
 │
 ▼
┌─────────────────────────────────┐
│ Hook System │
│ processSessionStartHooks() │
│ processSetupHooks() │
└─────────────────────────────────┘
 │
 ▼
┌─────────────────────────────────┐
│ QueryEngine │
│ preToolCall Hook │
└─────────────────────────────────┘
 │
 ▼
┌─────────────────────────────────┐
│ Tool.call() │
│ postToolCall Hook │
└─────────────────────────────────┘
 │
 ▼
结果

二、Hook 类型定义

文件：src/types/hooks.ts

2.1 支持的事件类型

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// HOOK_EVENTS 列表
type HookEvent =
 | 'PreToolUse' // 工具调用前
 | 'PostToolUse' // 工具调用后
 | 'UserPromptSubmit' // 用户提交输入前
 | 'UserPromptEdit' // 用户编辑输入时
 | 'RoundStart' // 回合开始
 | 'RoundEnd' // 回合结束
 | 'SessionStart' // 会话开始
 | 'SessionEnd' // 会话结束
 | 'PreAgentCall' // Agent 调用前
 | 'PostAgentCall' // Agent 调用后
 | 'PreProcessModel' // 模型处理前
 | 'PostProcessModel' // 模型处理后

2.2 Hook 接口

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


interface HookDefinition {
 event: HookEvent
 name: string
 source: 'plugin' | 'builtin' | 'user'
 handler: HookHandler
 config?: HookConfig
}

type HookHandler = (
 context: HookContext,
 input: HookInput,
) => Promise<HookResult>

2.3 Hook 输入/输出

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


// Hook 输入
interface HookInput {
 event: HookEvent
 sessionId: string
 messages: Message[]
 // 事件特定的输入数据
}

// Hook 输出
interface HookResult {
 continue: boolean // 是否继续执行
 suppressOutput?: boolean // 是否隐藏输出
 stopReason?: string // 停止原因
 decision?: 'approve' | 'block' // 决策
 reason?: string // 决策原因
 systemMessage?: string // 系统消息
 updatedInput?: object // 修改后的输入
 hookSpecificOutput?: object // Hook 特定输出
}

三、Hook 生命周期

3.1 会话启动 Hook

文件：src/utils/sessionStart.ts

CC源码剖析 #15 · 安全审查：Security Review 命令实现

Fri, 01 May 2026 08:00:00 +0800

基于 2026-03-31 公开的源码快照，~512,000 行代码

一、Security Review 命令定位

/security-review 是 Claude Code 内置的安全审查命令，通过解析 git diff 分析 PR 中的代码变更，识别高置信度的安全漏洞。

用户执行 /security-review
 │
 ▼
┌────────────────────────────────────────┐
│ Security Review Command │
│ 1. 获取 git diff │
│ 2. 获取修改文件列表 │
│ 3. 构建安全审查 prompt │
└────────────────────────────────────────┘
 │
 ▼
┌────────────────────────────────────────┐
│ Agent 处理 │
│ 分析 diff → 识别漏洞 → 输出报告 │
└────────────────────────────────────────┘
 │
 ▼
结构化安全报告（Markdown 格式）

二、命令实现

文件：src/commands/security-review.ts

2.1 命令定义

1
2
3
4
5
6
7
8


// 允许的工具（白名单）
allowed-tools: Bash(git diff:*), Bash(git status:*),
 Bash(git log:*), Bash(git show:*),
 Bash(git remote show:*), Read, Glob, Grep, LS, Task

// 描述
description: Complete a security review of the pending changes
 on the current branch

2.2 工具白名单策略

1
2
3
4
5
6
7
8
9


// 限制只能使用：
// 1. Git 读取命令（diff, status, log, show, remote show）
// 2. 文件读取（Read, Glob, Grep, LS）
// 3. Task（用于并行分析）

// 禁止：
// - Bash（其他命令）
// - FileWrite / FileEdit
// - Network tools

三、安全审查 Prompt

文件：src/commands/security-review.ts:6-179

OpenClaw源码剖析 #00 · 开篇

Fri, 01 May 2026 08:00:00 +0800

从源码层面深入理解 OpenClaw 的设计思想与实现细节。

系列介绍

OpenClaw 是一个面向 AI Agent 的开发框架，本系列从源码出发，拆解其核心模块的设计理念与实现机制。

适合对象：对 Agent 架构、工具调用链、任务规划感兴趣，想深入理解 OpenClaw 内部原理的开发者。

核心参考资料：

分析方法论：ANALYSIS_APPROACH.md
官方文档：https://docs.openclaw.ai
DeepWiki：https://deepwiki.com/openclaw/openclaw

目录规划

Part 1：架构层

#	文章	状态	说明
01	整体架构概览：目录结构与模块划分	✅ 完成	src/ 核心目录 + extensions/
02	Gateway 控制平面：API 路由与协议	✅ 完成	Gateway 控制平面
03	Plugin SDK：扩展机制与公开 API	✅ 完成	插件 SDK 架构
04	Agent Runtime：任务编排与执行	✅ 完成	Agent 运行时

Part 2：核心机制

#	文章	状态	说明
05	Provider 系统：多模型统一接口	✅ 完成	40+ 模型厂商抽象
06	Channel 系统：多渠道消息接入	✅ 完成	消息渠道抽象
07	会话与状态管理	✅ 完成	会话生命周期
08	记忆系统：Memory Architecture	✅ 完成	长期记忆

Part 3：扩展系统

#	文章	状态	说明
09	Extension 开发：Provider 篇	✅ 完成	开发新模型 Provider
10	Extension 开发：Channel 篇	✅ 完成	开发新消息渠道
11	Extension 开发：Skill 篇	✅ 完成	开发新 Skill

Part 4：工程实践

#	文章	状态	说明
12	测试策略：单元/集成/E2E	✅ 完成	Vitest + E2E
13	配置系统：Schema 与验证	✅ 完成	配置管理
14	安全机制：Auth 与权限	✅ 完成	认证授权
15	部署与运维：Docker 与容器化	✅ 完成	生产部署

模块速查

核心模块（src/）

目录	功能
`src/agents/`	Agent 定义、运行时、prompt 管理
`src/plugins/`	插件加载、激活、生命周期
`src/gateway/`	控制平面 API、路由、协议
`src/channels/`	渠道抽象层
`src/plugin-sdk/`	插件 SDK（公开 API）
`src/context-engine/`	上下文管理
`src/memory/`	记忆系统
`src/config/`	配置管理
`src/sessions/`	会话管理
`src/tasks/`	任务系统

扩展（extensions/）

类型	数量	示例
Provider	~40	`openai/`, `anthropic/`, `ollama/`
Channel	~30	`telegram/`, `discord/`, `whatsapp/`
Skill	~5	`skill-workshop/`
Tool	~10	`memory-core/`, `image-generation-core/`

源码结构概览

C:\dev\claude\openclaw\
├── src/
│ ├── agents/ # Agent 运行时
│ ├── gateway/ # 控制平面
│ ├── plugins/ # 插件系统
│ ├── plugin-sdk/ # SDK 公开 API
│ ├── channels/ # 渠道抽象
│ ├── context-engine/ # 上下文
│ ├── memory/ # 记忆
│ ├── sessions/ # 会话
│ ├── config/ # 配置
│ └── ...
├── extensions/
│ ├── providers/ # 模型提供商
│ │ ├── openai/
│ │ ├── anthropic/
│ │ └── ollama/
│ ├── channels/ # 消息渠道
│ │ ├── telegram/
│ │ ├── discord/
│ │ └── whatsapp/
│ └── skills/ # 技能
├── packages/ # 独立包
├── apps/ # 应用程序
└── ui/ # UI 组件

关键设计原则

来自 AGENTS.md

OpenClaw源码剖析 #01 · 整体架构概览：目录结构与模块划分

Fri, 01 May 2026 08:00:00 +0800

一、项目定位

OpenClaw 是一个个人 AI 助手平台，运行在用户自有设备上，通过用户已有的消息渠道进行交互。

用户 ──► OpenClaw ──► 30+ 消息渠道
 │ (Telegram/Discord/WhatsApp...)
 │
 ▼
 模型提供商
 (OpenAI/Anthropic/Google...)

核心特性：

个人化、单用户、本地优先
多渠道接入（30+ 消息平台）
多模型支持（40+ 厂商）
可扩展插件系统
支持语音和 Canvas

二、顶层目录结构

openclaw/
├── src/ # 核心业务逻辑
├── extensions/ # 扩展：Provider/Channel/Skill (~100 个)
├── packages/ # 独立 npm 包
├── apps/ # 应用程序
├── ui/ # UI 组件
├── test/ # E2E 测试
├── docs/ # 文档
├── scripts/ # 构建/工具脚本
├── skills/ # 内置 Skills
├── security/ # 安全相关
├── vendor/ # 第三方依赖
└── [配置文件]

三、核心模块（src/）

3.1 Agent 系统

目录	职责
`src/agents/`	Agent 定义、运行时、prompt 管理
`src/agent-sdk/`	Agent SDK
`src/agents/`	Agent 相关类型

3.2 控制平面

目录	职责
`src/gateway/`	Gateway 控制平面：API、路由、协议
`src/gateway/protocol/`	协议定义
`src/api/`	API 相关

3.3 插件系统

目录	职责
`src/plugins/`	插件加载、激活、生命周期管理
`src/plugin-sdk/`	Plugin SDK（公开 API，供扩展使用）
`src/plugin-state/`	插件状态管理
`src/plugin-activation-boundary.ts`	插件激活边界

3.4 渠道抽象

目录	职责
`src/channels/`	渠道抽象层
`src/channels/session.ts`	渠道会话

3.5 上下文与记忆

目录	职责
`src/context-engine/`	上下文引擎
`src/memory/`	记忆系统
`src/memory-host-sdk/`	记忆 Host SDK

3.6 会话与任务

目录	职责
`src/sessions/`	会话管理
`src/tasks/`	任务系统
`src/trajectory/`	轨迹记录

3.7 配置与安全

目录	职责
`src/config/`	配置管理
`src/secrets/`	密钥管理
`src/security/`	安全机制
`src/auth/`	认证授权

3.8 运行时能力

目录	职责
`src/hooks/`	Hook 系统
`src/flows/`	Flow 工作流
`src/commands/`	命令系统
`src/tui/`	TUI 界面

3.9 媒体与生成

目录	职责
`src/media/`	媒体处理
`src/media-generation/`	媒体生成
`src/media-understanding/`	媒体理解
`src/image-generation/`	图片生成
`src/video-generation/`	视频生成
`src/music-generation/`	音乐生成
`src/tts/`	文本转语音
`src/realtime-voice/`	实时语音
`src/realtime-transcription/`	实时转录

3.10 其他支持模块

目录	职责
`src/i18n/`	国际化
`src/mcp/`	MCP 协议
`src/bootstrap/`	启动初始化
`src/daemon/`	后台守护进程
`src/logger/`	日志
`src/logging/`	日志系统
`src/crone/`	定时任务
`src/poll-params.ts`	轮询参数
`src/polls.ts`	轮询系统

四、扩展系统（extensions/）

4.1 Provider（模型提供商）

Provider	说明
`anthropic/`	Anthropic API（Claude）
`openai/`	OpenAI API（GPT）
`ollama/`	Ollama（本地模型）
`google/`	Google AI
`azure/`	Azure OpenAI
`amazon-bedrock/`	AWS Bedrock
`deepseek/`	DeepSeek
`mistral/`	Mistral AI
`groq/`	Groq
`openrouter/`	OpenRouter
`together/`	Together AI
`xai/`	xAI
`nvidia/`	NVIDIA NIM
`cerebras/`	Cerebras
`Voyage/`	Voyage AI
`fireworks/`	Fireworks AI
`deepinfra/`	DeepInfra
`vllm/`	vLLM
`sglang/`	SGLang
`lmstudio/`	LM Studio
`kimi-coding/`	Kimi Coding
`moonshot/`	Moonshot
`qwen/`	Qwen
`wenxin/`	百度文心
`minimax/`	MiniMax
`volcengine/`	火山引擎
`baichuan/`	百川
`tencent/`	腾讯混元
`zalo/`	Zalo

4.2 Channel（消息渠道）

Channel	说明
`telegram/`	Telegram
`discord/`	Discord
`whatsapp/`	WhatsApp
`slack/`	Slack
`microsoft/`	Microsoft Teams
`googlechat/`	Google Chat
`msteams/`	Microsoft Teams（原生）
`matrix/`	Matrix
`irc/`	IRC
`signal/`	Signal
`feishu/`	飞书
`line/`	LINE
`mattermost/`	Mattermost
`nextcloud-talk/`	Nextcloud Talk
`synology-chat/`	群晖 Chat
`tlon/`	Tlon
`nostr/`	Nostr
`twitch/`	Twitch
`bluebubbles/`	BlueBubbles（iMessage）
`imessage/`	iMessage

4.3 Skill（技能）

Skill	说明
`skill-workshop/`	技能工作流

4.4 Tool（工具能力）

Tool	说明
`memory-core/`	记忆核心
`memory-lancedb/`	LanceDB 记忆存储
`memory-wiki/`	Wiki 记忆
`image-generation-core/`	图片生成核心
`video-generation-core/`	视频生成核心
`media-understanding-core/`	媒体理解核心
`speech-core/`	语音核心

五、架构设计原则

来自 AGENTS.md

OpenClaw源码剖析 #02 · Gateway 控制平面：API 路由与协议

Fri, 01 May 2026 08:00:00 +0800

一、Gateway 定位

Gateway 是 OpenClaw 的控制平面——负责接收来自渠道的消息、管理会话、协调 Agent 执行。

┌─────────────────────────────────────────────────────────┐
│ OpenClaw Gateway │
│ 控制平面 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 渠道接入 │ │ 会话 │ │ 凭证 │ │
│ │ │ │ 管理 │ │ 管理 │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 协议 │ │ API │ │ 运行时 │ │
│ │ 处理器 │ │ 路由 │ │ 协调 │ │
│ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────┘
 │ │ │
 ▼ ▼ ▼
┌──────────────────────────────────────────────────┐
│ Extensions / Plugins │
│ Channel (Telegram/Discord) │ Provider (OpenAI) │
└──────────────────────────────────────────────────┘

二、模块结构

文件：src/gateway/

OpenClaw源码剖析 #03 · Plugin SDK：扩展机制与公开 API

Fri, 01 May 2026 08:00:00 +0800

一、Plugin SDK 定位

Plugin SDK 是 OpenClaw 的扩展接入层——定义扩展如何与核心交互、如何注册能力、如何参与生命周期。

┌──────────────────────────────────────────────────────────────┐
│ OpenClaw Core │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ Gateway │ │ Agent │ │ Config │ │
│ │ │ │ Runtime │ │ │ │
│ └────────────┘ └────────────┘ └────────────┘ │
│ ▲ │
│ │ plugin-sdk/* │
│ │ (公开 API) │
└─────────────────────────┼───────────────────────────────────┘
 │
┌─────────────────────────┼───────────────────────────────────┐
│ Plugin SDK 公开接口 (src/plugin-sdk/) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ OpenClawPluginApi │ │
│ │ registerProvider() · registerChannel() │ │
│ │ registerTool() · registerHook() · registerCommand() │ │
│ │ registerHttpRoute() · registerService() │ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Plugin Manifest (openclaw.plugin.json) │ │
│ │ id · configSchema · kind · providers · channels │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────┼───────────────────────────────────┘
 │
┌─────────────────────────┼───────────────────────────────────┐
│ Extensions │
│ extensions/providers/ extensions/channels/ extensions/ │
│ openai/ telegram/ skill-workshop/│
└─────────────────────────────────────────────────────────────┘

核心原则（来自 AGENTS.md）：

OpenClaw源码剖析 #04 · Agent Runtime：任务编排与执行

Fri, 01 May 2026 08:00:00 +0800

一、Agent Runtime 定位

Agent Runtime 是 OpenClaw 的任务执行引擎——负责接收消息、选择模型、调度工具、生成回复。

┌──────────────────────────────────────────────────────────────┐
│ Agent Runtime │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ agent-command.ts │ │
│ │ 入口：解析参数 → 解析会话 → 路由到 Harness │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────┼─────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ ACP Harness │ │ PI Harness │ │ CLI Harness │ │
│ │ (外部 Agent)│ │ (内置模型) │ │ (Claude CLI)│ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ attempt-execution.ts │ │
│ │ 认证计划 · 模型选择 · Fallback · 生命周期 │ │
│ └─────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

二、模块结构

文件	职责
`agent-command.ts`	命令入口，解析参数，协调执行流程
`command/attempt-execution.ts`	核心执行引擎，运行单次 Agent Attempt
`command/delivery.ts`	结果投递到渠道
`command/session.ts`	会话解析与创建
`command/run-context.ts`	运行上下文构建
`harness/types.ts`	Harness 接口定义
`harness/registry.ts`	Harness 注册表
`harness/selection.ts`	Harness 选择策略
`acp-spawn.ts`	ACP 子 Agent 孵化

三、Agent 命令入口

文件：agent-command.ts

OpenClaw源码剖析 #05 · Provider 系统：多模型统一接口

Fri, 01 May 2026 08:00:00 +0800

一、Provider 系统定位

Provider 系统是 OpenClaw 的模型抽象层——通过统一接口接入 40+ 模型厂商，对上屏蔽厂商差异。

┌─────────────────────────────────────────────────────────────┐
│ OpenClaw Core │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Agent RT │ │ Channel │ │ Skills │ │
│ └──────┬───────┘ └──────────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Model Selection (model-selection.ts) │ │
│ │ resolveDefaultModelForAgent() │ │
│ │ buildAllowedModelSet() │ │
│ │ resolveConfiguredModelRef() │ │
│ └──────────────────────────────────────────────────┘ │
└─────────────────────────┬─────────────────────────────────┘
 │
┌─────────────────────────┼─────────────────────────────────┐
│ Provider 插件层 (extensions/providers/) │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ openai/ │ │anthropic/│ │ ollama/ │ │ gemini/ │ ... │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
└─────────────────────────────────────────────────────────────┘

二、模块结构

文件	职责
`agents/model-selection.ts`	模型选择、解析、规范化
`agents/model-selection-normalize.ts`	ModelRef 规范化
`agents/model-selection-shared.ts`	模型列表/别名共享逻辑
`agents/model-catalog.ts`	模型目录加载
`agents/defaults.ts`	默认 Provider/Model
`agents/provider-id.ts`	Provider ID 规范化
`extensions/providers/*/`	40+ Provider 插件

三、核心类型

3.1 ModelRef

1
2
3
4
5


// agents/model-selection-normalize.ts
export type ModelRef = {
 provider: string; // e.g. "openai", "anthropic"
 model: string; // e.g. "gpt-4o", "claude-sonnet-4"
};

3.2 ModelKey

模型唯一标识：provider/model

OpenClaw源码剖析 #06 · Channel 系统：多渠道消息接入

Fri, 01 May 2026 08:00:00 +0800

一、Channel 系统定位

Channel 系统是 OpenClaw 的消息渠道抽象层——通过统一接口接入 30+ 消息平台，对上屏蔽平台差异。

┌─────────────────────────────────────────────────────────────┐
│ OpenClaw Core │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Gateway │ │ Agent RT │ │ Memory │ │
│ └──────┬───────┘ └──────────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Channel 抽象层 (src/channels/) │ │
│ │ inbound → session → outbound │ │
│ └──────────────────────────────────────────────────┘ │
└─────────────────────────┬─────────────────────────────────┘
 │
┌─────────────────────────┼─────────────────────────────────┐
│ Channel 插件层 (extensions/channels/) │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │telegram/│ │discord/ │ │whatsapp/│ │ slack/ │ ... │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
└─────────────────────────────────────────────────────────────┘

二、模块结构

文件	职责
`channels/plugins/types.plugin.ts`	ChannelPlugin 接口定义
`channels/plugins/types.core.ts`	核心类型（ChannelId、ChannelCapabilities）
`channels/plugins/types.adapters.ts`	各 Adapter 接口
`channels/plugins/config-schema.ts`	配置 Schema
`channels/plugins/config-writes.ts`	配置写入逻辑
`channels/plugins/config-helpers.ts`	配置辅助函数
`channels/inbound-debounce-policy.ts`	入站消息去抖
`channels/conversation-resolution.ts`	会话解析
`channels/allow-from.ts`	AllowFrom 逻辑
`channels/mention-gating.ts`	提及过滤
`extensions/channels/*/`	30+ Channel 插件

三、ChannelPlugin 接口

文件：channels/plugins/types.plugin.ts

OpenClaw源码剖析 #07 · 会话与状态管理

Fri, 01 May 2026 08:00:00 +0800

一、会话系统定位

会话系统是 OpenClaw 的状态管理核心——管理会话生命周期、持久化、解析与投递。

┌─────────────────────────────────────────────────────────────┐
│ Session System │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ SessionEntry │ │
│ │ sessionId · model · tokenCount · skillsSnapshot │ │
│ │ acp meta · pluginExtensions · compactionState │ │
│ └──────────────────────────────────────────────────────┘ │
│ │ │
│ ┌────────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Session Key │ │ Session │ │ Transcript │ │
│ │ 解析 │ │ Store │ │ 管理 │ │
│ └────────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘

二、核心类型

文件：config/sessions/types.ts

OpenClaw源码剖析 #08 · 记忆系统：Memory Architecture

Fri, 01 May 2026 08:00:00 +0800

一、记忆系统定位

记忆系统是 OpenClaw 的长期知识管理模块——通过搜索、注入、压缩机制扩展 Agent 的上下文能力。

┌─────────────────────────────────────────────────────────────┐
│ Memory System │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ MemoryPluginCapability │ │
│ │ promptBuilder · flushPlanResolver · runtime │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Prompt Builder │ │ Search Manager │ │
│ │ 向 System Prompt │ │ 向量/全文搜索 │ │
│ │ 注入记忆段落 │ │ RAG 检索 │ │
│ └──────────────────┘ └──────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Flush Plan (Compaction) │ │
│ │ 会话过长时触发记忆压缩，释放上下文窗口 │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

二、模块结构

文件	职责
`plugins/memory-state.ts`	Memory 插件状态与注册
`plugin-sdk/memory-host-core.ts`	Memory Host 核心
`plugin-sdk/memory-host-search.ts`	搜索接口
`plugin-sdk/memory-core-host-runtime-*.ts`	各后端运行时
`agents/memory-search.ts`	Agent 记忆搜索
`auto-reply/reply/memory-flush.ts`	记忆刷新
`memory-host-sdk/host/types.ts`	SearchManager 类型

三、核心类型

文件：plugins/memory-state.ts

OpenClaw源码剖析 #09 · Extension 开发：Provider 篇

Fri, 01 May 2026 08:00:00 +0800

一、Provider 扩展定位

Provider 扩展是 OpenClaw 的模型接入层——通过插件机制接入 40+ 模型厂商，对上提供统一的 ProviderPlugin 接口。

┌─────────────────────────────────────────────────────────────┐
│ OpenClaw Core │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Agent RT │ │ Channel │ │ Skills │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ ProviderPlugin Interface │ │
│ │ id · label · auth · catalog · resolveDynamicModel │ │
│ └──────────────────────────────────────────────────┘ │
└───────────────────────────┬─────────────────────────────────┘
 │
┌───────────────────────────┼─────────────────────────────────┐
│ extensions/providers/ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ openai/ │ │anthropic/│ │ ollama/ │ │ gemini/ │ ... │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
└─────────────────────────────────────────────────────────────┘

二、模块结构

文件	职责
`src/plugins/types.ts`	ProviderPlugin 类型定义
`extensions/providers/<name>/index.ts`	Provider 插件入口
`extensions/providers/<name>/api.ts`	运行时 API 实现
`extensions/providers/<name>/provider-discovery.ts`	独立发现插件
`extensions/providers/<name>/openclaw.plugin.json`	Manifest 元数据
`src/agents/model-catalog.ts`	模型目录加载
`src/agents/model-catalog.types.ts`	ModelCatalogEntry 类型

三、ProviderPlugin 接口

文件：src/plugins/types.ts

OpenClaw源码剖析 #10 · Extension 开发：Channel 篇

Fri, 01 May 2026 08:00:00 +0800

一、Channel 扩展定位

Channel 扩展是 OpenClaw 的消息渠道接入层——通过插件机制接入 30+ 消息平台，对上提供统一的 ChannelPlugin 接口。

┌─────────────────────────────────────────────────────────────┐
│ OpenClaw Core │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Gateway │ │ Agent RT │ │ Memory │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ ChannelPlugin Interface │ │
│ │ id · meta · capabilities · config · setup │ │
│ │ outbound · gateway · lifecycle │ │
│ └──────────────────────────────────────────────────┘ │
└───────────────────────────┬─────────────────────────────────┘
 │
┌───────────────────────────┼─────────────────────────────────┐
│ extensions/channels/ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │telegram/│ │discord/ │ │whatsapp/│ │ slack/ │ ... │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
└─────────────────────────────────────────────────────────────┘

二、模块结构

文件	职责
`src/channels/plugins/types.plugin.ts`	ChannelPlugin 接口定义
`src/channels/plugins/types.core.ts`	核心类型（Capabilities、Meta）
`src/channels/plugins/types.adapters.ts`	各 Adapter 接口
`src/channels/plugins/config-schema.ts`	配置 Schema 构建器
`src/channels/plugins/setup-wizard-types.ts`	Setup Wizard 类型
`src/plugin-sdk/core.ts`	`createChatChannelPlugin()` 辅助函数
`extensions/channels/<name>/`	各 Channel 插件实现

三、ChannelPlugin 接口

文件：src/channels/plugins/types.plugin.ts

OpenClaw源码剖析 #11 · Extension 开发：Skill 篇

Fri, 01 May 2026 08:00:00 +0800

一、Skill 扩展定位

Skill 扩展是 OpenClaw 的技能模块——通过描述匹配触发，为 Agent 提供专用工具和知识。

┌─────────────────────────────────────────────────────────────┐
│ OpenClaw Core │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Agent RT │ │ Skills │ │ Memory │ │
│ └──────────────┘ └──────┬───────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Skill System │ │
│ │ SKILL.md · scripts/ · references/ │ │
│ └──────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

二、模块结构

文件/目录	职责
`src/agents/skills/types.ts`	Skill 类型定义
`src/agents/skills/workspace.ts`	Skill 加载、过滤、Prompt 构建
`src/agents/skills/frontmatter.ts`	Frontmatter 解析
`src/agents/skills/local-loader.ts`	文件系统加载
`src/agents/skills/plugin-skills.ts`	插件内嵌 Skill 加载
`skills/`	内置 Skill 目录
`extensions/*/skills/`	插件内嵌 Skill

三、两种 Skill 类型

3.1 独立 Skill

存储在 skills/ 目录：

OpenClaw源码剖析 #12 · 测试策略：单元/集成/E2E

Fri, 01 May 2026 08:00:00 +0800

一、测试系统定位

OpenClaw 采用 Vitest 作为主要测试框架，配合 Playwright 进行浏览器测试，构建了多层次的测试体系。

┌─────────────────────────────────────────────────────────────┐
│ Testing Infrastructure │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Vitest │ │ Playwright │ │ V8 │ │
│ │ 单元/集成 │ │ 浏览器测试 │ │ 覆盖率 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘

二、测试框架

工具	版本	用途
`vitest`	^4.1.5	单元/集成测试框架
`@vitest/coverage-v8`	^4.1.5	V8 引擎代码覆盖率
`@vitest/browser-playwright`	-	浏览器 E2E 测试
`jsdom`	^29.1.0	DOM 模拟
`playwright`	-	浏览器自动化

三、目录结构

C:\dev\claude\openclaw\
├── test/
│ ├── vitest/ # Vitest 配置文件（70+）
│ │ ├── vitest.config.ts # 根配置
│ │ ├── vitest.unit.config.ts # 单元测试
│ │ ├── vitest.unit-fast.config.ts # 快速单元
│ │ ├── vitest.e2e.config.ts # E2E 测试
│ │ ├── vitest.gateway.config.ts
│ │ ├── vitest.channels.config.ts
│ │ └── vitest.contracts-*.config.ts # 契约测试
│ │
│ ├── helpers/ # 测试工具
│ │ ├── openclaw-test-instance.ts # Gateway 实例启动器
│ │ ├── gateway-e2e-harness.ts # E2E 测试 harness
│ │ └── ...
│ │
│ ├── mocks/ # Mock 定义
│ ├── fixtures/ # 测试夹具
│ ├── setup.ts # 全局 Setup
│ ├── setup.shared.ts # 共享 Setup
│ └── setup-openclaw-runtime.ts # 运行时环境
│
├── src/
│ └── **/*.test.ts # 单元测试分散在 src/
│
└── ui/
 └── src/**/*.test.ts # UI 组件测试（~100 文件）

四、配置文件

4.1 根配置

test/vitest/vitest.config.ts

OpenClaw源码剖析 #13 · 配置系统：Schema 与验证

Fri, 01 May 2026 08:00:00 +0800

一、配置系统定位

OpenClaw 采用 Zod 作为配置 Schema 定义和验证的核心，提供类型安全的配置加载、验证和环境变量替换。

┌─────────────────────────────────────────────────────────────┐
│ Config System │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ OpenClawSchema │ │
│ │ env · auth · models · agents · channels · plugins │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────┐ │
│ │ Zod Schema │ │ Env Vars │ │ Includes │ │
│ │ validation │ │ ${VAR} 替换 │ │ $include │ │
│ └────────────────┘ └────────────────┘ └────────────┘ │
└─────────────────────────────────────────────────────────────┘

二、模块结构

文件	职责
`src/config/zod-schema.ts`	主 Zod Schema 定义
`src/config/validation.ts`	配置验证入口
`src/config/io.ts`	配置加载、写入
`src/config/types.openclaw.ts`	TypeScript 类型
`src/config/env-vars.ts`	环境变量收集
`src/config/env-substitution.ts`	`${VAR}` 替换
`src/config/includes.ts`	`$include` 指令
`src/plugin-sdk/config-schema.ts`	插件 Config Schema 构建器
`src/channels/plugins/config-schema.ts`	Channel Config Schema
`src/plugins/schema-validator.ts`	AJV JSON Schema 验证

三、OpenClawSchema

文件：src/config/zod-schema.ts

OpenClaw源码剖析 #14 · 安全机制：Auth 与权限

Fri, 01 May 2026 08:00:00 +0800

一、安全系统定位

OpenClaw 安全系统采用分层设计，区分认证（Authentication）与授权（Authorization），覆盖 Gateway、Provider、Channel 三大维度。

┌─────────────────────────────────────────────────────────────┐
│ Security Architecture │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Gateway Auth │ │
│ │ token · password · trusted-proxy · device-token │ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Auth Profiles │ │
│ │ api_key · token · oauth · SecretRef │ │
│ └──────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Channel Security │ │
│ │ dm-policy · allowlist · pairing │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

二、Gateway 认证

2.1 认证模式

src/gateway/auth-resolve.ts

OpenClaw源码剖析 #15 · 部署与运维：Docker 与容器化

Fri, 01 May 2026 08:00:00 +0800

一、部署系统定位

OpenClaw 支持多种部署方式，其中 Docker 容器化部署是生产环境的推荐方案。

┌─────────────────────────────────────────────────────────────┐
│ Docker Deployment │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Multi-Stage Build │ │
│ │ ext-deps → build → runtime-assets → base → runtime │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────┐ │
│ │ Docker Compose │ │ Gateway │ │ Sandbox │ │
│ │ Gateway + CLI │ │ 容器运行 │ │ 隔离代理 │ │
│ └────────────────┘ └────────────────┘ └────────────┘ │
└─────────────────────────────────────────────────────────────┘

二、Dockerfile 结构

2.1 多阶段构建

Dockerfile

架构 on SkySeraph

CC源码剖析 #01 · 整体架构概览：目录结构与模块划分

一、项目背景

二、顶层目录结构

三、src/ 模块全景图

3.1 核心运行模块

3.2 通信层

3.3 任务与状态

3.4 UI 与交互

3.5 生态扩展

3.6 其他

四、最关键模块详解

4.1 tools/ — 工具系统（Agent 的"手"）

CC源码剖析 #02 · 入口点解析：从 CLI 到 REPL

一、整体启动流程

二、main.tsx — 入口编排

2.1 启动顺序

CC源码剖析 #03 · Bridge 模块：主进程与渲染进程的通信机制

一、Bridge 在整个架构中的位置

二、三种 Spawn Mode（会话隔离策略）

CC源码剖析 #04 · 多阶段任务编排器

一、Coordinator 模式定位

二、核心工具集

CC源码剖析 #05 · Tools 系统：工具定义、注册与执行

一、Tool 在 Agent 架构中的位置

二、Tool 基类定义

2.1 核心类型签名

2.2 ToolResult 结构

2.3 ToolUseContext — 执行上下文

三、Tool 注册中心

CC源码剖析 #06 · Skills 加载与执行机制

一、Skill 定位：用户自定义 Agent 能力扩展

二、Skill 文件格式

2.1 Frontmatter 结构

2.2 Prompt 模板

2.3 参数替换

三、加载体系

CC源码剖析 #07 · MCP 协议：多工具协调

一、MCP 在架构中的位置

二、MCP 配置格式

2.1 配置作用域（ConfigScope）

2.2 传输类型（Transport）

2.3 服务器配置类型

CC源码剖析 #08 · 消息传递：inbound/outbound 架构

一、消息系统概述

二、消息类型体系

2.1 核心消息类型

2.2 特殊消息类型

2.3 ContentBlock 类型

三、消息规范化（Normalization）

3.1 normalizeMessagesForAPI

3.2 规范化规则

3.3 消息裁剪

四、inbound/outbound 架构

4.1 inbound（入站消息）

CC源码剖析 #09 · 权限系统：PermissionCallbacks 与安全边界

一、权限系统定位

二、权限模式

2.1 模式类型

2.2 CLI 参数

2.3 权限模式来源

三、权限规则（Permission Rules）

3.1 规则类型

3.2 规则示例

3.3 规则匹配

四、canUseTool 检查

4.1 接口签名

4.2 检查流程

五、自动模式（Auto Mode）

5.1 历史决策

CC源码剖析 #10 · 状态管理：memdir 与会话持久化

一、memdir 定位

二、目录结构

2.1 路径解析

2.2 路径安全验证

2.3 开关控制

三、MEMORY.md 入口

CC源码剖析 #11 · 插件系统：Plugin 架构与生命周期

一、插件系统定位

二、插件类型

三、`src/` 模块全景图

4.1 `tools/` — 工具系统（Agent 的"手"）

二、`main.tsx` — 入口编排

3.1 `normalizeMessagesForAPI`