Support OpenAI-compatible endpoint configuration with optional API key

rowandh · Autohand Evolve · rowandh · commit 70215f968cba · 2026-05-26T09:28:41.000+02:00
Allow endpoint-first setup for OpenAI-compatible providers, keep API keys optional when not required, and harden OpenAI-compatible response parsing to avoid runtime crashes on malformed 200 payloads.

Co-authored-by: Autohand Evolve &lt;code-noreply@autohand.ai&gt;
diff --git a/docs/config-reference.md b/docs/config-reference.md
@@ -221,19 +221,21 @@ OpenAI-compatible provider configuration for custom gateways/proxies that expose
 ```json
 {
   "openaicompatible": {
-    "apiKey": "your-provider-key",
     "baseUrl": "https://your-provider.example.com/v1",
-    "model": "gpt-4o-mini"
+    "model": "gpt-4o-mini",
+    "apiKey": "your-provider-key"
   }
 }
 ```
 
 | Field     | Type   | Required | Default                    | Description                                                        |
 | --------- | ------ | -------- | -------------------------- | ------------------------------------------------------------------ |
-| `apiKey`  | string | Yes      | -                          | API key from your OpenAI-compatible provider                       |
+| `apiKey`  | string | No       | -                          | API key for endpoints that require bearer auth                     |
 | `baseUrl` | string | Yes      | -                          | OpenAI-compatible endpoint base URL (for example `.../v1`)         |
 | `model`   | string | Yes      | -                          | Model name supported by your provider                              |
 
+When `apiKey` is omitted, requests are sent without an `Authorization` header.
+
 ### `mlx`
 
 MLX provider for Apple Silicon Macs (local inference).
diff --git a/src/config.ts b/src/config.ts
@@ -873,9 +873,18 @@ export function getProviderConfig(
     }
   } else if (chosen === "openaicompatible") {
     const { apiKey, model, baseUrl } = entry as ProviderSettings;
-    if (!apiKey || apiKey === "replace-me" || !model || !baseUrl) {
+    if (!model || !baseUrl) {
       return null;
     }
+
+    const sanitizedApiKey =
+      apiKey && apiKey !== "replace-me" ? apiKey : undefined;
+
+    return {
+      ...entry,
+      ...(sanitizedApiKey ? { apiKey: sanitizedApiKey } : {}),
+      baseUrl,
+    };
   } else if (
     chosen === "openrouter" ||
     chosen === "llmgateway" ||
diff --git a/src/core/agent/ProviderConfigManager.ts b/src/core/agent/ProviderConfigManager.ts
@@ -912,19 +912,6 @@ export class ProviderConfigManager {
         ),
       );
 
-      const apiKey =
-        (await showPassword({
-          title: t("providers.config.enterApiKey", {
-            provider: t("providers.openaicompatible"),
-          }),
-          placeholder: t("ui.apiKeyPlaceholder"),
-        })) ?? "";
-
-      if (!apiKey) {
-        console.log(chalk.gray("\n" + t("providers.config.cancelled")));
-        return;
-      }
-
       const baseUrlInput = await showInput({
         title: t("providers.config.changeBaseUrl"),
         defaultValue:
@@ -938,6 +925,26 @@ export class ProviderConfigManager {
         return;
       }
 
+      const apiKeyInput = await showPassword({
+        title: t("providers.config.enterApiKeyOptional", {
+          provider: t("providers.openaicompatible"),
+        }),
+        placeholder: t("ui.apiKeyPlaceholder"),
+        validate: (val: string) => {
+          const trimmed = val?.trim();
+          if (!trimmed) return true;
+          if (trimmed.length < 10) return t("providers.config.apiKeyTooShort");
+          return true;
+        },
+      });
+
+      if (apiKeyInput === undefined || apiKeyInput === null) {
+        console.log(chalk.gray("\n" + t("providers.config.cancelled")));
+        return;
+      }
+
+      const apiKey = apiKeyInput.trim();
+
       const model = await showInput({
         title: t("providers.config.enterModelId"),
         defaultValue:
@@ -955,10 +962,10 @@ export class ProviderConfigManager {
         sanitizedModel,
       );
       this.runtime.config.openaicompatible = {
-        apiKey,
         baseUrl,
         model: sanitizedModel,
         contextWindow,
+        ...(apiKey ? { apiKey } : {}),
       };
 
       this.runtime.config.provider = "openaicompatible";
@@ -2361,19 +2368,26 @@ export class ProviderConfigManager {
         title: t("providers.config.enterApiKey", { provider: providerName }),
         placeholder: t("ui.apiKeyPlaceholder"),
         validate: (val: string) => {
-          if (!val?.trim()) return t("providers.config.apiKeyRequired");
-          if (val.length < 10) return t("providers.config.apiKeyTooShort");
+          const trimmed = val?.trim();
+          if (!trimmed) {
+            return provider === "openaicompatible"
+              ? true
+              : t("providers.config.apiKeyRequired");
+          }
+          if (trimmed.length < 10) return t("providers.config.apiKeyTooShort");
           return true;
         },
       });
 
-      if (!apiKey) {
+      if (apiKey === undefined || apiKey === null) {
         console.log(
           chalk.gray("\n" + t("providers.config.settingsChangeCancelled")),
         );
         return;
       }
 
+      const trimmedApiKey = apiKey.trim();
+
       if (provider === "openaicompatible") {
         const baseUrlInput = await showInput({
           title: t("providers.config.changeBaseUrl"),
@@ -2403,26 +2417,32 @@ export class ProviderConfigManager {
         newBaseUrl = baseUrlInput.trim().replace(/\/+$/, "");
       }
 
-      // Validate the API key
-      console.log(chalk.gray("\n" + t("providers.config.validatingApiKey")));
-      const validationResult = await this.validateApiKey(
-        provider,
-        apiKey.trim(),
-        provider === "openaicompatible"
-          ? newBaseUrl
-          : provider === "openai"
-            ? (this.runtime.config.openai?.baseUrl ?? currentSettings?.baseUrl)
-            : undefined,
-      );
+      if (provider === "openaicompatible" && !trimmedApiKey) {
+        newApiKey = "";
+      } else {
+        // Validate the API key
+        console.log(chalk.gray("\n" + t("providers.config.validatingApiKey")));
+        const validationResult = await this.validateApiKey(
+          provider,
+          trimmedApiKey,
+          provider === "openaicompatible"
+            ? newBaseUrl
+            : provider === "openai"
+              ? (this.runtime.config.openai?.baseUrl ?? currentSettings?.baseUrl)
+              : undefined,
+        );
 
-      if (!validationResult.valid) {
-        console.log(chalk.red(`\n✗ ${validationResult.error}`));
-        console.log(chalk.gray(validationResult.hint || ""));
-        return;
-      }
+        if (!validationResult.valid) {
+          console.log(chalk.red(`\n✗ ${validationResult.error}`));
+          console.log(chalk.gray(validationResult.hint || ""));
+          return;
+        }
 
-      console.log(chalk.green("✓ " + t("providers.config.apiKeyValid") + "\n"));
-      newApiKey = apiKey.trim();
+        console.log(
+          chalk.green("✓ " + t("providers.config.apiKeyValid") + "\n"),
+        );
+        newApiKey = trimmedApiKey;
+      }
     }
 
     // Handle model change
@@ -2665,10 +2685,10 @@ export class ProviderConfigManager {
         };
       } else if (provider === "openaicompatible") {
         this.runtime.config.openaicompatible = {
-          apiKey: newApiKey,
           baseUrl,
           model: newModel,
           contextWindow,
+          ...(newApiKey ? { apiKey: newApiKey } : {}),
         };
       } else if (provider === "openrouter") {
         this.runtime.config.openrouter = {
diff --git a/src/i18n/locales/en.json b/src/i18n/locales/en.json
@@ -739,6 +739,7 @@
       "reasoningEffortLabel": "Reasoning effort: {{level}}",
       "enterModelId": "Enter the model ID",
       "enterApiKey": "Enter your {{provider}} API key",
+      "enterApiKeyOptional": "Enter your {{provider}} API key (leave blank if not required)",
       "apiKeyUrl": "Get your API key at: {{url}}",
       "modelChangeCancelled": "Model change cancelled.",
       "modelUnchanged": "Model unchanged.",
diff --git a/src/onboarding/setupWizard.ts b/src/onboarding/setupWizard.ts
@@ -217,13 +217,15 @@ export class SetupWizard {
             await this.validateApiKeyDuringSetup();
           }
         } else if (provider === 'openaicompatible') {
-          const apiKey = await this.promptApiKey(provider);
-          if (apiKey === null) return this.cancelled();
-
           const baseUrlConfigured = await this.promptOpenAICompatibleBaseUrl();
           if (!baseUrlConfigured) return this.cancelled();
 
-          await this.validateApiKeyDuringSetup();
+          const apiKey = await this.promptApiKey(provider, { required: false });
+          if (apiKey === null) return this.cancelled();
+
+          if (apiKey) {
+            await this.validateApiKeyDuringSetup();
+          }
         } else if (this.requiresApiKey(provider)) {
           const apiKey = await this.promptApiKey(provider);
           if (apiKey === null) return this.cancelled();
@@ -444,8 +446,12 @@ export class SetupWizard {
   /**
    * Prompt for API key (cloud providers)
    */
-  private async promptApiKey(provider: ProviderName): Promise<string | null> {
+  private async promptApiKey(
+    provider: ProviderName,
+    options?: { required?: boolean },
+  ): Promise<string | null> {
     this.state.currentStep = 'apiKey';
+    const required = options?.required !== false;
 
     // Check for existing key
     const existingKey = this.getExistingApiKey(provider);
@@ -468,18 +474,22 @@ export class SetupWizard {
       title: t('providers.config.enterApiKey', { provider: this.getProviderDisplayName(provider) }),
       placeholder: t('ui.apiKeyPlaceholder'),
       validate: (val: string) => {
-        if (!val?.trim()) return t('providers.config.apiKeyRequired');
-        if (val.length < 10) return t('providers.config.apiKeyTooShort');
+        const trimmed = val?.trim();
+        if (!trimmed) {
+          return required ? t('providers.config.apiKeyRequired') : true;
+        }
+        if (trimmed.length < 10) return t('providers.config.apiKeyTooShort');
         return true;
       }
     });
 
-    if (!apiKey) {
+    if (apiKey === undefined || apiKey === null) {
       return null;
     }
 
-    this.state.apiKey = apiKey.trim();
-    return this.state.apiKey;
+    const trimmedApiKey = apiKey.trim();
+    this.state.apiKey = trimmedApiKey || undefined;
+    return trimmedApiKey;
   }
 
   private async promptOpenAIAuthMode(): Promise<OpenAIAuthMode | null> {
@@ -1134,9 +1144,9 @@ export class SetupWizard {
         };
       } else if (this.state.provider === 'openaicompatible') {
         config.openaicompatible = {
-          apiKey: this.state.apiKey ?? '',
           model: this.state.model ?? this.getDefaultModel('openaicompatible'),
           baseUrl: this.state.providerBaseUrl ?? this.getDefaultBaseUrl('openaicompatible'),
+          ...(this.state.apiKey ? { apiKey: this.state.apiKey } : {}),
         };
       } else if (this.state.provider === 'vertexai' && this.state.vertexaiConfig) {
         config.vertexai = this.state.vertexaiConfig;
@@ -2114,7 +2124,7 @@ export class SetupWizard {
   // Helper methods
 
   private requiresApiKey(provider: ProviderName): boolean {
-    return provider === 'openrouter' || provider === 'openaicompatible' || provider === 'llmgateway' || provider === 'zai' || provider === 'vertexai' || provider === 'xai' || provider === 'cerebras' || provider === 'nvidia' || provider === 'deepseek';
+    return provider === 'openrouter' || provider === 'llmgateway' || provider === 'zai' || provider === 'vertexai' || provider === 'xai' || provider === 'cerebras' || provider === 'nvidia' || provider === 'deepseek';
   }
 
   private getProviderDisplayName(provider: ProviderName): string {
diff --git a/src/providers/OpenAIProvider.ts b/src/providers/OpenAIProvider.ts
@@ -310,8 +310,18 @@ export class OpenAIProvider implements LLMProvider {
         }
 
         const data = await response.json() as OpenAIChatResponse;
-        const message = data.choices[0].message;
-        const finishReason = data.choices[0].finish_reason;
+        const firstChoice = data.choices?.[0];
+        if (!firstChoice?.message) {
+            throw new ApiError(
+                'Received an invalid response from the OpenAI-compatible endpoint. Expected choices[0].message.',
+                'unknown',
+                response.status,
+                false,
+            );
+        }
+
+        const message = firstChoice.message;
+        const finishReason = firstChoice.finish_reason;
 
         // Parse tool calls if present
         let toolCalls: LLMToolCall[] | undefined;
@@ -647,6 +657,10 @@ export class OpenAIProvider implements LLMProvider {
             };
         }
 
+        if (!this.apiKey.trim()) {
+            return {};
+        }
+
         return {
             Authorization: `Bearer ${this.apiKey}`,
         };
diff --git a/src/types.ts b/src/types.ts
@@ -75,7 +75,7 @@ export interface OpenAISettings extends ProviderSettings {
 }
 
 export interface OpenAICompatibleSettings extends ProviderSettings {
-  apiKey: string;
+  apiKey?: string;
   baseUrl: string;
 }
 
diff --git a/tests/configProviders.spec.ts b/tests/configProviders.spec.ts
@@ -116,7 +116,7 @@ describe('getProviderConfig', () => {
     expect(result).toBeNull();
   });
 
-  it('returns openaicompatible settings only when api key, model, and base url are configured', () => {
+  it('returns openaicompatible settings when model and base url are configured', () => {
     const cfg = {
       provider: 'openaicompatible',
       openaicompatible: {
@@ -133,6 +133,22 @@ describe('getProviderConfig', () => {
     expect(result!.baseUrl).toBe('https://proxy.example.com/v1');
   });
 
+  it('returns openaicompatible settings when api key is omitted', () => {
+    const cfg = {
+      provider: 'openaicompatible',
+      openaicompatible: {
+        model: 'gpt-4o-mini',
+        baseUrl: 'https://proxy.example.com/v1'
+      }
+    } as unknown as AutohandConfig;
+
+    const result = getProviderConfig(cfg, 'openaicompatible' as any);
+    expect(result).not.toBeNull();
+    expect(result!.apiKey).toBeUndefined();
+    expect(result!.model).toBe('gpt-4o-mini');
+    expect(result!.baseUrl).toBe('https://proxy.example.com/v1');
+  });
+
   it('returns null for openaicompatible when base url is missing', () => {
     const cfg = {
       provider: 'openaicompatible',
diff --git a/tests/core/agent/ProviderConfigManager.openai.test.ts b/tests/core/agent/ProviderConfigManager.openai.test.ts
@@ -181,6 +181,23 @@ describe("ProviderConfigManager openai auth mode", () => {
     expect(mockSaveConfig).toHaveBeenCalledOnce();
   });
 
+  it("configures openaicompatible with endpoint and model when API key is omitted", async () => {
+    mockShowPassword.mockResolvedValueOnce("");
+    mockShowInput
+      .mockResolvedValueOnce("https://proxy.example.com/v1")
+      .mockResolvedValueOnce("gpt-4o-mini");
+
+    await (manager as any).configureOpenAICompatible();
+
+    expect(runtime.config.provider).toBe("openaicompatible");
+    expect(runtime.config.openaicompatible).toMatchObject({
+      baseUrl: "https://proxy.example.com/v1",
+      model: "gpt-4o-mini",
+    });
+    expect(runtime.config.openaicompatible?.apiKey).toBeUndefined();
+    expect(mockSaveConfig).toHaveBeenCalledOnce();
+  });
+
   it("validates openaicompatible api key against the newly entered base URL", async () => {
     runtime.config.provider = "openaicompatible";
     runtime.config.openaicompatible = {
diff --git a/tests/onboarding/setupWizard.test.ts b/tests/onboarding/setupWizard.test.ts
diff --git a/tests/providers/OpenAIProvider.test.ts b/tests/providers/OpenAIProvider.test.ts

Original file line number	Diff line number	Diff line change
`@@ -75,7 +75,7 @@ export interface OpenAISettings extends ProviderSettings {`
`75`	`75`	`}`
`76`	`76`
`77`	`77`	`export interface OpenAICompatibleSettings extends ProviderSettings {`
`78`		`- apiKey: string;`
	`78`	`+ apiKey?: string;`
`79`	`79`	`baseUrl: string;`
`80`	`80`	`}`
`81`	`81`