team-handoff

Team Handoff

Use when the user says "open a session on the team server for this", "hand this off to ", or "summarize this for a new agent and start it on ", and the target is a shared OpenClaw Gateway behind an identity-aware proxy (Cloudflare Access).

One Gateway request, as the operator's own identity. No browser automation, no SSH, no polling.

Script: scripts/team-handoff.sh

Setup (once per machine)

1. Operator config, outside any repo: ${XDG_CONFIG_HOME:-~/.config}/openclaw/team-handoff.env

   OPENCLAW_HANDOFF_URL=https://gateway.example      # the shared Gateway's public origin
   OPENCLAW_HANDOFF_AGENT=main                        # default agent id on that Gateway
   OPENCLAW_HANDOFF_PROJECT=example-project           # default projects.list id
   # optional:
   # OPENCLAW_HANDOFF_CLI=/path/to/openclaw           # installed OpenClaw CLI (default: openclaw on PATH)
   # OPENCLAW_HANDOFF_PROFILE_DIR=~/.openclaw/profiles/team
   # OPENCLAW_HANDOFF_SSH_HOST=gateway-host           # operator fallback only; see below
   

2. Isolated CLI profile so the local Gateway config is never touched. The script writes it on first probe when missing: OPENCLAW_STATE_DIR and OPENCLAW_CONFIG_PATH point at the profile dir, whose openclaw.json holds only gateway.mode: "remote", gateway.remote.url, and an exec secret provider that runs cloudflared access token -app=<url> for the Cf-Access-Token header (gateway.remote.edgeAuth, see the OpenClaw docs page "Remote access", section "Gateway behind an identity-aware proxy"). The provider command must be the real cloudflared binary, not a symlink.

3. The human logs in once per Access session lifetime (agents cannot):

   cloudflared access login https://gateway.example
   

   probe prints ok when the chain works. Exec provider "cloudflare-access" exited with code 1 or an HTTP 302 on upgrade means the login lapsed: ask the human to run it again; do not switch to the SSH fallback on your own.

Why there is no token to mint: with gateway.auth.mode: "trusted-proxy" the proxy authenticates the user and the Gateway maps the identity header to scopes; first connection auto-pairs a CLI device with the proxy's deviceAutoApprove scopes, which cover sessions.create.

Use

bash scripts/team-handoff.sh probe
bash scripts/team-handoff.sh create \
  --label "Installed-package entry cap durable fix" \
  --name tree-cap-fix --base origin/main \
  --message-file /path/to/handoff.md
bash scripts/team-handoff.sh status <sessionKey>
bash scripts/team-handoff.sh archive <sessionKey> <sessionId>

create prints url: in the Control UI form <origin>/chat/<agent>/<label-slug>-<session-key-uuid-without-dashes>, plus the session key and run id. Hand the human that URL. Creation returns before the worktree is prepared; running with worktree: null right after is normal, and the agent's first turn starts once the checkout binds. Read status once; do not loop.

Payload

• Branch first. Push the work, pass --base <branch>, keep the long handoff in the branch (for example .openclaw/handoff.md); the message is then three lines: what the branch is, what to do first, what not to do. Local files are unreachable from the Gateway; commit them or summarize the numbers.
• Without a branch, the whole handoff goes in --message-file: a one-line title first (it becomes the session title and URL slug), then goal, verified facts with numbers, owner files, the agreed plan and order, proof expectations, and explicit non-goals.
• Name scope boundaries when a local session keeps part of the work, so two agents do not open duplicate PRs.

Failure modes

• managed worktree allocation lease .../capacity was lost: the Gateway lost its worktree capacity lease during a slow project refetch. A retry in the same session then fails with branch already exists: openclaw/<name> because the failed attempt leaked its branch. Create a new session with a different --name; archive the dead one.
• chat.send requires idempotencyKey; sessions.patch lifecycle changes require expectedSessionId.

SSH operator fallback

--via ssh runs the same sessions.create on the Gateway host as the Gateway's service user (OPENCLAW_HANDOFF_SSH_HOST, OPENCLAW_HANDOFF_REMOTE_CLI, OPENCLAW_HANDOFF_REMOTE_USER). The session is then owned by the operator identity, not the human. Use only when the human asks for it; never change Gateway config or restart anything from this path.

Don'ts

• Do not drive the Gateway's web UI from an agent browser or sign in to the identity provider.
• Do not point the machine's primary openclaw.json at the shared Gateway.
• Do not poll session history in a loop.