上周有位朋友在群里发了张终端截图claude敲下去之后卡在登录页转圈光标一直在闪他以为是自己网络的问题折腾了半小时重装了三遍。我看了一眼就笑了——这压根不是安装的问题是它默认要走官方账号体系而他手上只有一份百炼的 API Key。这个场景在 Mac 用户里特别常见Claude Code 本身装起来不复杂真正让人卡住的是装完之后怎么让它用上我手里的模型这一步。这篇就把这两件事拆开讲透Mac 上把 Claude Code 装好、跑起来然后通过阿里云百炼的兼容端点把它接上全程不需要官方账号也不需要额外的东西。先把定位说清楚免得有人看到标题以为这是给 VS Code 装个补全插件。Claude Code 是跑在终端里的一个任务型工具你给它一句自然语言指令它会自己去读文件、改代码、跑命令、看报错、再改是一个能连续执行多步的循环体不是一个等着你按 Tab 的提示框。百炼在其中的角色也很明确它提供模型侧的调用能力和一个兼容端点Claude Code 把请求发过去模型吐回来工具继续干活。这套组合最适合两类人——一是手里已经有百炼额度、想把它用起来的开发者二是想在 Mac 上体验终端式 AI 编程、但不想被账号体系挡在门外的人。下面从概念、安装、接入、验证、长期使用五个层面依次展开每一步我都把为什么这么做和哪里容易翻车写清楚。1. 先把期望值对齐Claude Code 到底是什么百炼在其中扮演什么角色动手之前花五分钟把这两样东西的边界搞清楚能省掉后面大量装了但不知道在干嘛的困惑。很多人第一次用完之后的最大感受是它怎么自己就开始改我文件了这恰恰说明它的设计取向和常见的编辑器插件完全不是一回事。1.1 Claude Code 是终端里的任务执行器不是补全插件理解它的关键在一个词循环。你在终端里输入一句话比如把项目里的 fetch 请求统一加上超时处理它做的第一件事不是直接改代码而是先搜索、读文件、定位到所有相关位置然后生成修改方案逐个文件写入再回头检查有没有语法问题。如果中途某条命令报错它会读到这个报错把它当作新的输入继续调整。整个过程在你眼皮底下发生每一步都要你确认或者放行。这和编辑器里的补全插件有本质区别。补全插件的输入是光标前的那几行输出是接下里的几行它不知道你的项目结构也不会主动去跑测试。而 Claude Code 的输入是整个工作目录的上下文输出是一系列实际操作。它更像你雇的一个能自己动手的实习生你只需要下指令和验收中间过程它会自己跑。正因为它是执行器所以它对模型的能力要求比补全高得多。补全答错一句你按一下 Esc 就过去了执行器理解错一句它可能把三个文件改乱。这也是为什么模型选型在这一步格外重要——后面讲百炼模型名的时候会再提。1.2 百炼接入的本质把模型调用这一层换掉Claude Code 的架构里模型调用是被抽出来的一层。它本身不绑定某个具体的模型服务只认几个环境变量请求发到哪个地址、用什么凭证、用哪个模型名。把这几个变量指向百炼提供的兼容端点请求就会走百炼模型返回的内容格式是一致的工具照常解析。这个设计的巧妙之处在于上层的工作流完全不用改。文件读取、命令执行、权限确认、上下文压缩这些逻辑都在本地和模型是谁没关系。你换的只是大脑手脚还是原来那套。所以我经常跟人说接入这件事的技术难度约等于配置一个环境变量真正的门槛在于把凭证、地址、模型名这三者的对应关系搞对。注意兼容端点意味着接口格式对齐不意味着能力完全对齐。不同模型在长上下文、工具调用稳定性上的表现差异是真实存在的接上之后建议先用小任务试水别一上来就让它重构整个项目。1.3 这套组合的适用边界把话说透不是所有人都适合走这条路。下面这张表是我自己的判断标准可以对号入座。场景是否适合原因手上有百炼额度想拿它跑终端编程适合凭证现成配置十几分钟搞定想体验终端式 AI 编程暂时没有官方账号适合兼容端点绕开了账号体系团队想统一模型出口、便于统计用量适合所有请求走同一个平台账单集中需要模型对超长上下文做精细推理谨慎取决于所选模型的实际表现需实测只想在编辑器里要个补全不适合这个工具的设计目标不是补全最后一行值得多说一句。我见过有人装完之后抱怨怎么没有代码提示这就是工具选错了。想要补全去装编辑器插件想要一个能连续执行任务的终端助手才轮到 Claude Code。2. Mac 上的安装Node 版本、安装路径与第一次启动的三个坑安装本身十分钟能搞定但我见过太多人卡在三个地方Node 版本太老、全局安装的 bin 目录不在 PATH 里、以及第一次启动时那个登录页。这一节按顺序把这三点拆开。2.1 装之前先做环境自检Claude Code 的运行依赖 Node 环境官方对版本有下限要求我的经验是至少 Node 18推荐 20 或 22 的 LTS 版本。为什么强调这个因为 macOS 自带的 Node 往往是老版本或者你之前用某个安装包装过一个很久没更新的版本直接跑安装命令会成功但启动时报一堆语法错误排查起来很浪费时间。先跑三条命令看一眼当前状态node -v npm -v which node第三条命令经常被忽略但它很关键。如果which node指向的是/usr/local/bin/node而你平时用 nvm 管理版本那很可能你装的包和跑的包不是同一个 Node。这种情况下最稳妥的做法是用 nvm 统一管理# 安装或切换到 LTS 版本 nvm install --lts nvm use --lts nvm alias default node # 确认切换生效 node -v which nodenvm alias default这一步别省。我踩过一次坑临时切了版本装好工具关掉终端再打开PATH 又回到系统默认的 Node工具直接报错当时还以为是装坏了。设成 default 之后就不会有这个问题。npm 源的问题也顺手处理一下。如果安装过程中一直卡在下载阶段可以临时换一个下载更快的源装完再切回来npm config get registry npm config set registry https://registry.npmmirror.com装完之后如果想还原把 registry 设回原来的地址就行。这一步不是必须的但能显著减少装到一半卡住的情况。2.2 全局安装npm 与官方脚本的差异Mac 上有两种主流装法各有适用场景。第一种是 npm 全局安装也是我最常用的方式npm install -g anthropic-ai/claude-code装完直接敲claude就能启动。这种方式的优点是升级方便再跑一次同样的命令就是升级卸载也干净npm uninstall -g。第二种是官方提供的安装脚本走的是独立的安装路径不依赖你本地的 Node 环境curl -fsSL https://claude.ai/install.sh | bash这种方式的好处是把运行时打包进去了不会因为你后面切了 Node 版本就失效缺点是升级要重新跑脚本而且和你 npm 装的那份可能共存导致which claude指向的不是你以为的那个。我的建议很明确如果你已经在用 npm 管理工具链就走 npm别混着装。混装的典型症状是我明明升级了怎么版本号没变原因就是 shell 找到的是另一个路径下的可执行文件。装完验证一下claude --version which claude如果which claude什么都没输出说明 npm 的全局 bin 目录不在 PATH 里。查一下位置npm config get prefix假设输出是/Users/你的用户名/.npm-global那这个目录下的bin子目录就应该加进 PATH。在~/.zshrc里追加一行export PATH$HOME/.npm-global/bin:$PATH然后source ~/.zshrc让它生效。这一步是新手最容易漏的症状就是装成功了但命令找不到。2.3 首次启动卡在登录页怎么绕过去装好之后敲claude第一次启动通常会出现一个登录引导让你选择登录方式。如果你手上有官方账号跟着走就行如果你的目标是走百炼那这一步没必要走直接中断CtrlC先去把环境变量配好。配好之后再启动它会识别到已有的凭证不再弹登录。这里有个细节值得说明为什么配了环境变量就不弹登录了因为启动时它会按顺序检查凭证来源环境变量里的 token 优先级高于交互式登录。所以先配环境变量、再启动这个顺序很重要反过来做的话你可能会被引导到一个走不通的流程里。还有一个启动参数值得提前了解claude --help把所有可用参数过一遍尤其是后面会提到的权限相关参数。花两分钟看帮助比后面到处搜答案强。3. 接上百炼环境变量、兼容端点与模型名的对应关系这一节是全文的核心。接入这件事说到底就是把三样东西对齐地址、凭证、模型名。三者缺一不可错一个就会出现 401、404 或者模型不存在这类报错。我会把每一环都讲清楚包括容易混淆的地方。3.1 百炼控制台侧要准备的三样东西在配置本地之前先去百炼的控制台把准备工作做完。这一步做不扎实后面怎么调都是白费。第一样是API Key。在控制台的密钥管理页面创建一个格式通常是sk-开头的一长串。创建的时候注意两点一是创建后只显示一次务必当场复制保存二是权限范围如果平台支持按模型或者按业务空间做权限细分选最小够用的那个范围别图省事开最大权限。这个习惯在团队环境里尤其重要密钥泄露的代价比多花五分钟配置高得多。第二样是模型的开通状态。百炼的模型广场里有很多模型不是每个都默认可用。你需要确认自己要用的那个模型已经开通并且在控制台能看到它的准确名称。这里特别提醒模型名必须一字不差包括大小写和中间的连字符。我见过有人把-写成_排查了半小时。第三样是兼容端点的地址。百炼为 Claude Code 这类工具提供了专门的接入端点地址形如https://dashscope.aliyuncs.com/api/v2/apps/claude-code-proxy这个地址的作用是把 Claude Code 发出的请求格式转换成百炼能识别的格式再把结果转回来。建议以控制台文档页面当前显示的地址为准平台可能会调整路径照抄我这里的示例之前先核对一遍。模型选型上我的建议是优先选带 coder 标识的系列这类模型在代码理解和工具调用上的针对性更强如果任务偏重自然语言推理再考虑通用系列。具体可选型号以控制台列表为准不同时期上架的型号不一样。3.2 环境变量的三种写法与生效范围拿到三样东西之后就要写进本地环境。这里有三条变量是必须的变量名作用说明ANTHROPIC_BASE_URL指定请求发往哪个端点填百炼的兼容地址ANTHROPIC_AUTH_TOKEN凭证填你的 API KeyANTHROPIC_MODEL主模型名填控制台里确认过的准确名称另外还有一个可选但很实用的变量ANTHROPIC_SMALL_FAST_MODEL用来指定处理轻量任务比如生成文件名、做简单判断的模型。把它设成一个更小更快的型号能明显降低整体消耗因为这类小任务调用频次很高用大模型跑纯属浪费。配置文件的方式在~/.zshrc末尾追加# Claude Code 接入配置 export ANTHROPIC_BASE_URLhttps://dashscope.aliyuncs.com/api/v2/apps/claude-code-proxy export ANTHROPIC_AUTH_TOKENsk-你的密钥 export ANTHROPIC_MODEL你的主模型名 export ANTHROPIC_SMALL_FAST_MODEL你的轻量模型名然后source ~/.zshrc开一个新终端窗口验证echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_MODEL两条都有输出就说明生效了。这里有个小坑如果你用的是 bash 而不是 zshmacOS Catalina 之后默认是 zsh但有人手动改过要写到~/.bash_profile里写错文件的话source也不会有任何反应。第二种写法是临时生效适合做对照测试。直接在命令行前面带变量ANTHROPIC_BASE_URL... ANTHROPIC_AUTH_TOKEN... ANTHROPIC_MODEL... claude这种写法不会污染你的全局环境测完就没了。我在排查到底是配置问题还是模型问题的时候经常用它比反复改配置文件快得多。第三种是按目录隔离适合同时维护多个不同配置的场景。思路是在项目目录下放一个启动脚本里面 export 好这一套变量再启动。这样不同的项目可以用不同的模型互不干扰。3.3 写进 settings.json让配置跟着项目走环境变量是全局的但实际工作中经常遇到这个项目想用 A 模型那个项目想用 B 模型的情况。Claude Code 支持通过配置文件来做更细粒度的控制配置文件放在~/.claude/settings.json用户级或者项目目录下的.claude/settings.json项目级。用户级配置的写法{ env: { ANTHROPIC_BASE_URL: https://dashscope.aliyuncs.com/api/v2/apps/claude-code-proxy, ANTHROPIC_AUTH_TOKEN: sk-你的密钥, ANTHROPIC_MODEL: 你的主模型名, ANTHROPIC_SMALL_FAST_MODEL: 你的轻量模型名 } }这里的env字段会在启动时注入到进程环境里效果和 shell 里 export 是一样的但好处是可以按项目覆盖。项目级配置的优先级高于用户级所以在某个项目里放一份不同的settings.json就能实现项目内用另一套模型。注意项目级的配置文件如果包含密钥一定记得加进.gitignore别顺手提交上去了。团队协作场景里更推荐把密钥放在个人环境变量里项目配置里只放非敏感的模型名和端点地址。配置文件写好之后启动 Claude Code用内置的/status命令看一眼当前生效的配置。这一步是验收的关键能看到 base url 和模型名对得上才说明配置真的被读取了。如果/status里显示的地址还是空的或者默认值那说明配置文件的位置不对或者 JSON 格式有语法错误少个逗号、多个括号都很常见。4. 验证链路从 /status 到真的改一个文件配置写完不等于接通。我见过太多配置看起来没问题但就是不工作的情况所以这里给一套从轻到重的验证链路每一层都能独立确认出问题能立刻定位到是哪一环。4.1 四步最小验证第一步确认配置被读取。启动后输入/status检查三件事base url 是不是你填的那个地址、模型名是不是你填的那个、认证方式是否显示为 token。三项都对说明配置层没问题。第二步发一句最简单的对话。比如输入用一句话说明当前目录大概是什么类型的项目。这一步验证的是网络连通性和凭证有效性。如果这一步就报错问题一定在凭证或地址上不用往下查文件操作了。第三步让它读一个文件。输入读一下 package.json告诉我项目名和依赖数量。这一步验证的是工具调用链路——它需要发起一次文件读取操作然后基于读到的内容回答。如果对话能通但这一步失败说明模型对工具调用的支持有问题考虑换个模型试试。第四步让它改一个文件。找一个无关紧要的测试文件让它做个小改动比如在这个文件顶部加一行注释。这一步会触发权限确认弹窗你确认之后它才会真的写。写完之后你自己cat一下确认内容正确。这四步走完整个链路就通了。任何一步失败问题范围都能立刻缩小一半比一上来就跑大任务高效得多。4.2 报错定位按状态码分诊不同报错对应不同环节下面这张表是我整理的常见情况遇到问题可以直接对号入座。现象大概率原因处理方向401 / 认证失败密钥错误、密钥失效、变量名写错检查变量名是否为ANTHROPIC_AUTH_TOKEN重新复制密钥403 / 无权限模型未开通或密钥权限范围不含该模型去控制台确认开通状态和密钥范围404 / 地址不存在base url 拼错或端点路径已调整核对控制台文档中的最新地址提示模型不存在模型名大小写、连字符不一致逐字符比对控制台显示的名称请求超时网络到端点不通畅先用 curl 单独测端点连通性能对话但改文件失败模型工具调用能力不足换 coder 系列模型重试表格之外补充两个细节。第一变量名拼写是最隐蔽的坑。有人习惯写ANTHROPIC_API_KEY这个变量在走官方服务时是有效的但配合自定义端点时工具内部的校验逻辑可能对它有额外要求表现就是怎么都认不出凭证。遇到这种情况改用ANTHROPIC_AUTH_TOKEN通常能解决。第二环境变量有优先级。shell 里 export 的和 settings.json 里的会互相覆盖如果你两边都配了但值不一样最终生效的可能是你没想到的那一份。排查时先统一到一处别留两份。还有一个通用的排查手段用 curl 直接打端点把工具这一层剥掉。curl -X POST $ANTHROPIC_BASE_URL \ -H Authorization: Bearer $ANTHROPIC_AUTH_TOKEN \ -H Content-Type: application/json \ -d {model:$ANTHROPIC_MODEL,messages:[{role:user,content:hi}]}如果 curl 能通而工具不能通问题就在工具配置如果 curl 也不通问题就在凭证或地址。这一招能把排查范围一刀切两半我每次遇到玄学问题都先跑它。5. 长期用下去的几个习惯上下文、权限与成本接通只是开始真正决定这套东西好不好用的是日常使用习惯。这一节讲的都是我用了几个月之后总结出来的、文档里不太会写的部分。5.1 上下文管理CLAUDE.md 和清理时机Claude Code 启动时会读取项目根目录下的CLAUDE.md把里面的内容作为长期上下文。这个文件的价值在于把你反复要解释的东西固化下来。比如项目的技术栈、目录约定、代码风格、构建命令、不能碰的目录写进去之后就不用每次重复交代了。生成初稿很简单在项目根目录启动后输入/init它会扫描项目结构自动生成一份。但自动生成的只是起点一定要手动改。我的做法是把它压缩到一屏以内只保留三类信息必须遵守的约定、容易踩的坑、常用命令。写太长的后果是每次对话都占用大量上下文反而挤掉了真正有用的信息。除了 CLAUDE.md还有两个命令要养成习惯。/clear用来清空当前会话的上下文适合切换到完全不相关的新任务时用/compact用来压缩上下文适合同一个任务聊太久、历史太长的时候用。什么时候用哪个我的判断标准是任务切换用 clear任务延续但太长用 compact。搞反了会导致要么丢失必要的背景要么白白浪费上下文预算。5.2 权限模式与危险操作的边界Claude Code 默认对每个有副作用的操作写文件、执行命令都要求确认。这个设计一开始会觉得烦但它是必要的安全网。我在早期为了图快用过跳过确认的模式结果有一次它执行了一条删除命令虽然只是删了临时文件但那一刻的冷汗是真实的。我的建议是日常开发保持默认确认模式只在完全可控的沙箱环境里才考虑放宽。判断可控的标准很简单——这个目录里有没有不能丢的东西有就别放宽。另外有个很实用的功能值得用起来它支持先出方案再执行。你可以明确要求先告诉我你打算改哪些文件、每个文件改什么我确认后再动手。这个习惯在改动面比较大的任务里特别值能让你在动手之前就发现方向跑偏。5.3 把消耗压下来的几个动作走百炼的按量计费模式下成本控制是可以做得很细的。分享几个我实测有效的做法。第一把轻量任务分流到小模型。前面提到的ANTHROPIC_SMALL_FAST_MODEL就是干这个的很多内部的小判断用大模型跑纯属浪费切到小模型之后整体消耗能降下来一截。第二控制输入的文件范围。让它改一个函数不要让它读整个目录。指令里明确说只看 src/utils 下的文件比帮我优化一下项目省下的量级完全不是一个数量级。第三善用 plan 模式。在动手之前先让它出计划你审一遍再让它执行。这看起来多了一轮对话但能避免它朝着错误方向改一堆文件然后全部回滚——那才是真正的浪费。第四长会话及时压缩。上下文越长每一轮请求带上的 token 就越多成本是持续累积的。一个聊了两小时没清理过的会话单轮成本可能是刚开始时的好几倍。最后分享一个我自己的习惯给常用任务写几个固定的指令模板存在项目的CLAUDE.md或者一个单独的说明文件里。比如新增一个接口这个任务模板里写清楚要改哪几个文件、按什么顺序、遵循什么命名规范。用模板发起任务比每次自由发挥的产出稳定得多返工少消耗自然也少。这套东西跑顺之后终端里敲一句话就能完成过去要点十几次鼠标的活那种感觉确实不一样。
上周有位朋友在群里发了张终端截图claude敲下去之后卡在登录页转圈光标一直在闪他以为是自己网络的问题折腾了半小时重装了三遍。我看了一眼就笑了——这压根不是安装的问题是它默认要走官方账号体系而他手上只有一份百炼的 API Key。这个场景在 Mac 用户里特别常见Claude Code 本身装起来不复杂真正让人卡住的是装完之后怎么让它用上我手里的模型这一步。这篇就把这两件事拆开讲透Mac 上把 Claude Code 装好、跑起来然后通过阿里云百炼的兼容端点把它接上全程不需要官方账号也不需要额外的东西。先把定位说清楚免得有人看到标题以为这是给 VS Code 装个补全插件。Claude Code 是跑在终端里的一个任务型工具你给它一句自然语言指令它会自己去读文件、改代码、跑命令、看报错、再改是一个能连续执行多步的循环体不是一个等着你按 Tab 的提示框。百炼在其中的角色也很明确它提供模型侧的调用能力和一个兼容端点Claude Code 把请求发过去模型吐回来工具继续干活。这套组合最适合两类人——一是手里已经有百炼额度、想把它用起来的开发者二是想在 Mac 上体验终端式 AI 编程、但不想被账号体系挡在门外的人。下面从概念、安装、接入、验证、长期使用五个层面依次展开每一步我都把为什么这么做和哪里容易翻车写清楚。1. 先把期望值对齐Claude Code 到底是什么百炼在其中扮演什么角色动手之前花五分钟把这两样东西的边界搞清楚能省掉后面大量装了但不知道在干嘛的困惑。很多人第一次用完之后的最大感受是它怎么自己就开始改我文件了这恰恰说明它的设计取向和常见的编辑器插件完全不是一回事。1.1 Claude Code 是终端里的任务执行器不是补全插件理解它的关键在一个词循环。你在终端里输入一句话比如把项目里的 fetch 请求统一加上超时处理它做的第一件事不是直接改代码而是先搜索、读文件、定位到所有相关位置然后生成修改方案逐个文件写入再回头检查有没有语法问题。如果中途某条命令报错它会读到这个报错把它当作新的输入继续调整。整个过程在你眼皮底下发生每一步都要你确认或者放行。这和编辑器里的补全插件有本质区别。补全插件的输入是光标前的那几行输出是接下里的几行它不知道你的项目结构也不会主动去跑测试。而 Claude Code 的输入是整个工作目录的上下文输出是一系列实际操作。它更像你雇的一个能自己动手的实习生你只需要下指令和验收中间过程它会自己跑。正因为它是执行器所以它对模型的能力要求比补全高得多。补全答错一句你按一下 Esc 就过去了执行器理解错一句它可能把三个文件改乱。这也是为什么模型选型在这一步格外重要——后面讲百炼模型名的时候会再提。1.2 百炼接入的本质把模型调用这一层换掉Claude Code 的架构里模型调用是被抽出来的一层。它本身不绑定某个具体的模型服务只认几个环境变量请求发到哪个地址、用什么凭证、用哪个模型名。把这几个变量指向百炼提供的兼容端点请求就会走百炼模型返回的内容格式是一致的工具照常解析。这个设计的巧妙之处在于上层的工作流完全不用改。文件读取、命令执行、权限确认、上下文压缩这些逻辑都在本地和模型是谁没关系。你换的只是大脑手脚还是原来那套。所以我经常跟人说接入这件事的技术难度约等于配置一个环境变量真正的门槛在于把凭证、地址、模型名这三者的对应关系搞对。注意兼容端点意味着接口格式对齐不意味着能力完全对齐。不同模型在长上下文、工具调用稳定性上的表现差异是真实存在的接上之后建议先用小任务试水别一上来就让它重构整个项目。1.3 这套组合的适用边界把话说透不是所有人都适合走这条路。下面这张表是我自己的判断标准可以对号入座。场景是否适合原因手上有百炼额度想拿它跑终端编程适合凭证现成配置十几分钟搞定想体验终端式 AI 编程暂时没有官方账号适合兼容端点绕开了账号体系团队想统一模型出口、便于统计用量适合所有请求走同一个平台账单集中需要模型对超长上下文做精细推理谨慎取决于所选模型的实际表现需实测只想在编辑器里要个补全不适合这个工具的设计目标不是补全最后一行值得多说一句。我见过有人装完之后抱怨怎么没有代码提示这就是工具选错了。想要补全去装编辑器插件想要一个能连续执行任务的终端助手才轮到 Claude Code。2. Mac 上的安装Node 版本、安装路径与第一次启动的三个坑安装本身十分钟能搞定但我见过太多人卡在三个地方Node 版本太老、全局安装的 bin 目录不在 PATH 里、以及第一次启动时那个登录页。这一节按顺序把这三点拆开。2.1 装之前先做环境自检Claude Code 的运行依赖 Node 环境官方对版本有下限要求我的经验是至少 Node 18推荐 20 或 22 的 LTS 版本。为什么强调这个因为 macOS 自带的 Node 往往是老版本或者你之前用某个安装包装过一个很久没更新的版本直接跑安装命令会成功但启动时报一堆语法错误排查起来很浪费时间。先跑三条命令看一眼当前状态node -v npm -v which node第三条命令经常被忽略但它很关键。如果which node指向的是/usr/local/bin/node而你平时用 nvm 管理版本那很可能你装的包和跑的包不是同一个 Node。这种情况下最稳妥的做法是用 nvm 统一管理# 安装或切换到 LTS 版本 nvm install --lts nvm use --lts nvm alias default node # 确认切换生效 node -v which nodenvm alias default这一步别省。我踩过一次坑临时切了版本装好工具关掉终端再打开PATH 又回到系统默认的 Node工具直接报错当时还以为是装坏了。设成 default 之后就不会有这个问题。npm 源的问题也顺手处理一下。如果安装过程中一直卡在下载阶段可以临时换一个下载更快的源装完再切回来npm config get registry npm config set registry https://registry.npmmirror.com装完之后如果想还原把 registry 设回原来的地址就行。这一步不是必须的但能显著减少装到一半卡住的情况。2.2 全局安装npm 与官方脚本的差异Mac 上有两种主流装法各有适用场景。第一种是 npm 全局安装也是我最常用的方式npm install -g anthropic-ai/claude-code装完直接敲claude就能启动。这种方式的优点是升级方便再跑一次同样的命令就是升级卸载也干净npm uninstall -g。第二种是官方提供的安装脚本走的是独立的安装路径不依赖你本地的 Node 环境curl -fsSL https://claude.ai/install.sh | bash这种方式的好处是把运行时打包进去了不会因为你后面切了 Node 版本就失效缺点是升级要重新跑脚本而且和你 npm 装的那份可能共存导致which claude指向的不是你以为的那个。我的建议很明确如果你已经在用 npm 管理工具链就走 npm别混着装。混装的典型症状是我明明升级了怎么版本号没变原因就是 shell 找到的是另一个路径下的可执行文件。装完验证一下claude --version which claude如果which claude什么都没输出说明 npm 的全局 bin 目录不在 PATH 里。查一下位置npm config get prefix假设输出是/Users/你的用户名/.npm-global那这个目录下的bin子目录就应该加进 PATH。在~/.zshrc里追加一行export PATH$HOME/.npm-global/bin:$PATH然后source ~/.zshrc让它生效。这一步是新手最容易漏的症状就是装成功了但命令找不到。2.3 首次启动卡在登录页怎么绕过去装好之后敲claude第一次启动通常会出现一个登录引导让你选择登录方式。如果你手上有官方账号跟着走就行如果你的目标是走百炼那这一步没必要走直接中断CtrlC先去把环境变量配好。配好之后再启动它会识别到已有的凭证不再弹登录。这里有个细节值得说明为什么配了环境变量就不弹登录了因为启动时它会按顺序检查凭证来源环境变量里的 token 优先级高于交互式登录。所以先配环境变量、再启动这个顺序很重要反过来做的话你可能会被引导到一个走不通的流程里。还有一个启动参数值得提前了解claude --help把所有可用参数过一遍尤其是后面会提到的权限相关参数。花两分钟看帮助比后面到处搜答案强。3. 接上百炼环境变量、兼容端点与模型名的对应关系这一节是全文的核心。接入这件事说到底就是把三样东西对齐地址、凭证、模型名。三者缺一不可错一个就会出现 401、404 或者模型不存在这类报错。我会把每一环都讲清楚包括容易混淆的地方。3.1 百炼控制台侧要准备的三样东西在配置本地之前先去百炼的控制台把准备工作做完。这一步做不扎实后面怎么调都是白费。第一样是API Key。在控制台的密钥管理页面创建一个格式通常是sk-开头的一长串。创建的时候注意两点一是创建后只显示一次务必当场复制保存二是权限范围如果平台支持按模型或者按业务空间做权限细分选最小够用的那个范围别图省事开最大权限。这个习惯在团队环境里尤其重要密钥泄露的代价比多花五分钟配置高得多。第二样是模型的开通状态。百炼的模型广场里有很多模型不是每个都默认可用。你需要确认自己要用的那个模型已经开通并且在控制台能看到它的准确名称。这里特别提醒模型名必须一字不差包括大小写和中间的连字符。我见过有人把-写成_排查了半小时。第三样是兼容端点的地址。百炼为 Claude Code 这类工具提供了专门的接入端点地址形如https://dashscope.aliyuncs.com/api/v2/apps/claude-code-proxy这个地址的作用是把 Claude Code 发出的请求格式转换成百炼能识别的格式再把结果转回来。建议以控制台文档页面当前显示的地址为准平台可能会调整路径照抄我这里的示例之前先核对一遍。模型选型上我的建议是优先选带 coder 标识的系列这类模型在代码理解和工具调用上的针对性更强如果任务偏重自然语言推理再考虑通用系列。具体可选型号以控制台列表为准不同时期上架的型号不一样。3.2 环境变量的三种写法与生效范围拿到三样东西之后就要写进本地环境。这里有三条变量是必须的变量名作用说明ANTHROPIC_BASE_URL指定请求发往哪个端点填百炼的兼容地址ANTHROPIC_AUTH_TOKEN凭证填你的 API KeyANTHROPIC_MODEL主模型名填控制台里确认过的准确名称另外还有一个可选但很实用的变量ANTHROPIC_SMALL_FAST_MODEL用来指定处理轻量任务比如生成文件名、做简单判断的模型。把它设成一个更小更快的型号能明显降低整体消耗因为这类小任务调用频次很高用大模型跑纯属浪费。配置文件的方式在~/.zshrc末尾追加# Claude Code 接入配置 export ANTHROPIC_BASE_URLhttps://dashscope.aliyuncs.com/api/v2/apps/claude-code-proxy export ANTHROPIC_AUTH_TOKENsk-你的密钥 export ANTHROPIC_MODEL你的主模型名 export ANTHROPIC_SMALL_FAST_MODEL你的轻量模型名然后source ~/.zshrc开一个新终端窗口验证echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_MODEL两条都有输出就说明生效了。这里有个小坑如果你用的是 bash 而不是 zshmacOS Catalina 之后默认是 zsh但有人手动改过要写到~/.bash_profile里写错文件的话source也不会有任何反应。第二种写法是临时生效适合做对照测试。直接在命令行前面带变量ANTHROPIC_BASE_URL... ANTHROPIC_AUTH_TOKEN... ANTHROPIC_MODEL... claude这种写法不会污染你的全局环境测完就没了。我在排查到底是配置问题还是模型问题的时候经常用它比反复改配置文件快得多。第三种是按目录隔离适合同时维护多个不同配置的场景。思路是在项目目录下放一个启动脚本里面 export 好这一套变量再启动。这样不同的项目可以用不同的模型互不干扰。3.3 写进 settings.json让配置跟着项目走环境变量是全局的但实际工作中经常遇到这个项目想用 A 模型那个项目想用 B 模型的情况。Claude Code 支持通过配置文件来做更细粒度的控制配置文件放在~/.claude/settings.json用户级或者项目目录下的.claude/settings.json项目级。用户级配置的写法{ env: { ANTHROPIC_BASE_URL: https://dashscope.aliyuncs.com/api/v2/apps/claude-code-proxy, ANTHROPIC_AUTH_TOKEN: sk-你的密钥, ANTHROPIC_MODEL: 你的主模型名, ANTHROPIC_SMALL_FAST_MODEL: 你的轻量模型名 } }这里的env字段会在启动时注入到进程环境里效果和 shell 里 export 是一样的但好处是可以按项目覆盖。项目级配置的优先级高于用户级所以在某个项目里放一份不同的settings.json就能实现项目内用另一套模型。注意项目级的配置文件如果包含密钥一定记得加进.gitignore别顺手提交上去了。团队协作场景里更推荐把密钥放在个人环境变量里项目配置里只放非敏感的模型名和端点地址。配置文件写好之后启动 Claude Code用内置的/status命令看一眼当前生效的配置。这一步是验收的关键能看到 base url 和模型名对得上才说明配置真的被读取了。如果/status里显示的地址还是空的或者默认值那说明配置文件的位置不对或者 JSON 格式有语法错误少个逗号、多个括号都很常见。4. 验证链路从 /status 到真的改一个文件配置写完不等于接通。我见过太多配置看起来没问题但就是不工作的情况所以这里给一套从轻到重的验证链路每一层都能独立确认出问题能立刻定位到是哪一环。4.1 四步最小验证第一步确认配置被读取。启动后输入/status检查三件事base url 是不是你填的那个地址、模型名是不是你填的那个、认证方式是否显示为 token。三项都对说明配置层没问题。第二步发一句最简单的对话。比如输入用一句话说明当前目录大概是什么类型的项目。这一步验证的是网络连通性和凭证有效性。如果这一步就报错问题一定在凭证或地址上不用往下查文件操作了。第三步让它读一个文件。输入读一下 package.json告诉我项目名和依赖数量。这一步验证的是工具调用链路——它需要发起一次文件读取操作然后基于读到的内容回答。如果对话能通但这一步失败说明模型对工具调用的支持有问题考虑换个模型试试。第四步让它改一个文件。找一个无关紧要的测试文件让它做个小改动比如在这个文件顶部加一行注释。这一步会触发权限确认弹窗你确认之后它才会真的写。写完之后你自己cat一下确认内容正确。这四步走完整个链路就通了。任何一步失败问题范围都能立刻缩小一半比一上来就跑大任务高效得多。4.2 报错定位按状态码分诊不同报错对应不同环节下面这张表是我整理的常见情况遇到问题可以直接对号入座。现象大概率原因处理方向401 / 认证失败密钥错误、密钥失效、变量名写错检查变量名是否为ANTHROPIC_AUTH_TOKEN重新复制密钥403 / 无权限模型未开通或密钥权限范围不含该模型去控制台确认开通状态和密钥范围404 / 地址不存在base url 拼错或端点路径已调整核对控制台文档中的最新地址提示模型不存在模型名大小写、连字符不一致逐字符比对控制台显示的名称请求超时网络到端点不通畅先用 curl 单独测端点连通性能对话但改文件失败模型工具调用能力不足换 coder 系列模型重试表格之外补充两个细节。第一变量名拼写是最隐蔽的坑。有人习惯写ANTHROPIC_API_KEY这个变量在走官方服务时是有效的但配合自定义端点时工具内部的校验逻辑可能对它有额外要求表现就是怎么都认不出凭证。遇到这种情况改用ANTHROPIC_AUTH_TOKEN通常能解决。第二环境变量有优先级。shell 里 export 的和 settings.json 里的会互相覆盖如果你两边都配了但值不一样最终生效的可能是你没想到的那一份。排查时先统一到一处别留两份。还有一个通用的排查手段用 curl 直接打端点把工具这一层剥掉。curl -X POST $ANTHROPIC_BASE_URL \ -H Authorization: Bearer $ANTHROPIC_AUTH_TOKEN \ -H Content-Type: application/json \ -d {model:$ANTHROPIC_MODEL,messages:[{role:user,content:hi}]}如果 curl 能通而工具不能通问题就在工具配置如果 curl 也不通问题就在凭证或地址。这一招能把排查范围一刀切两半我每次遇到玄学问题都先跑它。5. 长期用下去的几个习惯上下文、权限与成本接通只是开始真正决定这套东西好不好用的是日常使用习惯。这一节讲的都是我用了几个月之后总结出来的、文档里不太会写的部分。5.1 上下文管理CLAUDE.md 和清理时机Claude Code 启动时会读取项目根目录下的CLAUDE.md把里面的内容作为长期上下文。这个文件的价值在于把你反复要解释的东西固化下来。比如项目的技术栈、目录约定、代码风格、构建命令、不能碰的目录写进去之后就不用每次重复交代了。生成初稿很简单在项目根目录启动后输入/init它会扫描项目结构自动生成一份。但自动生成的只是起点一定要手动改。我的做法是把它压缩到一屏以内只保留三类信息必须遵守的约定、容易踩的坑、常用命令。写太长的后果是每次对话都占用大量上下文反而挤掉了真正有用的信息。除了 CLAUDE.md还有两个命令要养成习惯。/clear用来清空当前会话的上下文适合切换到完全不相关的新任务时用/compact用来压缩上下文适合同一个任务聊太久、历史太长的时候用。什么时候用哪个我的判断标准是任务切换用 clear任务延续但太长用 compact。搞反了会导致要么丢失必要的背景要么白白浪费上下文预算。5.2 权限模式与危险操作的边界Claude Code 默认对每个有副作用的操作写文件、执行命令都要求确认。这个设计一开始会觉得烦但它是必要的安全网。我在早期为了图快用过跳过确认的模式结果有一次它执行了一条删除命令虽然只是删了临时文件但那一刻的冷汗是真实的。我的建议是日常开发保持默认确认模式只在完全可控的沙箱环境里才考虑放宽。判断可控的标准很简单——这个目录里有没有不能丢的东西有就别放宽。另外有个很实用的功能值得用起来它支持先出方案再执行。你可以明确要求先告诉我你打算改哪些文件、每个文件改什么我确认后再动手。这个习惯在改动面比较大的任务里特别值能让你在动手之前就发现方向跑偏。5.3 把消耗压下来的几个动作走百炼的按量计费模式下成本控制是可以做得很细的。分享几个我实测有效的做法。第一把轻量任务分流到小模型。前面提到的ANTHROPIC_SMALL_FAST_MODEL就是干这个的很多内部的小判断用大模型跑纯属浪费切到小模型之后整体消耗能降下来一截。第二控制输入的文件范围。让它改一个函数不要让它读整个目录。指令里明确说只看 src/utils 下的文件比帮我优化一下项目省下的量级完全不是一个数量级。第三善用 plan 模式。在动手之前先让它出计划你审一遍再让它执行。这看起来多了一轮对话但能避免它朝着错误方向改一堆文件然后全部回滚——那才是真正的浪费。第四长会话及时压缩。上下文越长每一轮请求带上的 token 就越多成本是持续累积的。一个聊了两小时没清理过的会话单轮成本可能是刚开始时的好几倍。最后分享一个我自己的习惯给常用任务写几个固定的指令模板存在项目的CLAUDE.md或者一个单独的说明文件里。比如新增一个接口这个任务模板里写清楚要改哪几个文件、按什么顺序、遵循什么命名规范。用模板发起任务比每次自由发挥的产出稳定得多返工少消耗自然也少。这套东西跑顺之后终端里敲一句话就能完成过去要点十几次鼠标的活那种感觉确实不一样。
知识建站
内容驱动
阅读友好版式
SEO 精细化
线索转化