piclaw
rcarmo/piclaw加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
你有没有过这样的经历：写代码写到一半，脑子里冒出一个精妙的解决方案，却苦于找不到合适的工具来验证、执行和管理那些碎片化的想法？或者，你尝试过各种 AI 编程助手，但每次对话结束后，所有的上下文和中间结果都烟消云散，下次打开又是白纸一张？PiClaw 正是为解决这些痛点而生的——它将一个功能完备的 AI 编程代理，包装成了一个可以私有部署、状态持久化、功能高度集成的 Web 工作空间。
图1：PiClaw 项目图标
PiClaw 的作者是长期活跃在 GitHub 上的高产开发者 rcarmo（Susana Lopes）。在漫长的编程生涯中，他一直在寻找一个真正能承载"状态"的 AI 助手——不是每次都要重新设定上下文的问答机器，而是一个能记住你项目结构、记得你上次的调试路径、了解你编码偏好的长期搭档。
这一需求在他接触了 pi-mono（由 Mario Zechner 开发的开源 AI 编程代理引擎）后找到了答案。pi-mono 本身是一个高度可扩展的代理框架，提供了丰富的基础工具集和会话管理能力。但 rcarmo 觉得，它缺少一个适合日常使用的"外壳"——一个能把所有功能聚合在一起、随时可用的完整工作环境。于是，PiClaw 诞生了。
值得注意的是，PiClaw 并非简单 fork 了 pi-mono，而是在其基础上构建了一个完整的运行时外壳（Runtime Shell），包括 Web UI、持久化存储、多渠道接入（Web + 可选 WhatsApp）、自动化脚本等一整套基础设施。这种"核心引擎 + 工作空间外壳"的架构，让它既能享受上游的持续更新，又能独立演进自己的生态系统。
PiClaw 的野心很大——它不只是一个聊天界面，而是一个一站式 AI 编程工作站。以下是它最核心的几个能力模块：
PiClaw 提供了一个基于 Preact + TypeScript 构建的现代化 Web 前端，所有交互通过 SSE（Server-Sent Events） 流式推送，响应速度和本地桌面应用无异。界面布局包含多个功能面板：
PiClaw 的一个核心设计哲学是不丢失任何上下文。它使用 SQLite 数据库持久化所有消息、媒体文件、任务状态和 token 使用记录。容器重启后，聊天历史、文件引用和会话状态完全恢复。这意味着你可以把 PiClaw 当作一个长期运行的个人 AI 助手，而不用担心每次重启后"失忆"。
PiClaw 并不绑定某个特定的大语言模型。通过 /login 命令配置 LLM 提供商，支持 OpenAI、Anthropic、兼容 OpenAI API 的自定义端点等。这种灵活性让用户可以根据自己的预算和隐私需求选择最合适的模型。
安全性方面，PiClaw 实现了 AES-256-GCM 加密的密钥链，用于安全存储 API 密钥等敏感信息。Web UI 支持 TOTP 动态口令和 Passkeys（WebAuthn） 双重认证，用户可以选择三种模式：totp-fallback（TOTP 备援 Passkey）、passkey-only 或 totp-only。
除了 Web UI，PiClaw 还支持通过 WhatsApp（基于 Baileys 库）与 AI 助手交互。需要在环境变量中设置 PICLAW_ENABLE_WHATSAPP=1 开启，提供了极大的使用灵活性。
PiClaw 内置了对 MCP 的支持，可以通过 pi-mcp-adapter 扩展连接外部工具和服务。此外还有可选的实验性 Microsoft 365 扩展包，支持更广泛的办公自动化场景。
内置自动化能力包括：图片生成（/image）、Flux 图像处理（/flux）、CDP 浏览器自动化、脚本调度（基于 cron/interval 任务调度器）、自动研究循环（autoresearch）和跨实例 IPC 通信。rcarmo 还维护了一个独立的 piclaw-addons 生态，将可选功能模块化发布。
PiClaw 的架构文档（docs/architecture.md）长达近 30,000 字，详细描述了其内部构造。从顶层俯瞰，系统分为以下几层：
客户端层：浏览器 Web UI 和可选的 WhatsApp（Baileys）。两者通过不同的 Channel 适配器接入核心运行时。
通道层（Channels）：WebChannel 处理 HTTP + SSE + WebSocket 路由，WhatsAppChannel 处理 Baileys 消息路由，两者统一汇入核心路由器。
核心运行时（Core Runtime）：
chat:{jid} 和 dream:{jid} 分组的并发队列（jid = Jabber ID，即会话唯一标识），带重试策略AgentSession后台工作器：IPC 文件监视器（跨实例通信）、任务调度器（cron/interval）、Dream/AutoDream（临时的 out-of-band 推理会话，用于在不打断主对话流的情况下执行复杂推理）。
数据层：SQLite（消息、聊天、任务、配置、token 用量）、Session 树（会话元数据）、Workspace（笔记、技能、文件）。
这种架构设计让每个组件职责单一、接口清晰。Router 不关心消息来自 Web 还是 WhatsApp，Queue 不关心任务来自用户还是自动化脚本——这种解耦为未来的扩展（比如新增一个 Telegram Channel）提供了极大便利。
PiClaw 在代码质量上展现了相当高的工程水准：
runtime/extensions/ 和 runtime/skills/ 实现能力扩展，支持文件系统驱动的技能加载supervisord 作为 PID 1，统一管理 Bun 运行时和其他服务进程PiClaw 提供了极其顺畅的容器化部署体验。官方维护的 Docker 镜像托管于 GHCR（GitHub Container Registry），默认配置下只需要几行命令就能启动完整服务：
mkdir -p ./home ./workspace
docker run -d \\
--init \\
--name piclaw \\
--restart unless-stopped \\
-p 8080:8080 \\
-e PICLAW_WEB_PORT=8080 \\
-v "$(pwd)/home:/config" \\
-v "$(pwd)/workspace:/workspace" \\
ghcr.io/rcarmo/piclaw:latest
启动后访问 http://localhost:8080，输入 /login 配置 LLM 提供商即可使用。docker-compose.yml 还支持通过环境变量配置 CPU/内存限制、Web 端口、用户权限映射等。
没有 GPU 需求，不需要 CUDA，不需要特殊驱动，普通 Linux 服务器或桌面 Docker 环境即可运行。硬件门槛相当亲民。
PiClaw 并非没有局限性。首先，它需要自备 LLM API Key——PiClaw 本身只是一个"壳"，不包含任何模型能力。用户必须自己搞定 API 凭证，这在保护隐私的同时也增加了初始配置成本。其次，WhatsApp 集成目前标记为可选（opt-in），配置相对复杂，对普通用户来说有一定的技术门槛。
在架构层面，PiClaw 的所有状态目前集中在单一 SQLite 数据库中，在极高并发场景下可能存在写入瓶颈——虽然对于单人使用的个人助手场景，这个担忧并不实际。
此外，Electrobun 桌面外壳虽然提供了本地窗口化的可能，但目前标记为"实验性"，Electron/Tauri 桌面化的完整体验还需要等待社区成熟。
PiClaw 代表的趋势是AI 工具从"在线服务"向"本地工作站"的迁移。随着开源大模型能力不断提升，越来越多的开发者希望拥有完全属于自己的 AI 工作环境——数据不出本机，可定制程度高，不依赖第三方服务稳定性。PiClaw 正好填补了这一空白：它不只是一个编程代理，更是一套将 AI 能力深度融入个人工作流的基础设施。
从生态角度看，rcarmo 同时维护了核心项目、插件生态（piclaw-addons）和独立的自动化脚本库（pi-autoresearch），形成了围绕 PiClaw 的开发者社区雏形。这种"核心开源 + 生态扩展"的模式，和 VSCode 的插件生态有异曲同工之妙。
一句话总结：PiClaw 是一个基于 Docker 的自托管 AI 编程工作站，将 AI 代理的流式对话、代码编辑、终端集成、文件管理和自动化能力聚合在一个持久化的 Web UI 中，适合追求隐私可控、高度可定制 AI 工作流的开发者。