★ FEATURED ARTICLE 1. Mac 上跑 Claude Code 到底卡在哪从安装到首次会话的真实路径Claude Code 是 Anthropic 推出的终端 Agent 编码工具它没有图形界面所有交互都在命令行里完成。它能自动读取你的项目结构、理解上下文、直接改文件、跑测试、提交代码适合习惯用终端、又想让 AI 深度参与工程流程的 Mac 开发者。很多人第一次接触它卡点其实不在“会不会用”而在“装完之后怎么让它真正连上模型跑起来”。我见过太多人卡在三个地方Node 版本太老导致 npm 全局安装报错、环境变量写错文件导致claude启动后一直转圈、以及 Base URL 和 Key 配了但没生效。这篇就按“从零到跑通第一个会话”的顺序把每一步命令、每个配置文件、每条验证动作都写清楚你照着敲就行。先说清楚整体链路Mac 装 Node → npm 全局装 Claude Code → 拿到可用的 API Key 和 Base URL → 写进 shell 配置文件 → 重开终端验证变量 → 进项目目录运行claude→ 完成主题/信任目录初始化 → 用/init生成项目说明 → 发第一个需求。这条链路里环境变量是否生效和API 通道是否可达是两个最容易翻车的点后面会重点排。关于 API 通道Claude Code 默认走 Anthropic 官方但国内直连经常超时。这时候可以用兼容 Anthropic 协议的通道比如 TaoToken 提供的接入地址把ANTHROPIC_BASE_URL指过去Key 换成对应平台的 Key就能在同样的命令下跑通。下面所有配置我都会用这个通道做示例你换成自己的 Key 即可。2. TaoToken 前置准备拿到 Base URL 和 Key 再动手在写任何环境变量之前你得先有两样东西一个可用的 API Key和一个兼容 Anthropic 协议的 Base URL。Claude Code 读取的是ANTHROPIC_AUTH_TOKEN或ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL这两个变量前者是身份凭证后者是请求发往哪里。TaoToken 的接入地址是https://taotoken.net/api这个地址兼容 Anthropic 的 Messages 接口格式Claude Code 不需要改任何源码只要把 Base URL 指过来就行。Key 需要你登录后在控制台创建创建完复制那串sk-开头的字符串后面写进配置文件。具体操作路径打开https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_mac_install创建 API Key然后到https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_mac_install确认一下当前支持的模型 ID。Claude Code 默认会请求 Claude 系列模型如果你在 TaoToken 侧用的是别的模型名需要在配置里显式指定否则会报模型不存在。这里有个细节要注意Claude Code 会优先读ANTHROPIC_AUTH_TOKEN如果这个没设才回退到ANTHROPIC_API_KEY。两个都设的时候AUTH_TOKEN生效。所以你在配置文件里只写一个就行写两个反而容易搞混。我建议统一用ANTHROPIC_AUTH_TOKEN。另外如果你打算长期用 Claude Code 做编码和 Agent 任务可以看一下 Coding Plan 这类套餐https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_mac_install按量或包月看你自己的调用频率。短期验证的话先用按量 Key 跑通再说。拿到 Key 之后先别急着写文件先在终端里临时 export 一下确认通道能通再固化到配置文件。这样万一 Key 有问题你不用反复改文件。export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的Key然后直接跑一个最小请求验证通道curl -s $ANTHROPIC_BASE_URL/v1/messages \ -H x-api-key: $ANTHROPIC_AUTH_TOKEN \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-3-5-sonnet-20241022, max_tokens: 64, messages: [{role: user, content: ping}] }如果返回里能看到content字段和一段文本说明 Key 和 Base URL 都没问题。如果返回 401就是 Key 错了返回 404多半是模型 ID 不对连接超时就是 Base URL 写错或网络不通。这一步过了再往下装 Claude Code。3. 可复制配置Node 安装、Claude Code 安装与 shell 变量写入Mac 上装 Node 最省事的方式是用 Homebrew。如果你还没装 Homebrew先去官网按提示装好这里不展开。装完 Node 之后用 npm 全局安装 Claude Code。# 安装 Node已装可跳过 brew install node # 验证 Node 和 npm node -v npm -v # 全局安装 Claude Code npm install -g anthropic-ai/claude-code # 验证安装 claude --versionclaude --version能打印出版本号比如1.0.61 (Claude Code)就说明装好了。如果这一步报command not found多半是 npm 全局 bin 目录不在 PATH 里用npm config get prefix看一下路径把它加到 PATH 即可。接下来是关键的配置写入。Mac 从 Catalina 开始默认 shell 是 zsh所以配置文件是~/.zshrc。先确认你的 shellecho $SHELL输出/bin/zsh就写~/.zshrc输出/bin/bash就写~/.bash_profile。只写一个文件不要两个都写否则变量重复加载容易出怪问题。# zsh 用户执行这三行 echo -e \nexport ANTHROPIC_BASE_URLhttps://taotoken.net/api ~/.zshrc echo -e \nexport ANTHROPIC_AUTH_TOKENsk-你的Key ~/.zshrc echo -e \nexport ANTHROPIC_MODELclaude-3-5-sonnet-20241022 ~/.zshrc # 让配置立即生效 source ~/.zshrc如果你用的是 bash把上面的~/.zshrc换成~/.bash_profile即可。ANTHROPIC_MODEL这一行是可选的但建议写上避免 Claude Code 默认请求一个你通道里没有的模型。除了环境变量Claude Code 还支持项目级和用户级配置文件。用户级配置在~/.claude/settings.json项目级在项目根目录的.claude/settings.json。如果你想把模型和权限固化下来可以写一个 settings 文件{ model: claude-3-5-sonnet-20241022, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的Key }, permissions: { allow: [Bash(git status), Bash(npm test)], deny: [] } }这个文件放在~/.claude/settings.json就是全局生效放在项目里就是只对该项目生效。注意env里的变量会覆盖 shell 里的同名变量所以如果你两边都配了以 settings.json 为准。我一般建议 Key 放 shell 环境变量模型和权限放 settings.json这样换 Key 不用改项目文件。配置写完重开一个终端窗口验证变量是否真的加载了echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_AUTH_TOKEN echo $ANTHROPIC_MODEL三个都能打印出你写的值才算配置成功。如果打印为空说明写错了文件或者没 source回去检查。4. 验证请求与成功结果跑通第一个 Claude Code 会话变量验证通过后进你的项目目录启动 Claude Codecd your-project-folder claude第一次运行会走几个初始化步骤选主题上下箭头选回车确认、确认安全须知、选择默认 Terminal 配置、信任当前工作目录。这几步都按回车用默认值即可。完成后你会看到 Claude Code 的交互界面底部有输入框。第一个该敲的命令是/init。它会让 Claude Code 扫描你的项目结构生成一个CLAUDE.md文件里面记录项目说明、技术栈、常用命令。生成完它会问你是否写入文件选 yes 回车。生成的内容默认是英文你可以接着输入“把 CLAUDE.md 翻译成中文并写入”它会自己改。/init跑完你的项目根目录会多出一个CLAUDE.md。这个文件很关键之后每次启动 Claude Code 都会读它相当于给 AI 的项目说明书。你可以在里面补充构建命令、测试命令、代码规范AI 会照着执行。接下来发第一个真实需求验证它能不能改代码。比如输入帮我看一下 utils.py 里的 generate_test_cases 函数把 test_case_count 参数改成可选默认 None并在函数内部根据需求文本长度自动推荐数量。Claude Code 会先输出一段 Thinking列出它打算改哪些文件、改什么逻辑然后逐个执行 Read、Update 操作最后跑测试验证。你能在终端里看到它读了哪些行、改了哪些行、测试结果如何。整个过程不需要你手动把文件加进上下文它自己会找。如果它成功改完并跑了测试说明整条链路——安装、配置、通道、模型、工具调用——全部打通。这时候你可以试试更复杂的任务比如“给这个函数补单元测试并运行”或者“把这次改动提交成一个 commit”。它会调用 Bash 工具执行 git 命令你确认后才会真正提交。验证成功的标志有三个claude --version有输出、/init生成了CLAUDE.md、发需求后能看到文件被实际修改且测试通过。三个都满足你就可以正常用了。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth 报错对照配置过程中最容易遇到的几类报错我按实际出现频率排一下每条都给对照原因和解法。401 Unauthorized / invalid api keyKey 错了或者没生效。先echo $ANTHROPIC_AUTH_TOKEN确认变量有值再确认 Key 没有多余空格或换行。如果你用的是ANTHROPIC_API_KEY而不是ANTHROPIC_AUTH_TOKEN注意 Claude Code 的读取优先级建议统一用AUTH_TOKEN。还有一种情况是 Key 复制时带了引号写进配置文件后引号被当成值的一部分检查一下。local proxy failed / connection refusedBase URL 写错或通道不可达。确认ANTHROPIC_BASE_URL是https://taotoken.net/api不要多写/v1或少写/api。然后用第 2 节的 curl 命令单独测一下通道curl 通但 Claude Code 不通多半是 Claude Code 读到了别的配置比如 settings.json 里覆盖了 env检查~/.claude/settings.json。reading choices / unexpected response format通常是模型 ID 不对或者通道返回的不是 Anthropic 格式。确认ANTHROPIC_MODEL写的是你通道里真实存在的模型名。如果没设ANTHROPIC_MODELClaude Code 会用默认模型而默认模型可能在你通道里不存在就会解析失败。显式指定模型 ID 能解决大部分这类问题。OAuth / login requiredClaude Code 某些版本会尝试走 OAuth 登录流程如果你用的是 API Key 模式它不应该弹登录。出现这个说明它没读到你的 Key回退到了默认认证方式。检查环境变量是否在启动 Claude Code 的同一个 shell 里生效或者直接在~/.claude/settings.json的env里写死 Key。command not found: claudenpm 全局 bin 不在 PATH。npm config get prefix拿到路径把$PREFIX/bin加到~/.zshrc的 PATH 里source 后重试。Node 版本过低Claude Code 要求 Node 18 以上。node -v看一下低于 18 就用brew upgrade node升级。排查顺序建议先 curl 测通道 → 再 echo 测变量 → 再看 settings.json 有没有覆盖 → 最后看 Node 版本。按这个顺序走90% 的问题能定位到。6. 语义一致 CTA把通道和 Key 管好长期用起来跑通第一个会话之后真正影响体验的是通道稳定性和 Key 管理。Claude Code 会频繁发请求尤其是让它读多个文件、跑测试的时候一次任务可能几十个请求。如果通道不稳定你会看到大量重试和超时体验很差。我的做法是把 Key 放在 shell 环境变量里模型和权限放~/.claude/settings.json项目相关的说明放项目里的CLAUDE.md。这样换 Key 只改一处换项目不用动配置。如果你要管理多个 Key 或看调用量去控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_mac_install看用量和余额。想快速验证某个模型能不能用不用每次都开 Claude Code直接用模型对话页面测一下更快https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_mac_install。输入一句话看返回确认模型 ID 和通道都正常再回到终端配 Claude Code。如果你打算把 Claude Code 当成日常编码主力长期跑 Agent 任务Coding Plan 会比按量更划算具体看你的调用频率https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_mac_install。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_mac_install遇到协议细节可以对照查。最后提醒一句Claude Code 的权限配置别开太大。settings.json里的permissions.allow只放你信任的命令比如git status、npm test涉及删除、推送、发布的命令让它每次问你。终端 Agent 能直接操作文件系统权限收着点没坏处。
阅读完成 · 觉得有帮助？
