OpenClaw Attach Guide: Claude Code on a Session-Scoped Grant, and the Limits the Docs Leave Out

openclaw attach starts Claude Code with a temporary MCP grant bound to one Gateway session, so Claude Code can use that session's tools without seeing any other session. Use it when you want a coding agent working beside one conversation, and run it on the Gateway host, because the MCP endpoint it writes is 127.0.0.1. If Claude Code needs to read and answer many channel threads, openclaw mcp serve is the better fit.

Search for this command today and you get the official CLI reference plus its translations and a docs2 mirror. That's it. The reference is accurate, and short. It says the Gateway "applies its own ceiling" to the grant TTL without saying what the ceiling is, and it never mentions that the generated config points at loopback. I read the 2026.10.8 source to fill those in.

What attach does, step by step

The CLI resolves your target (a Control UI URL, a short ref like movies-a1166b81, or a full agent:... key) to one session. It then calls attach.grant on the Gateway, which needs the operator.admin scope. A paired device with only operator.write gets a scope-mismatch here, and the fix is approving a scope upgrade in devices.

The Gateway answers with a random 64-character hex token, an expiry, and an MCP server block. The CLI writes that block to .mcp.json inside a fresh openclaw-attach- directory under your temp dir, file mode 0600, and spawns:

claude --strict-mcp-config --mcp-config /tmp/openclaw-attach-XXXX/.mcp.json

The token goes into the child's environment as OPENCLAW_MCP_TOKEN. The config file only holds the placeholder Bearer ${OPENCLAW_MCP_TOKEN}, and Claude Code expands it at connect time. --strict-mcp-config is the part I like most. Your global Claude MCP servers (the GitHub one, the Postgres one you forgot about) stay out of the attached session entirely.

openclaw attach                                   # main session
openclaw attach deploy-monitor-6db92d48           # short ref from a Control UI URL
openclaw attach --session agent:main:telegram:123 --ttl 900000
openclaw attach --bin /opt/claude/bin/claude      # non-default Claude Code binary

Pass a positional target or --session. Both together is an error. A missing session is never created for you, which is the right default: a typo fails loudly instead of handing Claude Code an empty session.

attach, mcp serve, acp, and tui side by side

Four commands put something next to a Gateway session. They differ in who supplies the model and how long the credential lives, and those two columns decide most setups:

My default for coding work against a live session is attach. A grant that dies when Claude Code exits is a much smaller thing to lose than the Gateway token that mcp serve holds all afternoon. I switch to mcp serve the moment the job spans more than one conversation, because attach simply can't see the others. The ACP bridge guide covers the editor case in detail.

Run it on the Gateway host

Here is the part the reference skips. The MCP server in the grant is the Gateway's own loopback endpoint, written as http://127.0.0.1:<port>/mcp. Attach from your laptop against wss://claw.example.com and the grant mints fine, the expiry prints, Claude Code opens. Then it dials 127.0.0.1 on your laptop, finds nothing, and the openclaw server shows as failed in /mcp.

Two fixes work. SSH into the Gateway box and run attach there, which is what I do. Or run openclaw attach --print-config once to read the port, then forward it:

ssh -N -L <port>:127.0.0.1:<port> you@gateway-host

The tunnel keeps the request looking local to the Gateway, which is what its loopback check expects. For the WebSocket side, a tailnet beats an open port, and the Tailscale guide walks through it.

Grant lifetime, in real numbers

With no --ttl, the grant lasts 3,600,000 ms, one hour. The ceiling is 43,200,000 ms, twelve hours, and anything above it is clamped without an error. Ask for a day and you get twelve hours, and the only sign is the expiry timestamp the CLI prints. --ttl takes plain milliseconds. 1h and 3600s are rejected before anything is minted.

A normal exit revokes the grant, so in theory the TTL only matters when something goes wrong. In practice things go wrong. If the attach process is killed with kill -9, or the laptop sleeps through a dropped SSH session, the revoke call never happens and the grant stays valid until expiry. The temp .mcp.json stays behind too. I pass --ttl 900000 (15 minutes) for quick jobs and accept the hourly default only for a long refactor.

Grants live in Gateway memory. Restart the Gateway and every live grant is gone, so a running Claude Code session loses its OpenClaw tools mid-task. Schedule the restart after the refactor.

Ctrl-C goes to Claude Code. The attach wrapper ignores SIGINT on purpose, waits for Claude Code to exit, revokes, and passes Claude Code's exit code back to your shell.

--print-config prints the token

--print-config mints the grant, writes the config, and prints a JSON block with the session key, expiry, config path, launch command, and an env object. That object holds OPENCLAW_MCP_TOKEN in plain text, on stdout. It doesn't revoke anything either. The grant runs to its full TTL and the config file stays until you delete it.

Fine at your own terminal. Bad in a CI job or any script whose output lands in a log somebody else can read, because for the next hour that string is a working bearer credential for the session. If you must script it, pair it with a short --ttl and pipe the output somewhere private. This is the kind of token handling the Security Hardening Kit is built around, along with tool permission boundaries for an always-on Gateway, and it is worth reading before you wire attach into automation.

What the attached session can and cannot do

The Gateway treats a grant holder as a non-owner sender bound to one session key. Owner-gated actions stay locked, and the grant carries no agent identity, so session-management tools behave the way they would for a guest. Explicit tool denies on the agent still apply.

• Structured questions from a tool (ask-user) can only be answered in the Control UI or native app. Replying on Telegram does nothing, because a standalone grant has no run snapshot that ordinary channel text could match.
• Sessions owned by an agent harness are refused at grant time with a reserved-key error.
• Exec approvals raised by attached tool calls go wherever your approvals normally go. The exec approvals guide explains that routing.

URL targets never reuse your configured token. First contact with a new Gateway origin means passing --token once, approving the pairing in Settings > Devices, and retrying. After that the stored device token for that exact origin is used. A URL with ?token= in it is rejected outright, which saves people from pasting secrets into shell history.

Errors you will actually hit

pass one session target means you gave both a ref and --session. Session reference ambiguous means two sessions share the short prefix, so copy a longer one from the CLI output. mcp loopback server unavailable comes from the Gateway itself, so read the Gateway log before touching anything on the client. Failed to launch 'claude' is a PATH problem on the box you ran attach on, which is common over SSH where your shell profile never loaded. Point --bin at the full path. For session lookups, openclaw sessions list is quicker than clicking around the Control UI.

Where each option fits (and where it does not)

openclaw attach fits a Claude Code session working on one conversation while you sit at a shell on the Gateway host. It is a poor fit for Codex or any non-Claude client (the launch flags are Claude Code's), and for a laptop talking to a remote Gateway without a tunnel.

openclaw mcp serve wins when the agent needs your whole inbox of channel threads, or the client is something other than Claude Code. You pay for that with a long-lived Gateway credential.

openclaw acp wins when you want your own OpenClaw agent, with its memory and skills, inside an editor.

openclaw tui is for when you just want to talk to the session yourself.

Final verdict

Use attach. For Claude Code on a single session it is the safest of the four, because the credential dies with the Claude Code process, and --strict-mcp-config keeps your other MCP servers out. Run it on the Gateway host, pass a --ttl shorter than the one-hour default, and treat --print-config output as a secret. The loopback URL is the one sharp edge, and I would expect a future release to fix it. Until then, SSH first.