DeepSeek 终端助手接入

Codex 接入

6 分钟阅读

接入 Codex

Codex 是OpenAI推出的开源编程Agent，支持CLI与桌面App两种使用形态，是目前能力最强的开源编程Agent之一。它原生支持复杂多步任务处理、工具调用、项目级代码操作、自动Debug与测试生成，可实现从需求描述到完整项目开发的端到端自动化，大幅降低大型项目的开发成本，适合资深开发者、AI Agent爱好者与开源项目维护者使用。

由于Codex原生使用OpenAI Responses API与模型通信，而DeepSeek提供Anthropic兼容API，因此需要通过Moon Bridge作为请求转发层，将OpenAI Responses格式的请求转换为DeepSeek兼容的格式，即可将DeepSeek V4系列模型作为Codex的后端推理引擎。接入DeepSeek后，可充分发挥DeepSeek V4的强推理能力与百万上下文优势，处理大型项目的复杂任务表现优异，同时高性价比可大幅降低Agent的运行成本。

通过本教程，你将掌握依赖安装、Moon Bridge配置、Codex配置、启动验证与问题排查的全流程，最终实现DeepSeek V4驱动的高性能编程Agent。

💡 前置准备

提前获取DeepSeek API Key：前往DeepSeek开放平台创建并复制，确保已开启V4系列模型的访问权限。
环境要求：
- Node.js ≥18.0.0（可执行node --version验证），用于运行Codex CLI；
- Go ≥1.25.0（可执行go version验证），用于编译运行Moon Bridge；
- Git ≥2.30.0（可执行git --version验证），用于克隆Moon Bridge仓库。
网络要求：确保可正常访问GitHub、DeepSeek API地址https://api.deepseek.com与Go模块镜像；国内用户可执行go env -w GOPROXY=https://goproxy.cn,direct配置Go代理，避免依赖下载失败。
权限要求：安装全局npm包、编译Go程序需要系统管理员权限，Linux/macOS用户可能需要使用sudo，Windows用户需要以管理员身份运行终端。

1. 安装依赖

Node.js 18+。
Go 1.25+。 依赖说明：
Node.js是Codex CLI的运行环境，18及以上版本支持所需的ES特性，版本过低会导致安装失败。
Go是Moon Bridge的开发语言，1.25及以上版本支持所需的标准库特性，版本过低会导致编译失败。
安装 Codex CLI：

npm install -g @openai/codex

操作目的：全局安装Codex CLI工具，使其可在系统任意目录下调用。 预期结果：npm无报错，安装完成后无异常提示。 注意事项：国内用户可先执行npm config set registry https://registry.npmmirror.com切换为淘宝npm镜像，提升安装速度。

验证安装：

codex --version
go version

操作目的：验证Codex CLI与Go是否安装成功，版本是否符合要求。 预期结果：两条命令分别输出对应的版本号，例如codex v0.1.0、go version go1.25.0 linux/amd64，无报错信息。 注意事项：若提示command not found: codex，检查npm全局安装路径是否已添加到系统环境变量中。

2. 获取 DeepSeek API Key

前往 DeepSeek 开放平台创建并复制 API Key。 操作说明：创建API Key时建议设置合理的过期时间与IP白名单，提升安全性；确保API Key已开启DeepSeek V4系列模型的访问权限。 注意事项：API Key请妥善保管，不要泄露给他人，避免产生不必要的费用损失。

3. 配置 Moon Bridge

克隆 Moon Bridge 并创建本地配置文件：

git clone https://github.com/ZhiYi-R/moon-bridge.git
cd moon-bridge

操作目的：克隆Moon Bridge的源代码到本地，拉取完整的代码库，进入项目目录准备配置。 预期结果：当前目录下生成moon-bridge文件夹，进入后可看到config.example.yml等配置文件。 注意事项：国内用户若克隆速度慢，可使用GitHub镜像地址替换原仓库地址。

创建 config.yml，并填入 DeepSeek API Key：

mode: "Transform"

server:
  addr: "127.0.0.1:38440"

models:
  deepseek-v4-pro:
    context_window: 1000000
    max_output_tokens: 384000
    default_reasoning_level: "high"
    supported_reasoning_levels:
      - effort: "high"
        description: "High reasoning effort"
      - effort: "xhigh"
        description: "Extra high reasoning effort"
    supports_reasoning_summaries: true
    default_reasoning_summary: "auto"
    extensions:
      deepseek_v4:
        enabled: true
  deepseek-v4-flash:
    context_window: 1000000
    max_output_tokens: 384000
    default_reasoning_level: "high"
    supported_reasoning_levels:
      - effort: "high"
        description: "High reasoning effort"
      - effort: "xhigh"
        description: "Extra high reasoning effort"
    supports_reasoning_summaries: true
    default_reasoning_summary: "auto"
    extensions:
      deepseek_v4:
        enabled: true

providers:
  deepseek:
    base_url: "https://api.deepseek.com/anthropic"
    api_key: "sk-your-deepseek-api-key"
    offers:
      - model: deepseek-v4-pro
      - model: deepseek-v4-flash

routes:
  moonbridge:
    model: deepseek-v4-pro
    provider: deepseek

defaults:
  model: moonbridge
  max_tokens: 65536

配置文件详细解释： YAML格式对缩进敏感，需使用空格缩进（2个空格为一个层级），不得使用Tab，否则会导致配置加载失败。各字段含义如下：

字段	含义	注意事项
`mode: "Transform"`	开启请求转换模式，将OpenAI Responses API请求转换为DeepSeek Anthropic兼容格式	固定为`Transform`，不得修改
`server.addr`	Moon Bridge服务监听的地址与端口	默认为`127.0.0.1:38440`，仅本地可访问；若需其他设备访问可改为`0.0.0.0:38440`，并开放对应端口
`models`	模型元数据配置，定义DeepSeek V4 Pro与Flash的能力参数	所有参数与DeepSeek官方规格一致，无需修改
`models.deepseek-v4-pro.context_window`	模型的上下文窗口大小	固定为`1000000`，即100万token
`models.deepseek-v4-pro.max_output_tokens`	模型最大输出token数	固定为`384000`，匹配官方最大输出规格
`models.deepseek-v4-pro.extensions.deepseek_v4.enabled`	启用DeepSeek V4专属适配扩展	固定为`true`，确保请求格式正确
`providers.deepseek`	DeepSeek服务商配置
`providers.deepseek.base_url`	DeepSeek Anthropic兼容API地址	固定为`https://api.deepseek.com/anthropic`，不得修改
`providers.deepseek.api_key`	你的DeepSeek API Key	将`sk-your-deepseek-api-key`替换为你自己的API Key，保留引号
`providers.deepseek.offers`	该服务商提供的模型列表	保持默认即可，包含Pro与Flash两个模型
`routes.moonbridge`	路由配置，将`moonbridge`模型名路由到DeepSeek的`deepseek-v4-pro`模型	可按需修改路由的目标模型，比如改为Flash
`defaults`	全局默认配置	`default.model`为默认使用的模型，`max_tokens`为默认最大输出token数

这个最小配置使用当前 Moon Bridge 配置结构，启用 DeepSeek V4 Pro / Flash、Codex 模型元数据和 DeepSeek V4 兼容扩展。如果需要图片输入、Web Search 或多 Provider 路由，可以再参考 Moon Bridge 的 config.example.yml 扩展配置。 扩展说明：config.example.yml包含了视觉支持、多服务商路由、工具调用、Web搜索等高级配置的示例，可按需添加对应的配置段。

操作说明：在moon-bridge目录下创建config.yml文件，粘贴上述配置内容，替换API Key后保存即可。 预期结果：config.yml文件位于moon-bridge根目录，格式正确无语法错误。

4. 启动 Moon Bridge

go run ./cmd/moonbridge --config config.yml

操作目的：编译并启动Moon Bridge服务，加载config.yml配置文件，监听指定端口等待请求。 预期结果：终端输出启动日志，显示INFO server started on 127.0.0.1:38440，无报错信息。 注意事项：

启动后请勿关闭当前终端，否则服务会停止；若需后台运行，Linux/macOS可执行nohup go run ./cmd/moonbridge --config config.yml &，Windows可使用Start-Job命令后台运行。
若启动报错端口被占用，可修改config.yml中server.addr的端口为其他未被占用的端口，后续所有步骤中的端口需同步修改。
若启动报错配置文件格式错误，检查YAML缩进是否正确，有无多余的空格或语法错误。

保持这个终端运行。默认情况下，Moon Bridge 监听 127.0.0.1:38440，并提供 OpenAI Responses 兼容接口：

http://127.0.0.1:38440/v1/responses

接口说明：该接口完全兼容OpenAI Responses API格式，Codex的请求会发送到这个地址，由Moon Bridge转发到DeepSeek。

5. 生成 Codex 配置

另开一个终端，在 Moon Bridge 目录下执行以下命令，将 Codex 的 config.toml 和 models_catalog.json 写入 CODEX_HOME_DIR。 操作说明：不要关闭运行Moon Bridge的终端，新打开一个终端执行后续命令，避免Moon Bridge服务停止。

如果你已经有 Codex 配置，建议先备份当前 config.toml： 备份目的：避免原有配置被覆盖，若配置失败可恢复到原有状态。

macOS / Linux:

CODEX_HOME_DIR="${CODEX_HOME:-$HOME/.codex}"
mkdir -p "$CODEX_HOME_DIR"

# 备份当前config.toml
cp "$CODEX_HOME_DIR/config.toml" "$CODEX_HOME_DIR/config.toml.bak" 2>/dev/null || true

# 创建config.toml和models_catalog.json
MODEL="$(go run ./cmd/moonbridge --config config.yml --print-codex-model)"
go run ./cmd/moonbridge \
  --config config.yml \
  --print-codex-config "$MODEL" \
  --codex-base-url "http://127.0.0.1:38440/v1" \
  --codex-home "$CODEX_HOME_DIR" \
  > "$CODEX_HOME_DIR/config.toml"

命令解释：

定义CODEX_HOME_DIR为Codex的配置目录，默认是当前用户主目录下的.codex文件夹，若已设置CODEX_HOME环境变量则使用该值。
创建CODEX_HOME_DIR目录，若已存在则跳过。
备份原有config.toml为config.toml.bak，若文件不存在则忽略错误。
执行--print-codex-model获取Moon Bridge配置的默认Codex模型名（默认为moonbridge）。
执行--print-codex-config生成Codex所需的config.toml配置文件，同时自动生成models_catalog.json模型元数据文件，写入到CODEX_HOME_DIR目录中。
--codex-base-url指定Codex请求发送的地址，需与Moon Bridge的监听地址一致，若修改了Moon Bridge的端口，此处需同步修改。

预期结果：命令执行无报错，~/.codex目录下生成config.toml与models_catalog.json两个文件。

Windows PowerShell:

$CODEX_HOME_DIR = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { "$HOME\.codex" }
New-Item -ItemType Directory -Force -Path $CODEX_HOME_DIR | Out-Null

# 备份当前config.toml
if (Test-Path "$CODEX_HOME_DIR\config.toml") {
  Copy-Item "$CODEX_HOME_DIR\config.toml" "$CODEX_HOME_DIR\config.toml.bak" -Force
}

# 创建config.toml和models_catalog.json
$MODEL = go run ./cmd/moonbridge --config config.yml --print-codex-model
go run ./cmd/moonbridge `
  --config config.yml `
  --print-codex-config "$MODEL" `
  --codex-base-url "http://127.0.0.1:38440/v1" `
  --codex-home "$CODEX_HOME_DIR" `
  | Set-Content -Path "$CODEX_HOME_DIR\config.toml"

命令解释：与Linux/macOS命令逻辑一致，适配PowerShell的语法。 预期结果：命令执行无报错，C:\Users\你的用户名\.codex目录下生成config.toml与models_catalog.json两个文件。

这会创建：

config.toml：Codex provider 配置，使用 wire_api = "responses"。
models_catalog.json：Codex 使用的模型能力元数据，包括上下文窗口、推理档位和工具支持。

生成前可以先检查 Moon Bridge 读到的默认 Codex 模型：

go run ./cmd/moonbridge --config config.yml --print-codex-model
# moonbridge

验证说明：执行该命令后正常输出moonbridge，说明Moon Bridge配置正确，可正常读取模型信息。

6. 启动 Codex

进入要处理的项目目录，然后启动 Codex。

cd /path/to/my-project
codex

操作目的：进入目标项目目录后启动Codex，使其自动读取当前目录下的所有文件作为上下文，处理项目相关的复杂任务。 预期结果：终端进入Codex交互界面，显示欢迎信息，输入问题后可正常收到模型回复；同时运行Moon Bridge的终端会出现POST /v1/responses的请求日志，说明请求已成功转发到DeepSeek。 使用说明：Codex支持多步任务处理，你可以直接描述需求，例如「基于FastAPI开发一个用户管理系统，包含增删改查接口、JWT认证、SQLite数据库，自动生成README与测试用例」，Codex会自动完成整个项目的开发。

Codex App 也可以使用同一份生成的 Codex 配置。说明：桌面版Codex App的配置目录与CLI一致，只需将生成的两个文件放到配置目录中，即可在App中使用DeepSeek模型，无需重复配置。

一键启动脚本

Moon Bridge 提供了面向 Codex CLI 的辅助脚本，可以一键构建并启动代理、生成 Codex 配置并启动 Codex：

./scripts/start_codex_with_moonbridge.sh --project-directory /path/to/my-project

脚本说明：该脚本封装了Moon Bridge启动、Codex配置生成、Codex启动的全流程，无需手动执行多个步骤，适合日常使用。 预期结果：脚本自动执行所有步骤，直接进入Codex交互界面，无需手动操作。

Windows PowerShell 用户可以使用：

.\scripts\start_codex_with_moonbridge.ps1 -ProjectDirectory C:\path\to\my-project

注意事项：执行前需确保脚本有执行权限，Windows用户若提示脚本禁止运行，可执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser放开权限。

验证

查看可用模型：

curl http://127.0.0.1:38440/v1/models

操作目的：验证Moon Bridge是否正常运行，是否正确返回可用模型列表。 预期结果：返回JSON格式的模型列表，包含moonbridge、deepseek-v4-pro、deepseek-v4-flash等模型信息。

发送一条 Responses 测试请求：

curl http://127.0.0.1:38440/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moonbridge",
    "input": "请用一句话打个招呼。",
    "max_output_tokens": 1024
  }'

操作目的：验证请求转发是否正常，DeepSeek API是否可正常调用。 预期结果：返回JSON格式的响应，包含模型的回复内容，例如{"id":"rsp-xxx","output":[{"type":"text","text":"你好！很高兴能为你提供帮助，有什么问题都可以随时问我~"}]}。

当 Codex 发出请求后，Moon Bridge 终端应出现 POST /v1/responses 日志。 验证说明：若日志出现，说明Codex的请求已成功发送到Moon Bridge，转发链路正常。

也可以验证推理档位是否进入配置：

curl http://127.0.0.1:38440/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moonbridge",
    "input": "用一句话说明 Moon Bridge 的作用。",
    "reasoning": {"effort": "high"},
    "max_output_tokens": 1024
  }'

操作目的：验证reasoning_effort参数是否正常传递到DeepSeek API。 预期结果：返回的回复内容更详细，推理更深入，Moon Bridge日志中可看到参数已正确传递。

常见问题

connection refused：Moon Bridge 未启动，或 config.yml 中的 server.addr 使用了其他端口。 根本原因：Moon Bridge服务未正常运行，或请求地址与Moon Bridge监听地址不一致。 排查步骤：

检查运行Moon Bridge的终端是否有报错，服务是否正常启动；
检查config.yml中的server.addr配置是否与请求地址一致，端口是否正确；
检查端口是否被防火墙拦截，是否被其他程序占用。 解决方法：启动Moon Bridge服务，修改端口为未被占用的端口，开放防火墙对应端口。

Codex 看不到模型：重新执行第 5 步；Codex 需要 CODEX_HOME 目录下的 models_catalog.json。 根本原因：models_catalog.json文件不存在或格式错误，Codex无法识别可用模型。 排查步骤：

检查CODEX_HOME目录下是否存在models_catalog.json文件；
检查文件格式是否正确，有无损坏；
检查CODEX_HOME环境变量是否设置正确。 解决方法：重新执行第5步生成配置文件，确保文件生成在正确的目录。

配置加载失败且提示 field provider not found：你使用的是旧版 provider.providers 配置；当前格式是顶层 providers、models、routes、defaults。 根本原因：使用了旧版本Moon Bridge的配置格式，旧版本的providers嵌套在provider字段下，新版本为顶层字段。 解决方法：使用教程中提供的最新配置格式，将providers、models、routes、defaults放在配置文件顶层，不要嵌套。
401 或认证失败：检查 config.yml 中的 DeepSeek API Key 是否正确。 根本原因：API Key错误、过期或无对应模型的访问权限。 排查步骤：

检查config.yml中的API Key是否正确，有无前后空格，是否与开放平台的Key一致；
检查API Key是否已过期，是否已开启DeepSeek V4模型的访问权限；
检查API Key的IP白名单是否包含当前设备的IP。 解决方法：重新生成正确的API Key，开启对应模型的访问权限，调整IP白名单配置。

402 或余额错误：检查 DeepSeek 开放平台账户余额。 根本原因：DeepSeek账户余额不足，无法完成API调用。 解决方法：登录DeepSeek开放平台充值余额。
图片输入失败：如果启用了 Visual 扩展，需要单独配置视觉 Provider（如 Kimi）的 API Key。你可以配置该 Provider，或移除 visual.enabled: true 来禁用 Visual 扩展。 根本原因：开启了视觉扩展但未配置视觉Provider，或视觉Provider配置错误。 解决方法：要么配置支持视觉的Provider（如Kimi）的API Key，要么从配置文件中移除visual.enabled: true字段禁用视觉扩展。

补充常见问题：

go run编译失败：检查Go版本是否≥1.25，是否配置了正确的GOPROXY，依赖是否下载完整；可执行go mod tidy重新下载依赖。
Codex启动报错配置文件格式错误：检查config.toml格式是否正确，重新执行第5步生成配置文件。
模型回复被截断：在config.yml的defaults.max_tokens中调大最大输出token数，最大可设置为384000。
Moon Bridge日志显示404错误：检查providers.deepseek.base_url是否正确，必须为https://api.deepseek.com/anthropic，末尾不要加斜杠。

参考资料

awesome-deepseek-agent

✨ 教程总结 本教程覆盖了从依赖安装、Moon Bridge配置、Codex配置到启动验证的全流程，你现在已经拥有了一个由DeepSeek V4驱动的高性能编程Agent，可处理大型项目开发、重构、Debug等复杂任务。下一步你可以：

访问Moon Bridge GitHub仓库查看更多高级配置，比如多服务商路由、工具调用、视觉支持、Web搜索等；
访问Codex官方仓库查看更多Agent使用技巧与任务示例；
查看awesome-deepseek-agent获取更多DeepSeek Agent的使用案例与最佳实践；
若遇到问题可前往对应项目的GitHub Issue提交反馈，或加入社区交流群寻求帮助。

上一页Reasonix 使用下一页 Langcli 接入