IronClaw 学习笔记 00：项目全景

学完了 TypeScript 版的 AI coding agent，现在来挑战 Rust 版的个人 AI 助手。

系列目录

本系列通过从零构建 tiny-claw 来学习 IronClaw 的架构设计，共 9 个阶段：

每篇文章只讲概念和设计思想，配套的代码规格文档和实现在 external/tiny-claw/ 项目中。

---

专题索引

Agent 如何思考和行动？

Agent 如何操作世界？

Agent 如何记忆和保护？

Agent 如何通信？

---

🎯 为什么学 IronClaw？

上一个系列我们从零实现了 tiny-agent，通过 TypeScript 学习了 OpenCode 的核心设计。现在来看一个完全不同的实现——IronClaw。

IronClaw 不是 OpenCode 的 Rust 翻译。它们的定位完全不同：

共同点很重要：两者都用 Agent Loop (ReAct)、Tool 系统、Provider 抽象、Session 模型。这意味着你在 OpenCode 系列学到的核心概念，全部可以迁移过来。

为什么值得学？

1. Rust 实战——不是教科书式的练习，而是一个生产级项目的架构
2. 安全优先——OpenCode 没有的 defense in depth 安全架构，这是 AI 应用的未来方向
3. 自主执行——Routines 让 agent 从"被动响应"变为"主动执行"，这是个人助手的核心差异
4. 概念迁移——已有 OpenCode 知识做底，学起来事半功倍

---

🧠 IronClaw 是什么？

IronClaw 的哲学用一句话概括：你的 AI 助手应该为你工作，而不是反过来。

核心理念：

• 你的数据是你的——所有信息本地存储、加密，从不离开你的控制
• 透明设计——开源、可审计、没有隐藏的遥测或数据收集
• 自我扩展——动态构建新工具，不用等厂商更新
• 纵深防御——多层安全防护，防止 prompt injection 和数据泄露

和 OpenCode "帮你写代码" 不同，IronClaw 要做的是个人生活和工作的 AI 管家——帮你处理消息、管理记忆、执行自动化任务，同时确保你的数据安全。

---

🏛️ 项目结构

IronClaw 的源码大约有 27 个顶层模块。我们把它们按功能域分成四大块来理解：

核心引擎

这四个模块是 agent 的"大脑"——接收消息、思考（LLM）、行动（Tool）、协调（Agent Loop）。

持久化与记忆

IronClaw 的记忆系统比 OpenCode 复杂得多——不仅有会话记忆，还有 Workspace 文件系统和混合搜索。

安全与隔离

这整个安全层是 IronClaw 最独特的部分——OpenCode 完全没有对应物。对于一个管理个人数据的 AI 助手来说，这层防护至关重要。

通信与扩展

IronClaw 是多渠道的——同一个 agent 可以同时通过 REPL、HTTP、Telegram、Web 浏览器来交互。这和 OpenCode 只有 CLI/TUI 完全不同。

---

🔍 架构全景

IronClaw 的消息流可以用一条主路径来理解：

消息进入 → 经过某个 Channel（REPL、HTTP、Telegram、Web Gateway）到达 Agent Loop

Agent Loop → Dispatcher 判断意图 → LLM 推理 → 决定调用哪些 Tool

Tool 执行 → 可以在进程内直接执行（Built-in），也可以扔进 WASM 沙箱或 Docker 容器执行

安全过滤 → 外部数据经过四层 Safety Layer：Sanitizer → Validator → Policy → Leak Detector

结果处理 → 写入 Workspace 记忆 / 返回给用户 / 两者兼有

自主执行 → Routines Engine 可以按 cron 时间表或事件触发自动运行 Agent Loop，不需要用户发起

和 OpenCode 相比，关键差异在两条"支线路径"：

1. 隔离执行路径：不可信的工具不是在进程内直接跑，而是经过 Orchestrator 扔进 Docker 容器或 WASM 沙箱
2. 自主执行路径：Routines Engine + Scheduler + Heartbeat 让 agent 可以自动运行任务

---

🧠 核心设计模式

IronClaw 的可扩展性建立在 trait 驱动的架构上。Rust 的 trait 相当于 TypeScript 的 interface，但有更强的编译时保证。

IronClaw 定义了 10 个核心 trait：

这种模式的好处是开闭原则——对扩展开放，对修改关闭。加新功能不用改核心代码。

在 tiny-claw 系列中，我们会逐步实现这些 trait 的简化版本。每一篇对应一个 trait 子集的引入。

---

🏛️ Cargo.toml 与 Feature 系统

IronClaw 的依赖管理有一个 TypeScript 项目没有的特点：feature-gated 编译。

IronClaw 支持两种数据库后端（PostgreSQL 和 libSQL），但它们是编译时选择的——你可以只编译 PostgreSQL 支持，或只编译 libSQL 支持，或两者都要。这通过 Rust 的 feature flag 系统实现。

这意味着发布给不同用户的二进制文件可以有不同的能力——嵌入式场景用 libSQL（零依赖），服务器场景用 PostgreSQL（生产级）。

IronClaw 的核心依赖生态：

特别注意最后三个——WASM 沙箱、加密、Docker 是 IronClaw 独有的依赖，反映了它"安全优先"的定位。

---

🔍 入口与启动流程

IronClaw 的启动过程分为三大阶段：

阶段一：环境准备

加载环境变量、解析 CLI 参数、检测是否首次运行。如果是首次运行，启动 Onboard Wizard（一个 7 步交互式配置向导）。

阶段二：核心构建

通过 AppBuilder 模式分阶段初始化所有核心组件：数据库连接、密钥解密、LLM Provider 构建、Safety Layer 初始化、Tool Registry 注册、Workspace 构建、Extension Manager 加载。

AppBuilder 模式值得学习——它让测试可以独立构建任意组件子集，不用经过完整的启动流程。

阶段三：渠道接线

设置各种 Channel（REPL、HTTP、WASM Channel、Signal、Web Gateway）、注册 Hooks、创建 Agent 实例、启动运行。

关键设计：Channel 设置在 AppBuilder 之外——因为 Channel 是"可选的外壳"，核心组件不依赖于任何特定 Channel。这种分层让 agent 可以灵活组合不同的通信方式。

---

📝 本篇总结

我们要造什么？

tiny-claw 是 IronClaw 的简化实现。每一篇文章对应一次代码迭代——从一个只能 echo 的 REPL，逐步进化为一个有记忆、有安全防护、能自主运行的个人 AI 助手。

我们不会 1:1 复刻 IronClaw 的所有细节，但会覆盖它的所有核心子系统。目标是理解设计思想，而不是复制实现。

---

下一篇：IronClaw 学习笔记 01：Tool + Provider —— 工具抽象的设计哲学，以及如何统一调用多个 LLM。