lzh/picoclaw

Fork 0

mirror of https://github.com/sipeed/picoclaw.git synced 2026-06-12 18:08:54 +00:00

Files

T

Administrator f7f27e237a merge: resolve conflicts between refactor/agent and main

2026-03-22 19:21:58 +08:00

31 KiB

Raw Blame History

PicoClaw: 基于Go语言的超高效 AI 助手

$10 硬件 · <10MB 内存 · <1s 启动 · 皮皮虾，我们走！

PicoClaw 是由矽速科技 (Sipeed) 发起的独立开源项目，完全使用 Go 语言从零编写——不是 OpenClaw、NanoBot 或其他项目的分支。

🦐 PicoClaw 是一个受 NanoBot 启发的超轻量级个人 AI 助手。它采用 Go 语言 从零重构，经历了一个"自举"过程——即由 AI Agent 自身驱动了整个架构迁移和代码优化。

⚡️ 极致轻量：可在 10 美元 的硬件上运行，内存占用 <10MB。这意味着比 OpenClaw 节省 99% 的内存，比 Mac mini 便宜 98%！

Caution

🚨 安全声明

无加密货币 (NO CRYPTO): PicoClaw 没有发行任何官方代币、Token 或虚拟货币。所有在 pump.fun 或其他交易平台上的相关声称均为诈骗。

官方域名: 唯一的官方网站是 picoclaw.io，公司官网是 sipeed.com。

警惕: 许多 .ai/.org/.com/.net/... 后缀的域名被第三方抢注，请勿轻信。

注意: PicoClaw 正在初期的快速功能开发阶段，可能有尚未修复的网络安全问题，在 1.0 正式版发布前，请不要将其部署到生产环境中。

注意: PicoClaw 最近合并了大量 PR，近期版本可能内存占用较大 (10~20MB)，我们将在功能较为收敛后进行资源占用优化。

📢 新闻

2026-03-17 🚀 v0.2.3 发布！ 系统托盘 UI（Windows & Linux）、子 Agent 状态查询 (spawn_status)、实验性 Gateway 热重载、Cron 安全门控，以及 2 项安全修复。PicoClaw 已达 25K ⭐！

2026-03-09 🎉 v0.2.1 — 史上最大更新！ MCP 协议支持、4 个新频道 (Matrix/IRC/WeCom/Discord Proxy)、3 个新 Provider (Kimi/Minimax/Avian)、视觉管线、JSONL 记忆存储、模型路由。

2026-02-28 📦 v0.2.0 发布，支持 Docker Compose 和 Web UI 启动器。

2026-02-26 🎉 PicoClaw 仅 17 天突破 20K Stars！频道自动编排和能力接口上线。

更早的新闻...

2026-02-16 🎉 PicoClaw 一周内突破 12K Stars！社区维护者角色和路线图正式发布。

2026-02-13 🎉 PicoClaw 4 天内突破 5000 Stars！项目路线图和开发者群组筹建中。

2026-02-09 🎉 PicoClaw 正式发布！ 仅用 1 天构建，将 AI Agent 带入 $10 硬件与 <10MB 内存的世界。🦐 皮皮虾，我们走！

✨ 特性

🪶 超轻量级: 核心功能内存占用 <10MB — 比 OpenClaw 小 99%。*

💰 极低成本: 高效到足以在 $10 的硬件上运行 — 比 Mac mini 便宜 98%。

⚡️ 闪电启动: 启动速度快 400 倍，即使在 0.6GHz 单核处理器上也能在 1 秒内启动。

🌍 真正可移植: 跨 RISC-V、ARM、MIPS 和 x86 架构的单二进制文件，一键运行！

🤖 AI 自举: 纯 Go 语言原生实现 — 95% 的核心代码由 Agent 生成，并经由"人机回环"微调。

🔌 MCP 支持: 原生 Model Context Protocol 集成 — 连接任意 MCP 服务器扩展 Agent 能力。

👁️ 视觉管线: 直接向 Agent 发送图片和文件 — 自动 base64 编码对接多模态 LLM。

🧠 智能路由: 基于规则的模型路由 — 简单查询走轻量模型，节省 API 成本。

*近期版本因快速合并 PR 可能占用 10–20MB，资源优化已列入计划。启动速度对比基于 0.8GHz 单核实测（见下方对比表）。

	OpenClaw	NanoBot	PicoClaw
语言	TypeScript	Python	Go
RAM	>1GB	>100MB	< 10MB*
启动时间 (0.8GHz core)	>500s	>30s	<1s
成本	Mac Mini $599	大多数 Linux 开发板 ~$50	任意 Linux 开发板低至 $10

📋 硬件兼容列表 — 查看所有已测试的板卡，从 $5 RISC-V 到树莓派到安卓手机。你的板卡没在列表中？欢迎提交 PR！

🦾 演示

🛠️ 标准助手工作流

🧩 全栈工程师模式	🗂️ 日志与规划管理	🔎 网络搜索与学习

开发 • 部署 • 扩展	日程 • 自动化 • 记忆	发现 • 洞察 • 趋势

📱 在手机上轻松运行

PicoClaw 可以将你 10 年前的老旧手机废物利用，变身成为你的 AI 助理！快速指南：

安装 Termux（可从 GitHub Releases 下载，或在 F-Droid 等应用商店搜索）
打开后执行指令

# 从 Release 页面下载最新版本
wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
tar xzf picoclaw_Linux_arm64.tar.gz
pkg install proot
termux-chroot ./picoclaw onboard   # chroot 提供标准 Linux 文件系统布局

然后跟随下面的"快速开始"章节继续配置 PicoClaw 即可使用！

🐜 创新的低占用部署

PicoClaw 几乎可以部署在任何 Linux 设备上！

$9.9 LicheeRV-Nano E(网口) 或 W(WiFi6) 版本，用于极简家庭助手
$30~50 NanoKVM，或 $100 NanoKVM-Pro，用于自动化服务器运维
$50 MaixCAM 或 $100 MaixCAM2，用于智能监控

https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4

🌟 更多部署案例敬请期待！

📦 安装

从 picoclaw.io 下载（推荐）

访问 picoclaw.io — 官网自动检测你的平台，提供一键下载，无需手动选择架构。

下载预编译二进制文件

也可以从 GitHub Releases 页面手动下载对应平台的二进制文件。

从源码构建（开发用）

git clone https://github.com/sipeed/picoclaw.git

cd picoclaw
make deps

# 构建（无需安装）
make build

# 为多平台构建
make build-all

# 为 Raspberry Pi Zero 2 W 构建（32位: make build-linux-arm; 64位: make build-linux-arm64）
make build-pi-zero

# 构建并安装
make install

Raspberry Pi Zero 2 W: 请使用与系统匹配的二进制文件：32 位 Raspberry Pi OS → make build-linux-arm；64 位 → make build-linux-arm64。或运行 make build-pi-zero 同时构建两者。

📚 文档

详细指南请参阅以下文档，README 仅涵盖快速入门。

主题	说明
🐳 Docker 与快速开始	Docker Compose 配置、Launcher/Agent 模式、快速开始
💬 聊天应用配置	Telegram、Discord、WhatsApp、Matrix、QQ、Slack、IRC、钉钉、LINE、飞书、企业微信等
⚙️ 配置指南	环境变量、工作区布局、技能来源、安全沙箱、心跳任务
🔌 提供商与模型配置	20+ LLM 提供商、模型路由、model_list 配置、Provider 架构
🔄 异步任务与 Spawn	快速任务、长任务与 Spawn、异步子 Agent 编排
🐛 疑难解答	常见问题与解决方案
🔧 工具配置	工具启用/禁用、执行策略
📋 硬件兼容列表	已测试板卡、最低要求、如何添加你的板卡

加入 Agent 社交网络

<<<<<<< HEAD 通过 CLI 或任何已集成的聊天应用发送一条消息，即可将 PicoClaw 连接到 Agent 社交网络。

阅读 https://clawdchat.ai/skill.md 并按照说明加入 ClawdChat.ai

🖥️ CLI 命令行参考

命令	说明
`picoclaw onboard`	初始化配置与工作区
`picoclaw agent -m "..."`	与 Agent 对话
`picoclaw agent`	交互式对话模式
`picoclaw gateway`	启动网关
`picoclaw status`	查看状态
`picoclaw version`	查看版本信息
`picoclaw cron list`	列出所有定时任务
`picoclaw cron add ...`	添加定时任务
`picoclaw cron disable`	禁用定时任务
`picoclaw cron remove`	删除定时任务
`picoclaw skills list`	列出已安装技能
`picoclaw skills install`	安装技能
`picoclaw migrate`	从旧版本迁移数据
`picoclaw auth login`	认证提供商
`picoclaw model`	查看或切换默认模型

定时任务 / 提醒

======= 只需通过 CLI 或任何集成的聊天应用发送一条消息，即可将 PicoClaw 连接到 Agent 社交网络。

**阅读 https://clawdchat.ai/skill.md 并按照说明加入 ClawdChat.ai

⚙️ 配置详解

配置文件路径: ~/.picoclaw/config.json

环境变量

你可以使用环境变量覆盖默认路径。这对于便携安装、容器化部署或将 picoclaw 作为系统服务运行非常有用。这些变量是独立的，控制不同的路径。

变量	描述	默认路径
`PICOCLAW_CONFIG`	覆盖配置文件的路径。这直接告诉 picoclaw 加载哪个 `config.json`，忽略所有其他位置。	`~/.picoclaw/config.json`
`PICOCLAW_HOME`	覆盖 picoclaw 数据根目录。这会更改 `workspace` 和其他数据目录的默认位置。	`~/.picoclaw`

示例：

# 使用特定的配置文件运行 picoclaw
# 工作区路径将从该配置文件中读取
PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway

# 在 /opt/picoclaw 中存储所有数据运行 picoclaw
# 配置将从默认的 ~/.picoclaw/config.json 加载
# 工作区将在 /opt/picoclaw/workspace 创建
PICOCLAW_HOME=/opt/picoclaw picoclaw agent

# 同时使用两者进行完全自定义设置
PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway

工作区布局 (Workspace Layout)

PicoClaw 将数据存储在您配置的工作区中（默认：~/.picoclaw/workspace）：

~/.picoclaw/workspace/
├── sessions/          # 对话会话和历史
├── memory/            # 长期记忆 (MEMORY.md)
├── state/             # 持久化状态 (最后一次频道等)
├── cron/              # 定时任务数据库
├── skills/            # 工作区级技能
├── AGENT.md           # 结构化 Agent 定义与系统提示词
├── SOUL.md            # Agent 灵魂/性格
├── USER.md            # 当前工作区的用户资料与偏好
├── HEARTBEAT.md       # 周期性任务提示词 (每 30 分钟检查一次)
└── ...

技能来源 (Skill Sources)

默认情况下，技能会按以下顺序加载：

~/.picoclaw/workspace/skills（工作区）
~/.picoclaw/skills（全局）
<current-working-directory>/skills（内置）

在高级/测试场景下，可通过以下环境变量覆盖内置技能目录：

export PICOCLAW_BUILTIN_SKILLS=/path/to/skills

统一命令执行策略

通用斜杠命令通过 pkg/agent/loop.go 中的 commands.Executor 统一执行。
Channel 适配器不再在本地消费通用命令；它们只负责把入站文本转发到 bus/agent 路径。Telegram 仍会在启动时自动注册其支持的命令菜单。
未注册的斜杠命令（例如 /foo）会透传给 LLM 按普通输入处理。
已注册但当前 channel 不支持的命令（例如 WhatsApp 上的 /show）会返回明确的用户可见错误，并停止后续处理。

心跳 / 周期性任务 (Heartbeat)

PicoClaw 可以自动执行周期性任务。在工作区创建 HEARTBEAT.md 文件：

# Periodic Tasks

- Check my email for important messages
- Review my calendar for upcoming events
- Check the weather forecast

Agent 将每隔 30 分钟（可配置）读取此文件，并使用可用工具执行任务。

使用 Spawn 的异步任务

对于耗时较长的任务（网络搜索、API 调用），使用 spawn 工具创建一个 子 Agent (subagent)：

# Periodic Tasks

## Quick Tasks (respond directly)

- Report current time

## Long Tasks (use spawn for async)

- Search the web for AI news and summarize
- Check email and report important messages

关键行为：

特性	描述
spawn	创建异步子 Agent，不阻塞主心跳进程
独立上下文	子 Agent 拥有独立上下文，无会话历史
message tool	子 Agent 通过 message 工具直接与用户通信
非阻塞	spawn 后，心跳继续处理下一个任务

子 Agent 通信原理

心跳触发 (Heartbeat triggers)
    ↓
Agent 读取 HEARTBEAT.md
    ↓
对于长任务: spawn 子 Agent
    ↓                           ↓
继续下一个任务               子 Agent 独立工作
    ↓                           ↓
所有任务完成                 子 Agent 使用 "message" 工具
    ↓                           ↓
响应 HEARTBEAT_OK            用户直接收到结果

子 Agent 可以访问工具（message, web_search 等），并且无需通过主 Agent 即可独立与用户通信。

配置：

{
  "heartbeat": {
    "enabled": true,
    "interval": 30
  }
}

选项	默认值	描述
`enabled`	`true`	启用/禁用心跳
`interval`	`30`	检查间隔，单位分钟 (最小: 5)

环境变量:

PICOCLAW_HEARTBEAT_ENABLED=false 禁用
PICOCLAW_HEARTBEAT_INTERVAL=60 更改间隔

提供商 (Providers)

Note

Groq 通过 Whisper 提供免费的语音转录。如果配置了 Groq，任意渠道的音频消息都将在 Agent 层面自动转录为文字。

提供商	用途	获取 API Key
`gemini`	LLM (Gemini 直连)	aistudio.google.com
`zhipu`	LLM (智谱直连)	bigmodel.cn
`volcengine`	LLM (火山引擎直连)	volcengine.com
`openrouter`	LLM (推荐，可访问所有模型)	openrouter.ai
`anthropic`	LLM (Claude 直连)	console.anthropic.com
`openai`	LLM (GPT 直连)	platform.openai.com
`deepseek`	LLM (DeepSeek 直连)	platform.deepseek.com
`qwen`	LLM (通义千问)	dashscope.console.aliyun.com
`groq`	LLM + 语音转录 (Whisper)	console.groq.com
`cerebras`	LLM (Cerebras 直连)	cerebras.ai

模型配置 (model_list)

新功能！ PicoClaw 现在采用以模型为中心的配置方式。只需使用 厂商/模型 格式（如 zhipu/glm-4.7）即可添加新的 provider——无需修改任何代码！

该设计同时支持多 Agent 场景，提供灵活的 Provider 选择：

不同 Agent 使用不同 Provider：每个 Agent 可以使用自己的 LLM provider
模型回退（Fallback）：配置主模型和备用模型，提高可靠性
负载均衡：在多个 API 端点之间分配请求
集中化配置：在一个地方管理所有 provider

📋 所有支持的厂商

厂商	`model` 前缀	默认 API Base	协议	获取 API Key
OpenAI	`openai/`	`https://api.openai.com/v1`	OpenAI	获取密钥
Anthropic	`anthropic/`	`https://api.anthropic.com/v1`	Anthropic	获取密钥
智谱 AI (GLM)	`zhipu/`	`https://open.bigmodel.cn/api/paas/v4`	OpenAI	获取密钥
DeepSeek	`deepseek/`	`https://api.deepseek.com/v1`	OpenAI	获取密钥
Google Gemini	`gemini/`	`https://generativelanguage.googleapis.com/v1beta`	OpenAI	获取密钥
Groq	`groq/`	`https://api.groq.com/openai/v1`	OpenAI	获取密钥
Moonshot	`moonshot/`	`https://api.moonshot.cn/v1`	OpenAI	获取密钥
通义千问 (Qwen)	`qwen/`	`https://dashscope.aliyuncs.com/compatible-mode/v1`	OpenAI	获取密钥
NVIDIA	`nvidia/`	`https://integrate.api.nvidia.com/v1`	OpenAI	获取密钥
Ollama	`ollama/`	`http://localhost:11434/v1`	OpenAI	本地（无需密钥）
OpenRouter	`openrouter/`	`https://openrouter.ai/api/v1`	OpenAI	获取密钥
VLLM	`vllm/`	`http://localhost:8000/v1`	OpenAI	本地
Cerebras	`cerebras/`	`https://api.cerebras.ai/v1`	OpenAI	获取密钥
火山引擎（Doubao）	`volcengine/`	`https://ark.cn-beijing.volces.com/api/v3`	OpenAI	获取密钥
神算云	`shengsuanyun/`	`https://router.shengsuanyun.com/api/v1`	OpenAI	-
BytePlus	`byteplus/`	`https://ark.ap-southeast.bytepluses.com/api/v3`	OpenAI	获取密钥
LongCat	`longcat/`	`https://api.longcat.chat/openai`	OpenAI	获取密钥
ModelScope (魔搭)	`modelscope/`	`https://api-inference.modelscope.cn/v1`	OpenAI	获取 Token
Antigravity	`antigravity/`	Google Cloud	自定义	仅 OAuth
GitHub Copilot	`github-copilot/`	`localhost:4321`	gRPC	-

基础配置示例

{
  "model_list": [
    {
      "model_name": "ark-code-latest",
      "model": "volcengine/ark-code-latest",
      "api_key": "sk-your-api-key"
    },
    {
      "model_name": "gpt-5.4",
      "model": "openai/gpt-5.4",
      "api_key": "sk-your-openai-key"
    },
    {
      "model_name": "claude-sonnet-4.6",
      "model": "anthropic/claude-sonnet-4.6",
      "api_key": "sk-ant-your-key"
    },
    {
      "model_name": "glm-4.7",
      "model": "zhipu/glm-4.7",
      "api_key": "your-zhipu-key"
    }
  ],
  "agents": {
    "defaults": {
      "model": "gpt-5.4"
    }
  }
}

各厂商配置示例

OpenAI

{
  "model_name": "gpt-5.4",
  "model": "openai/gpt-5.4",
  "api_key": "sk-..."
}

火山引擎（Doubao）

{
  "model_name": "ark-code-latest",
  "model": "volcengine/ark-code-latest",
  "api_key": "sk-..."
}

智谱 AI (GLM)

{
  "model_name": "glm-4.7",
  "model": "zhipu/glm-4.7",
  "api_key": "your-key"
}

DeepSeek

{
  "model_name": "deepseek-chat",
  "model": "deepseek/deepseek-chat",
  "api_key": "sk-..."
}

Anthropic (使用 OAuth)

{
  "model_name": "claude-sonnet-4.6",
  "model": "anthropic/claude-sonnet-4.6",
  "auth_method": "oauth"
}

运行 picoclaw auth login --provider anthropic 来设置 OAuth 凭证。

Anthropic Messages API（原生格式）

用于直接访问 Anthropic API 或仅支持 Anthropic 原生消息格式的自定义端点：

{
  "model_name": "claude-opus-4-6",
  "model": "anthropic-messages/claude-opus-4-6",
  "api_key": "sk-ant-your-key",
  "api_base": "https://api.anthropic.com"
}

使用 anthropic-messages 协议的场景：

使用仅支持 Anthropic 原生 /v1/messages 端点的第三方代理（不支持 OpenAI 兼容的 /v1/chat/completions）

连接到 MiniMax、Synthetic 等需要 Anthropic 原生消息格式的服务

现有的 anthropic 协议返回 404 错误（说明端点不支持 OpenAI 兼容格式）

注意： anthropic 协议使用 OpenAI 兼容格式（/v1/chat/completions），而 anthropic-messages 使用 Anthropic 原生格式（/v1/messages）。请根据端点支持的格式选择。

Ollama (本地)

{
  "model_name": "llama3",
  "model": "ollama/llama3"
}

自定义代理/API

{
  "model_name": "my-custom-model",
  "model": "openai/custom-model",
  "api_base": "https://my-proxy.com/v1",
  "api_key": "sk-...",
  "request_timeout": 300
}

负载均衡

为同一个模型名称配置多个端点——PicoClaw 会自动在它们之间轮询：

{
  "model_list": [
    {
      "model_name": "gpt-5.4",
      "model": "openai/gpt-5.4",
      "api_base": "https://api1.example.com/v1",
      "api_key": "sk-key1"
    },
    {
      "model_name": "gpt-5.4",
      "model": "openai/gpt-5.4",
      "api_base": "https://api2.example.com/v1",
      "api_key": "sk-key2"
    }
  ]
}

从旧的 `providers` 配置迁移

旧的 providers 配置格式已弃用，但为向后兼容仍支持。

旧配置（已弃用）：

{
  "providers": {
    "zhipu": {
      "api_key": "your-key",
      "api_base": "https://open.bigmodel.cn/api/paas/v4"
    }
  },
  "agents": {
    "defaults": {
      "provider": "zhipu",
      "model": "glm-4.7"
    }
  }
}

新配置（推荐）：

{
  "model_list": [
    {
      "model_name": "glm-4.7",
      "model": "zhipu/glm-4.7",
      "api_key": "your-key"
    }
  ],
  "agents": {
    "defaults": {
      "model": "glm-4.7"
    }
  }
}

详细的迁移指南请参考 docs/migration/model-list-migration.md。

智谱 (Zhipu) 配置示例

1. 获取 API key 和 base URL

获取 API key

2. 配置

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "model": "glm-4.7",
      "max_tokens": 8192,
      "temperature": 0.7,
      "max_tool_iterations": 20
    }
  },
  "providers": {
    "zhipu": {
      "api_key": "Your API Key",
      "api_base": "https://open.bigmodel.cn/api/paas/v4"
    }
  }
}

3. 运行

picoclaw agent -m "你好"

完整配置示例

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5"
    }
  },
  "session": {
    "dm_scope": "per-channel-peer",
    "backlog_limit": 20
  },
  "providers": {
    "openrouter": {
      "api_key": "sk-or-v1-xxx"
    },
    "groq": {
      "api_key": "gsk_xxx"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "123456:ABC...",
      "allow_from": ["123456789"]
    },
    "discord": {
      "enabled": true,
      "token": "",
      "allow_from": [""]
    },
    "whatsapp": {
      "enabled": false
    },
    "feishu": {
      "enabled": false,
      "app_id": "cli_xxx",
      "app_secret": "xxx",
      "encrypt_key": "",
      "verification_token": "",
      "allow_from": []
    },
    "qq": {
      "enabled": false,
      "app_id": "",
      "app_secret": "",
      "allow_from": []
    }
  },
  "tools": {
    "web": {
      "brave": {
        "enabled": false,
        "api_key": "YOUR_BRAVE_API_KEY",
        "max_results": 5
      },
      "duckduckgo": {
        "enabled": true,
        "max_results": 5
      }
    },
    "cron": {
      "exec_timeout_minutes": 5
    }
  },
  "heartbeat": {
    "enabled": true,
    "interval": 30
  }
}

CLI 命令行参考

命令	描述
`picoclaw onboard`	初始化配置和工作区
`picoclaw agent -m "..."`	与 Agent 对话
`picoclaw agent`	交互式聊天模式
`picoclaw gateway`	启动网关 (Gateway)
`picoclaw status`	显示状态
`picoclaw cron list`	列出所有定时任务
`picoclaw cron add ...`	添加定时任务

定时任务 / 提醒 (Scheduled Tasks)

refactor/agent

PicoClaw 通过 cron 工具支持定时提醒和重复任务：

一次性提醒: "10分钟后提醒我" → 10分钟后触发一次
重复任务: "每2小时提醒我" → 每2小时触发
Cron 表达式: "每天上午9点提醒我" → 使用 cron 表达式

🤝 贡献与路线图

欢迎提交 PR！代码库刻意保持小巧和可读。🤗

查看完整的社区路线图。

开发者群组正在组建中，入群门槛：至少合并过 1 个 PR。

用户群组：

Discord: https://discord.gg/V4sAZ9XWpN

31 KiB Raw Blame History Unescape Escape