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_URLhttps://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:8080API 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.cppdefaultModel填你在/llama里加载的模型名。enabledModels控制 CtrlP 循环切换时出现哪些模型支持通配符。认证文件在~/.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.mdPi 启动时会自动加载。加载顺序是全局~/.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.cpp401 通常是因为你在启动 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 callingPi 的工具调用会失败。换一个支持工具调用的模型比如 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默认 16384keepRecentTokens默认 20000。如果你的模型上下文窗口本身小于这两个值之和压缩会异常。把-c参数调大或者降低keepRecentTokens。排查时记住一个原则先确认 llama-server 本身能用 curl 访问再确认 Pi 的认证配置最后看模型是否支持工具调用。三层分开查比一股脑改配置快得多。6. 把 Pi Agent 用进日常模型切换与 Coding Plan链路跑通之后日常使用有几个提效点。模型切换用 CtrlL 打开选择器CtrlP 循环下一个ShiftCtrlP 循环上一个。enabledModels里配好通配符循环时只出现你关心的模型。思考级别用 ShiftTab 循环从 off 到 max 共七档。简单任务用 low复杂重构用 high能省不少 token。本地模型和云端模型混用时建议把本地模型用于快速迭代和隐私敏感代码云端模型用于复杂推理。Pi 的会话是树状的你可以在同一个会话里切换模型不同分支用不同模型对比效果很直观。如果你需要长期跑编码任务或 Agent 工作流可以了解一下 Coding Plan它适合需要稳定额度和更高调用频率的场景。模型对话入口可以用来单独验证某个模型是否可用接入文档里有各协议的详细说明。API Keys 页面管理你的凭证。最后说一个实用技巧把常用任务写成AGENTS.md里的指令Pi 每次启动自动加载不用重复交代。比如“改完代码跑 lint”“提交信息用中文”“不要动 migrations 目录”。这些约束写一次后面所有会话都生效。配合/tree的分支摘要功能长任务里回退到某个节点时Pi 会自动摘要被放弃的分支把关键决策和进度带回来不会丢上下文。终端编码代理的价值在于把 AI 能力变成你工作流里可组合的一环。Pi Agent 的极简设计让这件事变得可控llama.cpp 的本地推理让链路完全透明。从安装到跑通第一个任务上面这些步骤走一遍你就有了一套属于自己的终端编码环境。 
长河君 · 2026/10/3 0:23:15 · 阅读 1.2k 极简编程智能体 Pi Agent 入门指南：用 CLI 与 llama.cpp 搭建终端编码代理
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_URLhttps://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:8080API 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.cppdefaultModel填你在/llama里加载的模型名。enabledModels控制 CtrlP 循环切换时出现哪些模型支持通配符。认证文件在~/.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.mdPi 启动时会自动加载。加载顺序是全局~/.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.cpp401 通常是因为你在启动 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 callingPi 的工具调用会失败。换一个支持工具调用的模型比如 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默认 16384keepRecentTokens默认 20000。如果你的模型上下文窗口本身小于这两个值之和压缩会异常。把-c参数调大或者降低keepRecentTokens。排查时记住一个原则先确认 llama-server 本身能用 curl 访问再确认 Pi 的认证配置最后看模型是否支持工具调用。三层分开查比一股脑改配置快得多。6. 把 Pi Agent 用进日常模型切换与 Coding Plan链路跑通之后日常使用有几个提效点。模型切换用 CtrlL 打开选择器CtrlP 循环下一个ShiftCtrlP 循环上一个。enabledModels里配好通配符循环时只出现你关心的模型。思考级别用 ShiftTab 循环从 off 到 max 共七档。简单任务用 low复杂重构用 high能省不少 token。本地模型和云端模型混用时建议把本地模型用于快速迭代和隐私敏感代码云端模型用于复杂推理。Pi 的会话是树状的你可以在同一个会话里切换模型不同分支用不同模型对比效果很直观。如果你需要长期跑编码任务或 Agent 工作流可以了解一下 Coding Plan它适合需要稳定额度和更高调用频率的场景。模型对话入口可以用来单独验证某个模型是否可用接入文档里有各协议的详细说明。API Keys 页面管理你的凭证。最后说一个实用技巧把常用任务写成AGENTS.md里的指令Pi 每次启动自动加载不用重复交代。比如“改完代码跑 lint”“提交信息用中文”“不要动 migrations 目录”。这些约束写一次后面所有会话都生效。配合/tree的分支摘要功能长任务里回退到某个节点时Pi 会自动摘要被放弃的分支把关键决策和进度带回来不会丢上下文。终端编码代理的价值在于把 AI 能力变成你工作流里可组合的一环。Pi Agent 的极简设计让这件事变得可控llama.cpp 的本地推理让链路完全透明。从安装到跑通第一个任务上面这些步骤走一遍你就有了一套属于自己的终端编码环境。