Skip to main content
Glama
Gemini Codex Gateway

Gemini Codex Gateway

by HaKuLaMeTAT

Gemini Codex Gateway

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

项目背景

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

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

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

Related MCP server: AKIMCP

安装前准备

  • Linux 或 WSL2、Python 3.12 或以上、Git,以及已登录的 Codex CLI。本版本在 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 自定义应用说明

安装和关联

1. 安装依赖与登记项目

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

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 创建说明

  2. 运行配置助手,按提示输入自己的 GitHub 用户名、OAuth Client ID 和 Client Secret:

    .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 应用

先前台启动查看日志:

.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。

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。

公网返回 Cloudflare 530/1033 时,检查隧道连接器是否在线。访问网关 /.well-known/oauth-authorization-server 可验证公网 OAuth 发现,未携带令牌的 POST /mcp 应返回 401。 Cloudflare 1033 排查

许可证

采用 MIT 许可证。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Exposes a governed suite of 38 tools over one OAuth-gated MCP endpoint so web AI chat clients can read and edit files, run whitelisted shell commands, search, query Git/SQLite, drive browsers via DevTools, and manage background jobs on the local machine. Remote access runs through Tailscale Funnel while local tools connect straight to 127.0.0.1, keeping operations permission-scoped rather than granting unrestricted shell access.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      An OAuth-gated MCP endpoint that lets web-based AI chat clients such as Claude, ChatGPT, Grok, and Postman operate a local machine through a governed suite of 38 tools covering files, shell, search, Git, SQLite, browser automation, DevTools, background tasks, localhost services, clipboard, notifications, ports, and Postman control. It enables browsing, editing, running, and debugging projects from the browser without granting every client unrestricted shell access.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Exposes an OAuth-gated MCP endpoint with 38 governed tools that let web-based AI chat clients read and edit local files, run whitelisted shell commands, search, use Git and SQLite, fetch localhost/intranet APIs, automate Chromium and DevTools, and manage background tasks, ports, clipboard, notifications, and Postman. Local IDEs can connect directly over 127.0.0.1, while remote clients reach the same machine through a secure public ingress.
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables web-based AI clients like Claude, ChatGPT, and Grok to securely operate a local machine through OAuth-gated MCP tools covering files, shell, Git, databases, browser automation, and background tasks.
      MIT