1. Ubuntu 下 Claude Code 安装配置全流程从环境准备到跑通 TaoTokenClaude Code 是 Anthropic 推出的命令行 AI 编程助手能直接在终端里读写项目文件、执行命令、跑测试适合习惯在 Linux 上做开发的工程师。如果你刚装好一台 Ubuntu 机器想把它接上统一的 Key/API 通道来用这篇会从 Node 环境一路写到实际对话验证。我试过在 Ubuntu 22.04 和 24.04 上各跑一遍踩过的坑主要集中在 Node 版本、npm 全局路径和配置文件字段这三处下面按顺序拆开讲。先说清楚它适合谁一是刚接触 Linux 命令行、想找个能自动改代码的助手的新手二是团队里已经用统一网关管理多家模型 Key、希望 Claude Code 也走同一出口的开发者。核心检索词就是 Ubuntu、Claude Code、安装配置全文围绕这三件事展开每一步都给可复制的命令和结果说明。整个流程分六段先讲为什么要在 Ubuntu 上单独配一遍再准备 TaoToken 的 Key 和 Base URL然后给可复制的安装与配置片段接着发一次真实请求验证再列常见报错对照最后给接入文档和 Coding Plan 的入口。你按顺序做大概二十分钟能跑通。1.1 为什么 Ubuntu 上要单独走一遍配置很多人以为 Claude Code 装完就能用其实它默认会去连官方端点而团队里通常希望所有请求走统一通道方便计费和切换模型。Ubuntu 和 macOS 的差异主要在 Node 安装方式、全局包路径和配置文件位置照搬 macOS 教程容易卡在claude: command not found或者配置文件读不到。另一个原因是 Ubuntu 服务器常常没有图形界面CC-Switch 这类带界面的工具需要额外处理依赖纯命令行环境下更推荐直接改配置文件。所以这篇的重点是「命令行可复制」每一步都能在 SSH 里粘贴执行。2. TaoToken 前置准备拿到 Base URL 和 API Key在装 Claude Code 之前先把通道信息准备好否则装完还要回头找。TaoToken 提供统一的 Key/API 通道官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置里填这个。你需要准备三样东西我把它叫「三件套」Base URL、API Key、Model ID。Base URL 就是上面那个 API 地址API Key 在控制台的 API Keys 页面生成地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite Model ID 填你要用的模型标识比如 Claude 系列的具体型号具体以控制台模型列表为准。提示Key 生成后只显示一次建议先复制到本地临时文件配置完再删掉。不要直接提交到 Git 仓库。如果你还没决定用哪个模型可以先在模型对话页面试一下地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 确认能正常返回再写进配置。这一步能省掉后面「配置写对了但模型名不对」的排查时间。2.1 三件套的填写位置对照配置项填什么在哪拿Base URLhttps://taotoken.net/api固定不带 UTMAPI Keysk- 开头的字符串控制台 API Keys 页Model ID具体模型标识控制台模型列表把这三样记下来下一节的配置文件里会分别对应到ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN和ANTHROPIC_MODEL三个环境变量。3. 可复制配置Node 环境、Claude Code 安装与 settings 片段这一节是全文最长的部分按顺序执行即可。先装 Node再装 Claude Code最后写配置文件。3.1 安装 nvm 与 Node 24Ubuntu 自带的 Node 版本往往偏低Claude Code 需要较新的运行时所以用 nvm 管理。执行下面这条安装脚本bash -c $(curl -fsSL https://gitee.com/RubyMetric/nvm-cn/raw/main/install.sh)装完加载配置source ~/.bashrc为了下载快一点配一下 Node 镜像源echo export NVM_NODEJS_ORG_MIRRORhttps://npmmirror.com/mirrors/node ~/.bashrc source ~/.bashrc然后装 Node 24nvm install 24验证一下node -v npm -v git --version三条命令分别应输出类似v24.x.x、10.x.x和git version 2.x.x。如果node -v报找不到命令多半是source ~/.bashrc没执行重新执行一次即可。3.2 配置 npm 镜像并安装 Claude Codenpm 默认源在国内较慢换成镜像npm config set registry https://registry.npmmirror.com/然后全局安装npm install -g anthropic-ai/claude-code验证安装claude --version能打印版本号就说明装好了。如果报EACCES权限错误不要用sudo npm install -g而是配置 npm 全局目录到用户目录或者直接用 nvm 管理的 Nodenvm 环境下全局包默认就在用户目录不会有权限问题。3.3 生成并编辑配置文件先启动一次让它生成配置骨架claude首次启动会走引导流程按提示走完或者直接 CtrlC 退出配置文件就生成了。Claude Code 的配置在~/.claude.json用编辑器打开vim ~/.claude.json在里面加上 onboarding 完成标记注意 JSON 语法上一个字段尾部要加英文逗号{ hasCompletedOnboarding: true }如果你已经有其他字段就在最后一个字段后面补逗号再加这一行。JSON 对逗号很敏感多一个少一个都会导致解析失败这是最常见的坑。3.4 写入 TaoToken 三件套环境变量可以写在~/.bashrc里也可以写进 Claude Code 的 settings。推荐写进 settings路径是~/.claude/settings.json内容如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的Key, ANTHROPIC_MODEL: 你的ModelID } }把sk-你的Key和你的ModelID替换成第 2 节拿到的值。Base URL 一定填https://taotoken.net/api不要带 UTM 参数也不要多加斜杠。注意ANTHROPIC_AUTH_TOKEN和ANTHROPIC_API_KEY是两个不同的变量Claude Code 读的是前者。填错变量名会出现 401排查时先看这里。如果你用 CC-Switch 管理多套配置它的界面里同样填这三项Base URL、Key、Model ID。CC-Switch 在 Ubuntu 上装 deb 包sudo dpkg -i CC-Switch-v3.14.1-Linux-x86_64.deb如果报依赖错误sudo apt-get install -f sudo dpkg -i CC-Switch-v3.14.1-Linux-x86_64.deb装完在终端执行cc-switch就能打开配置界面。把三件套填进去保存它会帮你写回配置文件。3.5 用 Codex auth.json 思路理解配置结构如果你之前配过 Codex会发现它的auth.json也是把 Key 和端点写在一个 JSON 里Claude Code 的 settings 逻辑类似只是字段名不同。理解这一点后换工具时就不会慌核心永远是 Base URL、Key、Model ID 三件套只是存放位置和变量名变了。4. 验证请求发一次真实对话确认配置生效配置写完重启终端让环境变量生效或者直接新开一个 SSH 会话。然后进入一个测试目录mkdir -p ~/claude-test cd ~/claude-test claude启动后输入一句简单的话比如「用 Python 写一个读取当前目录文件列表的脚本」。如果配置正确它会返回代码并询问是否写入文件。看到正常返回说明 Base URL、Key、Model 三项都通了。也可以直接用 curl 验证通道本身curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d {model:你的ModelID,max_tokens:64,messages:[{role:user,content:ping}]}返回 JSON 里带content字段就说明通道正常。这一步能把「Claude Code 配置问题」和「通道问题」分开排查时很有用。4.1 成功结果的判断标准对话模式下Claude Code 会显示它读取了哪些文件、准备执行什么命令最后给出结果。如果它一直转圈或者报连接错误先看第 5 节的报错对照。正常情况下从输入到返回在几秒内完成模型不同略有差异。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节按真实报错整理遇到问题直接对号入座。401 Unauthorized最常见。原因有三个一是ANTHROPIC_AUTH_TOKEN没填或填错二是 Key 已失效三是 Base URL 写成了带 UTM 的地址。检查 settings.json 里的三个字段确认 Key 是sk-开头且没有多余空格。local proxy failed / connection refused说明请求没发出去通常是 Base URL 写错比如漏了/api或者多了斜杠。正确写法是https://taotoken.net/api。另外检查机器能否正常访问外网curl -I https://taotoken.net/api看返回码。reading choices 相关报错这类多半是返回体格式和预期不符常见于 Model ID 填错通道返回了错误结构。去控制台模型列表核对 Model ID确认拼写一致。OAuth 相关提示Claude Code 首次启动可能引导登录官方账号如果你要走统一通道就在 settings 里配好ANTHROPIC_AUTH_TOKEN并在~/.claude.json里设hasCompletedOnboarding: true跳过引导。如果仍然弹 OAuth检查 settings.json 路径是否是~/.claude/settings.json不是~/.claude.json两个文件作用不同。claude: command not foundnvm 环境没加载执行source ~/.bashrc或者检查npm bin -g输出的目录是否在 PATH 里。JSON 解析错误~/.claude.json里逗号或引号写错。用python3 -m json.tool ~/.claude.json验证语法能打印格式化结果就说明合法。5.1 排查顺序建议先 curl 验证通道再验证 Claude Code 配置最后看模型名。这个顺序能把问题范围一步步缩小比一上来就改配置高效得多。6. 接入文档与长期使用入口配置跑通后日常使用就是cd到项目目录执行claude。如果你需要更详细的参数说明和接入方式接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各语言的调用示例。Key 管理在 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 可以随时生成新 Key 或吊销旧的。如果你打算长期用 Claude Code 做编码和 Agent 任务Coding Plan 更划算入口是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它按编码场景优化了配额适合每天都要跑代码生成和重构的人。想先试模型效果就去模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 直接聊几句。最后给一个实用技巧把~/.claude/settings.json备份一份换机器时直接复制过去只改 Key 就能用。Ubuntu 上多用户环境记得检查文件权限chmod 600 ~/.claude/settings.json避免 Key 被其他用户读到。