Pi Agent 快速上手教程以及扩展推荐

介绍

Pi 是一个类似 Claude Code / Codex / OpenCode 的 Coding Agent，但更精简更轻量。

由于是快速上手教程，就不过多介绍了，详情可以看方生无归佬的贴子。

这篇贴子用于快速上手pi，要深入了解详细内容请看我贴出的原文链接
前言
按照的作者话来说,Pi Coding Agent是一个有主见且极简的Coding Agent，这段时间爆火的OpenClaw就是基于此工具包构建的。上手了一段时间后，我敢说这就是目前最好用的AI Agent CLI。
很多项目爆火后都会迎来各种低质量的issues和ai生成的pr，而pi这个名字非常有意思，会与数学信息产…

安装

这里比较推荐用 npm 安装：```
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

编辑 `~/.pi/agent/models.json`，参考下面的配置，把你的 baseUrl、apiKey、models 信息添加进去。

一般来说大部分 AI 服务都支持 openai chat 格式，所以 api 可以填 `openai-completions`。

如果有其他格式支持也可以填 `openai-responses`、`anthropic-messages` 等。```
{
  "providers": {
    "my-provider-1": {
      "baseUrl": "https://my-provider-1.com/v1",
      "api": "openai-completions",
      "apiKey": "sk-******",
      "headers": {
        "User-Agent": "claude-cli/2.1.217"
      },
      "compat": {
        "sendSessionAffinityHeaders": true
      },
      "models": [
        {
          "id": "grok-4.5",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 500000,
          "maxTokens": 128000
        },
        {
          "id": "glm-5.2",
          "reasoning": true,
          "input": ["text"],
          "contextWindow": 1000000,
          "maxTokens": 128000
        }
      ]
    },
    "my-provider-2": {
      "baseUrl": "https://my-provider-2.com/v1",
      "api": "openai-completions",
      "apiKey": "sk-******",
      "headers": {
        "User-Agent": "claude-cli/2.1.217"
      },
      "compat": {
        "sendSessionAffinityHeaders": true
      },
      "models": [
        {
          "id": "minimax-m3",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 500000,
          "maxTokens": 128000
        },
        {
          "id": "deepseek-v4-pro",
          "reasoning": true,
          "input": ["text"],
          "contextWindow": 1000000,
          "maxTokens": 128000
        }
      ]
    }
  }
}

如果你不想手搓配置文件，也可以考虑使用配置工具。

站内有几位佬写了配置工具，我是手搓的，这些工具都没有尝试过。

本帖使用社区开源推广，符合推广要求。我申明并遵循社区要求的以下内容：

我的帖子已经打上 开源推广 标签： 是
我的开源项目完整开源，无未开源部分： 是
我的开源项目已链接认可 LINUX DO 社区： 是
我帖子内的项目介绍，AI生成、润色内容部分已截图发出： 是
以上选择我承诺是永久有效的，接受社区和佬友监督： 是

以下为项目介绍正文内容，AI生成、润色内容已使用截图方式发出

本项目解决…

本帖使用社区开源推广，符合推广要求。我申明并遵循社区要求的以下内容：

我的帖子已经打上 开源推广 标签： 是
我的开源项目完整开源，无未开源部分： 是
我的开源项目已链接认可 LINUX DO 社区： 是
我帖子内的项目介绍，AI生成、润色内容部分已截图发出： 是
以上选择我承诺是永久有效的，接受社区和佬友监督： 是

以下为项目介绍正文内容，AI生成、润色内容已使用截图方式发出

Pi-Sw…

本帖使用社区开源推广，符合推广要求。我申明并遵循社区要求的以下内容：

我的帖子已经打上 开源推广 标签： 是
我的开源项目完整开源，无未开源部分： 是
我的开源项目已链接认可 LINUX DO 社区： 是
我帖子内的项目介绍，AI生成、润色内容部分已截图发出： 是
以上选择我承诺是永久有效的，接受社区和佬友监督： 是

以下为项目介绍正文内容，AI生成、润色内容已使用截图方式发出
一周前我发帖…

重试配置

配完 models.json 就已经可以输入 pi 开蹬了，但如果用的公益站，可能会遇到一些问题。

公益站通常有 RPM 限制，而 Pi 默认的重试机制是 2 秒、4 秒、8 秒，重试 3 次后就会报错，导致任务中断。

公益站的 RPM 限制是以分钟为单位的，也就是说默认配置下触发了必定会报错。

编辑 ~/.pi/agent/settings.json，把 retry 配置加进去，可以解决这个问题。```
{
"retry": {
"enabled": true,
"maxRetries": 5,
"baseDelayMs": 15000
}
}

原生状态的 Pi 已经足以应对大部分的任务，如果想用得更顺手，可以安装一些 package。

我安装了 LazyPi 推荐的全部 package，又从 package 库里选了一些下载量高的，然后用 AI 逐一审查，最终留下了 22 个 package。

一键安装

如果你不想看长篇大论，可以直接用下面的命令一键安装全部 22 个 package：```
pi install npm:@juanibiapina/pi-extension-settings npm:@juanibiapina/pi-powerbar npm:pi-hashline-edit-pro npm:pi-slopchop npm:@narumitw/pi-goal npm:@narumitw/pi-plan-mode npm:@narumitw/pi-subagents npm:@juicesharp/rpiv-ask-user-question npm:@juicesharp/rpiv-todo npm:@narumitw/pi-btw npm:pi-mcp-adapter npm:@ff-labs/pi-fff npm:pi-rtk-optimizer npm:pi-cache-optimizer npm:@narumitw/pi-lsp npm:pi-agent-browser-native npm:pi-add-dir npm:@ayulab/pi-rewind npm:@narumitw/pi-caffeinate npm:@tmustier/pi-raw-paste npm:@victor-software-house/pi-curated-themes npm:pi-autoresearch
```pi-extension-settings```
pi install npm:@juanibiapina/pi-extension-settings
```为扩展提供一个统一的配置命令 `/extension-settings`，目前只有 `pi-powerbar` 用到了。

由于是扩展管理器，因此需要第一个安装，或者手动编辑 `~/.pi/agent/settings.json`，把 `pi-extension-settings` 挪到 `packages` 数组的首位。

pi-powerbar```
pi install npm:@juanibiapina/pi-powerbar
```添加一个简洁的底部信息栏。

pi-hashline-edit-pro```
pi install npm:pi-hashline-edit-pro
```把内置的 `read` 和 `edit` 替换成哈希版，或许可以改善读写准确性。

pi-slopchop```
pi install npm:pi-slopchop
```添加 `/slopchop` 和 `/diff` 命令，方便代码审查。

pi-goal```
pi install npm:@narumitw/pi-goal
```添加 `/goal` 命令。

pi-plan-mode```
pi install npm:@narumitw/pi-plan-mode
```添加 `/plan` 命令。

pi-subagents```
pi install npm:@narumitw/pi-subagents
```添加 `subagent` 工具，支持主 Agent 自主决定。

pi-autoresearch```
pi install npm:pi-autoresearch
```添加 `/autoresearch` 命令，功能是针对指定目标自我迭代。

rpiv-ask-user-question```
pi install npm:@juicesharp/rpiv-ask-user-question
```添加多功能的 `ask-user-question` 工具。

rpiv-todo```
pi install npm:@juicesharp/rpiv-todo
```添加 todo 列表。

pi-btw```
pi install npm:@narumitw/pi-btw
```添加 `/btw` 命令。

pi-mcp-adapter```
pi install npm:pi-mcp-adapter
```添加按需发现的 MCP 服务器适配器。

pi-fff```
pi install npm:@ff-labs/pi-fff
```用 FFF 替换内置的 `find` 和 `grep` 工具。

pi-rtk-optimizer```
pi install npm:pi-rtk-optimizer
```自动调用 `rtk` 来压缩工具调用的输出，降低 Token 消耗。

pi-cache-optimizer```
pi install npm:pi-cache-optimizer
```缓存优化器，在提示要修改 model 配置时可以调用 `/cache-optimizer fix` 自动修改。

pi-lsp```
pi install npm:@narumitw/pi-lsp
```添加 lsp 配置。

pi-agent-browser-native```
pi install npm:pi-agent-browser-native
```添加 `agent_browser` 工具，可以执行打开页面、截图、点击、填表等操作。

pi-add-dir```
pi install npm:pi-add-dir
```添加 `/add-dir` 命令。

pi-rewind```
pi install npm:@ayulab/pi-rewind
```添加 `/rewind` 命令。

pi-caffeinate```
pi install npm:@narumitw/pi-caffeinate
```处理任务时，阻止电脑休眠，适合开个 `/goal` 模式挂一晚上。

pi-raw-paste```
pi install npm:@tmustier/pi-raw-paste
```添加 `/paste` 命令，直接贴入大段原始文本。

pi-curated-themes```
pi install npm:@victor-software-house/pi-curated-themes
```添加一些主题，可以通过 `/settings` 命令切换，在最后一项。

关于 oh-my-pi

oh-my-pi (omp) 是一个 Pi 的 fork 版本，添加了很多开箱即用的功能，但也有过于臃肿之嫌。如有兴趣，也可以试试。```
bun install -g @oh-my-pi/pi-coding-agent

如果是使用 Pi + Windows Terminal 的用户，可能会遇到窗口滚动条忽然跳到顶部的 bug。

Pi 社区说是 Windows Terminal 的渲染问题，不会做特殊处理，要等 Windows Terminal 修复。

以微软的效率，估计要几个月后了。 ╮（╯＿╰）╭