1. Ubuntu 上跑 Claude Code为什么先要解决「通道」问题如果你刚装好 Ubuntu想用 Claude Code 做点实际编码大概率会卡在第一步Claude Code 默认走 Anthropic 官方接口而国内网络环境下直连经常超时装完也调不通。我试过最省事的思路是把它接到一个统一的 API 通道上用 TaoToken 的 Key 做鉴权再通过本地 LiteLLM 网关把 Anthropic 协议转成 OpenAI 兼容协议这样 Claude Code 就能正常发请求了。这篇面向 Ubuntu 新手从零把 Node.js/npm 环境、Claude Code 安装、TaoToken 统一 Key 接入、settings.json 骨架、连通性验证一次跑通。适合谁刚接触 Linux、想用 Claude Code 但被网络和配置劝退的人已经装了 Node 但不知道 settings.json 怎么写的人以及想用一套 Key 同时切多个模型的人。核心检索词就三个Ubuntu、Claude Code、npm外加 LiteLLM 和 Node.js 这两个关键依赖。整个链路是这样的Claude Code客户端→ 本地 LiteLLM协议转换 统一出口→ TaoToken统一 Key/API 通道→ 底层模型。你只需要在 Ubuntu 上把这条链路搭起来之后日常就是两条命令一条起网关一条起 Claude Code。2. 前置准备TaoToken 统一 Key 与 API 通道在动手装环境之前先把「钥匙」拿到手否则后面配置 settings.json 时还得回头补。TaoToken 在这里扮演的是统一 API 通道的角色你拿到一个 API Base 和一个 Key就能通过它访问底层模型不用为每个模型单独配一套凭证。第一步打开官网注册并登录https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content第二步进入控制台创建 API Key。路径是 console 页面登录后找到 API Keys 入口https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite创建完你会得到两样东西一个 API Base形如https://taotoken.net/api和一个以sk-开头的 Key。把它们先记在记事本里后面第 4 节写环境变量要用。注意 API 地址不带 UTM 参数就是干净的https://taotoken.net/api。如果你还不确定要接哪个模型可以先去模型对话页面看看有哪些可用模型确认底层模型名再回来配https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite注意Key 只显示一次创建后立刻复制保存。丢了只能重新建一个。3. 可复制配置Node.js 环境 Claude Code 安装Ubuntu 新手最容易踩的坑是系统自带的 Node 版本太老。Claude Code 的 npm 安装要求 Node.js 18 或更高Ubuntu 22.04 仓库里的 Node 往往只有 12 或 16所以直接用 nvm 装一个 20 更稳。先装系统依赖这一步把 curl、git、编译工具都备齐sudo apt update sudo apt install -y curl git jq python3 python3-venv python3-pip ca-certificates gnupg接着装 nvm 并安装 Node 20curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 nvm alias default 20验证一下版本两个命令都要能看到 20.xnode -v npm -v which node which npm如果node -v还是老版本说明source ~/.bashrc没生效重新执行一次再nvm use 20。确认无误后安装 Claude Codenpm cache clean --force npm install -g anthropic-ai/claude-code这一步网络原因可能比较慢耐心等。装完验证which claude claude --version claude doctorclaude doctor会输出环境自检结果能看到版本号和配置路径就说明客户端本身没问题。接下来装 LiteLLM 做协议转换用独立虚拟环境避免污染系统 Pythonmkdir -p $HOME/ai-gateway python3 -m venv $HOME/litellm_env source $HOME/litellm_env/bin/activate python -m pip install --upgrade pip pip install litellm[proxy] httpx[socks]4. settings.json 骨架与 LiteLLM 配置Claude Code 的行为由~/.claude/settings.json和环境变量共同决定。新手最容易乱的地方是同时设了ANTHROPIC_AUTH_TOKEN和ANTHROPIC_API_KEY导致 auth conflict。当前方案只保留前者settings.json 先清成空对象把控制权交给启动脚本。先把旧配置备份并重置mkdir -p $HOME/.claude/backup cp $HOME/.claude/settings.json $HOME/.claude/backup/settings.json.bak 2/dev/null || true printf {}\n $HOME/.claude/settings.json rm -f .claude/settings.json rm -f .claude/settings.local.json然后写入环境变量把两个占位值换成你自己的 API Base 和 Keygrep -q export TAOTOKEN_API_BASE ~/.bashrc || echo export TAOTOKEN_API_BASEhttps://taotoken.net/api ~/.bashrc grep -q export TAOTOKEN_API_KEY ~/.bashrc || echo export TAOTOKEN_API_KEY你的Key ~/.bashrc grep -q export LITELLM_MASTER_KEY ~/.bashrc || echo export LITELLM_MASTER_KEYsk-litellm-local ~/.bashrc grep -q export NO_PROXY ~/.bashrc || echo export NO_PROXY127.0.0.1,localhost ~/.bashrc grep -q export no_proxy ~/.bashrc || echo export no_proxy127.0.0.1,localhost ~/.bashrc source ~/.bashrc检查三个变量都读到了echo $TAOTOKEN_API_BASE echo $TAOTOKEN_API_KEY echo $LITELLM_MASTER_KEY接着写 LiteLLM 的 config.yaml把统一 Key 映射成 Claude Code 认识的模型名cat $HOME/ai-gateway/config.yaml EOF model_list: - model_name: gpt-4-qwen litellm_params: model: openai/qwen-plus api_base: os.environ/TAOTOKEN_API_BASE api_key: os.environ/TAOTOKEN_API_KEY - model_name: gpt-4-glm litellm_params: model: openai/glm-4 api_base: os.environ/TAOTOKEN_API_BASE api_key: os.environ/TAOTOKEN_API_KEY litellm_settings: drop_params: true general_settings: master_key: os.environ/LITELLM_MASTER_KEY EOF这里drop_params: true很关键上游模型不支持某些 Anthropic 特有参数时LiteLLM 会自动丢弃而不是报 400。model_name是你在 Claude Code 里/model后面写的名字model是底层真实模型名按你 TaoToken 账号实际支持的填。5. 验证请求从 /v1/models 到 Claude Code 对话配置写完必须验证否则你不知道是网关没起还是 Key 错了。先写一个启动脚本mkdir -p $HOME/bin cat $HOME/bin/start-litellm.sh EOF #!/usr/bin/env bash set -euo pipefail source $HOME/.bashrc source $HOME/litellm_env/bin/activate exec litellm --config $HOME/ai-gateway/config.yaml EOF chmod x $HOME/bin/start-litellm.sh再写一个检查脚本它会依次测/v1/models和/v1/messagescat $HOME/bin/check-litellm.sh EOF #!/usr/bin/env bash set -euo pipefail source $HOME/.bashrc curl --noproxy * -fsS -H Authorization: Bearer ${LITELLM_MASTER_KEY} \ http://127.0.0.1:4000/v1/models /dev/null echo [OK] /v1/models 可访问 curl --noproxy * -s -X POST http://127.0.0.1:4000/v1/messages \ -H Authorization: Bearer ${LITELLM_MASTER_KEY} \ -H Content-Type: application/json \ -H anthropic-version: 2023-06-01 \ -d {model:gpt-4-qwen,max_tokens:64,messages:[{role:user,content:你好}]} | head -c 500 EOF chmod x $HOME/bin/check-litellm.sh最后写 Claude Code 启动脚本把 Anthropic 相关环境变量指向本地网关cat $HOME/bin/start-claude-code.sh EOF #!/usr/bin/env bash set -euo pipefail source $HOME/.bashrc export ANTHROPIC_BASE_URLhttp://127.0.0.1:4000 export ANTHROPIC_AUTH_TOKEN${LITELLM_MASTER_KEY} export ANTHROPIC_DEFAULT_SONNET_MODELgpt-4-qwen export ANTHROPIC_DEFAULT_HAIKU_MODELgpt-4-qwen export NO_PROXY127.0.0.1,localhost unset ANTHROPIC_API_KEY cd ${1:-$(pwd)} exec claude --model gpt-4-qwen EOF chmod x $HOME/bin/start-claude-code.sh加别名方便日常调用grep -q alias llmup ~/.bashrc || echo alias llmup$HOME/bin/start-litellm.sh ~/.bashrc grep -q alias llmcheck ~/.bashrc || echo alias llmcheck$HOME/bin/check-litellm.sh ~/.bashrc grep -q alias ccup ~/.bashrc || echo alias ccup$HOME/bin/start-claude-code.sh ~/.bashrc source ~/.bashrc联调分两个终端。终端 1 执行llmup启动网关看到监听 4000 端口即可。终端 2 执行llmcheck输出里出现[OK] /v1/models 可访问和一段 JSON 响应说明网关和 TaoToken 通道都通了。然后终端 2 进项目目录执行ccup在 Claude Code 里输入「你好」再输入「请先阅读当前项目结构告诉我主要目录和入口文件」。如果 LiteLLM 窗口出现POST /v1/messages ... 200 OK整条链路就跑通了。6. 本篇常见报错排查根分区满表现是No space left on deviceapt 和 npm 都会失败。先清缓存sudo rm -rf /var/cache/apt/archives/*.deb再df -h /看剩余空间。虚拟机场景下根分区太小是高频问题扩容前先确认lsblk里磁盘已变大。Node 版本过低node -v显示 12 或 16说明 nvm 没生效。重新source ~/.bashrc再nvm use 20必要时nvm alias default 20固定默认版本。Claude Code 安装卡住npm 安装超过 5 分钟没动静通常是异常。先npm cache clean --force若残留目录冲突再rm -rf ~/.nvm/versions/node/*/lib/node_modules/anthropic-ai/claude-code后重装。/v1/models 返回 401因为启用了 master_key访问 LiteLLM 必须带Authorization: Bearer $LITELLM_MASTER_KEY。检查脚本里是否漏了这个头。auth conflictClaude Code 提示认证冲突说明同时设了ANTHROPIC_AUTH_TOKEN和ANTHROPIC_API_KEY。当前方案只保留前者启动脚本里已经unset ANTHROPIC_API_KEY确认没在别处又导出。上游报 400多半是 Anthropic 特有参数不被底层模型支持。保留litellm_settings: drop_params: true即可自动丢弃。切换模型在 Claude Code 里直接/model gpt-4-glm前提是 config.yaml 里配了对应model_name且 TaoToken 账号支持该底层模型。排障和接入细节可以对照官方文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你打算长期用 Claude Code 做编码或接 Agent建议直接看 Coding Plan比按量调用更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite日常三条命令记住就够终端 1llmup起网关终端 2ccup进项目起 Claude Code出问题先llmcheck看链路。Key 和 Base 只在第 2 节拿一次之后所有模型切换都在 Claude Code 里用/model完成不用反复改配置。