The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
Add invite onboarding network host suggestions
Dotta7a2ecff4f0e1
diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.mdindex ffbb7fa36a..4659bb4b9f 100644--- a/doc/DEVELOPING.md+++ b/doc/DEVELOPING.md@@ -246,7 +246,7 @@ Agent-oriented invite onboarding now exposes machine-readable API docs:- `GET /api/invites/:token` returns invite summary plus onboarding and skills index links.- `GET /api/invites/:token/onboarding` returns onboarding manifest details (registration endpoint, claim endpoint template, skill install hints).-- `GET /api/invites/:token/onboarding.txt` returns a plain-text onboarding doc intended for both human operators and agents (llm.txt-style handoff).+- `GET /api/invites/:token/onboarding.txt` returns a plain-text onboarding doc intended for both human operators and agents (llm.txt-style handoff), including optional inviter message and suggested network host candidates.- `GET /api/skills/index` lists available skill documents.- `GET /api/skills/paperclip` returns the Paperclip heartbeat skill markdown.diff --git a/server/src/__tests__/invite-onboarding-text.test.ts b/server/src/__tests__/invite-onboarding-text.test.tsindex f72bb57033..0b807c55ab 100644--- a/server/src/__tests__/invite-onboarding-text.test.ts+++ b/server/src/__tests__/invite-onboarding-text.test.ts@@ -41,6 +41,9 @@ describe("buildInviteOnboardingTextDocument", () => {expect(text).toContain("/api/invites/token-123/accept");expect(text).toContain("/api/join-requests/{requestId}/claim-api-key");expect(text).toContain("/api/invites/token-123/onboarding.txt");+ expect(text).toContain("Suggested Paperclip base URLs to try");+ expect(text).toContain("http://localhost:3100");+ expect(text).toContain("host.docker.internal");});it("includes loopback diagnostics for authenticated/private onboarding", () => {@@ -69,6 +72,7 @@ describe("buildInviteOnboardingTextDocument", () => {expect(text).toContain("Connectivity diagnostics");expect(text).toContain("loopback hostname");+ expect(text).toContain("If none are reachable");});it("includes inviter message in the onboarding text when provided", () => {diff --git a/server/src/routes/access.ts b/server/src/routes/access.tsindex 340c7d7004..59fd2addbb 100644--- a/server/src/routes/access.ts+++ b/server/src/routes/access.ts@@ -377,6 +377,46 @@ function buildOnboardingDiscoveryDiagnostics(input: {return diagnostics;}+function buildOnboardingConnectionCandidates(input: {+ apiBaseUrl: string;+ bindHost: string;+ allowedHostnames: string[];+}): string[] {+ let base: URL | null = null;+ try {+ if (input.apiBaseUrl) {+ base = new URL(input.apiBaseUrl);+ }+ } catch {+ base = null;+ }++ const protocol = base?.protocol ?? "http:";+ const port = base?.port ? `:${base.port}` : "";+ const candidates = new Set<string>();++ if (base) {+ candidates.add(base.origin);+ }++ const bindHost = normalizeHostname(input.bindHost);+ if (bindHost && !isLoopbackHost(bindHost)) {+ candidates.add(`${protocol}//${bindHost}${port}`);+ }++ for (const rawHost of input.allowedHostnames) {+ const host = normalizeHostname(rawHost);+ if (!host) continue;+ candidates.add(`${protocol}//${host}${port}`);+ }++ if (base && isLoopbackHost(base.hostname)) {+ candidates.add(`${protocol}//host.docker.internal${port}`);+ }++ return Array.from(candidates);+}+function buildInviteOnboardingManifest(req: Request,token: string,@@ -402,6 +442,11 @@ function buildInviteOnboardingManifest(bindHost: opts.bindHost,allowedHostnames: opts.allowedHostnames,});+ const connectionCandidates = buildOnboardingConnectionCandidates({+ apiBaseUrl: baseUrl,+ bindHost: opts.bindHost,+ allowedHostnames: opts.allowedHostnames,+ });return {invite: toInviteSummaryResponse(req, token, invite),@@ -435,6 +480,7 @@ function buildInviteOnboardingManifest(deploymentExposure: opts.deploymentExposure,bindHost: opts.bindHost,allowedHostnames: opts.allowedHostnames,+ connectionCandidates,diagnostics: discoveryDiagnostics,guidance:opts.deploymentMode === "authenticated" && opts.deploymentExposure === "private"@@ -474,7 +520,7 @@ export function buildInviteOnboardingTextDocument(claimEndpointTemplate: { method: string; path: string };textInstructions: { path: string; url: string };skill: { path: string; url: string; installPath: string };- connectivity: { diagnostics?: JoinDiagnostic[]; guidance?: string };+ connectivity: { diagnostics?: JoinDiagnostic[]; guidance?: string; connectionCandidates?: string[] };};const diagnostics = Array.isArray(onboarding.connectivity?.diagnostics)? onboarding.connectivity.diagnostics@@ -546,6 +592,27 @@ export function buildInviteOnboardingTextDocument(onboarding.connectivity?.guidance ?? "Ensure Paperclip is reachable from your OpenClaw runtime.",);+ const connectionCandidates = Array.isArray(onboarding.connectivity?.connectionCandidates)+ ? onboarding.connectivity.connectionCandidates.filter((entry): entry is string => Boolean(entry))+ : [];++ if (connectionCandidates.length > 0) {+ lines.push("", "## Suggested Paperclip base URLs to try");+ for (const candidate of connectionCandidates) {+ lines.push(`- ${candidate}`);+ }+ lines.push(+ "",+ "Test each candidate with:",+ "- GET <candidate>/api/health",+ "",+ "If none are reachable: ask your human operator for a reachable hostname/address and help them update network configuration.",+ "For authenticated/private mode, they may need:",+ "- pnpm paperclipai allowed-hostname <host>",+ "- then restart Paperclip and retry onboarding.",+ );+ }+if (diagnostics.length > 0) {lines.push("", "## Connectivity diagnostics");for (const diag of diagnostics) {