本文基于大佬（@agegr）开源的 Pi Web ，带你快速上手最近超火的 Pi Agent。
系列规划：
1️⃣ 了解 Pi Agent，搭配 Pi Web 快速安装搭建、使用（本文，含 Windows / Linux 部署、局域网访问与安全配置）
2️⃣ 基于 Pi Agent 实现自有智能体（todo）

一、引言

最近一段时间，一个开源的 AI Agent 在 GitHub 上爆火：Pi（badlogic/pi-mono），作者是 Mario Zechner（libGDX 之父）。值得一提的是 OpenClaw 也就是我们常说的「小龙虾」，就是基于 Pi 实现的。

从功能和展现的角度来看，Pi 是一个运行在终端里的 通用 Agent，类似于 Claude Code、Codex CLI 这类工具：你给 Pi 一句话，它就能在你的项目目录里读文件、写文件、跑命令，循环调用大模型直到完成任务。

但 Claude Code \ Codex 这类工具，都希望能将更多、更强大的功能内置进来，而 Pi 的官方理念是反过来的——用最小的内核加极强的可扩展性，让你把工具改造成适合自己的样子，而不是反过来去适应工具。你需要什么，就去装 Skill、写 Extension，或者让 Pi 自己给自己造一个，最终打造出一个专属于你、最顺手的 Agent。

就像官网首页上写的：“There are many agent harnesses but this one is yours”（Agent 工具很多，但这个是你自己的）。

Pi 的内核到底有多小？

很多人对「最小内核」没有概念，这里简单展开一下。Pi 本体内置的工具基本只有这几样：

• read：读文件（文本和图片）
• write / edit：写文件、精确编辑
• bash：执行命令

就这些。没有内置的联网搜索、没有内置的 PDF 解析、没有内置的待办清单、子代理编排……所有「能力」都来自 Skill 和 Extension。这带来三个直接好处：

1. 快：系统提示词短，启动快，首 token 也快；
2. 省 token：不会把一堆你用不到的工具定义塞进每一次请求；
3. 可控：你的 Agent 会什么、不会什么，完全由你决定，行为更可预测。

Pi 适合谁？

• 了解（或者想了解）Skill 的人
• 需要同时接入多家大模型（Anthropic、OpenAI、Google 等）的人
• 想基于一个干净的底座做 Agent 二次开发 的开发者

⚠️ 注意两点：

1. Pi 默认以你的用户权限运行，没有内置沙箱，它能做的事就是你能在终端做的事，请谨慎对待来路不明的 Skill；
2. Pi 的会话数据全部在本地。每次对话的完整记录追加写到 ~/.pi/agent/sessions/<目录编码>/<时间戳>_<uuid>.jsonl，纯文本，没有云端、没有数据库。隐私友好，但也意味着翻历史不太方便——这正是下文 Pi Web 要解决的问题。

---

不过用过这类 Agent 的小伙伴都知道，CLI 终端对工程师没问题，但现实团队里不是所有人都习惯命令行，产品、测试、新人都想要个能点鼠标的地方，很多人也不想太深入了解命令，去做一些比如 Fork 之类的操作。

因此本文并不会细讲 Pi 的原理，也不会让你直接去装命令行的 Pi，而是基于大佬（@agegr）开源的 Pi Web 来讲——它的核心卖点，几乎都是冲着 Pi 的这些短板来的：

Pi（终端）	Pi Web（浏览器）
翻历史会话要翻文件系统	按项目分组列出所有历史对话，点开即看
没法从中间岔开	从任意一条历史消息 fork 出新路线
配置要编辑 json 文件	模型、API key、技能开关全在面板里点
看代码要另开编辑器	左侧文件树、右侧预览，Agent 改完自动刷新
绑死在终端窗口里	浏览器打开即用，天然支持多设备访问

一句话：Pi Web 给 Pi 套了一个网页界面——在浏览器里管理会话、对话、配模型、装技能、看文件，不用再抱着终端。

看完本文，你将能学会：

• 如何在 Windows / Linux（服务器）上安装、启动 Pi Agent（通过 Pi Web）
• 如何让局域网设备（手机/平板）访问，并配置密码保护
• 如何配置模型
• 如何安装 Skill、如何使用 Skill

---

二、安装 Pi Web

2.1 Node 环境安装

Pi Web 要求 Node ≥ 22.19.0，Node 的安装我就不详细讲了。

Windows 直接去官网下载 LTS 版本的 .msi 安装包，一路下一步即可，安装包会自动配置好 node 和 npm 的环境变量：

Node.js — 下载 Node.js®

Linux / macOS 推荐用 nvm 管理：

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc

# 安装并使用 Node 22 LTS
nvm install 22

也可以用系统包管理器或 NodeSource 源，只要版本达标即可。最后执行 node -v 验证，大于22.19就行。

---

2.2 启动 Pi Web

启动命令非常简单，就一行：

npx @agegr/pi-web@latest

首次执行会下载依赖（看到 Ok to proceed? (y) 输入 y 回车），然后自动启动一个本地服务。启动成功的标志是终端里出现类似输出：

▲ Next.js 16.x.x
- Local:   http://127.0.0.1:30141
✓ Ready in x.x s

并且浏览器会自动弹出 Pi Web 的界面：

几个补充说明：

• Pi Web 有几个关键命令行参数： -p -H --no-open ；环境变量：密码 PI_WEB_PASSWORD 。
• -p 用来改访问端口，比如 npx @agegr/pi-web@latest -p 8080；默认端口是 30141。
• -H 用来限制访问地址，想让局域网内其他设备（比如手机）访问，加 -H 0.0.0.0 参数即可；默认只监听 127.0.0.1（仅本机可访问）。
• 不想自动打开浏览器，加 --no-open；
• 环境变量 PI_WEB_PASSWORD 用来设置访问 Pi Web 时的密码。不设置时为免密访问。
• 更新到最新版同样是这条命令，npx xxx@latest 每次都会拉最新包。

上面这些参数可以组合使用，一个完整的例子——指定 8080 端口、允许局域网访问、不自动打开浏览器：

npx @agegr/pi-web@latest -p 8080 -H 0.0.0.0 --no-open

想设置密码的话：

Linux / macOS：

PI_WEB_PASSWORD=你的强密码 npx @agegr/pi-web@latest -p 8080 -H 0.0.0.0 --no-open

Windows (cmd)：

set PI_WEB_PASSWORD=你的强密码 && npx @agegr/pi-web@latest -p 8080 -H 0.0.0.0 --no-open

Windows (PowerShell)：

$env:PI_WEB_PASSWORD="你的强密码"; npx @agegr/pi-web@latest -p 8080 -H 0.0.0.0 --no-open

小区别：Linux 的前缀写法只对这一条命令生效，关了就没了；Windows 的 set 会在这个终端窗口里一直生效，之后直接 npx @agegr/pi-web@latest 也带密码。

---

可选1：全局安装（长期使用推荐）

npx 的方式每次启动都要检查/下载包，如果你打算长期使用，可以全局安装一次：

npm install -g @agegr/pi-web

装完后会注册一个 pi-web 命令，以后启动就不用 npx 了，参数完全一样：

pi-web -p 8080 -H 0.0.0.0 --no-open

几个相关的常用操作：

# 升级到最新版
npm update -g @agegr/pi-web

# 安装指定版本（比如指定安装 0.8.9）
npm install -g @agegr/pi-web@0.8.9

# 查看发布过哪些版本
npm view @agegr/pi-web versions

同理，npx 也能指定版本临时运行：npx @agegr/pi-web@0.8.9，适合用习惯了某个版本的场景。

---

可选2：Linux 上注册为系统服务

新建一个 systemd 服务，步骤如下：

1. 编辑服务文件

nano /etc/systemd/system/pi-web.service
# 或者用 vim
vim /etc/systemd/system/pi-web.service

2. 编辑服务配置

输入以下配置（该配置为 密码saf5a6oskaC 、 不自动打开浏览器、开放访问IP、端口指定为30141，大家看情况修改即可。如果不想要密码访问，就Environment=PI_WEB_PASSWORD那行注释掉即可）：

[Unit]
Description=Pi Web
After=network.target

[Service]
Environment=PI_WEB_PASSWORD=saf5a6oskaC
Environment=PI_WEB_NO_OPEN=1
ExecStart=/usr/bin/pi-web --hostname 0.0.0.0 --port 30141
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

注意，这里的 ExecStart 需要各位自己确认一下是不是在这个路径下。可以执行这行命令来确认：

which pi-web

3. 让 systemd 重新加载配置

systemctl daemon-reload

4. 启动Pi Web 服务

systemctl start pi-web

开启后，浏览器访问时会先弹出用户名/密码输入框（用户名随意，密码填你设置的值），输对才能进入。

几个安全提醒：

• ⚠️ 千万别 不配密码 + 监听 0.0.0.0。Pi Web 的权限很高，能删你系统内容的，被扫到了你的服务器就不保了。
• ⚠️ Basic Auth 走的是 HTTP，密码在网络传输中不加密。局域网/可信内网问题不大；如果要暴露到公网，建议套一层 HTTPS（如 Nginx 反代 + 证书），或者干脆走 Tailscale / WireGuard 这类虚拟组网，让服务只在你的私有网络里可见；
• 密码设置得强一点。

---

2.3 添加模型

Pi Web 添加模型非常简单：在设置面板里选择需要的模型提供商（Anthropic、OpenAI、Google 等主流厂商都在列表里），填入对应的 API Key 即可：

有几个点：

• Key 存在本地，和 Pi 的配置体系一致，不会上传到任何云端，不用担心风险；
• 可以同时配置多家厂商的 Key，对话时随时切换模型，方便对比不同模型在同一个任务上的表现；
• 如果你用的是第三方中转/代理 API，Pi 也支持自定义 provider 和 baseURL，这个属于进阶配置，感兴趣的可以去看 Pi 的 models 文档。

---

2.4 基本使用

Pi 作为现在主流的通用 Agent 之一，基本能力方面其实和其他常见 Agent 没有太大区别：可以让它整理桌面、下载安装包、帮忙整理代码、写脚本、跑数据处理，等等等等。

基础玩法这里就不过多演示了，大家有兴趣可以看看我这个专栏：https://blog.csdn.net/weixin_46739493/category_13196249.html，里面有详细讲到一些基本的 Agent 是如何使用、能做什么。

---

三、配置 Pi Web 系统提示词

---

四、安装 Skill

如果不知道 Skill 是什么的小伙伴，可以先去网上搜搜。简单来讲，Skill 就是各路人马封装好的提示词 + 调用链路 + 脚本，打包成一个「能力包」。比如解析 PDF、PDF 转 Word、转图片，这些都是一种能力，都会有相应的 Skill。
❗️❗️❗️Skill 不是 Agent 的必需品！你也不用原模原样照着我装！

前面说过，Pi 本身非常轻量，除了基本的读、改、写文件和执行命令以外，它没有太多其他内置功能：

因此想要 Pi 好用，前提就是根据自己的需求去下载和配置 Skill。 而 Pi Web 提供了非常方便的 Skill 安装入口，点几下就能装好。

添加技能时有个参数要注意：global 和 project。global 表示你所有的项目都能用这个 Skill；project 表示只有当前这个项目能用，其他项目不可用。一般默认选 global 就行：

4.1 联网搜索

比如我希望 Pi 拥有联网搜索的能力，那就给它装一个联网搜索的 Skill。

相关的 Skill 有不少，我推荐 tavily-search，点击安装即可：

只不过它需要配置 API Key，去官网免费注册就能拿到：https://app.tavily.com/。每个月有 1000 次免费额度，个人使用基本够了。

拿到 Key 之后怎么配？直接跟 Agent 讲，让 Pi 自己去配置就行了——这就是 Agent 工具最爽的地方，连配置都可以外包给它：

配好后直接对话使用：

结果还是挺不错的：

你还可以继续让它把结果总结成 Markdown、HTML，我这里就不继续演示了。大家自己动手去玩，一定会有收获。

---

4.2 读文件

这个就很多了，读excel、word、pdf啥的。本文就拿 PDF 为例。

直接搜索PDF，可以看到 anthropics 和 openai 都有开放的 Skill ，我这里选择 anthropics 的，这个不需要任何的 api key：

随便找个之前对接硬件的文档，让它识别总结一下：

--------

4.3 让AI开口说话

如果你想让agent实现一个功能，开口说话。比方说让AI生成口播的语音。那你可以了解一下 TTS。

还是同样的方法，我们选择 edge 的 tts。这个skill也是不需要任何账号的：

我们直接用上面那个解析PDF的例子继续对话：

非常快，打开看看，确实能播放，效果很不错。

大家一定要自己动手试试，这里我没法贴视频演示。效果真的很不错。

---

4.4 hyperframes

接下来推荐一个我很喜欢的 Skill ：hyperframes。

它是能把 HTML 渲染成视频。它用 HTML/CSS/JS 写视频 —— 视频场景就是一个 HTML 文件，通过 data-* 属性控制时间轴，然后渲染成 MP4/WebM。它会根据输入类型自动选择对应的工作流：

• 产品网站 → 产品宣传视频
• 普通网站 → 网站展示视频
• 文章/概念 → 无真人讲解动画
• GitHub PR → 代码变更说明视频
• 真人说话视频 → 加字幕/加图形包装
• 音乐 → 节拍同步视频
• 演示文稿 → 可交互幻灯片
• 短动画/LOGO/数据动效 → motion graphics
• 能力分层 —— 有核心层（HTML composition 合约）、动画层、关键帧层、创意方向层、媒体层、CLI 层等。

简单来说，你想做视频/动画时，可以直接让 hyperframes 帮你生成出 html，还能转成视频。

我们直接上实操，我让它出一个关于 Skill 是什么的 html，不用视频：

来看看这个 gif，很有意思：

这里只是抛砖引玉一下，其实你还可以自己去限定每一帧的内容，这样你就可以得到一个超快速制作PPT的方法了。

4.5 更多 Skill：这里先点到为止

上面提到的是我比较常用的Skill。因为 Skill 这个话题本身值得单独写一篇：Skill 到底是什么结构、怎么判断一个 Skill 靠不靠谱、怎么自己写一个、我实测好用的 Skill 清单……这些我会专门写个博客在里面详细展开，这里先把「怎么装、怎么用」跑通即可。 todo

装 Skill 之前最好看一眼它的内容。Skill 本质上是一段会进入模型上下文的提示词（还可能附带脚本），来路不明的 Skill 有安全风险。

---

总结

总的来说，Pi Agent 在核心能力上和其他热门 Agent（Claude Code、Codex 等）其实差不多——都是「给一句话，帮你把活干完」。

但 Pi 我现在用得确实比较多，主要原因就是它轻量。轻量带来的直接好处是：快速、精准、且相对不那么耗 token。再加上 Skill 体系可以按需扩展，用久了它会越来越像「你的」工具，而不是「某个厂商的」工具。

反正不管怎么说，动手实践才是第一原则。一行 npx 就能跑起来的东西，没什么试错成本。大家赶紧用起来，自然能体会出区别。