Clawd Code 技术分析
Clawd Code（又称 Claude-Code-Python）是一个基于 Claude Code 原始 TypeScript 源码的完整 Python 重构实现。它不是一个简单的源码转储，而是一个可运行的生产级 CLI Agent，具备工具调用循环、流式 REPL、会话历史和多轮执行能力。属性说明仓库地址开发语言许可证MIT星标数345+Fork 数180+核心定位Claude Code 的
·
1. 项目概述
Clawd Code（又称 Claude-Code-Python）是一个基于 Claude Code 原始 TypeScript 源码的完整 Python 重构实现。它不是一个简单的源码转储，而是一个可运行的生产级 CLI Agent，具备工具调用循环、流式 REPL、会话历史和多轮执行能力。
| 属性 | 说明 |
|---|---|
| 仓库地址 | https://github.com/GPT-AGI/Clawd-Code |
| 开发语言 | Python 100% |
| 许可证 | MIT |
| 星标数 | 345+ |
| Fork 数 | 180+ |
| 核心定位 | Claude Code 的 Python 重实现 |
2. 核心设计思路
2.1 设计哲学
项目遵循以下核心设计原则：
- 高保真移植：保留原始 Claude Code 的架构设计，同时适配 Python 的惯用模式
- 生产级运行：真正的 Agent 运行时，而非源码转储
- 可扩展性：可读性优先的 Python 代码库，支持技能扩展
- 多模型兼容：通过抽象层支持多家 LLM 提供商
2.2 核心工作流程
用户输入(REPL/CLI)
→ 命令解析(Command System)
→ Agent 循环(Agent Loop)
→ LLM 调用(Provider)
→ 工具执行(Tool System)
→ 结果返回
→ 流式输出(Stream Output)
3. 整体架构框架
3.1 模块结构（30+ 子模块）
src/
├── agent/ # Agent 核心：对话与会话管理
│ ├── conversation.py # 对话数据模型（Message/Conversation）
│ └── session.py # 会话状态管理
├── assistant/ # 助手功能（初始化占位）
├── bootstrap/ # 启动/初始化流程
├── bridge/ # 桥接层
├── buddy/ # 伙伴系统
├── command_system/ # 命令系统
├── compact_service/ # 上下文压缩服务
├── components/ # UI 组件
├── constants/ # 常量定义
├── context_system/ # 上下文管理
├── coordinator/ # 协调器
├── entrypoints/ # 入口点定义
├── hooks/ # 生命周期钩子
├── keybindings/ # 键盘快捷键
├── memdir/ # 内存目录管理
├── migrations/ # 数据迁移
├── native_ts/ # TypeScript 原生代码引用
├── outputStyles/ # 输出样式
├── plugins/ # 插件系统
├── providers/ # LLM 提供商抽象层
│ ├── base.py # 提供商抽象基类
│ ├── anthropic_provider.py
│ ├── openai_provider.py
│ ├── openai_compatible.py
│ ├── glm_provider.py
│ └── minimax_provider.py
├── reference_data/ # 参考数据
├── remote/ # 远程运行时
├── repl/ # REPL 交互核心
│ └── core.py # REPL 主循环
├── schemas/ # 数据模式定义
├── screens/ # 终端界面
├── server/ # 服务端组件
├── services/ # 业务服务层
├── skills/ # 技能系统
├── state/ # 全局状态管理
├── tool_system/ # 工具系统核心
│ ├── agent_loop.py # Agent 主循环
│ ├── context.py # 工具上下文
│ ├── defaults.py # 默认配置
│ ├── diff_utils.py # Diff 工具
│ ├── errors.py # 错误定义
│ ├── loader.py # 工具加载器
│ ├── permission_handler.py
│ ├── permissions.py # 权限控制
│ ├── protocol.py # 工具调用协议
│ ├── registry.py # 工具注册表
│ ├── schema_validation.py
│ ├── task_manager.py # 任务管理
│ └── tools/ # 内置工具集
├── types/ # 类型定义
├── upstreamproxy/ # 上游代理
├── utils/ # 工具函数
├── vim/ # Vim 集成
├── voice/ # 语音功能
├── cli.py # CLI 入口
├── main.py # 主程序入口
├── runtime.py # 运行时环境
├── repl.py # REPL 实现
├── config.py # 配置管理
└── context.py # 上下文管理
3.2 分层架构
┌─────────────────────────────────────┐
│ 用户界面层 │
│ CLI (cli.py) / REPL (repl/core.py) │
├─────────────────────────────────────┤
│ 命令系统层 │
│ Command System / Skill System │
├─────────────────────────────────────┤
│ Agent 核心层 │
│ Agent Loop / Conversation / Session │
├─────────────────────────────────────┤
│ 提供商抽象层 │
│ Providers (Base + 具体实现) │
├─────────────────────────────────────┤
│ 工具系统层 │
│ Tool System / Registry / Protocol │
├─────────────────────────────────────┤
│ 基础设施层 │
│ Config / State / Utils / Hooks │
└─────────────────────────────────────┘
4. 核心原理与算法
4.1 Agent 循环（Agent Loop）
Agent 循环是整个系统的核心，采用ReAct（Reasoning + Acting）模式：
# 伪代码示意
class AgentLoop:
def run(self, user_input):
# 1. 将用户输入添加到对话历史
conversation.add_user_message(user_input)
# 2. 主循环：思考-行动-观察
while not done:
# 2.1 调用 LLM 获取响应
response = provider.chat(
messages=conversation.messages,
tools=available_tools # Function Calling
)
# 2.2 检查是否包含工具调用
if response.tool_uses:
for tool_call in response.tool_uses:
# 2.3 执行工具
result = execute_tool(tool_call)
# 2.4 将工具结果添加到对话
conversation.add_tool_result(result)
else:
# 2.5 直接返回文本响应
return response.content
关键特性：
- 流式处理：支持 SSE（Server-Sent Events）流式输出
- 多轮迭代：工具调用结果会反馈给 LLM 进行下一轮推理
- 上下文窗口管理：
max_history=100自动裁剪历史消息
4.2 工具调用协议（Tool Protocol）
@dataclass(frozen=True)
class ToolCall:
name: str # 工具名称（如 Read, Grep, WebFetch）
input: dict # 工具参数
tool_use_id: str # 唯一标识符
@dataclass(frozen=True)
class ToolResult:
name: str # 工具名称
output: Any # 执行结果
is_error: bool # 是否出错
tool_use_id: str # 对应 ToolCall 的 ID
content_type: str # "text" 或 "json"
工具执行流程：
- LLM 通过 Function Calling 返回
ToolCall - 系统通过
registry.py查找对应工具 loader.py加载工具实现permission_handler.py检查权限- 执行工具并封装为
ToolResult - 结果反馈到对话上下文
4.3 对话管理系统
@dataclass
class Message:
role: str # "user" | "assistant" | "system"
content: str | list[ContentBlock]
timestamp: str
_is_internal: bool # 内部标记（如压缩边界）
@dataclass
class Conversation:
messages: list[Message]
max_history: int = 100 # 滑动窗口限制
内容块类型：
TextContentBlock：纯文本内容ToolUseContentBlock：工具调用请求ToolResultContentBlock：工具执行结果
4.4 多提供商抽象架构
class BaseProvider(ABC):
def __init__(self, api_key, base_url=None, model=None):
self.api_key = api_key
self.base_url = base_url
self.model = model
@abstractmethod
def chat(self, messages, tools=None, **kwargs) -> ChatResponse:
"""核心对话接口"""
@abstractmethod
def stream_chat(self, messages, tools=None, **kwargs) -> Generator:
"""流式对话接口"""
已实现的提供商：
| 提供商 | 文件 | 说明 |
|---|---|---|
| Anthropic Claude | anthropic_provider.py |
原生 Claude API |
| OpenAI GPT | openai_provider.py |
OpenAI 官方 API |
| OpenAI Compatible | openai_compatible.py |
兼容 OpenAI 格式的第三方 API |
| Zhipu GLM | glm_provider.py |
智谱 AI |
| MiniMax | minimax_provider.py |
MiniMax API |
4.5 技能系统（Skill System）
技能系统是可编程扩展的核心，基于 Markdown 驱动的声明式配置：
---
description: Explain code with diagrams and analogies
allowed-tools:
- Read
- Grep
- Glob
arguments: [path]
---
Explain the code in $path. Start with an analogy, then draw a diagram.
技能加载层级：
- 项目级技能：
.clawd/skills/或.claude/skills/目录 - 用户级技能：用户 home 目录下的技能
- 内置技能：随项目分发的默认技能
技能运行时：
- 通过
/skill-name命令触发 - 支持命名参数传递
- 工具沙箱限制（
allowed-tools白名单） - 动态加载和热更新
4.6 上下文压缩（Compact Service）
为解决长对话的 token 限制问题，系统实现了上下文压缩：
完整对话历史
→ 触发压缩条件（token 阈值）
→ 调用 /compact 命令
→ 生成历史摘要
→ 替换为压缩后的上下文
→ 继续对话
4.7 流式输出算法
# 流式处理流程
def stream_response(provider, messages, tools):
# 1. 建立 SSE 连接
stream = provider.stream_chat(messages, tools)
# 2. 实时解析内容块
for chunk in stream:
if chunk.type == "text":
# 2.1 文本块：直接输出到终端
yield ("text", chunk.text)
elif chunk.type == "tool_use":
# 2.2 工具调用块：显示工具执行状态
yield ("tool_start", chunk.name)
elif chunk.type == "tool_result":
# 2.3 工具结果块：显示执行结果
yield ("tool_end", chunk.result)
# 3. 完整响应缓存（用于 /render-last 重新渲染）
cache_full_response()
5. 关键数据流
5.1 正常对话流程
┌────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐ ┌────────┐
│ 用户 │───→│ REPL/ │───→│ Agent │───→│ Provider │───→│ LLM │
│ 输入 │ │ CLI │ │ Loop │ │ Layer │ │ API │
└────────┘ └──────────┘ └────┬────┘ └──────────┘ └───┬────┘
│ │
│ ┌───────────────────────────┘
│ │ 返回文本响应
│ ▼
│ ┌────────┐
│ │ 直接 │
└─┤ 输出 │
└────────┘
5.2 工具调用流程
┌────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐ ┌────────┐
│ 用户 │───→│ REPL/ │───→│ Agent │───→│ Provider │───→│ LLM │
│ 输入 │ │ CLI │ │ Loop │ │ Layer │ │ API │
└────────┘ └──────────┘ └────┬────┘ └──────────┘ └───┬────┘
▲ │
│ 返回工具调用请求 │
│ ┌───────────────────────────┘
│ │
│ ▼
│ ┌──────────┐ ┌────────┐
│ │ Tool │───→│ 文件系统│
└─┤ Registry │ │ 网络等 │
└──────────┘ └────────┘
6. 关键技术亮点
6.1 架构设计亮点
| 特性 | 说明 |
|---|---|
| 模块化设计 | 30+ 独立模块，职责清晰，便于扩展 |
| 抽象提供商 | 统一接口支持多模型，切换零成本 |
| 工具沙箱 | 技能级别的工具权限控制 |
| 流式架构 | 全链路流式处理，无阻塞等待 |
| 热加载技能 | Markdown 驱动，无需重启即可扩展 |
6.2 与原版 Claude Code 的对比
| 维度 | Claude Code (原版) | Clawd Code (本项目) |
|---|---|---|
| 语言 | TypeScript | Python |
| 开源 | 闭源 | MIT 开源 |
| 可扩展性 | 有限 | 高（技能系统） |
| 模型支持 | Anthropic 独占 | 多提供商 |
| 社区 | 官方维护 | 社区驱动 |
7. 总结
Clawd Code 是一个架构清晰、设计精良的 Claude Code Python 重实现。其核心价值在于：
- 完整的 Agent 架构：ReAct 循环 + Function Calling + 工具系统
- 生产级设计：流式输出、会话管理、错误处理、权限控制
- 高度可扩展：技能系统、插件架构、多模型支持
- Python 原生：充分利用 Python 生态，易于二次开发
该项目为理解 Claude Code 的内部工作原理提供了极佳的参考，同时也是构建 Python Agent 应用的优质基础框架。
欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。
更多推荐
11
0- 0
已为社区贡献2条内容
所有评论(0)