Beginner onboarding friction points: SSH prerequisites, troubleshooting, and context links

[bobbythelobster]

This guide is excellent for first-time users overall. I found a few beginner-friction points that could block setup for non-technical users.

High-impact onboarding gaps for new users

1) SSH prerequisites are assumed

Many beginners won’t have SSH tools or keys ready.

Suggested additions:

• Add a short prereq checklist before Part 1:
  • Confirm exists ()
  • Confirm Generating public/private ed25519 key pair.
    Enter file in which to save the key (/Users/claudine/.ssh/id_ed25519): exists
  • Confirm exists (and how to create if missing)
• Add OS-specific links for SSH setup:
  • macOS/Linux terminal basics
  • Windows (PowerShell/OpenSSH / WSL path differences)

2) Key filename/path ambiguity

Current instructions say , but beginners may not know the filename.

Suggested additions:

• Show how to list keys:
  total 32
  drwx------@ 6 claudine staff 192 Feb 24 20:00 .
  drwxr-x---+ 48 claudine staff 1536 Mar 4 15:53 ..
  -rw-------@ 1 claudine staff 411 Feb 18 20:54 id_ed25519
  -rw-r--r--@ 1 claudine staff 99 Feb 18 20:54 id_ed25519.pub
  -rw-------@ 1 claudine staff 3020 Feb 24 20:00 known_hosts
  -rw-------@ 1 claudine staff 2284 Feb 22 20:55 known_hosts.old
• Show default key names (, etc.) and what to do if they differ.

3) No explicit SSH troubleshooting section

If SSH fails, beginners often get stuck hard.

Suggested mini-runbook:

• Incorrect user ( vs provider-specific username)

Also suggest a basic test command sequence users can copy-paste.

4) Installer prerequisites and failure cases not documented

flow is smooth when it works, but beginners need recovery guidance.

Suggested additions:

• Verify exists
• Note possible apt lock/network failures
• Mention how to retry safely
• Link to official install docs for deeper troubleshooting

5) Discord channel/server ID flow can still confuse beginners

Developer Mode step is good, but format expectations can be clearer.

Suggested additions:

• Include one explicit sample of expected format if wizard asks
• Add quick “how to copy Server ID” and “how to copy Channel ID” with screenshots/links

6) “access not configured” pairing step could use context

Good that this is called out; beginners may not understand why this is happening.

Suggested additions:

• One sentence explaining this is expected due default safety gating
• Clarify where to run approve command (same SSH terminal on VPS)

7) Add “What this means” notes + links for jargon

Guide is practical, but terms like OAuth2, intents, allowlist, pairing, token reset can be unfamiliar.

Suggested additions:

• Tiny glossary box (1 line each) + links to official docs
• “Learn more” links at end of each part for users who want context

8) Add final validation checklist for confidence

Beginners need a success checklist after setup.

Suggested section:

• Bot appears online
• Bot can receive/respond in DM
• Approved pairing identity works
• Channel allowlist behavior verified
• OpenClaw status

Overview
┌─────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Item │ Value │
├─────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Dashboard │ http://127.0.0.1:18789/ │
│ OS │ macos 15.7.3 (arm64) · node 22.22.0 │
│ Tailscale │ off │
│ Channel │ stable (default) │
│ Update │ pnpm · npm latest 2026.3.2 │
│ Gateway │ local · ws://127.0.0.1:18789 (local loopback) · reachable 10ms · auth token · Mac (192.168.2. │
│ │ 104) app 2026.3.2 macos 15.7.3 │
│ Gateway service │ LaunchAgent installed · loaded · running (pid 24547) │
│ Node service │ LaunchAgent not installed │
│ Agents │ 4 · 1 bootstrap file present · sessions 203 · default main active just now │
│ Memory │ 910 files · 6010 chunks · sources memory, sessions · plugin memory-core · vector ready · fts │
│ │ ready · cache on (5174) │
│ Probes │ skipped (use --deep) │
│ Events │ none │
│ Heartbeat │ disabled (main), disabled (edgar), 30m (john-clawmack), disabled (john-mcclawfee) │
│ Sessions │ 203 active · default gpt-5.3-codex (200k ctx) · 4 stores │
└─────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────┘

Security audit
Summary: 0 critical · 4 warn · 1 info
WARN Reverse proxy headers are not trusted
gateway.bind is loopback and gateway.trustedProxies is empty. If you expose the Control UI through a reverse proxy, configure trusted proxies so local-client c…
Fix: Set gateway.trustedProxies to your proxy IPs or keep the Control UI local-only.
WARN Some configured models are below recommended tiers
Smaller/older models are generally more susceptible to prompt injection and tool misuse. - anthropic/claude-haiku-4-5 (Haiku tier (smaller model)) @ agents.def…
Fix: Use the latest, top-tier model for any bot with tools or untrusted inboxes. Avoid Haiku tiers; prefer GPT-5+ and Claude 4.5+.
WARN Potential multi-user setup detected (personal-assistant model warning)
Heuristic signals indicate this gateway may be reachable by multiple users: - channels.discord.groupPolicy="allowlist" with configured group targets - channels…
Fix: If users may be mutually untrusted, split trust boundaries (separate gateways + credentials, ideally separate OS users/hosts). If you intentionally run shared-user access, set agents.defaults.sandbox.mode="all", keep tools.fs.workspaceOnly=true, deny runtime/fs/web tools unless required, and keep personal/private identities + credentials off that runtime.
WARN Discord slash commands have no allowlists
Discord slash commands are enabled, but neither an owner allowFrom list nor any per-guild/channel users allowlist is configured; /… commands will be rejected f…
Fix: Add your user id to channels.discord.allowFrom (or approve yourself via pairing), or configure channels.discord.guilds..users.
Full report: openclaw security audit
Deep probe: openclaw security audit --deep

Channels
┌─────────────┬─────────┬────────┬────────────────────────────────────────────────────────────────────────────────────┐
│ Channel │ Enabled │ State │ Detail │
├─────────────┼─────────┼────────┼────────────────────────────────────────────────────────────────────────────────────┤
│ Telegram │ ON │ OK │ token config×4 (8550…eP_c · len 46) · accounts 4/4 │
│ Discord │ ON │ OK │ token config×2 (MTQ3…iheA · len 72) · accounts 2/2 │
│ Signal │ ON │ WARN │ configured · gateway: Channel error: signal daemon not ready (HTTP 404) │
│ BlueBubbles │ ON │ OK │ configured │
└─────────────┴─────────┴────────┴────────────────────────────────────────────────────────────────────────────────────┘

Sessions
┌───────────────────────────────────────────┬────────┬──────────┬───────────────────┬─────────────────────────────────┐
│ Key │ Kind │ Age │ Model │ Tokens │
├───────────────────────────────────────────┼────────┼──────────┼───────────────────┼─────────────────────────────────┤
│ agent:main:telegram:direct:3835… │ direct │ just now │ gpt-5.3-codex │ 202k/272k (74%) · 🗄️ 99% cached │
│ agent:main:main │ direct │ just now │ claude-opus-4-6 │ 91k/200k (45%) · 🗄️ 100% cached │
│ agent:edgar:telegram:direct:383… │ direct │ 6m ago │ gpt-5.3-codex │ 29k/272k (11%) · 🗄️ 99% cached │
│ agent:edgar:main │ direct │ 6m ago │ gpt-5.3-codex │ 14k/272k (5%) · 🗄️ 54% cached │
│ agent:main:cron:1fdeeee6-a984-4… │ direct │ 7m ago │ claude-sonnet-4-6 │ 59k/200k (30%) · 🗄️ 391% cached │
│ agent:main:cron:1fdeeee6-a984-4… │ direct │ 7m ago │ claude-sonnet-4-6 │ 59k/200k (30%) · 🗄️ 391% cached │
│ agent:john-clawmack:main │ direct │ 13m ago │ claude-opus-4-6 │ 23k/200k (11%) · 🗄️ 38% cached │
│ agent:edgar:cron:d8293a66-d87f-… │ direct │ 18m ago │ claude-sonnet-4-6 │ 22k/200k (11%) · 🗄️ 944% cached │
│ agent:edgar:cron:d8293a66-d87f-… │ direct │ 18m ago │ claude-sonnet-4-6 │ 22k/200k (11%) · 🗄️ 944% cached │
│ agent:main:cron:1fdeeee6-a984-4… │ direct │ 22m ago │ claude-sonnet-4-6 │ 30k/200k (15%) · 🗄️ 670% cached │
└───────────────────────────────────────────┴────────┴──────────┴───────────────────┴─────────────────────────────────┘

FAQ: https://docs.openclaw.ai/faq
Troubleshooting: https://docs.openclaw.ai/troubleshooting

Next steps:
Need to share? openclaw status --all
Need to debug live? openclaw logs --follow
Need to test channels? openclaw status --deep shows healthy

---

If useful, I can open a PR adding:

1. a compact prerequisites section,
2. an SSH troubleshooting appendix,
3. a beginner glossary + official doc links,
   while keeping your existing flow intact.

[AngelCodes95]

Lets see what you got @bobbythelobster. I'm curious to see your solutions. I'll wait for your PR.