把 Claude Code 接入 DeepSeek V4-Flash（Ubuntu / Debian / Alpine 配置教程）

一、这篇文章教你做什么

Claude Code 是 Anthropic 官方推出的终端 AI 编程助手，在终端里敲 claude 就能对话、写代码、改文件。它默认走 Anthropic 官方账号和官方模型（Claude 系列），需要订阅或付费。

DeepSeek 官方提供了一个 Anthropic 兼容接口（https://api.deepseek.com/anthropic），只要改几个环境变量，就能让 Claude Code 这个「壳」去调用 DeepSeek 的模型——客户端还是 Claude Code，底层模型换成 DeepSeek，按 DeepSeek 的 API 价格计费，便宜很多。

本文实测（Ubuntu 25.04 + Claude Code 2.1.233 + DeepSeek V4-Flash）走通全流程，覆盖：

Ubuntu / Debian 系统：安装 Claude Code → 配置 deepseek-v4-flash
Alpine 系统：同样的安装与配置（Alpine 有一个必踩的坑，见第 4 步）

二、原理一句话

Claude Code 启动时会读取一组 ANTHROPIC_* 环境变量，决定「连哪个服务器、用什么模型、带哪个密钥」。DeepSeek 的 Anthropic 兼容端点长这样：

Base URL:  https://api.deepseek.com/anthropic
模型名:    deepseek-v4-flash
密钥:      sk- 开头的 DeepSeek API Key

💡 为什么不用改 Claude Code 本体？ 它只是一个「客户端壳」，服务器地址和模型名都是可配置的。DeepSeek 服务端做了别名兼容：即使客户端写死 claude-sonnet / claude-haiku 这类官方模型名，服务端也会自动映射到 deepseek-v4-flash。

三、准备：拿到 DeepSeek API Key

这一步两个系统都一样，先做好再去装。

打开 DeepSeek 开放平台：https://platform.deepseek.com
注册 / 登录账号，进入左侧 API Keys 页面
点 创建 API Key，起个名字（如 claude-code），创建后立刻复制保存——密钥只在创建那一刻完整显示一次，页面刷新后就只能看到 sk-*** 脱敏形式了

密钥长这样（示例，不是真 Key）：

sk-2f9a8c1e7b3d5f6a8c1e7b3d5f6a8c1e

⚠️ 常抄错的值 ①： Key 必须以 sk- 开头，长度约 35~40 位。抄漏中间几位会导致认证失败（报错见「常见问题」Q2）。创建后如果弄丢了，删掉重新建一个即可，旧的会立即失效。

💡 查余额：API Keys 页面下方会显示余额。DeepSeek 需要先充值（最低 10 元）才能调用，新账号送的一定额度用完后也要充值。

四、Ubuntu / Debian：安装 Claude Code

适用系统：Ubuntu 20.04+ / Debian 11+（x86_64 或 arm64 均可）。

第 1 步：确认有 curl

curl --version

有输出就跳过。没有就先装：

sudo apt update && sudo apt install -y curl

第 2 步：运行官方安装脚本

curl -fsSL https://claude.ai/install.sh | bash

⚠️ 常抄错的值 ②： 安装脚本域名是 claude.ai，不是 claude.com。抄成 claude.com/install.sh 会 404。
⚠️ 不要加 sudo！ 官方脚本会拒绝在 sudo 下安装（报错 Error: do not run this installer with sudo.）。它会装到你的家目录，不需要 root。

看到下面输出就是装好了：

  Version: 2.1.233

  Location: ~/.local/bin/claude


  Next: Run claude --help to get started

✅ Installation complete!

第 3 步：把 claude 加进 PATH

脚本装到了 ~/.local/bin/claude，但你的 shell 可能还不认识它。运行：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

然后验证：

claude --version

⚠️ 常抄错的值 ③： 如果直接报 command not found: claude，就是没做这一步（或没 source）。新版 Ubuntu 也可能提示 /home/你的用户名/.local/bin 不在 PATH，照上面两条命令做就行。
💡 用 zsh 的（~/.zshrc）把命令里的 ~/.bashrc 换成 ~/.zshrc。

第 4 步：配置 DeepSeek 模型（推荐：settings.json 持久化）

Claude Code 的全局配置文件是 ~/.claude/settings.json。往里写一段 env 配置，以后每次启动都自动生效，不用每次开终端都 export。

mkdir -p ~/.claude
nano ~/.claude/settings.json

粘贴以下内容，把 sk-你的DeepSeek密钥 换成第三步拿到的真实 Key：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的DeepSeek密钥",
    "ANTHROPIC_MODEL": "deepseek-v4-flash",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-flash",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-flash",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
    "CLAUDE_CODE_SUBAGENT_MODEL": "deepseek-v4-flash"
  }
}

保存（nano 里 Ctrl+O 回车，Ctrl+X 退出）。

⚠️ 常抄错的值 ④： JSON 里每一行末尾都要有逗号（最后一行 CLAUDE_CODE_SUBAGENT_MODEL 后面没有），漏逗号或多逗号会导致 JSON 解析失败，claude 直接报错启动不了。改完可以先用 python3 -m json.tool ~/.claude/settings.json 检查格式。
💡 为什么 ANTHROPIC_MODEL 之外还要设 Opus/Sonnet/Haiku 三个？ Claude Code 内部不同任务（主对话、子代理、后台任务）会请求不同的「档位」模型。DeepSeek 只提供一个模型名，所以要全部指到 deepseek-v4-flash，否则子代理可能还试图请求 claude-sonnet（虽然 DeepSeek 服务端会兜底映射，但显式写明最稳）。

第 5 步：启动并验证

在任意项目目录运行：

claude

首次启动会让你确认信任当前文件夹（「Do you trust this folder?」），选 Yes 回车即可。

启动成功后的界面右下角会显示当前模型。配置正确时看到：

deepseek-v4-flash · API Usage Billing

（API Usage Billing 表示走的是 API 按量计费，而不是官方订阅账号。）

进去后发一句话测试，比如「你好」，能正常回复就是通了。也可以输入 /status 查看详情——Model 显示 deepseek-v4-flash，Base URL 指向 https://api.deepseek.com/anthropic 即成功。

✅ 验证方法（命令行）：不想进交互界面也能测。在终端直接跑：
claude -p "只回复两个字：收到"
能输出「收到」就说明整条链路（密钥 → 服务器 → 模型）全部通了。

五、Alpine：安装 Claude Code

适用系统：Alpine 3.18+（本文实测 3.23.5）。Alpine 是 musl 版 Linux，官方安装脚本原生支持，但有一个前置依赖坑——见第 1 步。

第 1 步：安装 bash 和 curl（Alpine 专属坑 ⚠️）

Alpine 默认只有 /bin/sh（BusyBox），没有 bash。而官方安装脚本 install.sh 第一行是 #!/bin/bash，直接跑会报：

/bin/sh: install.sh: not found

或者（如果你先下载再执行）：

sh: ./install.sh: not found

先装依赖：

apk add --no-cache bash curl

⚠️ 常抄错的值 ⑤： Alpine 的包管理器是 apk add，不是 apt install。在 Alpine 上敲 apt 会报 apt: not found——这是 Alpine 和 Debian 系最经典的区分点。

第 2 步：运行官方安装脚本

curl -fsSL https://claude.ai/install.sh | bash

装完输出与 Ubuntu 相同（✅ Installation complete!，版本 2.1.233）。

第 3 步：把 claude 加进 PATH

Alpine 默认 shell 是 ash（~/.profile），执行：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile
source ~/.profile

⚠️ 常抄错的值 ⑥： Alpine 没有 ~/.bashrc（除非你自己装 bash 并配置登录 shell）。写进 ~/.bashrc 的文件不会被 ash 读取，下次开终端又 command not found。装完 bash 后也仍然用 ~/.profile，不要混。

验证：

claude --version

第 4 步：配置 DeepSeek 模型

和 Ubuntu 完全相同——~/.claude/settings.json 内容一模一样：

mkdir -p ~/.claude
nano ~/.claude/settings.json

粘贴同样的 JSON（记得换真实 Key），保存退出。

第 5 步：启动并验证

claude

同样确认信任文件夹、看右下角 deepseek-v4-flash · API Usage Billing，再 claude -p "只回复两个字：收到" 测试。

✅ 本文在 Alpine 3.23.5 容器里完整实测过：安装、配置、调用全部通过，验证输出见文末「实战验证」。

六、可选：让 Claude Code 用 nvim 打开文件（配置 EDITOR / VISUAL）

Claude Code 在对话中打开/编辑文件时，默认用的是内置的简易编辑器。想让它在 review 代码、打开文件时直接调用 nvim（或其他你习惯的编辑器），配置两个环境变量即可：EDITOR 和 VISUAL。

💡 为什么要设两个？ EDITOR 是 Unix 世界约定俗成的「默认编辑器」变量，很多命令行工具（git、crontab 等）都会读它；VISUAL 是它的「全屏编辑器」版本，现代工具通常两个都会看。两个都设，一次配好到处生效。

⚠️ 前提：nvim 得先装好。 环境变量只是告诉系统「默认编辑器叫 nvim」，nvim 本身要提前安装，否则 Claude Code 调用时会报 nvim: command not found。
Ubuntu / Debian：
sudo apt install -y neovim
Alpine：
apk add --no-cache neovim

Ubuntu / Debian（Bash 或 Zsh）

如果你用 Bash（大部分 Linux 默认）：

echo 'export EDITOR="nvim"' >> ~/.bashrc
echo 'export VISUAL="nvim"' >> ~/.bashrc
source ~/.bashrc

如果你用 Zsh（macOS 默认或部分 Linux）：

echo 'export EDITOR="nvim"' >> ~/.zshrc
echo 'export VISUAL="nvim"' >> ~/.zshrc
source ~/.zshrc

验证：

echo $EDITOR

输出 nvim 就对了。

Alpine（ash）

Alpine 默认 shell 是 ash，配置要写进 ~/.profile（和第 5 步加 PATH 是同一个文件）：

echo 'export EDITOR="nvim"' >> ~/.profile
echo 'export VISUAL="nvim"' >> ~/.profile
source ~/.profile

⚠️ 常抄错的值 ⑦： Alpine 上还是老规矩——写进 ~/.bashrc 不会被读取（ash 不读它），必须写 ~/.profile。

配置完成后退出并重新启动 claude，再让它打开文件时，就会自动调用 nvim 了。

七、常见问题（Q&A）

Q1：启动时出现 `"deepseek-v4-flash" is not a model this version of Claude Code recognizes`

"deepseek-v4-flash" is not a model this version of Claude Code recognizes, so auto-compact will keep this session within 200k tokens (the context window it assumes).

这是正常现象，不用管。 Claude Code 自带的模型清单里没有 DeepSeek 的模型名（它只认识 Claude 系列），但 DeepSeek 服务端认这个模型名。这只是 Claude Code 在提示「我不认识这个模型，按 200k 上下文窗口处理」，不影响任何功能。想要安静一点，可以在 settings.json 的 env 里加一行：

"CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT": "1"

Q2：调用报 `401` / `Authentication Error` / `Execution error`

基本是 Key 的问题，按顺序查：

Key 是不是复制完整了（sk- 开头，35~40 位）
settings.json 里有没有留了占位符 sk-你的DeepSeek密钥 没替换
余额是不是 0（去 platform.deepseek.com 看）
密钥格式验证：echo "sk-你的Key" | wc -c 应该是 40 左右

Q3：`Both ANTHROPIC_AUTH_TOKEN and /login managed key set`

⚠ Both ANTHROPIC_AUTH_TOKEN and /login managed key set · auth may not work as expected

说明这台机器之前用 Anthropic 官方账号登录过（claude 首次启动时 /login 过），现在又配了 DeepSeek token，两套凭据并存会打架。解决：在 claude 里输入 /logout 退出官方登录，重启 claude 即可。

Q4：`/status` 显示的还是官方模型 / Base URL 没变

说明配置没被读进去。检查：

文件路径必须精确是 ~/.claude/settings.json（不是 ~/.claude/config.json，不是项目目录里的）
JSON 格式是否合法：python3 -m json.tool ~/.claude/settings.json
改完文件后退出 claude 重新启动才生效

Q5：Alpine 上装完 `claude` 还是 `command not found`

基本是 PATH 没生效：确认写进了 ~/.profile（不是 ~/.bashrc），并重新登录终端或 source ~/.profile。

八、不推荐的方式：临时环境变量

除了 settings.json，也可以每次开终端前手动 export（DeepSeek 官方文档写法）。不推荐作为主方式：每次开新终端都要重新 export，容易漏。仅当你只想「试一下」时用：

export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
export ANTHROPIC_AUTH_TOKEN="sk-你的DeepSeek密钥"
export ANTHROPIC_MODEL="deepseek-v4-flash"
export ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4-flash"
export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-flash"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-v4-flash"
export CLAUDE_CODE_SUBAGENT_MODEL="deepseek-v4-flash"
claude

⚠️ 若你的 shell 环境里已经存在 ANTHROPIC_AUTH_TOKEN 之类的变量（比如给其他工具用的），settings.json 和 export 同时存在时以 settings.json 为准，两者不一致会看到 Q3 的警告。

九、实战验证（本文实测记录）

项目	值
测试机 A	Ubuntu 25.04（本机），Claude Code 2.1.233
测试机 B	Alpine 3.23.5（Docker 容器干净环境），Claude Code 2.1.233
测试机 C	Ubuntu 24.04（Docker 容器干净环境），Claude Code 2.1.233
模型	`deepseek-v4-flash`（官方 `api.deepseek.com/anthropic` 端点）

Ubuntu 干净安装（测试机 C）：

$ curl -fsSL https://claude.ai/install.sh | bash
  Version: 2.1.233
  Location: ~/.local/bin/claude
  Next: Run claude --help to get started
✅ Installation complete!
$ claude --version
2.1.233 (Claude Code)

Alpine 干净安装（测试机 B）： 先 apk add --no-cache bash curl，再跑同一安装脚本，输出与 Ubuntu 一致，claude --version 同为 2.1.233。

配置后真实调用（测试机 A，settings.json 方式）：

$ claude -p "只回复两个字：收到"
"deepseek-v4-flash" is not a model this version of Claude Code recognizes, ...（无害提示，见 Q1）
收到

Alpine 容器内同样配置后调用：成功发出请求，因容器内使用测试 Key 返回 Execution error——证明配置已生效、请求已到达 DeepSeek 服务器（真正调用的是认证失败，而非配置问题）。

交互启动界面： 右下角显示 deepseek-v4-flash · API Usage Billing，确认模型已切换。

实测中遇到的坑： 本机曾用官方账号登录过 Claude Code，配置后出现 Q3 的 Both ANTHROPIC_AUTH_TOKEN and /login managed key set 警告——与正文 Q3 描述一致，/logout 后消失。

⚠️ 文中所有 sk- 示例 Key 均为占位符，请使用你自己在 DeepSeek 开放平台创建的 Key。

一、这篇文章教你做什么

二、原理一句话

三、准备：拿到 DeepSeek API Key

四、Ubuntu / Debian：安装 Claude Code

第 1 步：确认有 curl

第 2 步：运行官方安装脚本

第 3 步：把 claude 加进 PATH

第 4 步：配置 DeepSeek 模型（推荐：settings.json 持久化）

第 5 步：启动并验证

五、Alpine：安装 Claude Code

第 1 步：安装 bash 和 curl（Alpine 专属坑 ⚠️）

第 2 步：运行官方安装脚本

第 3 步：把 claude 加进 PATH

第 4 步：配置 DeepSeek 模型

第 5 步：启动并验证

六、可选：让 Claude Code 用 nvim 打开文件（配置 EDITOR / VISUAL）

Ubuntu / Debian（Bash 或 Zsh）

Alpine（ash）

七、常见问题（Q&A）

Q1：启动时出现 "deepseek-v4-flash" is not a model this version of Claude Code recognizes

Q2：调用报 401 / Authentication Error / Execution error

Q3：Both ANTHROPIC_AUTH_TOKEN and /login managed key set

Q4：/status 显示的还是官方模型 / Base URL 没变

Q5：Alpine 上装完 claude 还是 command not found

八、不推荐的方式：临时环境变量

九、实战验证（本文实测记录）

Q1：启动时出现 `"deepseek-v4-flash" is not a model this version of Claude Code recognizes`

Q2：调用报 `401` / `Authentication Error` / `Execution error`

Q3：`Both ANTHROPIC_AUTH_TOKEN and /login managed key set`

Q4：`/status` 显示的还是官方模型 / Base URL 没变

Q5：Alpine 上装完 `claude` 还是 `command not found`