第一章环境准备在开始配置之前需要确保开发环境满足以下基本要求。1.1 系统要求操作系统版本要求备注WindowsWindows 10/1164-bitCLI 建议使用 WSL2插件方式直接支持macOS11Big Sur或更高版本支持 Apple SiliconM1/M2/M3和 IntelLinux主流发行版Ubuntu 20.04、Debian 11等完整支持1.2 VS Code 版本要求VS Code1.85.0 或更高版本建议升级至最新稳定版从 code.visualstudio.com 下载安装1.3 Node.js 环境准备Codex CLI 官方推荐使用 Node.js 环境进行安装确保设备上已安装Node.js 18.x 或更高版本建议使用 22 以获得更好的兼容性。安装完成后验证环境bashnode --version npm --version1.4 Python 环境准备API 调用方式可选若计划通过 Python 脚本直接调用 OpenAI API需安装Python 3.7 或更高版本推荐使用虚拟环境venv 或 conda隔离依赖项。bash# 创建虚拟环境可选但推荐 python -m venv codex-env source codex-env/bin/activate # Linux/macOS codex-env\Scripts\activate # Windows # 安装依赖 pip install openai python-dotenv1.5 网络环境检查由于 OpenAI API 服务位于海外国内用户可能需要配置代理。请在继续之前确认网络连通性。第二章获取 API Key无论通过何种方式使用 CodexAPI Key 都是必须的凭证。本章详细说明获取流程。2.1 注册 OpenAI 账户访问 OpenAI 官网点击右上角“Sign up”进行注册使用电子邮件地址注册完成邮箱验证根据提示完成手机号验证部分国家/地区可能受限2.2 获取 API Key登录后点击页面右上角头像选择“View API keys”进入 API Keys 管理页面后点击“Create new secret key”为 Key 命名建议使用有意义的名称如codex-vscode选择适当的权限级别全功能即可立即复制并保存 API Key——OpenAI 不会再次显示完整 Key获取到 API Key 后将其保存在安全位置并记录用于后续配置。2.3 确保账户具备模型访问权限Codex 及相关 GPT 模型的访问权限取决于账户类型免费试用账户通常提供有限额度的 API 调用如 $5 初始额度可直接用于测试付费账户需绑定支付方式按使用量计费。建议先充值 $5-10 作为启动资金ChatGPT Plus/Pro 订阅用户在 CLI 中可选择 ChatGPT OAuth 登录方式直接调用账户权益⚠️重要提示OpenAI 官方已不再独立提供“Codex”命名模型的单独下载。Codex 的核心能力已整合进 GPT-3.5 Turbo、GPT-4 及 GPT-5 系列模型中。因此当前使用 Codex CLI、插件或 API 实际调用的是这些更强大的新一代模型。第三章接入路径选择与快速决策Codex 与 VS Code 的集成有多种方式本章帮助用户根据自身情况快速选择最适合的路径。3.1 四种接入路径横向对比接入方式开发体验配置复杂度集成深度适合人群成本官方 VS Code 插件⭐⭐⭐⭐⭐⭐低原生集成追求最简单开箱即用的开发者API 按量计费Codex CLI 终端代理⭐⭐⭐⭐⭐⭐中低终端交互 VS Code 联动习惯命令行的开发者、CI/CD 场景API 按量计费Continue 插件 本地模型⭐⭐⭐⭐⭐⭐⭐中代码补全 对话注重隐私、追求零月费的开发者免费Python API 脚本开发⭐⭐⭐⭐⭐⭐高完全自定义希望深度定制功能的开发者API 按量计费3.2 快速决策指南 如果你是新手追求最简单开箱即用直接选择方式一官方 VS Code 插件。在 VS Code 扩展商店搜索安装后填入 API Key 即可使用无需任何额外配置。 如果你是命令行重度用户选择方式二Codex CLI。在终端中运行codex 你的需求即可让 AI 直接操作项目文件。 如果你注重隐私或预算有限选择方式三Continue 插件 本地模型。完全在本地运行数据不离开电脑长期使用零成本。 如果你需要深度定制选择方式四Python API 脚本。自行编写脚本实现对 API 的完全控制。第四章方式一——官方 VS Code 插件安装与配置这是最简单、最直接的接入方式适合追求快速上手的新手用户。4.1 安装 Codex VS Code 插件打开 VS Code点击左侧活动栏的扩展图标或按CtrlShiftX在搜索框中输入Codex – OpenAI’s coding agent或openai.chatgpt找到官方插件后点击Install安装等待安装完成VS Code 会提示重启或自动激活插件如果搜索不到请直接从 VS Code Marketplace 访问openai.chatgpt页面进行安装。4.2 全局配置文件结构Codex 的所有配置均基于两个核心文件config.toml和.env或auth.json。这是理解 Codex 配置逻辑的关键。config.toml主配置文件定义模型服务商、接口地址、模型名称、运行规则、安全权限等所有核心行为使用TOML 格式编写.env/auth.json存储 API 密钥、OAuth 登录令牌等敏感凭证是工具连通服务的核心配置文件存放路径根据操作系统不同有所差异操作系统配置目录路径Windows%USERPROFILE%\.codex\macOS~/.codex/Linux~/.codex/4.3 配置 API Key完成插件安装后需要进行 API Key 配置。方法一通过 VS Code 设置界面配置在 VS Code 中按Ctrl,Windows/Linux或Cmd,macOS打开设置在搜索框中输入Codex或OpenAI找到 API Key 配置项粘贴你的 API Key保存设置重启 VS Code方法二通过配置文件手动配置推荐更可控创建config.toml文件toml# 默认使用的模型 model gpt-4o # 或 gpt-4-turbo、gpt-3.5-turbo # 模型提供商 model_provider openai # 上下文窗口大小token数 model_context_window 128000 # 推理强度minimal | low | medium | high | xhigh model_reasoning_effort medium # 沙箱模式read-only | workspace-write | danger-full-access sandbox_mode workspace-write # 审批策略on-request | on-failure | never approval_policy on-request # 允许网络访问在workspace-write模式下 [sandbox_workspace_write] network_access true # 定义OpenAI提供商 [model_providers.openai] name OpenAI Official base_url https://api.openai.com/v1 env_key OPENAI_API_KEY创建.env文件envOPENAI_API_KEYsk-你的实际API密钥⚠️安全提醒绝对禁止将包含 API Key 的配置文件提交到 Git 等代码仓库。确保在.gitignore中添加.codex/和.env规则。4.4 插件使用入门配置完成后重启 VS Code打开Codex 侧边栏如果未自动显示点击左侧活动栏中的 Codex 图标在侧边栏对话框中输入自然语言指令如用 Python 写一个快速排序函数解释这段代码的功能帮我重构这个函数使其更简洁插件会自动理解上下文当前打开的文件内容、光标位置等并生成相应结果。4.5 故障排查插件不生效如果安装后插件未正常响应请按以下顺序排查检查 API Key 是否有效使用 curl 直接测试将your-key替换为实际 Keybashcurl https://api.openai.com/v1/models -H Authorization: Bearer your-key如果返回 401 错误说明 Key 无效检查环境变量是否正确加载确保.env文件中的变量名与config.toml中env_key完全一致大小写和拼写必须一字不差重启 VS Code配置文件修改后必须重启 VS Code 才能生效查看 VS Code 输出面板选择 Codex 插件的输出通道查看具体错误日志第五章方式二——Codex CLI 终端代理安装与配置Codex CLI 是 OpenAI 官方推出的开源本地编码代理底层基于Rust构建能够在终端中直接读取代码上下文、修改文件甚至执行终端命令。与 VS Code 联动的核心思想是CLI 作为“大脑”理解任务和操作文件VS Code 作为“眼睛和手”实时展示变化两者协同完成 AI 编程。5.1 安装 Codex CLI推荐方式通过 npm 全局安装跨平台bashnpm install -g openai/codexWindows 用户注意CLI 在 Windows 上目前仍处于实验性阶段强烈建议在 WSL2Windows Subsystem for Linux中安装 Node.js npm 后再运行或者优先使用 VS Code 扩展方式。macOS 可选方式通过 Homebrew 一键安装bashbrew install --cask codex验证安装bashcodex --version如果正确输出版本号说明安装成功。5.2 认证与登录安装完成后Codex CLI 支持两种认证方式请根据自身情况选择。方法一ChatGPT OAuth 登录推荐有订阅的用户直接运行codexCLI 默认会唤起浏览器进入 ChatGPT 登录流程。授权成功后凭据会缓存在本地~/.codex/auth.json后续使用无需重复登录。方法二API Key 环境变量注入推荐使用量计费的开发者bash# macOS/Linux export OPENAI_API_KEY你的OpenAI_API_Key codex # Windows PowerShell $env:OPENAI_API_KEY你的OpenAI_API_Key codex如需永久生效将上述 export 命令添加到~/.bashrc、~/.zshrcmacOS/Linux或通过 Windows 系统环境变量面板设置。5.3 基础使用与 VS Code 联动场景一在终端直接使用bash# 进入项目目录 cd /path/to/your/project # 启动交互模式最常用 codex # 或者在启动时直接下达指令 codex 帮我写一个计算斐波那契数列的 Python 函数场景二与 VS Code 联动——核心操作链路这是本文的重点。Codex CLI 与 VS Code 的联动并不需要安装任何特殊连接插件而是通过以下工作流实现无缝协作步骤操作说明① 终端启动 CLI在项目根目录运行codexCLI 读取整个项目目录的代码上下文② 下达任务指令在终端输入自然语言需求例如“读取当前目录下的app.py为其中的函数添加类型注解”③ CLI 执行操作CLI 自动分析、修改文件修改会直接写入磁盘同步至 VS Code④ VS Code 实时显示VS Code 自动检测文件变化无需额外操作修改内容即时显示在编辑器中⑤ 手动确认在 VS Code 中审查和微调 AI 生成的代码形成“AI 生成 → 人工审查”的协作闭环这种“CLI 操作 VS Code 显示”的联动方式实现了 AI 编程助手在不离开终端的前提下完成从原型到部署的完整编码流程。场景三设置 VS Code 快捷键调用 Codex为提升联动效率可以在 VS Code 中创建任务用快捷键直接调用 Codex在项目根目录创建.vscode/tasks.json添加以下内容json{ version: 2.0.0, tasks: [ { label: Codex: 生成代码, type: shell, command: codex -p \${selectedText}\, group: none, presentation: { reveal: always, panel: new }, problemMatcher: [] }, { label: Codex: 解释代码, type: shell, command: codex -p \解释以下代码的功能\\n${selectedText}\, group: none } ] }为任务绑定快捷键CtrlK CtrlS打开快捷键设置搜索Run Task为Codex: 生成代码绑定CtrlShiftG等快捷键5.4 配置文件详解config.toml是 CLI 的核心配置文件以下几类常见配置场景供参考场景一基础 OpenAI 官方配置tomlmodel gpt-4o model_provider openai model_context_window 128000 model_reasoning_effort medium sandbox_mode workspace-write approval_policy on-request [model_providers.openai] name OpenAI Official base_url https://api.openai.com/v1 env_key OPENAI_API_KEY场景二通过网关/代理中转加速国内访问tomlmodel gpt-4o model_provider custom-gateway # 使用自定义提供商名称 model_reasoning_effort high [model_providers.custom-gateway] name My Gateway base_url https://your-gateway.com/v1 env_key OPENAI_API_KEY wire_api responses场景三开启更自主的审批模式approval_policy字段控制 CLI 执行敏感操作如写入文件、访问网络前是否需要用户确认on-request默认每项操作都需要用户确认安全性最高on-failure操作失败时才询问适合较为熟练的用户never完全自动执行风险极高强烈不推荐除非在完全隔离的沙箱环境中使用5.5 项目级配置 vs 全局配置Codex CLI 支持两套配置体系仅文件存放路径不同配置格式和语法完全通用配置类型存放路径作用范围优先级全局配置~/.codex/macOS/Linux或%USERPROFILE%\.codex\Windows本机所有 Codex 调用通用一次配置终身可用低可被项目级配置覆盖项目级配置项目根目录./.codex/仅当前项目目录内生效完全隔离其他项目高无条件覆盖全局配置配置优先级黄金法则命令行临时参数 Profile 配置档案 项目级配置 全局配置 系统环境变量 内置默认值。越靠近执行目录的配置优先级越高。5.6 沙箱安全配置Codex CLI 使用本地沙箱控制来限制文件系统和网络访问这是保护电脑安全的重要机制。sandbox_mode字段的安全等级说明模式文件系统权限网络访问适用场景read-only只读无法修改文件需单独配置仅用于分析代码的场景workspace-write推荐可在工作区内修改文件默认禁用需手动[sandbox_workspace_write] network_access true开启日常开发平衡安全与效率danger-full-access无限制无限制⚠️ 仅限完全隔离的沙箱环境5.7 安装故障排查问题一安装失败npm 报错检查 Node.js 版本是否符合要求≥ v22尝试清空 npm 缓存npm cache clean --force如果网络问题切换国内镜像源问题二API Key 无效401 错误90% 的 401 报错集中在 Key 格式/来源错误、账号权限不足、环境变量未正确加载三大类用 curl 直接测试是最快的诊断手段问题三Windows 兼容性问题目前 Windows 原生 CLI 仍处于实验性阶段强烈建议在WSL2中安装 Node.js npm 后再运行 CLI第六章方式三——第三方插件Continue Ollama本地化配置如果你注重代码隐私——不希望代码被发送到云端——或者没有 OpenAI API Key 但想零成本体验 AI 编程这一章的内容将非常适用。本方案的核心组件是ContinueVS Code 插件 Ollama本地模型运行工具实现完全本地化的 AI 编程助手。6.1 为什么选择完全本地化方案隐私保护代码完全不离开电脑特别适合处理敏感代码的企业开发场景零月费本地模型无按量计费长期使用成本为零无需网络在无互联网连接的环境下也可使用真实预期本地模型7B-16B 参数范围在复杂架构推理、跨文件重构等任务上能力弱于 GPT-4o但对于行内补全、样板代码生成、标准框架模式等日常开发场景完全够用。6.2 安装 Ollama 和 Continue 插件步骤一安装 OllamaOllama 是运行本地大语言模型的核心工具。Windows/macOS/Linux 均支持访问 ollama.com/download 下载对应版本安装完成后在终端执行以下命令拉取编码模型bash# 拉取 Qwen2.5-Coder 系列推荐中文支持好 ollama pull qwen2.5-coder:7b # 或拉取 DeepSeek-Coder-V2代码生成能力较强 ollama pull deepseek-coder-v2:16b # 如硬件足够可拉取 Qwen3-Coder-Next 更大模型 ollama pull qwen3.5:35b-a3b-coding-nvfp4拉取模型需要一定时间等待完成即可。步骤二安装 Continue 插件打开 VS Code进入扩展商店CtrlShiftX搜索Continue发布者Continue点击Install安装等待完成安装后VS Code 左侧会出现 Continue 图标类似对话气泡6.3 配置 Continue 连接本地 Ollama方法一通过 Continue 配置界面推荐点击 VS Code 左侧的 Continue 图标在打开的界面中点击设置齿轮图标选择“Add chat model”→“Ollama”输入模型名称如qwen2.5-coder:7b和本地 API 地址默认http://localhost:11434保存配置方法二手动编辑配置文件Continue 的配置文件位于Windows:%APPDATA%\Continue\config.jsonmacOS/Linux:~/.continue/config.json在配置文件中添加以下内容json{ models: [ { title: Qwen2.5-Coder, provider: ollama, model: qwen2.5-coder:7b, apiBase: http://localhost:11434 } ], tabAutocompleteModel: { title: Qwen2.5-Coder, provider: ollama, model: qwen2.5-coder:7b } }6.4 使用 Continue 实现 AI 编程配置完成后在 VS Code 中可以通过以下方式使用代码补全在编辑器中编写代码时Continue 会自动提供实时的行内代码建议对话式编程选中任意代码块 → 右键 →“Continue”或直接按CtrlImacOSCmdI打开对话面板快速指令在对话面板中输入需求如解释这段代码的功能为这个函数生成单元测试帮我找出这段代码中的性能问题Continue 插件在 VS Code Marketplace 的安装量已超过 300 万是目前 GitHub Copilot 最受欢迎的免费替代方案之一。6.5 进阶连接 Codex CLI 到本地 Ollama完全本地化如果你希望同时拥有 Codex CLI 的强大功能又想完全本地运行可以通过以下配置实现。步骤一启动 Ollama 的 OpenAI 兼容 API 服务Ollama 默认监听http://localhost:11434并提供了与 OpenAI API 完全兼容的/v1端点。步骤二配置 Codex CLI 指向本地 Ollama编辑~/.codex/config.tomltomlmodel qwen2.5-coder:7b # 或你拉取的其他模型 model_provider ollama model_context_window 32768 sandbox_mode workspace-write approval_policy on-request [model_providers.ollama] name Ollama Local base_url http://localhost:11434/v1 wire_api chat_completions env_key NO_KEY # 本地模型无需 API Key步骤三验证连通性bash# 确认 Ollama 服务正常 curl http://localhost:11434/api/version # 启动 Codex CLI它会使用本地模型 codex 用 Python 写一个单例模式的实现如果遇到网络连通问题可能需要将 Ollama 服务暴露到容器可视的地址特别是在使用 Docker 或容器化工具时。使用curl http://192.168.64.1:11434/api/version测试若失败需调整网络配置。第七章方式四——Python API 脚本开发高级定制如果你需要深度定制 AI 编程助手的行为——例如集成到公司内部工具链、批量处理代码文件或实现特定的代码生成逻辑——可以自行编写调用 OpenAI API 的 Python 脚本。适用场景团队统一 AI 助手配置、批量代码处理、CI/CD 流程中的自动代码审查。7.1 基础脚本模板创建codex_api.pypythonimport openai import os from dotenv import load_dotenv # 加载环境变量 load_dotenv() openai.api_key os.getenv(OPENAI_API_KEY) def generate_code(prompt: str, max_tokens: int 500) - str: 调用 OpenAI API 生成代码 try: response openai.Completion.create( modelgpt-4o, # 或 gpt-3.5-turbo promptprompt, max_tokensmax_tokens, temperature0.5, # 值越低越保守值越高越有创造力 top_p0.9 ) return response.choices[0].text.strip() except Exception as e: print(fAPI 调用失败: {e}) return def explain_code(code: str) - str: 解释选中的代码 prompt f请解释以下代码的功能和逻辑\n{code} return generate_code(prompt, max_tokens800) if __name__ __main__: user_prompt input(请输入代码需求: ) result generate_code(user_prompt) print(\n生成的代码:\n) print(result)7.2 与 VS Code 集成绑定快捷键调用脚本在项目根目录创建.vscode/tasks.json添加任务配置json{ version: 2.0.0, tasks: [ { label: Codex API: 生成代码, type: shell, command: cd ${workspaceFolder} python codex_api.py, group: none } ] }通过CtrlShiftP→Run Task或设置快捷键调用通过 VS Code 代码片段功能复用生成结果将 Codex 生成的常用代码保存为 VS Code 用户片段File→Preferences→Configure User Snippets添加自定义片段模板提升重复使用效率。7.3 调试与优化建议错误处理捕获 API 调用异常如速率限制、无效请求添加重试逻辑参数调优调整max_tokens和temperature参数来控制生成代码的长度和多样性缓存高频结果对常用代码模式使用本地缓存减少重复调用降低延迟日志记录记录 API 调用情况便于排查问题第八章代理配置国内用户必读由于 OpenAI API 服务位于海外国内用户常遇到连接问题。本章提供完整的代理配置方案。8.1 代理配置方式方法一通过系统环境变量配置推荐覆盖范围最广bash# macOS/Linux export HTTP_PROXYhttp://127.0.0.1:7890 export HTTPS_PROXYhttp://127.0.0.1:7890 # Windows PowerShell $env:HTTP_PROXYhttp://127.0.0.1:7890 $env:HTTPS_PROXYhttp://127.0.0.1:7890将上述命令添加到~/.bashrc、~/.zshrc或 Windows 系统环境变量中即可永久生效。方法二通过 VS Code 设置代理打开 VS Code 设置Ctrl,搜索proxy在Http: Proxy设置中输入代理地址如http://127.0.0.1:7890保存后重启 VS Code方法三通过 Codex config.toml 配置代理如果 API 请求需要通过特定代理网关可在config.toml中配置自定义base_url指向代理地址参考 5.4 节的网关配置示例。8.2 代理故障排查症状可能原因解决方法API 请求超时代理未生效或代理服务未启动确认代理软件正在运行验证环境变量是否正确设置认证失败代理修改了请求头尝试使用透明代理模式或更换代理服务部分请求失败代理分流规则不完整确保 OpenAI API 相关域名api.openai.com已纳入代理规则8.3 第三方 API 网关推荐对于国内开发者使用Crazyrouter等统一 API 网关是一个更为稳定的选择。这类网关提供以下优势无需自建代理直接接入国内可访问的 API 端点统一对接多个模型GPT、Claude、DeepSeek、Gemini 等按需切换计费和接入更加灵活配置方法参考 5.4 节“通过网关/代理中转”的config.toml模板将base_url指向网关提供的地址即可。第九章安全与最佳实践9.1 API Key 安全管理绝对禁止将 API Key 硬编码在代码中或以明文提交到 Git 仓库使用dotenv管理环境变量并在.gitignore中添加.env和.codex/定期轮换 API Key最小化泄露风险生产环境优先使用环境变量注入密钥9.2 沙箱安全配置日常开发建议使用sandbox_mode workspace-write配合approval_policy on-request除非在完全隔离的沙箱环境中否则永远不要使用danger-full-access定期审查 AI 对代码的修改确保不会引入安全漏洞9.3 代码审查与质量控制AI 模型可能会产生幻觉hallucinate并生成错误或不安全的代码。始终在使用前对生成的结果进行人工审查。尤其注意检查生成的代码是否包含硬编码的敏感信息确认生成的 SQL 查询是否存在注入风险验证生成的认证逻辑是否符合安全规范第十章常见问题与故障排查Q1安装 VS Code 插件时搜索不到 Codex访问 VS Code Marketplace 直接搜索openai.chatgpt进行安装或检查 VS Code 版本是否低于 1.85.0。Q2API 调用返回 401 错误90% 的情况是因为 Key 格式/来源错误、账号权限不足或环境变量未正确加载。先用 curl 快速诊断bashcurl https://api.openai.com/v1/models -H Authorization: Bearer 你的API_KEY如果返回 401说明 Key 无效。Q3Codex CLI 安装后运行提示“command not found”确认 npm 全局安装的 bin 目录已添加到系统 PATH 中尝试重新打开终端窗口检查 Node.js 版本是否符合要求Q4代理已配置但仍然无法连接确认代理软件正在运行尝试直接使用curl -x http://127.0.0.1:7890 https://api.openai.com/v1/models测试如果使用第三方网关请确认网关提供的base_url是否正确Q5本地 Ollama Codex CLI 配置后无法连接确认 Ollama 服务已启动curl http://localhost:11434/api/version检查config.toml中的base_url是否包含/v1后缀如果使用 Docker/容器工具可能需要将 Ollama 暴露到容器网络的可见地址Q6Codex CLI 认证机制不兼容Codex CLI 认证机制在版本迭代中多次变更当前最新版 v0.130.02026-05-08。建议确保 Codex CLI 已更新到最新版本npm update -g openai/codex如果使用旧的 API Key 格式无效尝试重新生成新的 API Key或切换到 ChatGPT OAuth 登录方式第十一章官方参考文档链接以下为官方文档链接供深入学习和查阅Codex CLI GitHub 官方仓库——源码、更新日志和详细使用说明Codex 配置基础——config.toml完整配置参考Codex IDE 扩展文档——VS Code 插件官方文档沙箱安全机制——深入了解 Codex 的安全机制代理审批与安全策略——approval_policy的详细说明结语本指南系统地介绍了 OpenAI Codex 与 VS Code 集成的四种核心方案。从最简单的官方插件一键安装到终端代理 CLI 的深度使用再到完全本地化的隐私优先方案和面向企业级定制的 API 开发——无论你处于哪个阶段都能找到最适合自己的配置路径。
Codex 安装与 VS Code 联动：手把手配置指南
第一章环境准备在开始配置之前需要确保开发环境满足以下基本要求。1.1 系统要求操作系统版本要求备注WindowsWindows 10/1164-bitCLI 建议使用 WSL2插件方式直接支持macOS11Big Sur或更高版本支持 Apple SiliconM1/M2/M3和 IntelLinux主流发行版Ubuntu 20.04、Debian 11等完整支持1.2 VS Code 版本要求VS Code1.85.0 或更高版本建议升级至最新稳定版从 code.visualstudio.com 下载安装1.3 Node.js 环境准备Codex CLI 官方推荐使用 Node.js 环境进行安装确保设备上已安装Node.js 18.x 或更高版本建议使用 22 以获得更好的兼容性。安装完成后验证环境bashnode --version npm --version1.4 Python 环境准备API 调用方式可选若计划通过 Python 脚本直接调用 OpenAI API需安装Python 3.7 或更高版本推荐使用虚拟环境venv 或 conda隔离依赖项。bash# 创建虚拟环境可选但推荐 python -m venv codex-env source codex-env/bin/activate # Linux/macOS codex-env\Scripts\activate # Windows # 安装依赖 pip install openai python-dotenv1.5 网络环境检查由于 OpenAI API 服务位于海外国内用户可能需要配置代理。请在继续之前确认网络连通性。第二章获取 API Key无论通过何种方式使用 CodexAPI Key 都是必须的凭证。本章详细说明获取流程。2.1 注册 OpenAI 账户访问 OpenAI 官网点击右上角“Sign up”进行注册使用电子邮件地址注册完成邮箱验证根据提示完成手机号验证部分国家/地区可能受限2.2 获取 API Key登录后点击页面右上角头像选择“View API keys”进入 API Keys 管理页面后点击“Create new secret key”为 Key 命名建议使用有意义的名称如codex-vscode选择适当的权限级别全功能即可立即复制并保存 API Key——OpenAI 不会再次显示完整 Key获取到 API Key 后将其保存在安全位置并记录用于后续配置。2.3 确保账户具备模型访问权限Codex 及相关 GPT 模型的访问权限取决于账户类型免费试用账户通常提供有限额度的 API 调用如 $5 初始额度可直接用于测试付费账户需绑定支付方式按使用量计费。建议先充值 $5-10 作为启动资金ChatGPT Plus/Pro 订阅用户在 CLI 中可选择 ChatGPT OAuth 登录方式直接调用账户权益⚠️重要提示OpenAI 官方已不再独立提供“Codex”命名模型的单独下载。Codex 的核心能力已整合进 GPT-3.5 Turbo、GPT-4 及 GPT-5 系列模型中。因此当前使用 Codex CLI、插件或 API 实际调用的是这些更强大的新一代模型。第三章接入路径选择与快速决策Codex 与 VS Code 的集成有多种方式本章帮助用户根据自身情况快速选择最适合的路径。3.1 四种接入路径横向对比接入方式开发体验配置复杂度集成深度适合人群成本官方 VS Code 插件⭐⭐⭐⭐⭐⭐低原生集成追求最简单开箱即用的开发者API 按量计费Codex CLI 终端代理⭐⭐⭐⭐⭐⭐中低终端交互 VS Code 联动习惯命令行的开发者、CI/CD 场景API 按量计费Continue 插件 本地模型⭐⭐⭐⭐⭐⭐⭐中代码补全 对话注重隐私、追求零月费的开发者免费Python API 脚本开发⭐⭐⭐⭐⭐⭐高完全自定义希望深度定制功能的开发者API 按量计费3.2 快速决策指南 如果你是新手追求最简单开箱即用直接选择方式一官方 VS Code 插件。在 VS Code 扩展商店搜索安装后填入 API Key 即可使用无需任何额外配置。 如果你是命令行重度用户选择方式二Codex CLI。在终端中运行codex 你的需求即可让 AI 直接操作项目文件。 如果你注重隐私或预算有限选择方式三Continue 插件 本地模型。完全在本地运行数据不离开电脑长期使用零成本。 如果你需要深度定制选择方式四Python API 脚本。自行编写脚本实现对 API 的完全控制。第四章方式一——官方 VS Code 插件安装与配置这是最简单、最直接的接入方式适合追求快速上手的新手用户。4.1 安装 Codex VS Code 插件打开 VS Code点击左侧活动栏的扩展图标或按CtrlShiftX在搜索框中输入Codex – OpenAI’s coding agent或openai.chatgpt找到官方插件后点击Install安装等待安装完成VS Code 会提示重启或自动激活插件如果搜索不到请直接从 VS Code Marketplace 访问openai.chatgpt页面进行安装。4.2 全局配置文件结构Codex 的所有配置均基于两个核心文件config.toml和.env或auth.json。这是理解 Codex 配置逻辑的关键。config.toml主配置文件定义模型服务商、接口地址、模型名称、运行规则、安全权限等所有核心行为使用TOML 格式编写.env/auth.json存储 API 密钥、OAuth 登录令牌等敏感凭证是工具连通服务的核心配置文件存放路径根据操作系统不同有所差异操作系统配置目录路径Windows%USERPROFILE%\.codex\macOS~/.codex/Linux~/.codex/4.3 配置 API Key完成插件安装后需要进行 API Key 配置。方法一通过 VS Code 设置界面配置在 VS Code 中按Ctrl,Windows/Linux或Cmd,macOS打开设置在搜索框中输入Codex或OpenAI找到 API Key 配置项粘贴你的 API Key保存设置重启 VS Code方法二通过配置文件手动配置推荐更可控创建config.toml文件toml# 默认使用的模型 model gpt-4o # 或 gpt-4-turbo、gpt-3.5-turbo # 模型提供商 model_provider openai # 上下文窗口大小token数 model_context_window 128000 # 推理强度minimal | low | medium | high | xhigh model_reasoning_effort medium # 沙箱模式read-only | workspace-write | danger-full-access sandbox_mode workspace-write # 审批策略on-request | on-failure | never approval_policy on-request # 允许网络访问在workspace-write模式下 [sandbox_workspace_write] network_access true # 定义OpenAI提供商 [model_providers.openai] name OpenAI Official base_url https://api.openai.com/v1 env_key OPENAI_API_KEY创建.env文件envOPENAI_API_KEYsk-你的实际API密钥⚠️安全提醒绝对禁止将包含 API Key 的配置文件提交到 Git 等代码仓库。确保在.gitignore中添加.codex/和.env规则。4.4 插件使用入门配置完成后重启 VS Code打开Codex 侧边栏如果未自动显示点击左侧活动栏中的 Codex 图标在侧边栏对话框中输入自然语言指令如用 Python 写一个快速排序函数解释这段代码的功能帮我重构这个函数使其更简洁插件会自动理解上下文当前打开的文件内容、光标位置等并生成相应结果。4.5 故障排查插件不生效如果安装后插件未正常响应请按以下顺序排查检查 API Key 是否有效使用 curl 直接测试将your-key替换为实际 Keybashcurl https://api.openai.com/v1/models -H Authorization: Bearer your-key如果返回 401 错误说明 Key 无效检查环境变量是否正确加载确保.env文件中的变量名与config.toml中env_key完全一致大小写和拼写必须一字不差重启 VS Code配置文件修改后必须重启 VS Code 才能生效查看 VS Code 输出面板选择 Codex 插件的输出通道查看具体错误日志第五章方式二——Codex CLI 终端代理安装与配置Codex CLI 是 OpenAI 官方推出的开源本地编码代理底层基于Rust构建能够在终端中直接读取代码上下文、修改文件甚至执行终端命令。与 VS Code 联动的核心思想是CLI 作为“大脑”理解任务和操作文件VS Code 作为“眼睛和手”实时展示变化两者协同完成 AI 编程。5.1 安装 Codex CLI推荐方式通过 npm 全局安装跨平台bashnpm install -g openai/codexWindows 用户注意CLI 在 Windows 上目前仍处于实验性阶段强烈建议在 WSL2Windows Subsystem for Linux中安装 Node.js npm 后再运行或者优先使用 VS Code 扩展方式。macOS 可选方式通过 Homebrew 一键安装bashbrew install --cask codex验证安装bashcodex --version如果正确输出版本号说明安装成功。5.2 认证与登录安装完成后Codex CLI 支持两种认证方式请根据自身情况选择。方法一ChatGPT OAuth 登录推荐有订阅的用户直接运行codexCLI 默认会唤起浏览器进入 ChatGPT 登录流程。授权成功后凭据会缓存在本地~/.codex/auth.json后续使用无需重复登录。方法二API Key 环境变量注入推荐使用量计费的开发者bash# macOS/Linux export OPENAI_API_KEY你的OpenAI_API_Key codex # Windows PowerShell $env:OPENAI_API_KEY你的OpenAI_API_Key codex如需永久生效将上述 export 命令添加到~/.bashrc、~/.zshrcmacOS/Linux或通过 Windows 系统环境变量面板设置。5.3 基础使用与 VS Code 联动场景一在终端直接使用bash# 进入项目目录 cd /path/to/your/project # 启动交互模式最常用 codex # 或者在启动时直接下达指令 codex 帮我写一个计算斐波那契数列的 Python 函数场景二与 VS Code 联动——核心操作链路这是本文的重点。Codex CLI 与 VS Code 的联动并不需要安装任何特殊连接插件而是通过以下工作流实现无缝协作步骤操作说明① 终端启动 CLI在项目根目录运行codexCLI 读取整个项目目录的代码上下文② 下达任务指令在终端输入自然语言需求例如“读取当前目录下的app.py为其中的函数添加类型注解”③ CLI 执行操作CLI 自动分析、修改文件修改会直接写入磁盘同步至 VS Code④ VS Code 实时显示VS Code 自动检测文件变化无需额外操作修改内容即时显示在编辑器中⑤ 手动确认在 VS Code 中审查和微调 AI 生成的代码形成“AI 生成 → 人工审查”的协作闭环这种“CLI 操作 VS Code 显示”的联动方式实现了 AI 编程助手在不离开终端的前提下完成从原型到部署的完整编码流程。场景三设置 VS Code 快捷键调用 Codex为提升联动效率可以在 VS Code 中创建任务用快捷键直接调用 Codex在项目根目录创建.vscode/tasks.json添加以下内容json{ version: 2.0.0, tasks: [ { label: Codex: 生成代码, type: shell, command: codex -p \${selectedText}\, group: none, presentation: { reveal: always, panel: new }, problemMatcher: [] }, { label: Codex: 解释代码, type: shell, command: codex -p \解释以下代码的功能\\n${selectedText}\, group: none } ] }为任务绑定快捷键CtrlK CtrlS打开快捷键设置搜索Run Task为Codex: 生成代码绑定CtrlShiftG等快捷键5.4 配置文件详解config.toml是 CLI 的核心配置文件以下几类常见配置场景供参考场景一基础 OpenAI 官方配置tomlmodel gpt-4o model_provider openai model_context_window 128000 model_reasoning_effort medium sandbox_mode workspace-write approval_policy on-request [model_providers.openai] name OpenAI Official base_url https://api.openai.com/v1 env_key OPENAI_API_KEY场景二通过网关/代理中转加速国内访问tomlmodel gpt-4o model_provider custom-gateway # 使用自定义提供商名称 model_reasoning_effort high [model_providers.custom-gateway] name My Gateway base_url https://your-gateway.com/v1 env_key OPENAI_API_KEY wire_api responses场景三开启更自主的审批模式approval_policy字段控制 CLI 执行敏感操作如写入文件、访问网络前是否需要用户确认on-request默认每项操作都需要用户确认安全性最高on-failure操作失败时才询问适合较为熟练的用户never完全自动执行风险极高强烈不推荐除非在完全隔离的沙箱环境中使用5.5 项目级配置 vs 全局配置Codex CLI 支持两套配置体系仅文件存放路径不同配置格式和语法完全通用配置类型存放路径作用范围优先级全局配置~/.codex/macOS/Linux或%USERPROFILE%\.codex\Windows本机所有 Codex 调用通用一次配置终身可用低可被项目级配置覆盖项目级配置项目根目录./.codex/仅当前项目目录内生效完全隔离其他项目高无条件覆盖全局配置配置优先级黄金法则命令行临时参数 Profile 配置档案 项目级配置 全局配置 系统环境变量 内置默认值。越靠近执行目录的配置优先级越高。5.6 沙箱安全配置Codex CLI 使用本地沙箱控制来限制文件系统和网络访问这是保护电脑安全的重要机制。sandbox_mode字段的安全等级说明模式文件系统权限网络访问适用场景read-only只读无法修改文件需单独配置仅用于分析代码的场景workspace-write推荐可在工作区内修改文件默认禁用需手动[sandbox_workspace_write] network_access true开启日常开发平衡安全与效率danger-full-access无限制无限制⚠️ 仅限完全隔离的沙箱环境5.7 安装故障排查问题一安装失败npm 报错检查 Node.js 版本是否符合要求≥ v22尝试清空 npm 缓存npm cache clean --force如果网络问题切换国内镜像源问题二API Key 无效401 错误90% 的 401 报错集中在 Key 格式/来源错误、账号权限不足、环境变量未正确加载三大类用 curl 直接测试是最快的诊断手段问题三Windows 兼容性问题目前 Windows 原生 CLI 仍处于实验性阶段强烈建议在WSL2中安装 Node.js npm 后再运行 CLI第六章方式三——第三方插件Continue Ollama本地化配置如果你注重代码隐私——不希望代码被发送到云端——或者没有 OpenAI API Key 但想零成本体验 AI 编程这一章的内容将非常适用。本方案的核心组件是ContinueVS Code 插件 Ollama本地模型运行工具实现完全本地化的 AI 编程助手。6.1 为什么选择完全本地化方案隐私保护代码完全不离开电脑特别适合处理敏感代码的企业开发场景零月费本地模型无按量计费长期使用成本为零无需网络在无互联网连接的环境下也可使用真实预期本地模型7B-16B 参数范围在复杂架构推理、跨文件重构等任务上能力弱于 GPT-4o但对于行内补全、样板代码生成、标准框架模式等日常开发场景完全够用。6.2 安装 Ollama 和 Continue 插件步骤一安装 OllamaOllama 是运行本地大语言模型的核心工具。Windows/macOS/Linux 均支持访问 ollama.com/download 下载对应版本安装完成后在终端执行以下命令拉取编码模型bash# 拉取 Qwen2.5-Coder 系列推荐中文支持好 ollama pull qwen2.5-coder:7b # 或拉取 DeepSeek-Coder-V2代码生成能力较强 ollama pull deepseek-coder-v2:16b # 如硬件足够可拉取 Qwen3-Coder-Next 更大模型 ollama pull qwen3.5:35b-a3b-coding-nvfp4拉取模型需要一定时间等待完成即可。步骤二安装 Continue 插件打开 VS Code进入扩展商店CtrlShiftX搜索Continue发布者Continue点击Install安装等待完成安装后VS Code 左侧会出现 Continue 图标类似对话气泡6.3 配置 Continue 连接本地 Ollama方法一通过 Continue 配置界面推荐点击 VS Code 左侧的 Continue 图标在打开的界面中点击设置齿轮图标选择“Add chat model”→“Ollama”输入模型名称如qwen2.5-coder:7b和本地 API 地址默认http://localhost:11434保存配置方法二手动编辑配置文件Continue 的配置文件位于Windows:%APPDATA%\Continue\config.jsonmacOS/Linux:~/.continue/config.json在配置文件中添加以下内容json{ models: [ { title: Qwen2.5-Coder, provider: ollama, model: qwen2.5-coder:7b, apiBase: http://localhost:11434 } ], tabAutocompleteModel: { title: Qwen2.5-Coder, provider: ollama, model: qwen2.5-coder:7b } }6.4 使用 Continue 实现 AI 编程配置完成后在 VS Code 中可以通过以下方式使用代码补全在编辑器中编写代码时Continue 会自动提供实时的行内代码建议对话式编程选中任意代码块 → 右键 →“Continue”或直接按CtrlImacOSCmdI打开对话面板快速指令在对话面板中输入需求如解释这段代码的功能为这个函数生成单元测试帮我找出这段代码中的性能问题Continue 插件在 VS Code Marketplace 的安装量已超过 300 万是目前 GitHub Copilot 最受欢迎的免费替代方案之一。6.5 进阶连接 Codex CLI 到本地 Ollama完全本地化如果你希望同时拥有 Codex CLI 的强大功能又想完全本地运行可以通过以下配置实现。步骤一启动 Ollama 的 OpenAI 兼容 API 服务Ollama 默认监听http://localhost:11434并提供了与 OpenAI API 完全兼容的/v1端点。步骤二配置 Codex CLI 指向本地 Ollama编辑~/.codex/config.tomltomlmodel qwen2.5-coder:7b # 或你拉取的其他模型 model_provider ollama model_context_window 32768 sandbox_mode workspace-write approval_policy on-request [model_providers.ollama] name Ollama Local base_url http://localhost:11434/v1 wire_api chat_completions env_key NO_KEY # 本地模型无需 API Key步骤三验证连通性bash# 确认 Ollama 服务正常 curl http://localhost:11434/api/version # 启动 Codex CLI它会使用本地模型 codex 用 Python 写一个单例模式的实现如果遇到网络连通问题可能需要将 Ollama 服务暴露到容器可视的地址特别是在使用 Docker 或容器化工具时。使用curl http://192.168.64.1:11434/api/version测试若失败需调整网络配置。第七章方式四——Python API 脚本开发高级定制如果你需要深度定制 AI 编程助手的行为——例如集成到公司内部工具链、批量处理代码文件或实现特定的代码生成逻辑——可以自行编写调用 OpenAI API 的 Python 脚本。适用场景团队统一 AI 助手配置、批量代码处理、CI/CD 流程中的自动代码审查。7.1 基础脚本模板创建codex_api.pypythonimport openai import os from dotenv import load_dotenv # 加载环境变量 load_dotenv() openai.api_key os.getenv(OPENAI_API_KEY) def generate_code(prompt: str, max_tokens: int 500) - str: 调用 OpenAI API 生成代码 try: response openai.Completion.create( modelgpt-4o, # 或 gpt-3.5-turbo promptprompt, max_tokensmax_tokens, temperature0.5, # 值越低越保守值越高越有创造力 top_p0.9 ) return response.choices[0].text.strip() except Exception as e: print(fAPI 调用失败: {e}) return def explain_code(code: str) - str: 解释选中的代码 prompt f请解释以下代码的功能和逻辑\n{code} return generate_code(prompt, max_tokens800) if __name__ __main__: user_prompt input(请输入代码需求: ) result generate_code(user_prompt) print(\n生成的代码:\n) print(result)7.2 与 VS Code 集成绑定快捷键调用脚本在项目根目录创建.vscode/tasks.json添加任务配置json{ version: 2.0.0, tasks: [ { label: Codex API: 生成代码, type: shell, command: cd ${workspaceFolder} python codex_api.py, group: none } ] }通过CtrlShiftP→Run Task或设置快捷键调用通过 VS Code 代码片段功能复用生成结果将 Codex 生成的常用代码保存为 VS Code 用户片段File→Preferences→Configure User Snippets添加自定义片段模板提升重复使用效率。7.3 调试与优化建议错误处理捕获 API 调用异常如速率限制、无效请求添加重试逻辑参数调优调整max_tokens和temperature参数来控制生成代码的长度和多样性缓存高频结果对常用代码模式使用本地缓存减少重复调用降低延迟日志记录记录 API 调用情况便于排查问题第八章代理配置国内用户必读由于 OpenAI API 服务位于海外国内用户常遇到连接问题。本章提供完整的代理配置方案。8.1 代理配置方式方法一通过系统环境变量配置推荐覆盖范围最广bash# macOS/Linux export HTTP_PROXYhttp://127.0.0.1:7890 export HTTPS_PROXYhttp://127.0.0.1:7890 # Windows PowerShell $env:HTTP_PROXYhttp://127.0.0.1:7890 $env:HTTPS_PROXYhttp://127.0.0.1:7890将上述命令添加到~/.bashrc、~/.zshrc或 Windows 系统环境变量中即可永久生效。方法二通过 VS Code 设置代理打开 VS Code 设置Ctrl,搜索proxy在Http: Proxy设置中输入代理地址如http://127.0.0.1:7890保存后重启 VS Code方法三通过 Codex config.toml 配置代理如果 API 请求需要通过特定代理网关可在config.toml中配置自定义base_url指向代理地址参考 5.4 节的网关配置示例。8.2 代理故障排查症状可能原因解决方法API 请求超时代理未生效或代理服务未启动确认代理软件正在运行验证环境变量是否正确设置认证失败代理修改了请求头尝试使用透明代理模式或更换代理服务部分请求失败代理分流规则不完整确保 OpenAI API 相关域名api.openai.com已纳入代理规则8.3 第三方 API 网关推荐对于国内开发者使用Crazyrouter等统一 API 网关是一个更为稳定的选择。这类网关提供以下优势无需自建代理直接接入国内可访问的 API 端点统一对接多个模型GPT、Claude、DeepSeek、Gemini 等按需切换计费和接入更加灵活配置方法参考 5.4 节“通过网关/代理中转”的config.toml模板将base_url指向网关提供的地址即可。第九章安全与最佳实践9.1 API Key 安全管理绝对禁止将 API Key 硬编码在代码中或以明文提交到 Git 仓库使用dotenv管理环境变量并在.gitignore中添加.env和.codex/定期轮换 API Key最小化泄露风险生产环境优先使用环境变量注入密钥9.2 沙箱安全配置日常开发建议使用sandbox_mode workspace-write配合approval_policy on-request除非在完全隔离的沙箱环境中否则永远不要使用danger-full-access定期审查 AI 对代码的修改确保不会引入安全漏洞9.3 代码审查与质量控制AI 模型可能会产生幻觉hallucinate并生成错误或不安全的代码。始终在使用前对生成的结果进行人工审查。尤其注意检查生成的代码是否包含硬编码的敏感信息确认生成的 SQL 查询是否存在注入风险验证生成的认证逻辑是否符合安全规范第十章常见问题与故障排查Q1安装 VS Code 插件时搜索不到 Codex访问 VS Code Marketplace 直接搜索openai.chatgpt进行安装或检查 VS Code 版本是否低于 1.85.0。Q2API 调用返回 401 错误90% 的情况是因为 Key 格式/来源错误、账号权限不足或环境变量未正确加载。先用 curl 快速诊断bashcurl https://api.openai.com/v1/models -H Authorization: Bearer 你的API_KEY如果返回 401说明 Key 无效。Q3Codex CLI 安装后运行提示“command not found”确认 npm 全局安装的 bin 目录已添加到系统 PATH 中尝试重新打开终端窗口检查 Node.js 版本是否符合要求Q4代理已配置但仍然无法连接确认代理软件正在运行尝试直接使用curl -x http://127.0.0.1:7890 https://api.openai.com/v1/models测试如果使用第三方网关请确认网关提供的base_url是否正确Q5本地 Ollama Codex CLI 配置后无法连接确认 Ollama 服务已启动curl http://localhost:11434/api/version检查config.toml中的base_url是否包含/v1后缀如果使用 Docker/容器工具可能需要将 Ollama 暴露到容器网络的可见地址Q6Codex CLI 认证机制不兼容Codex CLI 认证机制在版本迭代中多次变更当前最新版 v0.130.02026-05-08。建议确保 Codex CLI 已更新到最新版本npm update -g openai/codex如果使用旧的 API Key 格式无效尝试重新生成新的 API Key或切换到 ChatGPT OAuth 登录方式第十一章官方参考文档链接以下为官方文档链接供深入学习和查阅Codex CLI GitHub 官方仓库——源码、更新日志和详细使用说明Codex 配置基础——config.toml完整配置参考Codex IDE 扩展文档——VS Code 插件官方文档沙箱安全机制——深入了解 Codex 的安全机制代理审批与安全策略——approval_policy的详细说明结语本指南系统地介绍了 OpenAI Codex 与 VS Code 集成的四种核心方案。从最简单的官方插件一键安装到终端代理 CLI 的深度使用再到完全本地化的隐私优先方案和面向企业级定制的 API 开发——无论你处于哪个阶段都能找到最适合自己的配置路径。
