Skip to main content
Glama
Gemini Codex Gateway

Gemini Codex Gateway

by HaKuLaMeTAT
README.md
# Gemini Codex Gateway

给 Gemini 自定义应用使用的 MCP 网关。它在 Linux 或 WSL 中直接读写已登记的项目文件,也可以把用户明确委派的任务交给本机 Codex CLI。

## 项目背景

这个网关起初用于从手机上的 Gemini 使用一台 WSL 开发机。普通读写由文件工具完成,可按项目名访问原目录。需要开发、运行测试或审查时,Gemini 可以把任务交给本机 Codex,再通过任务 ID 查询结果。

项目文件、进程和任务状态留在运行网关的机器。Gemini 和 Codex 的模型服务仍在各自的服务端运行。授权读取的文件内容和任务输出会传回调用方。常见部署方式是使用 HTTPS 隧道,将公网请求转发到本机回环地址上的网关。

```text
Gemini → HTTPS 反向代理或隧道 → 127.0.0.1:8765/mcp
                                   ├─ 项目文件工具
                                   └─ 本机 Codex CLI
```

## 安装前准备

- Linux 或 WSL2、Python 3.12 或以上、Git,以及已登录的 [Codex CLI](https://learn.chatgpt.com/docs/cli/reference)。本版本在 Ubuntu WSL 和 Codex CLI 0.171.0 上验证。
- 一个可以转发至网关的公网 HTTPS 域名。网关只监听 `127.0.0.1:8765`。如果使用 Cloudflare Tunnel,将对应的主机名转发至 `http://127.0.0.1:8765`。如果连接器和网关分别在 Windows 与 WSL,先确认连接器能访问该回环端口。
- 支持自定义应用的 Gemini 账号。添加应用在 Gemini 网页版完成,关联后可以在网页版和手机端使用。 [Google 自定义应用说明](https://support.google.com/gemini/answer/17209137)

## 安装和关联

### 1. 安装依赖与登记项目

把本仓库克隆到 `~/src/gemini-codex-gateway`,在 WSL 或 Linux 终端运行:

```bash
cd ~/src/gemini-codex-gateway
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

install -d -m 700 ~/.config/gemini-codex-gateway
install -m 600 examples/projects.example.json ~/.config/gemini-codex-gateway/projects.json
```

编辑 `~/.config/gemini-codex-gateway/projects.json`,把 `allowed_root` 指向项目存放目录,例如 `~/projects` 或 WSL 中的挂载盘 `/mnt/d`。把示例 `sample` 的 `directory` 改为已存在的项目目录,并确认 `default` 对应登记名。每个项目目录须位于 `allowed_root` 内。

新登记项目默认可读写。项目只需访问文件时可以设 `"writable": false`。如果登记的是多个仓库共享的上级目录,并且需要从该目录运行 Codex,可以对这个条目设置 `"allow_non_git": true`。需要指定 nvm 安装的 Node.js 时,可加 `"node_version": "v22.22.1"`,该版本须已安装。

### 2. 配置 OAuth

默认可用 GitHub OAuth 登录来验证所有者身份。网关用 GitHub 的账户 ID 匹配允许使用文件与任务工具的账号,GitHub OAuth 应用不会获得项目仓库访问权限。

1. 在 GitHub 的开发者设置创建 OAuth App。Homepage URL 填自己的公网 HTTPS 地址,例如 `https://mcp.example.com`。Authorization callback URL 填 `https://mcp.example.com/auth/callback`。 [GitHub OAuth App 创建说明](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app)
2. 运行配置助手,按提示输入自己的 GitHub 用户名、OAuth Client ID 和 Client Secret:

   ```bash
   .venv/bin/python configure_oauth.py github --public-url https://mcp.example.com
   ```

3. 如果使用 Google OAuth,则准备 Google Web OAuth Client JSON,将同一 `/auth/callback` 注册给该客户端,运行 `configure_oauth.py google --public-url https://mcp.example.com`。配置助手会询问唯一允许访问的 Google 账号。

配置助手把 OAuth 配置和随机生成的签名密钥写到 `~/.config/gemini-codex-gateway/oauth.json`,文件权限为 `0600`。

### 3. 启动网关并添加 Gemini 应用

先前台启动查看日志:

```bash
.venv/bin/python gateway.py
```

1. 在 Gemini 网页版的「已连接应用 → 自定义应用」添加 `https://mcp.example.com/mcp`。
2. 首次注册时,网关会拒绝尚未获批的回调,并在日志输出 `Unapproved Gemini callback` 及对应地址。确认这条日志由自己的添加操作产生,把完整地址加入本地 `oauth.json` 的 `gemini_redirect_uris` 数组。后续如果当前应用还需其他回调,依次核对并加入。也可以在配置助手中用可重复的 `--gemini-redirect-uri` 参数预先登记已知地址。
3. 重新启动网关,在 Gemini 重试关联并完成上游 OAuth 登录。允许列表仅接受完整的 Gemini 回调地址。
4. 关联成功后,在 Gemini 对话里从 `@` 菜单选中 `WSL Codex`,请求列出 `projects/` 验证。

日常用 systemd 管理时,先结束前台进程。若仓库在不同目录,先编辑服务样例的 `WorkingDirectory` 和 `ExecStart`。

```bash
install -D -m 644 examples/gemini-codex-gateway.service ~/.config/systemd/user/gemini-codex-gateway.service
systemctl --user daemon-reload
systemctl --user enable --now gemini-codex-gateway.service
journalctl --user -u gemini-codex-gateway.service -n 50
```

## 使用说明

| 职责 | 工具 | 示例和约定 |
| --- | --- | --- |
| 列项目、浏览和读取 | `read_workspace_file` | `projects/` 列出项目,`sample/` 列出目录,`sample/README.md` 读取文件。返回 `next_offset` 时,用它和 `file_version` 分段继续。 |
| 写 UTF-8 文件 | `write_workspace_file` | 创建文件用项目相对路径。覆盖文件时带上读取第一段返回的 `sha256`,作为 `expected_sha256`。 |
| 委派 Codex | `submit_codex_task` | 明确说「让 Codex 只读评审 sample 当前改动」。使用 `project` 选择项目。设置相对 `workdir` 可在项目的某个子目录启动。 |
| 查询或续跑 | `codex_task_status` | 按任务 ID 查询模型、耗时和结果。若 `can_resume` 为 true,可以明确要求继续,并用 `previous_task_id` 和原项目、工作目录与读写模式接续。 |

日常任务默认使用 GPT‑6.2 Sol,复杂工作和评审用 GPT‑6.2 Astra,重复性代码任务可用 GPT‑6 Luna。用户可以显式选择模型和推理强度。后台执行上限为 15 分钟,客户端可按任务 ID 查询。任务改动直接写到所选项目的原工作区。

## 数据位置、升级与回滚

| 数据 | 默认位置 |
| --- | --- |
| 项目、OAuth 与签名密钥 | `~/.config/gemini-codex-gateway/` |
| 本地任务记录、OAuth 状态和进程锁 | `~/.local/state/gemini-codex-gateway/` |
| Codex 登录和会话 | 由本机 Codex CLI 管理。 |

可以通过 `XDG_CONFIG_HOME` 和 `XDG_STATE_HOME` 指定配置与状态基目录,通过 `CODEX_BINARY` 指定 Codex 可执行文件的绝对路径。部署文件、备份与日志均保存在部署主机。

升级前等待后台任务完成,获取 Git 标签,切换到目标版本并刷新虚拟环境依赖,再重启 systemd 服务。回滚时切回上一标签,按需安装对应版本的依赖并重新启动。保留配置和运行状态的本地备份。版本变更记录见 [CHANGELOG](CHANGELOG.md)。

公网返回 Cloudflare `530/1033` 时,检查隧道连接器是否在线。访问网关 `/.well-known/oauth-authorization-server` 可验证公网 OAuth 发现,未携带令牌的 `POST /mcp` 应返回 `401`。 [Cloudflare 1033 排查](https://developers.cloudflare.com/support/troubleshooting/http-status-codes/cloudflare-1xxx-errors/error-1033/)

## 许可证

采用 [MIT](LICENSE) 许可证。