1. Pi Agent 是什么为什么值得折腾Pi Agent 是一个极简底座的通用 AI Agent核心能力只有四个读文件、写文件、改文件、跑命令。它不预装任何花哨功能所有扩展能力都靠按需安装 Skill 来实现。你装什么 Skill它就会什么——搜资料、读 PDF、整理表格、做 PPT甚至生成图片素材全看你给它配了什么。它适合谁适合那些每天有一堆杂事要处理、但不一定天天写代码的人。比如你要从一堆 PDF 里提取数据整理成表格或者根据一段描述生成一份汇报 PPT又或者批量处理本地文件Pi Agent 都能通过 Skill 扩展来完成。它的设计哲学是「让 Pi 适应你的工作流而不是反过来」所以底座极简扩展灵活。和 Claude Code 的区别也很明显Claude Code 预装了代码索引、测试运行、Git 操作等一整套开发工具目标是写代码、交付软件Pi Agent 只保留最基础的四个能力通过 Skill 按需安装来扩展目标是完成日常工作任务。一句话总结Claude Code 解决开发效率Pi 解决工作流效率。我试过用 Pi Agent 做资料整理和 PPT 生成实测下来它的 token 消耗比预想中低不少。同样规模的任务Pi 的 token 消耗大概只有 Claude Code 的三分之一甚至更少但总消耗量却能排进 OpenRouter 排行榜前六。这说明有大量用户正在高频次地使用它来完成日常工作。要跑通 Pi Agent 的自动化工作流你需要准备三样东西Node.js 20 环境、一个可用的模型 API Key、一个项目目录。模型 API Key 这块你可以用 TaoToken 统一管理后面会详细讲怎么接入。项目目录推荐在项目根目录启动 Pi它会自动读取本地文件这样 Skill 就能直接操作你当前项目的文件了。Pi Agent 的安装路径和配置都在~/.pi/agent/目录下所有会话记录、Skill 包、配置文件都放在这里。这个设计的好处是你换项目目录时Pi 的配置和 Skill 不会丢直接跟着用户走。接下来我会从环境准备开始一步步带你跑通整个流程。2. 环境准备与 TaoToken 统一 Key 接入在开始安装 Pi Agent 之前先确认你的环境满足条件。Node.js 版本需要 20 以上推荐用最新 LTS 版本。你可以在终端运行node -v检查当前版本如果低于 20去 Node.js 官网下载最新 LTS 安装包覆盖安装即可。Windows 用户建议用 Windows Terminal后面有些快捷键在默认终端里可能不生效。模型 API Key 这块我推荐用 TaoToken 统一管理。TaoToken 是一个 API 通道聚合平台你可以把不同模型服务商的 Key 集中放在这里Pi Agent 只需要配置一个 Base URL 和 Key 就能调用多个模型。这样你切换模型时不用改 Pi 的配置直接在 TaoToken 后台切换就行。TaoToken 的官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。注册后进入控制台在 API Keys 页面创建一个新的 Key复制保存好后面配置 Pi Agent 时要用。Pi Agent 的模型配置支持自定义 Base URL所以你可以把 TaoToken 的 API 地址填进去。具体配置方式是在 Pi 的配置文件里指定 provider 为自定义然后填入 Base URL 和 API Key。配置文件路径在~/.pi/agent/config.json你可以直接编辑这个文件也可以用 Pi 的/settings命令在交互界面里配置。如果你用的是 Claude Code 或者 Cline 这类工具TaoToken 的接入方式也类似Base URL 填https://taotoken.net/apiAPI Key 填你在 TaoToken 控制台创建的 KeyModel ID 填你要用的模型名称。比如你想用 DeepSeekModel ID 就填deepseek-chat想用 Claude就填对应的模型 ID。TaoToken 的接入文档里有完整的模型列表和对应的 Model ID你可以去 https://taotoken.net/doc 查看。配置完成后你可以在 Pi Agent 里用/model命令切换模型或者按 CtrlP 打开模型选择面板。按 ShiftTab 可以切换思考强度这个功能在需要深度推理的任务里很有用。TaoToken 的好处是你只需要管理一个 Key不用在每个工具里分别配置不同服务商的 Key省去了很多麻烦。3. 可复制配置Pi Agent 安装与 Skill 配置Pi Agent 的安装很简单在终端运行一行命令curl -fsSL https://pi.dev/install.sh | sh安装完成后所有配置、会话记录和 Skill 包都在~/.pi/agent/目录下。你可以用ls ~/.pi/agent/查看目录结构里面会有config.json、sessions/、skills/等文件夹。接下来配置模型接入。编辑~/.pi/agent/config.json填入 TaoToken 的 Base URL 和 API Key{ provider: custom, baseUrl: https://taotoken.net/api, apiKey: 你的TaoToken API Key, model: deepseek-chat, thinkingLevel: medium }如果你不想手动编辑 JSON也可以在 Pi 启动后用/settings命令进入配置界面选择 provider 为 custom然后填入 Base URL 和 API Key。配置完成后用/model命令选择模型TaoToken 支持的模型都会列出来。Skill 的安装方式有两种一种是通过pi install命令从 Git 仓库安装另一种是手动把 Skill 文件放到~/.pi/agent/skills/目录下。以安装 PPT Skill 为例pi install git:github.com/op7418/guizang-ppt-skill安装完成后运行/reload重新加载 Skill。如果 Skill 没有生效检查~/.pi/agent/skills/目录下是否有对应的 Skill 文件。每个 Skill 通常包含一个skill.json配置文件和相关的脚本文件你可以打开skill.json查看这个 Skill 支持哪些命令和参数。如果你要自己写一个 Skill结构也很简单。在~/.pi/agent/skills/下新建一个文件夹比如my-skill/里面放一个skill.json{ name: my-skill, description: 我的自定义 Skill, commands: [ { name: hello, description: 输出问候语, script: hello.sh } ] }然后在同目录下创建hello.sh写入你要执行的命令。这样 Pi Agent 就能通过hello命令调用你的脚本了。Skill 的本质就是把常用操作封装成命令Pi 负责理解你的自然语言指令然后调用对应的 Skill 来执行。4. 验证请求与成功结果配置完成后在项目目录下启动 Pipi首次启动会提示你登录。输入/login选择 provider。如果你用的是 TaoToken 统一 Key选择 custom provider然后填入你的 TaoToken API Key。登录成功后你会看到 Pi 的交互界面。验证模型是否配置成功输入/model查看当前模型。如果显示的是你配置的模型名称说明接入成功。你可以直接问一个简单问题测试你好请用一句话介绍你自己如果 Pi 正常回复说明模型调用链路已经通了。接下来测试 Skill 是否生效。以 PPT Skill 为例输入帮我制作一张介绍南京风景的 PPTPi 会先分析需求并列出大纲你需要确认风格和主题色然后它开始生成。生成过程中你可以看到 Pi 调用了 PPT Skill 的相关命令。最终生成的 PPT 文件会保存在当前项目目录下你可以用ls查看生成的文件。如果 Skill 没有生效运行/reload重新加载。如果还是不行检查~/.pi/agent/skills/目录下是否有对应的 Skill 文件以及skill.json里的命令配置是否正确。你也可以用/session命令查看当前会话的 token 数和费用确认模型调用是否正常计费。验证自动化工作流是否跑通可以做一个简单的文件处理任务。比如在项目目录下创建一个test.txt然后让 Pi 读取并统计字数读取 test.txt统计有多少个字Pi 会调用读文件能力然后返回统计结果。如果这个流程能跑通说明你的 Pi Agent 已经具备了基本的文件操作和模型调用能力接下来就可以安装更多 Skill 来扩展功能了。5. 常见报错排查401 Unauthorized这是最常见的报错通常是 API Key 配置错误。检查~/.pi/agent/config.json里的apiKey是否和 TaoToken 控制台创建的一致。注意不要有多余的空格或换行。如果你用的是环境变量确认环境变量名和配置文件里引用的一致。local proxy failed这个报错通常出现在网络请求环节。检查你的 Base URL 是否填写正确TaoToken 的 API 地址是https://taotoken.net/api不要漏掉/api路径。如果你在公司内网确认网络策略是否允许访问外部 API。reading choices 报错这个报错说明模型返回的数据格式和 Pi 预期的格式不匹配。通常是因为 Model ID 填错了比如把deepseek-chat写成了deepseek。去 TaoToken 的接入文档确认正确的 Model ID然后更新配置文件。OAuth 授权失败如果你选择的是订阅登录方式OAuth 授权可能会因为浏览器缓存或网络问题失败。建议改用 API Key 方式登录在 TaoToken 控制台创建 Key然后在 Pi 里选择 custom provider 填入 Key。API Key 方式更稳定也方便管理。Skill 安装后不生效确认安装路径正确然后运行/reload重新加载。如果仍不生效检查~/.pi/agent/skills/目录下是否有对应的 Skill 文件。有些 Skill 需要额外的依赖比如 Python 环境或特定的命令行工具查看 Skill 的 README 确认依赖是否安装。模型切换后报错如果你在 TaoToken 后台切换了模型但 Pi 里还是旧的 Model ID会报模型不存在的错误。运行/model重新选择模型或者手动更新config.json里的model字段。TaoToken 支持多个模型你可以在控制台查看当前可用的模型列表。token 消耗异常如果发现 token 消耗比预期高很多检查/session里的 token 统计。可能是上下文压缩没有生效运行/compact手动压缩上下文。另外思考强度设置过高也会增加 token 消耗用 ShiftTab 调整到合适的级别。6. 长期使用与 CTAPi Agent 的日常使用有几个技巧可以提升效率。文件引用用加模糊搜索路径补全按 Tab 键多行输入用 ShiftEnter。执行 Shell 命令用!command输出会发送给模型如果不想让模型看到输出用!!command。外部编辑器用 CtrlG 打开$VISUAL或$EDITOR环境变量指定的编辑器。常用斜杠命令里/resume可以从之前的会话继续/new开启新会话/tree跳转到会话树的任意节点/fork从某条用户消息创建新会话。/compact手动压缩上下文可以附带自定义指令。/export将会话导出为 HTML方便存档和分享。如果你需要长期跑编码任务或者搭建 Agent 工作流可以考虑 TaoToken 的 Coding Plan。它提供了更稳定的 API 通道和更高的调用配额适合高频次使用的场景。具体可以看 https://taotoken.net/coding-plan 。验证模型效果的话可以直接在 TaoToken 的模型对话页面测试 https://taotoken.net/chat 。API Keys 管理在 https://taotoken.net/api-keys 接入文档在 https://taotoken.net/doc 。Claude Code 的接入配置可以参考 https://taotoken.net/claudecode 。Pi Agent 的核心理念是「让 Pi 适应你的工作流」所以不要一开始就装一堆 Skill。先跑通基础流程然后根据实际需求逐个安装 Skill。每装一个 Skill就测试一下是否生效确认没问题再装下一个。这样你的 Pi Agent 会越来越贴合你的工作习惯最终变成一个真正属于你自己的 Agent。