让 ChatGPT Web 看见你的本地仓库，并像本地代码代理一样工作。
English · 中文网站 · GitHub 点星 · npm · 稳定 URL 指南 · 中文 FAQ · 安全说明
## 安装 CodexPro 需要 Node.js 20+，以及能使用 Apps / Developer Mode 的 ChatGPT 账号。OpenAI 当前文档列出的 web 端 Developer Mode 账号范围包括 Pro、Plus、Business、Enterprise 和 Education。 先安装 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。到 ChatGPT 打开 `Settings -> Apps -> Advanced settings -> Create app`，粘贴这个 URL，并选择 `Authentication: No Authentication / None`。 以后同一个仓库日常启动只需要： ```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 或其他本地执行器负责终端里的实际执行。 ## 适合谁 CodexPro 适合已经有 ChatGPT Apps / Developer Mode 权限并希望做本地开发的人： - 想让 ChatGPT Web 直接读取本地代码，而不是反复复制文件片段。 - 想把 `AGENTS.md`、`.ai-bridge`、git diff、源码文件这些 Codex 风格上下文给 ChatGPT。 - 想在 ChatGPT 里完成规划、审查、改小文件、跑安全验证。 - 想在某些模型不能调用工具时，导出一个持久上下文包给它做规划。 - 想把 ChatGPT 的计划交给 Codex、OpenCode、Pi 或自定义本地代理执行。 当前测试显示，ChatGPT Free / Go 账号不暴露 CodexPro 需要的 Apps / Developer Mode 创建流程。请使用 ChatGPT 中能看到 Apps / Developer Mode 的账号层级。 ## 它能做什么 ```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。需要紧凑 v9 卡片时用 `CODEXPRO_TOOL_CARDS=1` 启动；server config、自测、workspace 摘要、读写 diff、bash 验证、git/tree/search/context 和 handoff/export 都有结构化视图。git、skills、tree、terminal 输出、context 和 raw diff 会折叠或截断，避免在聊天里刷出大段原始数据。`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 -> Apps -> Advanced settings -> Developer mode: on -> Enforce CSP in developer mode: on -> Create app ``` 保留 CSP 开启。CodexPro 的卡片和小组件就是按 CSP 开启的路径设计的，不需要远程脚本、外部字体、iframe 或第三方图片。 在 Create App 页面填写： ```text Name: CodexPro Description: Local workspace bridge for ChatGPT coding Connection: Server URL Server URL: 粘贴 CodexPro 自动复制的 URL Authentication: No Authentication / None ``` 复制的 Server URL 已经包含私有 `codexpro_token`。不要单独粘贴 token，除非你的 ChatGPT UI 明确支持自定义 header。 保持终端里的 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