当前位置：首页 > news >正文

Codex本地代码助手安装与使用全指南

news 2026/6/16 4:39:55

1. Codex 是什么：先别急着装，搞清它到底解决哪类问题

Codex 这个名字在当前技术圈里有点“模糊地带”——它既不是 GitHub 官方推出的工具，也不是 OpenAI 直接发布的 SDK，更不是某个开源基金会托管的标准化项目。从全网热词分布来看，“codex 安装”“codex cli”“codex ide”高频并列出现，但搜索结果中几乎找不到权威文档页、GitHub star 数破千的主仓库，或 npm 上下载量稳定的@codex/cli包。这说明：Codex 并非一个统一定义的单一产品，而是一类基于代码理解能力构建的本地化开发辅助工具的统称代号，其具体实现高度依赖于下游模型服务与前端载体形态。

我过去三年深度参与过 7 个企业级 IDE 插件项目（含 Python/JS/Go 三语言支持），也帮客户做过 12 次本地大模型代码助手集成落地。实操中发现，“Codex”这个词常被开发者用作“本地可运行、能读工程、支持 CLI 调用、带 IDE 插件入口”的轻量级代码智能体的简称。它背后真正的技术栈通常是：一个轻量级推理引擎（如 llama.cpp / ollama） + 一套代码切片与上下文注入逻辑（类似 CodeLlama 的 prompt engineering） + 多种接入层封装（CLI / VS Code 扩展 / Web UI）。

举个真实场景：某金融科技团队想让新人工程师快速理解遗留的 50 万行 COBOL+Java 混合系统。他们不希望把代码上传到任何云服务，也不愿部署整套 LLM 推理集群。最终方案是——用ollama run codellama:7b启动本地模型，再通过自研的codex-cli工具将当前目录结构、git diff、光标所在函数签名实时拼成 prompt，调用本地 Ollama API 获取补全建议。这个codex-cli就是他们内部命名的 “Codex”。

所以，当你看到“Codex 安装教程”，本质上是在找：如何把一个能理解代码语义的本地模型服务，包装成你日常开发流水中可即插即用的组件。它可能是：

一个命令行工具（CLI），让你在终端里输入codex --file main.py --ask "重构这个函数为异步"；
一个 VS Code 插件（IDE 扩展），右键菜单多出 “Ask Codex” 选项；
一个桌面应用（Electron 或 Tauri 构建），打开即用，无需配环境；
一个 Docker 容器镜像，docker run -p 3000:3000 codex-web启动网页版；
一个 Python 包，pip install codex-engine后在脚本里调用CodexClient().query(...)。

关键词里反复出现的homebrew、cli、ide、offline，恰恰印证了这个定位：它强调本地化、低侵入、高适配，核心价值不是“更强的模型”，而是“更顺的集成”。
这也是为什么网上搜不到 Codex 官网——它没有中心化发布渠道，它的“版本”取决于你选的底层模型（CodeLlama / DeepSeek-Coder / Qwen2.5-Coder）、推理框架（Ollama / LM Studio / text-generation-webui）和封装方式（Shell 脚本 / Node.js CLI / Rust 二进制）。

提示：如果你在搜索时看到 “Codex 网页版登录入口” 或 “Codex 下载安装包”，大概率指向某个第三方 SaaS 服务（可能已下线或改名），而非本文讨论的本地化工具链。真正的 Codex 不需要注册、不依赖账号、不联网也能工作——只要你的模型权重文件在本地磁盘上。

2. 五种安装路径：按你的环境约束和使用目标精准选择

安装 Codex 的本质，是搭建一条“从命令行/IDE 到本地模型推理服务”的稳定通信链路。不存在“唯一正确”的安装方式，只有“最适合你当前约束条件”的组合。下面五种路径，覆盖了从零基础小白到 DevOps 工程师的全部典型场景，每种都附带实测验证过的命令、耗时、成功率及适用边界。

2.1 路径一：Homebrew + Ollama（Mac 用户首选，5 分钟极速启动）

这是目前 Mac 用户落地 Codex 最稳、最省心的组合。Homebrew 解决依赖管理，Ollama 解决模型拉取与推理封装，两者配合天然契合“开箱即用”需求。

操作步骤（全程终端执行，无需 sudo）：

# 1. 安装 Homebrew（若未安装） /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # 2. 安装 Ollama（Homebrew 自动处理 Apple Silicon / Intel 兼容性） brew install ollama # 3. 启动 Ollama 服务（后台常驻，自动开机启动） brew services start ollama # 4. 拉取推荐的代码模型（CodeLlama-7b-Instruct，约 4.2GB，国内源加速） ollama pull codellama:7b-instruct # 5. 验证模型可用性（10 秒内返回响应即成功） ollama run codellama:7b-instruct "写一个 Python 函数，计算斐波那契数列第 n 项"

为什么选这个组合？
Ollama 的设计哲学就是“让本地大模型像curl一样简单”。它内置 HTTP API（默认http://localhost:11434/api/chat），所有 CLI 和 IDE 插件只需调用这个地址即可，完全屏蔽了 GPU 绑定、CUDA 版本、量化格式等复杂细节。Homebrew 则确保了ollama命令全局可用，且升级机制成熟（brew update && brew upgrade ollama即可）。

实测数据（M2 Pro, 32GB RAM）：

安装总耗时：3 分 28 秒（含 Homebrew 安装）
首次ollama pull时间：2 分 15 秒（使用清华源镜像）
ollama run首次响应延迟：1.8 秒（冷启动）→ 后续请求降至 0.3~0.6 秒
内存占用峰值：2.1GB（远低于 llama.cpp 的 3.5GB）

注意事项：

国内用户务必配置 Ollama 镜像源，否则pull极易超时。在~/.ollama/config.json中添加：
```
{ "OLLAMA_ORIGINS": ["https://mirrors.tuna.tsinghua.edu.cn/ollama/"] }
```
若需更高性能模型（如 DeepSeek-Coder-33B），Ollama 会自动启用q4_k_m量化，无需手动转换。

2.2 路径二：Docker Compose（跨平台统一交付，适合团队标准化）

当你的团队包含 Mac、Windows、Linux 开发者，且要求“所有人运行完全一致的 Codex 环境”，Docker 是不可替代的选择。它把模型、推理服务、API 网关、Web UI 打包成单个docker-compose.yml，docker compose up -d一键启动。

核心配置文件docker-compose.yml（实测可用）：

version: '3.8' services: codex-api: image: ghcr.io/ollama/ollama:latest ports: - "11434:11434" volumes: - ./models:/root/.ollama/models - ./data:/root/.ollama/data restart: unless-stopped codex-web: image: ghcr.io/ollama/webui:latest ports: - "3000:8080" depends_on: - codex-api environment: - OLLAMA_BASE_URL=http://codex-api:11434 restart: unless-stopped

部署流程：

创建空目录，放入上述docker-compose.yml；
执行docker compose up -d（首次会拉取镜像，约 5 分钟）；
访问http://localhost:3000，网页端 Codex 即可使用；
CLI 工具直接调用http://localhost:11434/api/chat，无需额外安装客户端。

为什么这是团队首选？

环境一致性：Windows 用户无需折腾 WSL2，Linux 用户不用编译 CUDA，Mac 用户告别 Rosetta 兼容问题；
模型复用：./models目录挂载后，所有容器共享同一份模型文件，pull一次，全环境生效；
隔离安全：模型运行在容器内，与宿主机文件系统完全隔离，杜绝意外读取敏感代码；
可扩展性强：后续增加 Redis 缓存、Prometheus 监控、Nginx 反向代理，只需修改docker-compose.yml。

踩坑实录：
曾有客户在 Windows 上遇到docker compose up后网页打不开。排查发现是 Docker Desktop 默认启用了 WSL2 后端，但未分配足够内存（默认仅 1GB）。解决方案：

打开 Docker Desktop → Settings → Resources → WSL Integration → 勾选当前发行版；
在 WSL2 中执行wsl -l -v确认发行版名称；
编辑C:\Users\<user>\AppData\Local\Packages\...\.wslconfig，添加：
```
[wsl2] memory=4GB processors=2
```

2.3 路径三：Python Pip + llama.cpp（极简嵌入式方案，适合资源受限设备）

如果你的开发机是老旧笔记本（8GB RAM）、树莓派（4GB RAM）或 CI/CD 构建节点（无 GPU），Ollama 的内存占用可能超标。此时llama.cpp是更优解——它纯 C/C++ 实现，支持 CPU 推理，且可通过--n-gpu-layers 1将部分层卸载到集成显卡（Intel Iris Xe / AMD Radeon Vega）。

安装与运行（以 Ubuntu 22.04 为例）：

# 1. 安装编译依赖 sudo apt update && sudo apt install -y build-essential cmake python3-dev # 2. 克隆并编译 llama.cpp（启用 BLAS 加速，提升 CPU 推理速度） git clone https://github.com/ggerganov/llama.cpp cd llama.cpp && make clean && make LLAMA_BLAS=1 LLAMA_BLAS_VENDOR=OpenBLAS -j$(nproc) # 3. 下载量化模型（Q4_K_M 格式，仅 3.7GB，比 FP16 小 60%） mkdir -p models && cd models wget https://huggingface.co/TheBloke/CodeLlama-7B-Instruct-GGUF/resolve/main/codellama-7b-instruct.Q4_K_M.gguf # 4. 启动服务器（HTTP API 兼容 Ollama 格式） cd .. && ./server -m models/codellama-7b-instruct.Q4_K_M.gguf -c 2048 --port 8080

验证 API：

curl -X POST http://localhost:8080/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "codellama-7b-instruct", "messages": [{"role": "user", "content": "用 Python 写一个快速排序"}] }'

关键优势：

内存极致优化：Q4_K_M 模型仅占 3.7GB 内存，比 Ollama 的 4.2GB 降低 12%；
CPU 利用率高：开启 OpenBLAS 后，M2 MacBook Air（8GB）单次推理耗时 2.1 秒，CPU 占用率稳定在 95%；
无依赖污染：不修改系统 Python 环境，pip install仅用于后续 CLI 工具，不影响现有项目。

必须注意的细节：

llama.cpp的server模块默认不支持 streaming，若需 IDE 插件的“逐字输出”效果，需加参数--chat-template chatml并在客户端解析delta.content字段；
模型文件名必须严格匹配gguf后缀，llama.cpp不识别.bin或.safetensors；
若使用 Apple Silicon，编译时加LLAMA_METAL=1可启用 Metal 加速，性能提升 3.2 倍（实测 M2 Max）。

2.4 路径四：VS Code 插件直装（零命令行，IDE 内闭环）

对多数前端/全栈开发者而言，“安装 Codex” 的终极目标不是获得一个 CLI，而是让“提问”动作无缝融入编码流——光标选中一段代码，右键 → “Ask Codex”，答案直接插入编辑器。此时，VS Code 插件是最自然的载体。

推荐插件：CodeWhisperer（AWS）或Tabnine（社区版）的本地化替代方案Continue.dev

Continue.dev是目前唯一真正开源、可完全离线运行、且原生支持自定义模型后端的 VS Code 插件。它不绑定任何云服务，所有配置均在~/.continue/config.json中明文定义。

安装与配置：

VS Code 扩展市场搜索Continue.dev，点击安装；

创建配置文件~/.continue/config.json：

{ "models": [ { "title": "Local Codex", "model": "codellama:7b-instruct", "apiBase": "http://localhost:11434", "apiKey": "" } ], "customCommands": [ { "name": "Explain Code", "description": "Explain the selected code in simple terms", "prompt": "Explain what this code does in simple terms, step by step:\n{{selection}}" } ] }

确保 Ollama 或 llama.cpp 服务已在localhost:11434或localhost:8080运行；
重启 VS Code，选中代码 → 右键 → “Continue: Explain Code”。

为什么它比“Codex 官方插件”更可靠？

无厂商锁定：配置中apiBase可指向任意兼容 OpenAI API 格式的本地服务（Ollama / text-generation-webui / vLLM）；
指令完全可控：prompt字段支持 Jinja2 模板语法，{{selection}}、{{file}}、{{cursor}}等变量自动注入上下文；
调试友好：插件日志输出完整 HTTP 请求/响应，遇到 500 错误可直接复制 curl 命令复现。

实测对比（M1 MacBook Pro）：

功能	Continue.dev	GitHub Copilot（离线模式）	Tabnine（本地模型）
首次响应延迟	1.2s	不支持离线	2.8s
支持自定义模型	✅	❌	✅（需付费版）
右键菜单快捷指令	✅（可自定义）	❌	✅
代码解释准确性	92%	—	85%

注意：不要尝试安装名为 “Codex Assistant” 或 “GitHub Codex” 的插件——这些多为早期废弃项目，最后更新在 2022 年，且不兼容 VS Code 1.85+ 的新 API。

2.5 路径五：离线安装包（断网环境强制要求，军工/金融/医疗场景刚需）

某些封闭网络环境（如银行核心系统开发网段、航天器地面站内网、医院 HIS 系统维护区）严禁设备联网。此时，所有安装必须依赖预下载的离线包。这不是简单的“把文件拷过去”，而是一整套校验、解压、权限修复、服务注册的标准化流程。

离线包构成（以 Codex-Ollama-MacOS 为例）：

ollama-darwin-arm64.tar.gz：Ollama 二进制（Apple Silicon 专用）
codellama-7b-instruct.Q4_K_M.gguf：量化模型文件（3.7GB）
install_offline.sh：自动化安装脚本（含 SHA256 校验、目录创建、服务注册）
config.json：预置镜像源与模型路径

install_offline.sh核心逻辑（经 3 家金融机构验证）：

#!/bin/bash # 步骤1：校验完整性（防止传输损坏） echo "校验 Ollama 二进制..." sha256sum -c ollama-sha256.txt || { echo "Ollama 校验失败"; exit 1; } echo "校验模型文件..." sha256sum -c model-sha256.txt || { echo "模型校验失败"; exit 1; } # 步骤2：解压并安装 tar -xzf ollama-darwin-arm64.tar.gz -C /usr/local/bin/ chmod +x /usr/local/bin/ollama # 步骤3：创建模型目录并复制 mkdir -p ~/.ollama/models/blobs cp codellama-7b-instruct.Q4_K_M.gguf ~/.ollama/models/blobs/ # 步骤4：注册 LaunchDaemon（macOS 后台服务） cp com.ollama.ollama.plist /Library/LaunchDaemons/ launchctl load /Library/LaunchDaemons/com.ollama.ollama.plist

交付物打包规范（甲方验收标准）：

所有文件必须提供.sha256校验文件，且由甲方指定密钥签名（如gpg --clearsign install_offline.sh）；
模型文件必须采用 GGUF 格式（非 HuggingFace 原生格式），因 GGUF 是 llama.cpp/Ollama 的通用交换格式；
安装脚本必须幂等：重复执行不报错、不覆盖已有配置、不重复注册服务；
提供《离线环境适配清单》，明确标注支持的 macOS 版本（12.6+）、最低内存（16GB）、是否需 Rosetta（否）。

血泪教训分享：
某省级医保平台采购 Codex 离线方案，交付时未注明 “需提前安装 Xcode Command Line Tools”。现场安装时ollama报错clang: command not found，导致整个上线延期 3 天。此后我们所有离线包均强制包含xcode-select --install的静默检测脚本，并在 README 首行加粗提示。

3. 四种使用方式：从命令行极客到 IDE 重度用户的全场景覆盖

安装只是起点，真正决定 Codex 价值的是它如何融入你的每日开发流。以下四种方式，按“介入深度”与“自动化程度”递进排列，每种都给出真实工作流中的触发时机、输入范式、输出处理技巧及避坑点。

3.1 方式一：CLI 基础问答（终端里的“代码版 Siri”）

这是最原子化的使用方式——在终端中输入一句话，获取一段可执行代码或解释。它不依赖 IDE，不启动 GUI，适合快速验证想法、生成脚本片段、理解陌生命令。

典型工作流：

场景：正在写一个部署脚本，需要解析 JSON 并提取字段；
操作：codex-cli ask "从 curl 响应中提取 JSON 的 'id' 和 'status' 字段，用 Bash 实现"；
输出：一段带注释的jq命令，可直接复制粘贴。

codex-cli工具链构建（推荐用 Rust 编写，性能与安全性兼顾）：

// src/main.rs（核心逻辑） use reqwest::Body; use serde_json::json; #[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> { let args: Vec<String> = std::env::args().collect(); if args.len() < 3 { panic!("Usage: codex-cli ask <question>"); } let question = &args[2..].join(" "); let client = reqwest::Client::new(); // 调用本地 Ollama API（兼容性最强） let res = client.post("http://localhost:11434/api/chat") .json(&json!({ "model": "codellama:7b-instruct", "messages": [{ "role": "user", "content": format!("You are a senior developer. Answer concisely. {}", question) }] })) .send() .await?; let text = res.text().await?; println!("{}", extract_response(&text)); // 解析 JSON 响应中的 message.content Ok(()) }

编译与安装：

# 1. 安装 Rust（macOS） curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # 2. 编译为静态二进制（无运行时依赖） cargo build --release # 3. 拷贝到 PATH sudo cp target/release/codex-cli /usr/local/bin/

为什么不用 Shell 脚本？

Shell 脚本无法优雅处理流式响应（Ollama 的stream: true返回多个 JSON 块）；
Rust 的reqwest库自动重试、连接池、超时控制远超curl；
静态编译后codex-cli单文件仅 8.2MB，可直接分发给无 Rust 环境的同事。

实战技巧：

精准控制输出格式：在提问末尾加 “Output only valid JSON, no explanation”，避免模型返回 Markdown；
利用上下文缓存：codex-cli context add --file utils.py将常用工具函数加入知识库，后续提问自动引用；
错误诊断：当返回{"error":"model not found"}，立即执行ollama list确认模型名称是否拼写正确（注意大小写与冒号）。

3.2 方式二：Git 集成（让代码审查自动化）

Codex 最被低估的能力，是作为 Git 的“智能钩子”。它能在git commit前自动检查代码质量，在git push时生成专业级 PR 描述，在git blame时解释某行代码的历史意图。

核心实现：Git Hooks + Codex CLI
在项目根目录创建.git/hooks/pre-commit：

#!/bin/bash # 检查本次提交是否修改了 Python 文件 CHANGED_PY=$(git diff --cached --name-only | grep "\.py$") if [ -z "$CHANGED_PY" ]; then exit 0 fi echo "🔍 Codex 正在分析 Python 更改..." for file in $CHANGED_PY; do # 提取变更内容（diff 格式） DIFF_CONTENT=$(git diff --cached "$file" | head -50) # 调用 Codex 评估风险 RESULT=$(codex-cli ask "Analyze this Python diff for security and performance issues:\n$DIFF_CONTENT" 2>/dev/null) if echo "$RESULT" | grep -q "SQL injection\|N+1 query\|hardcoded password"; then echo "❌ Codex 发现高危问题：" echo "$RESULT" | head -10 echo "请修复后重新提交" exit 1 fi done

post-merge钩子：自动同步文档
当团队合并main分支后，自动更新README.md中的 API 列表：

#!/bin/bash # .git/hooks/post-merge if git rev-parse --abbrev-ref HEAD | grep -q "main"; then echo "📝 Codex 正在更新 API 文档..." # 从 src/api/ 目录提取所有 @route 注释，生成 Markdown 表格 API_DOCS=$(find src/api -name "*.py" -exec grep -o "@route.*" {} \; | \ codex-cli ask "Convert these Flask route decorators to a Markdown table with columns: Path, Method, Description") sed -i '' "/## API Reference/,/^##/c\\ ## API Reference\n\n$API_DOCS\n" README.md fi

为什么 Git 集成比 IDE 插件更强大？

强制执行：钩子在服务器端运行（如 GitLab CI），确保所有成员遵守规则；
跨语言通用：不依赖特定 IDE，Java/Python/Go 项目共用同一套逻辑；
可审计：每次git log -g可追溯 Codex 生成的文档修改记录。

血泪教训：
某电商公司启用pre-commit钩子后，CI 流水线频繁失败。排查发现是 Codex 响应超时（默认 30 秒），而 CI 节点网络策略限制了localhost:11434访问。解决方案：

在 CI 配置中禁用钩子：git config --local core.hooksPath /dev/null；
改用post-receive钩子，在 Git 服务器上运行（需部署 Ollama 服务）。

3.3 方式三：VS Code 插件深度定制（超越“右键提问”的工作流再造）

Continue.dev插件的价值，远不止于右键菜单。通过编写customCommands，你可以将 Codex 变成专属的“开发助理”，接管整个模块的生命周期。

案例：React 组件全自动创建
在~/.continue/config.json中添加：

{ "customCommands": [ { "name": "Create React Component", "description": "Generate a new React component with hooks, tests, and storybook", "prompt": "Create a React functional component named '{{input}}' that:\n- Uses TypeScript\n- Includes useState and useEffect hooks\n- Has unit tests using Vitest\n- Includes Storybook stories\n- Follows our design system (Chakra UI)\n\nFile structure:\nsrc/components/{{input}}/\n├── {{input}}.tsx\n├── {{input}}.test.tsx\n└── {{input}}.stories.tsx\n\nOutput only the full file content, no explanations." } ] }

使用流程：

按Cmd+Shift+P→ 输入 “Create React Component”；
输入组件名UserProfileCard；
Codex 生成三个文件内容，自动在 VS Code 中打开新标签页；
按Cmd+S保存，文件即写入磁盘。

进阶技巧：结合 VS Code 变量
VS Code 提供editorLangId、workspaceFolder等上下文变量，可在 prompt 中动态注入：

"prompt": "Generate a {{editorLangId}} script to deploy the current project ({{workspaceFolder}}) to AWS ECS. Use the latest best practices."

避坑指南：

避免无限循环：不要在customCommand中调用会触发该命令的操作（如 “Save file” 后自动运行命令）；
超时设置：在config.json中添加"timeout": 120，防止大模型卡死阻塞编辑器；
敏感信息过滤：启用Continue.dev的redact功能，自动屏蔽password=、token=等字符串。

3.4 方式四：CI/CD 流水线嵌入（让 Codex 成为构建环节的守门人）

将 Codex 接入 CI/CD，是将其价值放大的终极形态。它不再是个体效率工具，而是团队级的质量网关。

GitHub Actions 示例（.github/workflows/codex-review.yml）：

name: Codex Code Review on: [pull_request] jobs: review: runs-on: ubuntu-22.04 steps: - uses: actions/checkout@v4 with: ref: ${{ github.head_ref }} - name: Setup Ollama run: | curl -fsSL https://ollama.com/install.sh | sh ollama pull codellama:7b-instruct - name: Run Codex Review id: codex run: | # 提取 PR 中的新增/修改代码 CHANGED_FILES=$(git diff --name-only ${{ github.base_ref }} ${{ github.head_ref }} | grep "\.py$\|\.js$") for file in $CHANGED_FILES; do echo "🔍 Analyzing $file..." # 用 Codex 生成代码审查意见 COMMENT=$(curl -s -X POST http://localhost:11434/api/chat \ -H "Content-Type: application/json" \ -d "{\"model\":\"codellama:7b-instruct\",\"messages\":[{\"role\":\"user\",\"content\":\"Review this Python code for bugs, security issues, and style violations. Be concise. File: $file\\n$(cat $file | head -30)\"}]}") # 提取 review comment（简化版） if echo "$COMMENT" | jq -r '.message.content' | grep -q "security\|bug\|vulnerability"; then echo "REVIEW_COMMENT<<EOF" >> $GITHUB_ENV echo "### Codex Review for $file" >> $GITHUB_ENV echo "$(echo "$COMMENT" | jq -r '.message.content')" >> $GITHUB_ENV echo "EOF" >> $GITHUB_ENV break fi done - name: Post Review Comment if: env.REVIEW_COMMENT != '' uses: marocchino/sticky-pull-request-comment@v2 with: header: codex-review message: ${{ env.REVIEW_COMMENT }}

为什么 CI 集成不可替代？

客观性：Codex 不会因“同事关系”降低审查标准，对 CEO 提交的代码同样严格；
可追溯：每次 PR 的 Codex 评论永久留存，成为代码演进的“第二份日志”；
持续进化：当团队更新codellama:13b模型，所有 PR 自动获得更强审查能力，无需修改任何配置。

性能优化关键点：

模型预热：在Setup Ollama步骤后加ollama run codellama:7b-instruct "hi"，触发模型加载，避免首次api/chat超时；
范围收敛：git diff --name-only限制只分析变更文件，而非整个仓库；
降级策略：添加timeout 60s包裹 Codex 调用，超时则跳过，不阻塞主流程。

4. 关键决策树：根据你的角色与场景，5 秒锁定最优方案

面对五种安装方式、四种使用方式，新手常陷入“选择困难”。这里提供一张基于真实项目经验提炼的决策树，帮你 5 秒内锁定最适合的路径。它不讲理论，只问三个问题，每个答案对应明确动作。

4.1 问题一：你的主要开发环境是？

✅ Mac（Apple Silicon M1/M2/M3）→ 选路径一：Homebrew + Ollama
理由：Homebrew 对 ARM64 支持最完善，Ollama 的 Metal 加速让 7B 模型在 8GB 内存机器上流畅运行。实测 M1 MacBook Air（8GB）跑codellama:7b-instruct平均延迟 1.4 秒，全程无卡顿。
行动指令：复制brew install ollama && ollama pull codellama:7b-instruct，回车执行。
✅ Windows（非 WSL2 用户）→ 选路径二：Docker Compose
理由：Docker Desktop for Windows 已原生支持 Hyper-V，无需折腾 WSL2 内核。docker compose up启动后，http://localhost:3000网页版 Codex 即可用，CLI 工具调用localhost:11434。
行动指令：安装 Docker Desktop → 新建docker-compose.yml→docker compose up -d。
✅ Linux（服务器/CI 节点）→ 选路径三：Python Pip + llama.cpp
理由：服务器通常无 GUI，llama.cpp的server模块提供轻量 HTTP API，内存占用比 Ollama 低 15%，且make编译过程可控（可禁用 CUDA）。
行动指令：sudo apt install build-essential && git clone https://github.com/ggerganov/llama.cpp && cd llama.cpp && make。
✅ 断网环境（金融/军工/医疗）→ 选路径五：离线安装包
理由：离线包含完整校验机制，install_offline.sh自动处理权限、服务注册、路径配置，符合等保三级对“软件供应链安全”的要求。
行动指令：向供应商