PicoClaw 入门：打造轻量级个人 AI 助手

本文为中文整理与评述，基于 Vignaraj Ravi 发布在 Medium 的文章 PicoClaw — Building Your Own Lightweight AI Assistant。本文保留原文的主要安装与配置路径，并结合中文读者的本地 AI、边缘设备和个人自动化场景做了重新组织。

现在很多 AI assistant 看起来都越来越“重”：要登录云端控制台，要运行庞大的 runtime，要配置复杂的编排框架，还经常默认你有一台资源充足的服务器。但 PicoClaw 走的是相反方向。它是一个用 Go 写成的轻量级个人 AI 助手，目标是用单个二进制文件运行，从 MacBook 到 Raspberry Pi 都可以承担。

原文最有价值的地方，不在于把 PicoClaw 描述成又一个万能 agent，而是给出了一条比较接近生产环境的配置路径：安装、初始化 workspace、接入模型、多 agent、技能、工具脚本、Telegram、cron 自动化，以及 24/7 常驻运行。对于想把 AI 助手放到本地机器、便宜 VPS 或边缘设备上的人，这篇指南很值得看。

为什么 PicoClaw 有意思

多数 AI agent 框架强调“规模”：更多插件、更多服务、更多可视化面板。PicoClaw 强调的是“控制”：低资源占用、快速启动、单文件部署、本地优先、可脚本化和可长期运行。

你可以把它理解为一个轻量级个人 AI operating system。它不一定替代大而全的 OpenClaw 或其他复杂 agent 平台，但很适合那些希望把 AI 助手塞进小机器、低成本硬件或私有工作流的人。

一句话理解：PicoClaw 不是把你的电脑变成一个巨大 agent 平台，而是把一个可控、可配置、可常驻的小型 AI 助手放进你的环境里。

第一步：安装 PicoClaw

原文以 macOS Apple Silicon 为例，直接下载 release binary，并放到本地可执行路径：

curl -L https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_darwin_arm64 \
  -o /usr/local/bin/picoclaw
chmod +x /usr/local/bin/picoclaw

安装后可以先确认版本：

picoclaw version

这个安装方式也解释了 PicoClaw 的设计取向：它不是先要求你搭一堆服务，而是先给你一个可以运行的二进制。对个人使用者来说，这能显著降低第一步的心理负担。

第二步：初始化 workspace

安装完成后，运行 onboarding：

picoclaw onboard

它会创建主要配置和工作区，例如：

• ~/.picoclaw/config.json：主配置文件。
• ~/.picoclaw/workspace/：agent 工作区和记忆目录。

之后可以随时查看状态：

picoclaw status

这个目录结构很关键。PicoClaw 不是把所有状态都藏在黑盒里，而是把配置、workspace、工具和 memory 放在你能看到、能备份、能修改的位置。对于本地优先的 AI assistant，这一点比花哨界面更重要。

第三步：理解配置文件

PicoClaw 的核心配置集中在：

~/.picoclaw/config.json

原文把主要 section 分成几类：

如果你用过其他 agent 框架，会发现这个结构很熟悉：模型、agent、工具、通道、记忆、gateway。PicoClaw 的重点是把这些东西压缩到一个较小的 runtime 里。

第四步：接入 AI 模型

PicoClaw 支持多个模型提供方，包括 OpenAI、DeepSeek、Anthropic、Gemini、Groq 和 Ollama。本地模型可以通过 Ollama 接入，云端模型则通过对应 provider 和 API key 接入。

一个简化示例类似这样：

{
  "model_list": [
    {
      "model_name": "gpt-4o",
      "model": "openai/gpt-4o",
      "api_key": "YOUR_KEY"
    }
  ]
}

原文特别提醒：在 v0.1.2 中，model_list 和 providers 两部分都需要配置。否则模型可能不是明确报错，而是“安静地失败”。这类问题在 agent runtime 里非常常见，因为上层看起来只是 assistant 没回应，但真正原因可能是 provider 配置不完整。

第五步：创建多个 agent

PicoClaw 不只支持一个 assistant。你可以把它配置成一组 agent，各自负责不同任务：

• 个人助理：处理日常对话、提醒和信息整理。
• 编程 agent：处理代码、脚本和开发任务。
• 文件搜索 agent：负责 workspace 索引和资料查找。

每个 agent 可以拥有自己的 workspace、memory、identity 和模型配置。这个设计非常适合把“一个万能助手”拆成几个更稳定的角色。相比让一个 agent 什么都做，多角色配置通常更容易控制行为边界。

第六步：用 Markdown 教 agent 性格

PicoClaw 会从 Markdown 文件构建 system prompt。你可以在 workspace 里创建类似这样的文件：

• SOUL.md：性格、行为规则、价值观。
• IDENTITY.md：角色描述、专业能力、工作范围。
• USER.md：用户偏好、时区、工作方式。

例如，你可以写入这样的行为规则：

I am concise and proactive.
Verify facts before answering.
End responses with action items.

这件事看似简单，其实很重要。很多 agent 产品把 prompt 隐藏在产品内部，而 PicoClaw 把行为配置变成用户可维护的文档。对个人 assistant 来说，这比一次性调 prompt 更接近长期使用。

第七步：打开网络搜索能力

如果希望 assistant 能查网页，可以启用 web tools：

{
  "tools": {
    "web": {
      "duckduckgo": { "enabled": true },
      "tavily": { "enabled": true }
    }
  }
}

原文列出几种可用搜索 provider：DuckDuckGo 免费、无需注册，适合作为 fallback；Tavily 更偏 AI 搜索和研究任务；Brave Search 则更重视隐私，但通常需要额外 API key。

第八步：用 skills 扩展能力

PicoClaw 的 skills 是可复用的 instruction pack。安装示例：

picoclaw skills install weather

一个 skill 通常放在 skills/skill-name/ 目录下，核心文件是 SKILL.md，其中包含 YAML front matter、name、description 和具体 instructions。

这类设计的好处是：你不一定要写完整插件，先用结构化说明书定义能力即可。对于个人自动化来说，很多能力其实不是复杂代码，而是稳定流程、边界和调用说明。

第九步：添加自定义工具脚本

每个 PicoClaw agent 都可以拥有 exec tool，运行你提供的脚本。脚本通常放在：

~/.picoclaw/workspace/tools/

适合放进去的工具包括：

• 本地文件搜索。
• 数据库查询。
• Supabase REST 调用。
• 自动化工作流。
• 开发者常用脚本。

这是 PicoClaw 从“聊天机器人”变成“本地助手”的关键一步。只有当 agent 能调用你环境里的工具，它才开始接近真实工作流。

第十步：接入 Telegram

原文用 Telegram 作为消息入口。先通过 @BotFather 创建 bot，然后在配置中加入 token：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_TOKEN"
    }
  }
}

启动 gateway：

picoclaw gateway

这样你的 PicoClaw assistant 就可以住进 Telegram。这个场景很实用：你不需要一直打开终端，也不需要专门打开一个 Web UI，只要在手机上发消息，就能触发 agent 工作。

第十一步：用 cron 做自动化

PicoClaw 支持 cron 风格的定时任务。比如每天早上做 AI 新闻摘要：

picoclaw cron add \
  --name "morning-briefing" \
  --message "Summarize today's AI news" \
  --cron "0 9 * * *"

适合做的自动化包括：

• 每日新闻简报。
• 服务器健康检查。
• 价格监控。
• 研究更新。
• 提醒和待办。

如果一个 assistant 只能被动回答问题，它的价值有限。一旦它能按时间主动运行任务，它就开始像一个个人运营系统。

第十二步：让 PicoClaw 24/7 运行

最简单的后台运行方式：

nohup picoclaw gateway &

或者用 tmux：

tmux new-session -d -s picoclaw 'picoclaw gateway'

如果走生产化，可以用 systemd service 做自动重启和持久运行。对 home lab、VPS 或边缘设备来说，这是从“实验项目”走向“长期基础设施”的分界线。

记忆与持久化

PicoClaw 的持久记忆放在 workspace 中，例如：

workspace/memory/MEMORY.md

你可以让它记住项目偏好、端口、技术栈、工作方式等信息。例如：

• “记住这个项目使用 3001 端口。”
• “保存一条偏好：优先使用 TypeScript。”

这类记忆文件不一定复杂，但它能让 assistant 跨会话积累上下文。对个人 AI 来说，长期记忆往往比单次回答更重要。

常见问题

PicoClaw 真正适合什么

配置完成后，PicoClaw 不再只是一个 chatbot。它更像是一个轻量级自托管 agent runtime，可以承担个人 DevOps 助手、编程协作、研究自动化、Telegram AI companion 和本地任务编排等角色。

当然，它并不是所有人的最佳选择。如果你需要庞大的插件生态、成熟 UI、多平台深度集成，OpenClaw 或其他大型框架可能更合适。但如果你在意低资源占用、可控性、单二进制部署、本地文件和边缘设备，PicoClaw 的方向就很有吸引力。

AI assistant 不一定只能住在云端。PicoClaw 代表的路线，是把智能拉近到开发者自己的机器、脚本、消息通道和自动化系统里。当一个 assistant 能运行工具、记住上下文、按时执行任务，并主动通过消息应用联系你时，它就不再只是软件，而开始变成个人基础设施的一部分。

参考链接：Medium 原文。