如果你最近对 AI Agent 开发感兴趣很可能已经被 Codex CLI 刷屏了。它是 OpenAI 开源的终端智能体能让模型像一位开发搭档一样直接读写项目文件、执行命令、查看运行结果并且在一个多步骤任务里持续迭代。不少国内开发者看到这类工具时第一反应是“网络环境会不会很麻烦”第二反应是“API 费用会不会很贵”。实际上Codex CLI 的架构决定了它可以把“客户端”和“模型服务”完全拆开你只需要在配置里把模型提供商指向一个国内可以直接访问的 OpenAI 兼容接口就完全不需要任何额外的网络工具也不需要 OpenAI 账号。本文会把 Codex CLI 在国内普通网络环境下对接 DeepSeek、本地 Ollama 以及中转模型的完整流程拆开讲清楚包含安装步骤、配置示例、交互式和非交互式用法以及常见报错排查思路。无论你是第一次接触 Agent 编程的新手还是已经用过 GitHub Copilot、Claude Code 等工具的开发者都能照着这份教程把环境跑起来。1. Codex CLI 是什么为什么值得在本地用1.1 从 AI 补全到 AI Agent过去几年大家最熟悉的 AI 编程工具是“代码补全”类产品例如 GitHub Copilot、通义灵码、CodeWhisperer。这类工具的工作方式是你写代码模型在光标后面预测下一段字符本质上是“你打字它补一句”。但 Codex CLI 不是补全工具它是一个真正意义上的 Agent智能体。你可以把它理解为你在终端里提出一个目标例如“帮我给这个 Python 项目补上单元测试”然后 Codex CLI 会自己规划步骤、读取目录结构、创建或修改文件、运行测试命令、根据报错继续调整直到任务完成。Codex CLI 这个名字里的“Codex”是 OpenAI 的 AI 编程智能体系列产品名称而“CLI”是 Command-Line Interface 的缩写也就是命令行界面。所以 Codex CLI 就是 Codex 的命令行形态专门面向开发者使用。相比网页版命令行版本的优势是它可以直接和本地文件系统交互也能调用终端里的各种工具天然适合开发场景。1.2 为什么 Codex CLI 在国内也能用很多同学看到 OpenAI 出品第一反应是“是不是必须要登录 ChatGPT是不是要额外网络环境”。如果把 Codex CLI 当作一个独立的桌面应用确实会有很多限制但实际拆开看Codex CLI 的架构非常干净它只负责三件事对话管理、工具调用、命令执行。真正做推理的大模型并不在客户端内部而是通过 API 请求发送到远程服务或本地服务。Codex CLI 支持自定义模型提供商Model Provider也就是允许你把请求转发到任意一个“OpenAI 兼容”的接口上。这意味着你可以把模型源配置为 DeepSeek 的云端 API也可以配置为本地 Ollama 启动的模型服务还可以配置为已购买并使用中的中转模型服务。这三种模型源都有国内可以直接访问的入口所以整个链路不需要任何额外的网络工具也不需要依赖 ChatGPT 账号登录。本文后面会围绕这三种方案分别给出配置方法。1.3 Codex CLI 的典型应用场景从实际使用来看Codex CLI 比较适合四类场景。第一类是新项目脚手架搭建你可以用自然语言描述项目结构让 Agent 直接生成目录、配置文件、依赖文件和初始代码。第二类是批量代码修改例如统一修改日志格式、给所有接口补充参数校验、把一个模块的命名风格从 snake_case 改成 camelCase这类重复性工作正好是 Agent 的强项。第三类是写测试和修测试Agent 可以读源码、生成测试用例、跑测试、修复失败用例。第四类是学习 AI Agent 开发因为 Codex CLI 本身是开源项目你可以看到它的运行机制也可以作为后续开发自己的 Agent 工具的参考。2. 环境准备与版本说明2.1 本机环境要求在开始安装之前你需要准备一个可用的开发环境。本文示例以 macOS 和 Linux 为主Windows 用户建议使用 PowerShell 7 或 WSL 2因为 Codex CLI 的交互界面在 Windows 原生终端下可能存在兼容性问题。需要提前安装 Node.js 和 Git。Node.js 主要用于通过 npm 安装 Codex CLI建议使用 Node.js 18 或更高版本具体版本要求以你安装时的官方 README 为准Git 用于代码仓库操作Codex CLI 的很多 Agent 功能例如查看 diff、提交代码、关联 GitHub 等都会依赖 Git 环境。如果你是纯前端或纯 Python 开发者没有现成的 Node.js 环境可以直接到 Node.js 官网下载 LTS 版本安装。安装完成后在终端执行node -v和npm -v能看到版本号就说明环境正常。这里要提醒一下很多开发者在配置环境时容易忽略 PATH 问题如果你安装完 Node.js 后终端找不到node命令需要检查安装器是否把 Node.js 的 bin 目录加入了系统 PATH。2.2 模型服务的三种选择你需要准备下面三种模型服务中的至少一种。第一种是 DeepSeek 开放平台的 API Key注册后在控制台创建通常是以sk-开头的字符串具体字段以平台展示为准。DeepSeek 的接口在国内可以直接访问价格也比较低适合想快速体验完整 Agent 能力的同学。第二种是本地 Ollama 部署的模型这是真正的零成本方案不过需要一定内存和磁盘空间8B 级别的模型通常需要 8GB 以上内存才能跑得比较流畅。第三种是已经购买并正常使用的 OpenAI 兼容中转模型服务这类服务通常会提供base_url和 API Key你只需要在 Codex CLI 里填好即可。2.3 版本与配置差异须知Codex CLI 的迭代速度非常快不同版本在配置字段、子命令、交互界面上都可能存在差异。本文中的配置示例采用社区中最常见的写法整体思路是稳定的但如果你安装的版本比较新出现了某些字段失效或命令不存在的情况请优先以官方 GitHub 仓库的 README、codex --help输出以及你本机生成的默认配置为准。换句话说看教程时要理解原理而不是死记命令。只要你理解了“Codex CLI 通过 base_url 访问 OpenAI 兼容接口”这件事后面遇到版本变化也能很快调整。3. 核心原理拆解Codex CLI 如何连接不同模型3.1 Agent 的基本运行循环要理解 Codex CLI首先要理解 Agent 的基本运行循环。当你启动 Codex CLI 并输入一个任务后系统会把“系统提示词 用户任务 当前目录信息 历史对话”一起发送给模型。模型接收到输入后可能会返回两种内容一种是最终答案另一种是“工具调用”请求也就是告诉客户端“我需要读取某个文件”或“我需要执行某条命令”。客户端拿到工具调用请求后会在本机执行对应操作并把结果追加到对话上下文中再次发送给模型。如此循环直到模型认为任务已经完成。这个循环中最关键的一点是“模型必须支持工具调用Function Calling”。如果你接入的模型本身不支持工具调用Codex CLI 就会退化成普通聊天助手无法帮你操作文件系统。因此在选模型时要优先考虑支持工具调用的模型。DeepSeek 的deepseek-chat和部分本地模型都具备这一能力但不同模型的工具调用效果会直接影响 Agent 的稳定性。3.2 OpenAI 兼容接口的含义Codex CLI 本身并不是直接连接 OpenAI 官方服务而是通过配置中的base_url把请求发送到任意服务地址。这里的“OpenAI 兼容”指的是接口路径和请求体遵循 OpenAI 的规范最常见的路径是/v1/chat/completions也有一些新版本会使用/v1/responses。对于模型服务提供商来说只要它实现了这套协议Codex CLI 就可以直接对接。所以你会看到无论对接 DeepSeek、Ollama 还是中转模型配置思路都一模一样修改base_url、修改默认模型名、设置对应的 API Key 环境变量。这就是“客户端与模型解耦”带来的灵活度。很多教程里提到的“Codex 接入 DeepSeek”本质上不是修改 Codex CLI 的源码而是调整一行配置指向 DeepSeek 的接口地址。3.3 三种模型来源的对比方案成本数据隐私配置难度适合场景DeepSeek API按 Token 计费价格低代码会上传到 DeepSeek 服务端低日常开发、需要较强模型能力的场景本地 Ollama 模型零成本数据不出本机中学习实验、隐私敏感工程、离线环境中转模型服务不定取决于服务商低已有稳定中转服务希望统一模型入口从使用体验来说DeepSeek 的云端 API 对 Agent 指令遵循能力通常好于本地小模型适合跑复杂任务本地 Ollama 适合晚上想折腾又不想花钱的场景中转模型则适合团队里已经统一采购了 API 服务、希望把 Codex CLI 也接入同一个入口的情况。选择哪一种主要取决于你的预算、隐私要求和对模型能力的要求。4. 保姆级实战Codex CLI 对接 DeepSeek / Ollama / 中转模型4.1 安装 Codex CLI首先通过 npm 全局安装 Codex CLI。在终端执行npm install -g openai/codex安装完成后确认版本号codex --version如果终端提示找不到codex通常是 npm 全局安装目录没有被加入 PATH。你可以通过npm prefix -g查看全局安装路径然后把对应的bin目录加入 PATH。国内网络环境下如果 npm 下载依赖较慢可以把 npm 源切换为国内镜像例如npm config set registry https://registry.npmmirror.com切换镜像后重新执行安装命令即可。安装并确认版本号正常后还需要创建一个 Codex CLI 的配置目录后续所有模型配置都放在这个目录下。macOS 和 Linux 的默认路径是~/.codexWindows 的默认路径通常是C:\Users\你的用户名\.codex。4.2 方案一Codex CLI 接入 DeepSeek第一步去 DeepSeek 开放平台注册账号创建一个 API Key。注意保存好这个 Key因为平台通常不会完整显示第二次。创建完成后先设置环境变量让 Codex CLI 能读取到你的 Keyexport DEEPSEEK_API_KEY你的API Key为了让环境变量永久生效可以把这行内容写入~/.bashrc或~/.zshrc然后执行source ~/.bashrc或source ~/.zshrc让配置生效。接下来创建 Codex CLI 的配置文件。打开~/.codex/config.toml写入以下内容model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY这里解释一下每个字段的含义。model是默认使用的模型名DeepSeek 开放平台主要提供deepseek-chat和deepseek-reasoner两种模型model_provider指向下面的 provider 配置[model_providers.deepseek]是定义一个名为 deepseek 的模型提供商name是显示名称base_url是接口地址Codex CLI 会在这个地址后拼接实际的请求路径env_key告诉 Codex CLI 从哪个环境变量读取 API Key。保存配置后在任意项目目录下启动codex首次进入交互界面后输入一个简单任务测试例如请查看当前目录结构然后创建一个 requirements.txt 文件里面写入 flask。Codex CLI 会调用 DeepSeek 模型规划步骤创建文件并输出结果。如果一切正常说明 Codex CLI 已经成功接入 DeepSeek。4.3 方案二Codex CLI 接入本地 Ollama 模型本地部署 Ollama 是一个非常典型的零成本方案。首先去 Ollama 官网下载对应操作系统的安装包并完成安装。国内下载安装包时偶尔会慢可以选择网络空闲时段也可以使用你信任的镜像站下载Linux 环境下也可以使用官方安装脚本。安装完成后在终端确认 Ollama 版本ollama --version然后拉取一个支持工具调用的模型。社区常用的选择包括qwen3:8b和deepseek-r1:7b以 Ollama 仓库可用的标签为准。拉取命令如下ollama pull qwen3:8b拉取完成后通过以下命令确认模型列表和服务状态ollama list curl http://localhost:11434/v1/models如果第二条 curl 返回了模型列表 JSON说明 Ollama 的 OpenAI 兼容接口已经正常启动。接下来配置 Codex CLI修改~/.codex/config.tomlmodel qwen3:8b model_provider ollama [model_providers.ollama] name Ollama Local base_url http://localhost:11434/v1本地模型服务不需要 API Key所以这里不需要设置env_key。配置完成后启动 Codex CLI 进行测试codex在交互界面输入一个任务例如在当前目录下创建一个 Python 脚本计算斐波那契数列前 20 项并打印。需要注意的是本地 8B 级别模型的 Agent 能力会弱于云端大模型在复杂任务上可能会出现“理解了但执行不对”的情况这是模型能力限制不是 Codex CLI 的问题。如果条件允许可以选择更大参数量或更强的本地模型。4.4 方案三Codex CLI 接入中转模型如果你已经有稳定使用且经过授权的中转模型服务配置方式与 DeepSeek 几乎一样。假设服务商提供的信息是接口地址为https://your-proxy.example.com/v1模型名为gpt-4o-miniAPI Key 通过PROXY_API_KEY环境变量读取。那么配置如下model gpt-4o-mini model_provider proxy [model_providers.proxy] name My Proxy base_url https://your-proxy.example.com/v1 env_key PROXY_API_KEY设置环境变量export PROXY_API_KEY你的Key然后启动codex。这里有一个必须强调的安全原则中转服务市场鱼龙混杂一定要选择正规、合法、有明确授权的服务商不要为了低价选择不透明的小平台不要把核心业务代码发送到不可信的服务端也不要购买来路不明、可能涉及违规的服务。代码和密钥的安全永远比省几块钱重要。4.5 使用codex exec实现非交互式调用除了交互式界面外Codex CLI 在较新版本中还提供了非交互式执行方式适合在脚本和 CI/CD 流水线中使用。具体命令格式以你本机codex --help输出为准常见形式是codex exec 修复 src/utils.js 中的空指针问题并补充单元测试非交互模式下Codex CLI 会在当前目录执行 Agent 循环并把 Agent 的最终回复输出到终端。这种模式的好处是方便集成到自动化流程中例如收到 issue 后自动触发修复、提交 PR 等。不过自动化场景对模型能力要求更高建议先用 DeepSeek 这类云端模型测试确认任务可以稳定完成后再接入流水线。5. 常见问题与排查思路5.1 高频问题对照表在配置和使用 Codex CLI 的过程中很多问题其实是相似的。下面整理一份高频问题对照表你可以根据现象快速定位问题现象常见原因解决思路安装后提示找不到codex命令npm 全局 bin 不在 PATH 中执行npm prefix -g查看路径并加入 PATH启动后提示 API Key 缺失环境变量未设置或env_key写错检查env_key字段并确认环境变量名一致请求返回 401 UnauthorizedAPI Key 无效、过期或余额不足到模型平台后台确认 Key 状态和余额请求返回 404 Not Foundbase_url路径错误或模型名不存在用 curl 手动调用接口确认地址和模型名Codex CLI 卡在某个任务上不执行模型输出异常或上下文过长重新发起任务精简描述或换更强模型Agent 提示没有权限执行命令未授权当前目录或命令检查 Codex CLI 的权限设置或重新进入项目目录本地 Ollama 模型连接失败Ollama 服务未启动或端口不是 11434执行ollama serve启动服务并检查ollama list模型返回结果明显不符合指令模型不支持工具调用或模型能力不足更换支持 Function Calling 的模型5.2 切换模型提供商时遇到 local proxy failed有同学在切换 model provider 时遇到过类似local proxy failed while handling codex endpoint /responses的报错。这里的 “local proxy” 是指 Codex CLI 内部的一个本地代理层它负责把客户端的请求转发到配置的模型服务地址。报错信息里出现了/responses端点说明你的版本正在使用新的 responses API 协议。遇到这种报错时可以按以下顺序排查。第一步检查base_url是否配置正确特别是是否缺少/v1前缀以及服务地址是否可以被当前网络直接访问。第二步用 curl 手动测试目标接口例如curl http://localhost:11434/v1/models确认服务本身可用。第三步检查终端环境变量中是否有代理相关设置例如HTTP_PROXY、HTTPS_PROXY、ALL_PROXY。如果你的开发环境中存在代理变量且当前场景不需要使用可以临时将它们取消后再启动 Codex CLIunset HTTP_PROXY unset HTTPS_PROXY unset ALL_PROXY这里的代理变量指的是公司内网或本地调试代理等常规网络设置排查时请遵守你所在公司的网络管理规范。如果取消代理变量后问题解决就可以确定是本地代理配置干扰了 Codex CLI 的请求转发。第四步将 Codex CLI 升级到最新版本再重新测试。5.3 Agent 执行中途终止怎么办在 Agent 执行较长任务时你可能会看到类似Agent terminated due to error的提示意思是某个步骤发生了错误Agent 被终止。这种情况一般不必慌Codex CLI 通常会提示你继续对话、让模型重试或者重新开始。常见原因有三个一是执行了会导致进程结束的命令例如误操作了退出快捷键二是模型输出触发了上下文长度上限三是模型在工具调用过程中返回了格式错误的数据。如果遇到终止建议先查看屏幕上的错误信息然后把任务拆小重新提交。比如一个“修复所有测试”的任务改成“先运行测试把第一个失败用例的报错贴给模型”往往能更稳定。另外在交互界面里保留历史上下文是有价值的Codex CLI 会记住之前的对话和操作记录所以不要急着退出重来。6. 最佳实践与工程建议6.1 API Key 安全与配置管理无论你使用 DeepSeek 还是中转模型API Key 都是敏感信息。不要把 Key 直接写入config.toml也不要提交到 Git 仓库。推荐的做法是利用 Codex CLI 的env_key机制把 Key 放进环境变量然后在项目的.gitignore中忽略.env文件。如果你使用 direnv 或 dotenv 之类工具可以做到不同项目使用不同 Key。对团队协作来说可以考虑把 Codex CLI 配置模板纳入仓库但真正的 Key 只保存在个人环境或密钥管理系统中。6.2 控制 Agent 的权限与执行范围Codex CLI 是一个能自动执行命令的工具因此权限控制非常重要。在陌生项目或重要项目中不要让 Agent 在无人监督的情况下执行危险操作例如删除文件、强制推送 Git 提交、修改数据库结构等。建议先让 Agent 以“只读模式”分析代码把修改方案列出来再由你确认后执行。Codex CLI 通常有审批策略你可以根据任务风险程度选择每次执行命令前手动确认或者只允许读取操作。简单来说能不给权限就不给权限能少执行危险命令就少执行。6.3 成本控制与任务拆分如果你使用按 Token 计费的云端模型成本主要取决于上下文长度和 Agent 循环次数。一个常见的误区是让 Agent 一次性完成超大任务结果上下文不断膨胀Token 消耗飙升。更经济的做法是把大任务拆成多个小任务每个任务聚焦一个目标。例如“重构整个项目”可以拆成“先迁移工具函数”“再替换调用方”“最后清理旧代码”三个步骤。这样既能降低单次任务的上下文压力也能减少出错后的重试成本。6.4 代码审查与生产环境纪律AI Agent 生成的代码并不天然正确甚至可能引入隐蔽的逻辑错误。在本地实验时可以直接运行但涉及生产环境、数据库、权限、支付等敏感领域时必须坚持人工审查。建议把 Agent 生成的代码当作“初级工程师提交的 PR”来对待你仍然需要做严格的 Code Review。涉及数据库变更或线上配置修改时要在测试环境完整验证保留备份遵循最小权限原则。这个纪律不只适用于 Codex CLI所有 AI 编程工具都一样。7. 总结与学习路线本文从 Codex CLI 的基本概念讲起解释了为什么这个 OpenAI 出品的终端 Agent 能在国内普通网络环境下使用。核心思路就是通过自定义模型提供商把模型请求转发到 DeepSeek、本地 Ollama 或中转模型服务上。随后我给出了三种模型来源的配置示例并演示了交互模式和非交互模式下的使用方法也整理了local proxy failed、API Key 缺失、Ollama 连接失败等高频问题的排查方法。你现在应该已经具备了把 Codex CLI 跑起来的基础能力。下一步你可以尝试把 Codex CLI 接入 GitHub Actions实现 issue 自动修复也可以研究它的沙箱和审批机制思考如何在自己的 Agent 项目里实现相同的能力还可以对比 DeepSeek、本地 OLLaMA 和不同中转模型在同一个任务上的表现找到最适合你工作流的模型和参数。AI Agent 方向的发展非常快工具本身的细节可能随时变化但“模型服务与客户端解耦”的思想不会过时。如果你按照本文配置时遇到了新的报错欢迎把报错信息留在评论区我会持续更新这份实操笔记。