Claude Code 源码架构解析

一、Coding Agent 赛道现状

二、核心架构：三角关系

用户/终端    ↓Hermes Agent（路由/调度层）    ↓OpenClaw CEO Agent（决策/规划层）    ↓Claude Code（执行/编程层）

三、源码结构解析

src/├── cli/# 命令行入口├── sessions/# 会话管理（SessionStore、session.ts）├── agent/# Agent 逻辑核心│   ├── index.ts      # Agent 主循环│   ├── circuit-breaker.ts  # 熔断器实现│   └── state-machine.ts    # 状态机├── tools/# 工具定义（核心亮点）│   ├── index.ts      # 工具注册表│   └── tool-metadata.ts    # 工具元数据协议├── transport/# 传输层（stdio / mcp）└── utils/# 工具函数

1 熔断器（Circuit Breaker）

// 简化版逻辑classCircuitBreaker {private failures = newMap<string, number>();private threshold = 3;  // 连续失败3次就熔断  call<T>(toolName: string, fn: () => T): T | null {if (this.failures.get(toolName) >= this.threshold) {// 熔断状态：跳过调用，返回 nullreturnnull;    }try {returnfn();    } catch (e) {const count = (this.failures.get(toolName) || 0) + 1;this.failures.set(toolName, count);returnnull;    }  }}

2 Proactive Pub/Sub 状态机

IDLE → THINKING → ACTING → WAITING → OBSERVING → IDLE         ↑___________||___________↓              (用户中断)         (工具调用)

3 工具元数据协议（Tool Metadata Protocol）

interfaceToolMetadata {name: string;          // 工具名description: string;   // AI 可读描述inputSchema: JSONSchema;  // 参数校验capabilities: ('read' | 'write' | 'execute' | 'browser')[];riskLevel: 'low' | 'medium' | 'high' | 'critical';confirmRequired: boolean;  // 是否需要用户确认}

四、会话管理（SessionStore）

classSessionStore {privatesessions: Map<string, Session>;create(userId: string): string;   // 创建会话，返回 sessionIdget(sessionId: string): Session;  // 获取会话append(sessionId: string, msg: Message): void;  // 追加消息history(sessionId: string, limit?: number): Message[];  // 历史}

~/.claude/├── sessions/│   ├── 2026-05/│   │   ├── session-abc123.json│   │   └── session-def456.json

五、与外部系统的集成方式

// MCP 客户端初始化const client = newMCPClient({serverPath: 'openclaw-mcp-server',env: {SESSION_ID: currentSession,USER_ID: userId,  }});// 调用工具const result = await client.callTool('database', 'query', {sql: 'SELECT * FROM users LIMIT 10'});

一、Coding Agent 赛道现状

二、核心架构：三角关系

用户/终端    ↓Hermes Agent（路由/调度层）    ↓OpenClaw CEO Agent（决策/规划层）    ↓Claude Code（执行/编程层）

三、源码结构解析

src/├── cli/# 命令行入口├── sessions/# 会话管理（SessionStore、session.ts）├── agent/# Agent 逻辑核心│   ├── index.ts      # Agent 主循环│   ├── circuit-breaker.ts  # 熔断器实现│   └── state-machine.ts    # 状态机├── tools/# 工具定义（核心亮点）│   ├── index.ts      # 工具注册表│   └── tool-metadata.ts    # 工具元数据协议├── transport/# 传输层（stdio / mcp）└── utils/# 工具函数

1 熔断器（Circuit Breaker）

// 简化版逻辑classCircuitBreaker {private failures = newMap<string, number>();private threshold = 3;  // 连续失败3次就熔断  call<T>(toolName: string, fn: () => T): T | null {if (this.failures.get(toolName) >= this.threshold) {// 熔断状态：跳过调用，返回 nullreturnnull;    }try {returnfn();    } catch (e) {const count = (this.failures.get(toolName) || 0) + 1;this.failures.set(toolName, count);returnnull;    }  }}

2 Proactive Pub/Sub 状态机

IDLE → THINKING → ACTING → WAITING → OBSERVING → IDLE         ↑___________||___________↓              (用户中断)         (工具调用)

3 工具元数据协议（Tool Metadata Protocol）

interfaceToolMetadata {name: string;          // 工具名description: string;   // AI 可读描述inputSchema: JSONSchema;  // 参数校验capabilities: ('read' | 'write' | 'execute' | 'browser')[];riskLevel: 'low' | 'medium' | 'high' | 'critical';confirmRequired: boolean;  // 是否需要用户确认}

安全分级：高风险操作（删除文件、执行命令）需要二次确认

按需调用：模型根据描述决定是否调用，而不是硬编码

可扩展：新增工具只需注册元数据，不需要改 Agent 核心

四、会话管理（SessionStore）

classSessionStore {privatesessions: Map<string, Session>;create(userId: string): string;   // 创建会话，返回 sessionIdget(sessionId: string): Session;  // 获取会话append(sessionId: string, msg: Message): void;  // 追加消息history(sessionId: string, limit?: number): Message[];  // 历史}

~/.claude/├── sessions/│   ├── 2026-05/│   │   ├── session-abc123.json│   │   └── session-def456.json

五、与外部系统的集成方式

// MCP 客户端初始化const client = newMCPClient({serverPath: 'openclaw-mcp-server',env: {SESSION_ID: currentSession,USER_ID: userId,  }});// 调用工具const result = await client.callTool('database', 'query', {sql: 'SELECT * FROM users LIMIT 10'});