Pi Coding Agent 安装教程 2026：npm 安装、API Key 配置与 Claude/GPT/Gemini TypeScript 实战

为什么「再下一个 IDE Agent」解决不了多模型

2026 年多数团队的痛苦不是「没有 Agent」，而是钥匙、模型和执行环境绑死在同一家产品里。Claude Code 吃 Anthropic 订阅，Codex CLI 吃 ChatGPT，Cursor 把模型选择藏进编辑器账号。你想下午用 Claude 改架构、晚上用 Gemini 扫测试、周末用 GPT 写提交说明，结果每次都要换窗口、换权限、换上下文。

Pi 把这个假设拆开了。官方定位是最小 harness：默认只给模型 read、write、edit、bash 四件工具；sub-agent、plan mode、权限门、MCP 这些「别人内置的功能」，改成扩展、Skills 或 Pi Package，由你按工作流加。模型是可替换后端，不是产品本体。

非对称结论是：分水岭不在 Claude、GPT、Gemini 谁更强，而在 harness 能不能把模型当成可替换的执行后端，并嵌进你自己的 TypeScript 项目。 该升级的是入口（CLI / SDK / RPC）、凭证分层和常开执行节点，不是再下一个更厚的 IDE。站内对「harness 是什么」的概念拆解，见 Omnigent Agent Harness 彻底搞懂；本篇只解决「怎么把 Pi 装上、把三家钥匙接上、写进仓库」。

Pi 是什么：最小 harness 的四条入口

先归类，再谈命令。Pi 不是又一个聊天窗口，而是同一套 Agent 循环的四种打开方式。分类维度仍是入口、执行、上下文与适合人群。

官网把哲学写得很直：改 harness，而不是改你的工作流。扩展是 TypeScript 模块，能注册工具、斜杠命令、快捷键和 TUI 部件；Skills 按需加载，避免一上来撑爆 prompt cache。包可以 pi install npm:@scope/pkg 或 pi install git:host/user/repo。完整能力清单以 pi.dev 与 npm 包说明为准，版本号会变，命令形态比「某月某日的模型名」更稳。

Pi vs 封闭 Agent：入口、执行、上下文

选型时若先问「Claude 强还是 GPT 强」，会错过真正差异。把 Pi、官方 CLI 和 IDE Agent 放在同一张表上，按入口、执行、上下文与适合人群对齐，结论几乎立刻翻转。排行榜体裁见 2026 最佳 AI Coding Agent 排名；本篇不重做名次，只回答「要不要把钥匙从产品里拆出来」。

Claude Code 与 Codex 在远程 Mac 上的取舍，见 Claude Code vs Codex：远程 Mac 开发环境。那两篇回答的是「官方 CLI 怎么挑」；本篇回答的是「当你已经确定要多模型、还要把循环嵌进 TypeScript 时，harness 怎么装」。

npm 安装与 API Key 配置

全局 CLI：先能对话，再谈嵌入

官方推荐带 --ignore-scripts 的全局安装。Pi 正常使用不依赖依赖包的 install 生命周期脚本；跳过脚本能减少供应链意外。Node 版本以你本机 LTS 为准，仓库声明的引擎号会随包更新，不要把某篇博客里的次版本写成合同。

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# 或：pnpm add -g --ignore-scripts @earendil-works/pi-coding-agent
# 或：bun add -g --ignore-scripts @earendil-works/pi-coding-agent
# 安装器备选：curl -fsSL https://pi.dev/install.sh | sh
pi --version

装完先做两件事：确认 pi 在 PATH 里；确认你准备用的提供商至少有一把钥匙或一次 /login。没有凭证时，TUI 能打开，但模型目录里可跑的项是空的。

钥匙怎么分层：环境变量、auth.json、一次性覆盖

官方凭证解析顺序是：命令行 --api-key → ~/.pi/agent/auth.json → 进程环境变量 → models.json 里的自定义提供商钥匙。交互里 /login 会把 OAuth 或 API Key 写入 auth.json（文件权限 0600）。auth.json 优先于环境变量，适合「这台机器长期用这把钥匙」；环境变量适合 CI 与一次性实验。SDK 里的 setRuntimeApiKey 是进程内覆盖，不落盘，适合测试与多租户宿主。

export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=...   # auth.json 里对应键名是 google

pi
# 交互：/login 选提供商；/model 或 Ctrl+L 切换；Ctrl+S 存为启动默认

{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "openai": { "type": "api_key", "key": "sk-..." },
  "google": { "type": "api_key", "key": "..." }
}

key 字段还支持 $ENV_VAR 插值，以及 !op read 'op://…' 这类命令取值（进程内缓存）。远程或无头机器上，OpenRouter 一类浏览器回调走不通时，官方要求把最终重定向 URL 或授权码粘回登录提示——SSH 上的云 Mac 特别常见。提供商对照表以 providers.md 为准。

接入 Claude、GPT、Gemini

Pi 为每个内置提供商维护一份「能跑工具」的模型目录；已配置的目录会自动刷新，也可 pi update --models 强制拉一次。认证可以是订阅（Claude Pro/Max、ChatGPT Plus/Pro Codex、GitHub Copilot）或 API Key。切换用 /model、Ctrl+L，常用模型用 Ctrl+P 循环；/scoped-models 决定循环名单。

pi --list-models claude
pi --list-models gpt
pi --list-models gemini

pi --provider anthropic --thinking high "把 src/ 里的循环改成可测函数"
pi --model openai/gpt-4o -p "用三句话总结本仓库的入口模块"
pi --provider google -p "只读：列出未覆盖的测试文件"

# 会话内切换，不必重装
# /model   或 Ctrl+L
# Ctrl+P   在 scoped 名单里循环

模型 ID 会随目录刷新变。官方示例里出现过 claude-opus-4-5、claude-sonnet-4-5、gpt-4o、gpt-5.1 这类写法；落地时以 pi --list-models 和 SDK 的 getAvailable() 为准，不要把博客里的快照 ID 写进生产脚本。自定义网关（Ollama、vLLM、公司代理）走 ~/.pi/agent/models.json，前提是对方讲 OpenAI / Anthropic / Google 其中一种 API；OAuth 或私有协议用扩展，不要硬改 CLI。

若你真正要的是「自己写 HTTP、自己解析 JSON」，那是 Function Calling 层，不是 harness 层。对照 Function Calling 与 JSON API 和 GPT-5.6 API 教程：那两篇教你直接打提供商；本篇教你让 Pi 替你管工具循环，只换后端。

TypeScript 项目实战

CLI 解决「人在终端里指挥」；SDK 解决「仓库里的脚本也能指挥」。SDK 打在同一个 npm 包里，不必另装。最小闭环是：本机依赖 → 三把钥匙只进环境 → ModelRuntime 选模型 → createAgentSession 发一条只读任务 → dispose()。

npm init -y
npm install @earendil-works/pi-coding-agent
# package.json 里加上 "type": "module"

import {
  createAgentSession,
  ModelRuntime,
  SessionManager,
} from "@earendil-works/pi-coding-agent";

const runtime = await ModelRuntime.create();

if (process.env.ANTHROPIC_API_KEY) {
  await runtime.setRuntimeApiKey("anthropic", process.env.ANTHROPIC_API_KEY);
}
if (process.env.OPENAI_API_KEY) {
  await runtime.setRuntimeApiKey("openai", process.env.OPENAI_API_KEY);
}
if (process.env.GEMINI_API_KEY) {
  await runtime.setRuntimeApiKey("google", process.env.GEMINI_API_KEY);
}

const preferred =
  runtime.getModel("anthropic", "claude-opus-4-5") ??
  runtime.getModel("openai", "gpt-4o") ??
  (await runtime.getAvailable())[0];

if (!preferred) {
  throw new Error("没有可用模型：先 export 三家钥匙之一，或跑 pi --list-models");
}

const { session } = await createAgentSession({
  model: preferred,
  thinkingLevel: "low",
  tools: ["read", "bash"],
  sessionManager: SessionManager.inMemory(),
  modelRuntime: runtime,
});

try {
  session.subscribe((event) => {
    if (
      event.type === "message_update" &&
      event.assistantMessageEvent.type === "text_delta"
    ) {
      process.stdout.write(event.assistantMessageEvent.delta);
    }
  });
  await session.prompt(
    "只读：列出当前目录的 TypeScript 入口文件，并指出最可能缺少测试的一处。不要改文件。"
  );
} finally {
  session.dispose();
}

这段代码刻意把工具收成 read + bash，会话用内存、不落盘。CI 里评审脚本不该默认拥有 write/edit。要持久会话，改用 SessionManager.create(process.cwd())；要和 CLI 共用同一把长期钥匙，不要调用 setRuntimeApiKey，让 runtime 去读 ~/.pi/agent/auth.json。自定义 auth 路径时，把 authPath / modelsPath 指到应用自己的目录，避免多服务抢同一份家目录文件。SDK 事件、转向（steer）与后续（followUp）的语义见 sdk.md。

AGENTS.md：把仓库规矩写给所有模型

Pi 启动时会拼接 ~/.pi/agent/AGENTS.md、父目录和当前目录的 AGENTS.md（或 CLAUDE.md）。某层若存在 AGENTS.override.md，该层只加载覆盖文件。这就是「换模型不换规矩」的落点：Claude、GPT、Gemini 读同一份入口、测试命令和红线。需要替换系统提示时用 .pi/SYSTEM.md，追加用 APPEND_SYSTEM.md。

# 本仓库给 Pi 的规矩
- 包管理：npm。不要擅自改成 pnpm。
- 检查：npm test && npm run lint
- 红线：不要提交 .env、auth.json、*.pem
- 默认只读；只有用户明确说「可以改文件」才用 write/edit

无头 CI 不会弹出项目信任框。没有已保存的 trust 决策时，非交互模式跟全局 defaultProjectTrust：ask（默认）和 never 会忽略项目级 .pi/ 资源，always 才信任。单次覆盖用 --approve / --no-approve。把 Pi 塞进自建 runner 时，先把信任策略写进机器镜像，再谈模型。GitHub Actions 与云 Mac runner 的分层，见 GitHub Actions macOS 自建 Runner 与云 Mac。

场景怎么选

真正该问的不是「要不要装 Pi」，而是第一约束：要交互改代码、要把 Agent 写成脚本，还是只要一家官方 CLI 的开箱体验。

「Cloud Mac 为什么是 Agent 执行层」的产品判断，见 Cloud Mac 为什么成为 2026 iOS 开发标配。本篇补的是节点上的那一层：npm、钥匙、模型切换和 TypeScript 脚本。

推荐组合

允许工具叠加。Pi 解决的是「可替换模型的 coding harness」；它不负责给你一台不合盖的 Mac，也不负责替你付三家账单。

• 个人日常组合：全局 pi + ANTHROPIC_API_KEY 作默认 + 另外两把钥匙备用 + 仓库 AGENTS.md。交互里 Ctrl+L 换模型，规矩不换。
• TypeScript 仓库组合：全局 CLI 给人用，devDependencies 里再装一份 SDK 给脚本用。评审走只读工具；改文件另开一条人工确认的命令。
• CI 组合：pi -p 或 SDK 脚本 + GitHub Actions Secrets + 自建 macOS runner。信任策略用 --approve 写死，不要在日志里打印钥匙。
• 多提供商网关组合：OpenRouter / Cloudflare AI Gateway 一把钥匙打多家模型；仍用 Pi 的 /model 切换。适合不想在每台机器上散落三把原厂钥匙的团队。
• 最小验证组合：只装 CLI，只 export 一把钥匙，跑 pi -p "列出当前目录的 ts 文件"。四拍跑通（安装→凭证→一次任务→可复现）再加第二家模型和 SDK。

多智能体课堂或 IM 分身不是 Pi 的主场：那些要编排与网关，见 OpenMAIC 与多智能体协作时代。Pi 更适合「同一套读改跑循环，换后端继续干」。

常见误区

• 把 Pi 理解成 Claude Code 的免费克隆。它故意不做 sub-agent 和 plan mode。你要的功能用扩展或 Package 加，不要抱怨「核心太瘦」然后回去等下一款 IDE。
• 三把钥匙塞进同一份会进 git 的 dotenv。开发机用 shell profile 或 1Password；CI 用 Secrets；共享机器用 0600 的 auth.json。SDK runtime key 不落盘，不能代替机器凭证。
• 把博客里的模型 ID 写死进生产。目录会刷新。脚本应 getAvailable() 或 --list-models，再用稳定的 provider 前缀做兜底。
• 在 CI 里给 Agent 默认 write/edit。评审与巡检用只读白名单；改文件另开人工门闩。
• 无头模式还指望弹出 trust 对话框。先设 defaultProjectTrust 或传 --approve，否则项目级 Skills 根本不会加载。
• 在会休眠的笔记本上跑长时 SDK 任务。会话树能恢复，但 bash 中途被休眠打断的副作用不会自动回滚。长时任务放到常开节点。

落地步骤

1. 写清不可妥协项：只要交互、只要脚本，还是两条都要；第一周是否必须同时接三家模型；CI 是否允许写磁盘。
2. 安装 CLI 并做一次空跑：npm install -g --ignore-scripts @earendil-works/pi-coding-agent，pi --version，确认 PATH。
3. 只接一把钥匙：export 或 /login，pi -p "列出当前目录"。验收标准是「可复现」，不是「回复更长」。
4. 再接第二、第三家：补 OPENAI_API_KEY / GEMINI_API_KEY，用 /model 或 --provider 各跑同一条提示，确认规矩来自 AGENTS.md 而不是模型脾气。
5. 把 SDK 写进仓库：项目依赖 + 一条只读 scripts/pi-review.ts。工具白名单写死在代码里。
6. 选定执行环境：本机试用可以；CI 与长时任务放到常开云 Mac 或自建 runner，日志脱敏，钥匙不进制品。
7. 再加扩展与观测：需要 plan mode / MCP / 权限门时再装 Package。先能量用量、失败回退和人工接管，再扩能力。

FAQ

Pi Coding Agent 和 Claude Code 是什么关系？

Claude Code 是 Anthropic 的官方 coding 工作流，模型和入口绑在一起。Pi 是第三方最小 harness，可以用 Anthropic 钥匙或 Claude 订阅，也可以同时接 OpenAI 与 Gemini。它不替代「官方深度集成」，它替代的是「换模型就要换整套工具」。

必须同时配置 Claude、GPT、Gemini 吗？

不必。一把钥匙就能跑通安装验收。第二家钥匙的意义是：同一套 AGENTS.md 和工具白名单，按任务换后端。没有第二家账单时，先不要为「多模型」增加运维面。

全局 npm 安装和项目里的 SDK 会冲突吗？

不会抢同一条命令，但版本可能漂移。约定：人用全局 CLI，脚本锁项目 package.json 的版本。两者读同一份 ~/.pi/agent 时，注意不要在脚本里用 runtime key 覆盖掉机器上的长期钥匙。

Gemini 的环境变量为什么不是 GOOGLE_API_KEY？

官方表把 Gemini API Key 写成 GEMINI_API_KEY，auth.json 键名却是 google。Vertex 走 ADC 与项目/地区变量，和 AI Studio 的 Gemini 钥匙不是同一条路。以 providers.md 为准，不要凭常识猜键名。

Windows / 无头云 Mac 能装吗？

能。npm 全局包跨平台；官网另有 install.sh 与 PowerShell 安装器。无头机器用 pi -p、RPC 或 SDK，不要依赖 TUI。OpenRouter 一类 OAuth 在 SSH 上要粘贴回调。云 Mac 上更该先固化 Node 版本、PATH 与 auth.json 权限。

为什么还要云端 Mac？本机装 npm 不够吗？

本机够用来学命令。不够用来跑夜间评审、合盖后的长时修复、以及和 Xcode / 签名同一套环境的 CI。Pi 把模型解耦了，但 bash 与文件工具仍然绑在那台正在跑进程的机器上。

总结

Pi Coding Agent 的安装教程，表面上是 npm、环境变量和三家模型 ID；真正要落地的是一条分层：harness 与模型分开，钥匙与仓库分开，交互入口与脚本入口分开。2026 年 9 月能站得住的用法，是全局 CLI 给人，SDK 给仓库，AGENTS.md 给所有后端，常开节点给长时任务。

非对称结论仍然成立：分水岭不在 Claude、GPT、Gemini 谁更强，而在你能不能把模型当成可替换后端。先跑通一把钥匙的一次 pi -p，再加第二家模型和 TypeScript 脚本；需要执行面时，再把进程从会休眠的笔记本挪到云端 Mac。该升级的是入口、凭证与节点，不是再下一个 IDE Agent。