CodexPro
让 ChatGPT Web 看见你的本地仓库，并像本地代码代理一样工作。
English
·
中文网站
·
GitHub 点星
·
npm
·
稳定 URL 指南
·
中文 FAQ
·
安全说明
## 安装
CodexPro 需要 Node.js 20+，以及当前能使用自定义 MCP App 的 ChatGPT 账号和 Web 界面。OpenAI 2026 年 7 月的文档说明：包含写入和修改操作的完整 MCP 目前面向 Business、Enterprise 和 Edu；Pro 目前只能连接 read/fetch 权限的 MCP App。该文档没有把 Plus 列为支持自定义 MCP 的账号层级。
先安装 CLI：
```bash
npm install -g codexpro
```
GitHub `main` 文档可能早于 npm 发布；用 `npm install -g codexpro` 前请看 npm badge/version，未发布的 `main` 行为请用下面的 source checkout 方式。
进入你想让 ChatGPT 工作的仓库，然后运行 setup：
```bash
cd /path/to/your/repo
codexpro setup
```
CodexPro 会自动复制 ChatGPT Server URL。先到 `Settings -> Security and login` 打开 Developer mode，再到 `Settings -> Plugins -> Plugins` 标签页，点击搜索框旁的圆形 `+` 图标。打开 **New Plugin** 后，粘贴这个 URL，连接方式选择 `Server URL`，并选择 `Authentication: No Authentication / None`。表单可能默认显示 OAuth，请在创建前改为 No Authentication / None。
### 当前 Plugins UI
| 打开 Plugins 并点击 `+` | 填写 New Plugin 表单 |
| --- | --- |
|  |  |
以后同一个仓库日常启动只需要：
```bash
codexpro start
```
CodexPro 把 ChatGPT Developer Mode 变成本地仓库的 MCP 代码代理。ChatGPT 可以读取文件、搜索代码、查看 git 状态、写入或精确编辑文件，并运行安全范围内的验证命令。
CodexPro 不是速率限制绕过工具。它不会绕过、提升、合并、转售或修改 ChatGPT、Codex、OpenAI 或第三方模型的限制。它只是通过官方 Developer Mode / MCP App 路径，把你自己的 ChatGPT 会话连接到你自己的本地仓库。
如果 Codex 当前工作流暂时不可用，而你的 ChatGPT 页面仍然可用，CodexPro 可以让你继续在同一个本地仓库上工作。反过来也一样：ChatGPT 负责高上下文规划，Codex、OpenCode、Pi 或其他本地执行器负责终端里的实际执行。
## 多项目
在主项目的 profile 里明确加入其他项目：
```bash
codexpro settings set --project ~/code/web --project ~/code/api
codexpro start
```
`open_workspace` 会为当前 MCP session 选择一个已允许的项目。之后其他工具可以省略 `workspace_id`，直接使用当前选择。`open_current_workspace` 会切回启动时的主项目。
项目选择按 MCP session 隔离，但 ChatGPT conversation 是否一一对应独立 MCP session 由客户端决定。需要严格的进程隔离、不同权限或不同公网地址时，仍然应该启动多个 CodexPro 进程。
移除保存的额外项目：
```bash
codexpro settings set --clear-projects
```
## 重启发布版编码体验
- `view_image` 会把 PNG、JPEG、GIF、WebP 作为原生 MCP 图片内容返回，ChatGPT 可以直接检查截图和视觉资源。
- `read` 会返回 SHA-256。多个 session 可能同时修改一个文件时，把它作为 `expected_sha256` 传给 `write` 或 `edit`；文件已变化时操作会失败，不会静默覆盖新内容。
- 新文件采用同目录原子替换。已有文件会原位更新，以保留所有权、ACL、扩展属性和硬链接；如果写入期间机器或进程崩溃，文件内容可能不完整。
- `codexpro start --headless` 不会提问、复制链接、打开浏览器或显示终端控制面板。就绪后输出一行 `CODEXPRO_READY`，在本地运行状态中记录受监管的 runtime PID，收到信号时清理；HTTP runtime 意外退出时 launcher 以非零状态退出。
## 适合谁
CodexPro 适合已经有 ChatGPT Apps / Developer Mode 权限并希望做本地开发的人：
- 想让 ChatGPT Web 直接读取本地代码，而不是反复复制文件片段。
- 想把 `AGENTS.md`、`.ai-bridge`、git diff、源码文件这些 Codex 风格上下文给 ChatGPT。
- 想在 ChatGPT 里完成规划、审查、改小文件、跑安全验证。
- 想在某些模型不能调用工具时，导出一个持久上下文包给它做规划。
- 想把 ChatGPT 的计划交给 Codex、OpenCode、Pi 或自定义本地代理执行。
账号权限和具体模型界面的工具调用能力是两回事，而且可用范围可能变化。请以 ChatGPT 当前界面和 OpenAI 最新文档为准。
## 它能做什么
```text
ChatGPT Web 可以看到：
AGENTS.md
.ai-bridge 计划、状态和执行记录
git status
show_changes 审查摘要和可选 diff
文件树、搜索结果、指定源码文件
ChatGPT Web 可以操作：
read 读取文件
search 搜索代码
write 在工作区内写文件
edit 精确替换文本
bash 运行安全验证命令
show_changes 查看当前改动摘要
本地执行器仍然有价值：
Codex / OpenCode / Pi 执行计划
终端重任务留在本地
ChatGPT 回看执行结果和 diff
```
默认 `CODEXPRO_TOOL_MODE=standard`，只暴露常用编码循环、`codexpro_self_test`、`show_changes`、上下文导出和 handoff。演示时可以用 `--tool-mode minimal`，需要完整兼容工具时用 `--tool-mode full`。
默认工具数量较少是故意的：ChatGPT 面对少量高信号工具时更稳定。workspace open 默认不做 skill discovery；需要 repo-local skills 时传 `include_skills=true`，需要 user/plugin skills 时再加 `include_global_skills=true`。然后用 `load_skill` 按名称、source 和显示出的 path 加载需要的 `SKILL.md`；如果仍有重名匹配，CodexPro 会报歧义错误，不会随便选一个，也不会把几十个 skill 变成单独 action。
CodexPro 默认给 ChatGPT 暴露纯 MCP 工具描述，不附带 widget/card metadata。需要紧凑 v10 卡片时用 `CODEXPRO_TOOL_CARDS=1` 启动；workspace、分析、改动、Git、handoff 和 bash 验证会使用结构化卡片，read/search 保持为普通聊天输出。终端输出和 raw diff 会折叠或截断，避免在聊天里刷出大段原始数据。更新 connector 后，刷新一次 ChatGPT plugin connection 以加载新的 widget resource。`CODEXPRO_WIDGET_DOMAIN` 用于设置 ChatGPT widget iframe 的专用 HTTPS origin，正式提交 app 前应换成你控制的独立域名。
## 其他启动方式
不想全局安装时，也可以用：
```bash
npx codexpro@latest start --root /absolute/path/to/your/repo
```
但普通用户更推荐全局安装，这样命令就是固定的 `codexpro setup` 和 `codexpro start`。
## ChatGPT 中的 App 设置
先在 ChatGPT 打开 Developer Mode：
```text
ChatGPT Settings
-> Security and login
-> Developer mode: on
-> Enforce CSP in developer mode: on
ChatGPT Settings
-> Plugins
-> Plugins 标签页
-> 点击搜索框旁的 +
```
保留 CSP 开启。CodexPro 的卡片和小组件就是按 CSP 开启的路径设计的，不需要远程脚本、外部字体、iframe 或第三方图片。
在打开的 New Plugin 页面填写：
```text
Name: CodexPro
Description: Local workspace bridge for ChatGPT coding
Connection: Server URL
Server URL: 粘贴 CodexPro 自动复制的 URL
Authentication: No Authentication / None
```
表单可能默认显示 OAuth；请改为 `No Authentication / None`。复制的 Server URL 已经包含私有 `codexpro_token`。不要单独粘贴 token，除非你的 ChatGPT UI 明确支持自定义 header。
URL 中的 token 只适合作为个人 connector 的兼容方式。共享或多用户生产部署必须使用
OAuth 或 `Authorization: Bearer `。CodexPro
要求 token 至少 24 个字节；本地引导页加载后会从浏览器地址中移除 token 参数，并返回
`no-store` 和 `no-referrer` 安全 header。不要分享或提交完整 connector URL。
保持终端里的 CodexPro 进程运行。你停止它之后，ChatGPT 就无法继续连接本地仓库。Cloudflare quick tunnel 的 URL 也会失效。
## 三种主要模式
### 1. Normal coding
默认模式。ChatGPT 可以在工作区内读取、搜索、写入、精确编辑文件，并运行安全验证命令。
```bash
codexpro start
```
适合小改动、文档更新、定位 bug、查看 diff、跑 lint/test/build。
如果你正在另一个 Codex 会话里工作，不希望 ChatGPT 触发任何 shell 命令，用：
```bash
codexpro start --no-bash
```
如果想保留 bash，但要求 ChatGPT 明确命中你启动的这个 CodexPro 终端会话标签，用：
```bash
codexpro start --bash-session main --require-bash-session
```
开启后，`bash` 工具调用必须带上 `session_id: "main"` 才会执行。
### 2. Handoff
规划模式。ChatGPT 不直接写源码，只写入：
```text
.ai-bridge/current-plan.md
```
然后你在本地终端决定是否执行：
```bash
codexpro execute-handoff --agent opencode --model provider/model --dry-run
codexpro execute-handoff --agent opencode --model provider/model
```
也可以启动监听器，让本地终端在计划变更后执行：
```bash
codexpro start --mode handoff
codexpro start --mode handoff --no-bash
codexpro watch-handoff --agent opencode --model provider/model --yes
```
执行结果会写回：
```text
.ai-bridge/agent-status.md
.ai-bridge/implementation-diff.patch
.ai-bridge/execution-log.jsonl
```
然后让 ChatGPT 通过 `read_handoff` 或 `codex_context` 审查结果。
### 3. Pro context fallback
有些 ChatGPT 模型或产品界面不能直接调用 Developer Mode Apps、连接器或 MCP 工具。即使同一个符合条件的账号可以创建 CodexPro app，某个具体模型界面仍然可能没有工具调用能力。
这时不要强行让它调用工具。先导出一个持久上下文包：
```bash
codexpro pro-bundle --root /absolute/path/to/your/repo --copy
```
它会写入：
```text
.ai-bridge/pro-context.md
```
把这个上下文粘贴给不能调用工具的模型，让它产出窄范围实现计划。然后保存计划并应用：
```bash
codexpro pro-apply --root /absolute/path/to/your/repo --file plan.md
```
这会写入 `.ai-bridge/current-plan.md`，再交给 Codex、OpenCode、Pi 或自定义本地代理执行。
如果你的 ChatGPT 账号已经在 Web 产品里提供 GPT-5.5 或更强模型，并且该模型界面可以调用 Developer Mode Apps，CodexPro 可以让它通过 MCP 使用本地仓库工具。CodexPro 不提供、不代理、不转售、也不解锁模型。
## 稳定 URL 怎么选
ChatGPT App 需要一个可访问的 Server URL。你有三个常用选择：
```text
Cloudflare quick tunnel 最快演示路径。每次重启 URL 都变。
ngrok free dev domain 推荐给大多数用户。免费账号给一个稳定 dev domain。
Cloudflare named tunnel 适合已有自定义域名的用户。
```
### Cloudflare quick tunnel
最适合录 demo 或临时试用：
```bash
codexpro start
```
缺点很明确：quick tunnel 的 URL 每次重启都会变。如果你把 quick URL 放进 ChatGPT App，下一次启动时需要重新编辑 ChatGPT App 的 Server URL。
### ngrok free dev domain
推荐给大多数用户。创建一个免费 ngrok 账号，在 ngrok Dashboard 的 Universal Gateway -> Domains 找到你的 dev domain，比如：
```text
your-name.ngrok-free.dev
```
一次性认证 ngrok：
```bash
ngrok config add-authtoken YOUR_NGROK_TOKEN
```
保存到 CodexPro：
```bash
codexpro settings set --tunnel ngrok --hostname your-name.ngrok-free.dev
```
以后启动：
```bash
codexpro start
```
ChatGPT 里的 Server URL 可以保持不变。
### Cloudflare named tunnel
如果你有自己的域名，可以用 Cloudflare named tunnel：
```bash
cloudflared tunnel login
cloudflared tunnel create codexpro
cloudflared tunnel route dns codexpro codexpro.example.com
```
之后日常启动：
```bash
codexpro stable --hostname codexpro.example.com --tunnel-name codexpro
```
更多域名细节见 [DOMAIN_SETUP.md](DOMAIN_SETUP.md)。
## Codex 风格上下文
CodexPro 不读取 Codex 的隐藏运行时记忆。它给 ChatGPT 的是显式工作区上下文：
```text
open_current_workspace 当前 root、安全模式、AGENTS 状态、git 状态
codex_context AGENTS 链、.ai-bridge 文件、可选 git status/diff
read_handoff 只读 .ai-bridge 文件
workspace_snapshot 更大的项目快照和 handoff 上下文
```
`codex_context` 会读取从仓库根目录到目标路径上的指令文件：
```text
AGENTS.override.md
AGENTS.md
agents.md
.agents.md
```
并加入：
```text
.ai-bridge/current-plan.md
.ai-bridge/agent-status.md
.ai-bridge/implementation-diff.patch
.ai-bridge/codex-status.md
.ai-bridge/decisions.md
.ai-bridge/open-questions.md
.ai-bridge/execution-log.jsonl
git status
可选 git diff
```
推荐流程：
```text
先调用 server_config 和 codexpro_self_test
如果 self-test 失败，先停下来报告失败项
先调用 open_current_workspace，include_tree=false
再调用 codex_context，target_path 指向要改的文件，include_diff=false
然后只读取当前任务需要的文件
```
这样 ChatGPT 会更接近 Codex 的指令模型，同时不会依赖隐藏状态或大范围重复扫描。
## 安全边界
CodexPro 是本地开发桥，不是操作系统级沙箱。
默认安全行为：
- 公网 tunnel 默认需要私有 CodexPro token。
- 写入限制在配置的工作区 root 内。
- 常见敏感路径会被拒绝：`.env`、私钥、`.git`、`node_modules`、生成目录、缓存目录。
- symlink 逃逸会被阻止。
- safe bash 只允许常见检查、搜索、git、lint、test、typecheck、build 等命令。
- `codexpro start --no-bash` 会完全关闭 ChatGPT 可调用的 bash 工具。
- `execute-handoff` 和 `watch-handoff` 是本地 CLI 命令，不是远程 MCP 工具。
只有在你信任当前仓库和命令时，才考虑更宽的权限，例如 full bash、自定义执行器、额外 allow root。
### Codex 会话边界
CodexPro 不能绑定、读取或复用某一个 Codex App 会话 id。MCP 里的 session id 只是 ChatGPT 和 CodexPro HTTP 服务器之间的传输会话，不代表 Codex 里的某个聊天或终端会话。
`bash` 工具属于你启动的 CodexPro 本地服务器进程，并在配置的 workspace root 下运行。想并行处理另一个任务时，请为另一个仓库、端口或 tunnel profile 启动单独的 CodexPro；不要把它理解成“远程控制当前 Codex 会话”。
如果要减少误触发，可以给这个本地 CodexPro 进程设置 bash session guard：
```bash
codexpro start --bash-session main --require-bash-session
```
这不是 Codex App 聊天会话 id，而是 CodexPro 本地 bash 工具的显式匹配标签。
bash 结果默认使用紧凑 transcript，避免 ChatGPT 对话里突然铺开大段 stdout/stderr。完整 stdout/stderr 仍在结构化工具数据里，CodexPro 卡片里的输出预览默认折叠。需要旧行为时可以显式打开：
```bash
codexpro start --bash-transcript full
```
CodexPro 也可以在 full tools 下显式开启只读的本地 Codex 会话列表：
```bash
codexpro start --tool-mode full --codex-sessions metadata
codexpro start --tool-mode full --codex-sessions read
```
`metadata` 会增加 `codex_sessions` 工具，从 `~/.codex/sessions` 和 `~/.codex/archived_sessions` 读取本地 JSONL 历史，列出 session id、标题、cwd、来源文件和 `codex resume ` 命令。`read` 还会增加 `read_codex_session`，用于有限长度的 transcript 读取。它类似本地 session manager 扫描 Codex 历史文件，但仍然不会附加到正在运行的 Codex App 聊天，也不会在那个会话里执行命令或绕过产品限制。
如果 Codex 历史不在默认位置，可以用 `--codex-dir `。
如果只想让 ChatGPT 规划、由你本地决定是否执行：
```bash
codexpro start --mode handoff --no-bash
```
## 常用命令
```bash
codexpro setup
codexpro start
codexpro doctor
codexpro settings
codexpro settings list
codexpro settings set --tunnel ngrok --hostname your-name.ngrok-free.dev
codexpro settings delete --yes
codexpro pro-bundle --copy
codexpro execute-handoff --agent opencode --model provider/model --dry-run
codexpro watch-handoff --agent opencode --model provider/model --yes
```
终端控制键：
```text
Enter 打开 ChatGPT connector 设置
c 再次复制 Server URL
o 打开本地 admin dashboard
h 显示帮助
q 停止 CodexPro
```
本地 admin dashboard 是带 token 保护的 setup/settings 页面。它会显示当前 workspace、local MCP endpoint、安全模式、安装/启动命令、ChatGPT 连接步骤、saved profile 设置和 allowed roots。
页面也提供 GitHub、npm、docs 链接，以及 global install、guided setup、daily start、source checkout setup 和高级重启命令的复制按钮。它能修改下一次启动使用的 saved profile：tunnel provider、public hostname、port、mode、bash mode、transcript、Codex session 模式、write mode、tool mode、widget origin 和 tunnel config 路径。修改后需要重新运行 `codexpro start` 才会生效。
浏览器 admin 页面只负责 setup/settings/status 和 MCP endpoint；不能切换 ChatGPT 账号，不能直接保存原始 Cloudflare tunnel token，也不能把 CodexPro 作为后台服务开关。Cloudflare dashboard-managed tunnel 请把 token 放在本地文件里，再填写 Cloudflare token file。
## FAQ
中文常见问题见 [FAQ_ZH.md](FAQ_ZH.md)。
核心结论：
- 需要当前能访问自定义 MCP App 的 ChatGPT 账号和 Web 界面。
- 完整写入能力目前以 Business、Enterprise 和 Edu 为准；Pro 目前只支持 read/fetch 权限。
- CodexPro 不绕过任何速率限制。
- 某些 Pro / planning 模型界面不能直接连接 MCP 工具，使用 `pro-bundle` 作为上下文回退。
- quick tunnel 每次重启 URL 会变。
- 想每天同一个 URL，用 ngrok free dev domain 或 Cloudflare named tunnel。
## 开源与贡献
项目地址：[github.com/rebel0789/codexpro](https://github.com/rebel0789/codexpro)
欢迎提 issue、补文档、补平台兼容性、补测试。提交 PR 前请至少运行：
```bash
npm run build
npm run smoke
npm audit --omit=dev
```
如果 CodexPro 对你有用，请在 GitHub 点星。这样其他使用 ChatGPT、Codex、OpenCode、Pi 和 MCP 的开发者更容易找到它。