如果你已经在本地装过 Codex 或 Claude Code却被官方账号登录、额度消耗和模型 API 成本搞得有点头疼那么把模型服务切到 DeepSeek是目前很多开发者都在尝试的一条路线。DeepSeek 的 API 走 OpenAI 兼容格式接入成本相对低价格又比不少海外大模型 API 友好社区里关于“Codex 接入 DeepSeek”“Claude Code 接入 DeepSeek”的讨论也越来越多。这篇文章不绕弯子直接把 Codex 安装、Claude Code 安装、DeepSeek 第三方 API 接入、会话找回四个环节串成一条可复现的链路。文章里会包含环境准备、命令行安装步骤、配置文件示例、常见报错排查和工程建议。适合的读者有两类刚接触 Codex / Claude Code想知道这两个工具怎么装、怎么跑起来的新手。已经在用这些工具但想换成 DeepSeek API、或者遇到 local proxy 报错、会话丢失问题的开发者。学完这篇文章你会得到一套可复制的安装与配置流程、一份能直接用来排错的命令清单以及把历史会话找回来的操作方法。1. 背景与核心概念先梳理一下这三个主角分别是什么。1.1 Codex 是什么Codex 是 OpenAI 推出的编程智能体工具主要形态是命令行工具。你可以在终端里启动它让它读取当前项目代码、修改文件、执行命令、帮你完成多步开发任务。它和普通聊天补全工具的区别在于它不只会生成代码片段还会尝试理解整个仓库结构像一个能操作终端的“编程副驾”。Codex 有官方 CLI 版本也有桌面版、编辑器集成等不同形态。社区里常说的“codex 安装”“codex 使用教程”大部分场景指的都是命令行版本。启动后你可以用自然语言描述需求比如“帮我写一个 Python 脚本把当前目录下的 CSV 文件按日期字段排序”它会先看目录里的文件再给出方案并尝试执行。1.2 Claude Code 是什么Claude Code 是 Anthropic 推出的终端编程助手拥有类似的 Agent 能力。它可以直接在命令行里和你对话也能操作文件、运行命令、把长任务拆解成多轮步骤。相比传统补全工具Claude Code 的特点是对长上下文和复杂任务的处理能力比较强社区里甚至有人用它来写嵌入式、STM32 这类偏底层的代码。Claude Code 的常见安装方式也是 npm 全局包安装后终端里运行claude就能进入交互界面。它可以单独使用也可以集成到 VS Code 的终端里使用还可以通过插件接入团队协作场景。1.3 DeepSeek 为什么适合做第三方 APIDeepSeek 是国内的大模型服务商提供两类常用的模型 APIdeepseek-chat通用对话模型适合日常代码生成、解释、重构等高频任务。deepseek-reasoner强化推理模型适合复杂逻辑分析、多步推理、疑难 Bug 定位。DeepSeek API 的一大特点是兼容 OpenAI 的 Chat Completions 接口格式。也就是说很多原本为 OpenAI API 写的工具只需要修改base_url和api_key就能把模型服务切到 DeepSeek。这正是“Codex 接入 DeepSeek”能成立的根本原因。1.4 容易混淆的几个概念在搜索相关资料时你可能会看到一堆名词混在一起DeepSeek Harness、DeepSeek Hermes、第三方 API、本地代理、会话找回。这里做一个快速区分概念含义说明DeepSeek APIDeepSeek 开放平台提供的云端模型接口按 token 计费使用官方 API KeyDeepSeek 开源模型DeepSeek 开源出来的模型权重可本地部署通过 vLLM/Ollama 暴露兼容接口第三方 API 接入把 Codex / Claude Code 的模型层改成 DeepSeek替换默认模型服务商local proxy本地运行的转换服务负责把不同 API 格式互相转换会话找回恢复历史对话上下文依赖本地会话文件不依赖模型服务商社区里偶尔出现“DeepSeek Harness”“DeepSeek Hermes”这类叫法实际配置时不用太纠结只需要认准 DeepSeek 开放平台 API 文档里的模型 ID 即可。2. 环境准备与版本说明动手安装之前先确认环境满足基本要求。Codex 和 Claude Code 都是命令行工具依赖 Node.js 生态所以 Node.js 是首要前置条件。2.1 操作系统本文的安装命令同时适用于 Windows、macOS 和 Ubuntu。不同系统差异不大主要区别在终端类型Windows建议使用 PowerShell 或 Windows Terminal。macOS使用内置 Terminal 或 iTerm2。Ubuntu使用系统终端安装时可能遇到 npm 权限问题。2.2 Node.js 与 npmClaude Code 官方推荐使用 npm 全局安装。Codex 也可以通过 npm 安装或从官方 Releases 下载二进制包。建议提前装好 Node.js。可以使用系统包管理器安装也可以借助nvm、asdf等版本管理工具。具体版本不需要死记通常 Node.js 18 以上的稳定版本都能满足要求。安装后先验证node -v npm -v如果 npm 执行时提示权限不足在 Linux/macOS 上可以配置用户级 npm 全局目录或者使用sudo安装不推荐但能用。2.3 Python 环境为什么要提 Python因为后面讲 Claude Code 接入 DeepSeek 时我们会讨论一种本地代理转换方案用 Python 写一个最小的 FastAPI 服务来演示转换原理。如果你不打算自己写代理也可以跳过 Python。2.4 账号与 API Key接入 DeepSeek 之前需要去 DeepSeek 开放平台注册账号、创建 API Key并按需充值。API Key 是后续配置的核心凭据不要泄露到公共仓库。版本说明这里单独强调一下Codex、Claude Code 的迭代速度非常快命令行参数、配置字段、会话目录都可能随版本变化。本文以常见稳定版本的用法为例重点讲解配置思路。如果命令或字段对不上先查看当前版本的帮助信息codex --help claude --help3. 安装 Codex 与 Claude Code这一节直接给出完整安装步骤。3.1 安装 CodexCodex 的安装方式主要有两种npm 全局包和二进制包。方式一npm 安装npm install -g openai/codex安装完成后验证codex --version方式二官方 Releases 下载Codex 官方也提供各平台的二进制安装包包括 Windows 桌面版。下载后解压到本地目录把可执行文件所在目录加入 PATH 即可。Windows 用户需要注意终端权限和路径中的中文目录问题。装好之后先不要急着登录官方账号。如果你是打算用 DeepSeek 作为模型服务后面会通过环境变量和配置文件绕过官方账号体系。3.2 安装 Claude CodeClaude Code 官方推荐 npm 安装npm install -g anthropic-ai/claude-code验证安装claude --versionUbuntu 环境下如果遇到权限问题可以先执行whoami如果是普通用户建议配置 npm 的用户级安装路径避免用sudo覆盖系统目录。也可以临时使用sudo npm install -g anthropic-ai/claude-code安装后运行claude会进入交互式对话界面。如果直接运行没反应先检查 Node.js 环境是否干净。macOS 和 Windows 的安装逻辑一致都是先确认 Node.js 再 npm 全局安装。桌面版可以从官网获取但 CLI 版对日常自动化脚本更友好。3.3 VS Code 中的使用很多人的习惯是在 VS Code 里写代码。Claude Code 和 Codex 都可以在 VS Code 的集成终端中运行打开 VS Code按Ctrl呼出终端。在终端里输入claude或codex直接进入交互模式。这样一边看代码一边和 Agent 对话体验比较顺。官方也有对应的扩展插件具体以扩展市场发布的版本为准。4. 接入 DeepSeek 第三方 API安装只是第一步真正的重头戏是把 Codex 和 Claude Code 的模型服务切到 DeepSeek。4.1 获取 DeepSeek API Key登录 DeepSeek 开放平台后在 API Key 管理页面创建一个新的 Key保存下来例如export DEEPSEEK_API_KEYsk-你的key这里有两个官方兼容的调用地址https://api.deepseek.comhttps://api.deepseek.com/v1两者的差异只在于路径里是否带/v1DeepSeek 官方兼容 OpenAI 格式所以也能兼容带/v1的写法。建议在配置时统一使用https://api.deepseek.com/v1先直接用 curl 验证 API Key 是否可用curl https://api.deepseek.com/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -d { model: deepseek-chat, messages: [{role: user, content: 你好}], max_tokens: 32 }如果返回 JSON 中包含choices字段说明 Key 和网络链路都正常。4.2 Codex 接入 DeepSeekCodex 本身是 OpenAI 生态的工具官方默认读取 OpenAI 的环境变量。DeepSeek API 兼容 OpenAI 格式所以接入方式比较直接。在终端里设置环境变量export DEEPSEEK_API_KEYsk-你的key export OPENAI_API_KEYsk-你的key export OPENAI_BASE_URLhttps://api.deepseek.com/v1这里把OPENAI_API_KEY也设为 DeepSeek 的 Key是为了让 Codex 在读取环境变量时不至于因为缺少 Key 而报auth token is unavailable。更规范的做法是在 Codex 的配置文件里声明独立的 model provider。Codex 的配置文件通常位于macOS / Linux~/.codex/config.tomlWindows%USERPROFILE%\.codex\config.toml参考配置如下model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 api_key_env_var DEEPSEEK_API_KEY这段配置的意思是默认使用deepseek-chat模型。选择名称为deepseek的模型服务商。模型服务商的基础地址指向 DeepSeek 的 OpenAI 兼容端点。API Key 从环境变量DEEPSEEK_API_KEY中读取而不是硬编码在文件里。不同版本的 Codex 配置字段可能略有差异。如果你打开的配置文件里已经有示例内容建议参照原格式修改而不是直接覆盖。运行codex exec 用一句话解释什么是依赖注入可以验证是否成功接通。如果返回结果来自 DeepSeek说明配置生效。有一个细节需要注意Codex 的部分版本会优先使用 OpenAI 的 Responses API/responses端点而 DeepSeek 官方兼容的是 Chat Completions 格式/chat/completions。如果启动后请求一直失败或者日志里出现/responses路径说明当前版本走的是 Responses API这时候需要在本地加一层转换代理或者调整 Codex 的 provider 配置让它走 Chat Completions 兼容路径。这也是为什么社区里大量讨论 local proxy 的原因。4.3 Claude Code 接入 DeepSeekClaude Code 的情况更特殊。Claude Code 官方对接的是 Anthropic Messages API 格式而 DeepSeek 提供的是 OpenAI Chat Completions 格式。两者字段结构不同直接让 Claude Code 请求 DeepSeek 并不能正常通信所以中间必须有一层转换。整体结构如下Claude Code --Anthropic格式-- 本地代理 --OpenAI格式-- DeepSeek API本地代理就是一个跑在你电脑上的小服务监听本地端口接收 Claude Code 发来的 Anthropic 格式请求再转换成 OpenAI Chat Completions 格式转发给 DeepSeek。配置方式export DEEPSEEK_API_KEYsk-你的key export ANTHROPIC_BASE_URLhttp://127.0.0.1:8080 export ANTHROPIC_AUTH_TOKENsk-你的keyANTHROPIC_BASE_URL指向本地代理地址ANTHROPIC_AUTH_TOKEN可以先用 DeepSeek 的 Key 代替因为最终认证发生在代理转发到 DeepSeek 的那一步。下面给一个最小可运行的 FastAPI 代理示例用于理解转换原理。这个示例只处理非流式请求用于验证链路# 文件路径deepseek_proxy.py import os import uuid import httpx from fastapi import FastAPI, Request from fastapi.responses import JSONResponse app FastAPI() DEEPSEEK_API_KEY os.environ.get(DEEPSEEK_API_KEY) DEEPSEEK_BASE_URL os.environ.get(DEEPSEEK_BASE_URL, https://api.deepseek.com) DEFAULT_MODEL os.environ.get(DEEPSEEK_MODEL, deepseek-chat) app.post(/v1/messages) async def anthropic_messages(request: Request): body await request.json() messages [] system_text for item in body.get(messages, []): role item.get(role, user) content item.get(content, ) if role system: system_text content if isinstance(content, str) else str(content) continue # Claude Code 的 content 可能是字符串也可能是数组 if isinstance(content, list): text_parts [] for block in content: if block.get(type) text: text_parts.append(block.get(text, )) content \n.join(text_parts) messages.append({role: role, content: content}) if system_text: messages.insert(0, {role: system, content: system_text.strip()}) payload { model: body.get(model, DEFAULT_MODEL), messages: messages, max_tokens: body.get(max_tokens, 4096), temperature: body.get(temperature, 1.0), } async with httpx.AsyncClient(timeout120) as client: resp await client.post( f{DEEPSEEK_BASE_URL}/chat/completions, headers{Authorization: fBearer {DEEPSEEK_API_KEY}}, jsonpayload, ) data resp.json() if resp.status_code ! 200: return JSONResponse( status_coderesp.status_code, content{type: error, error: data}, ) choice data[choices][0] text choice[message].get(content) or anthropic_resp { id: msg_ uuid.uuid4().hex, type: message, role: assistant, model: data.get(model, DEFAULT_MODEL), content: [{type: text, text: text}], stop_reason: end_turn if choice.get(finish_reason) stop else max_tokens, usage: data.get(usage, {}), } return anthropic_resp启动方式pip install fastapi uvicorn httpx export DEEPSEEK_API_KEYsk-你的key uvicorn deepseek_proxy:app --host 127.0.0.1 --port 8080然后另开一个终端进入任意项目目录运行claude如果 Claude Code 能正常回复说明链路通了。这里必须说明这个示例只覆盖最基本的非流式对话场景。Claude Code 实际运行时会发送流式请求、携带工具调用等复杂结构生产环境直接使用这个最小示例是不够的。更推荐的做法是使用社区中维护更完整的兼容代理工具或者等 Claude Code 官方适配 OpenAI 兼容端点。这个示例的定位是讲清转换原理方便你排查问题。4.4 模型选择建议接入 DeepSeek 后两个模型需要区分使用deepseek-chat日常代码补全、讲解、重构、写测试响应快、成本低。deepseek-reasoner复杂 Bug 定位、架构设计、多步推理推理更深入但耗时更长。建议默认使用deepseek-chat只有在明确需要深度推理时才切到deepseek-reasoner。这样既能保证开发效率也能控制 API 成本。5. 会话找回与会话管理使用终端型 AI 工具时最常见的痛点是跑了一个很长的任务结果网络断了、电脑重启、或者终端被误关再打开发现对话上下文没了。这一节专门讲会话找回。5.1 Codex 的会话找回Codex 的会话记录默认保存在本地目录。会话文件里包含你的对话内容、上下文摘要、历史命令等。常见位置macOS / Linux~/.codex/sessionsWindows%USERPROFILE%\.codex\sessions启动 Codex 时交互界面一般会展示历史会话列表你可以选择继续之前的对话。命令行模式下可以尝试恢复最近一次会话codex resume如果你想恢复指定会话可以先查看会话目录下的文件把对应的会话 ID 或名称传给resume命令。不同版本的命令格式有差异最可靠的方法是执行codex --help确认当前版本的参数。5.2 Claude Code 的会话找回Claude Code 同样支持会话恢复。恢复最近一次会话claude --resume指定历史会话时可以通过帮助信息查看支持的参数claude --helpClaude Code 的会话历史通常存放在用户目录~/.claude/下同时项目目录下也可能存在.claude/目录里面会记录当前项目的会话状态。如果你想手动备份会话直接复制这两个目录即可。5.3 会话找回的核心原理Codex 和 Claude Code 的会话找回本质上是读取本地会话文件把之前的对话上下文重新加载到当前交互中。需要注意的是DeepSeek 这类第三方 API 默认不会保存你的会话历史。会话找回依赖的是本地文件不是模型服务商。切换 API Key 或模型后历史会话仍然可以找回但后续回复会使用新的模型配置。跨机器迁移时把本地会话目录一起拷走即可。因此如果你经常在多台机器之间切换建议定期备份这些目录。备份时注意会话内容可能包含项目代码片段不要备份到公共仓库。6. 常见问题与排查思路工具集成类的文章没有 FAQ 基本上是不完整的。下面把接入过程中最容易踩的坑整理出来。问题现象常见原因解决思路Codex 报 auth token is unavailable未登录或环境变量缺失配置DEEPSEEK_API_KEY/OPENAI_API_KEY或执行codex login接入 DeepSeek 后返回 401API Key 错误或未生效用 curl 直接调用接口验证 Key返回 402 / 余额不足DeepSeek 账户余额不足登录开放平台充值确认返回 404 / model not found模型 ID 不正确或 base_url 路径不对确认使用deepseek-chat/deepseek-reasonerClaude Code 接入后一直转圈代理不支持流式响应换成支持 SSE 的完整代理实现Windows 下 npm 全局安装失败权限不足或 PATH 未配置管理员 PowerShell 执行或配置用户级 npm 路径Codex 请求打到 /responses 端点版本使用 Responses API加本地代理转换或调整 provider 配置6.1 local proxy 处理 Codex endpoint 报错热词里有一条很具体的报错CC switch local proxy failed while handling codex endpoint /responses. provider...这个现象的本质是Claude Code 在通过 local proxy 访问某个以 Codex 风格定义的端点时代理收到了/responses路径的请求但代理本身或后端模型服务不支持这个路径最终导致失败。排查步骤可以按下面顺序来查看 local proxy 的日志确认收到的是/responses还是/chat/completions。用 curl 直接调用 DeepSeek 的/chat/completions确认 Key 和模型可用。确认 local proxy 是否支持把/responses转换成/chat/completions。如果不支持需要换一个更新的代理实现。把ANTHROPIC_BASE_URL临时改回官方 Anthropic 接口做对照实验确认是配置问题还是代理实现问题。检查 Codex 和 Claude Code 的版本。工具版本不同端点行为可能完全不同。这种报错在本地代理场景里非常典型核心思路永远是先确认请求格式再确认后端能力最后看代理层是否匹配。6.2 DeepSeek Harness / Hermes 命名困惑社区里偶尔会出现 DeepSeek Harness、DeepSeek Hermes 这类叫法。实际调用时模型 ID 以 DeepSeek 开放平台文档为准通常是deepseek-chat和deepseek-reasoner。不需要纠结那些社区称呼认准官方模型 ID 就不会配置错。6.3 会话文件丢失怎么办如果历史会话目录被清理或重装系统后丢失会话找回基本无解。所以重要会话要及时备份。长任务执行前可以把关键决策点记录到项目文档里。不要依赖终端工具的会话历史作为唯一的知识沉淀。7. 最佳实践与工程建议工具能跑通只是开始真正进入工程化阶段后还需要关注 API Key 管理、成本控制、安全边界等事项。7.1 API Key 与环境变量管理不要把 API Key 硬编码到配置文件或代码仓库里。Codex 的配置文件中api_key_env_var就是为了从环境变量读取 Key 设计的。Claude Code 接入时也建议通过环境变量传入。日常开发中可以在~/.bashrc、~/.zshrc或 PowerShell 的$PROFILE中集中配置export DEEPSEEK_API_KEYsk-你的key export OPENAI_API_KEYsk-你的key export OPENAI_BASE_URLhttps://api.deepseek.com/v1团队协作时密钥应该放到统一的密钥管理平台而不是每人复制一份到本地。.gitignore中建议加入本地配置目录避免误提交。7.2 成本监控思路Cost 是第三方 API 接入中最容易失控的环节。建议从三个层面控制平台层DeepSeek 开放平台后台提供用量统计和余额查询。建议设置余额提醒避免某个长任务把额度跑光。代理层如果你使用 local proxy可以在代理层记录每次请求的usage字段把输入 token、输出 token 落日志。简单统计脚本可以这样grep -o total_tokens:[0-9]* proxy.log | awk -F: {s$2} END {print total tokens:, s}任务层配置max_tokens。默认不限制的话一个 reasoner 模型可能会输出非常长的推理内容成本会快速累积。日常开发建议把max_tokens控制在合理范围比如 4096 或 8192按任务类型调整。7.3 安全边界与权限意识Codex 和 Claude Code 这类 Agent 工具有能力执行终端命令、修改文件。这在带来效率的同时也带来风险。建议遵循以下原则先在测试仓库或临时目录里跑确认行为符合预期后再放到正式项目。不要把生产数据库密码、云服务密钥写在项目文件里Agent 读取项目内容时可能会把这些信息带进上下文中。涉及删除、覆盖、权限变更的高危操作先在代码评审中确认方案。涉及线上配置或数据库变更时需要合法授权、测试环境验证、备份和最小权限原则。AI 工具可以辅助编码但不能替代人工审查。越是高权限的操作越要手动确认。7.4 会话备份与团队协作把会话目录纳入备份策略# macOS / Linux tar -czf codex_sessions_backup.tar.gz ~/.codex/sessions ~/.claudeWindows 下可以手动复制%USERPROFILE%\.codex\sessions和%USERPROFILE%\.claude。团队内使用 Codex / Claude Code 时最好统一 Node.js 版本、CLI 版本和 local proxy 版本否则很容易出现“我这边能跑、你那边报错”的兼容性问题。7.5 本地部署延伸如果你不想依赖云端 API可以考虑把 DeepSeek 开源模型部署到本地通过 vLLM 或 Ollama 暴露一个 OpenAI 兼容端点然后把 Codex 的base_url指向本机地址。这种方式适合对数据隐私要求比较高的场景。部署前需要评估 GPU 显存、推理速度和工具调用能力。本地模型和云端 API 在能力上可能存在差异建议先用小项目验证再逐步推广。8. 总结与下一步这篇文章围绕 Codex 和 Claude Code 接入 DeepSeek 这条主线把安装、第三方 API 配置、会话找回和常见问题串成了一个完整链路。你现在应该已经掌握Codex 和 Claude Code 的 npm 安装方法。DeepSeek API Key 的获取与验证方式。Codex 通过环境变量和config.toml接入 DeepSeek 的方法。Claude Code 通过本地代理转换接入 DeepSeek 的原理与最小示例。常见报错如auth token is unavailable、local proxy 处理/responses失败的排查思路。会话找回与本地会话目录的管理方法。下一步建议做两件事花半小时把 Codex 和 Claude Code 都装上接一个真实的练习项目跑一遍感受两种 Agent 的编码风格差异。重点关注成本监控和生产环境安全边界。工具接入很容易但真正稳定的工程化使用靠的是环境变量规范、会话备份和权限意识。如果你在接入过程中遇到新的报错可以先从 API 格式、版本匹配、代理日志三个方向排查大概率能定位到问题根源。如果这篇文章对你有帮助建议先收藏备用。后面再遇到 local proxy 或者会话找回的问题可以直接翻到对应章节对照排查。