让 ChatGPT 直接操作你电脑上的代码项目。
安装并连接后，你可以在 ChatGPT 里直接说：
- “先看看这个项目是做什么的”
- “检查一下现在有哪些改动”
- “修掉这个报错”
- “跑一下测试”
- “把这个功能实现完”
- “切到另一个项目继续”
codex-mcp 会在你的电脑上读取文件、修改代码、执行命令、查看 Git，并把结果返回给 ChatGPT。
为了减少模型选择工具时的歧义，多项目 daemon 只公开 15 个顶层工具：project_control 加上 read、read_image、apply_patch、ls、grep、glob、code_explore、exec_command、write_stdin、skills_list、skill_read、mcp_tools、mcp_call、summary。Git 和包管理等操作统一通过 exec_command 完成。
codex-mcp 面向个人开发环境使用。它拥有很强的本机操作能力，请只连接你自己的 ChatGPT 和你信任的项目。
codex-mcp 在你的电脑上运行一个后台服务，并通过 MCP 把本地开发能力提供给 ChatGPT。
ChatGPT
│
│ HTTPS / MCP
▼
Cloudflare Tunnel 或你自己的 HTTPS 入口
│
▼
codex-mcp 后台服务
│
├── 项目 A
├── 项目 B
└── 项目 C
你只需要运行 一个 codex-mcp 后台服务。
不同项目不需要分别启动服务器，也不需要分别创建 Cloudflare Tunnel。进入每个项目目录运行一次 codex-mcp，它就会把这个项目注册到同一个后台服务里。
每个 ChatGPT 对话只会绑定一个项目。这样你可以在不同对话里分别处理不同项目，也可以明确切换当前对话使用的项目。
- Node.js 22 或更高版本
- Git：用于查看状态、提交历史和差异
你需要一个可以通过 HTTPS 访问到本机 codex-mcp 的公网地址。
最简单的方式是：
- 一个 Cloudflare 账号
- 一个已经接入 Cloudflare 的 域名
codex-mcp 可以自动创建和管理 Cloudflare Tunnel。
如果你已经有自己的反向代理、服务器或其他 HTTPS 入口，也可以不让 codex-mcp 管理 Cloudflare。
如果电脑上已经安装了这些工具，codex-mcp 还可以读取它们已有的能力：
- Codex
- Claude Code
- Agent Skills
没有这些也不影响 codex-mcp 的核心功能。
推荐用 npm：
npm install -g @meesii/codex-mcp也可以用安装脚本：
curl -fsSL https://github.com/meesii/codex-mcp/releases/latest/download/install.sh | shirm https://github.com/meesii/codex-mcp/releases/latest/download/install.ps1 | iex安装完成后，如果终端提示找不到 codex-mcp，关闭终端并重新打开一次。
检查版本：
codex-mcp --version运行：
codex-mcp setup首次设置会带你完成几个步骤。
默认情况下，codex-mcp 会询问是否自动配置 Cloudflare Tunnel。
选择自动配置后，它会：
- 准备
cloudflared - 打开浏览器登录 Cloudflare
- 读取账号中的域名
- 让你选择一个域名
- 创建或复用当前电脑对应的 Tunnel
- candidate 准备完成前保持现有后台服务在线；只有实际切换时才短暂停止
- 启动 candidate connector，确认它已经连接 Cloudflare
- 保存原 DNS 记录，再把域名切换到 candidate Tunnel
- 在默认最多 5 分钟的兜底窗口内验证公网随机探针确实回到这台电脑；可随时 Ctrl+C 安全取消
- 验证成功后才原子提交本机配置；失败会恢复 DNS，并保留上一次可用配置
例如最终得到：
https://codex-mcp.example.com/mcp
如果你的 Cloudflare 账号里没有已经接入 Cloudflare 的域名，自动 Tunnel 模式无法完成配置。
Cloudflare Tunnel 生成的
<UUID>.cfargotunnel.com是 DNS CNAME 目标，不是直接给 ChatGPT 使用的 MCP 地址。
如果你不想让 codex-mcp 管理 Cloudflare，可以在 setup 中选择自己提供公网入口，然后填写你的域名。
此时需要你自己保证：
https://你的域名/mcp
能够安全地转发到本机 codex-mcp 服务。
公网验证完成后，codex-mcp 会先生成 ChatGPT 连接密码。
请保存这个密码。
电脑上只保存密码哈希，不保存明文密码。忘记以后不能找回，只能重新设置。
重新设置密码：
codex-mcp auth核心公网连接和连接密码完成后，setup 还会检测当前环境是否存在：
- Codex
- Claude Code
- Agent Skills
你可以选择：
- 使用检测到的全部能力
- 自定义启用哪些 MCP / Skills
- 全部关闭
默认推荐自动同步。这样这些工具的配置发生变化后，codex-mcp 可以自动刷新。当前目录没有检测到某个能力源，不会再把用户之前为其它项目启用的同类能力全局关闭；取消这一步也不会破坏已经完成的公网连接和连接密码。
进入项目目录：
cd /path/to/your-project
codex-mcp第一次运行时，codex-mcp 会启动后台服务，然后注册当前项目。
以后再次运行同一个项目，只会确认这个项目处于已注册状态，不会再启动一套新的服务器。
你也可以从其他目录指定项目：
codex-mcp --root /path/to/your-project查看当前状态：
codex-mcp status你会看到：
- 后台服务是否运行
- 本机 MCP 地址
- 公网 MCP 地址
- Cloudflare Tunnel 是否在线
- 当前 CLI 版本和正在运行的 daemon 版本
- 两者版本不一致时的
codex-mcp restart提示 - 已注册项目
- 每个项目当前有多少会话绑定
ChatGPT 的 MCP App 入口和可用套餐可能会变化，请以你当前账号的 Apps 设置为准。
当前常见流程是：
- 在 ChatGPT 中启用 Developer Mode
- 打开 Apps → Create
- 填入 codex-mcp 的 MCP 地址
- 扫描工具（Scan Tools）
- 按提示完成 OAuth / 密码验证
- 创建并启用这个 App
MCP 地址就是 setup 最后显示的公网地址，例如：
https://codex-mcp.example.com/mcp
授权时使用 codex-mcp setup 生成的连接密码。
连接完成后，就可以直接让 ChatGPT 操作本机项目。
完整 MCP 写入能力是否可用取决于 ChatGPT 当前的套餐、工作区权限和产品开放状态。如果你的设置里没有 Developer Mode 或创建自定义 MCP App 的入口，请先确认当前 ChatGPT 账号是否支持。
这是当前版本最重要的使用方式。
先区分两个概念：
- 注册项目（Registered Project）：你运行
codex-mcp注册的主项目。一个 ChatGPT 对话同一时间只绑定一个注册项目。 - 会话绑定（Conversation Binding）：ChatGPT 对话当前选择的注册项目；文件和命令工具只能在这个项目目录内运行。
项目注册由本地 CLI 完成；模型只通过 project_control 选择已经注册的项目，不会自行注册项目或扩大路径边界。
假设电脑上有三个项目：
~/code/api
~/code/web
~/code/mobile
分别进入目录运行：
cd ~/code/api
codex-mcp
cd ~/code/web
codex-mcp
cd ~/code/mobile
codex-mcp它们会全部注册到同一个 codex-mcp 后台服务。
不会创建三个端口，也不会创建三个 Tunnel。
查看所有项目：
codex-mcp project list也可以显式注册指定目录：
codex-mcp project add /path/to/project查看单个项目详情：
codex-mcp project info <项目 ID、项目名或目录>一个 ChatGPT 对话只操作一个项目。
例如你可以说：
使用 web 项目，看看首页现在有什么问题。
ChatGPT 会通过 project_control 选择对应项目，然后后面的文件读取、代码修改、命令执行和 Git 操作都会以这个项目为上下文。
另一个 ChatGPT 对话可以同时绑定 api 项目，互不影响。
如果要在当前对话切换项目，可以直接说：
切换到 api 项目。
切换已有绑定时需要明确确认，不会静默跳到另一个项目。
推荐使用：
codex-mcp project remove <项目 ID、项目名或目录>如果当前终端就在项目目录，也可以省略目标：
codex-mcp project remove旧的 codex-mcp exit 仍然保留，等价于停用当前项目。
这只会停用目标项目；后台服务、Cloudflare Tunnel 和其他项目仍然继续运行。重新启用时，再运行 codex-mcp 或 codex-mcp project add <目录>。
停止：
codex-mcp stop重启：
codex-mcp restartstop 会关闭所有项目运行时、codex-mcp 后台服务和 Cloudflare Tunnel，但保留项目注册和 active 状态。需要再次启动时，进入项目目录运行 codex-mcp（本机模式用 codex-mcp --local）。restart 只用于重启当前正在运行的后台服务，因此能可靠保留原来的本机/公网模式。旧的 codex-mcp exit -a 仍作为 stop 的兼容入口。
连接项目以后，ChatGPT 可以通过 codex-mcp：
- 读取单个或多个文件
- 搜索字符串和正则表达式
- 按文件模式查找文件
- 浏览目录
- 查找代码关系
- 使用事务式
apply_patch精确替换已有代码 - 批量创建、覆盖或删除文件
- 提交失败时自动回滚本次批量改动
- 运行构建
- 运行测试
- 安装依赖
- 启动开发服务器
- 管理长时间运行的进程
- 通过
exec_command使用项目现有的 Git CLI
当你说：
继续这个项目。
或者：
先看看这个项目现在是什么情况。
ChatGPT 会先用 project_control 查看并绑定一个已注册项目，再通过精简工具集读取代码、Skills 和命令结果。一个对话同一时间只绑定一个项目。
所有文件工具和命令工作目录都限制在当前绑定项目的主目录内。
运行：
cd ~/code/my-project
codex-mcp那么：
~/code/my-project
就是这个项目的主工作区。
相对路径默认都从这里开始。
需要处理另一个目录时，把它注册成独立项目：
codex-mcp project add /path/to/other-project然后让 ChatGPT 使用 project_control 明确切换。工具不会通过绝对路径绕过当前项目边界。
路径限制不是完整的操作系统沙箱。项目内启动的 shell 命令仍然拥有当前系统用户本身拥有的系统权限。
codex-mcp 可以直接读取已有 AI 开发工具的配置，而不是复制一份。
支持：
| 来源 | MCP | Skills |
|---|---|---|
| Codex | ✅ | ✅ |
| Claude Code | ✅ | ✅ |
| Agent Skills | — | ✅ |
常见位置包括：
~/.codex/
~/.claude/
~/.agents/skills/
Claude Code 项目内的 .claude/skills 也可以按项目读取。
这些能力默认只是读取和引用原配置，不会把第三方 Token、MCP 配置和 Skill 文件复制到 ~/.codex-mcp。
重新管理这些设置：
codex-mcp setup然后选择：
管理外部能力
支持两种同步方式：
watch：配置发生变化后自动刷新，推荐startup：只在 codex-mcp 启动时读取一次
| 命令 | 作用 |
|---|---|
codex-mcp |
注册 / 启动当前项目，并确保后台服务运行 |
codex-mcp status |
查看后台服务、CLI/daemon 版本、Tunnel 和所有项目 |
codex-mcp status --json |
输出稳定的机器可读状态 |
codex-mcp restart |
重启后台服务，保留项目注册状态 |
codex-mcp stop |
停止后台服务和 Tunnel，保留项目注册状态 |
codex-mcp project list |
查看已注册项目 |
codex-mcp project add [目录] |
注册项目，默认当前目录 |
codex-mcp project remove [项目] |
停用项目，默认当前目录 |
codex-mcp project info [项目] |
查看项目详情 |
codex-mcp logs [--lines N] |
查看最近运行日志 |
codex-mcp logs -f |
持续跟随运行日志 |
codex-mcp setup |
首次设置或管理现有配置 |
codex-mcp doctor |
只读检查安装、配置和依赖 |
codex-mcp doctor --fix |
创建缺失本机目录、清理失效 daemon 状态等安全修复 |
codex-mcp auth |
修改 ChatGPT 连接密码 |
codex-mcp update |
更新到最新版本 |
codex-mcp tunnel |
重新配置公网连接（兼容快捷入口） |
codex-mcp exit |
兼容入口：停用当前项目 |
codex-mcp exit -a |
兼容入口：停止后台服务 |
codex-mcp --root <目录> |
注册指定目录，而不是当前目录 |
codex-mcp --local |
仅本机模式，不开放公网 |
codex-mcp --no-tunnel |
不自动启动 Cloudflare Tunnel |
codex-mcp --tunnel-logs |
把 Tunnel 日志同时输出到运行日志 |
codex-mcp serve --foreground |
前台运行服务，用于调试 |
codex-mcp --version |
查看版本 |
codex-mcp help |
查看帮助 |
已经完成首次配置后，再运行：
codex-mcp setup不会重新走一遍所有步骤。
你可以选择：
- 检查当前配置
- 修改公网连接
- 重新登录 / 切换 Cloudflare 账号
- 修改连接密码
- 管理 Codex / Claude Code / Agent Skills
- 退出，不做修改
“检查当前配置”会真实验证公网地址是否能够连接回当前电脑，而不只是检查配置文件是否存在。 这个检查只读取已提交配置和运行状态，不会登录 Cloudflare、修改 DNS 或重写 Tunnel 配置。
修改公网连接时，如果后台服务正在运行，setup 会先保留它的完整运行参数和所有项目注册，安全停止后完成切换，再按原参数恢复。多项目和会话绑定文件不会被重置。
codex-mcp 的用户数据默认保存在：
~/.codex-mcp/
主要文件包括：
~/.codex-mcp/config.json
~/.codex-mcp/daemon.json
~/.codex-mcp/projects.json
~/.codex-mcp/session-bindings.json
~/.codex-mcp/logs/
其中：
config.json：公网地址、工作区、权限、外部能力等设置daemon.json：当前后台服务状态projects.json：注册过的项目session-bindings.json：ChatGPT 会话和项目的绑定关系
Cloudflare 的登录和 Tunnel 凭据由 codex-mcp 放在自己的配置目录中管理，不依赖系统级 ~/.cloudflared 作为长期运行状态。
运行日志位于：
~/.codex-mcp/logs/
结构化日志文件类似：
codex-mcp.2026-08-12.0.jsonl
Cloudflare Tunnel 原始日志：
~/.codex-mcp/logs/tunnel.log
正常的工具日志不会记录：
- 原始命令内容
- 文件内容
- 工具返回的完整内容
- OAuth 凭据
它主要记录工具名、耗时、结果状态等运行信息。
如果遇到启动、Tunnel 或 MCP 连接问题，首先查看这里。
运行：
codex-mcp doctor它会检查：
- Node.js 版本
- Git
- 文件搜索组件
- codex-mcp 配置
- 连接密码
- 公网地址
- cloudflared
- Cloudflare 登录
- Tunnel 凭据
- Tunnel 配置文件
- 外部能力设置
这是排查问题时最先应该运行的命令。
重新打开终端后再试。
如果仍然找不到，重新运行安装脚本。
先运行：
codex-mcp status
codex-mcp doctor确认：
- 后台服务正在运行
- 公网连接已启动
- 公网地址正确
- Tunnel 没有报错
再查看：
~/.codex-mcp/logs/
密码明文无法找回。
重新设置：
codex-mcp auth运行：
codex-mcp setup选择：
重新登录 / 切换 Cloudflare 账号
codex-mcp 会在临时目录完成新登录并验证凭据，然后才替换自己管理的登录；取消或登录失败时旧凭据保持不变。它不会修改系统级 ~/.cloudflared。
重新运行：
codex-mcp tunnelcodex-mcp 会检查本机 Tunnel 凭据和 Cloudflare 上的 Tunnel 是否匹配。
如果发现同名 Tunnel 但本机没有可用凭据，不会删除远端 Tunnel，而是创建带唯一后缀的 candidate。只有本次新建、配置尚未提交且没有被 DNS 引用的 candidate 才会自动清理。
查看：
~/.codex-mcp/logs/tunnel.log
某些网络或防火墙会阻止 Cloudflare Tunnel 使用的 TCP 7844 连接。
当前版本会优先使用 IPv4，并在连接超时时给出更具体的错误提示。
先在 ChatGPT 的 MCP / App 设置中执行 Refresh，或者重新发布 / 重新连接当前 MCP App。
工具 ABI 已精简为固定的 15 个入口。旧的 ChatGPT action snapshot 不再兼容已删除的工具，因此升级后必须让 ChatGPT 重新扫描工具。
不需要。
每个项目只需要运行一次：
codex-mcp用来把它注册到同一个后台服务。
真正运行的 MCP server 和 Cloudflare Tunnel 都只有一套。
默认不会。
正常的 codex-mcp 会启动后台守护进程，终端命令完成后服务继续运行。
查看：
codex-mcp status停止后台服务：
codex-mcp stop旧的 codex-mcp exit -a 仍然兼容。
如果你是开发调试，希望服务一直占用当前终端，可以使用：
codex-mcp serve --foregroundcodex-mcp update更新会保留你的配置和连接密码。
更新后运行：
codex-mcp restart这样可以确保正在运行的 daemon 使用当前 CLI 版本。codex-mcp status 会同时显示 CLI 和 daemon 版本；如果两者不一致，会直接提示重启。
如果是用 npm 安装的：
npm uninstall -g @meesii/codex-mcp如果是用安装脚本安装的：
curl -fsSL https://github.com/meesii/codex-mcp/releases/latest/download/uninstall.sh | shirm https://github.com/meesii/codex-mcp/releases/latest/download/uninstall.ps1 | iex卸载程序默认保留用户配置和连接密码。
如果你确定不再使用，并希望彻底删除所有状态，可以再手动删除：
~/.codex-mcp
codex-mcp 的目标不是做一个强隔离沙箱，而是让个人开发环境中的 ChatGPT 可以真正完成开发工作。
因此请注意：
- 不要把自己的 codex-mcp 实例分享给其他人。
- 不要把连接密码公开。
- 只注册你信任的项目目录。
- 执行 shell 命令时，命令仍拥有当前系统用户本身的权限。
- 如果电脑上保存了生产环境密钥、SSH Key 或其他敏感文件，请按照正常本机开发安全标准管理它们。
公网 MCP 入口需要连接密码认证，但它不能替代操作系统级隔离。
正常情况下你不需要关心这一节。
ChatGPT 有时会缓存已经批准过的 MCP action 列表。当前工具 ABI 是固定的 15 个入口，升级后请在 ChatGPT 中 Refresh MCP App 或重新发布连接，让旧的 action snapshot 被完整替换。项目选择统一使用 project_control，其他已删除工具没有兼容别名。
克隆项目后：
npm ci
npm run typecheck
npm run build开发模式：
npm run dev只在本机调试：
npm run dev:once -- --local发布版本要求 Node.js 22。日常 CI 在 Linux 上检查，发版时再验证 Linux、macOS 和 Windows。