1. Claude Code 安装前必须搞清楚的几件事Claude Code 是 Anthropic 推出的终端 AI 编程助手它不是一个网页聊天窗口而是直接跑在你项目目录里的 CLI 工具。你可以把它理解成「住进你终端里的结对程序员」它能读你的文件、跑你的命令、改你的代码所有动作都在你本机完成模型推理走远端 API。适合谁适合每天在终端里敲 git、npm、pytest 的后端、全栈、运维同学也适合想把 AI 编码能力接进现有 IDE 工作流的开发者。很多人第一次装 Claude Code 会卡在三个地方一是 CLI 装完了但claude命令找不到二是 API Key 和 Base URL 没配对导致 401三是 IDE 里终端环境和系统终端不一致插件调不起来。这篇指南按「环境准备 → Key 获取 → CLI 安装 → 配置写入 → 终端验证 → IDE 集成 → 报错排查」的完整链路走一遍每一步都给可复制的命令和配置片段。我试过在 macOS、Windows PowerShell 7、Ubuntu 三种环境下各跑一遍下面把差异点都标出来。核心检索词先明确Claude Code 安装指南、CLI 环境准备、API Key 配置、Base URL 设置、IDE 集成。你如果是完全新手建议从第 2 节开始顺序读如果 CLI 已经装好只差 Key直接跳到第 3 节看 settings 配置。先给一个全局认知Claude Code 的配置分两层。一层是操作系统级的环境变量决定它连哪个 API 端点、用哪个 Key另一层是项目目录下的.claude/配置决定权限、命令、hooks。安装本身不复杂复杂的是「让 CLI 和 IDE 都读到同一套环境变量」。下面每一节都围绕这个目标展开。2. TaoToken 前置准备拿到统一 Key 和 Base URL在装 CLI 之前先把「通行证」准备好。Claude Code 默认连 Anthropic 官方端点但国内网络环境下直连经常超时而且官方 Key 的获取和计费对个人开发者不够友好。更稳的做法是用一个兼容 Anthropic 协议的统一接入层把 Base URL 和 Key 一次性配好CLI 和 IDE 共用同一套凭证后面换模型、换项目都不用重复改。TaoToken 就是干这个的它提供兼容 Anthropic Messages API 的端点你拿一个 Key配一个 Base URLClaude Code 就能正常发请求。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台创建 API Key。具体操作路径登录后进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 找到 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 点「创建 Key」复制出来。这个 Key 就是后面环境变量ANTHROPIC_API_KEY的值。Base URL 用https://taotoken.net/api注意这个地址不带任何查询参数直接填进ANTHROPIC_BASE_URL。这里有个关键点Claude Code 读的是ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL这两个环境变量。你只要把这两个值配对CLI 就会把请求发到 TaoToken 的端点而不是官方端点。模型 ID 方面Claude Code 内部用别名sonnet、opus、haiku映射TaoToken 侧兼容这些别名所以你不需要在 CLI 里手写完整模型名除非你要指定特定版本。如果你还想在浏览器里先验证一下 Key 能不能用可以打开模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 发一条消息确认返回正常再去配 CLI。这样能把「Key 本身有问题」和「CLI 配置有问题」两类故障分开排查时省很多时间。注意Key 只在创建时完整显示一次复制后存到密码管理器里。环境变量里不要带空格、不要带引号外的多余字符否则会报 401。3. 可复制配置settings 片段与 CLI 安装命令这一节是全文最核心的部分给你可以直接粘贴的配置。先装 CLI再写配置顺序不要反。3.1 CLI 安装三种方式选一macOS / Linux / WSL 用脚本安装最省事curl -fsSL https://claude.ai/install.sh | bashWindows PowerShell 7irm https://claude.ai/install.ps1 | iex如果你已经有 Node.js 18也可以用 npm 标准安装node --version npm install -g anthropic-ai/claude-code claude --version装完先别急着启动先把环境变量写对。macOS/Linux 编辑~/.zshrc或~/.bashrcexport ANTHROPIC_API_KEY你的TaoToken Key export ANTHROPIC_BASE_URLhttps://taotoken.net/api然后source ~/.zshrc让它生效。Windows PowerShell 7 永久写入用户环境变量[System.Environment]::SetEnvironmentVariable(ANTHROPIC_API_KEY, 你的TaoToken Key, User) [System.Environment]::SetEnvironmentVariable(ANTHROPIC_BASE_URL, https://taotoken.net/api, User)写完必须重开终端旧终端读不到新变量。3.2 项目级 settings 配置片段Claude Code 支持项目级配置放在项目根目录.claude/settings.json。这个文件决定权限、模型别名、环境变量覆盖。给你一个可直接用的片段{ model: sonnet, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的TaoToken Key }, permissions: { allow: [ Read, Glob, Grep ], deny: [ Bash(rm -rf *), Bash(git push --force*) ] } }这个片段做了三件事把模型固定成 sonnet 别名把 Base URL 和 Key 写进项目环境这样即使系统环境变量没配项目内也能跑以及限制危险命令。注意env里的 Key 会明文存在项目里如果是团队仓库建议只写ANTHROPIC_BASE_URLKey 走系统环境变量避免泄露。如果你用 Cline 或 CC Switch 这类工具管理多套配置它们的配置文件路径通常是~/.cline/config.json或~/.cc-switch/config.json写入的字段同样是三件套Base URL、API Key、Model ID。三件套缺一不可只填 Key 不填 Base URL 会打到官方端点然后超时只填 Base URL 不填 Key 会直接 401。3.3 验证配置是否被读到写完配置用这条命令确认 CLI 读到的值claude --version echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_API_KEYWindows 用$env:ANTHROPIC_BASE_URL。如果 Base URL 输出是https://taotoken.net/apiKey 输出完整就可以进下一步验证请求了。4. 验证请求跑通第一个对话配置写完必须实际发一次请求才算跑通。Claude Code 有三种模式交互模式claude、单次命令claude 你的问题、打印模式claude -p 你的问题。验证阶段推荐用打印模式输出干净、退出快、方便看报错。先建一个空目录做隔离测试mkdir ~/claude-hello cd ~/claude-hello git init claude -p 用一句话说明当前目录是什么项目如果配置正确你会看到模型返回一句描述终端退出码为 0。这一步成功说明 CLI、Key、Base URL 三者都通了。接着做一个稍微完整的验证让它生成文件claude -p 创建一个 hello.py打印 Hello Claude Code再创建一个 README.md 说明项目用途 python hello.py预期输出Hello Claude Code。这一步验证的是「模型能调用工具写文件」也就是 Claude Code 的 agent 能力。如果文件没生成多半是权限配置拦住了检查.claude/settings.json里的permissions.allow是否包含Write。再验证一下模型别名是否生效claude --model sonnet -p 回复 OK claude --model haiku -p 回复 OK两条都返回 OK说明别名映射正常。如果你在 TaoToken 控制台看到请求记录也能确认流量确实走了统一端点。验证模型对话是否正常也可以直接在网页端 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 发一条对比终端和网页的返回是否一致。提示验证阶段不要用--dangerously-skip-permissions这个参数会跳过所有权限确认个人测试目录可以用公司项目和生产环境绝对不要开。5. 常见报错排查401、local proxy failed、reading choices这一节按真实报错对照排查每条都给定位命令和修复动作。401 Unauthorized / invalid api key最常见。先确认 Key 有没有多余空格或换行echo $ANTHROPIC_API_KEY | cat -A如果末尾出现$之外还有^M或空格说明复制时带了脏字符。重新设置环境变量确保 Key 是完整的一串。再确认 Base URL 没写错https://taotoken.net/api后面不要加/v1或斜杠。如果 Key 本身失效去控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 重新生成一个。local proxy failed / connection refused这个报错说明 CLI 尝试连的端点不通。先ping taotoken.net看网络再curl -I https://taotoken.net/api看 HTTP 状态。如果系统里配了HTTP_PROXY或HTTPS_PROXY环境变量Claude Code 会走这个代理代理挂了就会报 local proxy failed。检查echo $HTTP_PROXY echo $HTTPS_PROXY如果不需要代理unset HTTP_PROXY HTTPS_PROXY再重试。reading choices / unexpected response format这个报错通常出现在响应体不是预期 JSON 时原因可能是 Base URL 指向了一个不兼容 Anthropic 协议的端点或者请求被中间层改写。确认ANTHROPIC_BASE_URL是https://taotoken.net/api不要填成 OpenAI 兼容端点。另外检查.claude/settings.json里有没有重复定义env项目级配置会覆盖系统级写错会互相打架。OAuth / authentication failed如果你之前用 Claude App Login 登录过CLI 可能缓存了旧凭证。清掉缓存再重试rm -rf ~/.claude/auth-token.json rm -rf ~/.claude/cache/然后重新用环境变量方式认证。command not found: claudePATH 没配好。macOS/Linux 检查which claude如果没有输出把export PATH$HOME/.local/bin:$PATH加进~/.zshrc。Windows 检查where claude把%USERPROFILE%\.local\bin加进用户 Path 变量重开终端。IDE 里插件调不起 CLIIDE 内置终端的环境变量可能和系统终端不一致。先在 IDE 终端里跑claude --version如果报 command not found说明 IDE 没继承系统 PATH。VS Code 可以在settings.json里指定终端 profileJetBrains 在 External Tools 里把 Program 写成claude的绝对路径。6. IDE 集成与长期使用建议CLI 跑通后IDE 集成就是把它接进你日常写代码的窗口。VS Code 和 Cursor 的配置方式基本一致核心是两件事让 IDE 终端能读到claude命令以及配几个快捷键快速调用。VS Code 的settings.json加终端 profile{ terminal.integrated.defaultProfile.osx: zsh, terminal.integrated.defaultProfile.linux: bash, terminal.integrated.defaultProfile.windows: PowerShell }再在.vscode/tasks.json里定义几个任务{ version: 2.0.0, tasks: [ { label: Claude: 审查当前文件, type: shell, command: claude \Review ${relativeFile} and suggest improvements\ }, { label: Claude: 解释当前文件, type: shell, command: claude \Explain what ${relativeFile} does\ } ] }然后在keybindings.json里绑快捷键比如ctrlshiftr触发审查任务。JetBrains 系列在 Settings → Tools → External Tools 里加一条Program 填claudeWorking directory 填$ProjectFileDir$再在 Keymap 里绑快捷键。如果你打算长期用 Claude Code 做日常编码和 agent 任务建议了解一下 Coding Plan它比按量计费更适合高频使用场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的端点和参数说明遇到协议层问题可以对照查。最后给一个实用技巧把项目级.claude/settings.json里的permissions.deny认真配一遍把rm -rf、git push --force、DROP TABLE这类危险命令拦掉。Claude Code 的 agent 能力越强权限边界越要提前划好。配置写完用claude -p 列出当前目录文件做一次冒烟测试确认读写权限符合预期再放开日常使用。