mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-16 10:50:38 +09:00
Improve external agent invite flow (#6183)
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies. > - Agent creation can happen through local runtimes, managed runtimes, and external agents that onboard through invites. > - The old OpenClaw-oriented invite UX lived under company settings/invites and made a gateway-specific path look like a company access setting. > - That hid the broader bring-your-own-agent flow and forced operators to leave the add-agent modal when adding an external agent. > - This pull request moves external agent invite generation into the add-agent modal and makes the copy agent-oriented instead of OpenClaw-only. > - The benefit is a clearer agent-first onboarding path while company invites stay focused on human access. ## What Changed - Added an external-agent invite branch to the add-agent modal, including a dedicated prompt result view with Back navigation. - Added a shared agent onboarding prompt builder and focused modal coverage for prompt replacement/back navigation. - Removed the agent invite prompt UI from Company Settings and Company Invites, leaving Company Invites focused on human access links and invite history. - Updated the hidden OpenClaw Gateway runtime hint to direct operators to the add-agent invite flow instead of presenting it as a blocked runtime card. - Updated invite/onboarding docs, storybook coverage, and server-side onboarding copy toward generic agent language while preserving existing gateway compatibility. ## Verification - `pnpm -r typecheck` - `pnpm build` - `FAKE_BIN="$(mktemp -d)/bin"; mkdir -p "$FAKE_BIN"; printf '#!/bin/sh\nexit 1\n' > "$FAKE_BIN/tailscale"; chmod +x "$FAKE_BIN/tailscale"; PATH="$FAKE_BIN:$PATH" pnpm test:run` - `pnpm test:run` without the fake `tailscale` shim was also attempted; it failed only in two pre-existing CLI tailnet fallback tests because this host has a real Tailscale address (`100.125.202.3`) where those tests expect no Tailscale. - Focused confirmation for that host-env issue: `FAKE_BIN=... PATH="$FAKE_BIN:$PATH" pnpm exec vitest run --project paperclipai cli/src/__tests__/network-bind.test.ts cli/src/__tests__/onboard.test.ts` - Manual UI verification: served UI locally in light mode, opened add-agent modal, generated external agent prompt, verified the generated prompt replaces the form and Back returns to the form. ### Screenshots    ## Risks - Existing OpenClaw gateway compatibility remains, but operators now discover external agent onboarding from the add-agent modal instead of company settings. - Agent invites still appear in the invite history table, so that page may show agent-scoped invite rows even though it no longer creates agent onboarding prompts. - Low migration risk: no schema changes. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex, GPT-5 coding agent in Codex desktop; tool-enabled repository, shell, browser, and GitHub workflow. Context window size was not exposed by the runtime. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge
This commit is contained in:
Aron Prins
GitHub
parent
e3c875c1c7
commit
897cc322c7
17 changed files with 693 additions and 451 deletions
|
|
@ -1554,16 +1554,17 @@ function buildInviteOnboardingManifest(
|
|||
),
|
||||
onboarding: {
|
||||
instructions:
|
||||
"Join as an OpenClaw Gateway agent, save your one-time claim secret, wait for board approval, then claim your API key. Save the claim response token to ~/.openclaw/workspace/paperclip-claimed-api-key.json and load PAPERCLIP_API_KEY from that file before starting heartbeat loops. You MUST submit adapterType='openclaw_gateway', set agentDefaultsPayload.url to your ws:// or wss:// OpenClaw gateway endpoint, and include agentDefaultsPayload.headers.x-openclaw-token (or legacy x-openclaw-auth).",
|
||||
"Join as an external Paperclip agent, save your one-time claim secret, wait for board approval, then claim your API key. Use requestType='agent', include your agentName and capabilities, and set adapterType plus agentDefaultsPayload for your runtime when applicable. OpenClaw Gateway agents must use adapterType='openclaw_gateway', set agentDefaultsPayload.url to a ws:// or wss:// gateway endpoint, and include agentDefaultsPayload.headers.x-openclaw-token.",
|
||||
inviteMessage: extractInviteMessage(invite),
|
||||
recommendedAdapterType: "openclaw_gateway",
|
||||
recommendedAdapterType: null,
|
||||
requiredFields: {
|
||||
requestType: "agent",
|
||||
agentName: "Display name for this agent",
|
||||
adapterType: "Use 'openclaw_gateway' for OpenClaw Gateway agents",
|
||||
adapterType:
|
||||
"Adapter type for this runtime. Use 'openclaw_gateway' only for OpenClaw Gateway agents.",
|
||||
capabilities: "Optional capability summary",
|
||||
agentDefaultsPayload:
|
||||
"Adapter config for OpenClaw gateway. MUST include url (ws:// or wss://) and headers.x-openclaw-token (or legacy x-openclaw-auth). Optional fields: paperclipApiUrl, waitTimeoutMs, sessionKeyStrategy, sessionKey, role, scopes, disableDeviceAuth, devicePrivateKeyPem."
|
||||
"Runtime-specific adapter config. OpenClaw Gateway agents must include url (ws:// or wss://) and headers.x-openclaw-token. Other runtimes should include the config their adapter expects."
|
||||
},
|
||||
registrationEndpoint: {
|
||||
method: "POST",
|
||||
|
|
@ -1600,7 +1601,7 @@ function buildInviteOnboardingManifest(
|
|||
name: "paperclip",
|
||||
path: skillPath,
|
||||
url: skillUrl,
|
||||
installPath: "~/.openclaw/skills/paperclip/SKILL.md"
|
||||
installPath: "runtime-specific Paperclip skill location"
|
||||
}
|
||||
}
|
||||
};
|
||||
|
|
@ -1651,7 +1652,7 @@ export function buildInviteOnboardingTextDocument(
|
|||
};
|
||||
|
||||
appendBlock(`
|
||||
# Paperclip OpenClaw Gateway Onboarding
|
||||
# Paperclip Agent Onboarding
|
||||
|
||||
This document is meant to be readable by both humans and agents.
|
||||
|
||||
|
|
@ -1675,62 +1676,30 @@ export function buildInviteOnboardingTextDocument(
|
|||
appendBlock(`
|
||||
## Step 0
|
||||
|
||||
Get the OpenClaw gateway auth token (THIS MUST BE SENT)
|
||||
Token lives in:
|
||||
Decide which Paperclip adapter type matches your runtime.
|
||||
|
||||
~/.openclaw/openclaw.json -> gateway.auth.token
|
||||
Extract:
|
||||
|
||||
TOKEN="$(node -p 'require(process.env.HOME+\"/.openclaw/openclaw.json\").gateway.auth.token')"
|
||||
test -n "$TOKEN" || (echo "Missing TOKEN" && exit 1)
|
||||
test "\${#TOKEN}" -ge 16 || (echo "Gateway token unexpectedly short (\${#TOKEN})" && exit 1)
|
||||
|
||||
3) IMPORTANT: Don't accidentally drop the token when generating JSON
|
||||
If you build JSON with Node, pass the token explicitly (argv), don't rely on an un-exported env var.
|
||||
|
||||
Safe payload build looks sort of like this (substitute where necessary):
|
||||
|
||||
BODY="$(node -e '
|
||||
const token = process.argv[1];
|
||||
if (!token) process.exit(2);
|
||||
const body = {
|
||||
requestType: "agent",
|
||||
agentName: "OpenClaw",
|
||||
adapterType: "openclaw_gateway",
|
||||
capabilities: "OpenClaw agent adapter",
|
||||
agentDefaultsPayload: {
|
||||
url: "ws://127.0.0.1:18789",
|
||||
paperclipApiUrl: "http://host.docker.internal:3100",
|
||||
headers: { "x-openclaw-token": token },
|
||||
waitTimeoutMs: 120000,
|
||||
sessionKeyStrategy: "issue",
|
||||
role: "operator",
|
||||
scopes: ["operator.admin"]
|
||||
}
|
||||
};
|
||||
process.stdout.write(JSON.stringify(body));
|
||||
' "$TOKEN")"
|
||||
Use adapterType only when there is a matching Paperclip adapter. Put runtime-specific settings in agentDefaultsPayload.
|
||||
|
||||
## Step 1: Submit agent join request
|
||||
${onboarding.registrationEndpoint.method} ${
|
||||
onboarding.registrationEndpoint.url
|
||||
}
|
||||
|
||||
IMPORTANT: You MUST include agentDefaultsPayload.headers.x-openclaw-token with your gateway token.
|
||||
Legacy x-openclaw-auth is also accepted, but x-openclaw-token is preferred.
|
||||
Use adapterType "openclaw_gateway" and a ws:// or wss:// gateway URL.
|
||||
Pairing mode requirement:
|
||||
- Keep device auth enabled (recommended). If devicePrivateKeyPem is omitted, Paperclip generates and persists one during join so pairing approvals are stable.
|
||||
- You may set disableDeviceAuth=true only for special environments that cannot support pairing.
|
||||
- First run may return "pairing required" once; approve the pending pairing request in OpenClaw, then retry.
|
||||
Do NOT use /v1/responses or /hooks/* in this gateway join flow.
|
||||
|
||||
Body (JSON):
|
||||
{
|
||||
"requestType": "agent",
|
||||
"agentName": "My Agent",
|
||||
"adapterType": "adapter_type_for_this_runtime",
|
||||
"capabilities": "Short summary of what this agent can do",
|
||||
"agentDefaultsPayload": {}
|
||||
}
|
||||
|
||||
OpenClaw Gateway payload example:
|
||||
{
|
||||
"requestType": "agent",
|
||||
"agentName": "My OpenClaw Agent",
|
||||
"adapterType": "openclaw_gateway",
|
||||
"capabilities": "Optional summary",
|
||||
"capabilities": "OpenClaw gateway agent",
|
||||
"agentDefaultsPayload": {
|
||||
"url": "wss://your-openclaw-gateway.example",
|
||||
"paperclipApiUrl": "https://paperclip-hostname-your-agent-can-reach:3100",
|
||||
|
|
@ -1742,6 +1711,8 @@ export function buildInviteOnboardingTextDocument(
|
|||
}
|
||||
}
|
||||
|
||||
For OpenClaw Gateway, include agentDefaultsPayload.headers.x-openclaw-token with your gateway token. Legacy x-openclaw-auth is also accepted, but x-openclaw-token is preferred. Do NOT use /v1/responses or /hooks/* in this gateway join flow.
|
||||
|
||||
Expected response includes:
|
||||
- request id
|
||||
- one-time claimSecret
|
||||
|
|
@ -1760,35 +1731,18 @@ export function buildInviteOnboardingTextDocument(
|
|||
"claimSecret": "<one-time-claim-secret>"
|
||||
}
|
||||
|
||||
On successful claim, save the full JSON response to:
|
||||
|
||||
- ~/.openclaw/workspace/paperclip-claimed-api-key.json
|
||||
chmod 600 ~/.openclaw/workspace/paperclip-claimed-api-key.json
|
||||
|
||||
And set the PAPERCLIP_API_KEY and PAPERCLIP_API_URL in your environment variables as specified here:
|
||||
https://docs.openclaw.ai/help/environment
|
||||
|
||||
e.g.
|
||||
|
||||
{
|
||||
env: {
|
||||
PAPERCLIP_API_KEY: "...",
|
||||
PAPERCLIP_API_URL: "...",
|
||||
},
|
||||
}
|
||||
|
||||
Then set PAPERCLIP_API_KEY and PAPERCLIP_API_URL from the saved token field for every heartbeat run.
|
||||
On successful claim, save the full JSON response somewhere private for your runtime and set PAPERCLIP_API_KEY and PAPERCLIP_API_URL for future Paperclip API calls.
|
||||
|
||||
Important:
|
||||
- claim secrets expire
|
||||
- claim secrets are single-use
|
||||
- claim fails before board approval
|
||||
|
||||
## Step 4: Install Paperclip skill in OpenClaw
|
||||
## Step 4: Install Paperclip skill
|
||||
GET ${onboarding.skill.url}
|
||||
Install path: ${onboarding.skill.installPath}
|
||||
|
||||
Be sure to prepend your PAPERCLIP_API_URL to the top of your skill and note the path to your PAPERCLIP_API_URL
|
||||
Use your runtime's normal skill or instruction installation path.
|
||||
|
||||
## Text onboarding URL
|
||||
${onboarding.textInstructions.url}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue