奕商创

标签： codex

  • Codex 安装使用教程：Windows、CLI 与 MCP 配置指南

    Codex 安装使用教程：Windows、CLI 与 MCP 配置指南

    Codex 可以帮助你理解项目、修改代码、运行命令、编写测试，并通过 MCP 接入内容管理、页面构建和其他外部工具。本文以 Windows 为例，从安装开始，带你完成桌面应用、CLI 和 MCP 的基础配置。

    Codex 安装、配置与开始工作教程封面
    从安装到 MCP 连接，建立一套可重复使用的 Codex 工作流。

    开始前：先确认你需要哪种使用方式

    Codex 有两种常见使用场景：桌面应用适合查看项目、讨论方案和持续协作；CLI 适合在 PowerShell 或终端中直接处理仓库任务。多数开发者会同时使用两者：在桌面应用里梳理需求，在终端里执行和验证。

    • 仅使用桌面应用：安装、登录、选择项目目录后即可开始。
    • 需要终端工作流：额外安装 Node.js 和 Codex CLI。
    • 需要连接 WordPress、文档或内部系统：再配置相应的 MCP 服务。

    一、安装 Codex 桌面应用

    从 Codex 官方渠道下载安装桌面应用，完成安装后登录账号。首次打开时，选择一个项目目录，让 Codex 读取项目结构和已有说明。若仓库中包含 AGENTS.md，它通常会定义项目约定、常用命令和验证方式，应优先遵循。

    开始任务时，建议把目标、范围和验收条件说清楚。例如：

    检查登录接口的 500 错误，定位原因并修复。
不要修改数据库结构；补充覆盖该问题的测试，并运行相关测试命令。

    这种描述比“帮我修一下登录”更容易得到可验证的结果。

    二、安装 Node.js 与 Codex CLI

    如果需要在 PowerShell 中运行 Codex CLI，请先安装 Node.js LTS。安装完成后，关闭当前 PowerShell 并重新打开，再确认以下命令能返回版本号：

    node --version
npm --version

    接着安装 Codex CLI：

    npm install -g @openai/codex

    部分 Windows 环境会因执行策略阻止 npm.ps1。出现该情况时，不必立刻修改系统策略，直接改用：

    npm.cmd install -g @openai/codex

    安装后验证 CLI：

    codex --version

    如果系统中存在同名但不可执行的桌面版内置程序，可使用 npm 安装目录中的 codex.cmd 进行验证和调用。

    三、开始第一个 Codex 任务

    进入项目目录后启动 CLI：

    codex

    一个可靠的工作流通常包含四步：

    1. 先让 Codex 阅读项目结构、依赖和已有规范。
    2. 明确说明要修改的功能、不能修改的范围，以及完成标准。
    3. 让 Codex 实施修改，并要求它运行对应的测试、构建或静态检查。
    4. 审阅变更内容，确认没有误改无关文件后再提交或发布。

    对于大型任务，可以先要求给出实施方案，再继续执行；对于小修复，直接说明问题与期望结果通常更高效。

    四、配置 MCP，让 Codex 连接外部服务

    MCP 让 Codex 能在授权范围内调用外部工具，例如读取 WordPress 内容、创建草稿、查询媒体库，或调整页面构建器布局。远程 MCP 通常由服务地址和认证信息组成。

    敏感信息应放在本机环境变量中，不要写入仓库、文章或聊天记录。以下是一个使用环境变量保存令牌的通用示例：

    $env:MY_MCP_TOKEN = "你的令牌"
codex mcp add example --url https://example.com/mcp --bearer-token-env-var MY_MCP_TOKEN

    添加完成后，重启 Codex 桌面应用或新开会话，使工具列表重新加载。接入后，先使用只读工具确认连接正常，再进行创建、更新或发布等写入操作。

    五、三个常见问题与处理方法

    1. PowerShell 提示找不到 codex

    这通常说明 CLI 未安装，或 npm 的全局命令目录没有加入环境变量。先运行 npm.cmd install -g @openai/codex，再新开 PowerShell 窗口验证。

    2. PowerShell 禁止运行 npm.ps1

    这是 PowerShell 执行策略导致的脚本入口限制。优先使用 npm.cmd，它不依赖 npm.ps1，也不会更改全局安全策略。

    3. 添加 MCP 后工具没有出现

    依次检查：服务地址是否正确、令牌环境变量是否存在、当前账号是否具备服务要求的权限，以及 Codex 是否已重启。对于内容类 MCP，先调用“使用说明”或“列出内容类型”等只读接口最容易确认问题所在。

    六、提高日常效率的提示词写法

    把需求写成“目标 + 范围 + 约束 + 验证”四部分，能明显减少来回沟通。例如：

    目标：为产品列表加入按价格排序。
范围：仅修改前端列表和相关测试。
约束：保持现有 URL 参数格式，不新增依赖。
验证：运行单元测试和生产构建，并说明结果。

    当任务涉及删除数据、发布内容、修改权限或调用外部系统时，先要求 Codex 列出影响范围，再明确授权执行。

    结语

    Codex 的价值不只在于生成代码，更在于把理解项目、实施修改、验证结果和连接外部工作流串成一个闭环。先把桌面应用和 CLI 跑通，再按需接入 MCP，你就能逐步建立适合自己团队的开发流程。