PiClaw
把 Pi Coding Agent 封装为可自托管的持久化开发工作区。
这个 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 有哪些优点和局限？
- 把 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？
创建持久化目录后运行：
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
也可实验性地执行 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 与同类方案有什么区别？
PiClaw 是基于 Pi Coding Agent 核心的衍生作品，增加了自己的运行时、工具和 Web UI；仓库明确说明其并不直接隶属于 pi.dev。