1. 终端里跑一个编码代理，为什么我最后选了 Pi Agent
如果你已经在用 Cursor、Claude Code 或者 Cline，可能会觉得“终端编码代理”这个品类已经够卷了。但我实际用下来，Pi Agent 的定位很不一样：它是一款极简编程智能体，核心只保留最必要的部分，把子代理、计划模式、权限弹窗这些统统交给扩展去实现。换句话说，它更像一个终端里的“编码内核”，而不是一个什么都替你决定的黑盒。
Pi Agent 能做什么？它可以在你的项目目录里读写文件、执行 shell 命令、搜索代码、按你的指令完成一个小型编码任务。适合谁？适合那些希望把 AI 编码能力嵌进自己工作流、而不是被工具牵着走的开发者。尤其是当你手头有 llama.cpp 本地推理环境时，Pi Agent 可以直接连本地模型，整个链路不依赖外部服务，调试起来非常直观。
这篇入门指南聚焦一件事：从安装到跑通第一个编码任务。我会把 CLI 安装、llama.cpp 路由器启动、Pi 连接配置、验证命令、以及常见报错排查都写成可复制的片段。你不需要先成为 Pi 专家，跟着敲一遍就能在终端里看到一个能改代码的代理跑起来。
我试过在同一个仓库里同时开 Claude Code 和 Pi Agent 做对比，Pi 的树状会话和上下文压缩机制在长任务里优势明显，尤其是需要反复回退、分叉尝试不同方案的时候。下面从环境准备开始。
2. 前置准备：TaoToken 接入与 llama.cpp 本地推理环境
在正式配置 Pi Agent 之前，需要先把模型来源确定下来。你有两条路：一条是走云端 API，另一条是走 llama.cpp 本地推理。两条路可以并存，Pi 支持在会话里随时切换模型。
先说云端这条。如果你希望用 Claude、GPT 这类模型来驱动 Pi Agent，可以通过 TaoToken 获取 API Key。它的接入地址是 https://taotoken.net/api，你需要在控制台创建一个 Key，然后把它写进 Pi 的 auth.json 或者环境变量里。TaoToken 的 API 兼容 OpenAI 和 Anthropic 两种协议格式，Pi 的 provider 配置里可以直接用。
具体操作：打开 https://taotoken.net/api-keys 创建 Key，复制出来。然后在终端里设置环境变量，比如用 Anthropic 协议：
export ANTHROPIC_API_KEY=你的TaoTokenKey export ANTHROPIC_BASE_URL=https://taotoken.net/api注意 Base URL 不要带末尾斜杠，Pi 在拼接路径时会自己处理。如果你用的是 OpenAI 协议格式，就换成OPENAI_API_KEY和OPENAI_BASE_URL。
再说本地这条。llama.cpp 的路由器模式是 Pi Agent 本地推理的关键。很多人第一次启动 llama-server 时习惯带-m参数指定单个模型，那样启动的是单模型模式，Pi 的/llama命令无法发现和切换模型。正确的做法是不带模型参数，只给模型目录：
llama-server \ --models-dir ~/models \ --no-models-autoload \ --jinja \ --host 127.0.0.1 \ --port 8080 \ -ngl 999 \ -c 32768这里几个参数值得解释。--models-dir指向你存放 GGUF 文件的目录，llama.cpp 会扫描里面的模型。--no-models-autoload表示不自动加载，等你通过 Pi 的/llama命令显式加载，这样启动快、内存也可控。--jinja必须开，否则聊天模板和工具调用会出问题。-ngl 999是尽量把层卸载到 GPU，没有 GPU 就忽略。-c 32768是每个已加载模型的上下文窗口。
模型目录建议这样组织：单文件模型直接放根目录，多分片或多模态模型放子目录。比如：
~/models/ ├── qwen2.5-coder-7b-instruct-q4_k_m.gguf ├── gemma-3-4b-it-Q4_K_M/ │ ├── gemma-3-4b-it-Q4_K_M.gguf │ └── mmproj-F16.gguf └── large-model-Q4_K_M/ ├── large-model-Q4_K_M-00001-of-00003.gguf ├── large-model-Q4_K_M-00002-of-00003.gguf └── large-model-Q4_K_M-00003-of-00003.gguf启动后访问http://127.0.0.1:8080能看到路由器的 Web 界面，说明服务正常。这一步是整个本地链路的地基，后面 Pi 能不能连上就看它。
3. 可复制配置：Pi Agent 安装与 settings.json 片段
Pi Agent 以 npm 包形式分发，包名是@earendil-works/pi-coding-agent。全局安装：
npm install -g --ignore-scripts @earendil-works/pi-coding-agent--ignore-scripts是官方推荐，Pi 的正常安装不需要跑依赖的生命周期脚本，加上它更干净。Linux 和 macOS 也可以用一键脚本，但 npm 方式跨平台更稳。
安装完成后，在项目目录里运行pi就能启动。首次启动需要认证。如果你走 TaoToken 云端，直接在环境变量里给 Key 就行；如果走本地 llama.cpp，用/login llama.cpp命令，输入路由器地址http://127.0.0.1:8080，API key 留空或填你设置的。
接下来是配置文件。Pi 的设置分全局和项目两级：全局在~/.pi/agent/settings.json，项目在.pi/settings.json。项目设置覆盖全局，嵌套对象会合并。下面是一份可以直接复制的 settings.json，兼顾云端和本地两种模型来源：
{ "defaultProvider": "anthropic", "defaultModel": "claude-sonnet-4-20250514", "defaultThinkingLevel": "medium", "theme": "dark", "compaction": { "enabled": true, "reserveTokens": 16384, "keepRecentTokens": 20000 }, "retry": { "enabled": true, "maxRetries": 3, "baseDelayMs": 2000 }, "enabledModels": ["claude-*", "gpt-4o", "qwen2.5-coder*"], "packages": ["pi-skills"] }如果你主要用本地模型，把defaultProvider改成llama.cpp，defaultModel填你在/llama里加载的模型名。enabledModels控制 Ctrl+P 循环切换时出现哪些模型，支持通配符。
认证文件在~/.pi/agent/auth.json，权限建议 0600。它支持环境变量插值和 shell 命令执行两种高级用法。比如从系统钥匙串读取：
{ "anthropic": { "type": "api_key", "key": "!security find-generic-password -ws 'anthropic'" }, "openai": { "type": "api_key", "key": "$MY_OPENAI_KEY" } }$开头是环境变量插值，!开头是执行命令取输出。转义规则：$$输出字面量$，$!输出字面量!。这个机制让你不用把明文 Key 写进文件，适合多环境切换。
项目级指令放在根目录的AGENTS.md，Pi 启动时会自动加载。加载顺序是全局~/.pi/agent/AGENTS.md、父目录和当前目录的AGENTS.md或CLAUDE.md，后者覆盖前者。一个最小示例：
# Project Instructions - 改完代码后运行 `npm run check`。 - 不要在本地跑生产迁移。 - 回复保持简洁。改完配置后运行/reload或重启 pi 生效。到这里，安装和配置就齐了。
4. 验证请求：跑通第一个终端编码任务
配置写好了，接下来验证整条链路。先确认 llama.cpp 路由器在跑，再启动 Pi。
第一步，检查路由器状态：
curl -s http://127.0.0.1:8080/v1/models | head -c 500如果返回模型列表 JSON，说明路由器正常。如果连接被拒，回到上一节检查 llama-server 是否启动、端口是否被占用。
第二步，启动 Pi 并加载本地模型。在项目目录运行pi，然后输入：
/llama在列表里选一个未加载的模型，回车加载。加载完成后运行/model，选择刚加载的模型。只有已加载的模型才会出现在/model选择器里，这是很多人第一次用会卡住的地方。
第三步，跑一个真实的编码任务。假设你有一个utils.js，里面有个函数写错了，直接让 Pi 改：
@utils.js 这个文件里的 parseDate 函数在输入空字符串时会抛异常，帮我改成返回 null，并补一个单元测试。Pi 会读取文件、定位函数、生成修改、写入文件，然后可能运行测试命令。你会在消息区看到工具调用和结果。如果一切正常，utils.js被修改，测试文件被创建。
第四步，用非交互模式验证 CLI 链路：
pi -p "总结这个仓库的主要模块" @README.md-p是打印模式，执行完直接退出，适合脚本集成。管道输入也支持：
cat src/app.ts | pi -p "找出这个文件里可能的空指针问题"如果这两条命令都能返回合理结果，说明 Pi Agent 的 CLI 与模型链路完全打通。本地模型响应会慢一些，但整个链路不依赖外部网络，调试体验很踏实。
再验证一下会话管理。运行/tree可以看到当前会话的树状结构，用方向键导航，回车选择某个历史节点继续。/fork从某条用户消息创建新会话，/clone复制当前分支。这三个命令的区别在于：/tree就地探索，/fork从早期提示开新会话，/clone复制当前工作后继续。长任务里用它们回退和分叉，比线性对话灵活得多。
5. 常见报错排查：401、local proxy failed、reading choices
这一节按真实报错来。你在配置 Pi Agent 加 llama.cpp 的过程中，大概率会碰到下面几个。
401 Unauthorized。如果你走 TaoToken 云端，检查ANTHROPIC_API_KEY或OPENAI_API_KEY是否设置正确，Base URL 是否写成https://taotoken.net/api。注意不要带末尾斜杠，也不要在 Key 前后留空格。如果走本地 llama.cpp，401 通常是因为你在启动 llama-server 时设了--api-key，但 Pi 的/login llama.cpp里没填对应的 key。两边要么都不设，要么设成一样。
local proxy failed / connection refused。这个报错说明 Pi 连不上http://127.0.0.1:8080。先确认 llama-server 进程还在，用curl http://127.0.0.1:8080/v1/models测一下。如果 curl 通但 Pi 不通，检查 Pi 的 auth.json 里 llama.cpp 的 URL 是不是写成了localhost而系统解析有问题，改成127.0.0.1更稳。另外确认没有其他程序占用 8080 端口。
reading choices / unexpected response format。这个报错通常出现在模型返回的 JSON 不符合 OpenAI 兼容格式时。本地模型尤其容易触发，原因是聊天模板不对。确保 llama-server 启动时带了--jinja，并且你加载的模型本身支持工具调用。如果模型不支持 function calling，Pi 的工具调用会失败。换一个支持工具调用的模型，比如 Qwen2.5-Coder 系列或 Llama 3.2 的 instruct 版本。
OAuth 相关报错。如果你用/login走订阅认证，报错通常是令牌过期或回调失败。令牌存在~/.pi/agent/auth.json，过期会自动刷新。如果刷新失败，运行/logout再/login重新走一遍。注意订阅认证和 API Key 认证是两套体系，不要混用。
模型加载后 /model 里看不到。回到/llama确认模型状态是 loaded。--no-models-autoload模式下，模型不会自动加载，必须手动选一次。加载过程中按 Escape 会取消，取消后模型不会出现在/model里。
上下文超限报错。长对话触发压缩失败时，检查compaction配置。reserveTokens默认 16384，keepRecentTokens默认 20000。如果你的模型上下文窗口本身小于这两个值之和，压缩会异常。把-c参数调大，或者降低keepRecentTokens。
排查时记住一个原则：先确认 llama-server 本身能用 curl 访问，再确认 Pi 的认证配置，最后看模型是否支持工具调用。三层分开查，比一股脑改配置快得多。
6. 把 Pi Agent 用进日常：模型切换与 Coding Plan
链路跑通之后，日常使用有几个提效点。
模型切换用 Ctrl+L 打开选择器，Ctrl+P 循环下一个，Shift+Ctrl+P 循环上一个。enabledModels里配好通配符，循环时只出现你关心的模型。思考级别用 Shift+Tab 循环，从 off 到 max 共七档。简单任务用 low，复杂重构用 high，能省不少 token。
本地模型和云端模型混用时，建议把本地模型用于快速迭代和隐私敏感代码，云端模型用于复杂推理。Pi 的会话是树状的，你可以在同一个会话里切换模型，不同分支用不同模型，对比效果很直观。
如果你需要长期跑编码任务或 Agent 工作流，可以了解一下 Coding Plan，它适合需要稳定额度和更高调用频率的场景。模型对话入口可以用来单独验证某个模型是否可用，接入文档里有各协议的详细说明。API Keys 页面管理你的凭证。
最后说一个实用技巧：把常用任务写成AGENTS.md里的指令，Pi 每次启动自动加载，不用重复交代。比如“改完代码跑 lint”“提交信息用中文”“不要动 migrations 目录”。这些约束写一次，后面所有会话都生效。配合/tree的分支摘要功能，长任务里回退到某个节点时，Pi 会自动摘要被放弃的分支，把关键决策和进度带回来，不会丢上下文。
终端编码代理的价值在于把 AI 能力变成你工作流里可组合的一环。Pi Agent 的极简设计让这件事变得可控，llama.cpp 的本地推理让链路完全透明。从安装到跑通第一个任务，上面这些步骤走一遍，你就有了一套属于自己的终端编码环境。
