Attach CLI: Launch Claude Code with Scoped Gateway MCP Grant
Reference for the openclaw attach command, which starts Claude Code with a temporary MCP configuration scoped to a single Gateway session. Covers target formats, options, and authentication.
Read this when
- You want Claude Code to use OpenClaw Gateway MCP tools
- You need a temporary session-bound MCP grant for an external harness
openclaw attach starts Claude Code using a temporary MCP configuration that is strictly scoped to a single Gateway session.
openclaw attach [target]
target takes a Control UI session URL, a compact host/agent/ref, a bare
short reference, or a literal agent:... session key. When a URL or host target
is given, that Gateway is selected authoritatively; a bare reference falls
back to the configured or default Gateway.
openclaw attach
openclaw attach https://gateway.example/dashboard/main/movies-a1166b81
openclaw attach movies-a1166b81
openclaw attach --session agent:main:telegram:123 --ttl 600000
openclaw attach --print-config
Options:
--session <key>ties the grant to a Gateway session. The main session is used by default.--url <url>picks a Gateway for a bare reference or--sessionkey. It must not be used alongside a URL target.--token <token>and--password <password>supply explicit Gateway authentication.--tls-fingerprint <sha256>fixes the Gateway TLS certificate.--ttl <ms>asks for a positive grant TTL in milliseconds. The Gateway enforces its own upper bound.--bin <path>chooses the Claude Code binary. Defaults toclaude.--print-configwrites the temporary.mcp.json, prints the launch command and env, and keeps the grant active until the TTL runs out (Claude Code is not spawned, and the grant is not revoked).
Provide either a positional target or --session, but never both. Short references
are resolved before the scoped attach grant is created; a missing session is
never made implicitly.
A URL or host target never reuses configured credentials or
OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD. It relies on the stored
device token for that exact Gateway origin, or on explicit --token/--password
credentials. On the first attempt, pass one of those credentials once, approve
the pairing request in that Gateway's Control UI, and try again; refer to
Devices. Session URLs must be free of credentials: userinfo and
sensitive query or fragment parameters like token and password are
rejected.
Target resolution follows the same session target error matrix
as openclaw tui.
The bearer token is passed through environment variables, never argv. OpenClaw launches Claude Code with --strict-mcp-config --mcp-config <path> so ambient Claude MCP servers do not join the attached session. Normal launches (without --print-config) revoke the grant once the Claude Code process ends.
See also: Control UI URLs, Devices, Gateway CLI, MCP CLI, and ACP CLI.