这次我们直接在服务器上装一个 AI 编程工具OpenAI Codex CLI然后把它接到大模型上跑代码任务。文章里会覆盖两种接法一种接第三方兼容 OpenAI API 的服务成本相对可控另一种接本地部署的开源模型模型权重完全可控。整条链路走通之后你可以在服务器上做代码生成、代码修改、批量脚本执行也能接到自己的工具或 CI/CD 流程里。Codex CLI 本身只是一个命令行客户端真正完成任务的是背后的大模型。所以本文的主体分两段先把 CLI 装好再把它指向你选定的模型。从部署难度看CLI 安装很简单难点基本都在模型接入这一步尤其是本地模型需要自己解决并发、延迟和上下文长度的问题。文章以 Linux 服务器为例给出安装命令、配置文件模板、验证命令和常见问题排查。没有具体测试环境数据的地方我会标注为“以实际环境为准”不硬编数字。内容适合刚有一台云服务器、想低成本尝试 AI 编程助手的开发者。1. 核心能力速览能力项说明项目类型AI 编程助手命令行工具OpenAI Codex CLI主要功能代码生成、代码修改、仓库级任务执行、批量脚本任务运行平台Linux / macOS / WindowsWSL运行方式命令行交互模式 / 非交互式 exec 模式模型接入官方模型 API、第三方兼容 API、本地开源模型是否需要 GPU仅接本地大模型时需要仅做远程 API 调用不需要显存占用由所选模型决定无法统一估算是否支持 API 服务CLI 本身不是 HTTP 服务可自行包装成服务是否支持批量任务支持通过 exec 模式 脚本循环实现适合场景服务器上自动写代码、改代码、持续集成中跑 AI 任务这个表把关键信息放在前面最多 30 秒就能判断这件事值不值得做、你的服务器能不能跑。如果你的目标是“远程写代码 接低成本模型”这个方案是可行的如果你手头只有一台 2 核 4G 的轻量服务器接官方 API 这类远程模型没问题但想在本地跑开源大模型就比较吃力需要换台更高配置的机器或者直接用第三方 API。2. 适用场景与使用边界2.1 适合谁有 Linux 服务器或云主机的开发者想在上面跑 AI 代码助手。团队想把 AI 编程能力接入代码仓库、CI/CD 流程的工程师。想用较低成本试用大模型不想被单一厂商绑定的用户。2.2 能解决什么问题Codex CLI 可以帮助你完成以下日常工作根据自然语言描述生成代码文件或补丁。在已有代码仓库中定位问题、生成修改方案。批量执行重复性代码任务例如为多个目录生成单元测试。通过脚本把 AI 能力接入自动化流水线。2.3 不适合什么场景需要高准确率、高并发生产的场景目前还是以人审为主。在低配机器上跑大参数本地模型体验会很差不建议硬上。涉及机密代码或敏感数据时要确认所选模型服务的数据合规条款不要盲目接入。2.4 合规与安全边界使用任何大模型服务前先确认服务商的数据使用条款和隐私政策。涉及人脸、声音、版权素材或企业内部代码时必须获得授权。本地部署开源模型时也要遵守模型的开源许可证。不要在日志或配置文件中明文保存 API Key不要将端口直接暴露到公网。3. 环境准备与前置条件这里以 Debian/Ubuntu 类服务器为例其他发行版命令略有差异。3.1 操作系统推荐使用 Ubuntu 20.04 / 22.04 / 24.04 LTS 或 Debian 11 / 12。需要确认系统是 64 位架构。可以用命令查看uname -m输出是x86_64或aarch64都可以继续不同架构不影响后续核心步骤。3.2 Node.js 环境Codex CLI 基于 Node.js 开发安装前需要确认 Node.js 版本。不同版本对 Node 版本要求可能不同建议使用官方维护的 Node.js LTS 版本。如果服务器上没有 Node.js可以先用 nvm 安装curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完之后重新登录 Shell然后安装 Node.js LTSnvm install --lts node -v npm -v这里以 nvm 为例因为它方便切换版本也避免掉/usr/bin下的权限问题。如果你习惯用 apt 安装 Node.js也可以只要最终node -v能正常输出版本号即可。3.3 网络与 API 服务可达性Codex CLI 启动后需要访问模型服务。这个服务可以是官方 API也可以是第三方服务还可以是本地启动的推理服务。无论哪种都要求 CLI 所在服务器能访问到对应服务的接口地址。如果接本地模型CLI 和推理服务在同一台服务器或同一内网网络问题不大。如果接远程 API确认服务器出口网络能正常访问对应域名端口 80/443 没有被安全组限制。3.4 API Key 与账号接入远程模型服务需要提前准备服务商账号。API Key。确认服务商提供的接口地址和模型名称。确认该模型在服务商平台已开通可用。不要先在环境变量里写死 Key最好在配置完成后通过独立环境变量注入避免误提交到代码仓库。3.5 磁盘空间Codex CLI 本身占用很小几百 MB 以内。如果还要本地部署开源模型则需要更充足的磁盘空间。一个 7B 左右的量化模型大约需要 5GB 到 8GB 空间更大参数的模型可能需要几十 GB。具体以模型文件实际大小为准提前预留空间。4. 安装部署与启动方式4.1 全局安装 Codex CLI在已经配置好 Node.js 的服务器上使用 npm 全局安装npm install -g openai/codex安装完成后验证版本codex --version如果能输出版本号说明安装成功。如果提示codex: command not found说明 npm 的全局 bin 目录没有加入 PATH需要手动找一下二进制路径npm bin -g把输出目录加入环境的 PATH 中或者建立软链接。具体路径在不同系统上不同这里不写死。4.2 直接执行命令测试安装完成后可以先跑一个简单命令确认 CLI 能正常启动codex exec print hello world in python这个命令会发起一次模型调用。如果配置还没完成通常会提示缺少 API Key。这一步的作用是确认 CLI 本身能启动错误信息能正常打印。4.3 交互式界面启动如果想在终端里进入交互式聊天界面执行codex app进入之后用自然语言描述你的需求例如“帮我写一个读取 CSV 并按列去重的 Python 脚本”。它会直接生成代码必要时还会操作工作目录下的文件。交互式模式适合做代码修改因为在对话里它可以读取文件、生成补丁、再执行命令。4.4 服务模式与端口说明Codex CLI 本身不是一个常驻 HTTP 服务它没有固定的监听端口。如果你希望给团队成员提供一个网页或 API 入口需要自己做一层包装例如用 FastAPI、Express 写一个中转服务在后台调用codex exec子进程。这样做的好处是不用暴露终端坏处是需要自己处理并发、超时和进程管理。5. 接入模型配置这是文章的核心部分。Codex CLI 默认使用 OpenAI 官方模型但它的配置体系支持通过model_providers指定其他兼容 OpenAI API 格式的服务。下面分别给出第三方云 API、本地开源模型、官方模型三种接法。5.1 官方模型配置如果使用官方模型只需配置 API Keyexport OPENAI_API_KEY你的 API Key然后执行codex exec write a function to check if a number is prime最基础的流程就通了。5.2 接入第三方兼容 OpenAI API 的服务现在很多大模型平台都提供兼容 OpenAI Chat Completions 格式的接口。你可以在~/.codex/config.toml中添加一个模型提供商。先手动创建配置文件目录mkdir -p ~/.codex然后编辑配置文件。下面是一个通用模板实际字段名和取值需要以项目文档和服务商文档为准# ~/.codex/config.toml model 你的模型名 model_provider 自定义提供商别名 [model_providers.自定义提供商别名] name 显示名称 base_url https://你的服务商接口地址/v1 env_key YOUR_PROVIDER_API_KEY wire_api chat保存后退出编辑器。由于这个文件里通常是静态配置不含 Key可以把 Key 放到环境变量中export YOUR_PROVIDER_API_KEY你的 Key接着执行codex exec 写一个 Python 脚本读取 JSON 文件并输出字段统计如果返回正常说明第三方模型已经接入成功。如果报 404、401 或模型不存在优先检查base_url是否正确是否带有/v1路径。env_key的环境变量是否真的被导入。model名称是否和平台实际提供的模型名一致。wire_api是chat还是responses需要按服务商支持的协议选择。这里需要特别提醒不同 Codex CLI 版本对wire_api的支持不同。chat表示走 Chat Completions 格式responses表示走 Responses API 格式。如果你的模型服务商只实现了 Chat Completions就选chat。5.3 接入本地开源模型如果你有一台配置还不错的服务器并且想完全掌控模型权重可以在本机启动一个推理服务再让 Codex CLI 指向它。以 Ollama 为例它自带一个 OpenAI 兼容接口步骤大致如下。先安装 Ollama 并拉取一个代码类模型# 安装 Ollama具体方式以官方文档为准 curl -fsSL https://ollama.com/install.sh | sh # 启动服务 ollama serve另开一个终端拉取模型ollama pull qwen2.5-coder:7b然后确认 Ollama 的 OpenAI 兼容地址默认一般是http://127.0.0.1:11434/v1接着配置~/.codex/config.tomlmodel qwen2.5-coder:7b model_provider ollama [model_providers.ollama] name Ollama base_url http://127.0.0.1:11434/v1 env_key OLLAMA_API_KEY wire_api chatOllama 本地服务默认不校验 Key可以设置一个占位环境变量export OLLAMA_API_KEYollama然后测试codex exec 用 Python 写一个快速排序函数如果本地模型能正常返回整个本地链路就通了。5.4 多模型切换在config.toml里可以同时定义多个model_providers需要切换时直接修改model和model_provider字段。也可以为不同项目准备不同的配置文件用环境变量或启动参数指定。几点提醒本地模型的速度取决于 GPU、CPU、内存带宽和量化程度。远程 API 的速度取决于网络延迟和服务商并发限制。不要把多个 API Key 写在同一个配置文件中并提交到 Git。6. 功能测试与效果验证接入之后不要急着跑正式工作先按下面的顺序做一轮验证。6.1 基础生成测试执行最简单的代码生成任务codex exec 用 Python 写一个函数输入一个列表返回去重后的列表判断标准命令能正常返回代码片段。返回内容里没有协议错误、HTTP 错误。生成的代码语法正确。6.2 仓库级代码修改测试进入一个测试仓库执行cd /path/to/test-repo codex exec 在这份代码里增加输入参数校验并输出修改后的 diff判断标准输出中能看到实际的 diff 内容。修改位置与描述大致相符。代码没有明显的逻辑错误。这一步是 Codex CLI 的核心能力建议选一个你熟悉的仓库测试这样能更快判断输出是否可靠。6.3 多轮交互测试进入交互式模式codex app输入两到三轮连续指令例如“给这个函数增加类型注解”“再加一个命令行入口”“补充 docstring”观察它是否能记住前面的修改上下文。不同模型的上下文能力差异很大这一步能直接反映实际可用性。6.4 长上下文测试找一个代码量较大的仓库让它分析某个模块codex exec 总结 src/utils 目录下的代码结构和主要函数判断标准输出内容是否覆盖了多个文件。是否出现截断或无意义的重复。如果输出被切断说明上下文窗口或输出长度限制需要调整。6.5 失败场景测试故意给它一个模糊任务例如codex exec 改一下这个项目观察行为有的模型会追问有的模型会直接拒绝有的会猜测一个方向并执行。这一步能帮你在正式使用前确定模型的“边界感”。7. 批量任务与自动化接入Codex CLI 的exec模式本身就是为非交互式调用设计的适合批量任务和脚本集成。7.1 脚本批量执行下面是一个简单的 Bash 脚本示例读取任务列表文件逐条执行#!/bin/bash INPUT_FILEtasks.txt LOG_FILEcodex_tasks.log while IFS read -r task; do echo $(date) $LOG_FILE echo 任务: $task $LOG_FILE codex exec $task $LOG_FILE 21 echo 完成: $task $LOG_FILE done $INPUT_FILE使用前先创建一个测试用的tasks.txt每行一个任务。注意处理任务失败时脚本仍然继续执行可以在codex exec后面加上结果码判断codex exec $task $LOG_FILE 21 if [ $? -ne 0 ]; then echo 任务失败: $task $LOG_FILE fi7.2 用 Python 包装为 API 服务如果希望其他人或系统能通过 HTTP 调用可以用 FastAPI 写一个简单的接口后台调用codex exec。import subprocess import os from fastapi import FastAPI, HTTPException from pydantic import BaseModel app FastAPI() class TaskRequest(BaseModel): task: str cwd: str /tmp app.post(/run) def run_task(req: TaskRequest): if not os.path.isdir(req.cwd): raise HTTPException(status_code400, detail目录不存在) env os.environ.copy() result subprocess.run( [codex, exec, req.task], cwdreq.cwd, envenv, capture_outputTrue, textTrue, timeout300 ) if result.returncode ! 0: raise HTTPException(status_code500, detailresult.stderr[-2000:]) return { task: req.task, cwd: req.cwd, output: result.stdout[-4000:] }启动服务uvicorn main:app --host 127.0.0.1 --port 8000调用接口curl -X POST http://127.0.0.1:8000/run \ -H Content-Type: application/json \ -d {task: 写一个 Python 快速排序函数, cwd: /tmp}这个包装思路同样适用于 CI/CD 场景。在 GitLab CI 或 GitHub Actions 中直接安装依赖并调用codex exec即可。7.3 并发与队列建议不要直接无限制地并发调用codex exec。如果模型服务是远程 API平台通常有速率限制如果是本地模型并发会挤占显存和计算资源。建议用一个简单的任务队列控制并发数。单条任务设置超时时间。保存每次调用的输入输出日志。对失败任务做有限重试不要无限重试。8. 资源占用与性能观察8.1 CLI 本体占用Codex CLI 是 Node.js 进程长时间运行时内存占用不算高但并不代表没有成本。在低配服务器上频繁执行任务会导致 Node 进程反复启动、退出带来额外的开销。建议观察top或htop中node进程的内存使用。如果使用的是远程 APICLI 本机的 CPU 和 GPU 压力都很小。真正需要关注的是模型服务的并发能力、错误率、响应延迟。这部分可以在模型服务商的控制台查看也可以在自己这一侧记录每次调用的耗时。8.2 接入本地模型时的资源占用接入本地大模型时资源占用主要由推理框架和模型大小决定和 Codex CLI 本身关系不大。观察方法用nvidia-smi看显存占用。用free -h看内存占用。用top看 CPU 和负载。用ollama ps看当前加载的模型显存占用。如果你发现响应很慢先确认模型是否已经被加载到显存再检查是单次请求慢还是并发之后才开始慢。如果 CPU 占用持续接近 100%说明模型运行在没有 GPU 的条件下速度会明显受限。这些数字不能统一给结论取决于模型规模、量化程度和硬件配置。请以你自己服务器的实际测试为准。8.3 如何降低资源占用几点通用做法本地模型优先选择量化版本例如 Q4_K_M、Q5_K_M 等减少显存占用。推理框架设置合理的最大并发数。对于远程 API控制同时进行的 exec 任务数量。定期清理日志和输出文件避免磁盘写满。9. 常见问题与排查方法问题现象可能原因排查方式解决方案codex: command not foundnpm 全局 bin 目录不在 PATH 中npm bin -g查看路径把该目录加入 PATHunable to locate the codex cli binary编辑器插件找不到 codex 可执行文件检查插件设置中的 codex_cli_path在插件设置里指定绝对路径或修复 PATH提示缺少 API Key未设置对应环境变量echo $YOUR_API_KEY导出环境变量后再执行请求返回 401API Key 错误或过期查看服务商控制台重新生成 Key 并更新环境变量请求返回 404base_url 或模型名错误核对 url 与模型列表修改 config.toml 中对应字段cc switch local proxy failed while handling codex endpoint /responses端点映射或代理配置有问题检查 config.toml 中 wire_api 和 provider 配置确认协议格式是 chat 还是 responses并按服务商调整本地模型回答很慢模型未完全加载到显存或 CPU 推理查看 nvidia-smi / free -h换量化模型或减少并发codex exec输出截断模型输出长度限制查看服务商输出 token 上限缩短任务描述或调整服务端 max_tokens批量任务卡住网络超时或 API 速率限制查看日志和模型服务商控制台设置超时控制并发失败重试端口被占用HTTP 包装服务端口冲突ss -lntp查看端口占用换端口或停掉旧进程9.1 安装依赖失败怎么办如果 npm 安装网络不稳定可以配置国内的 npm 镜像或使用--registry参数临时指定。例如npm install -g openai/codex --registryhttps://registry.npmmirror.com注意镜像只负责下载 npm 包不改变 Codex CLI 本身的模型调用逻辑。9.2 模型文件缺失接入本地模型时如果提示模型不存在先确认已执行模型拉取命令。以 Ollama 为例ollama list查看本地已经拉取的模型列表。列表里没有目标模型就先用ollama pull拉取。9.3 API 调用失败如果远程 API 调用失败建议先用 curl 直接测试接口是否通curl https://你的服务商接口地址/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $YOUR_API_KEY \ -d {model: 你的模型名, messages: [{role: user, content: hi}]}如果 curl 正常而 Codex CLI 失败问题大概率出在 config.toml 的字段配置上例如wire_api、model名称或环境变量名。10. 最佳实践与使用建议10.1 先小后大第一次使用不要直接让它处理整个仓库。先在小目录、小文件上跑通流程再逐步扩大任务范围。这样容易定位问题也不会因为模型误操作产生大范围文件变动。10.2 隔离工作目录建议给 Codex CLI 一个独立的工作目录避免它直接修改重要文件。如果它需要操作你的真实仓库先确保代码已提交到 Git方便回滚。养成每次让 AI 改完代码后人工 review diff 的习惯。10.3 密钥管理不要把 API Key 写在 config.toml 或者 BAT 脚本里。通过环境变量注入并确保.gitignore排除了相关文件。在服务器上建议使用 secrets 管理工具或配置管理工具统一分发。10.4 日志与审计批量任务一定要有日志。记录每条任务的入参。返回的完整输出。耗时和错误信息。对应的 commit 或文件变更。这样即使出现问题也能快速回放和定位。10.5 合规复核生成代码也可能包含第三方开源代码的片段。商用前要人工核对许可证和来源。涉及版权素材、人脸、声音等信息时必须确认已获得授权。不要将敏感代码直接发送到未知模型服务除非服务条款明确允许。11. 总结与下一步这次部署的核心是两条把 Codex CLI 装到服务器上通过配置把模型指向你需要的服务。接第三方 API 是成本最低的起步方式接本地模型则适合对数据隐私和可控性要求更高的