/unclawg-internet

Get set up with OpenClaw — account, agent, soul, and discovery config in one sitting.

What This Produces

1. OpenClaw account + API keys
2. Agent identity file (.claude/agents/<agent-id>.env)
3. Soul draft (soul_md policy document via API)
4. Discovery mode file (modes/<project>.local.md for /unclawg-discover)
5. Browser auto-logged into the approval portal

NEVER Do These Things

• NEVER show the machine key secret more than once. It cannot be retrieved after creation.
• NEVER store passwords or secrets in any file the user didn’t ask for.
• NEVER skip the confirmation before creating the account.
• NEVER run search/research in the main conversation context. Always delegate to Task tool subagents (see Rule below).

Subagent Rule

All search, web fetch, and research operations MUST be delegated to Task tool subagents. This preserves the main conversation context for the soul interview flow. Examples:

• Looking up a user’s website/product to understand their business → subagent
• Searching for competitor landscape → subagent
• Fetching example content from platforms the user mentions → subagent
• Validating URLs or checking platform availability → subagent

The main conversation should only contain: questions, user answers, confirmations, and artifact writes.

Config

OPENCLAW_PORTAL_URL=https://unclawg.com
SPAPS_URL=https://api.unclawg.com
APPROVAL_API_URL=https://api.unclawg.com
# Optional only for self-hosted gateways that do not inject server-side app binding:
OPENCLAW_API_KEY=
TENANT_ID=d0000000-0000-0000-0000-000000000001
# Proof-of-humanity fallback contacts (used when signup is pending):
OPENCLAW_PROOF_PRIMARY_X=@your-primary-proof-handle
OPENCLAW_PROOF_SECONDARY_X=https://x.com/your-backup-proof-handle

SPAPS_URL is the Unclawg auth facade (/api/auth/* and /api/cli/device/*), not a direct client call to SPAPS. On api.unclawg.com, the gateway injects X-API-Key server-side, so do not ask users for SPAPS_API_KEY.

References

• references/soul-interview.md — Full soul interview cascade (Phase B, Rounds 1-5). Read when entering the interview phase.
• references/artifact-templates.md — Soul draft templates, mode file template, smoke test, and summary output (Phase C/D). Read when writing artifacts.
• /unclawg-admin — Operator waitlist triage when signup proof-of-humanity is pending.
• references/default-soul.md — Default soul template for users who skip the interview.

Phase 0 — Detect Existing Setup

Before starting onboarding, check if the user is already set up (partially or fully).

Check for existing identity

ls .claude/agents/*.env 2>/dev/null

If identity files exist, read each one and extract OPENCLAW_AGENT_ID, OPENCLAW_MACHINE_KEY_ID.

Verify the machine key works

RESPONSE=$(curl -s -w "\nHTTP_STATUS:%{http_code}" -X POST \
  -H "X-Tenant-Id: ${TENANT_ID}" \
  -H "X-Machine-Key-Id: ${KEY_ID}" \
  -H "X-Machine-Secret: ${KEY_SECRET}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  "${APPROVAL_API_URL}/v0/approval-requests/social-reply" \
  -d "{
    \"agent_id\": \"${AGENT_ID}\",
    \"action\": \"social_reply_approval\",
    \"resource_type\": \"social_post\",
    \"resource_id\": \"test://setup-check-$(date +%s)\",
    \"expires_at\": \"$(date -u -v+1m +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -d '+1 minute' +%Y-%m-%dT%H:%M:%SZ)\",
    \"proposed_reply\": \"Setup verification ping.\",
    \"candidate\": {
      \"source_platform\": \"other\",
      \"source_post_url\": \"https://example.com/setup-check\",
      \"source_post_text\": \"Setup verification\",
      \"discovered_at\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"
    }
  }")

STATUS=$(echo "$RESPONSE" | grep "HTTP_STATUS:" | cut -d: -f2)

Check for missing pieces

ls modes/${AGENT_ID}.local.md 2>/dev/null

Triage result

Show the user what’s present and what’s missing:

Existing setup found:

  Agent ID:   ${AGENT_ID}
  Key ID:     ${KEY_ID}
  Identity:   .claude/agents/${AGENT_ID}.env
  Key valid:  ✓ (or ✗ — expired/revoked, needs re-provisioning)
  Soul:       [written / not yet]
  Mode file:  [found / missing]

Then offer to fill gaps:

• Key invalid → need to re-authenticate and provision a new key (jump to Step 4 — device flow)
• Soul missing → jump to Phase B (read references/soul-interview.md)
• Mode file missing → jump to Phase C Step 8 (read references/artifact-templates.md)
• Everything present and valid → “You’re all set. Run /unclawg-discover to start finding people.”

Skip any phase that’s already complete. Do not re-run the full onboarding.

Phase A — Account Provisioning

Step 1 — Ask Email

Ask one question:

“What email should we use for your OpenClaw account?”

Step 2 — Pick Agent Name

Ask:

“Name your agent — this is the ID that shows up in the approval portal. Examples: my-trading-bot, content-writer, code-deployer“

Default suggestion: derive from the current repo name or working directory.

Step 3 — Confirm

Show what’s about to happen:

Ready to set up:
  Email:    user@example.com
  Agent:    my-trading-bot
  Portal:   ${OPENCLAW_PORTAL_URL}

This starts browser-based device sign-in (no password sharing in chat),
then provisions API keys for your agent.
Continue?

Step 4 — Start CLI Device Flow (via Unclawg auth facade)

DEVICE_START_RESPONSE=$(curl -s -w "\nHTTP_STATUS:%{http_code}" -X POST \
  "${SPAPS_URL}/api/cli/device/authorize" \
  -H "Content-Type: application/json" \
  -d '{"scope":"approval_request.create.social_reply approval_revision.fulfill instruction_proposal.create agent_feedback_digest.read"}')

DEVICE_START_STATUS=$(echo "$DEVICE_START_RESPONSE" | grep "HTTP_STATUS:" | cut -d: -f2)
DEVICE_START_BODY=$(echo "$DEVICE_START_RESPONSE" | sed '/HTTP_STATUS:/d')

If using a self-hosted gateway that requires client-supplied app binding, add: -H "X-API-Key: ${OPENCLAW_API_KEY}".

• 200 → continue
• 404/405 with AUTH_PROXY_ROUTE_NOT_FOUND → stop and tell the user the API gateway must be updated to proxy /api/cli/device/*.
• Other error → print and stop

Step 5 — Complete Browser Authorization

Extract device-flow fields (supports both envelope and plain payload):

DEVICE_CODE=$(echo "$DEVICE_START_BODY" | jq -r '.data.device_code // .device_code // empty')
USER_CODE=$(echo "$DEVICE_START_BODY" | jq -r '.data.user_code // .user_code // empty')
VERIFY_URL=$(echo "$DEVICE_START_BODY" | jq -r '.data.verification_uri_complete // .data.auth_url // .data.verification_uri // .verification_uri_complete // .auth_url // .verification_uri // empty')
POLL_INTERVAL=$(echo "$DEVICE_START_BODY" | jq -r '.data.interval // .interval // 5')

If any required value is missing, print the response and stop.

Open the verification URL:

open "$VERIFY_URL" 2>/dev/null \
  || xdg-open "$VERIFY_URL" 2>/dev/null \
  || echo "Open this URL to continue: $VERIFY_URL"

Tell the user:

• “Browser opened. Sign in and approve this device request.”
• “If asked, enter code: ${USER_CODE}.”
• “If this email is new, create the account in that browser flow first.”

Step 6 — Poll for Tokens (No password needed)

while true; do
  TOKEN_RESPONSE=$(curl -s -w "\nHTTP_STATUS:%{http_code}" -X POST \
    "${SPAPS_URL}/api/cli/device/token" \
    -H "Content-Type: application/json" \
    -d "{
      \"device_code\": \"${DEVICE_CODE}\"
    }")

  TOKEN_STATUS=$(echo "$TOKEN_RESPONSE" | grep "HTTP_STATUS:" | cut -d: -f2)
  TOKEN_BODY=$(echo "$TOKEN_RESPONSE" | sed '/HTTP_STATUS:/d')

  if [ "$TOKEN_STATUS" = "200" ]; then
    ACCESS_TOKEN=$(echo "$TOKEN_BODY" | jq -r '.data.access_token // .access_token // empty')
    REFRESH_TOKEN=$(echo "$TOKEN_BODY" | jq -r '.data.refresh_token // .refresh_token // empty')
    break
  fi

  ERROR_CODE=$(echo "$TOKEN_BODY" | jq -r '.error.code // .code // .error // empty')
  case "$ERROR_CODE" in
    authorization_pending)
      sleep "${POLL_INTERVAL}"
      ;;
    slow_down)
      POLL_INTERVAL=$((POLL_INTERVAL + 5))
      sleep "${POLL_INTERVAL}"
      ;;
    access_denied|expired_token|invalid_grant)
      echo "Device flow ended: ${ERROR_CODE}"
      echo "$TOKEN_BODY"
      exit 1
      ;;
    *)
      echo "Unexpected device-flow token response:"
      echo "$TOKEN_BODY"
      exit 1
      ;;
  esac
done

If token polling keeps returning pending because signup proof is blocked, direct operators to /unclawg-admin and continue with Phase B only.

Step 6b — Verify Authenticated Account

Confirm the signed-in account and compare against requested email:

WHOAMI_RESPONSE=$(curl -s -X GET \
  "${SPAPS_URL}/api/auth/user" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}")
WHOAMI_EMAIL=$(echo "$WHOAMI_RESPONSE" | jq -r '.data.user.email // .user.email // empty' | tr '[:upper:]' '[:lower:]')
EXPECTED_EMAIL=$(echo "${USER_EMAIL}" | tr '[:upper:]' '[:lower:]')

If WHOAMI_EMAIL differs from EXPECTED_EMAIL, show both and ask whether to continue with the authenticated account.

Step 6c — Auto-Login via Token Handoff

Immediately after obtaining tokens, open the portal with token handoff. The /auth/cli-callback route stores tokens in the browser and redirects to /approvals.

# JWT tokens are base64url — no URL-encoding needed
open "${OPENCLAW_PORTAL_URL}/auth/cli-callback?access_token=${ACCESS_TOKEN}&refresh_token=${REFRESH_TOKEN}" 2>/dev/null \
  || xdg-open "${OPENCLAW_PORTAL_URL}/auth/cli-callback?access_token=${ACCESS_TOKEN}&refresh_token=${REFRESH_TOKEN}" 2>/dev/null \
  || echo "Open this URL to log in: ${OPENCLAW_PORTAL_URL}/auth/cli-callback?access_token=${ACCESS_TOKEN}&refresh_token=${REFRESH_TOKEN}"

Tell the user: “Opening the portal in your browser — you’re logged in automatically.”

Important: Open the browser immediately after tokens are issued. The access token expires in 1 hour, but the callback page auto-refreshes stale tokens via the refresh token.

Step 7 — Provision Machine Key (Only after approved auth)

RESPONSE=$(curl -s -w "\nHTTP_STATUS:%{http_code}" -X POST \
  "${APPROVAL_API_URL}/v0/claw-governance/machine-keys" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "X-Tenant-Id: ${TENANT_ID}" \
  -d "{
    \"agent_id\": \"${AGENT_ID}\",
    \"label\": \"onboard-$(date +%Y%m%d)\",
    \"scopes\": [
      \"approval_request.create.social_reply\",
      \"approval_revision.fulfill\",
      \"agent_feedback_digest.read\",
      \"instruction_proposal.create\"
    ],
    \"ttl_days\": 90
  }")

STATUS=$(echo "$RESPONSE" | grep "HTTP_STATUS:" | cut -d: -f2)
BODY=$(echo "$RESPONSE" | sed '/HTTP_STATUS:/d')

If using a self-hosted gateway that requires client-supplied app binding, add: -H "X-API-Key: ${OPENCLAW_API_KEY}".

• 201 → extract key_id and key_secret from data.key
• 403 → scope issue, print error
• Other → print error, stop

Step 8 — Output the Env Block

Print this exactly — the user copies it into their .env or shell profile:

# ── OpenClaw Configuration ──────────────────────
# Add these to your project's .env or ~/.zshrc

OPENCLAW_API_URL=${APPROVAL_API_URL}
OPENCLAW_TENANT_ID=${TENANT_ID}
OPENCLAW_AGENT_ID=${AGENT_ID}
OPENCLAW_MACHINE_KEY_ID=${KEY_ID}
OPENCLAW_MACHINE_SECRET=${KEY_SECRET}
# Optional for non-default gateways:
OPENCLAW_API_KEY=${OPENCLAW_API_KEY}

# ⚠️  Save OPENCLAW_MACHINE_SECRET now.
#     It cannot be retrieved again.
#     If lost, rotate via the portal.
# ─────────────────────────────────────────────────

Ask before writing any file with secrets:

“Save this identity to .claude/agents/${AGENT_ID}.env for auto-discovery?”

Only if the user says yes, save the identity file for skill auto-discovery:

mkdir -p .claude/agents
cat > .claude/agents/${AGENT_ID}.env << ENVEOF
OPENCLAW_API_URL=${APPROVAL_API_URL}
OPENCLAW_TENANT_ID=${TENANT_ID}
OPENCLAW_AGENT_ID=${AGENT_ID}
OPENCLAW_MACHINE_KEY_ID=${KEY_ID}
OPENCLAW_MACHINE_SECRET=${KEY_SECRET}
OPENCLAW_API_KEY=${OPENCLAW_API_KEY}
ENVEOF

Tell the user: “Saved to .claude/agents/${AGENT_ID}.env — other skills like /unclawg-feed and /unclawg-respond will auto-discover it.”

Then print the summary:

Account provisioned.

  Portal:     ${OPENCLAW_PORTAL_URL}
  Agent ID:   ${AGENT_ID}
  Key ID:     ${KEY_ID}
  Expires:    90 days from now
  Identity:   .claude/agents/${AGENT_ID}.env

Now let's define your agent's soul.

Phase B — Soul Interview (Ask-Cascade)

Read references/soul-interview.md for the full interview flow (Rounds 1-5).

Phase C — Write Artifacts

Read references/artifact-templates.md for soul draft templates, mode file template, smoke test, and summary output.

Phase D — Summary

See the summary template in references/artifact-templates.md (bottom section).