Claude Tools Native Gateway

一句话：让网页版 ChatGPT 成为唯一主脑，驱动本机真实的 Claude Code 原生 Session 完成受控读取、修改、验证与恢复。

公开仓库只包含源码和测试，不包含本机密钥、Tunnel 配置或 state/ 会话状态。

架构

Gateway 现在只有 Native V2 一套执行引擎：

当前 ChatGPT Chat（唯一主脑）
  ↔ Claude Tools Native MCP（六个 Session 控制工具）
      ↔ 本地模型回合桥（127.0.0.1）
          ↔ 隔离的 Claude Code 原生 Session
              → 原生 Agent loop
              → 网关自有的受控工具 Executor

Gateway 自己完成 MCP 初始化、工具清单和调用分发，不再启动或代理 V1 的 claude mcp serve 工具服务器。只有创建 Native Session 后，才会启动该 Session 专属的 Claude Code 进程。

原 V1 Agent Session、顶层 Read/Edit/Write/Bash、本地任务工具、旧 DeepSeek 委派和 ChatGPT Bridge 已从运行入口与代码树移除。保留下来的是 V2 仍需要的共用底层设施：原子状态写入、凭据路径保护、进程身份验证和 macOS 沙箱规则。旧 V1 状态文件不会被自动删除，但 Native Gateway 不会读取或执行它们。

MCP 控制面

网页版只看到六个工具：

• native_session_start

• native_session_continue

• native_session_recover

• native_session_reply_and_wait

• native_session_status

• native_session_stop

任何 V1 工具名、顶层文件工具、Bash、旧 DeepSeek 工具或其他 MCP 方法都会在服务端拒绝，而不是仅从工具列表隐藏。

Claude Code Session 能力

Session 有三个明确档位，创建后不能升降级或换根目录：

• read_only：Read、FindFiles、SearchText 和只读 RunCommand；读取范围是整台电脑，受保护状态/凭据路径与 macOS 权限除外。

• direct_write：在全电脑读取能力上增加 Edit、Write、NotebookEdit，只直接修改用户明确选择的真实目录。只有用户明确要求修改真实文件时才应选择此档位。

• worktree_write：工具集与 direct_write 相同，但修改的是 Gateway 创建并保留的独立 Git worktree，源 checkout 不变。

这些是 Claude Code 原生 Agent loop 中模型可调用的逻辑工具，但执行器归 Gateway 所有。未经监管的 Claude Code 内建文件工具和 Bash 仍关闭，避免绕过动作授权、哈希、恢复和审计账本。

读取与搜索

• Read 可读取电脑上任意未受保护的普通 UTF-8 文件，不再被写入目录限制。

• FindFiles 可从任意绝对目录做有界文件枚举。

• SearchText 只做 UTF-8 字面匹配，不接受正则或 glob。

• 搜索不跟随符号链接，跳过 .git、受保护路径和外部硬链接。

• 单次搜索结果和完整动作回执都限制在 64 KiB 内。

• 所有档位都可以检查不同磁盘和目录；working_directory 只是默认搜索位置、命令 CWD 和写档位的写入边界。macOS TCC/文件权限仍可能拒绝 Desktop、Documents 或其他受系统保护的位置。

文件与 Notebook 修改

• direct_write 下，Edit、Write 和 NotebookEdit 修改 Session 绑定的真实目录；worktree_write 下只修改受管 worktree。

• Write 可以在授权根目录内按需创建缺失的父目录，再原子创建目标文件；不会借此越过根目录、符号链接、.git 或受保护路径。

• NotebookEdit 支持按 cell ID 替换、插入和删除单元格，但不执行 Notebook。

• 每个写动作都保存写前和写后 SHA-256，并使用准备、CAS、原子落盘和持久回执。

• 进程崩溃后会核对真实文件状态，不能确定时停止恢复，不会盲目重复写入。

• direct_write 没有文件删除工具，也不会因为只读检查命令而写文件；它仍可能按用户明确指令覆盖或修改目标文件。

• worktree_write 中源 checkout 的文件、HEAD、tree、index 和工作区状态保持不变；Git common dir 会登记保留式 worktree。

验证命令

RunCommand 接受已安装的系统命令和 Session 目录内的可执行文件，不再维护容易误伤正常开发工具的静态命令白名单。参数仍以精确 argv 传入，不会由 Gateway 自动拼成 shell 字符串：

• 命令视角下的 Session 根文件系统只读；

• 网络、进程信号、Keychain/XPC 和模型 CLI 被 macOS Seatbelt 阻断；

• sudo、直接删除/移动、系统控制、find -delete/-exec、rg --pre、模型 CLI 等入口仍被明确拒绝；

• 普通项目里的符号链接、硬链接或文件数量不会再导致命令在启动前整仓拒绝；真正访问时由 Seatbelt、受保护路径和 macOS 权限约束；

• 输出、运行时间和子进程组回收均有边界；

• 结果先进入同一动作账本，再交给下一次 GPT 回合。

它用于可信仓库验证，不是对抗同一 macOS 账号恶意进程的容器。Session 运行时不要用其他编辑器或进程并发修改受管 worktree。

主模型、网页搜索与 DeepSeek

主路由固定为 chatgpt-main，不接受 model、provider、endpoint、API key 或 fallback 参数。当前 ChatGPT 回合停止时，Claude Code 会停在 waiting_for_gpt；不会私自切换到 Claude、DeepSeek 或 Codex 继续思考。

网页搜索继续由网页版 ChatGPT 完成。Claude Code 的 WebSearch/WebFetch 不开放，因此不会出现 GPT 搜索与 Claude 自己搜索相互冲突或来源失控。

默认 subagent_policy: "none"，不会创建 DeepSeek。只有 worktree_write 明确选择 deepseek_explicit 后，GPT 才能在主循环中使用：

• deepseek_subagent_start

• deepseek_subagent_get

• deepseek_subagent_stop

委派必须先进入主 Session 的持久动作账本，随后才放行隔离子 Session。子任务期间主 Session 不能并发 Edit、Write、NotebookEdit、RunCommand 或启动第二个子任务。路由固定为 Sonnet/Opus → Flash、Fable → Pro，失败不会回退到 Claude、Codex、OpenAI 或另一档 DeepSeek。

Skill 上下文

native_session_start 可以接收最多八个由 ChatGPT 明确选择的 skill_contexts。它们不是 Claude Code 原生 Skill 运行时：

• 只提取并冻结经过校验的指令正文；

• 不加载脚本、资源、插件、Hook、Slash Command 或额外工具；

• 每个允许项同时固定 skill ID 和规范化完整 SKILL.md 的 SHA-256；

• 首次启动和后续 resume 使用同一份持久快照；

• 完整正文只在 0600 私有状态与当前 GPT 必需的模型上下文中出现。

允许清单示例：

CLAUDE_TOOLS_NATIVE_SKILL_ALLOWLIST_JSON='[{"skill_id":"personal:review","content_sha256":"<64位小写SHA-256>"}]' \
npm start

哈希按去掉 UTF-8 BOM、把 CRLF/CR 统一为 LF 后的完整文本计算。

隔离与恢复

• 每个 Session 使用独立 HOME、Claude 配置目录、运行目录和进程组。

• Claude Code 使用 --bare、空 setting sources、严格 MCP 配置和精确工具集合。

• 主 Claude 进程只能访问精确的本地 Broker/Executor 回环端口。

• 凭据目录、Gateway 状态、.git、符号链接和外部硬链接均 fail closed；普通系统/用户路径能否访问由 Session 根、macOS TCC 和文件权限共同决定。

• ChatGPT 回复和每个获准动作先原子落盘，再释放给运行进程。

• 租约到期会停止 Runner 并留下可检查状态。

• Gateway 重启不会杀死仍属于 Session 的 Runner；native_session_recover 验证所有权、轮换租约并继续同一个 Claude Code Session。

• Runner 已不存在时不会伪装恢复，也不会重复已完成动作。

Claude Code 2.1.247 没有已验证的“只启用 Hooks，同时继续禁用 keychain、插件和自动记忆”的独立开关，因此原生 Hooks、原生 Skill/Slash、Agent、Workflow、Web 和未经动作账本监管的第三方 MCP 保持关闭。

运行

npm start

Native Gateway 不再需要 CLAUDE_TOOLS_NATIVE_V2 或 CLAUDE_TOOLS_NATIVE_V2_ONLY 开关；Native-only 是唯一运行模式。

状态默认保存在 state/，可通过绝对路径环境变量 CLAUDE_TOOLS_STATE_DIR 修改。Claude Code 默认路径为 $HOME/.npm-global/bin/claude，可用 CLAUDE_BIN 覆盖。

长期运行的 Tunnel/Connector 在源码更新后需要重启。ChatGPT 可能缓存已连接工具 schema；如果新会话没有看到六个 native_session_*，请刷新或重连 Claude Tools Connector。

验证

npm test
npm run test:native:installed
npm run test:native:installed:write
npm run test:native:installed:direct-write
npm run test:native:installed:deepseek
npm run test:native:installed:skills

自动测试覆盖：

• Native-only MCP 直接初始化、精确六工具、V1 工具和未知方法拒绝；

• 回合与动作账本、回复幂等、租约、进程所有权、停止与恢复；

• Read/FindFiles/SearchText 的全电脑读取、受保护路径、大小、排序、字面匹配和竞态边界；

• Edit/Write/NotebookEdit 的 direct real-directory 写入、worktree 隔离、CAS、哈希和崩溃恢复；

• RunCommand 的宽松开发命令入口、Session 本地可执行文件、只读文件系统、零网络、敏感服务阻断和超时回收；

• Skill 的 ID/正文哈希固定、start/resume 一致性和私有状态边界；

• DeepSeek 显式委派的启动屏障、单任务写锁、路由验真、Gateway 重启恢复和停止；

• 公开 MCP/Session/history 不泄露授权 ID、Runner token、PID、内部路径或模型凭据。

Installed 测试使用本机 Claude Code 2.1.247 和 localhost 脚本 GPT，不连接真实模型：

• test:native:installed：以 / 为只读根执行 FindFiles → 字面 SearchText → Read → final，以及 Gateway 断开后恢复同一 Runner/Claude Session。

• test:native:installed:write：Read → Edit → Write → NotebookEdit → RunCommand → resume → Read。

• test:native:installed:direct-write：同一套真实 Claude Code 回合直接修改测试夹具中的真实目录，再 resume 并验证持久结果。

• test:native:installed:deepseek：使用本地假 DeepSeek CLI 验证显式委派、结果验真、活动写锁、重启恢复与停止。

• test:native:installed:skills：验证两个哈希固定的纯指令 Skill 在 start/resume 使用同一快照。

这些本地脚本测试不消耗真实 ChatGPT、Claude 或 DeepSeek 模型额度。真实 DeepSeek 最小烟雾测试仍需用户单独授权。