在服务器上装 Codex CLI再把大模型接进去这件事听起来涉及的东西不少但拆开以后其实就是三步装好命令行工具、写好模型配置、跑通一条真实任务。这篇教程就是按这个顺序来的适合已经有一台云服务器、想在服务器上用命令行方式调用大模型的开发者也适合想用 Codex 接 DeepSeek 这类兼容接口模型的人。标题里的“免费”更准确的说法是 Codex CLI 本身可以装到自己的服务器上代码和命令行工具是开源的模型服务是否免费取决于你用的是哪家模型的 API有的有免费额度有的按量计费落地前记得先看清计费规则。我会把每个步骤的环境条件、命令、配置、验证方法和常见报错都写出来。你不需要有 GPU也不需要提前部署大模型权重因为 Codex CLI 本质上是一个客户端它负责把你的自然语言任务发给模型服务端再把结果带回来。1. 在服务器上装 Codex 之前先分清“CLI”和“大模型”的边界这一步很多人容易搞混。看到“服务器装 Codex 接入模型”第一反应是“我的服务器要跑一个大模型”。实际上Codex CLI 不是一个模型它是一个运行在终端里的 AI 编程助手负责发起请求、接收结果、展示上下文。真正产生对话能力的是模型接口也就是你接入的 DeepSeek、本地推理服务或者其他兼容 OpenAI 格式的模型服务。1.1 Codex 是什么在本教程里解决什么问题Codex CLI 适合用来在终端里完成代码生成、代码解释、文件操作建议、命令执行辅助这类任务。你可以直接输入一句话比如“写一个 Python 脚本统计日志里的状态码”它会调用你配置好的模型接口返回代码或解释。和直接在网页里用大模型相比Codex CLI 离开发环境更近。它运行在服务器上能读取当前目录下的文件也能理解你给的上下文适合在部署环境、远程服务器、构建任务里使用。这次教程里Codex CLI 只是“发动机外壳”真正干活的是你接入的模型。所以后面所有配置都围绕一件事让 Codex CLI 知道请求发到哪里、用什么密钥认证、用什么模型名称。1.2 服务器需要什么条件系统、配置和网络先看一下服务器最低条件。因为我强调的是接入外部模型接口不本地跑权重所以对 CPU、GPU、显存的要求很低。操作系统Ubuntu、Debian 这类 Linux 发行版最好操作CentOS 也可以只是包管理器命令不同。配置2 核 4G 内存足够跑 Codex CLI 本身。1G 内存的机器也能试但建议先把交换分区和磁盘空间确认好。网络服务器需要能访问模型 API 的域名。装 Codex CLI 时通常还需要能访问 npm registry否则 npm 安装会卡住。Node.jsCodex CLI 的常见安装方式依赖 Node.js 和 npm建议安装较新的 LTS 版本具体版本要求以你拿到的安装说明为准。用户权限不建议直接用 root更建议创建一个普通用户来跑 Codex。这样即使批量任务出错影响范围也可控。如果你打算在同一台服务器上本地跑大模型那就另说了。本地推理对显存和内存的要求明显更高2C4G 的机器跑小模型都很吃力更不用说中大型模型。所以先想清楚你的场景是“接外部模型”还是“本地部署模型”后面配置完全不同。1.3 模型接入的两种常见方式第一种是使用默认的官方账号登录方式也就是codex login之后直接使用官方模型服务。这种方式适合想快速体验、并且已经具备相应账号条件的人。第二种就是本教程重点讲的自定义接入方式。通过配置文件指定模型提供方、接口地址和 API Key把请求发到自定义模型服务上。这种方式的好处是灵活只要对方提供 OpenAI 兼容接口就可以接进来比如 DeepSeek、本地推理服务等。需要注意不是所有模型都支持 Codex CLI 需要用到的消息格式和工具调用能力。第一次测试时我会先选一个纯问答任务不涉及文件写入和工具调用这样可以先把“通信链路”验证通。2. 服务器安装 Codex CLI从依赖检查到命令行可用安装 Codex CLI 本身不复杂但它依赖 Node.js 环境。很多人装到一半失败不是 Codex 的问题而是系统里的 Node 版本太低或者 npm 全局安装目录没有被加入 PATH。2.1 检查 Node.js 和包管理器先登录服务器检查系统里有没有 Node.js 和 npm。node -v npm -v如果两个命令都能输出版本号说明环境基本可用。如果提示command not found需要先安装 Node.js。在 Ubuntu 和 Debian 上可以先用系统包管理装一版sudo apt update sudo apt install -y nodejs npm但这里要留一个心眼。系统自带源里的 Node.js 版本可能比较旧而 Codex CLI 对 Node 版本有最低要求。遇到安装报错时不要急着怀疑 Codex先检查 Node 是否满足要求。如果版本过低建议用 nvm 这类版本管理工具安装新的 LTS 版本或者直接使用 Node 官方提供的二进制包。这一步为什么重要因为 npm 安装包时很多依赖编译和运行都依赖 Node 版本。版本过旧时安装过程可能出现各种奇怪的报错比如找不到某个模块、权限不足、甚至安装成功但运行时报错。2.2 安装 Codex CLI 并验证二进制Node.js 环境确认没问题之后执行全局安装npm install -g openai/codex安装完成后验证一下codex --version如果你能看到版本号说明命令行工具已经可以使用。如果提示codex: command not found不要急着重新安装。大概率是 npm 的全局 bin 目录没有加入当前用户的 PATH。可以先查 npm 全局目录npm prefix -g ls $(npm prefix -g)/bin如果 bin 目录里确实有 codex但命令找不到就手动把这个目录加到 PATHexport PATH$(npm prefix -g)/bin:$PATH这个 export 只在当前会话生效。为了以后每次登录都能直接用需要把这一行追加到 shell 配置文件中比如~/.bashrc或~/.zshrc。还有一种运行方式是使用 npxnpx openai/codex --version这种方式不用全局安装但每次调用时 npx 可能会做包检查速度和稳定性不如全局安装好。正式使用我建议直接全局安装。2.3 初始化配置目录和日志目录Codex CLI 运行时会用到配置目录。常见位置是当前用户家目录下的~/.codex。第一次启动前先创建好mkdir -p ~/.codex ~/codex-logs chmod 700 ~/.codex配置目录里会存放config.toml有些版本还会缓存历史会话和日志。把它设为只有当前用户可读写避免其他用户看到模型配置和密钥信息。codex-logs这个目录是我建议加的。后面跑批量任务时把每次执行的 stdout 和 stderr 都存到独立日志文件里排错会轻松很多。不要等任务跑挂了才想起来没有日志。3. 接入模型用配置文件指定模型、接口地址和密钥Codex CLI 默认可能直接走官方登录通道。但在“服务器装 Codex 接入模型”这个场景里我更推荐你直接通过配置文件指定模型提供方这样不依赖登录态也方便切换到不同模型服务。3.1 为什么不用登录也能接入模型如果你接入的是自定义模型通常不需要执行codex login。你只需要在配置文件里告诉 Codex CLI模型叫什么、接口地址是什么、API Key 从哪个环境变量读。这背后的逻辑是Codex CLI 本身支持自定义模型提供方。它把请求发到base_url指定的地址用env_key指向的环境变量作为鉴权凭证。模型服务只要兼容 OpenAI 的请求格式CLI 就能和它通信。有些版本的 Codex 可能会在启动时提示需要登录那多半是配置文件没生效或者配置项格式不对。先检查配置文件名和路径不要急着去找登录流程。3.2 编写 Codex 配置文件常见配置文件路径是~/.codex/config.toml。不同版本的字段可能略有差异这里给一个常见的示例结构model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY字段含义model实际请求时使用的模型名称必须是模型服务支持的名字比如deepseek-chat。model_provider指定使用下面[model_providers.deepseek]这一组配置。name给这个模型提供方取的展示名称不影响请求。base_url模型服务的 API 根地址。这个值一定要照模型服务文档写不能自己猜。有的服务要求写成https://api.example.com/v1少了/v1可能直接报 404。env_key告诉 Codex CLI 去读取哪个环境变量作为 API Key。配置文件里的base_url是核心。你要是填错了后面所有请求都会失败。所以写完配置后建议先对照服务商文档检查一遍再继续下一步。3.3 配置环境变量的三种方式API Key 不推荐直接写进config.toml。更稳妥的方式是放到环境变量里由env_key指定读取。第一种临时设置适合快速测试export DEEPSEEK_API_KEYsk-你的密钥第二种持久化设置适合长期使用。把上面的 export 追加到~/.bashrc或~/.zshrc末尾然后重新加载source ~/.bashrc第三种用.env文件管理。适合在项目目录里维护不同环境的配置set -a source .env set a这些方式本质上都是设置环境变量。区别只是作用范围和生命周期。我个人建议至少要把 API Key 和项目代码分开不要写死在某个脚本里避免不小心提交到代码仓库。注意不要在命令行里直接粘贴完整 API Key 后按下回车这样会留在 shell history 里。测试时可以先echo $DEEPSEEK_API_KEY确认变量已加载但不要打印完整值。4. 第一次实操用最小任务跑通“服务器 - 模型 - 结果”配置写完环境变量设置好接下来就是验证。第一次验证不建议拿复杂项目来测而是用一个非常小的任务把链路跑通。4.1 单条任务命令与预期输出先跑一条纯问答任务不涉及写文件codex exec 用一句话解释什么是 HTTP 状态码 502如果一切正常你会看到模型返回一段解释。这一步只验证三件事Codex CLI 能启动。配置的接口地址能连通。API Key 验证通过。只要这一步通了说明最难的链路已经没问题。接下来再试写代码任务codex exec 使用 Python 生成一个脚本读取当前目录下的 access.log统计状态码出现次数这次可能会返回代码片段也可能直接生成文件取决于你使用的 Codex 版本和工作模式。第一次跑的时候不要默认它会自动写文件。先看回显内容确认模型确实理解任务了再去看文件系统变化。如果这条命令报错先看错误是在请求前还是请求后。请求前报错通常是配置问题请求后报错通常是模型本身不支持某些工具调用或者返回格式不符合预期。4.2 进入交互模式检查会话体验单条命令跑通后可以进入交互模式codex进入后你会看到一个交互式输入框可以直接输入自然语言问题比如“把刚才生成的脚本改成分钟级定时任务”。这种模式适合调试因为上下文可以连续不用每次把完整需求塞进一条命令。退出交互模式的方式一般是输入/exit或按CtrlC具体看版本提示。交互模式不是必须用的但它能帮你判断模型在多轮对话下是否稳定。如果你要用 Codex 做实际开发交互模式反而比单条命令更接近日常使用场景。4.3 如何在 VS Code 远程环境中使用如果你习惯在本地用 VS Code 操作远程服务器可以先用 Remote-SSH 扩展连接到服务器然后在 VS Code 的终端里运行 Codex。这种方式的好处是你可以在编辑器里直接看代码同时让 Codex 在服务器端工作。需要特别注意一点环境变量是按用户和会话加载的。如果你在 SSH 终端里设置了DEEPSEEK_API_KEY但在 VS Code 的终端里运行 Codex 时提示找不到 Key多半是因为新终端没有重新加载 shell 配置。执行一下source ~/.bashrc然后再运行codex。如果还不行检查当前登录用户是不是同一个用户。配置目录和环境变量都放在用户家目录下root 用户的~/.codex和普通用户的~/.codex是两套不要混用。5. 常见报错和排查顺序从 PATH 到 API 响应的逐层检查Codex CLI 接入模型时报错类型其实很固定。大部分问题集中在三个地方命令找不到、API Key 没生效、模型名称或接口地址不对。我给你按排查顺序列一遍。5.1 找不到 codex 命令或二进制最简单的问题是codex: command not found。先确认which codex如果没有输出说明 PATH 里没有 codex。再检查 npm 全局目录npm prefix -g ls $(npm prefix -g)/bin如果bin目录里有 codex说明问题就是 PATH 没配好。把$(npm prefix -g)/bin加入 PATH 即可。还有一个更隐蔽的错误信息类似unable to locate the codex cli binary. set codex cli path or ensure the elec...。这条报错一般不是单独运行 codex 时出现的而是某个编辑器插件或 GUI 客户端在后台找 Codex CLI 可执行文件时找不到。排查思路是在终端里执行which codex拿到可执行文件的绝对路径。把该路径填到插件设置里的 Codex CLI Path 字段或者设置对应的环境变量。重启插件或编辑器让路径配置重新加载。不要一看到这个报错就重装 Codex先确认可执行文件到底在哪。5.2 模型请求失败、401、404当 CLI 能启动但模型请求返回错误时常见现象和原因如下表错误现象大概率原因排查方式401 UnauthorizedAPI Key 没加载或密钥错误检查环境变量名和env_key是否一致404 Model Not Found模型名称不对或base_url路径不对对照模型服务文档确认模型名和接口路径Connection errorAPI 地址不可达或服务器网络受限用 curl 测试接口连通性API key missing配置项env_key没生效检查config.toml是否被正确读取先验证环境变量是否已经加载echo ${DEEPSEEK_API_KEY:0:6}这样可以只输出前几位字符确认变量非空又不暴露完整密钥。再验证接口地址是否连通。这里给一个通用测试命令curl -sS https://api.deepseek.com/v1/chat/completions \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -H Content-Type: application/json \ -d {model:deepseek-chat,messages:[{role:user,content:hi}]}注意不同服务商的接口路径可能不同有的需要/v1有的不需要。这个 curl 只是验证思路实际路径要以服务商文档为准。5.3 字符编码、退出码和日志分析Linux 服务器上还有一个容易忽略的问题中文乱码。模型返回的内容是中文但终端显示成乱码不一定是模型坏了很可能是 locale 没设置好。可以临时设置export LANGen_US.UTF-8或者使用zh_CN.UTF-8。如果系统没有安装对应语言包先安装语言包再重新加载 locale。设置完之后重新跑一次任务看输出是否正常。排查任务退出码时可以先看返回值echo $?退出码非 0 说明命令执行失败。失败信息通常会打印到 stderr所以批量跑任务时一定要把标准输出和标准错误分开保存。我一般是这样做的codex exec 你的任务 /tmp/codex_stdout.log 2 /tmp/codex_stderr.log任务卡住的时候不要直接杀进程先看系统资源top再确认网络连接和模型接口是否正常。如果请求发出去后长时间没有响应可能是接口超时或服务端压力大。这时候降低并发或者增加等待时间比盲目重启更有用。6. 从跑通到稳定使用批量任务、资源占用和边界单条任务跑通之后很多人会立刻想批量跑。但批量任务不是“多开几个终端”那么简单需要考虑日志、失败重试、并发控制和资源占用。这一节专门讲这些。6.1 批量任务基本思路我建议把每个任务保存成一个文本文件或者按行维护一个任务清单然后用循环逐条调用 Codex。这里给一个通用示例脚本#!/usr/bin/env bash mkdir -p logs i0 while read -r task; do [ -z $task ] continue i$((i1)) codex exec $task logs/task_${i}.log 21 if (( i % 3 0 )); then wait fi done tasks.txt这个脚本每执行 3 个任务会等待当前批次结束然后再继续。并发数可以自己调不要一上来就设成 20。批量任务为什么要单独存日志因为一旦任务多了你很难直接判断哪一条成功了、哪一条失败了。通过日志文件你可以快速对照任务内容和输出结果还能保留现场信息。如果任务失败需要重试可以在循环里加退避逻辑for attempt in 1 2 3; do codex exec $task break echo attempt $attempt failed logs/error.log sleep 5 done这种重试在 API 服务不稳定时很实用但也不要无限重试。重试 3 次还没过说明任务本身或配置有问题的概率更大需要人工介入。6.2 资源占用与并发控制因为 Codex CLI 本身不跑模型推理所以它对服务器 CPU 和内存的占用很低。2C4G 的机器跑批量任务瓶颈通常不是服务器资源而是 API 服务的限流和响应速度。并发数量越大单位时间内发出的请求越多API 服务可能返回 429 限流。这时候你需要看日志里有没有 rate limit 相关报错然后调低并发数。如果是跑本地模型情况就完全不同。本地模型需要加载权重到显存或内存资源和模型大小直接相关。你不能用“CLI 占内存很小”来推断本地推理也一定能跑。边界要先划清楚。场景CPU 内存磁盘主要瓶颈Codex CLI 接入外部模型需求很低日志和缓存会增长网络延迟、API 限流Codex CLI 接入本地模型取决于模型体积模型文件很大显存、内存、推理延迟批量任务需求较低日志增长明显并发控制、失败重试6.3 后续可以扩展的方向如果你想继续深入使用可以从这几个方向扩展。第一接入本地推理服务。如果你有 GPU 服务器可以先部署一个支持 OpenAI 兼容接口的推理服务然后在 Codex 配置里把base_url改成http://127.0.0.1:端口/v1。这样就变成了“自己的服务器 自己的模型 Codex CLI”不再依赖外部模型服务。但本地模型的工具调用能力和代码生成质量需要单独验证。第二把 Codex 集成进定时任务。比如每天固定时间让 Codex 生成工作摘要、更新某个文档。配合日志轮转机制避免日志文件无限增长。可以用logrotate或自己的清理脚本处理。第三封装成更友好的调用入口。比如写一个 Python 脚本接收任务内容再用子进程调用 Codex。但这有一个安全前提不要把不受信任的用户输入直接拼接进 shell 命令。否则任务内容里出现特殊字符时可能产生非预期行为。更稳妥的方式是使用subprocess.run并传入参数列表而不是拼一个完整的命令字符串。真正把这个方案用到日常任务里我建议的路径是先一台低配置服务器把 Codex CLI 跑通再接一个你有 API Key 的模型用一条任务验证最后才考虑批量、并发和集成。踩过几次之后你会发现很多问题不是模型能力不够而是环境变量没加载、配置文件写错、模型名称对不上。把这三件基础事做干净后面会省很多时间。