Skip to content

πŸ™Œ OpenHands: AI-Driven Development

feat: skip onboarding when a user-added Local backend has a usable LLM (#16931)

Vasco Schiavo1a7130ce9633
diff --git a/__tests__/components/onboarding/onboarding-host.test.tsx b/__tests__/components/onboarding/onboarding-host.test.tsx
index 42860c44b7..ffd6279582 100644
--- a/__tests__/components/onboarding/onboarding-host.test.tsx
+++ b/__tests__/components/onboarding/onboarding-host.test.tsx
@@ -208,14 +208,40 @@ describe("OnboardingHost", () => {
).toBeNull();
});
- it("shows the modal for a user-added Local backend that already has an LLM configured", async () => {
+ it("skips the modal for a user-added Local backend that already has an LLM configured", async () => {
+ seedUserAddedLocalBackend();
+ const getSettings = vi
+ .spyOn(SettingsService, "getSettings")
+ .mockResolvedValue({
+ ...DEFAULT_SETTINGS,
+ llm_api_key_set: true,
+ agent_settings: {
+ ...DEFAULT_SETTINGS.agent_settings,
+ llm: { model: "openai/zai-org/GLM-5.2", api_key: "**********" },
+ },
+ });
+
+ renderHost();
+
+ await waitFor(() => {
+ expect(getSettings).toHaveBeenCalledOnce();
+ expect(
+ screen.queryByTestId("onboarding-modal-stub"),
+ ).not.toBeInTheDocument();
+ });
+ expect(
+ window.localStorage.getItem(ONBOARDING_COMPLETED_STORAGE_KEY),
+ ).toBeNull();
+ });
+
+ it("still shows the modal for a user-added Local backend with a model but no API key", async () => {
seedUserAddedLocalBackend();
vi.spyOn(SettingsService, "getSettings").mockResolvedValue({
...DEFAULT_SETTINGS,
- llm_api_key_is_set: true,
+ llm_api_key_set: false,
agent_settings: {
...DEFAULT_SETTINGS.agent_settings,
- llm: { model: "openai/zai-org/GLM-5.2", api_key: "**********" },
+ llm: { model: "openai/zai-org/GLM-5.2", api_key: null },
},
});
diff --git a/src/components/features/onboarding/onboarding-host.tsx b/src/components/features/onboarding/onboarding-host.tsx
index 18d7658916..e986556326 100644
--- a/src/components/features/onboarding/onboarding-host.tsx
+++ b/src/components/features/onboarding/onboarding-host.tsx
@@ -1,5 +1,6 @@
import { useLocation } from "react-router";
import { useActiveBackend } from "#/contexts/active-backend-context";
+import { SEEDED_DEFAULT_BACKEND_ID } from "#/api/backend-registry/default-backend";
import { useSettings } from "#/hooks/query/use-settings";
import { isSubscriptionLlmConfig } from "#/constants/llm-subscription";
import type { Settings } from "#/types/settings";
@@ -10,7 +11,7 @@ import {
} from "./onboarding-preview";
import { useOnboardingCompletion } from "./use-onboarding-completion";
-function hasUsableCloudLlm(settings: Settings | undefined): boolean {
+function hasUsableLlm(settings: Settings | undefined): boolean {
const llm = settings?.agent_settings?.llm as
| Record<string, unknown>
| undefined;
@@ -27,10 +28,9 @@ function hasUsableCloudLlm(settings: Settings | undefined): boolean {
* isn't set yet). Closing or completing the flow marks it done so the
* modal won't re-appear on subsequent visits.
*
- * An already-authenticated Cloud backend may provide everything onboarding
- * would collect. Once the active Cloud backend reports a usable LLM, suppress
- * the redundant modal without writing a fake completion marker. Local backends
- * remain browser-onboarding-driven.
+ * A backend already reporting a usable LLM makes the modal redundant, so it is
+ * skipped β€” except the launcher-seeded default-local one, which may hold an
+ * LLM from an earlier user, leaving `openhands-onboarded` its first-run signal.
*
* With `?previewOnboardingStep=<0-3>` the modal opens on that slide for
* design review without persisting completion (works on any route when
@@ -43,12 +43,16 @@ export function OnboardingHost() {
const { isCompleted, markCompleted } = useOnboardingCompletion();
const { backend } = useActiveBackend();
const settings = useSettings();
- const isCloudBackend = backend.kind === "cloud";
+ // A backend the user pointed at explicitly (Cloud, or a Local server added
+ // via "Add Backend") is one whose configuration this browser did not create,
+ // so its reported LLM is trustworthy evidence that setup is already done.
+ const trustsBackendLlm =
+ backend.kind === "cloud" || backend.id !== SEEDED_DEFAULT_BACKEND_ID;
if (!isPreview) {
if (isCompleted) return null;
- if (isCloudBackend && settings.isLoading) return null;
- if (isCloudBackend && hasUsableCloudLlm(settings.data)) {
+ if (trustsBackendLlm && settings.isLoading) return null;
+ if (trustsBackendLlm && hasUsableLlm(settings.data)) {
return null;
}
}