跳到主要内容
Go / Golang AI
PicoClaw 超轻量级 AI 智能体架构设计 PicoClaw 是基于 Go 语言构建的超轻量级 AI 智能体，采用分层模块化架构实现高内聚低耦合。核心特性包括内存占用低于 10MB、支持多平台二进制运行及 AI 辅助代码生成。系统通过消息总线解耦各模块，集成多种 LLM 提供商与聊天渠道，具备完善的容错降级机制。技能模块采用三层优先级加载策略，支持灵活扩展。内置安全沙箱限制智能体操作范围，确保在低资源硬件环境下的高可用性与安全性。
忘忧 发布于 2026/3/15 更新于 2026/4/27
1. 项目概述
1.1 项目简介
PicoClaw 是一个用 Go 语言重构的超轻量级个人 AI 助手，灵感来源于 nanobot 。项目采用 AI 自举的方式，由 AI 智能体主导了整个架构迁移和代码优化过程。
1.2 核心特性
超轻量级 ：内存占用 < 10MB，比 Clawdbot 小 99%极低硬件成本 ：可在价值 $10 的硬件上运行极速启动 ：在 0.6GHz 单核上 1 秒内启动多平台支持 ：单一自包含二进制，支持 RISC-V、ARM、x86AI 自举 ：95% 的核心代码由 AI 生成
1.3 技术栈
语言 ：Go 1.25.7核心依赖 ：
github.com/openai/openai-go/v3：OpenAI 兼容 APIgithub.com/anthropics/anthropic-sdk-go：Anthropic APIgithub.com/mymmrac/telego：Telegram Botgithub.com/bwmarrin/discordgo：Discord Botgithub.com/slack-go/slack：Slack 集成以及其他 10+ 种渠道的 SDK
2. 架构设计原则
2.1 核心设计原则
轻量化优先 ：所有设计决策都以最小化内存占用为首要考虑零依赖原则 ：核心功能尽量减少外部依赖插件化架构 ：各功能模块松耦合，易于扩展容错设计 ：内置多重容错和降级机制安全沙箱 ：默认限制智能体的操作范围
2.2 架构风格
采用 分层模块化架构 ，通过清晰的职责分离和接口抽象实现高内聚低耦合。
3. 系统架构
3.1 整体架构图
┌─────────────────────────────────────────────────────────────────────────┐
│ 应用层 (App Layer) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────┐ │
│ │ CLI (cmd) │ │ Gateway │ │ Onboard │ │ Auth │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────┐
│ 业务层 (Business Layer) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────┐ │
│ │ Agent │ │ Channels │ │ Cron │ │ Skills │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────┐
│ 核心层 (Core Layer) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────┐ │
│ │ Providers │ │ Tools │ │ Session │ │ Bus │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────┐
│ 基础设施层 (Infrastructure Layer) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────┐ │
│ │ Config │ │ Logger │ │ State │ │ Utils │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
3.2 目录结构说明 picoclaw-main/
├── cmd/picoclaw/
│ ├── main.go
│ └── cmd_*.go
├── pkg/
│ ├── agent/
│ ├── auth/
│ ├── bus/
│ ├── channels/
│ ├── config/
│ ├── constants/
│ ├── cron/
│ ├── devices/
│ ├── health/
│ ├── heartbeat/
│ ├── logger/
│ ├── migrate/
│ ├── providers/
│ ├── routing/
│ ├── session/
│ ├── skills/
│ ├── state/
│ ├── tools/
│ ├── utils/
│ └── voice/
├── config/
├── docs/
└── workspace/
4. 核心模块详解
4.1 Agent 模块（pkg/agent）
4.1.1 模块职责
智能体实例的生命周期管理
上下文构建
工具调用循环
会话管理
记忆管理
4.1.2 核心数据结构
type AgentInstance struct {
ID string
Name string
Model string
Fallbacks []string
Workspace string
MaxIterations int
MaxTokens int
Temperature float64
ContextWindow int
Provider providers.LLMProvider
Sessions *session.SessionManager
ContextBuilder *ContextBuilder
Tools *tools.ToolRegistry
Subagents *config.SubagentsConfig
SkillsFilter []string
Candidates []providers.FallbackCandidate
}
4.1.3 工作流程 用户输入
↓
加载/创建会话
↓
构建上下文 (ContextBuilder)
↓
┌─────────────────────────────────┐
│ 工具调用循环 (Tool Loop) │
│ ┌───────────────────────────┐ │
│ │ 调用 LLM 获取响应 │ │
│ └───────────────┬───────────┘ │
│ ↓ │
│ ┌───────────────────────────┐ │
│ │ 判断是否需要工具调用？ │ │
│ └───────────────┬───────────┘ │
│ ↓ │
│ ┌───────────────────────────┐ │
│ │ 执行工具并获取结果 │ │
│ └───────────────┬───────────┘ │
│ ↓ │
│ ┌───────────────────────────┐ │
│ │ 将结果加入上下文 │ │
│ └───────────────────────────┘ │
└─────────────────────────────────┘
↓ (达到最大迭代或无工具调用)
返回最终响应给用户
4.2 Providers 模块（pkg/providers）
4.2.1 模块职责 Providers 模块负责与各种 LLM 提供商对接，提供统一的接口。
4.2.2 核心接口
type LLMProvider interface {
Chat(ctx context.Context, messages []Message, tools []ToolDefinition, model string , options map [string ]any) (*LLMResponse, error )
GetDefaultModel() string
}
4.2.3 支持的提供商
OpenAI 兼容协议：OpenRouter、OpenAI、Zhipu、Groq、vLLM、Ollama 等
Anthropic 协议：Claude 原生 API
自定义协议：Antigravity、GitHub Copilot 等
4.2.4 容错与降级机制 Primary Model (首选)
↓ (失败)
Fallback 1
↓ (失败)
Fallback 2
↓ (失败)
...
FailoverAuth：认证失败FailoverRateLimit：速率限制FailoverBilling：计费问题FailoverTimeout：超时FailoverFormat：格式错误（不可重试）FailoverOverloaded：服务过载FailoverUnknown：未知错误
4.3 Channels 模块（pkg/channels）
4.3.1 模块职责 Channels 模块负责与各种聊天应用对接，提供统一的消息收发接口。
4.3.2 支持的渠道 渠道 特点 Telegram 易于配置，只需 Token Discord 需要 Bot Token + Intents QQ AppID + AppSecret DingTalk 中等难度，需要应用凭证 LINE 需要凭证 + Webhook URL WeCom 支持机器人和自建应用两种方式 Slack 需 Bot Token WhatsApp 需要 Bridge URL Feishu 支持 32/64 位两种 MaixCAM 相机设备集成 OneBot 通用机器人协议
4.3.3 消息流转 外部渠道 (Telegram/Discord/...)
↓ Channel Adapter
↓ Message Bus (bus.InboundMessage)
↓ Agent Processing
↓ Message Bus (bus.OutboundMessage)
↓ Outbound Dispatcher
↓ Channel Adapter
↓ 外部渠道
4.3.4 Manager 架构 ChannelManager 负责所有渠道的生命周期管理，包括：
初始化配置的渠道
启动/停止所有渠道
分发出站消息
状态查询
4.4 Tools 模块（pkg/tools）
4.4.1 模块职责
4.4.2 内置工具 工具 功能 read_file读取文件 write_file写入文件 list_dir列出目录 edit_file编辑文件 append_file追加文件 exec执行命令 web_search网页搜索 spawn生成子智能体 message发送消息 cron定时任务 skills_install安装技能 skills_search搜索技能
4.4.3 安全沙箱
文件操作限制在 workspace 内
命令执行路径限制在 workspace 内
阻止危险命令（如 rm -rf、format 等）
4.5 Session 模块（pkg/session）
4.5.1 模块职责
4.5.2 存储结构 ~/.picoclaw/workspace/sessions/
├── <session-key-1 > .json
├── <session-key-2 > .json
└── ...
4.6 Skills 模块（pkg/skills）
4.6.1 模块职责 Skills 模块负责技能的安装、加载、搜索和管理，是 PicoClaw 扩展性的核心模块之一。
4.6.2 核心设计原理
4.6.2.1 技能概念 技能是一种可扩展的机制，允许智能体学习和应用特定领域的专业知识。技能本质上是 Markdown 格式的知识文档，包含：
领域特定的指令和最佳实践
工具使用示例
工作流程指南
4.6.2.2 三层加载机制 Skills 模块采用三层优先级的加载机制，允许灵活的技能覆盖：
┌─────────────────────────────────────────┐
│ 1. Workspace Skills (最高优先级) │
│ ~/.picoclaw/workspace/skills/ │
│ 项目级别，可覆盖全局和内置技能 │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ 2. Global Skills (次优先级) │
│ ~/.picoclaw/skills/ │
│ 全局级别，可覆盖内置技能 │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ 3. Builtin Skills (最低优先级) │
│ 系统内置 │
└─────────────────────────────────────────┘
用户可以在项目级别自定义技能
全局技能可供所有项目使用
内置技能提供基础功能
4.6.3 核心数据结构
type SkillsLoader struct {
workspace string
workspaceSkills string
globalSkills string
builtinSkills string
}
type SkillInfo struct {
Name string
Path string
Source string
Description string
}
type SkillRegistry interface {
Name() string
Search(ctx context.Context, query string , limit int ) ([]SearchResult, error )
GetSkillMeta(ctx context.Context, slug string ) (*SkillMeta, error )
DownloadAndInstall(ctx context.Context, slug, version, targetDir string ) (*InstallResult, error )
}
type RegistryManager struct {
registries []SkillRegistry
maxConcurrent int
}
4.6.4 技能文件格式 一个技能由 SKILL.md 文件定义，包含 Frontmatter 和内容两部分：
---
name: github
description: "Interact with GitHub using the `gh` CLI"
metadata: {"nanobot" : {"emoji" :"🐙" ,"requires" : {"bins" : ["gh" ]}}}
---
Use the `gh` CLI to interact with GitHub...
```bash
gh pr checks 55 --repo owner/repo
**Frontmatter 支持格式：**
1. **YAML 格式** （推荐）
2. **JSON 格式** （向后兼容）
##### 4.6.5 工作流程
###### 4.6.5.1 技能加载流程
ContextBuilder 构建上下文
↓ SkillsLoader.ListSkills()
↓ 遍历三个源目录
┌─────────────────────────────────────┐
│ 1. 读取 workspace/skills/ │
│ 2. 读取 ~/.picoclaw/skills/ │
│ 3. 读取 builtin/skills/ │
└─────────────────────────────────────┘
↓
解析 SKILL.md 的 Frontmatter
↓
验证技能信息（名称、描述）
↓
去重（高优先级覆盖低优先级）
↓
返回 SkillInfo 列表
用户搜索技能
↓ RegistryManager.SearchAll()
↓
┌─────────────────────────────────────────────┐
│ 创建 Goroutine 池（限制并发数） │
│ ┌─────────────────────────────────────┐ │
│ │ Registry 1 (ClawHub) │ │
│ └─────────────────────────────────────┘ │
│ ┌─────────────────────────────────────┐ │
│ │ Registry 2 (其他) │ │
│ └─────────────────────────────────────┘ │
│ ... │
└─────────────────────────────────────────────┘
↓
收集所有搜索结果
↓
按分数降序排序
↓
限制返回数量
↓
返回给用户
用户执行 picoclaw skills install
↓ SkillInstaller.InstallFromGitHub()
↓ 检查技能是否已存在
↓ 从 GitHub 下载 SKILL.md
↓ 创建技能目录
↓ 写入 SKILL.md 文件
↓ 完成安装
##### 4.6 .6 核心功能
###### 4.6 .6 .1 技能列表与加载
```go
func (sl *SkillsLoader)ListSkills ()[] SkillInfo
func (sl *SkillsLoader)LoadSkill (name string)(string,bool)
func (sl *SkillsLoader)LoadSkillsForContext (skillNames []string)string
func (sl *SkillsLoader)BuildSkillsSummary ()string
4.6.6.2 技能安装与卸载
func (si *SkillInstaller) string )error
func (si *SkillInstaller) string )error
func (si *SkillInstaller) error )
4.6.6.3 多注册中心管理
func (rm *RegistryManager) func (rm *RegistryManager) string , limit int )([]SearchResult,error )
func (rm *RegistryManager) string ) SkillRegistry
4.6.7 技能目录结构 ~/.picoclaw/
├── skills/
│ ├── github/
│ │ └── SKILL.md
│ └── ...
└── workspace/
└── skills/
├── weather/
│ └── SKILL.md
└── ...
4.6.8 验证与安全
名称验证 ：必须是字母数字加连字符，不超过 64 字符描述验证 ：必填，不超过 1024 字符来源去重 ：高优先级技能覆盖低优先级同名技能
4.6.9 CLI 命令 命令 功能 picoclaw skills list列出已安装的技能 picoclaw skills install <repo>从 GitHub 安装技能 picoclaw skills remove <name>卸载技能 picoclaw skills search <query>搜索可用技能 picoclaw skills show <name>显示技能详情 picoclaw skills install-builtin安装内置技能 picoclaw skills list-builtin列出内置技能
4.6.10 设计优势
声明式设计 ：技能是纯文本，易于编写和理解三层覆盖机制 ：灵活的优先级管理多注册中心支持 ：可扩展的技能生态并发搜索 ：高效的多源搜索零运行时开销 ：技能仅在需要时加载到上下文向后兼容 ：支持 JSON 和 YAML 两种 Frontmatter 格式
5. 关键设计决策
5.1 模型配置设计（model_list）
5.1.1 设计原则
5.1.2 优势
零代码添加新提供商
灵活的多智能体支持
模型降级和负载均衡
集中化配置管理
5.1.3 格式 { "model_list" : [ { "model_name" : "gpt-5.2" , "model" : "openai/gpt-5.2" , "api_key" : "sk-..." , "api_base" : "https://api.openai.com/v1" } ] }
5.2 消息总线设计（bus）
5.2.1 设计原则
5.2.2 消息类型
InboundMessage：入站消息（从渠道到智能体）OutboundMessage：出站消息（从智能体到渠道）
5.3 工作区设计
5.3.1 目录结构 ~/.picoclaw/ workspace/
├── sessions/
├── memory/
├── state /
├── cron/
├── skills/
├── AGENTS.md
├── HEARTBEAT.md
├── IDENTITY.md
├── SOUL.md
├── TOOLS.md
└── USER.md
5.4 心跳任务（Heartbeat）
5.4.1 设计原理 定期读取 HEARTBEAT.md 文件并执行任务。
5.4.2 异步处理 对于耗时任务，使用 spawn 工具创建子智能体异步执行，避免阻塞心跳。
6. 数据流
6.1 完整消息处理流程 1. 用户在 Telegram 发送消息
↓
2. Telegram Channel 接收消息
↓
3. 转换为 InboundMessage 发送到 Bus
↓
4. Gateway 从 Bus 消费 InboundMessage
↓
5. 创建/加载会话
↓
6. ContextBuilder 构建上下文
↓
7. Agent Loop 开始：
├─ 调用 Provider 发送请求
├─ 接收 LLM 响应
├─ 判断是否需要工具调用
├─ 如需要，执行工具
├─ 将结果加入上下文
└─ 重复直到结束
↓
8. 生成 OutboundMessage 发送到 Bus
↓
9. Outbound Dispatcher 从 Bus 消费消息
↓
10. 找到对应的 Channel
↓
11. Channel 发送消息给用户
7. 扩展性设计
7.1 添加新的 LLM 提供商
在 pkg/providers/ 下创建新目录
实现 LLMProvider 接口
在 factory.go 中注册
配置 model_list 即可使用（对于 OpenAI 兼容协议）
7.2 添加新的聊天渠道
在 pkg/channels/ 下创建新文件
实现 Channel 接口
在 manager.go 的 initChannels() 中添加初始化代码
在 config/config.go 中添加配置结构
7.3 添加新的工具
在 pkg/tools/ 下创建新文件
实现 Tool 接口
在 ToolRegistry 中注册
7.4 添加新的技能注册中心
在 pkg/skills/ 下创建新文件（如 myregistry.go）
在 config/config.go 中添加配置结构
在 registry.go 的 NewRegistryManagerFromConfig() 中添加初始化代码
type MyRegistry struct {
}
func (r *MyRegistry) string {return "myregistry" }
func (r *MyRegistry) string , limit int )([]SearchResult,error ){
func (r *MyRegistry) string )(*SkillMeta,error ){
func (r *MyRegistry) string )(*InstallResult,error ){
7.5 创建自定义技能 cp -r my-skill ~/.picoclaw/workspace/skills/
编写 SKILL.md，包含 Frontmatter 和内容：
---
name: my-skill
description: "我的自定义技能"
---
技能内容...
8. 性能优化策略
8.1 内存优化
避免不必要的对象分配
使用对象池复用资源
及时释放不再需要的引用
流式处理大文本
8.2 启动优化
延迟加载非核心模块
并行初始化独立组件
最小化启动时的 I/O 操作
8.3 并发设计
使用 Goroutine 处理并发请求
合理使用 Channel 进行协程间通信
避免共享状态，使用消息传递
9. 安全设计
9.1 访问控制
9.2 命令安全
9.3 数据隔离
10. 部署架构
10.1 单机部署 PicoClaw Binary
├─ Agent
├─ Channels (Telegram/ Discord/ ...)
└─ Local Workspace
10.2 Docker 部署 Docker Container
├─ picoclaw-gateway (服务)
├─ picoclaw-agent (一次性)
└─ Volume: config & workspace
11. 总结 PicoClaw 采用清晰的分层模块化架构，通过以下关键设计实现了超轻量级和高性能：
清晰的职责分离 ：各模块高内聚低耦合统一的接口抽象 ：Provider、Channel、Tool 等接口事件驱动架构 ：消息总线解耦各模块容错与降级 ：多重保障机制安全沙箱 ：默认限制保护系统可扩展设计 ：易于添加新功能 这套架构使得 PicoClaw 能够在极低资源的硬件上运行，同时保持功能的完整性和可扩展性。
关键点回顾
核心架构采用四层分层设计（应用层→业务层→核心层→基础设施层），各层职责清晰、低耦合；
核心特性围绕'轻量化'展开，通过内存优化、启动优化、沙箱限制等实现低资源占用；
扩展性设计完善，支持新增 LLM 提供商、聊天渠道、工具、技能注册中心等，且技能系统采用三层优先级加载机制，灵活性高。
相关免费在线工具 RSA密钥对生成器 生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
Mermaid 预览与可视化编辑 基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
随机西班牙地址生成器 随机生成西班牙地址（支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选），支持数量快捷选择、显示全部与下载。 在线工具，随机西班牙地址生成器在线工具，online
Base64 字符串编码/解码 将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
Base64 文件转换器 将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
Markdown转HTML 将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
