1. claude-code 安装前先搞懂它到底解决什么问题claude-code 是 Anthropic 推出的命令行 AI 编程助手它跟你在网页里聊天最大的区别是它能直接读写你本地的项目文件、执行终端命令、跑测试、提交 Git相当于把一个懂代码的助手放进了你的工作目录。你不需要复制粘贴代码片段直接说「帮我把这个接口加上重试逻辑」它会自己找到文件、改完、再跑一遍验证。它适合谁我观察下来主要是三类人一是日常写业务代码、希望减少重复劳动的开发者二是刚接手陌生项目、需要快速读懂代码结构的人三是想把 AI 接进 CI、脚本、自动化流程的工程团队。如果你只是偶尔问几个语法问题网页版就够了但如果你每天有大量文件级操作claude-code 的效率提升是肉眼可见的。这篇内容聚焦一条完整链路从 npm 全局安装到配置 API Key再到接入 MCP 服务最后用 ccr code 启动验证。中间会给出可直接复制的命令、settings 配置片段以及每一步的验证动作。我试过在几台不同环境的机器上跑这套流程踩过的坑主要集中在 npm 权限、环境变量没生效、MCP 服务连不上这三块后面会逐条拆开讲。先明确一个前提claude-code 本身是个客户端它需要一个模型服务来驱动。你可以用官方账号也可以用统一的 API 通道把请求转发到不同模型上。本文以 TaoToken 的统一 Key/API 通道为例来演示配置因为它把 Base URL、Key、Model ID 三件套收敛得比较清楚适合新手一次跑通。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 后面配置里会反复用到。在动手之前先确认你的机器满足基本条件Node.js 18 以上、npm 可用、终端能访问外网。Linux 和 macOS 基本开箱即用Windows 建议用 WSL2原生 PowerShell 也能跑但路径和权限问题会多一些。下面从环境检查开始。2. npm 全局安装 claude-code 与环境变量配置这一节解决「装不上」和「装了但命令找不到」两个高频问题。很多人第一次装 claude-code 会卡在 npm 权限上报 EACCES然后习惯性加 sudo结果把全局目录搞成 root 所有后面更麻烦。正确做法是给 npm 配一个用户级的全局目录彻底绕开权限问题。先做环境检查。打开终端确认 Node 和 npm 版本node -v npm -v如果提示 command not found说明 Node 没装。Linux 上可以用 NodeSource 的脚本装 LTS 版本curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt-get install -y nodejs装完再跑一次node -v能打印版本号就说明基础环境 OK。接下来配置 npm 的用户级全局目录这一步是避免 EACCES 的关键mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc如果你用的是 zsh把~/.bashrc换成~/.zshrc。配完之后用npm config get prefix确认输出是/home/你的用户名/.npm-global不是/usr或/usr/local。然后安装 claude-code 本体。注意不要加 sudonpm install -g anthropic-ai/claude-code如果之前装过旧版本先卸载再装npm uninstall -g anthropic-ai/claude-code npm install -g anthropic-ai/claude-code装完验证claude -v能打印版本号就说明二进制已经进了 PATH。如果提示 command not found八成是 PATH 没生效重新source ~/.bashrc或者直接开一个新终端。接下来是 API Key 配置。claude-code 读取环境变量来拿认证信息核心是三个Base URL、API Key、Model ID。以 TaoToken 通道为例你需要在控制台创建一个 Key然后把它写进环境变量。先拿到 Key再执行export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的_API_KEY export ANTHROPIC_MODELclaude-sonnet-4-20250514这三行建议写进~/.bashrc或~/.zshrc否则每次开新终端都要重设。写完之后source一下再用echo $ANTHROPIC_API_KEY确认变量确实存在。这里有个细节Base URL 末尾不要带/v1claude-code 会自己拼路径多写一层反而会 404。到这一步安装和认证就齐了。下一节进入 settings 配置和 MCP 接入把日常使用需要的东西一次配好。3. settings.json 配置片段与 MCP 服务接入claude-code 的配置分两层用户级和项目级。用户级放在~/.claude/settings.json对所有项目生效项目级放在项目根目录的.claude/settings.json只对当前项目生效。日常我建议把模型和权限放用户级把 MCP 和 Hook 放项目级这样换项目不会互相干扰。先看用户级 settings.json 的最小可用片段。路径是~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的_API_KEY, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Bash(git commit:*), Bash(npm run test:*), Read ], deny: [ Bash(rm -rf:*) ] } }这里env块的作用是把环境变量固化进配置省得每次开终端都 export。permissions.allow里列的是免确认就能执行的操作deny是明确禁止的。注意Bash(git commit:*)这种写法冒号后面是参数通配*表示任意参数。如果你不想每次都被问「是否允许执行」把常用命令加进 allow 会顺很多。接下来接 MCP。MCP 是 Model Context Protocol简单说就是给 claude-code 挂外部工具的协议。比如 Context7 这个 MCP 服务能让 AI 拉到最新的库文档避免它用过时的 API 写代码。安装命令分项目级和用户级# 项目级只在当前目录生效 claude mcp add context7 -- npx -y upstash/context7-mcp # 用户级全局生效 claude mcp add context7 --scope user -- npx -y upstash/context7-mcp装完用/mcp命令查看已安装的 MCP server 列表能看到 context7 就说明注册成功。想删掉的话claude mcp remove context7如果你用的是 claude-code-router 这套方案配置文件在~/.claude-code-router/config.json结构长这样{ Providers: [ { name: taotoken, api_base_url: https://taotoken.net/api/v1/chat/completions, api_key: 你的_API_KEY, models: [claude-sonnet-4-20250514], transformer: { use: [[maxtoken, { max_tokens: 65536 }], enhancetool] } } ], Router: { default: taotoken,claude-sonnet-4-20250514 } }注意这里的api_base_url跟环境变量里的 Base URL 不一样router 需要完整的 chat completions 路径。配好之后在终端输入ccr code就能启动。这里的三件套要记牢Base URL 用https://taotoken.net/apiKey 用控制台创建的Model ID 用你实际要调的模型名三者缺一不可。MCP 和 router 都配好之后下一节做实际验证确认整条链路真的通了。4. 验证请求与 ccr code 启动成功结果配置写完不代表能用必须跑一遍验证。这一节给出逐条验证动作从最简单的版本检查到实际发一次请求确保每一步都有明确结果。第一步确认 claude-code 能启动claude -v输出类似1.x.x (Claude Code)就对了。如果这里就报错回到第 2 节检查 PATH。第二步验证环境变量被正确读取。启动交互模式claude进去之后输入/status它会打印当前使用的 Base URL、模型和认证状态。重点看 Base URL 是不是https://taotoken.net/api模型是不是你配的那个。如果显示的是默认的 anthropic 地址说明环境变量没生效检查 settings.json 的 env 块或者 shell 配置。第三步发一个最小请求验证链路。在交互模式里直接输入用一句话说明这个项目是做什么的如果它能读取当前目录并给出回答说明模型调用和文件读取都通了。如果卡住或者报 401往下看第 5 节的排查。第四步验证 MCP 是否可用。输入/mcp应该能看到 context7 的状态是 connected。然后试着让它用 context7 查一个库的文档用 context7 查一下 react 最新的 hooks 用法如果它能返回文档内容说明 MCP 链路正常。第五步如果你用的是 router 方案用ccr code启动而不是claude。启动后同样跑/status确认 provider 是你在 config.json 里配的那个。ccr code和claude的区别在于前者会走 router 的路由逻辑后者直接读环境变量。第六步验证权限配置。让 claude-code 执行一个你加进 allow 的命令比如帮我跑一下 git status如果它没问你就直接执行了说明 allow 配置生效。反过来如果你让它执行rm -rf之类的它应该拒绝说明 deny 生效。全部跑通之后日常使用就顺了。常用命令记几个/init让它通读项目生成 CLAUDE.md/compact压缩上下文省 token/clear清空对话/resume找回历史话题。think、think hard、think harder、ultrathink可以控制模型思考长度复杂任务用 ultrathink 效果更稳。5. 常见报错排查401、local proxy failed 与 OAuth 问题这一节把高频报错逐条拆开。这些错误我基本都遇到过按下面的顺序排查能省不少时间。401 Unauthorized。这是最常见的说明 Key 没被正确识别。先确认echo $ANTHROPIC_API_KEY能打印出 Key且没有多余空格或换行。然后检查 Base URL 是不是https://taotoken.net/api末尾不要带/v1。如果用的是 settings.json 的 env 块确认 JSON 格式没写错逗号、引号都要对。还有一种情况是 Key 本身失效了去控制台重新创建一个再试。local proxy failed / connection refused。这个通常出现在 router 方案里说明ccr的本地代理没起来。先确认~/.claude-code-router/config.json里的api_base_url写的是完整路径https://taotoken.net/api/v1/chat/completions少写/v1或/chat/completions都会连不上。然后检查端口有没有被占用router 默认会起一个本地端口如果被别的进程占了就换一个。重启终端再跑ccr code一般能解决。reading choices 报错。这个错误说明返回的 JSON 结构跟预期对不上多半是 Base URL 拼错了请求打到了错误的端点。确认你用的是 chat completions 格式的地址而不是 messages 格式。router 和环境变量用的地址格式不一样别混用。OAuth 相关报错。如果你之前用官方账号登录过本地可能残留了 OAuth 凭证跟 API Key 模式冲突。解决办法是清掉旧的凭证文件通常在~/.claude/目录下找到跟 auth 或 credentials 相关的文件删掉然后重新用 API Key 模式启动。如果还是不行检查是不是同时设了ANTHROPIC_API_KEY和 OAuth token两者只能留一个。MCP 服务连不上。先跑/mcp看状态如果是 failed检查npx -y upstash/context7-mcp能不能单独跑起来。有时候是网络问题导致 npx 拉包失败可以先手动npx -y upstash/context7-mcp跑一次让它把包缓存下来再重新 add。权限被拒。如果你执行命令时一直被问检查 settings.json 的 allow 列表有没有写对。Bash(git commit:*)这种格式冒号和星号都不能少。如果想让某个 MCP server 免确认加mcp__context7这样的条目。实在嫌麻烦可以用--dangerously-skip-permissions启动但这等于关掉所有确认只建议在隔离环境里用。排查的核心思路是先确认认证Key 和 Base URL再确认网络能不能访问到端点最后确认配置格式JSON 有没有写错。按这个顺序走大部分问题都能定位。6. 把 claude-code 接进日常开发流的几个实用动作跑通之后真正提升效率的是把它接进日常流程。这里分享几个我实际在用的动作都是配置层面能落地的。第一个是自定义命令。在项目根目录建.claude/commands/文件夹每放一个.md文件就多一个命令。比如建一个review.md内容写「审查当前改动的代码指出潜在 bug 和性能问题用 $ARGUMENTS 指定关注点」之后在 claude-code 里输入/review 并发安全就能触发。$ARGUMENTS是参数占位符很灵活。放到~/.claude/commands/下就变成用户级所有项目都能用。第二个是 Hook。在.claude/settings.json里配 PostToolUse让 claude-code 每次写完代码自动跑格式检查{ hooks: { PostToolUse: [ { matcher: Edit|MultiEdit|Write, hooks: [ { type: command, command: npx prettier --check . } ] } ] } }这样它改完文件就会自动检查格式省得你手动跑。matcher 匹配的是工具名Edit、MultiEdit、Write 覆盖了大部分写文件的操作。第三个是 Sub Agent。用/agents命令可以创建子代理把复杂任务拆开。比如一个 agent 专门读代码一个专门写测试一个专门做 review。子代理之间上下文隔离适合处理大任务成功率比单线程高不少。第四个是回退。装ccundo之后可以按对话节点回退代码npm install -g ccundo ccundo list ccundo undo operation-idccundo list列出所有操作记录带编号ccundo undo 编号就能把代码和对话一起回退到那个节点。改坏了不用慌回退就行。第五个是 GitHub 集成。装了gh命令行工具之后claude-code 能直接操作仓库比如gh repo list列出你的所有仓库或者让它帮你建 PR、查 issue。最后提一下 Key 和通道的管理。如果你同时用多个模型建议把 Base URL、Key、Model ID 这三件套统一走一个通道换模型只改 Model ID不用动其他配置。TaoToken 的 API 地址是 https://taotoken.net/api 控制台在 https://taotoken.net/console Key 在 https://taotoken.net/api-keys 管理。想先试试模型对话效果可以去 https://taotoken.net/chat 长期跑编码任务或者 Agent 的话Coding Plan 会更划算入口在 https://taotoken.net/coding-plan 。接入文档在 https://taotoken.net/doc 遇到配置问题可以先翻文档。Claude Code 相关的接入说明在 https://taotoken.net/ClaudeCodeAnthropic 。整套流程跑下来从安装到能用大概十几分钟真正花时间的是排查环境问题。把第 5 节的排查清单存下来下次换机器能省不少事。