背景与动机

Claude Code 是 Anthropic 推出的命令行编程代理（Agent），内置 Claude 模型驱动代码生成、文件编辑、终端执行和调试能力。DeepSeek 系列模型则以高性价比和出色的代码理解能力著称。将 DeepSeek-v4 接入 Claude Code 架构，可以利用其作为底层推理引擎或补充模型，在保持 Claude Code 工作流不变的前提下，获得更灵活的成本控制和模型选择。

通过自定义适配器将 DeepSeek 的 API 集成到 Claude Code 的配置层中，开发者可以在需要长上下文、多模态理解或特定语言任务时，无缝调用 DeepSeek-v4 的能力。

环境准备

前置条件

在开始之前，确保满足以下基础要求：

已安装 Node.js。Claude Code 基于 Node.js 运行，建议版本为 18.0 或以上：

node --version
npm --version

已安装 Claude Code。通过 npm 全局安装：

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

DeepSeek API 密钥。注册 DeepSeek 开发者账号并获取 API 密钥，注册地址为 deepseek.com 的开发者控制台。创建 API Key 后妥善保存。

代理服务器配置。DeepSeek 的 API 端点在国内可能需要通过代理访问，确保网络环境通畅。

接入方案一：通过环境变量配置

方法概述

Claude Code 支持通过环境变量配置外部模型适配，核心思路是将 DeepSeek 的 API 端点、密钥和参数以标准格式注入到 Claude Code 的运行时配置中。

具体步骤

第一步：设置环境变量

在项目根目录创建 .env 文件：

DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
DEEPSEEK_MODEL=deepseek-v4

在终端中导出环境变量：

export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"
export DEEPSEEK_BASE_URL="https://api.deepseek.com/v1"
export DEEPSEEK_MODEL="deepseek-v4"

建议将上述 export 语句添加到 ~/.bashrc 或 ~/.zshrc 中，实现持久化配置。

第二步：创建适配器脚本

在 Claude Code 项目目录下创建 deepseek-adapter.js 文件，用于封装 DeepSeek API 调用：

const axios = require('axios');

const DEEPSEEK_BASE_URL = process.env.DEEPSEEK_BASE_URL || 'https://api.deepseek.com/v1';
const DEEPSEEK_API_KEY = process.env.DEEPSEEK_API_KEY;
const DEEPSEEK_MODEL = process.env.DEEPSEEK_MODEL || 'deepseek-v4';

async function deepseekChat(messages, options = {}) {
    if (!DEEPSEEK_API_KEY) {
        throw new Error('DEEPSEEK_API_KEY 环境变量未设置');
    }

    const response = await axios.post(
        `${DEEPSEEK_BASE_URL}/chat/completions`,
        {
            model: DEEPSEEK_MODEL,
            messages: messages,
            temperature: options.temperature || 0.7,
            max_tokens: options.maxTokens || 4096,
            top_p: options.topP || 0.9,
            stream: options.stream || false,
        },
        {
            headers: {
                'Authorization': `Bearer ${DEEPSEEK_API_KEY}`,
                'Content-Type': 'application/json',
            },
            timeout: 120000,
        }
    );

    return response.data;
}

async function deepseekStreamChat(messages, onChunk) {
    if (!DEEPSEEK_API_KEY) {
        throw new Error('DEEPSEEK_API_KEY 环境变量未设置');
    }

    const response = await axios.post(
        `${DEEPSEEK_BASE_URL}/chat/completions`,
        {
            model: DEEPSEEK_MODEL,
            messages: messages,
            temperature: 0.7,
            max_tokens: 4096,
            stream: true,
        },
        {
            headers: {
                'Authorization': `Bearer ${DEEPSEEK_API_KEY}`,
                'Content-Type': 'application/json',
            },
            responseType: 'stream',
        }
    );

    let buffer = '';
    return new Promise((resolve, reject) => {
        response.data.on('data', (chunk) => {
            buffer += chunk.toString();
            const lines = buffer.split('\n');
            buffer = lines.pop();

            for (const line of lines) {
                const trimmed = line.trim();
                if (trimmed.startsWith('data: ') && trimmed !== 'data: [DONE]') {
                    try {
                        const data = JSON.parse(trimmed.slice(6));
                        const content = data.choices?.[0]?.delta?.content;
                        if (content) {
                            onChunk(content);
                        }
                    } catch (e) {
                        // 忽略解析失败的数据块
                    }
                }
            }
        });

        response.data.on('end', () => resolve());
        response.data.on('error', reject);
    });
}

module.exports = { deepseekChat, deepseekStreamChat };

第三步：集成到 Claude Code 工作流

在 Claude Code 的配置目录（通常为 ~/.claude/ 或项目根目录的 .claude/）中创建自定义配置。Claude Code 支持通过 settings.json 定义外部工具调用：

{
    "tools": {
        "deepseek-completion": {
            "type": "script",
            "command": "node",
            "args": ["deepseek-adapter.js", "chat"],
            "description": "使用 DeepSeek-v4 进行代码补全和对话"
        }
    }
}

接入方案二：通过 OpenAI 兼容接口

方法概述

DeepSeek 提供了与 OpenAI API 完全兼容的接口，这意味着任何支持 OpenAI 格式配置的工具都能直接使用 DeepSeek。Claude Code 虽然不原生支持自定义 OpenAI 端点替换，但可以通过中间层代理实现。

具体步骤

第一步：部署 API 代理

使用开源工具如 litellm 或 one-api 作为中间代理，将 OpenAI 格式的调用路由到 DeepSeek：

# 使用 LiteLLM 代理
npm install -g litellm

# 配置 LiteLLM
export OPENAI_API_KEY="sk-placeholder"
export LITELLM_MODEL="deepseek/deepseek-v4"

# 启动代理，监听在 4000 端口
litellm --model deepseek/deepseek-v4 --api_base https://api.deepseek.com/v1

第二步：配置 Claude Code 指向代理

在 Claude Code 的配置中，将 API 端点指向本地代理：

{
    "api": {
        "baseUrl": "http://localhost:4000/v1",
        "apiKey": "sk-placeholder"
    }
}

这种方案的优势在于：代理层还可以统一处理多家 API 的路由、负载均衡和用量统计。

接入方案三：通过自定义 Shell 工具集成

方法概述

Claude Code 支持通过 shell 命令与外部工具交互。通过封装 DeepSeek API 调用为可执行的 shell 脚本，Claude Code 可以在需要时调用 DeepSeek 进行代码审查、文档生成或问题解答。

具体步骤

创建 Shell 脚本

在 ~/.claude/tools/ 目录下创建 deepseek-cli.sh：

#!/bin/bash

# DeepSeek CLI 工具 - 通过 stdin 接收消息，输出模型回复

API_KEY="${DEEPSEEK_API_KEY:-}"
BASE_URL="${DEEPSEEK_BASE_URL:-https://api.deepseek.com/v1}"
MODEL="${DEEPSEEK_MODEL:-deepseek-v4}"

if [ -z "$API_KEY" ]; then
    echo "ERROR: DEEPSEEK_API_KEY not set" >&2
    exit 1
fi

# 读取 stdin 作为用户消息
MESSAGE=$(cat)

RESPONSE=$(curl -s -X POST "${BASE_URL}/chat/completions" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ${API_KEY}" \
    -d "{
        \"model\": \"${MODEL}\",
        \"messages\": [{\"role\": \"user\", \"content\": \"${MESSAGE}\"}],
        \"temperature\": 0.7,
        \"max_tokens\": 4096
    }")

# 提取回复内容
echo "$RESPONSE" | python3 -c "import sys, json; print(json.load(sys.stdin)['choices'][0]['message']['content'])" 2>/dev/null || echo "$RESPONSE"

赋予执行权限：

chmod +x ~/.claude/tools/deepseek-cli.sh

在 Claude Code 中调用

通过 Claude Code 的 shell 工具集成，可以直接调用该脚本：

echo "请审查以下代码的潜在安全漏洞：
const query = \"SELECT * FROM users WHERE id = \" + userInput;" \
| ~/.claude/tools/deepseek-cli.sh

验证接入效果

测试脚本

创建测试文件 test-deepseek.js 验证连接是否正常：

const { deepseekChat } = require('./deepseek-adapter');

async function test() {
    const messages = [
        { role: 'system', content: '你是一个专业的编程助手。' },
        { role: 'user', content: '请用 Python 写一个快速排序函数，并解释时间复杂度。' },
    ];

    try {
        const result = await deepseekChat(messages);
        console.log('模型回复：');
        console.log(result.choices[0].message.content);
        console.log('\nToken 用量：');
        console.log(result.usage);
    } catch (error) {
        console.error('调用失败：', error.message);
        if (error.response) {
            console.error('响应状态：', error.response.status);
            console.error('响应内容：', error.response.data);
        }
    }
}

test();

执行测试：

node test-deepseek.js

预期输出应包含完整的 Python 快速排序代码和复杂度分析。

常见问题排查

401 Unauthorized。确认 API Key 正确且未被吊销，检查 DEEPSEEK_API_KEY 环境变量是否已正确设置。

403 Rate Limited。DeepSeek API 有调用频率限制，确保在配额范围内。对于高频使用场景，考虑使用 LiteLLM 代理实现请求排队和限流。

超时错误。DeepSeek API 响应时间可能较长，特别是在处理长上下文时。将超时时间设置为 120 秒或更长。

模型不可用。确认 deepseek-v4 模型名称在当前 API 版本中有效，可通过 DeepSeek 官方文档查询当前可用的模型列表和对应名称。

核心要点总结

将 DeepSeek-v4 接入 Claude Code 的核心思路是：通过 API 适配层将 DeepSeek 的接口封装为 Claude Code 可调用的形式。三种方案各有适用场景——环境变量适配器适合深度集成，OpenAI 兼容代理适合多模型统一路由，Shell 脚本工具适合轻量级调用。无论采用哪种方案，确保 API 密钥安全、网络通畅和超时设置合理是关键。通过这种集成方式，开发者可以在 Claude Code 的完整工作流中灵活调度 DeepSeek-v4 的能力，获得更丰富的编程辅助体验。