chatgpt-web-agent

ChatGPT 웹페이지가 OpenClaw Secure MCP Tunnel을 통해 로컬 도구를 사용할 수 있도록 하는 로컬 MCP 글루 레이어.

이것은 원클릭 설치를 목표로 하는 완성품이 아니라 실행 가능한 참조 구현입니다. 주로 실제로 검증된 접근 방식을 공유하기 위한 것이며, 사용자는 Agent를 활용하여 자신의 로컬 환경에 맞게 빠르게 적응할 수 있습니다.

프로젝트 자체의 MCP 인터페이스는 안정적으로 유지되며, 실제 도구는 교체 가능한 LocalToolBackend가 제공합니다. 첫 번째 백엔드는 OpenClaw Plugin SDK를 직접 재사용하며, OpenClaw 소스 코드를 수정하지 않고 파일, Shell, 패치 및 백그라운드 프로세스 도구를 다시 구현하지 않습니다.

현재 상태

P0은 4가지 OpenClaw 도구를 제공합니다:

• read

• exec

• process

• apply_patch

선택적으로 Google Drive 파일 교환 도구를 활성화할 수 있습니다:

• drive_list

• drive_search

• drive_stat

• drive_upload

• drive_download

• drive_export

• drive_mkdir

기본적으로 두 개의 읽기 전용 OpenClaw Skills 도구가 활성화됩니다:

• skills_list(query?, limit?)

• skill_read(name)

skills_list()는 현재 eligible + model-visible Skill의 간결한 이름 디렉토리를 반환합니다. 자연어 query가 있는 경우 독립적인 QMD collection을 통해 소수의 후보 이름과 설명을 반환할 수 있습니다. skill_read는 Skill 이름/키만 허용하며, 정식 SKILL.md 경로는 항상 실시간 OpenClaw skills.status에서 해석되며 클라이언트가 제공하는 파일 경로를 받지 않습니다. MCP initialize 지침은 클라이언트에게 다음을 추가로 알립니다: 작업이 명백히 로컬 도구, 서비스, 워크플로우 또는 운영 규칙에 의존할 가능성이 있고 현재 컨텍스트가 부족한 경우에만 Skill을 적극적으로 발견하도록 합니다. 일반적인 자체 포함 작업은 Skill을 조회하지 않습니다.

기본적으로 파일 및 패치 도구만 구성된 workspace에 접근할 수 있으며, exec.workdir도 workspace 내에 위치해야 합니다. OpenClaw 내부의 host/security/ask/node/elevated 매개변수는 MCP 클라이언트에 노출되지 않습니다.

신뢰할 수 있는 ChatGPT workspace에만 권한이 부여된 독립 Connector의 경우 CHATGPT_WEB_AGENT_WORKSPACE_ONLY=false를 설정할 수 있으며, 이 경우 workspace는 상대 경로와 기본 cwd의 기준점일 뿐이며 read/apply_patch/exec.workdir은 외부 절대 경로에 접근할 수 있습니다. 이 모드는 보안 샌드박스가 아닙니다.

exec.workdir 경계는 명령 샌드박스가 아닙니다. exec 권한을 얻은 클라이언트는 여전히 명령 텍스트에서 시스템의 다른 위치에 접근할 수 있습니다. Tunnel은 신뢰할 수 있는 ChatGPT workspace에만 권한을 부여해야 하며, 필요에 따라 OpenClaw의 allowlist/approval 정책을 사용해야 합니다.

개발

Node.js 22.22.3 또는 호환되는 OpenClaw Node 버전과 pnpm이 필요합니다.

pnpm install
pnpm check
pnpm smoke

실행

export CHATGPT_WEB_AGENT_WORKSPACE=/path/to/workspace
# 可信独立 Connector 如需把 workspace 仅作为默认工作目录：
# export CHATGPT_WEB_AGENT_WORKSPACE_ONLY=false
pnpm build
node dist/cli.js

서비스는 MCP stdio를 사용하며, 표준 출력은 MCP 프로토콜만 전달합니다.

설정

.env.example을 복사하여 사용 가능한 환경 변수를 확인하세요. 기본 도구 화이트리스트는 다음과 같습니다:

read,exec,process,apply_patch

exec는 기본적으로 allowlist + on-miss를 사용합니다. 명시적으로 덮어쓸 수 있습니다:

export CHATGPT_WEB_AGENT_EXEC_SECURITY=allowlist
export CHATGPT_WEB_AGENT_EXEC_ASK=on-miss

로컬 신뢰할 수 있는 초기 smoke 테스트 시 임시로 다음을 사용할 수 있습니다:

export CHATGPT_WEB_AGENT_EXEC_SECURITY=full
export CHATGPT_WEB_AGENT_EXEC_ASK=off

아키텍처

ChatGPT Web
  → OpenAI Secure MCP Tunnel
  → chatgpt-web-agent MCP Server
  → LocalToolBackend
      → OpenClawBackend
      → SkillsBackend → OpenClaw Gateway (live status)
                      → QMD MCP (optional semantic discovery)
      → NativeBackend / other backend（后续按需）

Skills 백엔드는 capability discovery/read만 수행합니다. QMD는 후보 검색 가속기일 뿐이며, 실시간 OpenClaw 인벤토리는 항상 eligibility, model visibility 및 정식 Skill 경로의 사실 공급원입니다.

Skills semantic discovery

의미론적 카탈로그는 공유 memory index가 아닌 독립적인 QMD named index에 배치하는 것이 좋습니다. QMD 2.5.3의 vector ANN은 먼저 전체 index에서 후보를 가져온 다음 collection filter를 적용합니다. 수십 개의 Skill을 수만 개의 memory 문서에 섞어 넣으면 작은 collection이 전체 라이브러리 후보에 의해 압도될 수 있습니다.

현재 배포에서는 다음을 사용합니다:

local catalog: <workspace>/skills-catalog/
M4 mirror:     ~/qmd-data/skills-chatgpt-web-agent/
QMD index:     skills-chatgpt-web-agent
collection:    skills-chatgpt-web-agent
MCP endpoint:  http://192.168.0.96:8182/mcp

검색은 Qwen3-Embedding-0.6B, vector-only, rerank=false를 사용하며, query expansion / HyDE를 수행하지 않습니다. QMD 히트는 단지 후보일 뿐입니다. 반환 전에 live skills.status와의 교집합을 구합니다. 카탈로그 스키마/인벤토리는 catalogHash를 통해 세대(generation) 무효화를 수행하며, QMD를 사용할 수 없거나 카탈로그가 오래된 경우 자동으로 live names-only catalog로 폴백합니다.

Google Drive

Drive는 선택적 데이터 채널이며, 백그라운드 동기화, 디스크 마운트 또는 전체 디스크 미러링을 수행하지 않습니다. 구현은 Google Drive API v3를 직접 사용하며, MCP는 작고 안정적인 파일 작업 원시 연산만 노출합니다.

기본적으로 Drive의 로컬 업로드/다운로드/내보내기 경로는 다음 위치에만 있을 수 있습니다:

<CHATGPT_WEB_AGENT_WORKSPACE>/exchange

이 제한은 CHATGPT_WEB_AGENT_WORKSPACE_ONLY와 독립적이며, Drive 도구가 임의의 로컬 데이터 유출 채널로 오용될 위험을 줄이기 위한 것입니다. 실제로 필요한 경우 배포자가 CHATGPT_WEB_AGENT_DRIVE_LOCAL_ROOT 및 CHATGPT_WEB_AGENT_DRIVE_LOCAL_ROOT_ONLY를 통해 조정할 수 있습니다.

일회성 OAuth 설정

1. Google Cloud에서 Drive API를 활성화하고 Desktop OAuth 클라이언트를 생성합니다.

2. 다운로드한 OAuth JSON을 다음 위치에 저장합니다:

   <workspace>/.credentials/google-drive/credentials.json

   또는 CHATGPT_WEB_AGENT_DRIVE_CREDENTIALS를 설정하여 다른 로컬 개인 경로를 가리킵니다.

3. 다음을 실행합니다:

   CHATGPT_WEB_AGENT_WORKSPACE=/path/to/workspace pnpm drive:auth

   브라우저 인증이 완료되면 권한이 0600인 authorized-user 토큰이 생성됩니다. OAuth 클라이언트 시크릿과 갱신 토큰은 Git에 커밋해서는 안 되며, MCP를 통해 반환되지 않습니다.

4. 서비스 시작 시 다음을 설정합니다:

   export CHATGPT_WEB_AGENT_DRIVE_ENABLED=true

Drive 도구의 folderId / fileId는 Drive API ID를 직접 사용합니다. 일반 바이너리 파일은 drive_download를 사용합니다. Google Docs/Sheets/Slides는 drive_export를 사용하여 지정된 MIME 유형으로 내보냅니다.