1. 为什么先做环境准备：OpenCode 与 Pi Coding Agent 目录式学习路径的起点
如果你最近在搜 OpenCode 教程、Pi Coding Agent 怎么跑第一个示例，大概率会看到一堆“先装这个、再配那个”的碎片文章。我自己的习惯是：在写第一行业务代码之前，先把环境变量、配置文件、验证命令三件事固定下来。因为 Agent 类项目跟普通前端项目不一样，它要同时跟模型服务、本地文件系统、终端命令打交道，任何一环没对齐，后面章节的示例都会“看起来能跑，实际报错”。
这篇是目录式学习路径的第 00 篇，目标很明确：让你在 30 分钟内得到一个可复现的起点。所谓可复现，指的是你关掉终端、重启电脑、换一个项目目录，只要把配置文件复制过去，OpenCode 和 Pi Coding Agent 的行为是一致的。很多教程跳过这一步，直接让你复制一段代码跑，结果你跑通了但不知道为什么通，下一章换个模型就崩。
我会把环境准备拆成三层：系统层（Node、包管理器、终端）、凭证层（统一 Key 怎么放、放哪里）、项目层（目录结构、配置文件、忽略规则）。三层都验证过之后，你再去跑第一个 Agent 示例，报错信息会少一大半。这里先给一个整体判断：如果你只是想在浏览器里跟模型聊两句，不需要这么麻烦；但你要做的是“能改文件、搜代码、跑命令”的编码 Agent，那环境准备就是必答题，不是选择题。
另外提醒一句，环境准备阶段最容易踩的坑不是技术难度，而是“凭证散落”。有人把 Key 写在代码里，有人写在 shell 的 export 里，有人写在.env里但忘了加.gitignore。后面章节一旦涉及多模型切换、多项目并行，这些散落的 Key 就会变成排查噩梦。所以这篇的核心动作只有一个：把模型访问凭证收敛到一个统一入口，项目里只留引用，不留明文。
2. TaoToken 前置：统一 Key 接入前的账号与凭证准备
在讲具体配置之前，先把“统一 Key”这件事说清楚。你可以把 TaoToken 理解成一个模型访问的聚合入口：你不需要为每个模型厂商单独注册、单独充值、单独记一套 Key，而是用一套凭证去访问多个模型。对于跟着目录学 Agent 的开发者来说，这能省掉大量“注册—实名—充值—找文档”的重复劳动，把时间留给代码本身。
前置准备分三步。第一步，打开官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 注册账号。注册过程跟普通开发者平台一样，邮箱加密码，完成验证即可。第二步，进入控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，登录后在 API Keys 页面点创建，复制生成的 Key。这个 Key 只显示一次，建议先粘贴到一个临时文本里，马上要用。第三步，确认你要用的模型 ID。不同章节可能会切换模型，所以你需要知道模型对话页面在哪里查：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite ，这里能看到当前可用的模型列表和对应的调用名称。
这里有个细节值得展开：为什么强调“统一 Key”而不是“每个模型一个 Key”。因为 Agent 项目在调试阶段会频繁切换模型——今天用便宜的快模型跑循环，明天用强模型做代码编辑。如果每个模型一套凭证，你的配置文件里就会堆满XXX_API_KEY、YYY_API_KEY，代码里还要写分支判断用哪个。统一 Key 之后，切换模型只需要改一个model字段，Base URL 和 Key 都不动。这对后面第 4 章“Provider 模式”和第 18 章“评测”尤其重要，因为评测要跑多组模型对比，凭证统一能让你少写一半胶水代码。
还有一点，凭证安全。无论你用哪种方式存 Key，都不要提交到 Git。后面第 3 节的配置文件里我会用环境变量引用的方式，项目里只出现变量名，不出现明文。如果你现在还没有 Git 仓库，也建议先养成这个习惯，因为 Agent 项目经常会读写文件，一旦 Key 被写进某个被 Agent 修改的文件里，再提交上去就麻烦了。
3. 可复制配置：环境变量与项目配置文件片段
这一节是全文最需要你动手的部分。我会给出三份可直接复制的配置：一份 shell 环境变量、一份项目级.env、一份 Agent 运行配置。三份配合使用，路径和字段名保持一致，你照着改就能用。
先看 shell 环境变量。Mac 或 Linux 用户编辑~/.zshrc或~/.bashrc，Windows 用户在 PowerShell 里执行notepad $PROFILE编辑配置文件。加入以下内容：
# TaoToken 统一接入凭证 export TAOTOKEN_API_KEY="sk-你的Key粘贴在这里" export TAOTOKEN_BASE_URL="https://taotoken.net/api" export TAOTOKEN_MODEL_ID="你的默认模型ID"保存后执行source ~/.zshrc（或对应文件）让配置生效。Windows 用户保存后重开一个 PowerShell 窗口。验证方式是echo $TAOTOKEN_API_KEY，能打印出你的 Key 就说明生效了。注意 Base URL 这里用的是https://taotoken.net/api，不带任何查询参数，这是 API 调用的标准入口。
接下来是项目级配置。在你的项目根目录创建.env文件，内容如下：
# 项目级配置，引用系统环境变量，避免明文 TAOTOKEN_API_KEY=${TAOTOKEN_API_KEY} TAOTOKEN_BASE_URL=${TAOTOKEN_BASE_URL} TAOTOKEN_MODEL_ID=${TAOTOKEN_MODEL_ID}然后创建.gitignore，至少包含这几行：
.env .env.local node_modules/ *.log再创建 Agent 运行配置agent.config.json，这份配置后面章节会反复用到：
{ "provider": { "name": "taotoken", "baseUrl": "https://taotoken.net/api", "apiKeyEnv": "TAOTOKEN_API_KEY", "modelId": "你的默认模型ID" }, "agent": { "maxTurns": 10, "workDir": "./workspace", "allowShell": false }, "tools": { "readFile": true, "writeFile": true, "grep": true, "bash": false } }这份 JSON 里有三个字段需要你注意。apiKeyEnv写的是环境变量名，不是 Key 本身，这样配置文件可以安全提交。workDir是 Agent 的工作目录，建议单独建一个workspace文件夹，避免 Agent 误改你的源码。allowShell和tools.bash默认关闭，等第 11 章讲命令执行时再打开，现在保持关闭更安全。
如果你用的是 OpenCode 或 Cline 这类工具，配置方式类似，核心三件套是 Base URL、API Key、Model ID。以 Cline 的 MCP 配置为例，在设置里填入：
{ "mcpServers": { "taotoken": { "url": "https://taotoken.net/api", "env": { "TAOTOKEN_API_KEY": "从环境变量读取" } } } }Codex 用户如果用到auth.json，结构如下：
{ "baseUrl": "https://taotoken.net/api", "apiKey": "从环境变量读取", "model": "你的默认模型ID" }三件套缺一不可：Base URL 决定请求发到哪里，API Key 决定身份，Model ID 决定用哪个模型。任何一项写错，后面都会报错，第 5 节会逐个对照。
4. 逐项验证：从环境变量到首个成功请求
配置写完不等于能用，必须逐项验证。我习惯按“环境变量 → 网络连通 → 模型响应 → 项目配置加载”的顺序来，每一步都有明确的成功标志。
第一步，验证环境变量。在终端执行：
echo $TAOTOKEN_API_KEY echo $TAOTOKEN_BASE_URL echo $TAOTOKEN_MODEL_ID三条命令都应该有输出，且 Base URL 应该是https://taotoken.net/api。如果某一条为空，说明 shell 配置没生效，回到第 3 节检查。
第二步，验证网络连通。用 curl 发一个最小请求：
curl -s -o /dev/null -w "%{http_code}" \ -X POST "https://taotoken.net/api/v1/chat/completions" \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"'"$TAOTOKEN_MODEL_ID"'","messages":[{"role":"user","content":"ping"}]}'如果返回200，说明凭证和网络都没问题。如果返回401，说明 Key 不对或没带上；返回404，多半是 Base URL 或路径写错。这一步不要跳过，因为后面 Agent 循环里的报错往往被包装过，直接看 curl 的原始状态码最快。
第三步，验证模型响应内容。把上面的-o /dev/null去掉，看返回的 JSON：
curl -s \ -X POST "https://taotoken.net/api/v1/chat/completions" \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"'"$TAOTOKEN_MODEL_ID"'","messages":[{"role":"user","content":"用一句话说明你是什么模型"}]}'成功的话你会看到choices数组里有message.content。如果choices为空，检查 Model ID 是否拼写正确。这一步验证通过，说明你的统一 Key 接入已经跑通，后面章节可以直接复用。
第四步，验证项目配置加载。写一个最小的 Node 脚本check-env.mjs：
import fs from 'node:fs'; const config = JSON.parse(fs.readFileSync('./agent.config.json', 'utf8')); const apiKey = process.env[config.provider.apiKeyEnv]; console.log('Base URL:', config.provider.baseUrl); console.log('Model ID:', config.provider.modelId); console.log('API Key 已加载:', Boolean(apiKey)); console.log('工作目录:', config.agent.workDir);执行node check-env.mjs，四项都应该正常输出，API Key 显示true。如果显示false，说明环境变量没被 Node 进程读到，检查你的 shell 配置是否对当前终端生效。
四步都通过之后，你的环境就达到了“可复现”标准。建议把这四步写成一个verify.sh脚本，每次换机器或换项目目录先跑一遍。这个习惯在后面的多章节学习中会帮你省下大量排查时间。
5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth
环境准备阶段会遇到的报错其实就那么几类，我把最常见的四个列出来，对照着排查。
第一个，401 Unauthorized。这是最高频的报错，原因通常有三个：Key 没带上、Key 写错、Key 对应的环境变量没生效。排查顺序是先用echo $TAOTOKEN_API_KEY确认变量有值，再用 curl 直接测，如果 curl 也 401，那就是 Key 本身的问题，去控制台重新生成一个。注意不要用Bearer后面带空格或换行，复制时容易带上不可见字符。
第二个，local proxy failed或类似的连接失败提示。这类报错通常出现在工具类客户端里，原因是客户端配置的 Base URL 和实际请求路径不匹配。比如你在 Cline 里填了https://taotoken.net/api，但客户端自动拼接了/v1/chat/completions，实际请求就变成了https://taotoken.net/api/v1/chat/completions，这是正确的。如果你填的是带/v1的地址，就会变成/v1/v1/...，导致失败。记住一个原则：Base URL 只填到/api，路径由客户端或代码拼接。
第三个，reading choices或cannot read property choices of undefined。这个报错说明请求发出去了，但返回的 JSON 结构里没有choices字段。常见原因是 Model ID 写错，服务端返回了一个错误对象而不是正常的补全结果。排查方法是把 curl 的完整返回打印出来，看error字段的内容。另一个原因是请求体格式不对，比如messages不是数组，或者model字段缺失。
第四个，OAuth相关报错。如果你用的是 Claude Code 或类似工具，它可能默认走 OAuth 登录流程，而不是 API Key。这时候你需要在配置里显式指定使用 API Key 模式，把 Base URL 和 Key 填进去。以 Claude Code 为例，配置里要写全三件套：Base URL 填https://taotoken.net/api，API Key 从环境变量读取，Model ID 填你控制台里看到的模型名称。三件套缺任何一个，工具都可能回退到 OAuth 流程，然后报错。
除了这四个，还有一个隐蔽的坑：.env文件被提交到了 Git。如果你在验证过程中发现 Key 泄露，第一时间去控制台吊销旧 Key 并生成新的。这也是为什么第 3 节强调.gitignore要先建好。
排查的时候有个通用技巧：把报错信息里的关键词直接拿去搜，但要注意区分“客户端报错”和“服务端报错”。客户端报错通常是配置问题，服务端报错通常是凭证或模型问题。curl 能帮你快速定位是哪一类。
6. 下一步：从环境准备到第一个 Agent 示例
环境准备做完，你应该已经拥有了：一套统一的环境变量、一份可提交的项目配置、一个验证脚本、以及四个常见报错的排查思路。这些是后面所有章节的地基。下一章我们会在这个地基上跑通第一个 Agent 示例：让模型读取一个本地文件，修改其中一行，然后写回。到那时你会发现，今天花在配置上的时间，会在调试循环时加倍还给你。
如果你在验证过程中卡住了，优先回到第 4 节的四步验证，从环境变量开始逐项确认。需要重新生成 Key 或查看模型列表，可以去 API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 和接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 对照。如果你打算长期跟着这个目录学下去，并且会频繁跑 Agent 循环和评测，可以了解一下 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite ，它在多模型切换和长会话场景下会更省心。环境就绪之后，打开终端，我们下一章见。
