这段时间我被问得最多的一个问题，不是“AI 能不能写代码”，而是“你还在用 Claude Code 吗”。不少团队给我的回答是：我们已经换 Pi 了。Claude Code 刚发布那阵子，确实是终端编程助手的天花板，一句话改整个仓库、跨文件重构、自动跑测试，那种“真结对编程”的体验，第一批用上的人应该都还有印象。但热度消退之后，续费账单、闭源限制、上下文失控这些现实问题开始浮出水面，社区里也开始出现从 Claude Code 转向 Pi 的明显趋势。如果你正在被 Claude Code 的成本和可扩展性困扰，或者正准备入局 AI 编程助手、想找一个模型无关的开源替代品，这篇文章就是给你写的。

1. 先说清楚：Claude Code 为什么曾经是王炸

1.1 惊艳之处：终端里的“AI 结对程序员”

Claude Code 能火，靠的不是花哨的界面，而是它把“AI 结对编程”这件事第一次做得足够完整。传统补全工具，比如 Copilot 那种，本质上是你的“高级自动补全”，它可以给你一段代码，但你得自己考虑它在整个项目里适不适用。Claude Code 不一样，它是真正长在终端里的 agent：你给它一个自然语言目标，它可以自己读取仓库结构、搜索关键函数、跨文件修改、运行测试、再根据报错迭代修复。

我第一次用它重构一个老项目时，印象很深。那个项目里的工具函数散落在七八个文件里，接口命名混乱，我自己动手改起码要一个下午。Claude Code 只花了几分钟就把核心调用链梳理出来，给出了重构方案，还自动跑了测试。那种“有一个通读了整个代码库的同事坐在你旁边”的感觉，确实很震撼。再加上后来推出的 1M 上下文版本，很多人觉得大仓库的终极解法终于来了。

不过也就是这种“震撼体验”，拉高了大家对它的预期。等真正把它放进日常开发流程，尤其是放进团队协作和长期项目里，问题就一个一个冒出来了。

1.2 劝退清单：账单、黑盒、上下文与可用性

先说最直接的：钱。Claude Code 底层走的是 Anthropic 的模型 API，所有的输入、输出、工具调用结果都要按 token 计费。听起来 1M 上下文很美好，但“喂进去的每一块上下文”都要真金白银。我见过一个团队用 Claude Code 跑一个中型仓库的跨模块重构，单次会话消耗了几百万 token，账单直接二三十美元。对他们来说这不是工具不好用，而是“好用得用不起”。如果每天几十个这样的会话，成本会迅速压过团队里任何一个人的工资。

第二个问题是闭源带来的黑盒感。Claude Code 的行为完全取决于 Anthropic 服务端的模型策略，今天你觉得它交互很聪明，明天后端一改，行为可能就变了。你没有办法查看它的完整逻辑，没法在本地离线运行，更没法针对团队自己的代码规范去做深度的定制。本质上你是租了一辆车，但引擎盖是焊死的。

第三个问题隐藏在“1M 上下文”这个卖点背后：上下文大，不代表上下文管理得好。实际用下来，长会话跑到后期照样会丢信息，模型对早前某个决策的“记忆”会变得模糊。尤其是几十万 token 的仓库，它更多是在“大海捞针”，而不是“真正理解整片海洋”。最后你会发现，上下文工程还是得你自己来做，工具并没有帮你省掉这件事。

第四个问题可能更敏感，也更现实：官方支持的可用性在不同地区有差异，部分场景下访问不稳定；同时代码全都上传到第三方服务，对不少企业来说，合规和内网数据策略这一关就过不去。很多人不是不想用 Claude Code，而是用不了、不敢用。于是，一个开源、模型无关、可以自己掌控的 Pi 开始进入大家的视野。

2. Pi 是什么？它凭什么接住这些用户

2.1 定位差异：从“云端黑盒”到“本地可拆的积木”

先说清楚，这里的 Pi 不是树莓派，也不是自动控制理论里那个 PID 的 Pi 项，而是社区里一个开源的 coding agent 项目，核心代号在社区里经常被称为 pi harness。它和 Claude Code 最根本的区别在于：Claude Code 是一个“模型+工具链+策略”深度耦合的成品，而 Pi 只是一个“agent 框架”，模型本身是外插的。

这是什么概念？你用 Claude Code，模型基本锁死在 Anthropic 的闭源模型上。你用 Pi，模型完全由自己选：可以接 DeepSeek 这种性价比很高的云端模型，可以接 Qwen 这类国产开源模型，也可以接你自己机器上跑的本地模型，甚至同一个项目里，轻任务用便宜模型、重任务切换更强的模型，都随你。模型对你来说不再是绑定的“引擎”，而是可以随时更换的零件。

这种“模型无关”的设计，带来的直接好处就是不再被厂商锁定。你不需要跟着某一家模型的能力迭代而被迫升级，也不需要为了一次 API 涨价而慌慌张张。Claude Code 当初吸引人的核心能力，现在被拆成“规划、工具调用、文件编辑、任务执行”这些基础能力，放在 Pi 这个框架里，谁都可以拼装。

2.2 pi harness：把“模型”和“干活的能力”拆开

“harness”这个词，在编程 agent 领域常被翻译成“指令框架”或者“工作服”。你可以把它理解成一套控制 agent 如何思考、如何调用工具、如何修改文件的规则系统。Claude Code 的 harness 是内置的、不可改的，而 Pi 的 harness 是开放的、可配置的。

具体来说，Pi 会调用你配置好的模型去做规划和决策，但真正干活的工具链，比如终端命令执行、文件读写、代码搜索、测试运行，都在 harness 层实现。这意味着你可以控制 Pi 在什么场景下调用什么工具，什么操作必须经过确认，什么操作绝对禁止。类比一下：Claude Code 是一辆原厂调校好但所有零件都焊死的整车；Pi 是一套底盘，引擎自己选，方向盘自己装，刹车踏板自己去定义灵敏度。

社区里常见的玩法是，把 Pi 接到一个 openai-compatible 的 API 端点上，然后针对不同项目配置不同的系统提示词、技能包和工作流。还有 pi web 这种基于浏览器的工作台，你在远程开发机上跑 Pi，通过它来看会话记录、查 token 消耗、管技能库，对团队协作很友好。这种开放生态，远比在一个闭源工具里默默等官方更新要踏实。

2.3 解决 Claude Code 的四个具体痛点

我整理了一下大家从 Claude Code 迁移到 Pi 的核心理由，基本可以和上一节的劝退清单一一对应：

当然，这并不意味着 Pi 在所有场景下都能胜过 Claude Code。它更像是一次“权责重分配”：把选择权和掌控权还给你，代价是——你得自己花一点时间去配置和维护。对愿意折腾的团队来说，这笔账非常划算。

3. 从 Claude Code 迁到 Pi：完整实操路径

3.1 环境准备：安装与初始化

迁移之前，先把 Pi 跑起来。下面的安装方式以社区最常见的通用路径为例，具体命令以你拿到的项目官方文档为准。

# 方式一：直接通过包管理器安装 pip install pi-agent # 方式二：从源码安装，方便改 harness 源码 git clone https://github.com/pi-agent/pi.git cd pi pip install -e .

我推荐第二种方式，尤其你打算长期使用的话。源码安装意味着你能直接看到 agent 框架的内部逻辑，出了问题可以自己改，这是“掌控工具链”的第一步。

装完之后初始化工作区：

pi init --workspace ~/code/my-project

这个命令会在项目目录下生成.pi/目录，里面会放配置文件、技能目录、命令别名等。初始化完成之后，先不要急着接模型，它会提示你设置 provider。这一步走完，Pi 的骨架就算搭好了。

3.2 关键配置：模型端点与核心参数

Pi 的配置通常集中在一个 YAML 文件里，比如~/.pi/config.yaml或者项目下的.pi/config.yaml。我给出一个接 DeepSeek 类 openai-compatible 端点的配置示例：

provider: openai-compatible base_url: https://your-gateway.example.com/v1 api_key_env: PI_API_KEY model: deepseek-chat temperature: 0.2 max_tokens: 8192 auto_accept: false tools: enabled: - file_read - file_write - shell - grep_search denied: - git_push workspace: root: ~/code/my-project test_cmd: "pytest"

逐项解释一下关键参数：

• base_url是你选定的模型网关地址，必须兼容 OpenAI 的/v1/chat/completions协议。接 DeepSeek 就填它的官方端点，接本地模型就填http://localhost:11434/v1这类地址。
• temperature建议从 0.2 起步。代码生成任务不是创意写作，温度太高会让它“自由发挥”，产出一些结构漂亮但跑不通的代码。
• max_tokens控制单次生成的最大长度，太短会导致长修改被截断，太长又会拖慢响应。
• auto_accept: false是新手期最重要的一个配置。它要求 Pi 每做一次文件修改或命令执行前都跟你确认，防止 agent 自己跑飞。
• test_cmd告诉 Pi 项目用什么命令跑测试，这样它可以在修改完代码之后自动执行回归。

如果你想把模型换成本地模型，比如用 Ollama 跑 Qwen2.5-Coder，只需要把base_url指到本地端点，把model改成 Ollama 里拉取的模型名称。但注意，本地模型和云端大模型的能力差距是真实存在的，复杂重构、长文件一致性、微妙的多文件关联，本地小模型明显吃力。对小项目和轻任务没问题，大项目建议还是用云端强模型。

3.3 把 Claude Code 的技能和工作流搬过来

很多人担心换工具之后积累的“技能库”作废。其实 Claude Code 里的 skills 本质上是“markdown 指令 + 触发条件 + 工具使用规范”，这套东西在 Pi 里完全能平移。

比如你在 Claude Code 里有一个“按团队规范生成后端接口”的 skill，本质上是一段指令文本。在 Pi 里，你只需要把它放到.pi/skills/backend-conventions/SKILL.md：

--- name: backend-conventions description: 生成符合团队规范的后端接口代码，包含参数校验、错误处理和单元测试 triggers: - 创建接口 - 新增路由 --- 1. 先读取项目根目录的 docs/api-style.md 2. 接口命名遵循 snake_case 3. 所有参数必须经过 pydantic 校验 4. 每个接口必须附带单元测试，运行 test_cmd 验证 5. 错误响应统一使用 {"code": <int>, "message": <str>} 格式

Pi 在遇到相关任务时，会自动加载这个 skill 作为上下文的一部分。项目级规范也可以沿用你之前放在 Claude 里的项目说明文档，改成PROJECT.md放在仓库根目录，让 Pi 每次开始任务前先读一遍。

如果你之前用 Claude Code 做过复杂的“分析->计划->执行->测试”工作流，Pi 里同样可以用命令别名或者 hooks 串联。比如把“完成任务后自动跑测试并汇报”绑定到任务结束钩子上：

hooks: post_task: "pi run --test"

这一步迁移的工作量其实不大，真正要改的是你的心态：从“依赖一个闭源工具的全部内置行为”，变成“自己定义 agent 的行为边界”。

3.4 并行验证与收尾

我不太建议你把 Claude Code 一卸了之，尤其是正在做长期项目的团队。更稳的做法是并行两个星期：同一个仓库，用 Claude Code 和 Pi 各跑一遍典型任务，对比产出质量和成本消耗。

我是这样操作的：把仓库复制一份到另一个目录，在旧目录继续用 Claude Code 处理紧急需求，新目录用 Pi 跑一些新功能和新重构。跑了一周之后，两边产出质量基本接近，但 Pi 这边的账单数字明显更友好。确认没问题，再按官方文档把 Claude Code 从环境里卸载干净。

4. 迁移之后：账本、注意事项与故障排查

4.1 用一个真实小项目算一笔账

用一个我实际做过的小任务来说话：把一个两千行的 Bash 部署脚本重构成 Python CLI，同时修复一个偶发的 IO 超时 bug。任务量大概相当于一个中级开发者半天的工作量。

需要说明的是，这个数字只是数量级参考，不同模型价格和促销政策随时会变。但趋势很清楚：在产出质量相差不大的情况下，Pi 因为模型可选，成本可以压低一个量级。省下来的不是一次任务的几十块钱，而是整个团队全年轻松上万的成本开销。

4.2 实操中的四个注意事项

第一，模型能力决定 agent 的上限。Pi 再灵活，如果底层模型不会正确输出工具调用格式，它照样没法替你改文件。便宜的模型跑简单任务可以，但涉及复杂重构时，该上好模型还是要上，这个钱省不得。

第二，上下文问题并不会因为换工具就自动消失。我一开始天真地以为换到 Pi 就再也不用管上下文了，结果长会话照样信息漂移。后来学乖了，给 Pi 的要求里明确写“先输出探索计划，再执行”，或者在会话中期主动让它总结已达成事项，这比无限堆上下文管用得多。

第三，权限配置要克制。Pi 既然把工具链的控制权交给你，你就得负起责任。我见过有人图方便给 Pi 开了全部 shell 权限，结果它在一次“重构测试文件”的任务里顺手把.git目录里的旧对象清掉了。建议按我在配置示例里写的那样，用denied把危险操作比如git_push、rm -rf /先禁掉。

第四，不要忽略提示词质量。换了新工具，很多人第一反应是“提示词是不是不用讲究了”，实际恰恰相反。Pi 的灵活性和可定制性反而要求你更精确地表达任务边界——它不会像 Claude Code 那样耐心猜测你的意图，但它会在你的规则边界内执行得非常听话。

4.3 常见错误排查速查表

我在迁移和日常使用中踩过不少坑，整理成一张速查表：

这里特别说一下response stream was malformed这个报错，它出现的频率不低。网上对这个报错的解释很多，但多数没说到点上。我遇到的情况基本都是流式输出被中间环节掐断造成的，不是你配置写错了。排查顺序是：先看网关日志有没有超时记录，再调低单次输出长度试试，最后才考虑模型兼容问题。很多人一上来就怀疑模型选错了，其实方向就跑偏了。

最后说点实在的

我自己用 Pi 跑了几周之后，最强烈的感受不是“省了多少钱”，而是一种“工具终于可以被自己掌控”的安全感。Claude Code 依然可以在半小时内帮你完成一个小任务时带来惊喜，但把你整个团队的工作流、数据策略和长期成本押在一个闭源黑盒上，这个风险我是不太愿意承担的。Pi 给我的价值，是当我想换一个更便宜的模型、或加一个自定义工具、或把环境整体迁到内网时，我不需要等任何人批准，自己动手就能完成。

最后分享一个我个人的小习惯：对于十分钟内能完成的小任务，我不会刻意禁用任何工具，哪个顺手用哪个；但只要任务要跨文件、跨模块，或者要沉淀成团队可复用的流程，我会优先打开 Pi，把每一步动作确认清楚，让它自己跑。工具会不断迭代，但“选择自己工具链”的能力，永远值得你花时间去掌握。