Ollama本地安装部署与对接Codex完整教程

这份教程将带你一步步将本地Codex部署到自己的电脑上，让你完全离线、免费地使用AI编程助手。无论你是轻度使用还是专业开发，都能找到适合自己的方案。下面，我们从一个核心概念开始，然后手把手完成安装、配置和验证。

核心概念澄清

开始操作前，请先分清两个容易混淆的关键概念，避免走弯路：

1. OpenAI Codex：这是闭源的云端编程模型，你无法在本地直接部署它。
2. Ollama官方集成的Codex（开源OSS Codex）：这是一个独立的、开源的本地编程智能体框架。它可以让你完全在本地运行代码模型（如CodeLlama、DeepSeek-Coder、Qwen-Coder）。它其实就是你Cursor里的子智能体、worktree派生功能背后的底层载体。

一、第一步：安装Ollama运行环境

Ollama是运行本地代码模型的容器，我们首先需要安装它。

1. 下载安装

前往官网：https://ollama.com/

• Windows/Mac：双击安装包，按照提示一键安装即可。
• Linux：打开终端，执行一行脚本即可完成安装。

curl -fsSL https://ollama.com/install.sh | sh

小提示：如果在Linux下安装遇到权限问题，可以在命令前加上sudo。

2. 验证安装

打开一个新的终端窗口，执行以下命令，如果成功输出版本号，则说明安装成功：

ollama --version

Ollama默认的后台服务地址是：http://127.0.0.1:11434，后续的配置会用到它。

二、第二步：拉取本地代码大模型（三档硬件选择）

根据你电脑的内存大小，选择最合适的代码专用模型。选择合适的模型至关重要，它直接影响运行流畅度和代码生成质量。

低配电脑（8G内存，轻薄本）

推荐使用轻量化的7B模型，对中文友好：

# 7B轻量化代码模型，中文友好
ollama pull qwen2.5-coder:7b

中端电脑（16G内存，游戏本）

推荐使用13B模型，性能平衡，多语言代码能力强：

# 平衡性能，多语言代码强
ollama pull deepseek-coder:13b

高配电脑（32G+内存/独立显卡）

推荐使用34B或32B的专业模型，适合处理专业项目、多文件重构和子智能体并行开发：

# 专业项目、多文件重构、子智能体并行开发
ollama pull codellama:34b-instruct
# 或通义千问代码大模型
ollama pull qwen2.5-coder:32b

注意：这种方式只适合自己电脑有独立显卡，并且内存比较大的情况。如果配置不足，强行运行大模型会导致系统卡顿或OOM（内存溢出）错误。

下面以一台32G内存+8G独显的电脑安装 qwen2.5:14b-instruct-q4_K_M 模型为例。实际上这个配置也属于中等偏下，只能勉强安装。我们使用量化版本（q4_K_M）来节省内存。

 ollama pull qwen2.5:14b-instruct-q4_K_M

部署成功

测试模型能否正常运行

拉取完模型后，务必测试一下，确保模型能正常响应：

ollama run  qwen2.5:14b-instruct-q4_K_M
# 输入一段代码需求，例如："写一个Python函数，计算斐波那契数列。"
# 能正常输出代码即表示模型就绪。

小提示：测试时，如果模型长时间无响应，可能是内存不足，请尝试关闭其他占用内存的程序。

三、第三步：启动本地开源Codex（Ollama OSS Codex）

模型就绪后，就可以启动Codex本地智能体框架了。这里有几种方式，你可以根据使用习惯选择。

方式1：以本地模型启动CodeX

在终端（CMD/PowerShell）里输入以下命令，它会自动读取你本地Ollama里的所有模型，并打开Codex界面：

ollama launch codex-app

它会自动打开 Codex 界面，并自动读取你本地 Ollama 里的所有模型（包括你的 DeepSeek）。

方式2：临时命令启动（单次使用）

使用 --oss 参数代表使用本地开源模式，-m 参数指定你下载好的本地代码模型。这种方式适合临时测试不同模型。

# 基础启动，对接ollama本地7B代码模型
codex --oss -m qwen2.5-coder:7b

# 中端13B模型启动
codex --oss -m deepseek-coder:13b

# 34B专业模型
codex --oss -m codellama:34b-instruct

方式3：持久化配置

如果你想固定使用某个模型，可以创建配置文件，这样每次启动时就不需要重复输入参数了。

首先，打开Codex配置文件。路径如下：

• Windows：C:Users你的用户名.codexconfig.toml
• Mac/Linux：~/.codex/config.toml

将以下内容粘贴到配置文件中，并保存：

# 绑定本地Ollama服务
[model_providers.ollama-local]
name = "Ollama本地模型"
base_url = "http://localhost:127.0.0.1:11434/v1"

# 默认使用的本地代码模型
[profiles.local-coder]
model = "qwen2.5-coder:7b"
model_provider = "ollama-local"

注意：base_url 中的端口号（11434）必须与Ollama服务端口一致。

之后，你就可以用配置文件一键启动Codex了：

codex --profile local-coder

方式4：图形化Cursor编辑器对接本地Ollama Codex

如果你是在Cursor软件内使用Codex子智能体，可以这样配置：

1. 打开设置：Windows按 Ctrl+,，Mac按 Cmd+,。
2. 搜索 AI Model Provider，将其切换为 Custom。
3. 在自定义接口地址中填入：http://localhost:11434/v1。
4. 模型名填写你拉取的模型，例如 qwen2.5-coder:7b。
5. API Key留空，保存后重启Cursor。
6. 重启后，所有子智能体、派生工作树、代码修改功能都将全部走本地模型，不联网云端。

官方一键恢复

如果你不想用Ollama本地模式了，想还原Codex最初的状态（恢复为使用OpenAI/ChatGPT），可以执行以下命令：

ollama launch codex-app --restore

这个命令的作用是：自动把Codex恢复成出厂默认设置（OpenAI/ChatGPT模式）。

执行完命令后，完全关掉Codex程序（不是关闭窗口，而是退出程序），再重新打开。启动后，Codex会弹出ChatGPT扫码登录界面，成功登录后，就切换回去了。

四、核心功能验证（选做）

为了确保你的本地Codex具备完整的能力，可以尝试以下两个高级功能。

本地Codex创建隔离工作树worktree

这个功能可以让你在隔离的分支上进行代码修改，不影响主分支。

# 基于main分支新建一个隔离的本地工作树，并交给本地子智能体迭代
git worktree add -b codex/local-test ../local-coder-worktree main
# 切换到新目录，codex会自动识别本地模型读写代码
cd ../local-coder-worktree
codex --oss

并行多子智能体（Subagent）本地运行

你可以同时运行多个Codex实例，每个实例使用不同的模型，模拟多个子智能体并行工作，且不占用任何云端额度。

# 终端1：前端子智能体，使用轻量模型
codex --oss -m qwen2.5-coder:7b --profile frontend
# 终端2：后端接口子智能体，使用更强大的模型
codex --oss -m deepseek-coder:13b --profile backend

五、常见问题修复

在部署过程中，你可能会遇到一些常见问题，这里给出了具体的解决方案。

1. codex命令找不到

原因：未安装开源Codex客户端。

解决：执行以下命令，一键安装Codex客户端到Ollama环境中。

# Windows/Mac/Linux一键安装Codex客户端
ollama install codex

2. Ollama连接超时

原因：Ollama后台服务可能未启动或已崩溃。

解决：检查Ollama后台是否运行，重启服务。

# Windows
ollama stop && ollama start
# Mac/Linux
systemctl restart ollama

小提示：在Windows上，你也可以在任务管理器中找到Ollama进程，结束它后再重新启动。

3. 内存不足、模型加载卡顿

原因：选择的模型太大，超出了电脑的物理内存或显存。

解决：

1. 切换更小参数量模型：优先使用7B模型，如 qwen2.5-coder:7b。
2. 开启GPU加速：Ollama默认会尝试使用NVIDIA独立显卡。如果你的N卡未被自动识别，可以尝试设置环境变量 CUDA_VISIBLE_DEVICES=0。AMD显卡需要额外配置，具体请参考Ollama官方文档。
3. 关闭后台软件：关闭所有不必要的高内存占用软件（如浏览器、IDE、游戏等）。

4. GitHub CLI不可用，但不影响本地Codex

原因：误解了本地Codex对GitHub的依赖关系。

解决：放心，本地模型仅依赖Git本体来管理worktree和分支。gh（GitHub CLI）只是一个推送代码到云端仓库的增强工具。如果你只做纯本地开发，完全可以不安装gh。

5. 模型回答为空或报错

原因：模型文件损坏或与当前Codex版本不兼容。

解决：重新拉取模型：ollama pull 模型名。如果问题依旧，请尝试更新Ollama和Codex到最新版本。

6. Codex界面不显示模型

原因：Codex启动时没有正确读取到Ollama中的模型列表。

解决：先确保Ollama服务正在运行，并且模型已成功拉取（ollama list查看）。然后，使用codex --oss -m 模型名手动指定模型启动。

六、关键区分避坑

最后，再次强调几个关键区别，帮助你避免混淆：

1. 闭源OpenAI Codex：只能云端调用API，你无法在本地部署它。
2. Ollama OSS Codex：这是一个开源的本地编程智能体框架，搭配CodeLlama、通义千问等代码模型，可以完全离线运行。它支持子智能体、Git工作树、代码重构等完整功能。
3. 本地Codex拥有完整能力，包括：派生分支、隔离worktree、多Subagent并行、文件读写、Git提交。这些功能与你Cursor侧边栏里的一致，唯一的区别是计算资源全部来自你的本地电脑。

极简快速上手流程总结

装Ollama → 拉取代码模型 → 使用 codex --oss 启动本地智能体 → 对接Cursor编辑器，自由创建worktree、子智能体，开始离线写代码。