fix(onboard): clarify skill credential prompts

vyctorbrzezowski · vyctorbrzezowski · commit 26172c8c7863 · 2026-04-29T14:54:36.000-03:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -25,6 +25,7 @@ Docs: https://docs.openclaw.ai
 
 - Models/UI: hide unauthenticated providers from the default Web chat, `/models`, and model setup pickers while keeping explicit full-catalog browse paths through `view: "all"`, `/models <provider> all`, and `models list --all`. Fixes #74423. Thanks @guarismo and @SymbolStar.
 - Exec: reject invalid per-call `host` values instead of silently falling back to the default target, so hostname-like values fail before commands run. Fixes #74426. Thanks @scr00ge-00 and @vyctorbrzezowski.
+- CLI/onboarding: separate skill API credential prompts from local dependency installs so keyless local skills such as OpenAI Whisper are not confused with API-backed skill setup. Fixes #74382. Thanks @sanjarcode.
 - Google/Gemini: send non-empty placeholder content when a Gemini run is triggered with empty or filtered user content, avoiding `contents is not specified` API errors. Thanks @CaoYuhaoCarl.
 - Heartbeat: preserve non-task `HEARTBEAT.md` context around `tasks:` blocks and apply `agents.defaults.heartbeat` to all agents unless per-agent heartbeat entries restrict scope. Thanks @Sekhar03.
 - Markdown: preserve paragraph breaks inside loose list items in shared outbound formatting while keeping tight list spacing stable. Thanks @Lucenx9.
diff --git a/src/commands/onboard-skills.test.ts b/src/commands/onboard-skills.test.ts
@@ -31,9 +31,11 @@ import { setupSkills } from "./onboard-skills.js";
 function createBundledSkill(params: {
   name: string;
   description: string;
-  bins: string[];
+  bins?: string[];
+  env?: string[];
+  primaryEnv?: string;
   os?: string[];
-  installLabel: string;
+  installLabel?: string;
 }): {
   name: string;
   description: string;
@@ -42,6 +44,7 @@ function createBundledSkill(params: {
   filePath: string;
   baseDir: string;
   skillKey: string;
+  primaryEnv?: string;
   always: boolean;
   disabled: boolean;
   blockedByAllowlist: boolean;
@@ -57,6 +60,8 @@ function createBundledSkill(params: {
   configChecks: [];
   install: Array<{ id: string; kind: string; label: string; bins: string[] }>;
 } {
+  const bins = params.bins ?? [];
+  const env = params.env ?? [];
   return {
     name: params.name,
     description: params.description,
@@ -65,14 +70,17 @@ function createBundledSkill(params: {
     filePath: `/tmp/skills/${params.name}`,
     baseDir: `/tmp/skills/${params.name}`,
     skillKey: params.name,
+    primaryEnv: params.primaryEnv,
     always: false,
     disabled: false,
     blockedByAllowlist: false,
     eligible: false,
-    requirements: { bins: params.bins, anyBins: [], env: [], config: [], os: params.os ?? [] },
-    missing: { bins: params.bins, anyBins: [], env: [], config: [], os: params.os ?? [] },
+    requirements: { bins, anyBins: [], env, config: [], os: params.os ?? [] },
+    missing: { bins, anyBins: [], env, config: [], os: params.os ?? [] },
     configChecks: [],
-    install: [{ id: "brew", kind: "brew", label: params.installLabel, bins: params.bins }],
+    install: params.installLabel
+      ? [{ id: "brew", kind: "brew", label: params.installLabel, bins }]
+      : [],
   };
 }
 
@@ -186,4 +194,57 @@ describe("setupSkills", () => {
     const brewNote = notes.find((n) => n.title === "Homebrew recommended");
     expect(brewNote).toBeDefined();
   });
+
+  it("separates local dependency installs from API credential prompts", async () => {
+    mockMissingBrewStatus([
+      createBundledSkill({
+        name: "openai-whisper",
+        description: "Local speech-to-text with the Whisper CLI (no API key).",
+        bins: ["whisper"],
+        installLabel: "Install OpenAI Whisper (brew)",
+      }),
+      createBundledSkill({
+        name: "openai-whisper-api",
+        description: "Transcribe audio via OpenAI Audio Transcriptions API (Whisper).",
+        env: ["OPENAI_API_KEY"],
+        primaryEnv: "OPENAI_API_KEY",
+      }),
+      createBundledSkill({
+        name: "sag",
+        description: "ElevenLabs text-to-speech with mac-style say UX.",
+        env: ["ELEVENLABS_API_KEY"],
+        primaryEnv: "ELEVENLABS_API_KEY",
+      }),
+    ]);
+
+    const { prompter, notes } = createPrompter({ multiselect: ["__skip__"] });
+    await setupSkills({} as OpenClawConfig, "/tmp/ws", runtime, prompter);
+
+    const installCall = vi.mocked(prompter.multiselect).mock.calls[0]?.[0];
+    expect(installCall?.message).toBe("Install missing skill dependencies");
+    expect(installCall?.options).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          label: "🧩 openai-whisper",
+          hint: expect.stringContaining("no API key"),
+        }),
+      ]),
+    );
+
+    const credentialNote = notes.find((n) => n.title === "Skill API credentials");
+    expect(credentialNote?.message).toContain(
+      "These prompts configure API-backed skills separately from local dependency installs.",
+    );
+    expect(credentialNote?.message).toContain("openai-whisper-api: OPENAI_API_KEY");
+    expect(credentialNote?.message).toContain("sag: ELEVENLABS_API_KEY");
+
+    expect(vi.mocked(prompter.confirm)).toHaveBeenCalledWith({
+      message: "Set OPENAI_API_KEY for openai-whisper-api?",
+      initialValue: false,
+    });
+    expect(vi.mocked(prompter.confirm)).toHaveBeenCalledWith({
+      message: "Set ELEVENLABS_API_KEY for sag?",
+      initialValue: false,
+    });
+  });
 });
diff --git a/src/commands/onboard-skills.ts b/src/commands/onboard-skills.ts
@@ -30,6 +30,10 @@ function formatSkillHint(skill: {
   return combined.length > maxLen ? `${combined.slice(0, maxLen - 1)}…` : combined;
 }
 
+function formatCredentialSkillLine(skill: { name: string; primaryEnv: string }): string {
+  return `- ${skill.name}: ${skill.primaryEnv}`;
+}
+
 function upsertSkillEntry(
   cfg: OpenClawConfig,
   skillKey: string,
@@ -198,10 +202,21 @@ export async function setupSkills(
     }
   }
 
-  for (const skill of missing) {
-    if (!skill.primaryEnv || skill.missing.env.length === 0) {
-      continue;
-    }
+  type CredentialSkill = (typeof missing)[number] & { primaryEnv: string };
+  const credentialSkills = missing.filter(
+    (skill): skill is CredentialSkill => Boolean(skill.primaryEnv) && skill.missing.env.length > 0,
+  );
+  if (credentialSkills.length > 0) {
+    await prompter.note(
+      [
+        "These prompts configure API-backed skills separately from local dependency installs.",
+        ...credentialSkills.map(formatCredentialSkillLine),
+      ].join("\n"),
+      "Skill API credentials",
+    );
+  }
+
+  for (const skill of credentialSkills) {
     const wantsKey = await prompter.confirm({
       message: `Set ${skill.primaryEnv} for ${skill.name}?`,
       initialValue: false,
