OpenClaw attach: give Claude Code temporary access to one session
openclaw attach is the safer way to bring Claude Code into an active OpenClaw session. It creates a temporary, session-bound MCP grant, launches Claude Code with only that configuration, and revokes the grant when Claude Code exits. You get a useful handoff without turning a long-lived Gateway credential into a general-purpose coding-agent token.
That matters when a conversation starts in OpenClaw but the next part is code work: inspecting a repository, making a focused change, or using the coding harness while preserving the context and tools that already belong to that session. The command arrived in the v2026.7.1-beta.5 release line as an external-harness attachment feature.
Table of contents
- What OpenClaw attach does
- Why a temporary session grant is different
- How to use OpenClaw attach
- What to check before handing off
- When not to use it
- FAQ
What OpenClaw attach does
The command launches Claude Code against an existing Gateway session. By default, it uses the main session; --session lets you target a specific Gateway session key instead.
openclaw attach
# Attach Claude Code to one known session for up to 10 minutes
openclaw attach --session agent:main:telegram:123 --ttl 600000Under the hood, OpenClaw writes a temporary .mcp.json file and starts Claude Code with --strict-mcp-config --mcp-config <path>. The strict flag is important: it prevents ambient Claude MCP servers from silently joining the attached session. The bearer token travels through environment variables rather than command-line arguments.
This is a narrow integration point, not a way to make every Claude Code terminal automatically control your Gateway. OpenClaw’s Attach CLI documentation says the grant is bound to one Gateway session and that normal launches revoke it when the Claude Code process exits.
| Concern | A durable shared credential | openclaw attach |
|---|---|---|
| Reach | Often broader than one task | One selected Gateway session |
| Lifetime | Remains usable until manually rotated or removed | TTL-bound, with revoke-on-exit for normal launches |
| MCP configuration | Can inherit whatever a local environment already has | Temporary strict MCP configuration |
| Token handling | Easy to leak through copied commands or config files | Passed through environment variables, not argv |
Why a temporary session grant is different
A session identifier is a routing selector, not proof that a caller is authorized. OpenClaw’s Gateway security model makes that distinction explicitly. Giving another process a session key alone should not be confused with granting it control-plane access.
openclaw attach pairs the session choice with a real, revocable grant. The feature’s implementation notes describe the flow as minting a per-session grant, writing a temporary MCP configuration, launching Claude Code, then revoking the grant on exit. That gives the operator a few useful limits at once:
- The handoff has an expiry.
--ttlrequests a positive duration in milliseconds, while the Gateway still applies its own ceiling. - The handoff has a target. Use
--sessionwhen the task belongs to a particular conversation instead of relying on the default main session. - The coding harness starts clean. Strict MCP configuration prevents unrelated local MCP servers from piggybacking on the work.
- The token stays out of shell history. Environment-based token handling reduces one common accidental disclosure path, although it does not remove the need to protect the host and its process environment.
The Model Context Protocol’s authorization guidance reaches the same practical conclusion from the protocol side: tokens should be sent in an Authorization header, not in a URI, and should be tied to the resource they are meant to access. OpenClaw’s temporary grant is product-specific, but the design choice fits that broader rule: avoid portable, over-broad credentials when a bounded access path will do.
How to use OpenClaw attach
Start with a session you recognize and a small task. A handoff is easier to review when the original conversation already states what Claude Code should change and how you will verify it.
1. Choose the session deliberately
If the work belongs to a channel conversation or a specialist agent, pass that session key directly:
openclaw attach --session agent:main:telegram:123 --ttl 600000Do not treat a session key as a user-isolation mechanism. If mutually untrusted people share a Gateway or host, OpenClaw recommends separate Gateway cells and ideally separate OS users or hosts. An attachment command cannot repair the wrong trust boundary.
2. Use the default Claude binary or specify one
openclaw attach uses claude by default. If your approved Claude Code binary lives elsewhere, provide it explicitly:
openclaw attach --bin /usr/local/bin/claudeUse an expected local binary. A shell alias or wrapper that changes MCP settings defeats the point of reviewing a narrow handoff.
3. Inspect a setup without launching it
--print-config writes the temporary config, prints the launch command and environment, and does not start Claude Code. It leaves the grant available until its TTL expires, which makes it useful for inspection or a controlled manual launch.
openclaw attach --session agent:main:telegram:123 --ttl 600000 --print-configTreat this as a diagnostic mode, not a permanent integration recipe. It intentionally leaves the grant alive for the requested window, so close the loop before the TTL ends.
4. Review what Claude Code can do
Before launching, reread the task as if you were delegating it to a person with the same tools. Limit the task to the repository, service, or investigation that needs attention. For broader agent hardening, how OpenClaw works and the OpenClaw security guide are useful context; the latter is a separate guide to host, channel, and tool boundaries.
What to check before handing off
A short preflight catches most avoidable mistakes:
- Confirm that the Gateway and session belong to the same trusted operator boundary.
- Pick the shortest reasonable TTL. A coding task that needs an afternoon should not receive a grant that survives for days.
- Make the task explicit: file scope, desired result, tests, and whether external actions are allowed.
- Check the configured tool policy. A temporary grant can be narrow in time and session scope while the session itself still has powerful host tools.
- Keep secrets out of the task text and repository whenever possible. Temporary access does not make copied credentials safe.
- Run the relevant validation after the handoff. For application changes, that normally means tests, linting, or a build, not just a plausible Claude Code summary.
The same principle applies to skills and plugins. Use the AI agent skills versus tools guide to decide whether the task needs a reusable capability or just a one-off coding turn. Do not add a new MCP server merely because a temporary attachment exists.
When not to use it
Do not use openclaw attach as a multi-user access system, a way to expose the Gateway over the public internet, or a substitute for sandboxing. It is an operator-controlled bridge between OpenClaw and Claude Code.
It is also not the best answer when you only need a quick command-line change and no session context. In that case, run your ordinary local coding workflow. Attachment adds value when the selected Gateway session is the context you want Claude Code to work from and you want the access to disappear afterward.
OpenClaw’s security documentation recommends a local-only Gateway, explicit authentication, pairing or allowlists for inbound DMs, and selective tool access. Keep those baseline controls in place. A short-lived MCP grant is one layer of the design, not the whole design.
FAQ
Does OpenClaw attach expose every OpenClaw session to Claude Code?
No. openclaw attach binds the grant to the selected Gateway session. If you omit --session, it defaults to the main session; use --session when you need a specific target.
How long does an OpenClaw attach grant last?
You request a positive TTL with --ttl <ms>, and the Gateway applies its own ceiling. With a normal launch, OpenClaw also revokes the grant when the Claude Code process exits.
Does OpenClaw attach put the token in my terminal command?
The Attach CLI documentation says the bearer token is passed via environment variables, not argv. That reduces exposure in copied commands and shell history, but you should still protect the machine and avoid printing sensitive environment values.
Is OpenClaw attach a replacement for separate Gateways?
No. OpenClaw documents one Gateway as one user or trust boundary. For mutually untrusted users or organizations, run isolated Gateways rather than relying on session naming or a temporary attachment.
A bounded bridge for coding work
openclaw attach is useful because it makes a common workflow explicit: start a task in an assistant session, hand the coding portion to Claude Code, then let that access expire. The important discipline is not the command syntax. It is choosing the right session, a short TTL, a clean MCP configuration, and a task narrow enough to review.
For the larger picture, start with what OpenClaw is and keep the Gateway’s own security audit and access controls current. A temporary handoff works best when the surrounding system already has clear boundaries.