最近在折腾编程 Agent 的时候，被 Claude Code 的能力惊艳到了，但订阅限制、地区限制、模型收费这些问题也确实让人头疼。尤其是团队协作时，每个人都要配置一遍环境，还要处理各种 token 消耗，实在有点劝退。后来接触到 Pi 这个编程 Agent，发现它可以在不受 Claude Code 官方限制的情况下实现类似的 Agent 编程体验，而且对 Ubuntu、Windows、macOS 都比较友好。这篇文章就把我的完整实操过程整理出来，包括 Pi 的安装、基础配置、在 VS Code 中的使用方式，以及它和 Claude Code、Codex 等工具的核心差异。不管你是刚接触 Agent 编程的新手，还是想找一个免费替代方案的开发老手，都可以在文中找到可以直接照做的步骤和避坑经验。
1. 为什么需要 Pi 编程 Agent
先聊一个基础问题：什么是编程 Agent？从使用角度看，它就像一双“看不见的手”，能根据你输入的自然语言指令，自动读取项目文件、生成代码、执行命令、定位报错，甚至帮你完成多文件的修改。Claude Code 就是这一类工具的代表，它的交互方式和真实开发流程非常接近，很多开发者用过之后就很难回到纯手写代码的模式。
但 Claude Code 在落地时有不少限制：
- 官方通道有订阅门槛，免费体验额度有限。
- 部分地区网络环境不稳定，连接官方服务容易中断。
- 公司或组织可能禁用 Claude Subscription Access。
- token 消耗速度快，一次复杂任务容易吃光额度。
Pi 编程 Agent 的出现，就是要在“类 Claude Code 体验”和“更低门槛”之间找到平衡。它支持本地部署，也可以接入不同模型，像 Ollama、DeepSeek 这类第三方模型都能配合使用。对于想尝鲜 Agent 编程，又不想被官方限制卡住的人来说，Pi 是一个很合适的替代选择。
还有一点很实用：Pi 在 Ubuntu 这类 Linux 系统上也能正常安装运行，开发者不需要因为工具链不兼容而被迫切回 Windows。整个 Agent 编程的流程，从对话、代码生成到工具调用，Pi 都提供了完整的命令行界面。
2. Pi 和 Claude Code、Codex 的核心差异
在进入实操前，先用一张表格把 Pi、Claude Code、Codex 的区别理清楚，这样后面配置时你会更清楚每一步的作用。
| 对比维度 | Pi 编程 Agent | Claude Code | Codex |
|---|---|---|---|
| 官方限制 | 相对较少，可本地配置模型 | 官方订阅限制较多 | OpenAI 生态，需要 API Key |
| 模型接入 | 支持 Ollama、DeepSeek 等多种模型 | 主要以 Anthropic 模型为主 | 主要以 OpenAI 模型为主 |
| 安装复杂度 | 较低，跨平台支持较好 | 中等，需要 Node.js 环境 | 中等，依赖官方 CLI |
| 使用场景 | 个人开发、开源项目、本地模型实验 | 深度代码重构、复杂任务编排 | GitHub 仓库操作、代码生成 |
| 社区活跃度 | 新工具，社区成长快 | 高，资料丰富 | 高，但订阅限制更多 |
如果你之前在 VS Code 中配置过 Claude Code，会发现它依赖 npm 全局安装，启动后要登录 Claude 账号。而 Pi 的安装方式更灵活，有些版本可以直接下载二进制，也可以配合 VS Code 插件使用，甚至能连接本地 Ollama 服务，实现完全离线的 Agent 编程。
对于 Ubuntu 环境，Claude Code 的安装有时会遇到 Node.js 版本不兼容的问题，而 Pi 在这方面的依赖更少，安装过程更平滑。这也是很多人把 Pi 当作“不受限替代”的原因之一。
3. 环境准备与版本说明
本文的实操环境如下，你可以根据自己的系统做微调：
- 操作系统：Ubuntu 22.04 LTS（Windows 10/11、macOS 也可以参考）
- 命令行终端：Bash / Zsh / PowerShell
- 核心工具：Pi 编程 Agent，以及可选的 VS Code
- 辅助模型：Ollama + 本地模型，或者通过 API 接 DeepSeek
- 语言环境：Node.js 16+（部分安装方式需要，但不是必须）
特别说明：Pi 还在快速迭代中，不同版本的安装命令和配置项可能会有差异。本文以下示例以常见的稳定版流程为准，重点演示配置思路，如果你下载的版本命令不一样，优先参考你目标版本的官方 README。
建议你在开始前先确认网络环境能够访问 Pi 的下载源或 GitHub，否则离线安装会比较麻烦。如果你完全离线，也可以提前下载好安装包再拷贝到目标机器。
4. Pi 编程 Agent 的安装与基础配置
4.1 安装步骤（Ubuntu 示例）
Pi 的安装方式常见有两种：一种是使用包管理器直接安装，另一种是下载发行版二进制文件。下面分别演示。
方式一：通过 npm 安装（适合已有 Node.js 环境）
# 全局安装 npm install -g pi-agent需要注意的是，包名可能因版本变化，如果提示找不到包，请去官方仓库确认最新包名。
方式二：下载二进制文件
# 下载最新版本到 /usr/local/bin curl -L https://github.com/pi-agent/pi/releases/latest/download/pi-linux-amd64 -o /usr/local/bin/pi chmod +x /usr/local/bin/pi安装完成后，验证版本：
pi --version如果能输出版本号，说明安装成功。
4.2 初始化项目与环境变量
在项目目录下初始化 Pi：
cd ~/my-project pi init该命令会生成配置文件，通常是.pi/config.json或pi.config.json。配置文件中需要指定模型提供方。
如果你想接入 DeepSeek，可以在环境变量中配置 API Key：
export DEEPSEEK_API_KEY=sk-xxxx或者写入配置文件的 model 字段。按照 Pi 的常见设计，模型配置项类似：
{ "model": "deepseek-chat", "provider": "deepseek", "apiBase": "https://api.deepseek.com" }如果你用的是 Ollama 本地模型，可以这样配置：
{ "model": "qwen2.5-coder:7b", "provider": "ollama", "apiBase": "http://localhost:11434" }这里体现了 Pi 的一个优势：它不绑定单一厂商模型。你完全可以根据项目需求，在云 API 和本地模型之间切换，不用改任何业务代码。
4.3 启动 Pi 交互界面
基础配置完成后，在项目目录启动：
pi启动后，你可以输入类似这样的自然语言指令：
请读取 src/main.py 的代码，并帮我修复未处理异常的问题。Pi 会像 Claude Code 一样，分析文件内容、生成修改建议，并在确认后执行改动。这种“对话即编程”的体验，正是 Agent 编程的核心价值。
5. 在 VS Code 中使用 Pi 插件
很多开发者习惯在 VS Code 里完成所有开发工作，Pi 本身也提供了 VS Code 插件支持。
5.1 安装插件
在 VS Code 扩展商店中搜索“Pi Agent”，找到由官方发布的插件，点击安装即可。如果商店搜不到，可以下载 VSIX 文件后，通过以下命令安装：
code --install-extension pi-agent-1.0.0.vsix5.2 配置插件连接
插件安装后，打开命令面板（Ctrl+Shift+P），输入“Pi: Select Model”，选择你设置好的模型来源。
如果你使用的是本地 Ollama，需要确保 Ollama 服务已启动：
ollama serve然后在 VS Code 设置中搜索pi.ollama.url，设置为http://localhost:11434。
5.3 使用插件修改代码
在编辑器中选中一段代码，右键选择“Pi: Explain Selection”，插件会在侧边栏输出代码解释。你也可以直接打开 Pi 面板，输入改造需求，例如：
把当前文件的数据库连接改成连接池方式Pi 会生成一个 diff 预览，你确认后才会应用更改。这种“先预览再应用”的机制，可以大大降低误改代码的风险。
如果你之前在 VS Code 里配置过 Claude Code，会发现两者的交互逻辑非常像。区别在于 Pi 可以自由切换模型源，而 Claude Code 对模型的要求比较严格。
6. 实战：用 Pi 完成一次带排错的代码修复
这一节我们通过一个完整小案例，演示 Pi 在实际项目中的工作流。
6.1 准备一个示例项目
我们创建一个简单的 Python 项目，里面故意留一个文件读取错误。
mkdir pi-demo && cd pi-demo touch data.txtdata.txt内容是：
hello pi在项目里创建reader.py：
def read_file(filename): with open(filename, "r") as f: return f.read() if __name__ == "__main__": data = read_file("data.txt") print(data)正常运行时能输出内容。现在改造成一个容易出错的版本：把文件名写错。
def read_file(filename): with open(filename + ".missing", "r") as f: return f.read() if __name__ == "__main__": data = read_file("data") print(data)6.2 使用 Pi 分析错误
启动 Pi：
pi输入：
请分析当前项目中的 reader.py，为什么运行会报错？请修复并解释原因。Pi 会先检查文件内容，然后输出类似下面的分析：
- 错误原因：
open()打开了一个不存在的文件，导致FileNotFoundError。 - 修复思路：恢复正确的文件路径，或加入异常处理。
接着 Pi 会提供修改后的代码片段，并询问是否应用。你确认后，文件就被更新。
6.3 验证修复结果
修复后，在终端运行：
python3 reader.py如果输出hello pi，说明 Pi 的修复生效了。
这个案例很基础，但足够体现 Agent 编程的闭环：问题定位 → 方案生成 → 代码修改 → 运行验证。实际开发中，处理多文件重构或跨模块调用时，这种效率提升会更明显。
7. 常见问题与排查思路
在安装和使用 Pi 的过程中，我遇到过一些典型的坑，这里整理成表格，方便你遇到报错时快速定位。
| 问题现象 | 常见原因 | 解决思路 |
|---|---|---|
pi命令找不到 | 安装路径未加入 PATH | 检查全局安装路径，添加软链或配置环境变量 |
| 启动时报模型配置错误 | config.json中的模型名写错 | 对照模型提供方的模型列表，修正名称 |
| 连接 Ollama 超时 | Ollama 服务未启动或端口不对 | 先运行ollama serve，再检查 11434 端口 |
| VS Code 插件无法加载 | 插件版本与 VS Code 版本不兼容 | 升级 VS Code，或安装旧版插件 |
| 生成的代码有乱码 | 终端编码问题 | 设置终端编码为 UTF-8，检查文件首行注释 |
| 任务执行到一半卡住 | 模型 API 请求超时 | 调整配置中的超时时间，或者切换更快的模型 |
| 中文输出变成乱码 | 系统 locale 设置不正确 | 执行export LANG=zh_CN.UTF-8 |
遇到问题时，优先查看 Pi 的日志。大多数 CLI 工具都支持--verbose参数，打开后能看到更详细的错误信息，定位会快很多。
8. 最佳实践与工程建议
8.1 模型选择策略
如果你只是写脚本、改 bug，使用本地 7B 模型已经很快；如果要进行大规模架构重构，建议接入更强的云端模型。我的习惯是：日常小需求用 Ollama 本地模型，降低费用；大功能开发时切换 DeepSeek 等云 API，保证生成质量。
8.2 使用权限与文件变更确认
不要直接让 Pi 无确认地修改文件。在重要项目中，一定要开启“确认变更”模式。Pi 通常会在应用改动前展示 diff，你需要逐个确认 hunk。这既能防止大范围误改，也能让你在审核中理解 AI 的改动逻辑。
8.3 隔离测试环境
Agent 编程工具很强大，但有时候会过度自信。在涉及数据库、生产环境配置或关键业务逻辑时，一定要先在测试环境验证。我在团队内部推广 Pi 时，要求所有改动必须通过 CI 流水线检查，而不是直接信任 AI 的“我改好了”。
8.4 注意 token 消耗
如果你使用的是付费 API，建议在config.json中设置最大 token 上限，避免单个任务把额度耗尽。同时，给 Pi 明确的任务边界，减少无意义的全文件扫描。
8.5 结合 Git 使用
使用 Pi 前，最好先提交一次干净的 Git 快照。这样即使 Pi 生成了不理想的代码，你也可以随时回滚。
git add -A && git commit -m "before pi changes"8.6 保持配置文件的版本管理
将.pi/config.json文件纳入 Git 管理，这样团队成员可以复用同一套模型配置。对于 API Key 等敏感信息，不要直接写在配置文件里，而是使用环境变量注入。
9. 总结与下一步学习路线
本文详细介绍了 Pi 编程 Agent 的安装、配置和在 VS Code 中的使用方法，并结合实际案例演示了一次代码错误定位与修复过程。Pi 最大的价值在于它提供了不局限于某一厂商的 Agent 编程体验，既能接入 DeepSeek 等云端模型，也能配合 Ollama 实现本地运行，真正做到了“预算有限也能玩 Agent 编程”。
如果你之前已经接触过 Claude Code，再上手 Pi 会非常顺滑；如果你是第一次接触 Agent 编程，建议从一个小型 Python 项目开始，先让 Pi 帮你完成代码解释和简单 bug 修复，逐步深入到多文件重构、自动化测试生成等高阶场景。
下一步可以尝试的方向包括：将 Pi 接入 CI/CD 流程、与 OpenCode 等开源工具联动、为 Pi 编写自定义 Skill 或 Prompt 模板。随着开源模型质量持续提升，本地 Agent 编程的体验会越来越接近云端大模型，届时 Pi 这类工具的使用空间还会更大。
希望这篇教程能帮你少踩一些坑，早点用上顺畅的 Agent 编程工作流。如果你在安装配置中遇到其他问题，也欢迎在评论区留言，一起交流解决。
