PiClaw
把 Pi Coding Agent 封装为可自托管的持久化开发工作区。
- Star 数
- ★ 886
- 最近更新
- 今天
- License
- MIT
- 主语言
- TypeScript
- FA 评分
- 48/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台OpenAI API
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 中 · 需要几步配置
- 开始前需要
- 典型场景
- 需要在自有机器或服务器上，把编码助手、编辑器和终端集中在一个浏览器工作区的个人开发者。
- 不适合
- 需要稳定 Windows 支持的团队，Windows 支持仍属实验性
- 希望开箱即用、无需配置 LLM 提供商的用户
- 需要多用户或团队协作的场景，PiClaw 为单用户设计
这个 Agent 能做什么，适合哪些场景？
PiClaw 是围绕 Pi Coding Agent 构建的单用户、自托管 AI 工作区，提供流式 Web UI。它将聊天、代码编辑器、终端、文件浏览、上传和多种查看器放在同一界面中，并以 SSE 推送更新。运行状态保存在 SQLite 中，覆盖消息、媒体、任务、运行日志、令牌用量、加密密钥链和会话相关 SSH 配置。它可在 Docker 容器中运行，也提供基于 Bun 的全局安装方式；另有实验性的 Electrobun 桌面壳。其边界是本地或容器化工作区中的 Pi 运行时与内置工具，扩展功能可通过可选 add-on 加入。
用户在 Web UI 中通过聊天驱动 Pi Coding Agent，并可在同一工作区编辑代码、使用嵌入式 xterm.js 终端、上传和浏览文件。内置查看器可打开 CSV/TSV、PDF、图片、视频、代码预览和 VNC 窗格；自动化功能包括 image_process、cdp_browser 和 mcp。系统把消息、媒体、任务、令牌用量及运行记录写入 /workspace/.piclaw/store/messages.db，并把 Pi 状态持久化到 /config/.pi。工具采用分阶段加载：常驻小型工具集，其余能力通过 list_tools 和 list_scripts 发现；聊天还支持 steering、queued follow-ups、side prompts 与 scheduled tasks。
- 需要在自有机器或服务器上，把编码助手、编辑器和终端集中在一个浏览器工作区的个人开发者。
- 希望用 Docker 持久保存 Pi 登录状态、模型元数据与项目文件的开发者。
- 需要让编码会话直接查看 CSV、PDF、图片、视频或 VNC 远程桌面的运维和开发人员。
- 希望在同一界面中安排任务、发送后续指令，并保留聊天分支和运行日志的单用户工作流。
- 需要配置自定义 OpenAI 兼容端点或本地 llama.cpp router preset 的自托管用户。
如何安装或部署这个 Agent？
创建持久化目录后运行：
mkdir -p ./home ./workspacedocker 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也可实验性地执行 bun add -g github:rcarmo/piclaw。Docker 方式需要 Docker；全局安装方式需要 Bun。
如何使用这个 Agent？
打开 http://localhost:8080，在聊天中输入 /login，并在 Pi Agent 设置中配置 LLM 提供商凭据；无需把提供商 API 密钥设为 PiClaw 环境变量。随后可在聊天中发起编码任务，使用 Workspace 浏览项目与上传文件，或打开 Terminal、CSV/TSV、PDF、图片、视频和 VNC 窗格。需要调整运行方式时，可设置 PICLAW_WEB_PORT、PICLAW_WEB_TERMINAL_ENABLED、PICLAW_WEB_TOTP_SECRET、PICLAW_WEB_PASSKEY_MODE、PICLAW_KEYCHAIN_KEY 或 PICLAW_TRUST_PROXY 等环境变量。
这个 Agent 有哪些优点和局限？
- 把 Pi Coding Agent、聊天、CodeMirror 6 编辑器、xterm.js 终端与文件查看器整合进同一个自托管界面。
- SQLite 持久化覆盖聊天、任务、媒体、令牌用量、运行日志、加密密钥链和会话相关 SSH 配置。
- 内置 image_process、cdp_browser、mcp、VNC 以及 CSV/TSV、PDF、图片和视频查看能力。
- 支持自定义 OpenAI 兼容端点和本地 llama.cpp router preset，并可用 add-on 扩展运行时和 Web UI。
- 核心使用依赖 Pi Agent 的提供商登录与模型配置；仓库未说明任何内置模型或免费推理服务。
- Windows 支持被标为实验性，且该平台默认关闭 PICLAW_WEB_TERMINAL_ENABLED。
- messages.db 是聊天、任务、令牌记录、密钥链和会话的唯一事实来源，删除会丢失这些持久数据。
- 部分能力依赖可选 add-on，例如 Ghostty 终端、Draw.io、Office 渲染、Windows 桌面自动化、Proxmox 和 Portainer。
这个 Agent 与同类方案有什么区别？
PiClaw 是基于 Pi Coding Agent 核心的衍生作品，增加了自己的运行时、工具和 Web UI；仓库明确说明其并不直接隶属于 pi.dev。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| PiClaw 当前 | 48 · 缺口较多 | 自托管服务免费 + 模型费 | ★ 886 | 今天 | TypeScript | OpenAI API |
| 智坤代码 (ZhikunCode) | 56 · 缺口较多 | 自托管服务免费 + 模型费 | ★ 540 | 3 天前 | Java | OpenAI API · Claude API |
| OtoDock | 77 · 表现良好 | 自托管服务免费版 + 付费版 | ★ 197 | 1 天前 | Python | Codex · Claude Code |
| CamoFox Browser Server | 72 · 存在缺口 | 自托管服务免费 | ★ 436 | 12 天前 | JavaScript | Claude Code |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示有权限控制（如外部路由注册限制、数据目录逃逸检查）和用户确认机制（如m365扩展的dry-run/confirm参数），但未全面覆盖所有工具。数据流透明度部分：有文档说明存储和密钥管理，但未详细说明所有数据流。敏感数据处理：有密钥管理和RAM-only缓存，但未全面评估。依赖安全：使用精确版本和overrides，但未提供漏洞扫描证据。外部影响：有外部路由和浏览器自动化，但未明确限制。回滚：未提及。来源归属：有版权和许可证，但未验证发布者。
自一致性：代码和测试显示一致的架构和命名。依赖可用性：依赖项固定版本，但未验证所有依赖的可用性。失败消息：测试显示有错误处理，但未全面评估。
受众和场景：README明确目标用户和使用场景。能力边界：有工具和扩展的文档，但未明确所有边界。触发精度：有命令和工具定义，但未详细说明触发条件。环境适配：支持多种安装方式和平台，但Windows支持有限。
信息架构：文档结构清晰，有多个文档。安装说明：提供Docker和源码安装指南。命名稳定性：版本号明确，但未提供变更日志。示例和FAQ：有示例但无FAQ。已知限制：部分提及（如Windows支持有限）。许可证：MIT。版本和变更日志：有版本号但无详细变更日志。维护责任：有GitHub Issues，但未明确维护者。
输出可用性：Web UI功能丰富，输出格式多样。边际价值：提供集成工作区，有独特功能。成本效益：需要自托管，但未提供性能或资源消耗数据。
声明可追溯性：README中的功能有文档支持，但未提供测试结果。跨来源佐证：有多个文档和测试，但未独立验证。事实与推断分离：文档区分了实验性和稳定功能，但未明确标注所有推断。
- 源码中未见：回滚或恢复路径运行前先备份，或在 git 分支、快照上操作，确保改动可以撤销。
- 发布者身份未验证，需谨慎评估供应链风险。
- 依赖项虽固定版本，但未提供漏洞扫描证据，建议运行安全审计。
- 部分工具（如浏览器自动化、外部路由）可能带来安全风险，需确保配置最小权限。
- Windows支持有限，可能影响跨平台部署。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
v3.3.4 PiClaw v3.3.4 — “Galaxy Quest”
发布说明摘录
PiClaw v3.3.4 — “Galaxy Quest” The ship’s computer has received several clarifications. A status report must describe the turn currently on the bridge, a message must reach the conversation that actually exists, and an instruction to finish without tools must not include directions to the armoury. The crew may still improvise; the routing system should not. Credential handling receives similar attention. A locked storage compartment is distinguishable from an invalid access code, reducing the occasions on which the captain is invited to log in again because someone misplaced the cupboard. …在 GitHub 查看 ↗ -
v3.3.3 PiClaw v3.3.3 — “Batteries Not Included”
发布说明摘录
PiClaw v3.3.3 — “Batteries Not Included” The maintenance department has repaired the phone’s Delete button, fitted the GPU gauges with better instruments, and clarified which doors an add-on may use. The desktop application has meanwhile left the building. Its historical releases remain available, but new releases will concentrate on the web interface, server, containers and portable command-line packages. …在 GitHub 查看 ↗ -
v3.3.2 PiClaw v3.3.2 — “Apollo 13”
发布说明摘录
> Locally tested hotfix. Local qualification for #1619 passed before merging. The artifact-only release workflow skipped repeat test suites, UX, integration and image smoke checks. Source: c4c7f699aa8fa5afc7d10cd416609cb2cd10149b. Actor: piclaw-bot. [Artifact run](https://github.com/rcarmo/piclaw/actions/runs/38050535667). PiClaw v3.3.2 — “Apollo 13” …在 GitHub 查看 ↗