1. 为什么 AI Agent 开发第一步总是卡在环境上AI Agent 开发听起来很酷但真正动手时八成的人会在第一步就卡住Python 版本不对、Node.js 装成了 Current 版、Claude Code 装完启动报错、settings 配置文件不知道往哪改。我见过太多人在这几个环节反复折腾一整天最后连一个能跑的最小 Agent 都没搭起来。这篇是 AI Agent 开发实战系列的第一篇目标很明确把 Python、Node.js、Docker、Git 这套基础运行时装好再装上 Claude Code然后把 Claude Code 的 settings 配置文件改到 TaoToken 统一 Key/API 通道最后跑通一次连通性验证。做完这些你输入claude就能在终端里启动一个能读代码、改文件、跑命令的 AI 工程师而且后续所有 Agent 调用都走同一条稳定的 API 通道。适合谁看第一次接触 Claude Code 的开发者、想系统学 AI Agent 但被环境劝退的人、以及已经装了 Claude Code 但不知道怎么把请求接到统一通道的人。整篇按“装完就能用”的思路写每一步都有可复制的命令和预期输出你照着敲就行。先建一个统一工作目录后面所有东西都放这里避免文件散落各处mkdir -p ~/ai-agent-lab cd ~/ai-agent-labWindows 用户用mkdir ai-agent-lab然后cd ai-agent-lab即可。这个目录后面会放虚拟环境、Claude Code 项目配置以及后续篇的 Agent 代码。环境版本要求先列清楚避免装错版本返工软件版本要求用途Python≥ 3.11推荐 3.13Agent 逻辑、LangGraph、MCP ServerNode.js≥ 20推荐 22 LTSClaude Code、部分 MCP 工具Docker最新稳定版容器化部署 Agent后续篇Git任意新版代码管理、拉取开源项目Claude Code最新版终端里的 AI 工程师版本这块有个坑要提前说Node.js 一定选 LTS 22不要选 Current。Current 版虽然版本号更高但很多 MCP 工具对引擎版本有严格校验装 Current 后面会报EBADENGINE错误到时候还得卸掉重装不如一开始就装对。2. 基础运行时安装Python 3.13 与 Node.js 22 的完整配置流程这一节把 Python、Node.js、Docker、Git 四个基础件装完每个都给出验证命令和预期输出。装完这四个Claude Code 才有运行的地基。2.1 安装 Python 3.13去 python.org 下载 3.13 安装包。Windows 安装时务必勾选Add python.exe to PATH这一步漏了后面命令行会提示“不是内部或外部命令”。Mac 用户直接用 Homebrewbrew install python3.13装完验证版本python --version # 预期输出Python 3.13.x接着建虚拟环境。虚拟环境的作用是把项目依赖和系统 Python 隔离开避免包污染。后续每一篇的 Agent 代码都复用这个虚拟环境python -m venv .venv # Windows 激活 .venv\Scripts\activate # Mac/Linux 激活 source .venv/bin/activate激活成功后命令行前面会出现(.venv)前缀。这个前缀很重要它告诉你当前 pip 装包是装进虚拟环境而不是系统 Python。如果激活后没看到这个前缀说明激活没成功后面pip install会装错地方。2.2 安装 Node.js 22 LTS去 nodejs.org 下载 LTS 22注意选 LTS 而不是 Current。Mac 用brew install node22验证node --version # 预期输出v22.x.x npm --version # 预期输出10.x.x 或更高Node.js 是 Claude Code 的运行基础因为 Claude Code 本身是通过 npm 全局安装的。npm 是 Node 的包管理器装 Node 时会一起装上。2.3 安装 Docker去 docker.com 下载 Docker Desktop安装后启动任务栏出现小鲸鱼图标且状态为 running 才算启动成功。验证docker --version # 预期输出Docker version 27.x.x docker run hello-world # 预期输出Hello from Docker!docker run hello-world这条命令会拉取一个测试镜像并运行如果能看到Hello from Docker!说明 Docker 引擎工作正常。这一步在后续篇部署容器化 Agent 时会用到。2.4 安装 GitWindows 去 git-scm.com 下载安装时全部默认选项即可。Mac 一般自带 Git。验证git --version # 预期输出git version 2.x.x2.5 配置国内镜像加速这一步不是必须的但强烈推荐能省掉大量等待时间。pip 换清华源pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simpleDocker 换源打开 Docker Desktop → Settings → Docker Engine在 JSON 配置里加入镜像地址然后点 Apply Restart{ registry-mirrors: [https://docker.m.daocloud.io] }配完镜像源后pip install和docker pull的速度会有明显提升。如果docker run hello-world之前超时拉不下来配完这个镜像源再试通常就能成功。四个基础件装完跑一条组合命令确认全部就绪python --version node --version docker --version git --version四条版本号都正常输出说明基础环境这一层已经稳了。3. Claude Code 安装与 settings 改到 TaoToken 的可复制配置基础环境就绪后这一节装 Claude Code并把它的 settings 配置文件改到 TaoToken 统一 Key/API 通道。这是整篇最核心的一步配好之后后续所有 Agent 调用都走这条通道。3.1 全局安装 Claude Codenpm install -g anthropic-ai/claude-codeWindows 如果报权限红字用管理员身份打开 PowerShell 重跑这条命令。验证安装claude --version # 预期输出版本号如 1.0.283.2 获取 TaoToken API Key打开 TaoToken 控制台创建 API Key地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。创建后复制 Key格式类似sk-xxxx这个 Key 后面要填进 settings 配置文件。TaoToken 在这里的角色是统一 API 通道你不需要分别去各家模型厂商申请 Key用同一个 Key 就能调用不同模型。对 AI Agent 开发来说这意味着后续切换模型只需要改一个 Model ID不用重新配 Key。3.3 修改 settings 配置文件Claude Code 的配置文件在用户目录下的.claude/settings.json。Windows 路径是C:\Users\你的用户名\.claude\settings.jsonMac/Linux 是~/.claude/settings.json。如果文件不存在就新建一个。把下面这段配置复制进去注意把sk-你的TaoToken密钥替换成你实际创建的 Key{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }这三个字段是接入的三件套缺一不可字段作用填什么ANTHROPIC_BASE_URLAPI 请求地址https://taotoken.net/apiANTHROPIC_AUTH_TOKEN身份认证 Key你的 TaoToken KeyANTHROPIC_MODEL调用的模型 ID按需填如 claude-sonnet-4-20250514注意ANTHROPIC_BASE_URL填的是https://taotoken.net/api不要在后面加多余的路径。ANTHROPIC_AUTH_TOKEN填的是 TaoToken 创建的 Key不是 Anthropic 官方的 Key。如果你用的是项目级配置而不是全局配置也可以在项目根目录建.claude/settings.json格式完全一样。项目级配置只对当前项目生效全局配置对所有项目生效。刚开始建议用全局配置省得每个项目都配一遍。3.4 配置生效验证配置写完后重新打开一个终端让环境变量重新加载。然后启动 Claude Codecd ~/ai-agent-lab claude第一次启动如果之前登录过 Anthropic 官方账号可能会提示重新认证。因为我们已经在 settings 里配了ANTHROPIC_AUTH_TOKEN它会优先用这个 Key 走 TaoToken 通道。启动后进入输入提示符说明 Claude Code 已经跑起来了。这时候它发出的请求会走 TaoToken 的 API 通道而不是直连官方。4. 连通性验证从最小冒烟测试到成功结果确认配置写完不代表就能用必须跑一次连通性验证确认请求真的能通到 TaoToken 并拿到模型响应。这一节给出完整的验证动作和成功结果判断标准。4.1 最小冒烟测试在 Claude Code 的提示符后输入 列出当前目录下的文件它会调用命令把目录内容打出来。如果能看到ai-agent-lab目录下的文件列表说明安装、配置、请求链路全通了。再输入一句确认模型身份 你是谁能正常回应即达标。这一步验证的是模型真的在响应而不是只连上了 API 地址但模型调用失败。4.2 用 curl 直接验证 API 通道除了在 Claude Code 里测还可以用 curl 直接打 TaoToken 的 API确认 Key 和地址都没问题curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 100, messages: [{role: user, content: 回复 OK 两个字母}] }如果返回的 JSON 里content字段有内容说明 API 通道完全正常。如果返回 401说明 Key 填错了如果返回连接超时说明地址或网络有问题。4.3 成功结果判断标准跑完上面两步满足以下条件就算环境就绪第一claude --version能输出版本号。第二claude启动后进入提示符。第三输入“列出当前目录下的文件”能正常返回结果。第四curl 请求返回的 JSON 里有模型回复内容。最终目录结构应该是这样ai-agent-lab/ ├── .venv/ # Python 虚拟环境 └── .claude/ # Claude Code 项目配置自动生成.claude目录是 Claude Code 自动生成的里面会存项目级的配置和会话记录。.venv是 Python 虚拟环境后续装 LangGraph、MCP Server 都装在这里面。4.4 退出与重启退出 Claude Code 用/exit。下次要用直接cd ~/ai-agent-lab然后claude即可配置会一直保留。如果改了 settings.json 里的配置需要退出 Claude Code 重新启动才能生效因为它只在启动时读取配置。5. 本篇常见报错排查401、local proxy failed、EBADENGINE 对照解决环境搭建过程中最容易遇到几类报错这一节按真实报错信息对照给出解决方法。遇到报错先别慌对照下面的条目找。5.1 401 认证失败报错信息类似API Error: 401 Unauthorized原因通常是ANTHROPIC_AUTH_TOKEN填错了或者 Key 已经失效。排查步骤打开~/.claude/settings.json确认ANTHROPIC_AUTH_TOKEN字段的值是完整的 TaoToken Key没有多余空格。然后去 TaoToken 控制台确认这个 Key 还在有效期内。如果 Key 没问题但还是 401检查ANTHROPIC_BASE_URL是不是写成了https://taotoken.net/api/带了尾部斜杠去掉尾部斜杠再试。5.2 local proxy failed 连接失败报错信息类似Error: local proxy failed to connect这类报错通常是网络层的问题。先确认ANTHROPIC_BASE_URL填的是https://taotoken.net/api然后用 curl 直接测一下地址通不通curl -I https://taotoken.net/api如果 curl 也连不上说明本机网络到 TaoToken 的链路有问题检查一下网络设置。如果 curl 能通但 Claude Code 报错重启 Claude Code 让配置重新加载。5.3 reading choices 解析错误报错信息类似Error reading choices from response这个报错说明请求发出去了但返回的数据格式不符合预期。常见原因是ANTHROPIC_MODEL填了一个不存在的模型 ID。去 TaoToken 的模型列表确认一下你填的 Model ID 是否正确比如claude-sonnet-4-20250514这种格式大小写和连字符都要对。5.4 EBADENGINE 引擎版本不匹配报错信息类似npm ERR! code EBADENGINE npm ERR! engine Unsupported engine这是 Node.js 版本不对导致的。很多 MCP 工具要求 Node ≥ 20如果你装的是 Current 版或者版本太低就会报这个。解决方法是卸掉当前 Node重装 LTS 22node --version # 如果输出不是 v22.x.x去 nodejs.org 重装 LTS 225.5 OAuth 登录相关报错如果你之前用 Anthropic 官方账号登录过可能会遇到 OAuth 相关的报错比如提示 token 过期或认证方式冲突。因为我们已经在 settings 里配了ANTHROPIC_AUTH_TOKEN它会优先用这个 Key。如果还是报 OAuth 错误删掉~/.claude/下的认证缓存文件再重启 Claude Code。5.6 命令找不到不是内部或外部命令Windows 输入python或claude提示“不是内部或外部命令”说明 PATH 没生效。Python 重跑安装包勾选Add to PATHclaude 则跑npm bin -g找到全局目录把它加进系统 PATH然后重开终端。5.7 虚拟环境激活后 pip 装错地方激活虚拟环境后命令行前面没出现(.venv)说明激活没成功。重新激活然后用where pipWindows或which pipMac确认 pip 路径里包含.venv。如果路径里没有.venv说明装到了系统 Python需要重新激活再装。5.8 终端中文乱码Windows 老版 cmd 可能出现中文乱码。用 Windows Terminal 替代老 cmd或者执行chcp 65001切换到 UTF-8 编码。6. 环境就绪之后把 Claude Code 接入更多模型与后续实战到这里Python 3.13、Node.js 22、Docker、Git 四个基础件装好了Claude Code 装好了settings 配置文件也改到了 TaoToken 统一通道连通性验证也跑通了。你现在输入claude就能在终端里启动一个能读代码、改文件、跑命令的 AI 工程师。这套环境的价值在于它是后续所有 Agent 实战的地基。虚拟环境.venv后面会装 LangGraph、MCP Server 这些 Agent 框架Claude Code 的 settings 配置后面只需要改ANTHROPIC_MODEL字段就能切换不同模型TaoToken 的统一 Key 让你不用为每个模型单独申请凭证。如果你还没创建 TaoToken 的 Key去控制台创建一个https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。创建后填进 settings.json 的ANTHROPIC_AUTH_TOKEN字段即可。想先体验一下模型对话效果可以直接打开模型对话页面测试https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。在里面选一个模型发一句话确认 Key 和通道都正常再回到 Claude Code 里用。如果你打算长期做 Agent 开发频繁调用模型可以了解一下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它适合需要稳定、长期编码调用的场景比按次调用更划算。接入文档在这里遇到配置细节可以查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。下一篇是 AI Agent 开发实战02Claude Code 接入 DeepSeek。用 DeepSeek 当大脑、Claude Code 当双手把模型接入这一步彻底跑通。环境已经就绪下一篇直接改 settings 里的 Model ID 就能切换模型不用再折腾安装。