Skip to content

Commit 62112d9

Browse files
steipetesteipete
committed
feat: add onboarding doc links
1 parent 19c95d0 commit 62112d9

7 files changed

Lines changed: 110 additions & 21 deletions

File tree

‎docs/gateway/configuration.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1194,6 +1194,12 @@ Control UI base path:
11941194
- Examples: `"/ui"`, `"/clawdbot"`, `"/apps/clawdbot"`.
11951195
- Default: root (`/`) (unchanged).
11961196

1197+
Related docs:
1198+
- [Control UI](/web/control-ui)
1199+
- [Web overview](/web)
1200+
- [Tailscale](/gateway/tailscale)
1201+
- [Remote access](/gateway/remote)
1202+
11971203
Notes:
11981204
- `clawdbot gateway` refuses to start unless `gateway.mode` is set to `local` (or you pass the override flag).
11991205
- `gateway.port` controls the single multiplexed port used for WebSocket + HTTP (control UI, hooks, A2UI).

‎src/commands/configure.ts‎

Lines changed: 40 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,14 @@ async function promptGatewayConfig(
150150

151151
let tailscaleResetOnExit = false;
152152
if (tailscaleMode !== "off") {
153+
note(
154+
[
155+
"Docs:",
156+
"https://docs.clawd.bot/gateway/tailscale",
157+
"https://docs.clawd.bot/web",
158+
].join("\n"),
159+
"Tailscale",
160+
);
153161
tailscaleResetOnExit = Boolean(
154162
guardCancel(
155163
await confirm({
@@ -300,6 +308,7 @@ async function promptAuthConfig(
300308
} catch (err) {
301309
spin.stop("OAuth failed");
302310
runtime.error(String(err));
311+
note("Trouble with OAuth? See https://docs.clawd.bot/start/faq", "OAuth");
303312
}
304313
} else if (authChoice === "openai-codex") {
305314
const isRemote = isRemoteEnvironment();
@@ -373,6 +382,7 @@ async function promptAuthConfig(
373382
} catch (err) {
374383
spin.stop("OpenAI OAuth failed");
375384
runtime.error(String(err));
385+
note("Trouble with OAuth? See https://docs.clawd.bot/start/faq", "OAuth");
376386
}
377387
} else if (authChoice === "antigravity") {
378388
const isRemote = isRemoteEnvironment();
@@ -447,6 +457,7 @@ async function promptAuthConfig(
447457
} catch (err) {
448458
spin.stop("Antigravity OAuth failed");
449459
runtime.error(String(err));
460+
note("Trouble with OAuth? See https://docs.clawd.bot/start/faq", "OAuth");
450461
}
451462
} else if (authChoice === "apiKey") {
452463
const key = guardCancel(
@@ -608,9 +619,11 @@ export async function runConfigureWizard(
608619
note(summarizeExistingConfig(baseConfig), title);
609620
if (!snapshot.valid && snapshot.issues.length > 0) {
610621
note(
611-
snapshot.issues
612-
.map((iss) => `- ${iss.path}: ${iss.message}`)
613-
.join("\n"),
622+
[
623+
...snapshot.issues.map((iss) => `- ${iss.path}: ${iss.message}`),
624+
"",
625+
"Docs: https://docs.clawd.bot/gateway/configuration",
626+
].join("\n"),
614627
"Config issues",
615628
);
616629
}
@@ -789,6 +802,14 @@ export async function runConfigureWizard(
789802
await healthCommand({ json: false, timeoutMs: 10_000 }, runtime);
790803
} catch (err) {
791804
runtime.error(`Health check failed: ${String(err)}`);
805+
note(
806+
[
807+
"Docs:",
808+
"https://docs.clawd.bot/gateway/health",
809+
"https://docs.clawd.bot/gateway/troubleshooting",
810+
].join("\n"),
811+
"Health check help",
812+
);
792813
}
793814
}
794815

@@ -797,20 +818,22 @@ export async function runConfigureWizard(
797818
runtime.error(controlUiAssets.message);
798819
}
799820

800-
note(
801-
(() => {
802-
const bind = nextConfig.gateway?.bind ?? "loopback";
803-
const links = resolveControlUiLinks({
804-
bind,
805-
port: gatewayPort,
806-
basePath: nextConfig.gateway?.controlUi?.basePath,
807-
});
808-
return [`Web UI: ${links.httpUrl}`, `Gateway WS: ${links.wsUrl}`].join(
809-
"\n",
810-
);
811-
})(),
812-
"Control UI",
813-
);
821+
note(
822+
(() => {
823+
const bind = nextConfig.gateway?.bind ?? "loopback";
824+
const links = resolveControlUiLinks({
825+
bind,
826+
port: gatewayPort,
827+
basePath: nextConfig.gateway?.controlUi?.basePath,
828+
});
829+
return [
830+
`Web UI: ${links.httpUrl}`,
831+
`Gateway WS: ${links.wsUrl}`,
832+
"Docs: https://docs.clawd.bot/web/control-ui",
833+
].join("\n");
834+
})(),
835+
"Control UI",
836+
);
814837

815838
const browserSupport = await detectBrowserOpenSupport();
816839
if (!browserSupport.ok) {

‎src/commands/onboard-helpers.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,9 @@ export function formatControlUiSshHint(params: {
195195
"Then open:",
196196
localUrl,
197197
authedUrl,
198+
"Docs:",
199+
"https://docs.clawd.bot/gateway/remote",
200+
"https://docs.clawd.bot/web/control-ui",
198201
]
199202
.filter(Boolean)
200203
.join("\n");

‎src/commands/onboard-providers.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ async function noteProviderPrimer(prompter: WizardPrompter): Promise<void> {
3939
"DM security: default is pairing; unknown DMs get a pairing code.",
4040
"Approve with: clawdbot pairing approve --provider <provider> <code>",
4141
'Public DMs require dmPolicy="open" + allowFrom=["*"].',
42+
"Docs: https://docs.clawd.bot/start/pairing",
4243
"",
4344
"WhatsApp: links via WhatsApp Web (scan QR), stores creds for future sends.",
4445
"WhatsApp: dedicated second number recommended; primary number OK (self-chat).",
@@ -59,6 +60,7 @@ async function noteTelegramTokenHelp(prompter: WizardPrompter): Promise<void> {
5960
"2) Run /newbot (or /mybots)",
6061
"3) Copy the token (looks like 123456:ABC...)",
6162
"Tip: you can also set TELEGRAM_BOT_TOKEN in your env.",
63+
"Docs: https://docs.clawd.bot/telegram",
6264
].join("\n"),
6365
"Telegram bot token",
6466
);
@@ -71,6 +73,7 @@ async function noteDiscordTokenHelp(prompter: WizardPrompter): Promise<void> {
7173
"2) Bot → Add Bot → Reset Token → copy token",
7274
"3) OAuth2 → URL Generator → scope 'bot' → invite to your server",
7375
"Tip: enable Message Content Intent if you need message text.",
76+
"Docs: https://docs.clawd.bot/discord",
7477
].join("\n"),
7578
"Discord bot token",
7679
);
@@ -158,6 +161,7 @@ async function noteSlackTokenHelp(
158161
"4) Enable Event Subscriptions (socket) for message events",
159162
"5) App Home → enable the Messages tab for DMs",
160163
"Tip: set SLACK_BOT_TOKEN + SLACK_APP_TOKEN in your env.",
164+
"Docs: https://docs.clawd.bot/slack",
161165
"",
162166
"Manifest (JSON):",
163167
manifest,
@@ -298,6 +302,7 @@ async function maybeConfigureDmPolicies(params: {
298302
"Default: pairing (unknown DMs get a pairing code).",
299303
`Approve: clawdbot pairing approve --provider ${params.provider} <code>`,
300304
`Public DMs: ${params.policyKey}="open" + ${params.allowFromKey} includes "*".`,
305+
"Docs: https://docs.clawd.bot/start/pairing",
301306
].join("\n"),
302307
`${params.label} DM access`,
303308
);
@@ -383,6 +388,7 @@ async function promptWhatsAppAllowFrom(
383388
"- disabled: ignore WhatsApp DMs",
384389
"",
385390
`Current: dmPolicy=${existingPolicy}, allowFrom=${existingLabel}`,
391+
"Docs: https://docs.clawd.bot/whatsapp",
386392
].join("\n"),
387393
"WhatsApp DM access",
388394
);
@@ -551,6 +557,7 @@ export async function setupProviders(
551557
[
552558
"Scan the QR with WhatsApp on your phone.",
553559
`Credentials are stored under ${WA_WEB_AUTH_DIR}/ for future runs.`,
560+
"Docs: https://docs.clawd.bot/whatsapp",
554561
].join("\n"),
555562
"WhatsApp linking",
556563
);
@@ -566,6 +573,10 @@ export async function setupProviders(
566573
await loginWeb(false, "web");
567574
} catch (err) {
568575
runtime.error(`WhatsApp login failed: ${String(err)}`);
576+
await prompter.note(
577+
"Docs: https://docs.clawd.bot/whatsapp",
578+
"WhatsApp help",
579+
);
569580
}
570581
} else if (!whatsappLinked) {
571582
await prompter.note(
@@ -864,6 +875,7 @@ export async function setupProviders(
864875
'Link device with: signal-cli link -n "Clawdbot"',
865876
"Scan QR in Signal → Linked Devices",
866877
"Then run: clawdbot gateway call providers.status --params '{\"probe\":true}'",
878+
"Docs: https://docs.clawd.bot/signal",
867879
].join("\n"),
868880
"Signal next steps",
869881
);
@@ -902,6 +914,7 @@ export async function setupProviders(
902914
"Ensure Clawdbot has Full Disk Access to Messages DB.",
903915
"Grant Automation permission for Messages when prompted.",
904916
"List chats with: imsg chats --limit 20",
917+
"Docs: https://docs.clawd.bot/imessage",
905918
].join("\n"),
906919
"iMessage next steps",
907920
);

‎src/commands/onboard-remote.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,10 @@ export async function promptRemoteGatewayConfig(
4242

4343
if (!hasBonjourTool) {
4444
await prompter.note(
45-
"Bonjour discovery requires dns-sd (macOS) or avahi-browse (Linux).",
45+
[
46+
"Bonjour discovery requires dns-sd (macOS) or avahi-browse (Linux).",
47+
"Docs: https://docs.clawd.bot/gateway/discovery",
48+
].join("\n"),
4649
"Discovery",
4750
);
4851
}
@@ -98,6 +101,7 @@ export async function promptRemoteGatewayConfig(
98101
`ssh -N -L 18789:127.0.0.1:18789 <user>@${host}${
99102
selectedBeacon.sshPort ? ` -p ${selectedBeacon.sshPort}` : ""
100103
}`,
104+
"Docs: https://docs.clawd.bot/gateway/remote",
101105
].join("\n"),
102106
"SSH tunnel",
103107
);

‎src/commands/onboard-skills.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -168,6 +168,7 @@ export async function setupSkills(
168168
runtime.log(
169169
"Tip: run `clawdbot doctor` to review skills + requirements.",
170170
);
171+
runtime.log("Docs: https://docs.clawd.bot/skills");
171172
}
172173
}
173174
}

‎src/wizard/onboarding.ts‎

Lines changed: 42 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -142,9 +142,11 @@ export async function runOnboardingWizard(
142142
await prompter.note(summarizeExistingConfig(baseConfig), title);
143143
if (!snapshot.valid && snapshot.issues.length > 0) {
144144
await prompter.note(
145-
snapshot.issues
146-
.map((iss) => `- ${iss.path}: ${iss.message}`)
147-
.join("\n"),
145+
[
146+
...snapshot.issues.map((iss) => `- ${iss.path}: ${iss.message}`),
147+
"",
148+
"Docs: https://docs.clawd.bot/gateway/configuration",
149+
].join("\n"),
148150
"Config issues",
149151
);
150152
}
@@ -302,6 +304,10 @@ export async function runOnboardingWizard(
302304
} catch (err) {
303305
spin.stop("OAuth failed");
304306
runtime.error(String(err));
307+
await prompter.note(
308+
"Trouble with OAuth? See https://docs.clawd.bot/start/faq",
309+
"OAuth help",
310+
);
305311
}
306312
} else if (authChoice === "openai-codex") {
307313
const isRemote = isRemoteEnvironment();
@@ -375,6 +381,10 @@ export async function runOnboardingWizard(
375381
} catch (err) {
376382
spin.stop("OpenAI OAuth failed");
377383
runtime.error(String(err));
384+
await prompter.note(
385+
"Trouble with OAuth? See https://docs.clawd.bot/start/faq",
386+
"OAuth help",
387+
);
378388
}
379389
} else if (authChoice === "antigravity") {
380390
const isRemote = isRemoteEnvironment();
@@ -448,6 +458,10 @@ export async function runOnboardingWizard(
448458
} catch (err) {
449459
spin.stop("Antigravity OAuth failed");
450460
runtime.error(String(err));
461+
await prompter.note(
462+
"Trouble with OAuth? See https://docs.clawd.bot/start/faq",
463+
"OAuth help",
464+
);
451465
}
452466
} else if (authChoice === "apiKey") {
453467
const key = await prompter.text({
@@ -520,6 +534,14 @@ export async function runOnboardingWizard(
520534

521535
let tailscaleResetOnExit = false;
522536
if (tailscaleMode !== "off") {
537+
await prompter.note(
538+
[
539+
"Docs:",
540+
"https://docs.clawd.bot/gateway/tailscale",
541+
"https://docs.clawd.bot/web",
542+
].join("\n"),
543+
"Tailscale",
544+
);
523545
tailscaleResetOnExit = Boolean(
524546
await prompter.confirm({
525547
message: "Reset Tailscale serve/funnel on exit?",
@@ -693,6 +715,14 @@ export async function runOnboardingWizard(
693715
await healthCommand({ json: false, timeoutMs: 10_000 }, runtime);
694716
} catch (err) {
695717
runtime.error(`Health check failed: ${String(err)}`);
718+
await prompter.note(
719+
[
720+
"Docs:",
721+
"https://docs.clawd.bot/gateway/health",
722+
"https://docs.clawd.bot/gateway/troubleshooting",
723+
].join("\n"),
724+
"Health check help",
725+
);
696726
}
697727

698728
const controlUiAssets = await ensureControlUiAssetsBuilt(runtime);
@@ -726,6 +756,7 @@ export async function runOnboardingWizard(
726756
`Web UI: ${links.httpUrl}`,
727757
tokenParam ? `Web UI (with token): ${authedUrl}` : undefined,
728758
`Gateway WS: ${links.wsUrl}`,
759+
"Docs: https://docs.clawd.bot/web/control-ui",
729760
]
730761
.filter(Boolean)
731762
.join("\n");
@@ -772,5 +803,13 @@ export async function runOnboardingWizard(
772803
}
773804
}
774805

806+
await prompter.note(
807+
[
808+
"Back up your agent workspace.",
809+
"Docs: https://docs.clawd.bot/concepts/agent-workspace",
810+
].join("\n"),
811+
"Workspace backup",
812+
);
813+
775814
await prompter.outro("Onboarding complete.");
776815
}

0 commit comments

Comments
 (0)