如何学习opencode和openclaw源码

从"会用"到"读懂源码"：OpenCode 与 OpenClaw 源码学习指南

随着 AI Coding 和 Agent 技术快速发展，OpenCode、OpenClaw 这类开源项目越来越值得深入研究。

很多开发者在使用这些工具时，能够完成代码生成、文件修改、Tool Calling、Skill 调用等操作，但一旦遇到问题，就只能依赖日志、搜索和 AI 问答。

如果想真正掌握这类系统，一个更有效的方法是：

从"会使用 AI Agent"进一步学习到"理解 AI Agent Runtime 的源码实现"。

本文介绍如何选择源码阅读工具，以及如何系统学习 OpenCode 和 OpenClaw 的源码。

一、先选择合适的编辑器

如果主要研究 OpenCode 和 OpenClaw，我推荐：

VS Code + OpenCode + Git + ripgrep

而不是一开始就使用 IntelliJ IDEA。

编辑器选择

工具	推荐度	适合场景
VS Code	⭐⭐⭐⭐⭐	OpenCode/OpenClaw 源码阅读和调试
Cursor	⭐⭐⭐⭐⭐	AI 辅助源码理解
IntelliJ IDEA	⭐⭐⭐⭐	Java/Spring 项目
WebStorm	⭐⭐⭐⭐	TypeScript/Node.js 项目
Neovim	⭐⭐⭐	熟悉之后可以提高效率

OpenCode 和 OpenClaw 的核心技术栈更偏向 TypeScript/Node.js，因此 VS Code 是非常自然的选择。

更重要的是：

不要让 OpenCode 取代编辑器，而应该让 OpenCode 成为你的源码研究助手。

也就是说：

复制代码

VS Code
  │
  ├── 阅读源码
  ├── 搜索代码
  ├── 调试
  ├── Git
  │
  └── OpenCode
        │
        ├── 分析代码
        ├── 解释调用链
        ├── 定位核心模块
        └── 辅助修改和实验

二、不要试图从第一行读到最后一行

这是学习大型开源项目时最容易踩的坑。

例如打开一个项目：

复制代码

src/
├── a.ts
├── b.ts
├── c.ts
├── d.ts
├── ...

然后从第一个文件开始看。

这种方式通常很快就会迷路。

更好的方法是：

从一个真实问题开始，沿着调用链阅读源码。

例如：

复制代码

用户输入
   ↓
Session
   ↓
Agent
   ↓
LLM
   ↓
Tool Call
   ↓
Tool Executor
   ↓
Tool Result
   ↓
Agent Loop
   ↓
最终结果

通过一个完整请求，把整个系统串起来。

当你能够解释这条调用链之后，再深入研究每一个模块。

三、OpenCode 应该重点学习什么

OpenCode 可以理解为一个 AI Coding Agent Runtime。

它最值得研究的并不是 UI，而是 Agent 如何运行。

建议重点关注以下模块：

复制代码

Agent
Session
Message
Model
Provider
Tool
Prompt
Context
Permission
Storage
MCP

1. Agent

Agent 是整个系统的核心。

首先需要理解：

复制代码

Agent
 ├── System Prompt
 ├── Model
 ├── Tools
 ├── Permissions
 └── Execution Loop

重点思考几个问题：

Agent 是如何创建的？
Agent 如何选择模型？
Agent 如何获得 Tools？
Agent 如何决定下一步操作？
Agent Loop 在哪里实现？

2. Tool

Tool 是 AI Agent 真正执行操作的基础。

例如：

复制代码

Read File
Write File
Edit File
Shell
Search
Grep

基本运行模式是：

复制代码

LLM
 ↓
Tool Call
 ↓
Tool Executor
 ↓
Tool Result
 ↓
LLM

这实际上就是现代 AI Agent 的核心循环之一。

理解 Tool Architecture 后，你会发现很多 Agent 框架的设计其实具有高度相似性。

3. Session

Session 负责保存 Agent 与用户之间的交互状态。

可以抽象为：

复制代码

Session
 ├── Messages
 ├── Context
 ├── Model
 ├── Tools
 ├── State
 └── History

这里需要重点理解：

Agent 为什么能够记住之前发生过什么？

答案通常并不是简单的"模型有记忆"，而是系统通过 Session、Message History、Context Management 等机制不断把相关信息提供给模型。

4. Context

Context 是 AI Agent 系统中非常重要的一层。

可以抽象为：

复制代码

Context
 ├── System
 ├── User
 ├── Assistant
 ├── Tool
 ├── Files
 └── Previous Messages

进一步需要研究：

Context Window
Token
Message History
Context Compaction
Context Pruning
文件上下文
Tool Result

当项目越来越大时，Context Management 往往会成为 Agent 系统的核心问题之一。

四、OpenCode 最值得研究的一条调用链

例如用户输入：

复制代码

帮我修改 UserService.java

可以从源码追踪：

复制代码

User Input
    ↓
Session
    ↓
Agent
    ↓
Prompt / Context
    ↓
LLM Request
    ↓
Model Response
    ↓
Tool Call
    ↓
Read File
    ↓
Tool Result
    ↓
LLM
    ↓
Edit File
    ↓
Tool Result
    ↓
LLM
    ↓
Final Answer

如果能够从源码完整追踪这条链路，就基本掌握了 OpenCode 的核心运行机制。

五、OpenClaw 应该重点学习什么

OpenClaw 与 OpenCode 的定位有所不同。

如果说 OpenCode 更偏向：

AI Coding Agent

那么 OpenClaw 更值得从：

通用 Agent Runtime

的角度去理解。

建议重点关注：

复制代码

Gateway
Session
Agent
Message
Channel
Skill
Tool
Memory
Plugin
Event
Cron
Multi-Agent

六、OpenClaw 最重要的模块：Gateway

如果之前使用过 OpenClaw，可能会遇到类似：

复制代码

127.0.0.1:18789
Gateway
RPC
Unauthorized
Gateway Token
Connection Refused

这些问题其实都是非常好的源码学习入口。

可以从下面的架构开始理解：

复制代码

Client
   ↓
Gateway
   ↓
Agent Runtime
   ↓
LLM

然后进一步研究：

复制代码

Gateway
 ├── Connection
 ├── Authentication
 ├── RPC
 ├── Session
 ├── Event
 └── Agent Dispatch

这样以后再遇到 Gateway 相关错误，就不再只是"查错误日志"，而是能够理解错误发生在整个调用链的哪一层。

七、研究 OpenClaw 的完整消息链路

例如从飞书发送一条消息：

复制代码

Feishu
   ↓
Channel
   ↓
Gateway
   ↓
Message Routing
   ↓
Session
   ↓
Agent
   ↓
Model
   ↓
Tool / Skill
   ↓
Agent Loop
   ↓
Response
   ↓
Gateway
   ↓
Feishu

源码学习时，可以围绕一个问题展开：

"我在飞书发送一句话以后，OpenClaw 内部到底发生了什么？"

沿着这个问题追踪源码，比直接阅读整个项目有效得多。

八、推荐采用"问题驱动"的源码学习方式

不要把学习目标设置成：

"我要把 OpenCode 源码看完。"

而应该设置成：

"我要回答一个关于 Agent Runtime 的问题。"

例如 OpenCode：

复制代码

1. 用户输入如何进入 Agent？

2. Agent 如何调用 LLM？

3. LLM 如何调用 Tool？

4. Tool 如何执行 Shell？

5. Tool 返回结果后如何继续 Agent Loop？

6. Context 如何管理？

7. Context 太长怎么办？

8. Session 如何保存？

9. MCP 如何接入？

10. Permission 如何控制？

OpenClaw：

复制代码

1. Gateway 如何启动？

2. Gateway 如何接收消息？

3. Feishu 消息如何进入 Agent？

4. Agent 如何选择 Model？

5. Skill 如何发现？

6. Tool 如何注册？

7. Plugin 如何加载？

8. Memory 如何工作？

9. Session 如何保存？

10. Cron 如何触发 Agent？

11. 多 Agent 如何协作？

每解决一个问题，就相当于完成了一个源码学习单元。

九、让 OpenCode 成为你的"源码老师"

学习 OpenCode 和 OpenClaw 最大的优势之一，就是可以使用 AI 来辅助理解源码。

例如在源码目录中让 OpenCode 分析某个函数：

复制代码

Explain this function.

Please tell me:

1. Who calls it?
2. What calls does it make?
3. What state does it modify?
4. What are the important abstractions?
5. Where does the result go?
6. Give me the complete call chain.

然后继续追踪：

复制代码

Trace this call chain until the LLM request is sent.

接着：

复制代码

Now trace the response back to the user.

这样就可以把一个陌生函数逐步放回整个系统架构中理解。

十、可以把 OpenCode 设置成"源码学习 Agent"

可以给 OpenCode 一个固定的源码研究角色：

复制代码

I am studying the source code of an AI Agent system.

Act as a senior TypeScript and AI Agent architect.

Do not modify any files unless explicitly requested.

For every question:

1. Explain the architecture.
2. Point to the relevant source files.
3. Explain the call chain.
4. Explain why the code is designed this way.
5. Explain important abstractions.
6. Explain possible alternatives.
7. Give me a small learning exercise.

Start by explaining the complete request lifecycle.

这样使用 AI 的方式和普通的代码补全完全不同。

它不是单纯帮你写代码，而是在帮助你：

建立源码级别的架构认知。

十一、建议建立自己的源码学习工作区

可以建立一个统一目录：

复制代码

ai-source/
│
├── opencode/
│
├── openclaw/
│
├── notes/
│   ├── opencode.md
│   ├── openclaw.md
│   ├── agent.md
│   ├── tool.md
│   ├── context.md
│   └── architecture.md
│
└── diagrams/
    ├── opencode-agent.md
    └── openclaw-runtime.md

VS Code 直接打开：

复制代码

ai-source/

这样可以同时搜索两个项目。

例如搜索：

复制代码

Agent
Tool
Session
Gateway
Plugin
Memory
Context

非常适合做横向对比。

十二、OpenCode 和 OpenClaw 最值得对比的部分

当两个项目分别入门以后，不要继续孤立地研究。

可以开始进行横向比较：

技术领域	OpenCode	OpenClaw
Agent	核心	核心
Agent Loop	重点	重点
Tool	核心	核心
Context	重点	重点
Session	重点	重点
Model	重点	重点
MCP	重点	重点
Plugin	有	重点
Skill	相对较弱	核心
Gateway	相对较弱	核心
Channel	相对较弱	核心
Memory	重点	重点
Multi-Agent	可研究	重点
Automation	相对较弱	重点

通过这种方式，可以逐渐建立自己对 AI Agent Runtime 的抽象认识。

十三、推荐的四周学习路线

第一周：OpenCode

复制代码

Day 1    项目结构
Day 2    Agent
Day 3    Session
Day 4    Tool
Day 5    Model / Provider
Day 6    Context / Compaction
Day 7    完整 Agent Loop

目标：

能够从用户输入一路追踪到最终回答。

第二周：OpenClaw

复制代码

Day 1    Gateway
Day 2    Channel
Day 3    Agent
Day 4    Skill
Day 5    Tool
Day 6    Plugin
Day 7    Memory / Session

目标：

能够解释一条消息从 Channel 到 Agent，再返回 Channel 的完整生命周期。

第三周：横向对比

重点研究：

复制代码

Agent Loop
Tool Architecture
Context Management
Memory
Plugin
MCP
Permission
Session
Multi-Agent

目标：

不只是理解某一个项目，而是理解 AI Agent Runtime 的通用设计。

第四周：自己实现 Mini Agent

最终可以尝试实现一个非常精简的 Agent Runtime：

复制代码

             Your Agent Runtime
                     │
          ┌──────────┼──────────┐
          ▼          ▼          ▼
        Model       Tool       Memory
          │          │          │
          └──────────┼──────────┘
                     ▼
                 Agent Loop
                     │
                     ▼
                  Result

只实现最核心的部分：

复制代码

LLM
Tool
Agent Loop
Context
Memory

不需要一开始就实现完整的 Gateway、Plugin、UI 等复杂功能。

当你能够自己实现一个 Mini Agent，再回头看 OpenCode 和 OpenClaw 的源码，会发现很多设计会突然变得非常容易理解。

十四、最终学习目标：从"源码阅读"升级到"架构能力"

真正值得追求的并不是：

"我看过 OpenCode 源码。"

而是最终能够自己画出这样的架构：

复制代码

                    Client
                      │
                      ▼
                  Gateway
                      │
                      ▼
                   Session
                      │
                      ▼
                    Agent
                      │
          ┌───────────┼───────────┐
          ▼           ▼           ▼
       Context       Model       Tools
          │           │           │
          │           ▼           │
          │          LLM           │
          │                       │
          └───────────┬───────────┘
                      ▼
                  Agent Loop
                      │
                      ▼
                  Final Answer

到了这个阶段，你学习的就已经不再只是某一个开源项目。

你真正掌握的是：

AI Agent Runtime 的设计思想。

这对于以后开发 AI Coding Agent、企业级 Agent、自动化 Agent、数据迁移 Agent、AI 咨询 Agent、学习顾问 Agent 等系统，都具有直接的帮助。

十五、总结

如果现在开始学习 OpenCode 和 OpenClaw，我的建议非常明确：

编辑器：

VS Code

AI 辅助：

OpenCode

代码导航：

Git + ripgrep

学习方式：

问题驱动 + 调用链追踪

学习顺序：

复制代码

OpenCode
   ↓
OpenClaw
   ↓
横向对比
   ↓
Mini Agent Runtime

不要追求"把源码全部看完"。

真正有效的目标应该是：

从一个真实请求出发，沿着调用链找到 Agent、Model、Context、Tool、Session 和 Runtime，最终理解整个系统为什么这样设计。

当你能够自己解释一个 Agent 从"接收请求"到"调用模型"、从"调用 Tool"到"返回结果"的完整生命周期时，你就已经从一个 AI 工具使用者，开始进入 AI Agent 系统开发者 的阶段。