直接以正文开始：
如果你在Ubuntu上折腾过几款AI编程助手，大概率会有同感：网页版对话式AI和真正嵌进开发流程的编程助手，完全不是一回事。前者是“问一句答一句”，后者是“你在编辑器里写代码，它在一旁读上下文、补全、跑命令、改文件”。这篇要说的CodeX，就是OpenAI出的官方版编程助手CLI工具，而“Ubuntu本地部署CodeX”这件事，恰恰是很多人卡壳的地方——不是装不上，而是装上了不知道怎么配、配完了不知道怎么让它和本地环境好好配合。
这篇博文会把整个Ubuntu本地部署CodeX的思路和操作完整拆开，从环境准备、CLI安装、登录认证、模型对接，到本地调试和常见问题排查，全程基于我在Linux环境下实际踩过的坑和验证过的方案。不管你是刚入门的开发者，还是已经在用其他AI编程助手想换个工具，只要按照这套流程走，基本都能在半小时内跑起来一个能用的CodeX CLI环境。适合对命令行不陌生的Linux用户，也适合第一次在Ubuntu上部署AI编程助手的新手。
1. 先搞清楚CodeX CLI的定位与本地部署思路
1.1 CodeX到底解决什么问题，为什么选CLI形态
在动手安装之前，先把CodeX CLI的定位说透。CodeX是OpenAI在2025年推出的编程助手产品线，而它的CLI版本（命令行工具）定位非常明确：让开发者在不离开终端的情况下，获得一个能理解项目上下文、能读写文件、能执行命令的AI编程搭档。
和传统的“编辑器插件型”AI助手不同，CodeX CLI是跑在终端里的独立进程，这意味着两件事。第一，它不绑定某个编辑器，Vim、Neovim、VS Code、JetBrains全家桶，甚至你只用SSH连到服务器上改代码，它都能用；第二，它天然适合“本地优先”的工作流——你的代码、你的配置、你的对话记录都留在本机，适合对代码隐私有要求的场景。
我在Ubuntu上选CLI形态还有一个很实际的原因：服务器或远程开发机上往往没有图形界面，编辑器插件那套方案根本跑不起来。CLI工具只要一个终端就能干活，无论你是本地电脑还是云主机，只要能装Node.js，就能跑CodeX。
1.2 本地部署的技术栈与准备工作
CodeX CLI本身是一个Node.js应用，本地部署这套东西需要的基础环境并不复杂，核心就三样：Node.js运行时（版本要求18以上，实测20 LTS最稳）、Git（用于版本控制集成和认证）、以及一个OpenAI账号的API Key或者在本地跑一个兼容OpenAI接口的模型服务。
这里要特别说一下“本地部署”的含义。CodeX的架构是“CLI客户端 + 远端或本地模型服务”，CLI本身负责交互、上下文收集、文件读写，而实际做推理的模型可以有两种选择：一种是用OpenAI官方API，走云端推理；另一种是接你自己本地部署的大模型（比如DeepSeek、Ollama托管的模型、或者通过vLLM等框架启动的本地推理服务）。
我个人强烈建议在开始之前先想清楚一个问题：你的主要场景更看重“开箱即用的代码能力”，还是更看重“数据完全不出本机”？如果选前者，配置官方API最快；如果选后者，就得提前把本地模型服务跑起来。这两种方案的配置路径我都试过，下面会分别展开，两种都适配。
1.3 安装前需要知道的三个关键术语
在配置过程中会反复看到三个词：auth（认证）、config.toml（配置文件）、model_providers（模型提供方）。理解这三个概念，后面就不会在配置里迷路。
auth解决的是“你是谁”的问题。CodeX CLI默认通过OpenAI账号体系做OAuth登录，登录成功后会在本地生成一个凭据文件，之后调用API就用这个凭据完成身份认证。如果不用官方OpenAI，而是接第三方或本地模型，通常会改用API Key方式，效果一样，走的路径不同。
config.toml是CodeX CLI的核心配置文件，位置在~/.codex/config.toml。这个文件决定了两件事：模型从哪里来、以及CLI用什么样的行为方式。后面配置的重点就是折腾这个文件。
model_providers是CodeX为了支持第三方模型做的抽象层。它的作用是让你在config.toml里自定义一个“模型提供方”，然后指定这个提供方的请求地址和模型名，从而把CodeX当成一个“万能客户端”，接DeepSeek、接Ollama、接本地推理服务，都是靠这个机制实现的。
2. Ubuntu环境准备与依赖安装
2.1 Node.js安装：版本选择和两个常见路径
CodeX CLI跑在Node.js上，所以第一步是把Node.js装好。我见过不少人在这一步就翻车，主要原因是用了系统自带的apt源，装出来的Node.js版本太老（Ubuntu 22.04默认apt源里只有12.x），而CodeX要求至少18以上。所以不要省事，直接用NodeSource源或者nvm装。
我自己用的方案是nvm，因为它的好处是能随时切换Node版本，万一CodeX更新要求更高的Node版本，一条命令就能升，不需要重装系统级环境。安装流程很简单：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash # 重开终端或执行 source ~/.bashrc 让nvm生效 nvm install 20 nvm use 20如果你不想用nvm，也可以直接装NodeSource的LTS版本：
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs装完验证一下：
node --version npm --version注意：如果这里
node --version输出的是v20.x以上，说明环境OK；如果还是旧版本，检查一下是不是PATH里其他位置的node优先级更高（比如/usr/bin/node），用which node看当前执行的是哪一个。
2.2 Git安装与基础配置
CodeX在和代码仓库交互时依赖Git，比如它需要读取git diff来理解你改了什么、需要用git log来看提交历史、甚至可以直接让CodeX帮你生成commit信息。所以Git的安装和基础配置是必须的。
sudo apt update sudo apt install -y git git --version装完之后做最小配置，否则后面CodeX的Git集成可能会报身份信息缺失：
git config --global user.name "你的名字" git config --global user.email "你的邮箱"这里有一个容易忽略的细节：CodeX在会话中如果需要执行Git操作，会继承你当前用户的Git配置。如果你在某个项目里设置了局部用户信息，但全局没设置，它跑命令时偶尔会因为这个报错。所以最好一上来就把全局的user.name和user.email配好，避免后患。
2.3 为什么建议先把本地AI模型服务跑起来
前面提到了CodeX可以接本地模型服务，这里展开说说为什么我建议在“本地部署”这个主题下，优先考虑把本地模型也跑起来。
一是成本。CodeX如果走官方API，按token计费，重度使用的话一个月下来不是小数目。而本地部署一套开源模型（比如DeepSeek的量化版、Qwen系列），只要显卡够用，就是一次性的硬件投入。
二是数据安全。很多公司代码库是敏感的，不允许发到外部API。本地部署模型意味着代码上下文只在本机流转，这在合规性上省了很多麻烦。
三是调试效率。本地模型服务没有网络延迟，响应速度完全取决于你的显卡性能。实测在RTX 4090上跑中等尺寸的代码模型，首token延迟可以压到几百毫秒，体感跟云端API差距不大。
我给读者的建议是：如果你是个人开发者、想快速体验CodeX的完整功能，先配官方API，几分钟就能通；如果你是在公司环境、或者对私密性有要求，那就提前把Ollama或者vLLM搭好，再接CodeX。下面第4节会讲具体的对接方式。
3. 安装CodeX CLI与核心配置
3.1 安装命令与版本验证
CodeX的安装方式在官方文档里其实很简单，但很多人会被网络问题卡住。在Ubuntu上，官方推荐的方式是用npm全局安装：
sudo npm install -g @openai/codex装完之后验证安装是否成功：
codex --version如果你看到类似codex 0.x.x的输出，说明CLI本体装好了。如果提示command not found，大概率是npm全局bin目录不在PATH里，排查方法下面单独说。
这里有个小坑：npm全局安装默认会把可执行文件放到/usr/local/bin或/usr/lib/node_modules下的bin目录。如果你用nvm装的Node，它的全局bin目录在~/.nvm/versions/node/v20.x.x/bin。不管哪种，只要codex命令能被找到就行。
3.2 登录认证：官方OAuth方式
第一次运行codex时，CLI会引导你完成登录。官方推荐的流程是OAuth登录：
codex首次运行会输出一个登录链接和一行等待码（类似设备码验证），在浏览器里打开链接、输入等待码、授权之后，CLI就会在本地保存凭据，之后就不需要重复登录了。
认证成功后，建议先跑一次最简单的对话验证一下：
codex "你好，简单介绍一下你自己"如果正常返回，说明CLI已经能连上官方模型服务。
注意：OAuth登录是OpenAI官方路径。如果你用的是第三方模型服务，这一节可以跳过，直接用下面的API Key方式。
3.3 config.toml配置文件逐项拆解
不管走哪条模型路径，config.toml都是CodeX CLI的核心。我直接把一份经过实测的配置拆开讲，每行干什么、为什么这么写，尽量说清楚。
配置文件默认路径：~/.codex/config.toml，如果不存在就自己创建：
mkdir -p ~/.codex vim ~/.codex/config.toml一份接官方API的最小配置长这样：
model = "gpt-5-codex" model_provider = "openai"model指定默认模型名，model_provider指定使用哪个提供方。这两个字段在CLI里甚至在跑起来之后都能临时覆盖，但在配置文件里写清楚，省的每次启动都要加参数。
如果你想接第三方API（比如DeepSeek），需要自定义provider：
model = "deepseek-chat" model_provider = "deepseek" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY" wire_api = "chat"这段配置里值得说清楚的是wire_api这个字段。CodeX支持两种API协议：chat（对应于OpenAI的Chat Completions接口）和responses（新的Responses接口）。OpenAI自己的模型用responses格式，但大多数第三方厂商目前只兼容chat格式，所以接DeepSeek或者其他兼容OpenAI的第三方服务时，必须把wire_api设成chat，否则会请求失败。
env_key的作用是告诉CodeX：去环境变量里找API Key。也就是说你需要在~/.bashrc或~/.zshrc里加上：
export DEEPSEEK_API_KEY="你的key"然后source ~/.bashrc让它生效。
3.4 通过API Key方式接入第三方模型服务
除了官方OAuth，CodeX也支持直接用API Key的方式调用OpenAI兼容接口。这种方式在接本地模型、内网模型网关时非常方便，因为不依赖浏览器登录。
配置方法还是在config.toml里加provider，比如接一个本地的vLLM服务：
model = "qwen2.5-coder-7b" model_provider = "local-vllm" [model_providers.local-vllm] name = "Local vLLM" base_url = "http://localhost:8000/v1" env_key = "LOCAL_VLLM_API_KEY" wire_api = "chat"这里的base_url指向你本地推理服务暴露的OpenAI兼容地址。很多本地推理框架（vLLM、Ollama、LM Studio、llama.cpp server）都提供这个接口，只需要让CodeX的base_url指向它们即可。
环境变量里加上：
export LOCAL_VLLM_API_KEY="local-key"本地服务一般不做严格鉴权，但CodeX的这个字段是必填的，随便填个占位符就行，关键是不能空着。
实测心得：很多人在这一步会纠结“没有OpenAI账号能不能用CodeX”。答案是可以的，只需要让
model_provider指向任意一个兼容OpenAI协议的服务即可，不一定非得是OpenAI官方。这意味着你在Ubuntu上完全可以用CodeX客户端去接DeepSeek、Qwen、或者任何本地跑起来的模型。
3.5 环境变量配置与PATH排查
前面提到了环境变量，这里把Ubuntu下配置环境变量的细节补齐。打开你的shell配置文件：
vim ~/.bashrc在末尾追加：
export DEEPSEEK_API_KEY="你的key"然后使其生效：
source ~/.bashrc用下面命令确认环境变量已经加载：
echo $DEEPSEEK_API_KEY如果你遇到codex: command not found，用下面方法排查：
npm prefix -g # 这个命令会输出npm全局根目录，比如 /usr/local 或 /home/用户名/.nvm/versions/node/v20.x.x # 那它的bin目录就是 /usr/local/bin 或 /home/用户名/.nvm/versions/node/v20.x.x/bin # 检查这个bin目录是否在PATH里： echo $PATH不在PATH里就加上，比如：
export PATH="/usr/local/bin:$PATH"同样写入~/.bashrc。
4. 模型对接与本地调试实战
4.1 CodeX接Ollama本地模型实操
如果你希望数据完全本地化，Ollama是目前最省事的本地模型运行方案。安装Ollama只需要一条命令：
curl -fsSL https://ollama.com/install.sh | sh安装完成后，拉一个适合代码生成的模型，比如：
ollama pull deepseek-coder-v2:16b如果是配置一般的机器，也可以选更小尺寸：
ollama pull qwen2.5-coder:7b模型拉下来之后，默认会启动在http://localhost:11434。Ollama自带OpenAI兼容接口，路径是http://localhost:11434/v1。
然后在~/.codex/config.toml里加这样的provider：
model = "qwen2.5-coder:7b" model_provider = "ollama" [model_providers.ollama] name = "Ollama" base_url = "http://localhost:11434/v1" env_key = "OLLAMA_API_KEY" wire_api = "chat"设置环境变量：
export OLLAMA_API_KEY="ollama"注意：Ollama的OpenAI兼容接口在最新版本中已经不强制校验API Key，但CodeX的配置结构要求这个字段存在，随便填一个非空字符串即可。
然后启动CodeX：
codex如果能看到模型正常响应，说明CodeX已经成功接入本地Ollama。
4.2 本地推理服务参数选择与调试技巧
如果你不想用Ollama，而是想用vLLM或者llama.cpp跑一个更高性能的本地服务，这个思路也一样，就是让CodeX的base_url指向你的服务地址。
以vLLM为例，启动一个OpenAI兼容服务：
python -m vllm.entrypoints.openai.api_server \ --model Qwen/Qwen2.5-Coder-7B-Instruct \ --host 0.0.0.0 \ --port 8000这时CodeX的config.toml里base_url就填http://localhost:8000/v1。
说一下参数选择的逻辑。本地模型的参数量直接决定了显存需求和推理速度。以7B模型为例，FP16精度大约需要14GB显存，4-bit量化之后大约降到5~6GB。如果你只有8GB显存，建议直接用Ollama跑量化版7B模型，或者选更小的3B/4B模型。如果你有24GB显存（比如RTX 3090/4090），可以考虑14B甚至32B的量化模型，代码能力会有明显提升。
关于量化，Ollama默认拉下来的很多模型就是量化过的，一般不需要手动处理。用vLLM的话，可以加--quantization awq或--quantization gptq来加载量化模型。
操作心得：本地模型刚接上CodeX时，不要直接用大任务测试。先用一行代码的补全、一个简单的“解释这段代码”请求去验证连通性，确认无误后再做批量代码生成，这样能快速定位是配置问题还是模型能力问题。
4.3 模型能力对比：官方模型与本地模型怎么选
接入不同的模型之后，我实测下来的感受是：官方模型（比如gpt-5-codex）在复杂任务理解、多文件上下文记忆、跨文件重构这些场景下明显更强，尤其是对大型代码仓库的全局理解，本地中等尺寸模型做不到那个程度。
但本地模型也有自己的位置。首先是隐私和成本，其次对于机械性任务——补全函数、写单元测试、批量改格式、生成模板代码——本地模型完全够用，而且响应速度在好显卡上不输云端。
我的建议是：在config.toml里同时配好官方和本地两个provider，日常用官方模型干活，但在处理敏感代码或网络不方便时，用--config方式临时切到本地模型。CodeX支持启动时指定模型配置：
codex --config ~/.codex/config.local.toml这样你可以在家准备两套配置文件，按需切换，很灵活。
4.4 CodeX CLI的日常使用工作流
配置完了之后，说说日常怎么把它用好。CodeX最实用的模式是repl模式，直接在终端里进入交互对话：
codex repl在这个模式下，你可以让它读取文件、解释报错、修改代码，甚至让它执行shell命令。关键技巧是让它“先读懂上下文再动手”，比如进入项目目录后先来一句：
请阅读一下当前目录的README和src/main.py，告诉我这个项目的大致架构，以及入口函数在哪里。CodeX会自己读取文件，然后基于真实代码回答，而不是瞎编。这一点比很多只基于聊天窗口的工具靠谱得多。
另一个常用模式是直接在CodeX命令后加指令，实现快速本次对话完成：
codex "给这个项目的README写一份简洁的说明，包括安装步骤和用法示例"它会自动扫描当前目录，生成对应文件或输出内容。
体验分享：第一次用CodeX的时候，别急着让它写整个项目，先让它做小任务——重构一个函数、写一个测试用例、解释一段复杂的正则——这样你能快速摸清它的行为习惯，也避免它做出不可控的大改动。
5. 常见问题与排查技巧实录
5.1 高频问题速查表
把我在Ubuntu上部署和使用CodeX过程中遇到的高频问题整理成一张表，方便你按图索骥：
| 问题现象 | 可能原因 | 排查与解决方法 |
|---|---|---|
codex: command not found | npm全局bin目录不在PATH中 | 用npm prefix -g确认bin路径，加入PATH |
启动报错提示Cannot find module @openai/codex | npm全局安装不完整 | 重装：sudo npm uninstall -g @openai/codex后再装 |
| 认证后仍提示401或未授权 | 环境变量API Key未生效 | 检查echo $OPENAI_API_KEY是否输出，重新source ~/.bashrc |
| 接本地模型时请求超时 | 本地服务未启动或base_url拼错 | 先curl测试本地接口：curl http://localhost:11434/v1/models |
| 请求返回404 | wire_api字段类型不匹配 | 第三方服务改为wire_api = "chat"，官方模型用responses |
| 输入中文时编辑器内显示乱码 | 终端locale未设为UTF-8 | 执行export LANG=en_US.UTF-8或安装中文语言包 |
| 生成的代码缩进混乱 | 模型本身能力限制 | 改用官方模型或更大尺寸本地模型 |
5.2 最容易踩的坑：wire_api不匹配和API Key优先级
第一个高频坑就是wire_api。很多人在接第三方API时，从网上复制一段配置，wire_api字段要么没写，要么写的是responses，导致请求打到第三方服务后，对方不认识这个协议，直接返回404或400。记住这个基本原则：除非你连的是OpenAI官方模型，否则一律用chat。
第二个坑是环境变量优先级的问题。CodeX读取API Key时，如果同时存在OPENAI_API_KEY环境变量和config.toml里自定义provider的环境变量，某些版本可能会优先走默认的OpenAI路径，导致你明明配了DeepSeek的provider，结果请求还是发给了OpenAI。
解决方法是：如果不用官方模型，就不要在环境变量里导出OPENAI_API_KEY；或者把config.toml里的model_provider显式指定为你自定义的provider名称，不给CLI任何猜测空间。
5.3 调试工具与日志查看方法
CodeX留下了一些日志，出问题时有日志可看会快很多。默认日志位置在~/.codex/log/下，每个会话会生成一个日志文件。排查问题时可以执行：
ls -lt ~/.codex/log/ | head -5然后打开最新的日志文件，搜索error或failed关键字。日志里通常能看到HTTP请求的完整URL、请求体、响应状态码，这些信息能快速帮你定位问题出在CLI本地、网络、还是远端服务。
如果想更直观地确认base_url是否被正确读取，可以加--verbose参数运行CodeX：
codex --verbose "测试一下"它会把正在使用的配置和请求目标打印出来。
5.4 让CodeX和VS Code协作的补充技巧
虽然标题是CLI配置，但实际使用中很多人会同时开着VS Code。CodeX CLI不直接提供编辑器插件，但你可以用VS Code的“集成终端”来跑CodeX，这样既能看代码，又不脱离CLI工作流。
具体做法：在VS Code里按Ctrl+`打开终端，直接运行codex repl，然后就能一边看编辑器里的代码，一边在终端里和CodeX对话。CodeX读取文件、修改代码的痕迹会直接反映在编辑器里，体验相当顺畅。
如果希望CodeX生成的代码块能更结构化地展示，可以在VS Code里搭配一个Markdown预览插件，这样终端里输出的代码块会自动格式化，阅读体验好不少。
结束语
我个人在实际操作中最受益的一个习惯是：永远准备两套model_provider，一套官方模型，一套本地模型，用config文件快速切换。因为在不同的项目、不同的网络环境、不同的隐私要求下，没有一套配置能通吃所有场景。把“本地部署”这件事真正做好，不是把CodeX装起来就完事，而是让它在你的Ubuntu环境里做到按需切换、随叫随到。最后再分享一个小技巧：配置完成后，记得把~/.codex/config.toml做一个备份，折腾坏了随时能恢复，这个习惯让我少踩了很多坑。
