学习笔记

Codex CLI 安装与国内模型配置指南

blueideaPost a Comment

本文转载自 CSDN 博客，原文作者：G_whang，原文链接：https://blog.csdn.net/G_whang/article/details/161949179

Codex CLI 安装与国内模型配置指南

1. 概述

1.1 什么是 Codex CLI

Codex CLI 是 OpenAI 于 2025 年开源的终端 AI 编程代理（Rust 编写，83,000+ Stars，Apache-2.0），支持在终端中读取文件、执行命令、自主修改代码库。

1.2 架构原理

Codex 核心是一个 Agent Loop（代理循环）：

  1. 组装 Prompt（系统指令 + 工具列表 + 用户输入 + AGENTS.md + 环境信息）
  2. POST JSON → OpenAI Responses API
  3. 流式接收事件（推理输出 / 工具调用请求）
  4. 执行工具（Bash / 文件操作 / MCP 工具），结果追加回上下文
  5. 循环，直到 LLM 发出 done 事件

1.3 与 Claude Code 对比

维度Codex CLIClaude Code
开源性开源（Apache-2.0）未开源
实现语言Rust（96.1%）TypeScript
API 协议OpenAI Responses APIAnthropic Messages API
沙箱机制Seatbelt/Landlock/restricted-token无内置沙箱
子 Agent.toml 文件定义，max_threads 并行/agent 命令基于 worktree
生态规模280+ 资源丰富的 MCP + Skill
Windows 支持需 WSL 2原生支持

2. 安装

2.1 前置条件

依赖说明
Node.js ≥ 18推荐 22 LTS
Git项目必须在 Git 仓库中才能运行
操作系统macOS / Linux 原生；Windows 需 WSL 2

2.2 方式一：npm 全局安装

# 配置国内镜像
npm config set registry https://registry.npmmirror.com

# 安装
npm install -g @openai/codex

# 验证
codex --version

2.3 方式三：桌面版

从 codex.chat 下载桌面安装包（Windows/macOS）。

3. 配置体系

3.1 文件层级与优先级

层级路径说明
系统级/etc/codex/config.toml管理员推送（可选）
用户全局~/.codex/config.toml个人默认，对所有项目生效
Profile 文件~/.codex/<name>.config.toml通过 –profile <name> 激活
项目级.codex/config.toml仅对受信项目加载

优先级（从高到低）：CLI 参数 → 项目配置 → Profile → 用户配置 → 系统配置 → 内置默认值。

⚠️ 安全限制：以下键在项目级 .codex/config.toml 中会被忽略——openai_base_url、model_provider、model_providers、chatgpt_base_url 等。这些必须设置在 ~/.codex/config.toml 中。

3.2 config.toml 核心配置

# ~/.codex/config.toml —— 个人全局配置

# ── 模型 ──────────────────────────────
model                         = "gpt-5.5"
model_provider                = "openai"
model_reasoning_effort        = "medium"
model_verbosity               = "medium"

# ── 安全边界 ──────────────────────────
sandbox_mode                  = "workspace-write"
approval_policy               = "on-request"

# ── 沙箱微调 ──────────────────────────
[sandbox_workspace_write]
network_access                = false
writable_roots                = ["~/extra"]

# ── Shell 环境 ────────────────────────
[shell_environment_policy]
inherit                       = "all"
exclude                       = ["AWS_*", "AZURE_*"]

# ── 特性开关 ──────────────────────────
[features]
hooks                         = true
multi_agent                   = true
undo                          = false
memories                      = false

# ── 项目上下文 ────────────────────────
web_search                    = "cached"
project_doc_max_bytes         = 32768

4. 方案一：七牛云直连（最简方案）

三行配置即可接入国内模型，适合快速上手体验。

# ~/.codex/config.toml
[model_providers]
"openai" = { base_url = "https://api.qnaigc.com/v1" }

model = "qwen3-235b"

可自定义根目录标记：project_root_markers = [".git", ".hg"]

5. 方案二：CC-Switch（推荐方案）

CC-Switch 是目前最成熟的国内接入方案，提供图形化界面管理。

原理：在 127.0.0.1:15721/v1 启动本地路由，完成协议识别 → 请求改写 → 转发 → 响应回译

预置 50+ 供应商模板，同时支持 Claude Code / Codex / Gemini CLI。

安装：brew install --cask cc-switch（macOS）或下载桌面安装包。

配置步骤：

  1. 安装 CC-Switch → 启动
  2. 切换到 Codex 标签页 → 点击 + 添加供应商
  3. 选择预设（DeepSeek / 通义千问 / SiliconFlow / Kimi / GLM）
  4. 填入 API Key → 勾选「需要本地路由映射」→ 保存
  5. 设置 → 路由 → 打开本地路由开关 → 打开 Codex 开关
  6. Codex 自动连接 http://127.0.0.1:15721/v1

6. 本地代理方案对比

方案图形界面多工具管理部署方式适用场景
CC-Switch✅✅（Claude Code + Codex + Gemini）桌面应用长期主力
mimo2codex✅ Web 面板❌（仅 Codex）npm / Docker / 桌面包多 provider 并存
codex-proxy✅ Web 面板❌（仅 Codex）npm 全局快速轻量

7. 方案三：降级到旧版 Codex

如果不需要新版特性，可安装仍使用 Chat Completions 的旧版（≤ 0.80.0）：

npm install -g @openai/codex@0.80.0

旧版直接兼容国内模型：

# ~/.codex/config.toml（仅 ≤ 0.80.0 有效）
openai_base_url = "https://api.deepseek.com/v1"
model = "deepseek-chat"
sandbox_mode = "workspace-write"

⚠️ 代价：失去新版 Responses API 特性（推理摘要、并行工具调用优化、流式改进）、Bug 修复和安全更新。

8. 国内厂商配置速查

8.1 各厂商端点

平台Base URL获取 API Key
DeepSeekhttps://api.deepseek.com/v1platform.deepseek.com
SiliconFlowhttps://api.siliconflow.cn/v1siliconflow.cn
阿里百炼https://dashscope.aliyuncs.com/compatible-mode/v1百炼控制台
智谱 GLMhttps://open.bigmodel.cn/api/paas/v4open.bigmodel.cn
Kimihttps://api.moonshot.cn/v1platform.moonshot.cn
MiniMaxhttps://api.minimax.io/v1platform.minimax.io
七牛云https://api.qnaigc.com/v1portal.qiniu.com
腾讯云https://tokenhub.tencentmaas.com/plan/v3腾讯云 AI 控制台
魔搭免费https://api-inference.modelscope.cn/v1每日 2000 次免费调用

8.2 推荐模型

场景推荐模型
日常编码DeepSeek V4 Pro / DeepSeek V3.2
复杂推理DeepSeek R2 / Qwen3.6-Max
中文优化Qwen 系列 / GLM 系列
长上下文Kimi K2.6（百万 Token）
省钱首选DeepSeek Chat + 魔搭免费额度
离线/隐私Ollama 本地部署

8.3 各方案配置速查

CC-Switch + DeepSeek：在 CC-Switch 中添加 DeepSeek 预设 → 填入 Key → 勾选本地路由 → 启动

9. 常见问题

问题原因解决方案
Codex 报 404协议不匹配使用 CC-Switch / mimo2codex 协议转换；或降级到 0.80.0
openai_base_url 不生效项目级 .codex/config.toml 会忽略此键移到 ~/.codex/config.toml
DeepSeek 上游 404Base URL 带了 /chat/completions只保留根地址
白屏/无法启动图形驱动或权限问题检查 macOS 辅助功能权限；用 codex –terminal 纯终端模式
沙箱内 pip/npm 超时network_access = false设置 sandbox_workspace_write.network_access = true
Windows 运行失败官方暂不支持原生 Windows使用 WSL 2
非 Git 目录不能运行Codex 要求 Git 仓库git init 初始化仓库
工具调用退化转换层未完整映射更换代理方案或接受能力折损

10. 最佳实践

  • 首选 CC-Switch + DeepSeek：图形化管理 + 稳定协议转换 + 多工具统一，是目前最成熟的国内接入方案。
  • 七牛云直连用于快速上手：三行配置即可跑通，适合初次体验。
  • API Key 只放环境变量：不在 config.toml 中硬编码，通过 env_key 引用。
  • Profile 分场景使用：轻量任务用 quick profile（省 Token），复杂推理用 deep profile。
  • 沙箱就不要全关：workspace-write 是平衡安全与效率的最佳默认值。
  • 接受功能折损：接入国产模型后，Image Gen 和 Computer Use 能力不可用，基础编码/调试/文件操作正常。

blueidea

Leave A Comment

Recommended Posts