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을 저장하며, 준비(prepare), CAS, 원자적 디스크 쓰기, 영속적 영수증을 사용한다.

• 프로세스 충돌 후 실제 파일 상태를 대조하며, 확실하지 않으면 복구를 중단하고 맹목적으로 재쓰기하지 않는다.

• direct_write에는 파일 삭제 도구가 없으며, 읽기 전용 검사 명령 때문에 파일을 쓰지 않는다. 사용자의 명시적 지시에 따라 대상 파일을 덮어쓰거나 수정할 수는 있다.

• worktree_write에서 원본 checkout의 파일, HEAD, tree, index, 작업 영역 상태는 변경되지 않는다. Git common dir에는 보존형 worktree가 등록된다.

검증 명령

RunCommand는 설치된 시스템 명령과 Session 디렉터리 내의 실행 파일을 허용하며, 정상적인 개발 도구를 오탐하는 정적 명령 화이트리스트는 더 이상 유지하지 않는다. 인수는 여전히 정확한 argv로 전달되며, Gateway가 자동으로 셸 문자열로 조합하지 않는다:

• 명령 관점에서 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가 명시적으로 선택한 최대 8개의 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 응답과 각 승인된 작업은 먼저 원자적으로 디스크에 기록된 후 실행 중인 프로세스에 전달된다.

• 임대(lease) 만료 시 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 실제 디렉터리 쓰기, 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 최소 스모크 테스트는 여전히 사용자의 별도 승인이 필요하다.