macOS 下 Codex CLI 接入 DeepSeek 完整配置指南

约 1925 字大约 6 分钟

布欧-Lewyon

2026-06-17

在国内没有 ChatGPT 账号的情况下，仍想用 OpenAI Codex CLI 做终端 Agent，同时把模型成本压到 DeepSeek。本文记录在一台 Intel Mac（macOS 26.x） 上从安装、踩坑到跑通的完整过程，并与 Cursor + DeepSeek 的用法做对照。

1. 背景：Codex 是什么，为什么要接 DeepSeek

Codex CLI 是 OpenAI 开源的终端编程 Agent（codex-cli 0.140.x），能力包括：

读仓库、改多文件、跑 shell、做 refactor
支持 MCP、Skills、AGENTS.md 项目说明
与 Cursor 同属「Agent 循环」，但入口是 纯终端

维度	Cursor	Codex CLI
界面	IDE 图形	终端 TUI
国内 + DeepSeek	✅ Override Base URL 即可	⚠️ 需本地代理（见下文）
计费	Cursor Pro + 可选 BYOK	DeepSeek API 按量
适合	日常改代码、看 diff	脚本化、headless、长任务 Agent

DeepSeek 官方文档 写明 OpenAI 兼容地址为 https://api.deepseek.com，这对 Cursor 完全够用；但对 Codex 0.140+ 还不够，这是本文的核心坑点。

2. 环境前提（本文实测机器）

项目	版本 / 说明
系统	macOS 26.x，Intel（`x86_64`）
Shell	`zsh`
Node	v22.22.0（`nvm use 22`）
包管理	pnpm 10.x、Homebrew
Python	3.11（代理依赖，通过 `uv` 管理）
DeepSeek	控制台 API Key，国内直连 `api.deepseek.com`
Codex	`@openai/codex@0.140.0`

3. 核心原理：为什么 Codex 不能直连 DeepSeek

3.1 两套 API 协议

工具	请求的接口	DeepSeek 是否支持
Cursor	`POST /v1/chat/completions`	✅
Codex 0.140	`POST /v1/responses`	❌ → 404

Codex 从 0.122 起废弃 wire_api = "chat"，自定义 provider 只支持 Responses API。

因此会出现典型报错：

unexpected status 404 Not Found: url: https://api.deepseek.com/responses

或：

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

换 base_url 有没有 /v1 都无法解决——缺的是接口类型，不是 URL 写法。

3.2 `/anthropic` 也不行

DeepSeek 还提供 https://api.deepseek.com/anthropic，给 Claude Code 等 Anthropic Messages 客户端用。
Codex 仍发 OpenAI Responses 格式，不能通过改 /anthropic 解决。

3.3 正确架构

Codex CLI
  → http://127.0.0.1:8787/v1/responses   （本地代理）
      → https://api.deepseek.com/chat/completions

代理项目：deepseek-responses-proxy（本文采用）。

4. 第一步：安装 Codex CLI

4.1 使用 pnpm 全局安装

nvm use 22
pnpm config set registry https://registry.npmmirror.com   # 国内建议换源
pnpm add -g @openai/codex

常见坑：

现象	原因	处理
`resolved 523, downloaded 0` 卡住	旧镜像 `registry.npm.taobao.org`	改为 `registry.npmmirror.com`
`codex: command not found`	PATH 未包含 pnpm 全局 bin	见下文 PATH

PATH 补充（写入 ~/.zshrc）：

export PATH="$HOME/Library/pnpm:$PATH"

验证：

codex --version
# codex-cli 0.140.0

4.2 备选：Homebrew

brew install --cask codex

5. 第二步：配置 DeepSeek API Key

不要把 Key 写进 config.toml 的 env_key 字段。

env_key 填的是 环境变量名，不是 Key 本身。

5.1 写入 `~/.zshrc`

export DEEPSEEK_API_KEY="sk-从-platform.deepseek.com-复制"

source ~/.zshrc
echo $DEEPSEEK_API_KEY   # 必须输出 sk- 开头，不能是「你的sk-密钥」占位符

5.2 首次登录 Codex（可选）

首次运行 codex 会出现登录菜单，国内用户选：

3. Provide your own API key → 粘贴 DeepSeek Key。

或终端非交互登录：

printenv DEEPSEEK_API_KEY | codex login --with-api-key
codex login status

6. 第三步：安装本地 Responses 代理

Codex 0.140 需要代理把 /responses 转成 DeepSeek 的 /chat/completions。

6.1 安装 uv

curl -LsSf https://astral.sh/uv/install.sh | sh
# 安装后 ~/.local/bin 会加入 PATH（install 脚本会写 env）
source "$HOME/.local/bin/env"

6.2 克隆并安装代理

uvx --from git+... 在部分网络下 clone GitHub 会失败，推荐 本地 clone：

git clone --depth 1 https://github.com/holo-q/deepseek-responses-proxy.git \
  ~/.local/share/deepseek-responses-proxy

cd ~/.local/share/deepseek-responses-proxy
uv sync

6.3 启动脚本

创建 ~/.local/bin/start-deepseek-proxy.sh：

#!/bin/zsh
set -euo pipefail

export PATH="$HOME/.local/bin:$PATH"
PROXY_DIR="$HOME/.local/share/deepseek-responses-proxy"

if [[ -z "${DEEPSEEK_API_KEY:-}" ]]; then
  echo "DEEPSEEK_API_KEY 未设置，请先执行: source ~/.zshrc" >&2
  exit 1
fi

cd "$PROXY_DIR"
exec uv run deepseek-responses-proxy \
  --bind 127.0.0.1 \
  --port 8787 \
  --chat-base-url https://api.deepseek.com

chmod +x ~/.local/bin/start-deepseek-proxy.sh

6.4 启动与验证

终端 1（保持运行）：

source ~/.zshrc
start-deepseek-proxy.sh

看到 JSON 日志 "event": "server.start", "port": 8787 即成功。

另开终端验证：

curl http://127.0.0.1:8787/health
# {"status": "ok"}

curl http://127.0.0.1:8787/v1/models
# 含 deepseek-v4-pro、deepseek-v4-flash

代理进程退出后 Codex 会连不上，每次用 Codex+DeepSeek 前需确认代理在跑。

7. 第四步：Codex 配置文件（0.140 新格式）

Codex 0.134+ 不再支持 config.toml 里的 [profiles.xxx] 表，需拆成独立 profile 文件。

7.1 `~/.codex/config.toml`（公共配置）

# 默认模型（不指定 --profile 时使用）
model = "deepseek-v4-pro"
model_provider = "deepseek"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "http://127.0.0.1:8787/v1"
experimental_bearer_token = "codex-deepseek-local"
wire_api = "responses"
requires_openai_auth = false

[projects."/path/to/your/project"]
trust_level = "trusted"

说明：

字段	含义
`base_url`	指向本地代理，不是 `api.deepseek.com`
`experimental_bearer_token`	Codex 访问本地代理用的 token（任意固定字符串）
`wire_api`	必须为 `responses`（0.140 默认，勿写 `chat`）
`requires_openai_auth`	非 OpenAI 网关必须 `false`

7.2 `~/.codex/deepseek-v4-pro.config.toml`（Profile）

model = "deepseek-v4-pro"
model_provider = "deepseek"
model_context_window = 1000000
approval_policy = "untrusted"
sandbox_mode = "workspace-write"

7.3 `~/.codex/deepseek-v4-flash.config.toml`（便宜版）

model = "deepseek-v4-flash"
model_provider = "deepseek"
model_context_window = 1000000
approval_policy = "untrusted"
sandbox_mode = "workspace-write"

若仍保留旧版 [profiles.deepseek-v4-pro]，会报错：

--profile `deepseek-v4-pro` cannot be used while config.toml contains legacy [profiles...]

需删除 config.toml 中的 [profiles.*]，改用上方的独立 .config.toml 文件。

8. 第五步：启动 Codex 并使用

终端 1： 代理（若未运行）

start-deepseek-proxy.sh

终端 2： 进入项目并启动 Codex

source ~/.zshrc
cd /path/to/your/project
codex -p deepseek-v4-pro

首次进入项目会问是否信任目录，自己的仓库选 Yes, continue。

界面应显示：

model: deepseek-v4-pro
directory: .../your-project

测试：

你好，请用中文介绍这个项目的结构

常用命令

命令	说明
`codex -p deepseek-v4-pro`	Pro 模型（推理强）
`codex -p deepseek-v4-flash`	Flash 模型（更便宜）
`codex`	使用 config.toml 默认模型
`/model`	TUI 内切换模型
`/quit`	退出

注意： 使用 -p deepseek-v4-pro，不要只用 -m deepseek-v4-pro，否则可能仍走 OpenAI 默认 provider。

9. 与 Cursor + DeepSeek 的对照配置

Cursor 走 Chat Completions，无需代理。

Cursor Settings → Models

项	值
OpenAI API Key	你的 DeepSeek Key
Override OpenAI Base URL	`https://api.deepseek.com`（不要加 `/v1`）
自定义模型	`deepseek-v4-pro`

Cursor 两套模式（避免冲突）

模式	操作
DeepSeek Key	开 API Key → 选 `deepseek-v4-pro` → 纯文字 Chat
Cursor Pro（Composer）	`Cmd+Shift+0` 关 Key → 选 Composer / Auto

常见报错：

报错	原因
`This model does not support custom API keys`	开着 Key 却选了 Composer
`unknown variant image_url`	DeepSeek API 不支持图片，需 New Chat
Auto 总是 DeepSeek	关掉 `deepseek-v4-pro` 模型开关再用 Auto

10. 踩坑清单（本文真实遇到）

#	现象	根因	解决
1	pnpm 安装卡住	旧 npm 淘宝镜像	`pnpm config set registry https://registry.npmmirror.com`
2	`Missing environment variable: sk-xxx`	把 Key 写进 `env_key`	`env_key = "DEEPSEEK_API_KEY"`
3	`echo $DEEPSEEK_API_KEY` 输出「你的sk-密钥」	复制了教程占位符	改成真实 Key
4	404 `/responses`	Codex 与 DeepSeek 协议不兼容	本地 deepseek-responses-proxy
5	profile 加载失败	0.140 废弃 `[profiles.xxx]`	拆成 `~/.codex/xxx.config.toml`
6	metadata 警告	Codex 无 DeepSeek 官方元数据	可忽略，不影响对话
7	在 `~` 目录问「Explain codebase」	不在项目根	`cd` 到具体仓库再问

11. 安全建议

API Key 只放环境变量，不要提交到 Git（application.yml 明文 Key 建议改为 ${DEEPSEEK_API_KEY}）。
Key 若曾在聊天、截图、配置中暴露，可在 DeepSeek 控制台轮换。
代理只监听 127.0.0.1，不暴露到公网。

12. 日常启动速查

# 1. 环境
source ~/.zshrc

# 2. 代理（终端 1，保持运行）
start-deepseek-proxy.sh

# 3. Codex（终端 2）
cd /path/to/your/project
codex -p deepseek-v4-pro

健康检查：

curl -s http://127.0.0.1:8787/health

13. 选型建议

IDE 里边写边改、看 diff     → Cursor + deepseek-v4-pro
终端 Agent、批量改仓库       → Codex + 本地代理 + deepseek-v4-pro
要便宜、快                   → deepseek-v4-flash（Cursor 或 Codex 均可）
多文件 Agent + 看图          → Cursor Composer（关 DeepSeek Key）
Claude Code 形态 + DeepSeek  → ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic

14. 参考链接

附录：完整文件路径一览

路径	作用
`~/.zshrc`	`DEEPSEEK_API_KEY`、`PATH`
`~/.codex/config.toml`	Provider、代理地址、项目信任
`~/.codex/deepseek-v4-pro.config.toml`	Pro profile
`~/.codex/deepseek-v4-flash.config.toml`	Flash profile
`~/.local/bin/start-deepseek-proxy.sh`	启动代理
`~/.local/share/deepseek-responses-proxy/`	代理源码与 venv

文档基于 2026-06-17 在 Intel Mac 上的实测整理，Codex 版本 0.140.0。