From 8975c3c986b17ef02bec91d4bb99d58cd10d58f7 Mon Sep 17 00:00:00 2001
From: A <258483684+la14-1@users.noreply.github.com>
Date: Sat, 28 Feb 2026 13:11:56 -0800
Subject: [PATCH] fix(openclaw): add pre-launch tip for sequential channel
 setup (#2035)

Display a hint before launching `openclaw tui` warning users to set
up channels one at a time. Concurrent token pastes trigger a race
condition inside OpenClaw's TUI that causes setup to hang.

Adds an optional `preLaunchMsg` field to `AgentConfig` so any agent
can surface a user-visible tip just before its interactive session
starts. OpenClaw sets this to advise sequential channel onboarding.

Fixes #2030

Agent: issue-fixer

Co-authored-by: B <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 packages/cli/src/shared/agent-setup.ts | 2 ++
 packages/cli/src/shared/agents.ts      | 2 ++
 packages/cli/src/shared/orchestrate.ts | 6 ++++++
 3 files changed, 10 insertions(+)

diff --git a/packages/cli/src/shared/agent-setup.ts b/packages/cli/src/shared/agent-setup.ts
index d5dc406f..e25e496d 100644
--- a/packages/cli/src/shared/agent-setup.ts
+++ b/packages/cli/src/shared/agent-setup.ts
@@ -446,6 +446,8 @@ export function createAgents(runner: CloudRunner): Record<string, AgentConfig> {
       ],
       configure: (apiKey, modelId) => setupOpenclawConfig(runner, apiKey, modelId || "openrouter/auto"),
       preLaunch: () => startGateway(runner),
+      preLaunchMsg:
+        "Set up one channel at a time in the OpenClaw TUI. Wait for each channel to fully complete before pasting the next token — concurrent token pastes can cause setup to hang.",
       launchCmd: () =>
         "source ~/.spawnrc 2>/dev/null; export PATH=$HOME/.npm-global/bin:$HOME/.bun/bin:$HOME/.local/bin:$PATH; openclaw tui",
     },
diff --git a/packages/cli/src/shared/agents.ts b/packages/cli/src/shared/agents.ts
index 3d4f7914..045c6551 100644
--- a/packages/cli/src/shared/agents.ts
+++ b/packages/cli/src/shared/agents.ts
@@ -28,6 +28,8 @@ export interface AgentConfig {
   setup?: (envContent: string, apiKey: string, modelId?: string) => Promise<void>;
   /** Pre-launch hook (e.g., start gateway daemon). */
   preLaunch?: () => Promise<void>;
+  /** Optional tip or warning shown to the user just before the agent launches. */
+  preLaunchMsg?: string;
   /** Shell command to launch the agent interactively. */
   launchCmd: () => string;
   /** Cloud-init dependency tier. Defaults to "full" if unset. */
diff --git a/packages/cli/src/shared/orchestrate.ts b/packages/cli/src/shared/orchestrate.ts
index a579593b..d847e736 100644
--- a/packages/cli/src/shared/orchestrate.ts
+++ b/packages/cli/src/shared/orchestrate.ts
@@ -130,6 +130,12 @@ export async function runOrchestration(cloud: CloudOrchestrator, agent: AgentCon
     await agent.preLaunch();
   }
 
+  // 11b. Agent-specific pre-launch tip (e.g. channel setup ordering hint)
+  if (agent.preLaunchMsg) {
+    process.stderr.write("\n");
+    logInfo(`Tip: ${agent.preLaunchMsg}`);
+  }
+
   // 12. Launch interactive session
   logInfo(`${agent.name} is ready`);
   process.stderr.write("\n");