linux/mac/wsl 如何使用 Claude Code 并配置免费的硅基流动 API？（官方的需要付费订阅）

1. 三端跑通 Claude Code 的真实门槛在哪Claude Code 是 Anthropic 推出的终端级编码 Agent能直接读写你当前项目目录、执行 shell 命令、跑测试、改文件交互方式就是敲自然语言。它适合谁适合已经在 Linux、macOS 或 WSL 里写代码、又不想在 IDE 里来回切窗口的人。核心检索词先摆出来linux/mac/wsl 如何使用 Claude Code 并配置免费的硅基流动 API本质就是解决两件事——装得上、连得通。装得上不难官方给了 npm 全局包一条命令的事。难的是连得通。Claude Code 默认走 Anthropic 官方通道而官方 Pro/Max 订阅是付费的对只想先试试水的人不友好。于是社区里最常见的做法是把 Claude Code 的请求地址Base URL指向一个兼容 Anthropic Messages 协议的服务用第三方 Key 驱动它。硅基流动SiliconFlow就是被提得最多的一个它提供了一批开源模型的 Anthropic 兼容端点注册后能拿到免费额度跑 Kimi、Qwen、DeepSeek 这类模型做日常编码辅助够用。但这里有个坑要先说清楚Claude Code 对自定义模型的支持是有限的。它读的是环境变量ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY、ANTHROPIC_MODEL你没法在同一个会话里挂多个模型来回切想换模型只能改环境变量再重启。这一点在后面的排障章节会反复出现先记住。三端的差异主要在环境变量持久化的位置Linux 和 WSL 走~/.bashrc或~/.zshrcmacOS 默认是 zsh走~/.zshrc。WSL 还要注意它和 Windows 宿主的环境隔离别把变量写到 Windows 那边去了。下面按先装、再配、后验的顺序走一遍每一步都给可复制的片段。我试过在 Ubuntu 22.04、macOS Sonoma 和 WSL2 Ubuntu 上各跑一遍流程基本一致差异点会单独标出来。整篇不涉及任何网络加速工具所有地址都是服务商公开的 API 端点直接填就行。2. 装 Claude Code 与准备硅基流动 Key2.1 三端安装 Claude CodeClaude Code 通过 npm 分发前提是本机有 Node.js 18 以上。先确认版本node -v npm -v如果 node 版本低于 18Linux/WSL 建议用 nvm 装curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20macOS 用 Homebrew 更省事brew install nodeNode 就绪后全局安装 Claude Codenpm install -g anthropic-ai/claude-code装完验证claude --version能打印版本号就说明二进制到位了。WSL 用户注意如果你在 Windows 侧也装了 Node别混用which node确认指向的是 WSL 里的/usr/bin/node或 nvm 路径而不是/mnt/c/...。2.2 拿硅基流动 API Key打开硅基流动控制台注册后在API 密钥页面新建一个 Key形如sk-xxxxxxxx。复制下来先存到记事本后面要填进环境变量。免费额度通常在注册后自动到账具体额度以控制台显示为准这里不编造数字。同时记下你要用的模型 ID。硅基流动的模型名是厂商/模型格式比如moonshotai/Kimi-K2-Instruct-0905、Qwen/Qwen2.5-Coder-32B-Instruct这类。模型 ID 一定要和控制台里列出的完全一致大小写错了会直接报模型不存在。2.3 备选通道TaoToken 统一 Key如果你后面想换一个统一入口管理 Key或者硅基流动的免费额度用完了想切别的模型可以把 Base URL 改到 TaoToken 的 API 通道。它的地址是https://taotoken.net/api同样兼容 Anthropic 协议Key 在控制台的 API Keys 页面生成。这一步不是必须的但作为备选方案先记下来配置方式和硅基流动完全一样只换 URL 和 Key。3. 三端可复制的环境变量与配置文件这一节是重点直接给能粘贴的片段。核心就三个变量ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY、ANTHROPIC_MODEL。3.1 临时生效三端通用先验证用在终端里直接 export只对当前会话有效关掉就没了。适合先试通再持久化export ANTHROPIC_BASE_URLhttps://api.siliconflow.cn/ export ANTHROPIC_API_KEYsk-你的硅基流动Key export ANTHROPIC_MODELmoonshotai/Kimi-K2-Instruct-0905注意 Base URL 结尾的斜杠硅基流动的端点带斜杠别漏。3.2 Linux 持久化写进 ~/.bashrc临时变量重启终端就丢永久生效要写进 shell 配置文件。Linux 默认 bashecho export ANTHROPIC_BASE_URLhttps://api.siliconflow.cn/ ~/.bashrc echo export ANTHROPIC_API_KEYsk-你的硅基流动Key ~/.bashrc echo export ANTHROPIC_MODELmoonshotai/Kimi-K2-Instruct-0905 ~/.bashrc source ~/.bashrc如果你用的是 zsh把~/.bashrc换成~/.zshrc。3.3 macOS 持久化写进 ~/.zshrcmacOS 从 Catalina 起默认 shell 是 zsh所以写~/.zshrcecho export ANTHROPIC_BASE_URLhttps://api.siliconflow.cn/ ~/.zshrc echo export ANTHROPIC_API_KEYsk-你的硅基流动Key ~/.zshrc echo export ANTHROPIC_MODELmoonshotai/Kimi-K2-Instruct-0905 ~/.zshrc source ~/.zshrc3.4 WSL 持久化同样写 ~/.bashrcWSL 里就是标准 Ubuntu写~/.bashrc即可和 Linux 一致echo export ANTHROPIC_BASE_URLhttps://api.siliconflow.cn/ ~/.bashrc echo export ANTHROPIC_API_KEYsk-你的硅基流动Key ~/.bashrc echo export ANTHROPIC_MODELmoonshotai/Kimi-K2-Instruct-0905 ~/.bashrc source ~/.bashrc3.5 用 settings.json 管理可选更干净Claude Code 也支持项目级或用户级配置文件。用户级配置在~/.claude/settings.json可以这样写{ env: { ANTHROPIC_BASE_URL: https://api.siliconflow.cn/, ANTHROPIC_API_KEY: sk-你的硅基流动Key, ANTHROPIC_MODEL: moonshotai/Kimi-K2-Instruct-0905 } }这个文件的好处是环境变量和 shell 解耦换终端也不受影响。注意 JSON 不能有注释Key 别带多余空格。3.6 切到 TaoToken 通道想换成 TaoToken 统一 Key只改两处export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的TaoToken Key export ANTHROPIC_MODEL你的模型ID模型 ID 以 TaoToken 控制台文档里列出的为准。三件套Base URL Key Model ID必须同时对上缺一个都会连不通。4. 验证请求与成功结果配完别急着写代码先验证通道是否真的通。4.1 检查环境变量是否生效echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_MODEL能打印出你填的值就对了。如果为空说明 source 没执行或写错了文件。4.2 发起一次对话进入任意项目目录启动cd ~/your-project claude第一次启动会问一些初始化问题按提示走。然后直接输入一句帮我看看当前目录下有哪些文件并解释 package.json 的作用如果配置正确Claude Code 会调用你指定的模型读取目录、返回文件列表和分析。这一步能跑通说明 Base URL、Key、Model 三件套全部生效。4.3 验证读取项目文件再试一条涉及文件读写的读取 README.md 的前 20 行总结这个项目是做什么的模型能准确说出 README 内容说明它确实拿到了项目上下文而不是空转。4.4 切换模型验证想换模型改ANTHROPIC_MODEL后重启 claudeexport ANTHROPIC_MODELQwen/Qwen2.5-Coder-32B-Instruct claude再问一句代码问题观察响应风格变化。注意Claude Code 不支持会话内热切换模型必须重启进程这是它的设计限制不是配置错误。4.5 成功结果的判断标准一次成功的请求终端里会看到模型流式输出的文字没有红色报错没有卡住不动。如果出现API Error或长时间无响应直接跳到下一节排障。5. 本篇常见错排查5.1 401 Unauthorized最常见。原因通常是 Key 错了、Key 前后有空格、或者 Key 和 Base URL 不匹配比如拿硅基流动的 Key 去连 TaoToken 的地址。排查echo $ANTHROPIC_API_KEY | cat -A看有没有多余的^M或空格。重新复制 Key确保和 Base URL 是同一家的。5.2 local proxy failed / connection refused这个报错说明请求根本没发出去通常是 Base URL 写错或者本机有残留的代理环境变量在捣乱。检查env | grep -i proxy如果有http_proxy、https_proxy之类先 unset 掉再试unset http_proxy https_proxy all_proxy注意这里只是清理本机可能存在的代理变量不涉及任何网络工具的使用。5.3 reading choices 相关报错这个报错一般出现在响应格式不符合预期时多半是 Base URL 指向了一个 OpenAI 格式的端点而 Claude Code 要的是 Anthropic Messages 格式。确认你填的是硅基流动或 TaoToken 的 Anthropic 兼容地址而不是它们的 OpenAI 兼容地址。两者路径不同别混。5.4 OAuth / 登录循环如果 Claude Code 一直让你登录 Anthropic 账号说明它没读到你的环境变量还在走官方通道。检查~/.claude/settings.json是否被官方登录信息覆盖或者环境变量是不是写到了错误的 shell 文件比如 macOS 写进了.bashrc但实际用 zsh。用echo $SHELL确认当前 shell。5.5 模型不存在 / model not found模型 ID 拼错或者该模型在你的账号下没有权限。回到控制台复制准确的模型 ID注意大小写和斜杠。硅基流动的模型名区分大小写Kimi-K2和kimi-k2不是一回事。5.6 WSL 里变量在 Windows 终端不生效WSL 和 Windows 是两套环境。你在 WSL 的~/.bashrc里配的变量只在 WSL 终端里有效。如果你在 Windows 的 PowerShell 里跑 claude那是另一个环境需要单独配。建议统一在 WSL 里操作。5.7 三件套对照表变量作用硅基流动示例TaoToken 示例ANTHROPIC_BASE_URL请求地址https://api.siliconflow.cn/https://taotoken.net/apiANTHROPIC_API_KEY鉴权 Keysk-硅基流动KeyTaoToken KeyANTHROPIC_MODEL模型 IDmoonshotai/Kimi-K2-Instruct-0905控制台文档所列任何一次接入失败先按这张表逐项核对八成问题出在某一项对不上。6. 后续怎么用得更顺跑通之后几个实用习惯能省不少事。第一把常用模型 ID 记成 shell 别名切换时一条命令搞定alias cc-kimiexport ANTHROPIC_MODELmoonshotai/Kimi-K2-Instruct-0905 claude alias cc-qwenexport ANTHROPIC_MODELQwen/Qwen2.5-Coder-32B-Instruct claude第二项目级配置优先用~/.claude/settings.json比改 shell 文件干净换机器也好迁移。第三免费额度有限写代码时把大任务拆小别一次性让它读整个仓库既省额度又快。如果你后面想统一管理多个模型的 Key或者需要更稳定的编码 Agent 通道可以了解下 TaoToken 的 Coding Plan地址在 https://taotoken.net/api Key 和模型在控制台里配。接入文档在 https://taotoken.net/api-keys 和 https://taotoken.net/doc 有详细说明模型对话入口在 https://taotoken.net/chat 。这些入口按需取用核心还是先把上面三端的环境变量跑通剩下的都是换 URL 和 Key 的事。