chatgpt-web-agent

A local MCP glue layer that lets the ChatGPT web client use local tools via the OpenAI Secure MCP Tunnel.

This is a runnable reference implementation, not a polished one-click install product; its main purpose is to share a proven integration approach. Users can quickly adapt it to their local environment with the help of an Agent.

The project's own MCP interface remains stable; real tools are provided by a replaceable LocalToolBackend. The first backend directly reuses the OpenClaw Plugin SDK, without modifying OpenClaw source code or reimplementing file, shell, patch, and background process tools.

Current Status

P0 provides four OpenClaw tools:

• read

• exec

• process

• apply_patch

Optional Google Drive file exchange tools:

• drive_list

• drive_search

• drive_stat

• drive_upload

• drive_download

• drive_export

• drive_mkdir

Two read-only OpenClaw Skills tools are enabled by default:

• skills_list(query?, limit?)

• skill_read(name)

skills_list() returns a compact name directory of currently eligible + model-visible Skills; when a natural language query is provided, it returns a small set of candidate names and descriptions via a separate QMD collection. skill_read only accepts a Skill name/key; the canonical SKILL.md path is always resolved from the live OpenClaw skills.status and does not accept a file path from the client. The MCP initialize instructions also hint to the client: only proactively discover Skills when the task clearly might depend on local tools, services, workflows, or operational norms and the current context is insufficient; do not query Skills for ordinary self-contained tasks.

By default, file and patch tools are only allowed to access the configured workspace; exec.workdir must also be within the workspace. OpenClaw's internal host/security/ask/node/elevated parameters are not exposed to the MCP client.

For a standalone Connector only authorized for a trusted ChatGPT workspace, you can set CHATGPT_WEB_AGENT_WORKSPACE_ONLY=false. In this case, the workspace is only the fallback for relative paths and the default cwd; read/apply_patch/exec.workdir can access external absolute paths. This mode is not a security sandbox.

The exec.workdir boundary is not a command sandbox. A client with exec permission may still access other parts of the system in the command text; only authorize the Tunnel for a trusted ChatGPT workspace, and use OpenClaw's allowlist/approval policies as needed.

Development

Requires Node.js 22.22.3 or a compatible OpenClaw Node version, and pnpm.

pnpm install
pnpm check
pnpm smoke

Running

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

The service uses MCP stdio; standard output only carries the MCP protocol.

Configuration

Copy .env.example to see available environment variables. The default tool allowlist is:

read,exec,process,apply_patch

exec uses allowlist + on-miss by default. You can explicitly override:

export CHATGPT_WEB_AGENT_EXEC_SECURITY=allowlist
export CHATGPT_WEB_AGENT_EXEC_ASK=on-miss

For an initial trusted local smoke test, you can temporarily use:

export CHATGPT_WEB_AGENT_EXEC_SECURITY=full
export CHATGPT_WEB_AGENT_EXEC_ASK=off

Architecture

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（后续按需）

The Skills backend only does capability discovery/read; QMD is only a candidate retrieval accelerator; the live OpenClaw inventory is always the source of truth for eligibility, model visibility, and canonical Skill paths.

Skills semantic discovery

It is recommended to place the semantic catalog in a separate QMD named index, rather than sharing the memory index. QMD 2.5.3's vector ANN first retrieves candidates from the entire index and then applies the collection filter; mixing a few dozen Skills with tens of thousands of memory documents would cause the small collection to be overwhelmed by candidates from the full index.

The current deployment uses:

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

Retrieval uses Qwen3-Embedding-0.6B, vector-only, rerank=false, without query expansion / HyDE. QMD hits are only candidates; they are still intersected with the live skills.status before returning. The catalog schema/inventory uses catalogHash for generation invalidation; when QMD is unavailable or the catalog is stale, it falls back to a live names-only catalog.

Google Drive

Drive is an optional data channel; it does not do background sync, disk mounting, or full disk mirroring. The implementation directly uses the Google Drive API v3; MCP only exposes small, stable file operation primitives.

By default, Drive's local upload/download/export paths can only be located in:

<CHATGPT_WEB_AGENT_WORKSPACE>/exchange

This restriction is independent of CHATGPT_WEB_AGENT_WORKSPACE_ONLY and is intended to reduce the risk of Drive tools being misused as an arbitrary local data exfiltration channel. If necessary, deployers can adjust it via CHATGPT_WEB_AGENT_DRIVE_LOCAL_ROOT and CHATGPT_WEB_AGENT_DRIVE_LOCAL_ROOT_ONLY.

One-time OAuth configuration

1. Enable the Drive API in Google Cloud and create a Desktop OAuth client.

2. Save the downloaded OAuth JSON as:

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

   Or set CHATGPT_WEB_AGENT_DRIVE_CREDENTIALS to point to another local private path.

3. Run:

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

   After browser authorization completes, an authorized-user token with permissions 0600 will be generated. The OAuth client secret and refresh token should not be committed to Git, nor returned via MCP.

4. When starting the service, set:

   export CHATGPT_WEB_AGENT_DRIVE_ENABLED=true

The folderId / fileId in Drive tools directly use Drive API IDs. Use drive_download for ordinary binary files; use drive_export for Google Docs/Sheets/Slides to export to the specified MIME type.