Codex Native Agent Hub

A unified Codex MCP bridge and local panel for Gemini / Antigravity, Claude Code, and DeepSeek Harness, with isolated worktrees and live task progress.

在 Codex 右侧完成模型接入、任务委派、进度查看与变更检查。三种模型分别使用自己的原生编码运行环境，连接配置和 API Key 独立保存。

Windows x64 · Python 3.11+ · Git · MCP stdio · MIT

Codex / 本地面板
       │
       ├─ Gemini   → Antigravity SDK
       ├─ Claude   → Claude Code / Agent SDK
       └─ DeepSeek → DeepSeek Harness / dsh SDK
                         │
                   对应原生协议的模型服务

这是通过 MCP 接入的外部代理服务。右侧界面是本项目的本地网页，模型返回结果后由 Codex 检查。它不会把第三方模型注册为 Codex 内部的 spawn_agent 模型，也不需要修改 Codex 客户端。

能做什么

• 在一个面板中为三种代理分别设置 Base URL、Key、模型和适用的推理强度。

• 从中转站拉取模型列表，保留准确 ID，搜索、选择或为本次任务覆盖模型。

• 可为每个代理开启「自动选择适配模型」（默认关闭），由 Codex 判断复杂度后按模型名称为单次任务选型。

• 按原生协议测试基础生成；通过任务验证流式响应与真实文件工具。

• 默认只读审查；编辑任务默认创建独立 Git worktree，保留变更供检查和合并。

• 查看实际阶段、工具活动、调用次数、耗时、结果和历史；支持取消与超时。

• 每个服务实例最多同时运行两个任务，每个任务限制 40 次模型调用、100 次工具调用。

• Windows DPAPI 按当前用户加密凭据；状态、会话和 worktree 默认存储在仓库外。

原生运行环境提供各自的系统提示、工具与执行流程；实际效果仍取决于模型、任务和中转站兼容性。

Related MCP server: Pair

安装

准备 Windows x64、Python 3.11+、Git 和可在终端使用的 Codex CLI。

git clone https://github.com/sdpd2333/codex-native-agent-hub.git
cd codex-native-agent-hub
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install.ps1

脚本创建项目内 .venv，安装固定版本的三套 SDK，并注册名为 native-agent-hub 的 MCP 服务。路径按实际安装位置生成。已有的 gemini-antigravity 服务不会被覆盖。

固定版本的 Windows SDK 包含各自所需的原生运行组件，无需另外安装 agy、Gemini CLI、Claude Code CLI 或 dsh 命令行。首次安装仍需下载 Python 依赖和运行组件；它们不会提交到本仓库。

仅安装依赖，不注册 MCP：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -SkipMcpRegistration

从右侧面板开始

重新加载 Codex 的 MCP 服务，或重新打开 Codex，然后说：

打开 native-agent-hub 的统一面板，放在右侧，项目目录使用当前项目。

Codex 调用 get_panel(project_dir=项目绝对路径)，再通过桌面应用的 open_in_codex 打开返回的 URL，设置 target.type="browser"、placement="right"。普通 MCP 客户端也可在浏览器打开同一面板。

1. 在「连接设置」选择 Gemini、Claude 或 DeepSeek。

2. 填写该代理使用的 Base URL 和 API Key，点击「拉取模型」，选择完整模型 ID 后保存。

3. 「测试基础生成」会发送一条简短请求，使用少量服务额度。

4. 在「新建任务」选择代理、项目、模式和目标，先用小型只读任务验证工具兼容性。

5. 在「任务进展」查看活动和结果；编辑任务可「查看变更」，读取 worktree 路径、分支与差异。

三套配置可以指向同一中转站，也可指向不同服务；Key 不会在代理之间自动复用。更换地址时必须重新填写 Key。任务提交时固定当时的配置，之后保存设置只影响新任务。

双击 configure.cmd 会在普通浏览器打开面板。也可手动启动：

.\.venv\Scripts\python.exe -B server.py --panel --project-dir C:\Projects\my-app

加 --no-browser 只输出本机面板地址。服务结束后旧地址失效，重新获取即可。

自动选择适配模型

在「连接设置」为需要的代理勾选「自动选择适配模型」并保存。三种代理独立设置，旧配置升级后也默认关闭。开启后，无需在每次对话中指定模型，例如直接说「让 Gemini 调整这个页面的按钮样式」。Codex 根据范围、风险和不确定性判断 task_complexity；服务从该代理的实时模型列表中匹配完整 ID，只覆盖当前新任务。

默认名称规则按代理分别处理：

• Gemini：版本号优先，其次匹配能力档位。 Flash 为快速档（Flash Lite 也归入快速档），Pro / Ultra / Argon 为高能力档；不再单独识别 Lite / Nano 轻量档。先从这些通用编码候选中限定最高可解析版本，再按上表选型。因此，只有 gemini-4-pro 和 gemini-3.8-flash 时，简单任务也会优先使用 gemini-4-pro；如果同为 4 版本，简单/常规任务优先 Flash，复杂任务只选择高能力档。最高版本没有复杂任务所需的高能力型号时保留默认模型，不回到旧版本重新选型。版本优先于稳定/预览标记，所以较新预览版也会排在旧稳定版前面。

• Claude：保持现有设置。 Haiku 为快速档、Sonnet 为均衡档、Opus / Fable 为高能力档。先按任务档位顺序选择，同档优先稳定版，再比较系列档位和版本号，同分优先已保存模型。

• DeepSeek：自动候选仅保留 Flash 快速档。 简单、常规和复杂任务均在 Flash 型号中选择；不再自动识别 Lite / Chat / V3 / Pro / Reasoner / R1 档位。同档优先稳定版，再比较版本号，同分优先已保存模型。没有可用 Flash 时保留默认模型，其他型号仍可手动指定。

Gemini 最高版本内的同档排序也优先稳定版，再比较系列档位，同分优先已保存模型。无法解析版本号的别名不优先于有明确版本号的型号；若全部候选都无法解析版本，则直接按任务档位顺序选择。发布日期、上下文长度和参数规模不作为版本号；中转站的完整原始 ID 保持不变。

仅识别对应代理的家族名称和少数明确别名（例如 Gemini 配置下的 3.8flash）。不自动选择其他家族、嵌入/图片/音视频等专用模型，无法识别的名称留给手动指定。列表拉取失败或没有合适档位时使用保存的默认模型。规则是名称启发式，不读取价格、不承诺实际能力或工具兼容性，也不会自动重试升级。

你在对话或「本次模型」中明确指定的 ID 始终优先；自动选型不会修改默认模型、切换代理或改变保存的推理强度。任务详情会显示实际模型、选型方式和原因。面板手动新建任务时由你选择复杂度；服务本身不会额外调用模型分析任务。

MCP 客户端需重新加载服务以获取新参数和策略。get_configuration 返回每个代理的开关及 model_selection_policy，list_models 额外返回名称分类。开启自动选型且未指定 model 时，submit_task 必须提供 task_complexity；关闭时仍直接使用默认模型。不要调用 select_model 实现临时选型。

自定义策略

策略集中在项目根目录的 model_selection.py，可直接编辑。 配置面板的「自定义选型策略」也会指出此位置。

例如，希望 Claude 的常规开发优先用 Haiku，可以把 PREFERENCES["claude"] 中的 standard 改为：

"standard": ("fast", "balanced", "strong"),

若希望 Gemini 恢复为先按档位、再比较版本，可将其从 VERSION_FIRST 中移除（例如设为 set()）。新增模型系列时，在对应代理的 NAME_RULES 中加入提示词和档位，例如 ("newseries", "balanced")；默认只自动识别对应代理家族，完全自定义的别名还需调整 describe_model 的别名识别。修改后重新加载 MCP 服务，并重启面板，再运行单元测试确认符合你的预期。修改这些规则不会更改已保存的默认模型或已经启动的任务。

中转站的协议要求

此处固定的 dsh 版本使用 Messages 协议。只提供 OpenAI /chat/completions 的路径不够。 根据你的服务商提供的兼容端点填写地址；不能仅凭模型名称判断协议。

Base URL 使用 HTTPS，可保留服务商要求的路径前缀。末尾 /v1 或 /v1beta 会被归一化，再添加对应接口路径。模型列表优先使用 /v1/models，Claude 支持分页；Gemini 必要时回退 /v1beta/models。

列表中可见、基础生成成功，均不能保证完整代理流程可用。SDK 会发送工具定义和流式请求，需要中转站完整转发。当前 DeepSeek 只读模式使用精简原生配置，尚不提供目录搜索工具；可在任务中指定需要读取的文件。编辑模式使用完整编码工具配置。

编辑任务与 worktree

edit 默认以源仓库当前 HEAD 创建独立分支 agent-hub/<代理>/<任务ID> 与 worktree，因此源仓库必须干净、已有提交。两个任务使用不同目录，避免直接覆盖彼此的修改。worktree 从已提交内容开始，未跟踪、忽略的文件和已安装依赖不会自动复制；必要时可在任务中要求安装依赖。

源项目有未提交更改或不是 Git 仓库时，可以先处理仓库状态，或在面板中明确选择「直接编辑项目目录」。只读任务始终读取指定目录，无需 Git。

任务结束、失败、取消或超时后，worktree 及已发生的修改都会保留。面板与 get_changes 返回已跟踪文件相对起点的差异和新增文件名；新增文件内容需要在工作区进一步查看。不会自动提交、合并或清理。

检查结果与测试后，可手动将需要的修改提交并 cherry-pick 到源分支：

git -C <worktree路径> diff
git -C <worktree路径> status --short
# 选择文件后提交，再在源项目中 cherry-pick 该提交。

review 通过原生工具白名单禁用写入与命令执行。edit 允许文件修改和命令执行；worktree 用于隔离版本变更，不是操作系统沙箱。只对你授权的任务开放编辑模式。

在对话中委派

用 native-agent-hub 的 Claude 审查当前项目。先读取配置，再以 review 模式提交，最后核实发现的问题。

将这个模块的实现交给 DeepSeek，通过 dsh 执行。允许修改代码和运行测试，使用独立 worktree。完成后检查 get_changes 和测试结果。

submit_task 参数包括 task、绝对路径 project_dir、backend=gemini|claude|deepseek、mode=review|edit、可选 model、可选 task_complexity=simple|standard|complex、workspace_mode=worktree|direct、timeout_seconds。默认 Gemini、review、worktree，超时 600 秒（可设 10–1800 秒）。

凭据与本地数据

默认状态目录：%LOCALAPPDATA%\CodexNativeAgentHub。无 LOCALAPPDATA 时使用 ~/.local/share/CodexNativeAgentHub。可通过 AGENT_HUB_STATE_DIR 覆盖；请保持在源码仓库外。

• settings.json：三套非密钥配置。

• <代理>.dpapi：Windows 当前用户加密的 Key。

• jobs/：任务摘要、原生会话及规范化活动。

• worktrees/：保留的编辑工作区。

也支持 AGENT_HUB_GEMINI_API_KEY、AGENT_HUB_CLAUDE_API_KEY、AGENT_HUB_DEEPSEEK_API_KEY，环境变量优先于本地凭据。其他平台可用环境变量，但本项目的安装与原生集成测试范围为 Windows x64。

Key 经工作进程 stdin 传入，不放进启动参数、任务摘要或前端存储。面板活动只含固定标签和计数；原生会话日志与最终结果可能包含任务、文件内容和路径，不要上传状态目录。配置的模型服务会接收任务和代理读取的内容。本机面板 URL 自带随机访问令牌，请勿公开或转发。

开发与验证

.\.venv\Scripts\python.exe -B -m unittest discover -s tests -p "test_*.py" -v
.\.venv\Scripts\python.exe -B tests/runtime_smoke.py
.\.venv\Scripts\python.exe -B scripts/audit_release.py

单元测试覆盖独立凭据、配置快照、来源校验、结果持久化、取消与超时、工具权限及 worktree 隔离。原生集成测试用真实 SDK 和运行组件连接本地模拟接口，验证三种代理的「读取 → 工具结果 → 回复」、文件写入及命令执行，检查实际进度与只读工具集；使用假 Key，不消耗模型服务额度。

GitHub Actions 在 Windows、Python 3.11 / 3.14 上执行这些检查。模拟接口验证的是本项目与固定 SDK 的集成，不代表某个第三方中转服务已通过验证。

欢迎通过 Issue 或 PR 提交最小复现和改进；请先运行上述检查，勿附带真实 Key、访问令牌、会话日志或个人路径。

参考与许可

• Antigravity SDK

• Claude Agent SDK

• DeepSeek Harness

• Codex MCP

本项目从 codex-gemini-antigravity 的本地面板与 MCP 桥接方案扩展而来，以独立仓库维护。项目代码采用 MIT License；第三方 SDK 及运行组件按各自条款分发。