Ubuntu 20.04 上装 Claude Code 并接入 DeepSeek：从 Node.js 到 cc-switch 的完整配置

1. Ubuntu 20.04 装 Claude Code 接入 DeepSeek 到底难在哪

如果你在 Ubuntu 20.04 上搜「Claude Code 接入 DeepSeek」，大概率会撞上三堵墙：Node.js 版本太老跑不起来、官方 cc-switch 装完打不开、API 通道填完却一直 401。这篇就把这三件事一次讲透，从 Node.js 环境准备到 cc-switch 配置切换，再到终端里跑通一次真实请求，全程可复制。

先说清楚这套组合是什么。Claude Code 是 Anthropic 出的命令行编程助手，本质是一个跑在终端里的 Agent，能读你项目里的文件、执行命令、改代码。它默认连的是 Anthropic 官方通道，但通过环境变量或 cc-switch 这类配置切换工具，可以把请求指向兼容 Anthropic 协议的第三方通道。DeepSeek 提供了兼容接口，所以理论上能让 Claude Code 用上 DeepSeek 的模型。

适合谁看：手上有一台 Ubuntu 20.04 的机器（物理机、虚拟机、云主机都行），想用命令行 AI 编程助手，又不想被官方通道的额度和网络问题卡住的人。Ubuntu 20.04 是个特殊版本，它的 glib 和 webkit 版本偏旧，很多 2024 年之后基于 Tauri 2 打包的桌面工具都跑不起来，cc-switch 官方版就是典型受害者，这也是本文要专门处理的一个坑。

我试过在 20.04 上直接dpkg -i官方 cc-switch 的 deb 包，装是装上了，点图标没反应，终端启动报libwebkit2gtk-4.1.so.0: cannot open shared object file。原因就是 Tauri 2 依赖 webkit2gtk 4.1，而 20.04 的软件源里只有 4.0。硬升级 glib 会连带一堆系统库，风险太大，所以正确做法是换一个用 WebKit2GTK 4.0 重新打包的版本。

整篇的路线是：先装一个足够新的 Node.js（Claude Code 要求 18 以上，建议直接上 20 或 22），再全局装 Claude Code，然后装适配 20.04 的 cc-switch-web，配置好 DeepSeek 的 Base URL、Key 和 Model ID，最后在终端验证一次请求真的通了。每一步我都会给出完整命令和预期输出，你照着敲就行。

需要提前说明的是，本文用的是 TaoToken 提供的兼容通道来对接 DeepSeek，它的 API 地址是https://taotoken.net/api，控制台和密钥管理在官网。你需要在官网注册后拿到一个 API Key，后面配置里会用到。这个 Key 就是你的身份凭证，别泄露，也别提交到 git 仓库里。

2. 前置准备：Node.js 版本、TaoToken Key 与目录规划

这一节把动手前需要的东西一次性备齐，避免装到一半发现缺东西。核心是三样：合适版本的 Node.js、一个可用的 API Key、以及清晰的目录规划。

2.1 Node.js 为什么必须升级

Ubuntu 20.04 自带的 apt 源里 Node.js 是 10.x 或 12.x，太老了。Claude Code 的 npm 包在安装时会检查 engines 字段，低于 18 直接报Unsupported engine。所以别用apt install nodejs，用官方预编译包手动装，干净可控，也不污染系统。

我选的是 Node.js 22 的 LTS 线，稳定且兼容性好。下载走国内镜像会快很多：

cd ~ wget https://registry.npmmirror.com/-/binary/node/v22.14.0/node-v22.14.0-linux-x64.tar.xz tar -xvJf node-v22.14.0-linux-x64.tar.xz mv node-v22.14.0-linux-x64 ~/nodejs

解压后把~/nodejs作为安装目录。接着配置环境变量，编辑~/.bashrc：

nano ~/.bashrc

在文件最后一行加上（注意路径换成你自己的实际路径）：

export PATH="$HOME/nodejs/bin:$PATH"

保存后让它生效：

source ~/.bashrc node -v npm -v

预期输出类似v22.14.0和10.9.2。如果node -v还是老版本，说明 PATH 没生效，检查一下~/.bashrc里那行有没有写错，或者当前 shell 是不是 bash（echo $SHELL确认）。

2.2 拿到 TaoToken 的 API Key

打开官网https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=，注册登录后进控制台，在 API Keys 页面创建一个新 Key。创建时给它起个名字比如ubuntu-claude-code，方便以后区分。复制出来的 Key 形如sk-xxxxxxxx，只显示一次，先存到安全的地方。

这个 Key 后面要填进 cc-switch 的配置里，作为访问 DeepSeek 模型的凭证。同时你需要记住两个地址：Base URL 是https://taotoken.net/api，模型 ID 用 DeepSeek 对应的名称（比如deepseek-chat或deepseek-reasoner，以控制台模型列表为准）。

2.3 目录规划建议

建议把 Node.js 装在~/nodejs，项目代码放~/projects，配置文件交给 cc-switch 自己管理（它默认存在~/.cc-switch/或类似路径）。这样以后要卸载或迁移，删目录就行，不会散落一地。

注意：API Key 不要写进任何会提交到 git 的文件。cc-switch 的配置文件本身在用户目录下，一般不会被 git 跟踪，但你自己写脚本时要注意。

到这里前置就齐了：Node.js 22 装好、Key 拿到手、目录心里有数。下一节开始装 Claude Code 本体。

3. 安装 Claude Code 与 cc-switch-web 的可复制配置

这一节是全文的技术核心，分三步：装 Claude Code、装适配 20.04 的 cc-switch-web、写配置文件。每一步都给完整命令和配置片段。

3.1 全局安装 Claude Code

Node.js 就绪后，一条命令搞定：

npm install -g @anthropic-ai/claude-code

装完验证：

claude --version

能打印出版本号就说明二进制已经进 PATH 了。如果报command not found，检查npm config get prefix输出的路径是否在 PATH 里，通常全局包会装到~/nodejs/bin，和 node 同目录，正常不会有问题。

第一次直接运行claude会进入一个初始化引导，让你选主题、确认一些设置。这一步先别急着配通道，因为默认它连的是 Anthropic 官方，国内环境大概率连不上。我们要先用 cc-switch 把通道切到 DeepSeek，再回来启动。

3.2 为什么官方 cc-switch 在 20.04 上装不了

官方 cc-switch 用 Tauri 2 打包，依赖libwebkit2gtk-4.1-dev和glib >= 2.70。Ubuntu 20.04 的仓库里 webkit2gtk 只到 4.0，glib 是 2.64，两个都不满足。你强行apt install libwebkit2gtk-4.1-dev会提示找不到包，加第三方源又可能把系统库搞乱。

解决办法是用社区重新打包的cc-switch-web，它把前端渲染从 Tauri 换成了 WebKit2GTK 4.0 原生窗口，业务逻辑保留，20.04 开箱即用。下载安装：

curl -sL https://github.com/greluoqixi/cc-switch-web/releases/download/v1.0.0/cc-switch-web_1.0.0_amd64.deb -o cc-switch-web_1.0.0_amd64.deb sudo dpkg -i cc-switch-web_1.0.0_amd64.deb

如果dpkg报依赖缺失，补一条：

sudo apt-get install -f

装完在终端输入cc-switch-web就能启动，也可以双击桌面图标。启动后是一个图形界面，用来管理不同的 API 通道配置。

3.3 写 cc-switch 配置：Base URL + Key + Model ID 三件套

cc-switch 的核心作用就是帮你管理多套「Base URL + Key + Model ID」组合，一键切换。在它的界面里新增一个配置，填三个字段：

如果你更喜欢直接改配置文件，cc-switch 的配置一般落在~/.cc-switch/config.json（不同版本路径可能略有差异，以界面里「打开配置目录」为准）。一个可参考的 JSON 片段如下：

{ "providers": [ { "name": "deepseek-via-taotoken", "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的Key", "model": "deepseek-chat" } ], "current": "deepseek-via-taotoken" }

保存后在界面里把当前通道切到deepseek-via-taotoken。cc-switch 会把这份配置同步到 Claude Code 读取的环境变量或配置文件里，具体机制是它帮你写~/.claude/settings.json或设置ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY这类变量。

注意：Model ID 一定要和控制台里列出的名称完全一致，大小写、连字符都不能错。填错会报模型不存在的错误。

配置完成后，回到终端运行claude，它会读取切换后的通道。第一次可能还会让你确认信任当前目录，按提示走即可。

4. 验证请求：确认 DeepSeek 通道真的通了

配置写完不代表通了，必须发一次真实请求验证。这一节给你两种验证方式：命令行直接问一句，以及看返回结构确认走的是 DeepSeek。

4.1 用 claude 交互式验证

在终端进入任意一个项目目录，运行：

cd ~/projects claude

进入交互界面后，输入一句简单的话，比如「用一句话解释什么是递归」。如果通道配对了，几秒内会返回 DeepSeek 生成的回答。这时候你观察两点：一是回答能正常流式输出，二是没有报 401 或连接超时。

如果它一直卡在思考状态或者报错，先退出（Ctrl+C），检查 cc-switch 里当前选中的是不是你刚建的那套配置。

4.2 用 curl 直接打接口验证

图形界面有时候会骗你，最硬的验证是直接打 API。用 curl 发一个最小请求：

curl https://taotoken.net/api/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: sk-你的Key" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "deepseek-chat", "max_tokens": 64, "messages": [{"role": "user", "content": "说一句你好"}] }'

预期返回是一段 JSON，里面有content数组，第一项的text字段就是模型回复。如果返回{"error": ...}，看错误类型：authentication_error是 Key 问题，not_found_error是模型 ID 或路径问题。

这个 curl 能通，说明 Base URL、Key、Model ID 三件套都对，Claude Code 那边只要配置同步到位就一定能用。

4.3 确认走的是 DeepSeek 而不是别的

有个小技巧：DeepSeek 的模型在回答风格上有自己的特点，你可以问一个需要推理的问题，比如「9.11 和 9.9 哪个大」，观察它的推理过程。另外在返回的 JSON 里，model字段会回显实际调用的模型名，确认它是deepseek-chat而不是别的。

如果返回的model字段和你填的不一致，说明通道那边做了映射，以控制台文档说明为准，一般不影响使用。

验证通过后，你就可以在日常项目里用claude命令干活了。它会读取当前目录的代码，帮你改 bug、写测试、解释逻辑。

5. 常见报错排查：401、local proxy failed 与 reading choices

这一节把最容易撞的几类错误列出来，对照着查。这些报错我在配置过程中基本都遇到过，按顺序排查能省不少时间。

5.1 401 authentication_error

最常见。表现是请求返回401或authentication_error。原因通常是三个：Key 复制时多了空格或换行、Key 已经失效或被删、请求头字段名写错。

排查步骤：先用上面 4.2 的 curl 单独测 Key，排除 Claude Code 本身的干扰。如果 curl 也 401，回控制台重新生成一个 Key，复制时注意别带上首尾空白。如果 curl 通了但 claude 报 401，说明 cc-switch 没把配置同步过去，检查~/.claude/settings.json里的ANTHROPIC_API_KEY是不是旧值。

5.2 local proxy failed / connection refused

报local proxy failed或connection refused，一般是 cc-switch 或某个本地代理进程没起来，或者端口被占用。先确认 cc-switch-web 进程在跑：

ps aux | grep cc-switch

如果没有，重新启动cc-switch-web。如果它监听了某个本地端口而 Claude Code 去连那个端口，端口被别的程序占了也会失败。换个端口或关掉冲突程序。

还有一种情况是系统里残留了旧的代理环境变量，比如http_proxy、https_proxy指向了一个已经关掉的本地端口。检查：

env | grep -i proxy

如果有，unset http_proxy https_proxy清掉再试。

5.3 reading choices / 流式解析错误

报reading choices或类似的流式解析错误，通常发生在通道返回的响应格式和 Claude Code 期望的不完全一致时。Claude Code 期望的是 Anthropic 的 messages 格式（content数组），如果通道返回的是 OpenAI 的choices格式，就会解析失败。

解决办法是确认你用的 Base URL 是 Anthropic 兼容端点。TaoToken 的https://taotoken.net/api提供兼容 Anthropic 协议的接口，路径是/v1/messages。如果你误填了 OpenAI 风格的/v1/chat/completions，就会出这个错。回 cc-switch 检查 Base URL 和路径。

5.4 OAuth 相关报错

如果报 OAuth 或登录相关错误，说明 Claude Code 还在尝试走官方登录流程。这时候要确保环境变量ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY已经设置，让它跳过 OAuth。可以在~/.bashrc里显式导出：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的Key"

然后source ~/.bashrc再启动 claude。注意这种方式和 cc-switch 管理可能冲突，二选一即可，推荐用 cc-switch 统一管理。

5.5 模型不存在 / model not found

报模型不存在，九成是 Model ID 拼错。回控制台看模型列表，复制准确名称。DeepSeek 常见的 ID 是deepseek-chat（通用对话）和deepseek-reasoner（推理增强），别自己造名字。

排查完这些，基本能覆盖 95% 的接入问题。如果还不行，把 curl 的完整返回贴出来，错误信息里通常有明确线索。

6. 后续怎么用：把 Claude Code 变成日常编码搭子

通道通了之后，真正的价值在于日常怎么用它。这一节聊几个实用场景和长期使用的建议。

最直接的用法是在项目根目录跑claude，然后用自然语言描述需求，比如「这个函数有内存泄漏，帮我看看」「给这个模块补单元测试」。它会读文件、给 diff、甚至直接改。改之前它会问你确认，别一路回车，看清楚再同意。

如果你经常在多个通道之间切换（比如官方和 DeepSeek 换着用），cc-switch 的价值就体现出来了。建好几套配置，点一下切换，不用手动改环境变量。对于长期做 Agent 开发或需要稳定编码助手的场景，可以考虑用 Coding Plan 这类方案，把额度和通道管理得更省心。

密钥管理要养成习惯：定期在控制台轮换 Key，旧 Key 及时删除。不要把 Key 写进项目代码或 Dockerfile。如果团队协作，每个人用自己的 Key，别共用。

想验证不同模型的效果，可以到模型对话页面直接对比 DeepSeek 和其他模型对同一段代码的解释，找到最适合你工作流的那个。接入文档里有更详细的参数说明和端点列表，遇到协议层面的问题去那里查最快。

最后给个实用技巧：把常用的 claude 调用封装成 shell 别名，比如alias cc='claude --dangerously-skip-permissions'（谨慎使用跳过权限的选项，只在你信任的目录里用）。日常在~/projects下开一个终端，随时claude一下，比开编辑器插件还快。整套流程跑通一次之后，换机器或重装系统，照着这篇的命令重来一遍，十分钟就能恢复。