Peter Steinberger
055a2dc6ce
* feat(cli): ingest session targets * refactor(ui): remove gateway scope shim * docs(cli): document session targets * fix(cli): classify session target failures * fix(cli): keep session target result private * fix(cli): simplify timeout option warning * build: declare session URL contract dependency * fix(cli): parse bare session URL options symmetrically * fix(cli): preserve command-owned URL arguments * build: keep session URL contract build-only * fix: address session URL review findings * test: preserve session key mock exports * fix: keep session URL helpers internal * fix(tui): preserve URL agent for global sessions * fix(tui): keep URL agent input internal * fix(gateway): reconcile websocket protocol owner * fix(attach): preserve global session agent ownership * fix(attach): enforce global owner at grant boundary
2.8 KiB
summary, read_when, title
| summary | read_when | title | ||
|---|---|---|---|---|
| CLI reference for `openclaw attach` (launch Claude Code with a scoped Gateway MCP grant) |
|
Attach CLI |
openclaw attach launches Claude Code with a strict temporary MCP config bound to one Gateway session.
openclaw attach [target]
target accepts a Control UI session URL, a compact host/agent/ref, a bare
short reference, or a literal agent:... session key. A URL or host target
authoritatively selects that Gateway; a bare reference uses 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>binds the grant to a Gateway session. Defaults to the main session.--url <url>selects a Gateway for a bare reference or--sessionkey. Do not combine it with a URL target.--token <token>and--password <password>provide explicit Gateway auth.--tls-fingerprint <sha256>pins the Gateway TLS certificate.--ttl <ms>requests a positive grant TTL in milliseconds. The Gateway applies its own ceiling.--bin <path>selects the Claude Code binary. Default:claude.--print-configwrites the temporary.mcp.json, prints the launch command and env, and leaves the grant live until TTL expiry (it does not spawn Claude Code or revoke the grant).
Pass either a positional target or --session, not both. Short references are
resolved before the scoped attach grant is minted; a missing session is never
created implicitly.
A URL or host target never reuses configured credentials or
OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD. It uses the stored
device token for that exact Gateway origin, or explicit --token/--password
credentials. On first contact, pass one of those credentials once, approve the
pairing request in that Gateway's Control UI, and retry; see
Devices. Session URLs must stay credential-free: userinfo and
sensitive query or fragment parameters such as token and password are
rejected.
Target resolution uses the same session target error matrix
as openclaw tui.
The bearer token is passed through environment variables, not 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 when the Claude Code process exits.
See also: Control UI URLs, Devices, Gateway CLI, MCP CLI, and ACP CLI.