Fix kiloclaw kilocode provider discovery (#3048)

* fix(kiloclaw): always keep kilocode provider entry so bundled plugin loads

* fix(kiloclaw): drop as/non-null assertions in kilocode provider cleanup

* fix(kiloclaw): scrub stale plaintext apiKey from kilocode provider entry

Author: St0rmz1

.specs/kiloclaw-controller.md

@@ -335,14 +335,21 @@ patches to `openclaw.json`. The patches MUST include:
 2. Gateway auth token from `OPENCLAW_GATEWAY_TOKEN`.
 3. `allowInsecureAuth` when `AUTO_APPROVE_DEVICES=true`.
 4. Allowed origins from `OPENCLAW_ALLOWED_ORIGINS`.
-5. Stale kilocode provider migration (remove entries with old base
-   URLs).
-6. KiloCode API base URL override from `KILOCODE_API_BASE_URL`.
+5. KiloCode provider entry MUST always be present at
+   `models.providers.kilocode` with `baseUrl`
+   `https://api.kilo.ai/api/gateway/`, `api` `openai-completions`, and
+   `models` set to `[]`. The bundled openclaw kilocode plugin only loads
+   when this entry is present; without it, live model discovery never
+   runs and `kilo-auto/*` is unreachable. Stale entries written with
+   the old `/api/openrouter/` base URL MUST be dropped before the entry
+   is rebuilt.
+6. KiloCode API base URL override from `KILOCODE_API_BASE_URL` (local
+   dev tunnel).
 7. Org-scoped KiloCode provider configuration from
    `KILOCODE_ORGANIZATION_ID`: MUST set the
-   `X-KiloCode-OrganizationId` header and MUST set the provider's
-   `models` array to `[]` so OpenClaw uses live gateway model discovery
-   rather than a stale static catalog.
+   `X-KiloCode-OrganizationId` header on the kilocode provider entry.
+   When `KILOCODE_ORGANIZATION_ID` is unset, the controller MUST
+   remove any stale `X-KiloCode-OrganizationId` header from the entry.
 8. Default model from `KILOCODE_DEFAULT_MODEL`.
 9. Agent default user timezone from `KILOCLAW_USER_TIMEZONE`.
 10. Remove `agents.defaults.models` allowlist (KiloClaw users see all

services/kiloclaw/controller/src/config-writer.test.ts

@@ -82,7 +82,7 @@ function minimalEnv(): Record<string, string | undefined> {
 }
 
 describe('generateBaseConfig', () => {
-  it('generates config with gateway and exec defaults, no kilocode provider entry', () => {
+  it('generates config with gateway, exec defaults, and a kilocode provider entry that triggers live discovery', () => {
     const { deps } = fakeDeps();
     const config = generateBaseConfig(minimalEnv(), '/tmp/openclaw.json', deps);
 
@@ -93,8 +93,11 @@ describe('generateBaseConfig', () => {
     expect(config.gateway.auth.token).toBe('test-gw-token');
     expect(config.gateway.controlUi.allowInsecureAuth).toBe(true);
 
-    // No kilocode provider entry in production — built-in provider takes over
-    expect(config.models).toBeUndefined();
+    // The bundled kilocode plugin only loads when this entry is present.
+    // Empty `models` lets live gateway discovery own the catalog.
+    expect(config.models.providers.kilocode.baseUrl).toBe('https://api.kilo.ai/api/gateway/');
+    expect(config.models.providers.kilocode.api).toBe('openai-completions');
+    expect(config.models.providers.kilocode.models).toEqual([]);
 
     // No default model override when env var not set, and no memorySearch
     // schema introduced when the feature is off and absent from existing config.
@@ -311,7 +314,7 @@ describe('generateBaseConfig', () => {
     expect(config.gateway.port).toBe(3001);
   });
 
-  it('removes stale kilocode provider with /api/openrouter/ baseUrl', () => {
+  it('removes stale kilocode openrouter entry and rebuilds it pointed at the production gateway', () => {
     const existing = JSON.stringify({
       models: {
         providers: {
@@ -327,16 +330,70 @@ describe('generateBaseConfig', () => {
     const { deps } = fakeDeps(existing);
     const config = generateBaseConfig(minimalEnv(), '/tmp/openclaw.json', deps);
 
-    // Stale provider deleted, models object cleaned up
-    expect(config.models).toBeUndefined();
+    // Stale entry replaced — old apiKey and models dropped, baseUrl pointed
+    // at the production gateway so the bundled plugin can load.
+    expect(config.models.providers.kilocode.baseUrl).toBe('https://api.kilo.ai/api/gateway/');
+    expect(config.models.providers.kilocode.api).toBe('openai-completions');
+    expect(config.models.providers.kilocode.models).toEqual([]);
+    expect(config.models.providers.kilocode.apiKey).toBeUndefined();
+  });
+
+  // Regression: an earlier migration deleted the kilocode provider entry on
+  // personal (non-org) instances, expecting the bundled openclaw kilocode
+  // plugin to auto-activate from KILOCODE_API_KEY alone. It does not — the
+  // plugin only loads when an explicit provider entry is present, so without
+  // it `kilo-auto/balanced` and the rest of the dynamic catalog were never
+  // discovered and the agent failed with "Unknown model".
+  it('keeps kilocode provider entry on personal instances (no KILOCODE_ORGANIZATION_ID) so the bundled plugin loads', () => {
+    const { deps } = fakeDeps();
+    const env = {
+      ...minimalEnv(),
+      KILOCODE_DEFAULT_MODEL: 'kilocode/kilo-auto/balanced',
+    };
+    const config = generateBaseConfig(env, '/tmp/openclaw.json', deps);
+
+    expect(config.models.providers.kilocode.baseUrl).toBe('https://api.kilo.ai/api/gateway/');
+    expect(config.models.providers.kilocode.api).toBe('openai-completions');
+    expect(config.models.providers.kilocode.models).toEqual([]);
+    expect(config.models.providers.kilocode.headers?.['X-KiloCode-OrganizationId']).toBeUndefined();
+    expect(config.agents.defaults.model.primary).toBe('kilocode/kilo-auto/balanced');
+  });
+
+  it('preserves kilocode provider with production /api/gateway/ baseUrl and clears stale models', () => {
+    const existing = JSON.stringify({
+      models: {
+        providers: {
+          kilocode: {
+            baseUrl: 'https://api.kilo.ai/api/gateway/',
+            api: 'openai-completions',
+            models: [{ id: 'kilo/auto', name: 'Kilo Auto' }],
+          },
+        },
+      },
+    });
+    const { deps } = fakeDeps(existing);
+    const config = generateBaseConfig(minimalEnv(), '/tmp/openclaw.json', deps);
+
+    // Entry preserved (so the plugin loads), stale onboard-written models
+    // cleared so live discovery owns the catalog.
+    expect(config.models.providers.kilocode.baseUrl).toBe('https://api.kilo.ai/api/gateway/');
+    expect(config.models.providers.kilocode.api).toBe('openai-completions');
+    expect(config.models.providers.kilocode.models).toEqual([]);
   });
 
-  it('removes stale kilocode provider with production /api/gateway/ baseUrl', () => {
+  // Auth must come from `KILOCODE_API_KEY` env, never from a literal `apiKey`
+  // field on disk. The previous deletion-based migration was incidentally
+  // scrubbing the field; this test pins that the new normalization keeps that
+  // scrub so a stale plaintext credential from a legacy onboard run cannot
+  // survive across boots.
+  it('scrubs a stale plaintext apiKey from the kilocode provider entry', () => {
     const existing = JSON.stringify({
       models: {
         providers: {
           kilocode: {
             baseUrl: 'https://api.kilo.ai/api/gateway/',
+            api: 'openai-completions',
+            apiKey: 'sk-stale-plaintext',
             models: [],
           },
         },
@@ -345,7 +402,8 @@ describe('generateBaseConfig', () => {
     const { deps } = fakeDeps(existing);
     const config = generateBaseConfig(minimalEnv(), '/tmp/openclaw.json', deps);
 
-    expect(config.models).toBeUndefined();
+    expect(config.models.providers.kilocode.apiKey).toBeUndefined();
+    expect(config.models.providers.kilocode.baseUrl).toBe('https://api.kilo.ai/api/gateway/');
   });
 
   it('keeps gateway provider for org-scoped instances but clears static models', () => {
@@ -396,7 +454,7 @@ describe('generateBaseConfig', () => {
     expect(config.models.providers.kilocode.baseUrl).toBe('https://api.kilo.ai/api/gateway/');
   });
 
-  it('preserves non-kilocode providers when removing stale kilocode entry', () => {
+  it('preserves non-kilocode providers when rebuilding stale kilocode openrouter entry', () => {
     const existing = JSON.stringify({
       models: {
         providers: {
@@ -414,9 +472,9 @@ describe('generateBaseConfig', () => {
     const { deps } = fakeDeps(existing);
     const config = generateBaseConfig(minimalEnv(), '/tmp/openclaw.json', deps);
 
-    // kilocode removed, openai preserved
-    expect(config.models.providers.kilocode).toBeUndefined();
+    // openai preserved, kilocode rebuilt with production gateway URL
     expect(config.models.providers.openai.baseUrl).toBe('https://api.openai.com/v1');
+    expect(config.models.providers.kilocode.baseUrl).toBe('https://api.kilo.ai/api/gateway/');
   });
 
   it('creates kilocode provider with baseUrl and models: [] when KILOCODE_API_BASE_URL is set', () => {
@@ -428,7 +486,7 @@ describe('generateBaseConfig', () => {
     expect(config.models.providers.kilocode.models).toEqual([]);
   });
 
-  it('preserves existing models array when overriding baseUrl', () => {
+  it('clears stale models when overriding baseUrl, since live discovery owns the catalog', () => {
     const existing = JSON.stringify({
       models: {
         providers: {
@@ -443,9 +501,10 @@ describe('generateBaseConfig', () => {
     const env = { ...minimalEnv(), KILOCODE_API_BASE_URL: 'https://new-tunnel.example.com/' };
     const config = generateBaseConfig(env, '/tmp/openclaw.json', deps);
 
-    // baseUrl updated, existing models preserved
+    // baseUrl updated, stale onboard-written models cleared so live
+    // discovery populates the catalog from the new endpoint.
     expect(config.models.providers.kilocode.baseUrl).toBe('https://new-tunnel.example.com/');
-    expect(config.models.providers.kilocode.models).toEqual([{ id: 'kept/model', name: 'Kept' }]);
+    expect(config.models.providers.kilocode.models).toEqual([]);
   });
 
   it('sets X-KiloCode-OrganizationId header when KILOCODE_ORGANIZATION_ID is set', () => {
@@ -465,8 +524,10 @@ describe('generateBaseConfig', () => {
     const { deps } = fakeDeps();
     const config = generateBaseConfig(minimalEnv(), '/tmp/openclaw.json', deps);
 
-    // No kilocode provider entry created when neither baseUrl nor orgId is set
-    expect(config.models).toBeUndefined();
+    // Personal instance: kilocode entry still present (the bundled plugin
+    // requires it to load), but no org header attached.
+    expect(config.models.providers.kilocode.baseUrl).toBe('https://api.kilo.ai/api/gateway/');
+    expect(config.models.providers.kilocode.headers?.['X-KiloCode-OrganizationId']).toBeUndefined();
   });
 
   it('preserves existing kilocode baseUrl and headers when adding org header', () => {
@@ -517,7 +578,8 @@ describe('generateBaseConfig', () => {
     // Other headers and config preserved
     expect(config.models.providers.kilocode.headers['X-Custom']).toBe('preserved');
     expect(config.models.providers.kilocode.baseUrl).toBe('https://tunnel.example.com/');
-    expect(config.models.providers.kilocode.models).toEqual([{ id: 'kept/model', name: 'Kept' }]);
+    // models cleared so live discovery from the (preserved) baseUrl owns the catalog
+    expect(config.models.providers.kilocode.models).toEqual([]);
   });
 
   it('removes agents.defaults.models allowlist left by openclaw onboard', () => {

services/kiloclaw/controller/src/config-writer.ts

@@ -226,69 +226,63 @@ export function generateBaseConfig(
     );
   }
 
-  // Migration: remove stale manually-managed kilocode provider config.
-  // OpenClaw 2026.2.24+ has a built-in kilocode provider that activates when
-  // KILOCODE_API_KEY is in the environment. Stale config entries with the old
-  // /api/openrouter/ URL or the production /api/gateway/ URL conflict with it.
-  // For the production /api/gateway/ URL, skip removal when KILOCODE_ORGANIZATION_ID
-  // is set: org-scoped instances need an explicit provider entry (with the production
-  // baseUrl) to carry the org header. Its model list is cleared below so live gateway
-  // discovery still controls the catalog. The /api/openrouter/ cleanup always runs
-  // since that URL is unconditionally broken.
-  if (config.models?.providers?.kilocode) {
-    const staleBaseUrl: string = config.models.providers.kilocode.baseUrl || '';
-    const isOpenrouterUrl = staleBaseUrl.includes('/api/openrouter/');
-    const isGatewayUrl = staleBaseUrl === 'https://api.kilo.ai/api/gateway/';
-    if (isOpenrouterUrl || (isGatewayUrl && !env.KILOCODE_ORGANIZATION_ID)) {
-      delete config.models.providers.kilocode;
-      console.log(`Removed stale kilocode provider config (baseUrl: ${staleBaseUrl})`);
-      if (Object.keys(config.models.providers).length === 0) {
-        delete config.models.providers;
-      }
-      if (Object.keys(config.models).length === 0) {
-        delete config.models;
-      }
-    }
-  }
+  // KiloCode provider entry. The bundled openclaw kilocode plugin only loads
+  // when an explicit `models.providers.kilocode` entry exists in the config —
+  // without it, the plugin's catalog hook never runs and live gateway model
+  // discovery never populates `kilo-auto/*` and the rest of the dynamic
+  // catalog. So we always include this entry (production baseUrl, empty
+  // `models` so live discovery owns the catalog).
+  //
+  // Cleanup: the old `/api/openrouter/` URL is unconditionally broken; if a
+  // stale entry pointing at it survives from a previous boot, drop it before
+  // we rebuild.
+  const existingProviders = config.models?.providers;
+  const existingBaseUrl: string = existingProviders?.kilocode?.baseUrl ?? '';
+  if (existingProviders && existingBaseUrl.includes('/api/openrouter/')) {
+    delete existingProviders.kilocode;
+    console.log(`Removed stale kilocode provider config (baseUrl: ${existingBaseUrl})`);
+  }
+
+  config.models = config.models ?? {};
+  config.models.providers = config.models.providers ?? {};
+  config.models.providers.kilocode = config.models.providers.kilocode ?? {};
+  config.models.providers.kilocode.baseUrl =
+    config.models.providers.kilocode.baseUrl ?? 'https://api.kilo.ai/api/gateway/';
+  config.models.providers.kilocode.api =
+    config.models.providers.kilocode.api ?? 'openai-completions';
+  // Empty array keeps the provider schema-valid while letting live gateway
+  // discovery populate the catalog. Stale model entries written by an older
+  // `openclaw onboard` are intentionally cleared here.
+  config.models.providers.kilocode.models = [];
+  // Auth must come from `KILOCODE_API_KEY` env (env-backed SecretRef in
+  // `auth-profiles.json` for new installs). A literal `apiKey` in
+  // `openclaw.json` is never the source of truth on kiloclaw, but the
+  // previous deletion-based migration was incidentally scrubbing the field.
+  // Preserve that scrub explicitly so any pre-existing plaintext key from a
+  // legacy onboard run does not linger on disk.
+  delete config.models.providers.kilocode.apiKey;
 
   // KiloCode provider base URL override (local dev only).
   // OpenClaw's native kilocode provider hardcodes https://api.kilo.ai/api/gateway/.
   // In local dev, Fly machines need to route through a Cloudflare tunnel, so we
   // override the base URL when KILOCODE_API_BASE_URL is set.
   if (env.KILOCODE_API_BASE_URL) {
-    config.models = config.models ?? {};
-    config.models.providers = config.models.providers ?? {};
-    config.models.providers.kilocode = config.models.providers.kilocode ?? {};
     config.models.providers.kilocode.baseUrl = env.KILOCODE_API_BASE_URL;
-    // Provider entries require a models array per OpenClaw's strict zod schema.
-    // Empty array is valid — the built-in kilocode provider fills in its catalog.
-    config.models.providers.kilocode.models = config.models.providers.kilocode.models ?? [];
     console.log(`Overriding kilocode base URL: ${env.KILOCODE_API_BASE_URL}`);
   }
 
   // Pass org scope to KiloCode provider as request header when available.
   // This is used by OpenClaw provider requests (not Kilo CLI).
   // Header name matches ORGANIZATION_ID_HEADER in src/lib/constants.ts.
   if (env.KILOCODE_ORGANIZATION_ID) {
-    config.models = config.models ?? {};
-    config.models.providers = config.models.providers ?? {};
-    config.models.providers.kilocode = config.models.providers.kilocode ?? {};
-    // Explicit provider entries require a baseUrl per OpenClaw's strict schema.
-    // When KILOCODE_API_BASE_URL already set the URL above, preserve it;
-    // otherwise default to the production gateway URL.
-    config.models.providers.kilocode.baseUrl =
-      config.models.providers.kilocode.baseUrl ?? 'https://api.kilo.ai/api/gateway/';
     config.models.providers.kilocode.headers = config.models.providers.kilocode.headers ?? {};
     config.models.providers.kilocode.headers['X-KiloCode-OrganizationId'] =
       env.KILOCODE_ORGANIZATION_ID;
-    // Empty array keeps the provider schema-valid while allowing OpenClaw to
-    // populate the full Kilo Gateway catalog through live model discovery.
-    config.models.providers.kilocode.models = [];
     console.log('Configured KiloCode organization header from KILOCODE_ORGANIZATION_ID');
   } else {
     // Remove stale org header from previous boots (e.g., instance was transferred
     // from org to personal, or org was deleted).
-    delete config.models?.providers?.kilocode?.headers?.['X-KiloCode-OrganizationId'];
+    delete config.models.providers.kilocode.headers?.['X-KiloCode-OrganizationId'];
   }
 
   // User-selected default model override.