内容
# codex-gpt-桥接
## 概要
这是一个小型MCP桥接项目，用于ChatGPT/OpenAI模型与本地Codex之间进行双向通信。
## 桥接功能
- ChatGPT -> Codex: ChatGPT可以作为规划者，而本地HTTP MCP服务器将范围内的执行请求转发给在您的机器上运行的官方`codex mcp-server`。
- Codex -> ChatGPT类似模型：Codex可以调用一个名为`chatgpt`的本地stdio MCP服务器，该服务器将明确的提示转发给官方的OpenAI响应API。
## 重要边界
Codex -> 模型方向不调用ChatGPT网页或ChatGPT私有产品后端。它使用官方的OpenAI API，因此需要`OPENAI_API_KEY`和API模型访问。
## 日常使用
是的，这是MCP。ChatGPT将`本地Codex桥接安全`视为一个具有五个MCP工具的应用：
- `bridge_status`
- `codex_read`
- `codex_run`
- `codex_reply`
- `codex_job_status`
### ChatGPT角色：顾问和评审
将外部ChatGPT视为顶级顾问，而不是本地执行者。
它的两个最佳工作是：
1. 执行前：通过`codex_read`检查足够的仓库上下文，然后编写计划、风险、工作订单和成功检查。
2. 执行后：作为独立的批判性评审员。它应该通过`codex_read`读取更改的文件或差异，并返回`PASS`或具体的阻塞因素。
本地Codex仍然负责执行：编辑文件、运行测试、编译、渲染、检查差异和提交。保持ChatGPT工具调用的范围狭窄，以便它能够很好地推理，并且桥接保持稳定。
顾问提示：
```text
@本地Codex桥接安全 调用 codex_read，只传 prompt：你是这个项目的顶层顾问。只读调查当前允许的根目录，先列出与任务相关的仓库事实，然后给出整体方案、执行顺序、风险、验收标准，以及可以交给Codex执行的下一步指令；不要修改任何文件。
```
评审提示：
```text
@本地Codex桥接安全 调用 codex_read，只传 prompt：你是独立的批判性评审员。只读复查当前改动是否满足计划；不要修改、不要编译、不要运行shell。只输出状态：PASS/NEEDS_CHANGES、阻塞因素、证据、下一个指令。
```
最佳日常路径是OpenAI安全MCP隧道。一次性设置后，使用密钥链支持的启动器保持本地守护进程运行：
```bash
cd /path/to/codex-gpt-bridge
npm run bridge:chatgpt:secure:keychain
```
将`/path/to/...`示例替换为自己的绝对本地路径。
如果安装为macOS LaunchAgent，则无需终端步骤。直接使用ChatGPT：
```text
@本地Codex桥接安全 调用 codex_read，只传 prompt：调查当前项目顶层有哪些文件和目录，说明每个重要文件的用途；不要修改任何文件。
```
### 提示模板
通常只需要应用名称和任务。如果桥接器只有一个允许的根目录，`codex_read`将自动使用该根目录，并且始终强制Codex `只读`。仅在您故意启动写入模式时使用`codex_run`。
### 固定代理流程
使用此流程。不要猜测工具名称或传递额外的参数。
1. 确认应用可以访问桥接器：
```text
@本地Codex桥接安全 调用 bridge_status。只返回 allowedRoots、defaultCwd、defaultSandbox、allowWorkspaceWrite、allowDangerFullAccess、upstreamTools。
```
2. 对于只读调查，调用`codex_read`并仅传递`prompt`：
```text
@本地Codex桥接安全 调用 codex_read，只传 prompt：<您的任务>; 不要修改任何文件。
```
3. 如果结果包含`status=running`，复制确切的`jobId`并显式查询它：
```text
@本地Codex桥接安全 调用 codex_job_status，只传 jobId：<确切的 jobId>
```
4. 仅在完成读取/运行返回`threadId`后使用`codex_reply`。
5. 仅在故意启动写入模式工作后，使用`codex_run`，并重启具有狭窄`CODEX_GPT_BRIDGE_ROOT`的桥接器。
6. 如果ChatGPT表示自动轮询被阻止，请不要重试相同的模糊指令。粘贴确切的`jobId`。
状态检查：
```text
@本地Codex桥接安全 调用 bridge_status。只返回 allowedRoots、defaultCwd、defaultSandbox、allowWorkspaceWrite、allowDangerFullAccess、upstreamTools。
```
检查仓库中的文件：
```text
@本地Codex桥接安全 调用 codex_read，只传 prompt：调查当前允许根目录的顶层文件和目录，说明每个重要文件的用途；不要修改任何文件。如果返回 status=running 和 jobId，请继续调用 codex_job_status 直到 completed 或 failed。
```
如果`codex_read`或`codex_run`返回`status=running`，请轮询作业：
```text
@本地Codex桥接安全 调用 codex_job_status：jobId=<作业 ID>
```
ChatGPT可能会在尝试自行重用前一个工具结果的`jobId`时阻止自动链接轮询。如果发生这种情况，请将确切的`jobId`粘贴到下一个提示中：
```text
@本地Codex桥接安全 调用 codex_reply：
threadId=<线程 ID>
prompt=继续上一轮，只读检查 README.md 和 docs/chatgpt-setup.md 是否解释清楚日常用法；不要修改任何文件。
```
对于不同的项目，请重启桥接器，将该仓库作为唯一允许的根目录：
```bash
CODEX_GPT_BRIDGE_ROOT="/绝对路径/到/项目" npm run bridge:chatgpt:secure:keychain
```
对于编辑，请保持根目录狭窄，并仅为目标仓库启动写入模式：
```bash
CODEX_GPT_BRIDGE_ROOT="/绝对路径/到/项目" npm run bridge:chatgpt:secure:write:keychain
```
然后在ChatGPT中：
```text
@本地Codex桥接安全 调用 codex_run，只传 prompt：在当前允许根目录内修改我的简历。先检查相关文件，说明计划，然后执行最小改动并运行可用检查。
```
对于迭代审查/编辑循环，请保持每个工具调用狭窄：
1. `codex_read`：要求Codex检查文件并返回具体的编辑计划。
2. `codex_run`：要求Codex应用一个狭窄的编辑集。不要要求它编译、运行长shell命令或在同一个桥接调用内进行广泛清理。
3. 从Codex或终端本地验证：编译、渲染、运行测试并检查差异。
4. `codex_read`：通过ChatGPT发送更新的文件进行审查。
5. 仅在ChatGPT返回真正的阻塞因素时重复。
稳定编辑提示：
```text
@本地Codex桥接安全 调用 codex_run，只传 prompt：只修改当前允许根目录内的 <文件>。按上一轮建议进行最小改动；不要编译、不要运行shell、不要改其他文件。完成后只总结改了什么。
```
稳定最终审查提示：
```text
@本地Codex桥接安全 调用 codex_read，只传 prompt：只读复查 <文件> 是否已经解决上一轮阻塞因素；不要修改、不要编译、不要运行shell。只输出状态：PASS/NEEDS_CHANGES、阻塞因素、备注。
```
一次性安全设置需要：
```bash
security add-generic-password -a "$USER" -s "codex-gpt-bridge:control-plane-api-key" -w "<运行时API密钥>" -U
security add-generic-password -a "$USER" -s "codex-gpt-bridge:control-plane-tunnel-id" -w "tunnel_..." -U
```
然后使用连接 = `隧道`、匹配的隧道ID和身份验证 = `无身份验证`配置ChatGPT。
较旧的Cloudflare快速隧道路径仍然存在于烟雾测试，但它不是推荐的日常工作流程，因为URL会更改并且可以失败DNS。
## 为什么
Codex已经附带了一个stdio MCP服务器，带有两个有用的工具：
- `codex`：启动本地Codex会话。
- `codex-reply`：通过线程ID继续Codex会话。
ChatGPT应用/ GPT需要一个HTTP可访问的MCP端点。这个项目是一个小型适配器：HTTP MCP输入，官方Codex MCP输出，中间带有本地安全策略。
对于另一个方向，Codex已经可以连接到stdio MCP服务器。这个项目添加了`codex-chatgpt-mcp`，一个小型MCP服务器，公开一个工具，`ask_chatgpt`，由OpenAI响应API支持。
## 安全默认值
- 默认绑定到`127.0.0.1`。
- 仅在配置的根目录下接受`codex_read.cwd`和`codex_run.cwd`。
- 默认使用Codex `只读`沙盒。
- 需要`CODEX_GPT_BRIDGE_TOKEN`或显式本地`CODEX_GPT_BRIDGE_NO_AUTH=1`。
- 不暴露原始shell、进程控制、完整的Codex应用服务器或任意Codex配置。
- 当在请求的当前工作目录下存在类似敏感文件的`.env`、私钥或`.pem`文件时，阻止委托。
- 仅允许`codex_reply`用于通过此桥接器首次创建的线程，并在继续它们之前重新运行敏感文件预检。
- 除非设置`CODEX_GPT_BRIDGE_ALLOW_WRITE=1`，否则阻止`workspace-write`。
- 不将`danger-full-access`作为每个调用的ChatGPT选项公开。
## 安装
```bash
npm install
npm run build
```
Codex CLI必须安装并登录：
```bash
codex --version
codex mcp-server --help
```
## Codex -> ChatGPT类似模型
首先设置OpenAI API密钥：
```bash
export OPENAI_API_KEY="<openai-api-key>"
export CODEX_CHATGPT_MODEL="gpt-5.5"
```
此仓库包括一个项目范围的Codex MCP配置，位于`.codex/config.toml`：
```toml
[mcp_servers.chatgpt]
command = "npm"
args = ["run", "chatgpt:mcp"]
env_vars = ["OPENAI_API_KEY", "OPENAI_BASE_URL", "CODEX_CHATGPT_MODEL", "CODEX_CHATGPT_TIMEOUT_MS"]
```
在为此受信任的项目打开新的Codex线程后，Codex应该有一个`chatgpt` MCP服务器，具有一个工具：
- `ask_chatgpt`：向配置的OpenAI API模型发送明确的提示并返回文本。可选的`reasoningEffort`值为默认的`gpt-5.5`模型为`none`、`low`、`medium`、`high`和`xhigh`。
## 在本地运行
从您希望ChatGPT委托到的仓库：
```bash
CODEX_GPT_BRIDGE_NO_AUTH=1 \
CODEX_GPT_BRIDGE_ROOTS="$PWD" \
npm run dev
```
服务器：
```text
http://127.0.0.1:8765/mcp
```
对于非本地绑定：
```bash
export CODEX_GPT_BRIDGE_TOKEN="$(openssl rand -hex 32)"
CODEX_GPT_BRIDGE_HOST=0.0.0.0 \
CODEX_GPT_BRIDGE_ROOTS="/Users/me/project" \
npm run start
```
使用`Authorization: Bearer <token>`从您的MCP客户端。
当通过HTTPS隧道公开本地服务器时，请保持桥接器绑定到`127.0.0.1`，并显式允许隧道主机，以便MCP SDK DNS重新绑定保护接受转发的`Host`标头：
```bash
CODEX_GPT_BRIDGE_ALLOWED_HOSTS=127.0.0.1,localhost,your-tunnel.example.com \
CODEX_GPT_BRIDGE_NO_AUTH=1 \
CODEX_GPT_BRIDGE_ROOTS="/Users/me/project" \
npm run start
```
仅在短暂的本地/隧道烟雾测试中使用无身份验证。对于持久使用，请在桥接器前面放置OAuth或受信任的身份验证代理。
## ChatGPT连接
对于ChatGPT应用/ GPT，公开本地MCP端点与以下之一：
- OpenAI安全MCP隧道。
- Cloudflare隧道。
- ngrok。
然后将ChatGPT应用/连接器MCP URL配置为HTTPS `/mcp`端点。尽可能保持桥接器绑定到本地主机，并在其上放置隧道。
内置的承载令牌身份验证旨在用于本地开发、手动MCP客户端或受信任的代理。需要受保护工具身份验证的生产ChatGPT应用应在桥接器前面添加OAuth 2.1 / PKCE层；OAuth未在v0.1中实现。
## 暴露给ChatGPT的工具
### `bridge_status`
报告桥接策略、允许的根目录和上游Codex MCP工具可用性。
### `codex_read`
在允许的工作目录中启动只读Codex检查。这是仓库调查和规划上下文的默认日常工具。
它接受与`codex_run`相同的`prompt`、可选`cwd`和可选`timeoutMs`字段，但不接受沙盒选项。桥接器始终转发`sandbox=read-only`。
长读取使用与`codex_run`相同的`status=running` + `jobId`流程。
### `codex_run`
在允许的工作目录中启动Codex会话。使用此功能进行写入模式工作流；优先使用`codex_read`进行只读调查。
如果Codex快速完成，工具直接返回Codex结果。如果Codex运行时间超过`CODEX_GPT_BRIDGE_FAST_RETURN_MS`（默认为25秒），则工具返回：
```json
{
"status": "running",
"jobId": "..."
}
```
使用该`jobId`调用`codex_job_status`直到作业完成或失败。
必填：
- `prompt`
可选：
- `cwd`：默认为唯一配置的允许根目录；当配置多个根目录时需要。
- `sandbox`：默认为`read-only`；仅当桥接器所有者启动写入模式时出现`workspace-write`。
- `timeoutMs`
### `codex_reply`
继续通过此桥接器首次创建的Codex会话。
必填：
- `threadId`
- `prompt`
桥接器拒绝未知线程ID，并在转发回复之前对原始会话目录重新运行敏感文件预检。
长回复使用与`codex_run`相同的`status=running` + `jobId`流程。
### `codex_job_status`
检查长运行的`codex_read`、`codex_run`或`codex_reply`作业。
必填：
- `jobId`
跟踪的会话仅在内存中，限制为1000条记录，6小时后过期。重启桥接器会清除它们。
## 开发
```bash
npm run check
```
测试使用假上游，不调用真实模型。
