本文安装、命令部分已在 Ubuntu 26.04 服务器上实测;Ollama 接入与只读任务实测已在 o3(arm02,Ubuntu 26.04 aarch64,2 核,11G 内存)上补完,见第五节。2026 年 11 月 14 日更新:换 9B 模型再测,pi 调动了工具(但答案卡在 thinking 里),见第六节。2026 年 11 月 19 日更新:改用 LLM API(Gemini)再测,不用拉模型、不用 GPU,7 秒多就出了正确的表,见第七节。

昨天实测了 omp,今天轮到它的“原作”:pi。一个跑在终端里的 AI 编程 agent,作者是 Mario Zechner(libGDX 的作者),MIT 开源。omp 就是在 pi 基础上 fork 出来再大幅扩展的,所以把 pi 搞明白,omp 的很多设计选择也就看懂了。本文只写实测过的内容:安装、命令、配置目录、那个静默卡住的坑和 Ollama 接入都是亲手跑过的;1.5B 小模型那节没跑通就明说没跑通。

pi 的理念是“越薄越好”:内置只有 4 个工具——read、write、edit、bash,系统提示词不到 1000 token,没有子 agent、没有权限弹窗、没有 plan mode,其他功能都靠扩展。1.0 之后加了 MCP 和 codemode。换句话说,它故意不做“大而全”,把选择权留给用户:要什么自己装扩展,不要的它也不塞给你。这个项目迭代很快,10 月中旬文档里还是 1.2.0,我 11 月 11 日实测装到的已经是 1.5.2,pi update 可以随时跟进新版本。

一、安装(实测)

pi 是个 npm 包,安装命令就一行:

npm i -g @earendil-works/pi-coding-agent

我在一台 Ubuntu 26.04、Node 22 的服务器上实测:Node 是系统自带的(node -v 显示 v22.22.1,npm 9.2.0),无需另装;npm i -g 装了 123 个包,约 22 秒装完,版本是 1.5.2。装完 pi --version 能正常输出版本号。

注意别装错包:PyPI 上有个同名的 pi-coding-agent,是另一个 Python 写的项目,不是这个。认准 npm 上的 @earendil-works/pi-coding-agent。

二、内置工具比文档说的多一点

文档说内置 4 个工具(read、write、edit、bash),实测 pi --help 末尾列出的还多三个:grep、find、ls。但它们默认是关闭的,需要手动开启。开启的办法是 pi config,它会打开一个设置界面(TUI),全局设置存在 ~/.pi/agent/settings.json,按 Tab 可以切到项目本地的 .pi/settings.json。刚装完跑 pi list 会显示 No packages installed,说明一个扩展都没装,底子确实干净。

顺带一提,pi --help 里还列出了 powershell——在 Windows 上跑 bash 的替代品,Linux 服务器上用不到。

三、基本用法:交互和非交互两种跑法

直接敲 pi 进终端界面(TUI),在里面对话、按命令切换模型、分支会话。想把它嵌进脚本里,用 -p(--print)非交互模式:跑完任务就退出,不停在界面里:

pi -p "列出当前目录下的 Python 文件"

指定模型用 --model,格式是 provider/id,比如 --model ollama/qwen3-coder:30b;输出格式用 --mode,除了默认的 text,还有 json 和 rpc,适合脚本解析。会话管理有 --continue(续上最近一次会话)、--resume(从历史会话里挑一个)、--session(按路径或 ID 打开指定会话)。升级用 pi update,不带参数默认只更新 pi 自己,加 --extensions 更新扩展,--models 只刷新模型目录。

功能不够就装扩展,这是 pi 的核心玩法。pi install <来源> 装一个扩展源,pi list 列出已装的扩展,pi remove <来源> 卸载,pi update --extensions 批量更新。刚装完的 pi 是“裸机”,pi list 显示 No packages installed;社区扩展市场里已经有两千多个包,按需拼自己的工具箱,而不是等官方把所有功能都塞进核心里。

四、认证和模型:不配模型,pi 会静默卡住

这是实测踩到的最值得写进教程的一个坑:没配模型的时候跑 pi -p(非交互模式),它会一直静默卡住,没有任何报错。不像 omp 会明确告诉你 No default model selected,pi 就安静地挂在那儿,很容易误判成程序死了。我实测时用 timeout 25 跑了一次,25 秒后被 timeout 杀掉才退出,全程零输出。规矩很简单:先配好 provider,再跑任务。

认证走 pi auth login,用法是:

pi auth login <provider> [--api-key]

凭证存在 ~/.pi/agent/auth.json。pi auth check 可以检查某个 provider 是不是就绪,pi auth print-api-key 能把凭证打出来给外部工具用。首次运行后,pi 会在用户目录下建出 ~/.pi/agent/,里面有 auth.json、models-store.json 和 sessions/,会话记录就存在这里。

五、接入 Ollama(实测:1.5B 小模型调不动工具,和 omp 一样)

这一节在 o3(arm02)上实测补完。o3 是台空机器,Ubuntu 26.04 aarch64,2 核,11G 内存,100G 硬盘,只装了系统和用户,Ollama、Node、pi 都是这次现装的。

先装 Ollama 和 Node:

curl -fsSL https://ollama.com/install.sh | sudo sh
ollama --version  # 0.40.16

sudo apt-get install -y nodejs npm
node --version  # v22.22.1

注意:o3 上 npm i -g 不加 sudo 会报 EACCES(/usr/local/lib/node_modules 没写权限),pi 要加 sudo 装:

sudo npm i -g @earendil-works/pi-coding-agent
pi --version  # 1.5.2

拉模型:为了和 omp 那篇对照,用同一个模型:

ollama pull qwen2.5-coder:1.5b  # 986 MB

配模型:在 ~/.pi/agent/models.json 里加一个 Ollama 入口。1.5.2 的格式是这样(字段名是我直接读装好的 pi 的源码确认的,providers 下面挂 baseUrl、api 和 models):

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        { "id": "qwen2.5-coder:1.5b" }
      ]
    }
  }
}

apiKey 随便填一个值就行,Ollama 本地服务不校验它。配好后 pi --list-models ollama 能看到它:

provider  model               context  max-out  thinking  images
ollama    qwen2.5-coder:1.5b  128K     16.4K    no        no

注意这里的 128K 是 pi 默认的假设,不是 Ollama 真正给的上下文。模型跑起来的时候,ollama ps 里 CONTEXT 一栏是 4096——Ollama 默认还是 4096。pi 之所以没踩 omp 那个坑,原因在下面。模型配好后,在交互界面里用 /model 切换,/model 会重新读 models.json。

只读任务实测:和 omp 那篇用一样的任务——读 servers.yml 和 AGENTS.md,列出四台服务器的角色、主机和端口,做成一张表,只做只读检查:

timeout 600 pi -p --model ollama/qwen2.5-coder:1.5b "读 servers.yml 和 AGENTS.md,列出四台服务器的角色、主机和端口,做成一张表,只做只读检查"

结果:38 秒就退出了,退出码 0,全程输出只有下面这一段:

{
  "name": "read_servers.yml_and_AGENTS.md",
  "arguments": {
    "command": "cat /home/xianqingy/pi-test/servers.yml AGENTS.md"
  }
}

没有调 read,没有调 bash,没有表,之后就停了。会话记录里也只有这一条 assistant 消息。也就是说,1.5B 这个量级的模型在 pi 上和在 omp 上是一样的:调不动工具。它会编一个看起来像工具调用的 JSON 文本发出来,但并不会真的调用工具。链路是通的(装 pi、拉模型、pi 认出模型、模型能出字),干活指望不上。

但有一点和 omp 不一样:4096 上下文的坑在 pi 这边没重现。这次没有报 400,也没有 “exceeds the available context size”。原因是 pi 的系统提示词不到 1000 token,加上任务本身很短,4096 装得下;omp 是系统提示词自己就 7945 token,4096 连开局都不够。所以这个坑踩不踩,取决于 agent 的系统提示词有多大,不取决于 Ollama——pi 的提示词小,4096 够用;文件再长、任务再大,4096 还是会不够,到时候一样要焊 num_ctx。

结论和 omp 那篇一样:想让本地模型真干活,要上带工具支持的大模型,文档建议的 Qwen3-Coder-30B、Devstral Small 2、gpt-oss-20b 这类。2 核 ARM 跑不动 30B,1.5B 只能用来验证链路和练手。

另有一层关系值得提:OpenClaw 就是基于 pi 的 SDK 做的,所以 pi 的扩展和会话机制,也是 OpenClaw 底下那套东西。

六、换 9B 模型再测:pi 终于调动了工具,但答案卡在 thinking 里

第五节的结论只对 1.5B 成立。2026 年 11 月 14 日,我换了一个 9B 模型再测——不是本地跑的,是通过一个 OpenAI 兼容接口接进来的(~/.pi/agent/models.json 里把 baseUrl 改成 https://api.example.com/v1,api 还是 openai-completions,模型填 lukey03/qwen3.5-9b-abliterated,上下文 262144)。任务、文件、跑法和第五节完全一样:读 servers.yml 和 AGENTS.md,做一张四台服务器的表,只读检查,pi -p 非交互模式,各跑了两次。

第一次(12 秒):stdout 是空的,退出码 0。乍一看像没跑成,但会话记录(~/.pi/agent/sessions/ 下的 jsonl)里看得清清楚楚:第一轮发起了两个真实的 read 工具调用,两个文件确实被读到了,工具返回了真实内容;第二轮只有一个 thinking 块,表就在里面(角色、主机、端口三列,数据全对)。pi -p 只打印 text 内容,thinking 块不打印,所以终端上什么都没看到。

第二次(19 秒):同样 stdout 为空,退出码 0。第一次 API 调用先报了 500(工具调用的 XML 格式写坏了),pi 自动重试后恢复;随后又是两个真实的 read 调用,工具返回成功;最后一轮的 thinking 块里是完整正确的表,这次还带了服务器名那一列(web1/db1/cache1/mq1,角色、主机、端口全对)。

两次都把 thinkingLevel 设成了 off,但模型还是返回了 thinking 块——OpenAI 兼容接口把推理内容当 reasoning 返回,pi 记成 thinking,-p 不打印。结论要分两句说:9B 模型确实能调工具,1.5B 的结论在 pi 这边被推翻了;但在 -p 模式下,答案可能落在 thinking 里,终端上看不到,得去会话记录里翻。如果只看 stdout,会误判成“没跑成”,这个坑和第四节那个静默卡住的坑是一路的:pi 不报错,只是把东西放在你没看的地方。

适用范围写清楚:只测了 -p 打印模式、同一个只读任务、各两次;交互模式没测。

七、用 LLM API 再测:Gemini,不用拉模型、不用 GPU

第五、六节都是本地模型路线:先 ollama pull 拉模型文件(1.5B 是 986 MB,30B 更大),再在 2 核 ARM 上跑,慢、还容易调不动工具。有了 LLM 的 API key,这条路可以反过来:模型在云端跑,本地只发请求,不拉模型文件、不用 GPU,o3 这种小机器也能用。

这一节在同一台 o3、同一个 ~/pi-test、同一个只读任务上实测,模型是 google/gemini-2.5-flash。

pi 1.5.2 自带 google provider,认 GEMINI_API_KEY 这个环境变量,不用在 models.json 里手写一个自定义 provider。密钥别写进 models.json、别写进文章、别进 git,我的做法是放一个单独的文件 ~/.keys,权限 600,里面一行:

GEMINI_KEY=你的密钥

用的时候再导成 pi 认的名字:

set -a; source ~/.keys; export GEMINI_API_KEY="$GEMINI_KEY"
pi auth check --provider google  # ready

pi --list-models google 能看到它,gemini-2.5-flash 那行是 1.0M 上下文、65.5K 最大输出,thinking 和图片都是 yes。同一份 key 在 generativelanguage.googleapis.com 上也能直接列出模型,2.5-flash、2.5-pro、3、3.1、3.5、3.6 的 flash 都在里面,这里只测 2.5-flash 一个。

跑法和第五、六节完全一样:

timeout 300 pi -p --model google/gemini-2.5-flash "读 servers.yml 和 AGENTS.md,列出四台服务器的角色、主机和端口,做成一张表,只做只读检查"

跑了两次,两次都成功:

第一次(7.48 秒):退出码 0,stdout 直接就是表,不用去会话记录里翻:

| 服务器名称 | 角色       | 主机       | 端口   |
| ---------- | ---------- | ---------- | ------ |
| web1       | Web 服务器 | 10.0.0.11  | 80     |
| db1        | 数据库     | 10.0.0.12  | 5432   |
| cache1     | 缓存       | 10.0.0.13  | 6379   |
| mq1        | 消息队列   | 10.0.0.14  | 5672   |

第二次(7.27 秒):退出码 0,同样直接出表,四行数据全对(这次表里没带服务器名那一列,角色、主机、端口都对)。

会话记录(~/.pi/agent/sessions/ 下最新的 jsonl)里看得清楚:第一次发起了两个真实的 read 工具调用,一个读 AGENTS.md,一个读 servers.yml,不是编出来的表。

和前面两节放一起比,差别很直接:1.5B 本地模型 38 秒、没调工具还编了一个假调用;9B 模型 12 秒、19 秒,调了工具但答案落在 thinking 里、-p 打印为空;Gemini API 7 秒多,调了工具,答案直接打在 stdout 上。本地路线要先拉模型、再拼硬件,API 路线把这两步都省了,代价是请求要走网络、用量按 Google 的 API 计费,具体看 Google AI Studio 里的用量和账单,别在文章里写死价格。

适用范围写清楚:只测了 gemini-2.5-flash、同一个只读任务、两次;其他 Gemini 模型、写文件任务、交互模式都没测。

八、和 omp 对比

piomp
定位极简原作,4 个内置工具在 pi 基础上 fork 并大幅扩展
系统提示词不到 1000 token大得多(这也是小模型上下文容易爆的原因)
子 agent / plan mode / 权限弹窗都没有,靠扩展内置
扩展方式扩展 + MCP + codemode内置 LSP、调试器、子 agent、计划模式等
适合想要一个薄底子、自己拼功能的人开箱即用、要现成运维工作流的人

一句话总结:pi 像一块毛坯,omp 像精装修。喜欢自己动手拼的人选 pi;想装完就能按 AGENTS.md 规则干运维活的,omp 更省事。两者的安装、认证、本地模型坑大多是通的,但 omp 那篇里的 Ollama 上下文坑(默认 4096 不够、要 Modelfile 焊 num_ctx)在 pi 这边没重现——pi 的系统提示词不到 1000 token,4096 够装;1.5B 调不动工具这一点,两边一模一样。

2026 年 11 月 14 日补测:换 9B 模型后,pi 能真正调 read 工具(但答案可能落在 thinking 里,-p 打印为空,见第六节);omp 在 -p 模式下两次都不调工具,直接编表(见 omp 教程第二节新增小节)。同一个模型、同一个任务,两边结果不一样,差别在 agent 不在模型。

九、安全提醒

pi 默认不做权限确认,bash 是直接跑的。在重要机器上用时心里要有数:它执行命令前不会问你,也没有内置的沙箱隔离,命令直接落在宿主机上跑。要么在隔离环境(容器、虚拟机)里跑,要么先从只读任务开始练手,每次任务后人工核对它动了什么,再逐步放开到写文件、改配置这类操作。

API key 也一样:别随手写进明文配置文件里传来传去,别贴进文章、聊天记录、git 仓库。上面第七节的做法是 key 只存在 ~/.keys(600)里,运行时用环境变量导给 pi,用完就只是个环境变量,不落盘到项目里。


实测环境:pi 1.5.2(npm 全局安装)、Node 22.22.1、Ubuntu 26.04;Ollama 部分在 o3(arm02,Ubuntu 26.04 aarch64,2 核,11G 内存)上实测,Ollama 0.40.16、模型 qwen2.5-coder:1.5b。