企业官网建设流程全解析

如果你已经在本地装过 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 为什么适合做第三方 API

DeepSeek 是国内的大模型服务商，提供两类常用的模型 API：

• deepseek-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 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 与 npm

Claude 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 --help

3. 安装 Codex 与 Claude Code

这一节直接给出完整安装步骤。

3.1 安装 Codex

Codex 的安装方式主要有两种：npm 全局包和二进制包。

方式一：npm 安装

npm install -g @openai/codex

安装完成后验证：

codex --version

方式二：官方 Releases 下载

Codex 官方也提供各平台的二进制安装包，包括 Windows 桌面版。下载后解压到本地目录，把可执行文件所在目录加入 PATH 即可。Windows 用户需要注意终端权限和路径中的中文目录问题。

装好之后先不要急着登录官方账号。如果你是打算用 DeepSeek 作为模型服务，后面会通过环境变量和配置文件绕过官方账号体系。

3.2 安装 Claude Code

Claude Code 官方推荐 npm 安装：

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

验证安装：

claude --version

Ubuntu 环境下如果遇到权限问题，可以先执行：

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_KEY="sk-你的key"

这里有两个官方兼容的调用地址：

• https://api.deepseek.com
• https://api.deepseek.com/v1

两者的差异只在于路径里是否带/v1，DeepSeek 官方兼容 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 接入 DeepSeek

Codex 本身是 OpenAI 生态的工具，官方默认读取 OpenAI 的环境变量。DeepSeek API 兼容 OpenAI 格式，所以接入方式比较直接。

在终端里设置环境变量：

export DEEPSEEK_API_KEY="sk-你的key" export OPENAI_API_KEY="sk-你的key" export OPENAI_BASE_URL="https://api.deepseek.com/v1"

这里把OPENAI_API_KEY也设为 DeepSeek 的 Key，是为了让 Codex 在读取环境变量时不至于因为缺少 Key 而报auth token is unavailable。

更规范的做法是在 Codex 的配置文件里声明独立的 model provider。Codex 的配置文件通常位于：

• macOS / Linux：~/.codex/config.toml
• Windows：%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 接入 DeepSeek

Claude 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_KEY="sk-你的key" export ANTHROPIC_BASE_URL="http://127.0.0.1:8080" export ANTHROPIC_AUTH_TOKEN="sk-你的key"

ANTHROPIC_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(timeout=120) as client: resp = await client.post( f"{DEEPSEEK_BASE_URL}/chat/completions", headers={"Authorization": f"Bearer {DEEPSEEK_API_KEY}"}, json=payload, ) data = resp.json() if resp.status_code != 200: return JSONResponse( status_code=resp.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_KEY="sk-你的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/sessions
• Windows：%USERPROFILE%\.codex\sessions

启动 Codex 时，交互界面一般会展示历史会话列表，你可以选择继续之前的对话。命令行模式下，可以尝试恢复最近一次会话：

codex resume

如果你想恢复指定会话，可以先查看会话目录下的文件，把对应的会话 ID 或名称传给resume命令。不同版本的命令格式有差异，最可靠的方法是执行codex --help确认当前版本的参数。

5.2 Claude Code 的会话找回

Claude Code 同样支持会话恢复。恢复最近一次会话：

claude --resume

指定历史会话时，可以通过帮助信息查看支持的参数：

claude --help

Claude Code 的会话历史通常存放在用户目录~/.claude/下，同时项目目录下也可能存在.claude/目录，里面会记录当前项目的会话状态。如果你想手动备份会话，直接复制这两个目录即可。

5.3 会话找回的核心原理

Codex 和 Claude Code 的会话找回，本质上是读取本地会话文件，把之前的对话上下文重新加载到当前交互中。

需要注意的是：

• DeepSeek 这类第三方 API 默认不会保存你的会话历史。
• 会话找回依赖的是本地文件，不是模型服务商。
• 切换 API Key 或模型后，历史会话仍然可以找回，但后续回复会使用新的模型配置。
• 跨机器迁移时，把本地会话目录一起拷走即可。

因此，如果你经常在多台机器之间切换，建议定期备份这些目录。备份时注意：会话内容可能包含项目代码片段，不要备份到公共仓库。

6. 常见问题与排查思路

工具集成类的文章，没有 FAQ 基本上是不完整的。下面把接入过程中最容易踩的坑整理出来。

6.1 local proxy 处理 Codex endpoint 报错

热词里有一条很具体的报错：

CC switch local proxy failed while handling codex endpoint /responses. provider...

这个现象的本质是：Claude Code 在通过 local proxy 访问某个以 Codex 风格定义的端点时，代理收到了/responses路径的请求，但代理本身或后端模型服务不支持这个路径，最终导致失败。

排查步骤可以按下面顺序来：

1. 查看 local proxy 的日志，确认收到的是/responses还是/chat/completions。
2. 用 curl 直接调用 DeepSeek 的/chat/completions，确认 Key 和模型可用。
3. 确认 local proxy 是否支持把/responses转换成/chat/completions。如果不支持，需要换一个更新的代理实现。
4. 把ANTHROPIC_BASE_URL临时改回官方 Anthropic 接口，做对照实验，确认是配置问题还是代理实现问题。
5. 检查 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_KEY="sk-你的key" export OPENAI_API_KEY="sk-你的key" export OPENAI_BASE_URL="https://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 ~/.claude

Windows 下可以手动复制%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失败的排查思路。
• 会话找回与本地会话目录的管理方法。

下一步建议做两件事：

1. 花半小时把 Codex 和 Claude Code 都装上，接一个真实的练习项目跑一遍，感受两种 Agent 的编码风格差异。
2. 重点关注成本监控和生产环境安全边界。工具接入很容易，但真正稳定的工程化使用，靠的是环境变量规范、会话备份和权限意识。

如果你在接入过程中遇到新的报错，可以先从 API 格式、版本匹配、代理日志三个方向排查，大概率能定位到问题根源。

如果这篇文章对你有帮助，建议先收藏备用。后面再遇到 local proxy 或者会话找回的问题，可以直接翻到对应章节对照排查。