我最近把一台放在机房里、连显示器都没有的 Linux 服务器翻了出来给它装上本地部署的 DeepSeek 模型再用 Codex 这个终端工具直接对接调用。折腾完回头去看这条链路并不复杂但中间有几个特别容易让人绕弯的位置无图形界面环境下只能靠 SSH 操作Codex 的配置需要改不少参数本地模型的 OpenAI 兼容协议也不是每个框架都完全一致。这篇文章就是我这套方案的完整记录从环境准备到安装调试再到常见报错的排查思路希望能给同样想在纯终端环境下跑私有化 AI 编程助手的同学一点参考。适合阅读的人有一定 Linux 基础、想折腾本地大模型、或者正在找 Codex 接入非官方模型的解决方案的开发者。1. 整体方案设计一条链路打通纯终端 AI 工作流1.1 需求拆解无图形界面服务器到底限制了什么先明确无图形界面服务器是什么意思。简单说就是一台没有显示器、没有桌面环境GNOME、KDE 这些平时只能通过 SSH 远程登录操作的 Linux 机器。它并不比普通电脑差恰恰相反服务器通常配备更大的内存、更强的 CPU 和显卡非常适合跑大模型。但它有一个现实约束你只能和它通过命令行交互。这个约束带来三个问题。第一Web 类管理界面不方便开就算开了也只能在浏览器里通过端口转发访问网络稍微不稳定就断第二SSH 断开会导致前台进程被杀掉如果没做好终端复用训练一半的任务或者 AI 对话就可能中断第三很多 AI 编程客户端比如桌面版应用依赖图形界面在服务器上用不起来。所以能在终端里直接运行的工具才是硬道理。我最终选的组合是服务器上用 Ollama / vLLM 这类推理框架把 DeepSeek 跑成本地服务然后在终端里用 Codex CLI 作为客户端把请求发送到本地接口。整条链路完全不依赖图形界面SSH 进去以后就是一个 tmux 会话 一个 Codex 交互界面非常干净。1.2 为什么选 Codex 而不是其他终端方案很多人会问我直接用 curl 调 API 不也能用吗当然可以但 curl 是纯手工档而 Codex 这类 CLI 工具的价值在于它把和模型对话、执行命令、审查改动打包成了一个工作流。Codex 能识别任务意图列出要执行的命令请求你批准后再执行然后把结果继续交给模型做下一步判断。这种循环在纯终端环境里非常高效配合本地模型就相当于拥有一个私有化的 AI 编程搭档。Codex 连接非 OpenAI 官方模型的原理也不复杂。它本质上是调 OpenAI 格式的 API所以只要本地推理框架提供的是兼容接口通常是 /v1/chat/completionsCodex 就能通过配置 base_url 把流量指向本地端点。Ollama、vLLM、llama.cpp 服务模式都在这个兼容范围内这也是整个方案能够成立的核心机制。对比其他方案比如自己在终端里写一个 Python 脚本去调 API或者用 Open WebUI 这类 Web 前端Codex 的优势在于它已经把权限管理、文件读写、命令执行这些 AI 编程场景的常用能力封装好了你用起来不需要自己再写一层胶水代码。2. 环境准备先把 DeepSeek 在服务器上跑起来2.1 先用 nvidia-smi 和 free 命令体检服务器在动手装东西之前先把服务器的家底摸清楚。我用几条命令就能完成整体体检# 查看显卡型号与显存 nvidia-smi # 查看 CPU 和内存 lscpu | grep -E Model name|Socket|Core|Thread free -h # 查看磁盘剩余空间 df -h /home显存大小直接决定了你能运行哪个档位的 DeepSeek 模型。以 DeepSeek-R1-Distill 系列为例量化后 7B 模型大概需要 6~8GB 显存14B 大概需要 12~14GB32B 如果没有足够显存基本没法流畅跑。我的这台服务器是一张 24GB 的显卡所以选 14B 档完全够用还能留出余量给上下文长度。还有一个容易忽略的地方确认系统里有没有装好 NVIDIA 驱动和 CUDA。很多时候显卡插上了但驱动没装或者版本太低推理框架根本起不来。建议先跑一次nvidia-smi只要能看到显卡信息和驱动版本就可以继续。2.2 Ollama 快速部署一条命令拉起本地模型如果你想最快速度把 DeepSeek 跑起来Ollama 是绕不开的选择。它的安装很简单curl -fsSL https://ollama.com/install.sh | sh安装完成后服务默认监听 11434 端口。接着拉取模型ollama pull deepseek-r1:7b # 或者 ollama pull deepseek-coder:6.7b这里我个人建议优先用deepseek-r1系列它在代码生成和逻辑推理上表现更好和 Codex 的编程场景更契合。模型拉取完成后可以通过一条命令验证服务是否正常curl http://localhost:11434/v1/models如果返回了一段包含模型列表的 JSON说明服务已经起来了。Ollama 从 0.26 版本开始自带一个 OpenAI 兼容的/v1接口Codex 可以直接通过这个地址接入。要注意的是Ollama 默认只监听 127.0.0.1如果 Codex 和服务不在同一台机器上需要通过环境变量OLLAMA_HOST0.0.0.0:11434来让服务监听所有网卡。不过我们这个场景里 Codex 和模型都在同一台服务器上默认配置就够了。2.3 vLLM 部署参数详解与启动示例Ollama 简单但如果你追求更高的并发吞吐和更低的延迟vLLM 是更专业的选择。它专门为 GPU 推理做了优化支持 PagedAttention、连续批处理等特性跑大批量请求时优势很明显。安装和启动的参考命令pip install vllm python -m vllm.entrypoints.openai.api_server \ --model deepseek-ai/DeepSeek-R1-Distill-Qwen-14B \ --served-model-name deepseek-local \ --max-model-len 8192 \ --gpu-memory-utilization 0.9 \ --port 8000vLLM 启动后默认提供一个 OpenAI 兼容的 API 服务监听 8000 端口。--served-model-name参数很重要它决定了代码里调用的模型名后面 Codex 配置里要和服务端保持一致。--max-model-len控制上下文长度上限8K 算是比较稳妥的起步值如果你的显卡显存够大想跑长上下文可以调到 16K 甚至 32K但对应的显存占用也会上升。无论用哪种方式部署完以后都要先验证一下真实的模型推理是否正常。我最常用的验证命令是这个curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: deepseek-local, messages: [{role: user, content: 用一句话介绍你自己}], max_tokens: 100 }能正常返回带有choices[0].message.content的 JSON就说明接口通了可以进入下一阶段。2.4 为什么 OpenAI 兼容接口是关键这里多说一句为什么本地模型服务能直接对接 Codex。OpenAI 公布了一套 Chat Completions API 的格式本地推理框架为了兼容生态都实现了这一套接口。也就是说不管后端跑的是 Ollama、vLLM 还是 llama.cpp对客户端来说长得都一样都是 POST /v1/chat/completions输入输出格式相同。这样的标准化设计让 Codex 这类工具几乎不需要做什么定制就能连接各种本地模型服务。反过来看如果某个模型服务没有实现 OpenAI 兼容接口那 Codex 基本连不上除非你写一个转换代理层。这里也顺带解释了为什么很多部署框架都强调OpenAI compatible——它不是空话而是生态兼容的入场券。3. Codex 安装与连接本地 DeepSeek 的配置3.1 Codex 安装npm 与二进制两种方式Codex 的官方安装方式是 npm 全局安装命令很简单npm install -g openai/codex安装完成后执行codex --version确认装好。如果你的服务器上没有 Node.js 环境需要先装 Node 18 以上的版本否则 npm 会直接报错。也有直接下载二进制包的方式官方 GitHub Release 页面提供了对应平台的压缩包解压后把可执行文件放到 PATH 里就能用。在无图形界面服务器上二进制的优势是不用额外装 Node对系统环境更友好。装完以后先别急着登录。Codex 默认会走 OpenAI 官方的认证流程但我们这次的目标是本地模型不需要也无权使用官方 API所以要跳过这一环。跳过的方式是设置一个虚拟的 API Key 和自定义 API 地址这个在下一节讲。3.2 核心配置文件把 Codex 指向本地端点Codex 的全局配置文件默认在~/.codex/config.toml。配置的核心是告诉 Codex去哪个地址找模型、用哪个 API Key、走哪种协议。我用的配置如下model deepseek-local model_provider deepseek-local [model_providers.deepseek-local] name DeepSeek Local base_url http://localhost:8000/v1 env_key DEEPSEEK_API_KEY wire_api chat解释一下每个字段的含义model指定使用的模型名必须和推理服务里的模型名一致。vLLM 的--served-model-name设为deepseek-local这里就写deepseek-local如果用 Ollama 拉的是deepseek-r1:7b这里就要写deepseek-r1:7b。base_url本地 API 服务的根地址。注意结尾要带/v1因为 Codex 会在这个地址后面拼接具体的路由。env_keyAPI Key 来源的环境变量名。Codex 需要读取一个非空的 key内容无所谓因为本地服务并不校验但不能缺。在启动 Codex 之前做个导出就行。wire_api指定走 Chat Completions 协议chat让 Codex 使用 OpenAI 传统的对话补全接口。这一步非常关键我后面会展开讲为什么。配置写好后启动前先导出一个假的 keyexport DEEPSEEK_API_KEYlocal-dev-key codex3.3 纯环境变量方式快速验证用如果你不想动配置文件也可以直接用环境变量指定地址和 keyexport OPENAI_BASE_URLhttp://localhost:8000/v1 export OPENAI_API_KEYlocal-dev-key codex这个方法适合快速验证但缺点是无法指定模型名和wire_api等细节。在本地部署场景下配置文件的可控性和可维护性更强尤其当你要切换不同模型提供者时只要改一行model_provider就行。这两种方式的优先级需要注意如果配置文件里已经设置了model_provider那么环境变量会被配置文件覆盖反之如果配置文件里没有对应字段环境变量才会生效。我的建议是二选一别两边都设不然排查问题的时候容易搞混。3.4 进入 Codex 前的最后检查配置完成后进入交互界面之前先做一个快速的链路自检我习惯按下面这几步走# 1. 确认模型服务还在监听 ss -lntp | grep -E 11434|8000 # 2. 确认 Codex 版本 codex --version # 3. 确认环境变量 echo $DEEPSEEK_API_KEY这三步没问题就可以直接执行codex进入交互界面。发一条最简单的指令测试比如count from 1 to 10 and list the numbers。如果本地模型正常响应Codex 会把结果一步步展示出来并生成对应的命令执行计划。我实测时 7B 模型响应速度大概在每秒 15~25 个 token 之间14B 模型会慢一些但整体可用。如果看到类似连接失败、404、401 之类的报错不要急着改配置先回到第 2 章用 curl 验证一下本地接口是否还在监听。链路排查的顺序永远是先确认服务活着再确认 Codex 配置正确最后才是看 Codex 自身的日志。4. 无图形界面环境下的实操细节4.1 SSH 登录与终端工具选型实战既然服务器没有图形界面第一步就是用 SSH 从本地电脑连过去。终端模拟器我自己用过不少Windows 上推荐 tabby 或 Windows TerminalmacOS 上直接用系统 Terminal 也行。tabby 的好处是自带主题、支持多标签和多窗口布局SFTP 传输文件也很方便。操作上有个小技巧为了不让 SSH 连接因为断网或空闲时间过长而断开可以在本地 SSH 配置~/.ssh/config里加上ServerAliveInterval 30。这样客户端每隔 30 秒发一个心跳包连接长时间空闲也不会被服务端踢掉。Host myserver HostName 192.168.1.100 User ubuntu ServerAliveInterval 30 ServerAliveCountMax 2无图形界面服务器上默认的 shell 一般是 bash如果你习惯 zsh 也没问题但要注意配置好.zshrc里的 PATH否则命令行里找不到codex可执行文件。刚开始折腾的时候可以顺手给 shell 加个简单的提示符比如把当前目录、Git 分支展示出来操作效率会高不少。4.2 用 tmux 给 Codex 加一道保险这是无图形界面场景下最容易踩的坑。你直接 SSH 登录服务器在终端里跑codex然后中途网络闪断SSH 进程退出前台启动的 Codex 也会跟着被杀掉。AI 交流进行到一半全部丢失非常难受。解决办法是 tmux 终端复用。tmux 的核心用法只有几个# 新建会话 tmux new -s codex # 在会话中启动 codex codex # 按 Ctrlb 松开后再按 d分离会话Codex 继续在后台运行 # 重新回到会话 tmux attach -t codex有了这个习惯即使 SSH 断掉你重新登录后只要tmux attach就能回到之前的画面Codex 的上下文和对话历史都还在。整个过程相当于给 AI 工作流加了一个保鲜层。4.3 实战让 Codex 写一个日志统计脚本配置好之后我实际测试过一个需求让 Codex 写一个 Python 脚本扫描指定目录下的日志文件统计每个级别的日志数量并输出报告。进入 Codex 交互界面后输入需求Codex 会生成代码内容和执行计划。在本地 DeepSeek 模型支撑下它先给出了一个遍历文件、用正则匹配日志级别的脚本然后请求执行权限。我批准后 Codex 在服务器上创建了脚本文件运行并返回了统计结果。整个过程和官方模型的使用体验差异不大只是本地模型的指令理解和代码生成速度弱一些需要更长的等待时间。无图形界面下运行 Codex 还有几个小细节编辑器方面如果 Codex 在审批前让你查看代码它会用默认编辑器打开文件建议提前设置好环境变量EDITORvim或EDITORnano避免它反复调用系统默认编辑器导致体验割裂。5. 常见问题排查与性能调优5.1 连接报错base_url 与代理设置很多人在配置 Codex 接入本地模型时会碰到这样一串报错cc switch local proxy failed while handling codex endpoint /responses. provider...这类报错我把它拆成两层来看。第一层是endpoint /responses它说明 Codex 尝试访问的是 OpenAI 新版 Responses API 的/responses路由而不是传统的/v1/chat/completions。本地推理框架比如 Ollama并没有实现/responses端点所以连接自然失败。解决方式是在配置里显式加一行wire_api chat强制 Codex 走 Chat Completions 协议。第二层是local proxy failed这通常和终端环境变量中的 HTTP 代理有关。服务器上如果设了http_proxy或https_proxyCodex 会尝试通过代理访问本地地址代理又处理不了 127.0.0.1 的请求于是报代理切换异常。排查时先看环境变量如果有代理且当前任务不需要就临时清掉再启动unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY如果确实需要代理访问外部网络也要确保本地地址走 no_proxy 白名单最简单的方法是设置no_proxylocalhost,127.0.0.1。5.2 上下文溢出codex ran out of room 怎么调使用过程中另一个高频报错是Error running remote compact task: codex ran out of room in the models context意思是 Codex 当前会话内容累积超出了模型的上下文窗口上限。本地部署的模型规格多种多样7B 模型常见上下文的 8K 或 32K而 Codex 默认会尽量向上取用上下文。解决办法有三种第一调低 Codex 侧的上下文占用比如在配置里给max_tokens设置较小值减少单次生成的 token 量。第二执行/new开启新的会话把对话历史清空适合任务已经完成、不用保留上下文的情况。第三换用支持更长上下文的模型版本比如 DeepSeek-R1-Distill-Qwen 的 32K 版本或者在 vLLM 启动时把--max-model-len调大。这里还有一个容易忽略的点本地模型的上下文实际可用长度由服务端启动参数决定。就算 Codex 认为自己可以用 32K服务端只开 8K超出的请求也会被截断或直接报错。所以排查上下文问题时优先确认服务端启动参数再改 Codex 侧配置。5.3 响应慢从 GPU 利用率和并发参数入手如果你发现 Codex 回复一个字要磨蹭半天先别怀疑配置很可能是模型服务端的性能瓶颈。几个实测有效的优化方向第一如果用的是 vLLM检查--gpu-memory-utilization是否设置得偏低。默认 0.9 已经不错但如果你同时跑其他任务可以调低到 0.8 避免显存交换。第二确认服务端有没有真正用上 GPU运行nvidia-smi看显卡利用率和显存占用。如果显存占用正常但 GPU 利用率不高有可能是 CPU 预处理成了瓶颈可以提高--max-num-seqs的值来增加连续批处理的吞吐。第三Ollama 用户可以通过环境变量OMP_THREADS控制使用的 CPU 线程数避免和系统其他任务抢资源。一个更直接的经验本地模型的速度上限受硬件约束这是没办法绕过的。如果只是偶尔用一下7B 模型完全够用如果要作为日常主力建议直接上 32B 量化模型配一张 12GB 以上显存的显卡体验差别会非常明显。5.4 终端相关问题速查表我在排查过程中还遇到一些和终端本身相关的小问题顺手整理成一张速查表现象可能原因处理方式SSH 登录后找不到 codex 命令PATH 未包含 npm 全局目录在.bashrc或.zshrc里追加 npm 全局路径终端自动关闭SSH 超时或会话异常调整 ServerAliveInterval或用 tmux 保护会话编辑器打不开EDITOR 环境变量未设置设置EDITORvim端口被占用、服务起不来上一次进程未退出ss -lntp查看端口kill对应进程后重启排查命令是小东西但关键时刻很救命。比如你怀疑 8000 端口没起来不要反复重启先ss -lntp | grep 8000看端口状态再用lsof -i :8000查进程比盲目的 process kill 效率高得多。这类查找和删除命令的小技巧在无图形界面服务器上属于日常必备技能。整条链路跑通之后我再回头看最核心的经验其实只有一句话先把本地模型的 API 端点验证通过再让 Codex 去对接最后才调各种细粒度参数。按照这个顺序来大部分连接报错都不会困扰你。另外无图形界面服务器上一定要养成 tmux 的习惯这不仅是给 Codex 用任何长任务的保护都靠它。目前这套方案我已经跑了一段时间日常写脚本、处理日志分析、做代码审查都直接扔给本地模型处理数据完全不出服务器用着确实踏实。如果你也在折腾本地大模型希望这篇能帮你少走几个弯路。