最近在尝试将AI助手集成到开发工作流中时，发现很多开发者都卡在了第一步：如何选择一个稳定、免费且功能强大的工具。特别是对于国内开发者，直接使用某些国际服务存在诸多不便。经过一番探索和踩坑，我发现 Codex 配合 DeepSeek 大模型是一个极佳的解决方案。它不仅完全免费、无需复杂网络环境，而且功能强大，足以满足日常代码编写、问题解答和文档查询的需求。

本文将从零开始，手把手带你完成 Codex 的安装、配置，并成功接入 DeepSeek 大模型。整个过程清晰明了，即使你是完全没有相关经验的小白，也能跟着步骤一步步搭建起来。学完后，你将拥有一个在本地或开发环境中随时可用的智能编程助手。

1. 背景与核心概念：为什么选择 Codex + DeepSeek？

在开始动手之前，我们有必要先了解下我们将要使用的两个核心组件是什么，以及它们组合在一起能为我们解决什么问题。

1.1 什么是 Codex？

Codex 在这里并非特指 OpenAI 的 Codex 模型，而是一个 开源的、可扩展的 AI 助手客户端 。你可以把它理解为一个“壳”或者“前端界面”。它的核心功能是提供一个统一的交互界面（可能是命令行 TUI 或图形界面），然后允许你配置并接入后端不同的 AI 模型服务，比如 OpenAI 的 GPT 系列、Anthropic 的 Claude，或者我们今天重点要用的——国产的 DeepSeek。

它的价值在于：

  • 统一入口 ：无需在不同平台的网页间切换，一个工具管理所有对话。
  • 高度可定制 ：可以灵活配置模型 API 地址、密钥、上下文长度等参数。
  • 本地化与隐私 ：某些部署方式可以更好地保护对话隐私，并优化国内访问体验。
  • 开发者友好 ：通常提供丰富的快捷键、代码高亮、历史记录等功能，提升开发效率。

简单说，Codex 是一个让你用得更爽的 AI 对话工具。

1.2 什么是 DeepSeek 大模型？

DeepSeek 是由深度求索公司开发的国产大型语言模型。它有几个非常吸引开发者的特点：

  • 完全免费 ：通过官方 API 调用，目前对公众免费开放，这为开发者提供了极大的便利和成本优势。
  • 强大的代码能力 ：在多项基准测试中，DeepSeek 的代码生成和理解能力表现突出，非常适合编程辅助。
  • 超长上下文 ：最新版本支持 128K 甚至更长的上下文窗口，可以处理非常长的代码文件或技术文档。
  • 国内直接访问 ：API 服务器在国内，访问速度快且稳定，无需额外配置网络环境。

对于国内开发者而言，DeepSeek 是一个在性能、成本和可访问性上都非常平衡的选择。

1.3 组合优势：Codex 接入 DeepSeek

将 Codex 作为前端客户端，DeepSeek 作为后端推理引擎，这个组合解决了几个关键痛点：

  1. 摆脱订阅制 ：无需支付 ChatGPT Plus 等订阅费用。
  2. 访问稳定 ：直接使用国内 API，告别网络波动和连接中断。
  3. 体验优化 ：利用 Codex 客户端的本地化功能（如快捷键、主题、会话管理），获得比单纯使用网页版更好的交互体验。
  4. 集成工作流 ：可以更方便地将 AI 助手与本地开发环境（如 VSCode）结合使用。

接下来，我们就开始具体的安装和配置之旅。

2. 环境准备与前置检查

在安装任何软件之前，准备好正确的环境是成功的第一步。本节将详细说明所需的系统环境、工具依赖以及必要的账户准备。

2.1 系统与工具要求

Codex 作为一个客户端工具，通常有多种安装方式。我们需要根据你的操作系统来选择最合适的方法。

  • 操作系统 ：

    • Windows 10/11 ：推荐使用 Windows Terminal 或 PowerShell 7+ 以获得更好的命令行体验。
    • macOS ：版本 10.15 (Catalina) 或更高。建议使用系统自带的 Terminal 或 iTerm2。
    • Linux ：主流的发行版均可，如 Ubuntu 20.04+/CentOS 8+/Arch Linux 等。需要基本的命令行操作知识。

  • 必备工具 ：

    • Git ：用于克隆 Codex 的源代码仓库（如果从源码安装）。你可以从 Git 官网 下载并安装。
    • Node.js 与 npm ：许多现代命令行工具基于 Node.js 开发。请安装 Node.js 18 或更高版本。安装 Node.js 时会自动包含 npm。你可以访问 Node.js 官网 下载 LTS 版本。
    • Python 3.8+ （可选但推荐）：部分工具链或脚本可能需要 Python。系统可能已预装，可通过 python3 --version 或 python --version 检查。
    • 包管理器 ：根据你的系统，可能需要用到 brew (macOS)、 apt / yum / dnf (Linux)、 winget / choco (Windows)。

2.2 获取 DeepSeek API Key

DeepSeek 的免费 API 是本次配置的核心。你需要注册一个账户并获取 API Key。

  1. 访问官网 ：打开浏览器，访问 DeepSeek 开放平台 。
  2. 注册/登录 ：使用手机号或邮箱注册一个新账户，或直接登录。
  3. 创建 API Key ：
    • 登录后，在控制台页面通常会有“API Keys”或“密钥管理”的入口。
    • 点击“创建新的 API Key”或类似按钮。
    • 为这个 Key 起一个名字，例如 “My-Codex-Client”。
    • 创建成功后， 务必立即复制并妥善保存 这个 Key。它通常是一串以 sk- 开头的长字符。页面关闭后可能无法再次查看完整 Key，只能重新生成。

安全提示 ：API Key 是你的身份凭证，相当于密码。不要将它直接提交到公开的代码仓库（如 GitHub）或分享给他人。泄露可能导致他人滥用你的额度。

2.3 网络连通性测试（可选但建议）

为了确保后续配置顺利，可以简单测试一下你的机器是否能正常访问 DeepSeek API。 打开你的终端（命令行），执行以下命令：

# 测试 DeepSeek API 基础连通性 (使用一个无害的调用)
curl -X POST https://api.deepseek.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 5
  }'

请将 YOUR_API_KEY_HERE 替换为你刚才获取的真实 API Key。如果网络和 Key 都正常，你会收到一个包含 choices 字段的 JSON 响应，或者一个提示认证失败的响应。如果出现连接超时等错误，请检查你的本地网络设置。

环境准备就绪后，我们就可以开始安装 Codex 客户端了。

3. Codex 客户端的安装与部署

Codex 客户端可能有不同的实现和分支。一种常见且流行的版本是 codex-cli 或类似的开源项目。由于网络信息中提到了“ccswitch”等关键词，我们推测安装可能涉及一个代理切换或配置组件。下面我们将以两种最可能的方式进行安装演示。

3.1 安装方式一：通过 npm 全局安装（推荐首选）

这是最简洁的安装方式，前提是你已经安装了 Node.js 和 npm。

  1. 打开终端 ：打开你的命令行工具（Windows PowerShell / CMD, macOS Terminal, Linux Terminal）。

  2. 执行安装命令 ：

    npm install -g @codex/cli

    或者，如果上述包名不对，可以尝试搜索确切的包名：

    npm search codex-cli
# 从结果中找到合适的包，例如 `codex-terminal`
npm install -g codex-terminal

    -g 参数表示全局安装，这样你可以在系统的任何位置运行 codex 命令。

  3. 验证安装 ：

    codex --version
# 或
codex --help

    如果安装成功，命令行会输出 Codex 的版本号或帮助信息。

3.2 安装方式二：从源码克隆与构建

如果通过 npm 无法找到合适的包，或者你想使用最新的开发版本，可以从 GitHub 克隆源码。

  1. 克隆仓库 ：

    git clone https://github.com/某个作者/codex.git
# 注意：这里的仓库地址是示例，你需要根据实际找到的可靠开源项目地址替换。
# 例如，可能是 `git clone https://github.com/microsoft/codex-cli.git` (假设)
cd codex

  2. 安装项目依赖 ：

    npm install
# 或如果项目使用 yarn
yarn install

  3. 构建与链接 ：

    npm run build
# 将本地构建的包链接到全局，使其可以在命令行中调用
npm link

  4. 验证 ：同样使用 codex --help 验证是否安装成功。

3.3 安装方式三：使用预编译的二进制包

有些项目会发布针对不同操作系统的可执行文件。

  1. 访问发布页面 ：前往该 Codex 项目的 GitHub 仓库，找到 Releases 页面。
  2. 下载对应版本 ：根据你的操作系统（Windows-x64, macOS-arm64, linux-x64等）下载对应的压缩包（如 .zip 或 .tar.gz ）。
  3. 解压并放置到系统路径 ：
    • Windows ：解压后，你会得到一个 codex.exe 文件。你可以将其放在任意目录，然后将该目录添加到系统的 PATH 环境变量中。
    • macOS/Linux ：解压后，通常得到一个名为 codex 的可执行文件。你可以将其移动到 /usr/local/bin/ 目录下（需要 sudo 权限），或者放到 ~/bin 目录并确保该目录在 PATH 中。
    # Linux/macOS 示例
tar -zxvf codex-linux-x64.tar.gz
chmod +x codex # 添加执行权限
sudo mv codex /usr/local/bin/
  4. 验证 ：打开新的终端窗口，输入 codex ，看是否能启动。

重要提示 ：由于“Codex”这个名字比较通用，你在互联网上可能会找到多个不同的项目。请务必通过官方文档、GitHub Star 数、社区活跃度等判断哪个是当前主流且维护良好的版本。本文的步骤是通用流程，具体命令请以你选择项目的官方 README 为准。

4. 配置 Codex 接入 DeepSeek API

安装好客户端后，最关键的一步就是配置它，让它知道去哪里（DeepSeek API）以及用什么身份（你的 API Key）获取 AI 服务。

4.1 初始化配置

大多数 CLI 工具在第一次运行时，会引导你进行初始化配置，或者要求你编辑一个配置文件。

  1. 启动 Codex 配置向导 （如果支持）：

    codex config init

    或者，直接运行 codex ，它可能会提示你尚未配置，并进入交互式配置模式。

  2. 如果没有向导，则手动创建配置文件 。 Codex 的配置文件通常位于用户主目录下的一个隐藏文件夹中，例如 ~/.codex/config.json (Linux/macOS) 或 C:\Users\<你的用户名>\.codex\config.json (Windows)。 你可以用任何文本编辑器创建并编辑这个文件。

4.2 编写核心配置文件

下面是一个典型的 config.json 配置文件示例，用于接入 DeepSeek。你需要根据你的实际情况修改。

{
  "version": "1.0",
  "model": "deepseek-chat", // DeepSeek 的聊天模型
  "api_base_url": "https://api.deepseek.com/v1", // DeepSeek API 基础地址
  "api_key": "sk-your-actual-deepseek-api-key-here", // 替换成你的真实 API Key！
  "default_system_prompt": "You are a helpful programming assistant. You answer questions concisely and provide code examples when relevant.",
  "ui": {
    "theme": "dark",
    "show_line_numbers": true
  },
  "features": {
    "stream": true, // 启用流式输出，体验更好
    "save_history": true,
    "context_window": 128000 // 上下文窗口大小，根据模型能力设置
  }
}

配置项详解 ：

  • model : 指定要使用的模型。DeepSeek 可能提供多个模型，如 deepseek-chat (通用对话)、 deepseek-coder (专用代码模型)。请查阅 DeepSeek 官方文档获取最新模型列表。
  • api_base_url : 这是 DeepSeek API 的端点地址。务必确认地址正确。
  • api_key : 最重要的部分 。将 sk-your-actual-deepseek-api-key-here 替换为你在第 2.2 步中获取的真实密钥。
  • default_system_prompt : 系统提示词，用于设定 AI 的行为角色。你可以根据需要修改，例如让它更专注于代码审查或算法解释。
  • features.stream : 建议设为 true ，这样 AI 的回复会逐字显示，而不是等待全部生成完毕再显示，体验更流畅。

4.3 关于 “ccswitch” 或代理配置

在网络热词中出现了 ccswitch 、 cc switch local proxy failed 等字样。这暗示某些 Codex 版本或配置中，可能包含一个用于切换不同模型服务商（如 OpenAI, Claude, DeepSeek）的代理或路由组件。

如果你的 Codex 客户端有类似功能，配置可能略有不同。你可能需要在一个 providers 或 endpoints 的列表中进行配置：

{
  "providers": [
    {
      "name": "deepseek",
      "type": "openai", // 很多国产 API 兼容 OpenAI 格式
      "base_url": "https://api.deepseek.com/v1",
      "api_key": "sk-...",
      "default_model": "deepseek-chat"
    }
  ],
  "default_provider": "deepseek"
}

如果遇到 cc switch local proxy failed 这类错误，通常意味着：

  1. 配置的 base_url 或 api_key 不正确。
  2. 本地代理设置（如果工具内部尝试启动一个本地代理服务）失败，可能是端口冲突或权限问题。可以尝试检查配置文件中是否有 proxy 或 local_port 相关设置，并确保指定端口未被占用。

最稳妥的方法是查阅你所使用的 Codex 客户端的官方文档或 GitHub 仓库的 Issues 部分，寻找关于 DeepSeek 配置的具体说明。

5. 运行与测试：你的第一个 AI 对话

配置完成后，让我们启动 Codex 并与 DeepSeek 进行第一次对话，验证整个链路是否通畅。

5.1 启动 Codex 客户端

在终端中直接输入命令：

codex

如果一切配置正确，你应该会看到一个基于终端的用户界面（TUI）启动。这可能是一个类似聊天软件的界面，或者一个交互式命令行提示符。

5.2 进行测试对话

在 Codex 的界面中，通常会有一个闪烁的光标等待你输入。输入一个简单的测试问题：

你好，请用 Python 写一个函数，计算斐波那契数列的第 n 项。

按下回车键发送。如果配置正确，你应该会看到 DeepSeek 模型开始流式输出回答，内容大致如下：

def fibonacci(n):
    """
    计算斐波那契数列的第 n 项。
    参数:
        n (int): 要计算的项数（从0开始或从1开始取决于定义，这里假设第1项是0，第2项是1）。
    返回:
        int: 第 n 项的值。
    """
    if n <= 0:
        return 0
    elif n == 1:
        return 1
    else:
        a, b = 0, 1
        for _ in range(2, n + 1):
            a, b = b, a + b
        return b

# 测试函数
print(fibonacci(10))  # 输出第10项：34

5.3 验证与调试

如果出现错误，不要慌张。仔细阅读错误信息，它们是排查问题的关键。

  • 常见错误1： Invalid API Key 或 Authentication failed

    • 原因 ：配置文件中的 api_key 填写错误，或 Key 已失效。
    • 解决 ：重新登录 DeepSeek 平台，检查 API Key 是否正确复制，并确保没有多余的空格。可以尝试创建一个新的 API Key 替换。

  • 常见错误2： Connection refused 或 Failed to connect to ...

    • 原因 ： api_base_url 地址错误，或者你的网络无法访问该地址。
    • 解决 ：确认 api_base_url 是 https://api.deepseek.com/v1 。用浏览器或 curl 命令测试该地址的连通性。

  • 常见错误3： Model not found

    • 原因 ：配置的 model 名称不正确。
    • 解决 ：查阅 DeepSeek 最新文档，确认可用的模型名称，并更新配置文件。

  • 常见错误4： cc switch local proxy failed

    • 原因 ：客户端内部的代理组件启动失败。
    • 解决 ：
      1. 检查配置中是否有关于本地代理端口（如 8080 , 7860 ）的设置，尝试更换一个端口。
      2. 以管理员/root权限运行命令（不推荐长期使用，仅作测试）。
      3. 如果工具提供绕过本地代理的选项，尝试直接连接 API。

6. 进阶使用与最佳实践

成功运行只是第一步，要让 Codex + DeepSeek 真正成为你的生产力工具，还需要掌握一些进阶用法和最佳实践。

6.1 多会话与上下文管理

一个好的 AI 助手客户端应该支持多会话。

  • 新建会话 ：在 TUI 界面中，通常有快捷键（如 Ctrl+N ）或菜单选项来创建一个新的聊天会话。这可以让你同时进行多个不同主题的对话，互不干扰。
  • 会话历史 ：确保 save_history 功能开启。你的对话历史会被保存，下次启动时可以继续。历史记录通常保存在 ~/.codex/history/ 目录下。
  • 上下文长度 ：DeepSeek 支持长上下文（如 128K）。在配置中合理设置 context_window 。但请注意，过长的上下文会增加每次 API 调用的 token 消耗（虽然免费，但可能有速率限制）和响应时间。对于大多数编程问答，16K-32K 的上下文已足够。

6.2 优化提示词（Prompt）技巧

系统提示词 ( default_system_prompt ) 和你的提问方式极大影响回答质量。

  • 角色设定 ：在系统提示词中明确 AI 的角色。例如：

    “你是一位经验丰富的全栈软件工程师，擅长 Python、Java 和系统设计。请用中文回答，代码示例要简洁明了，并附上关键解释。”

  • 具体化问题 ：提问越具体，回答越精准。不要问“怎么写代码？”，而是问“用 Python 的 requests 库如何发送一个带 JSON body 和自定义请求头的 POST 请求？”
  • 提供上下文 ：如果需要 AI 基于你的代码回答，可以将相关代码片段粘贴到问题中。例如：“这是我的 Flask 路由代码，它目前返回 500 错误，可能是什么原因？[粘贴代码]”
  • 分步任务 ：对于复杂任务，可以要求 AI 分步思考或输出。例如：“请先分析这个需求，然后给出数据库设计草图，最后写出核心 API 的伪代码。”

6.3 集成到开发工作流

  • VSCode 集成 ：虽然 Codex 本身是独立客户端，但你可以将其与 VSCode 的终端面板结合使用。在 VSCode 中打开集成终端 ( Ctrl+``)，运行 codex`，就可以边写代码边问问题，无需切换窗口。
  • 代码片段生成与解释 ：直接向 Codex 描述你想要的功能，生成代码片段后，可以要求它逐行解释，加深理解。
  • 错误排查 ：将复杂的错误日志复制给 Codex，让它帮你分析可能的原因和解决方案。
  • 文档查询 ：忘记某个库的函数用法时，可以直接问 Codex，比翻文档更快。

6.4 安全与成本注意事项

  • API Key 安全 ：重申一遍，切勿将包含真实 API Key 的配置文件上传到公开 Git 仓库。可以考虑将 API Key 存储在环境变量中，然后在配置文件中引用。 
    # 在 shell 中设置环境变量
export DEEPSEEK_API_KEY='sk-...'

    // 在 config.json 中引用环境变量
{
  "api_key": "${DEEPSEEK_API_KEY}"
}
  • 理解免费限制 ：虽然 DeepSeek API 目前免费，但通常会有每分钟/每小时/每天的请求次数（Rate Limit）和令牌（Token）消耗限制。频繁、大量地调用可能会被限流。用于学习和日常辅助开发完全足够，但避免编写脚本进行无意义的压力测试。
  • 内容审查 ：对于生成的内容，尤其是代码，要有基本的审查意识。AI 生成的代码不一定总是最优或最安全的，特别是涉及数据库操作、文件 IO、网络请求等关键环节时，务必人工复核。

7. 常见问题与故障排除 (FAQ)

这里汇总了在安装、配置和使用过程中可能遇到的其他典型问题及其解决方案。

问题现象 可能原因 排查与解决思路
运行 codex 命令提示“未找到命令” 1. 未全局安装 ( -g )。
2. 安装目录未加入系统 PATH。
3. 安装失败。		 1. 使用 `npm list -g
安装依赖时 npm install 报错（网络超时） npm 源访问慢或被墙。 更换为国内镜像源：
npm config set registry https://registry.npmmirror.com
配置正确，但 AI 回复慢或经常中断 1. 网络不稳定。
2. DeepSeek 服务器负载高。
3. 上下文过长导致生成慢。		 1. 检查本地网络。
2. 稍后再试，或尝试简化问题。
3. 在配置中调小 context_window ，或在对话中开启新会话重置上下文。
流式输出不流畅，一次性显示全文 客户端或配置未启用流式输出。 检查配置文件中 features.stream 是否设置为 true 。部分客户端可能需要特定启动参数，如 codex --stream 。
想切换回其他模型（如 OpenAI） 需要配置多模型支持。 在配置文件的 providers 数组中添加新的 provider 配置，并修改 default_provider 。确保你拥有对应模型的 API Key。
历史记录没有保存 配置文件中的 save_history 被关闭，或历史存储路径无写入权限。 1. 检查配置项。
2. 检查 ~/.codex/ 目录的权限。
在 Windows 上遇到奇怪的字符显示（乱码） 终端编码问题。 尝试将终端（如 PowerShell、Windows Terminal）的编码设置为 UTF-8。

如果遇到上述未涵盖的问题，建议按以下顺序排查：

  1. 查日志 ：运行 codex 时添加 --verbose 或 --debug 参数，查看详细输出。
  2. 查文档 ：仔细阅读你所使用的 Codex 客户端的 GitHub README 和 Wiki。
  3. 查社区 ：在 GitHub Issues、相关论坛或社群中搜索错误关键词。
  4. 简化测试 ：用最基础的 curl 命令（如第 2.3 步所示）直接测试 DeepSeek API，先确认 API 本身是通的，从而隔离客户端问题。

至此，你已经完成了从零到一的 Codex 安装、DeepSeek 接入以及基础使用。这个组合为你提供了一个强大、免费且稳定的本地 AI 编程伙伴。接下来，就是在你的实际开发项目中不断去使用它，探索更多提高效率的使用场景了。

# DeepSeek
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

Ox Alpha 模型火爆全网，完全免费使用，开发者狂喜，附使用教程

avatar AI编程社区

1M 上下文 0.10 入场:5 模型长文档屠夫榜

本文针对2026年Q3长文档处理场景，对比分析了5款支持1M上下文的AI模型（DeepSeek-V4-Flash、Kimi-K2.5、GLM-5.1、Qwen3.6-Max-Preview、Claude-Sonnet-4-6）在成本、性能和适用场景上的表现。文章通过实际案例（21万字合同处理）展示了1M上下文直灌相比传统RAG切片方案的成本优势（从50美元降至0.02美元），详细介绍了各模型的定价

avatar AI编程社区
cover

Design Token 驱动暗色主题——CSS 变量工程化实践

avatar AI编程社区