From 5f3923fc30b2cb8a6c7b2f3f3deb35e6be760bc0 Mon Sep 17 00:00:00 2001
From: zhaohaha <406123980@qq.com>
Date: Mon, 13 Jul 2026 17:00:42 +0800
Subject: [PATCH] fix(openai-spring-boot-starter): make api-key optional for
 OpenAI-compatible providers

Some free OpenAI-compatible providers (e.g., opencode free models) do not require an API key. Remove the mandatory startup check so the auto-configuration can create the OpenAIChatModel without an api-key property.
---
 .../boot/openai/OpenAIAutoConfiguration.java  |  5 ----
 .../spring/boot/openai/OpenAIProperties.java  |  3 ++
 .../openai/OpenAIAutoConfigurationTest.java   | 29 ++++++++++++++-----
 3 files changed, 25 insertions(+), 12 deletions(-)

diff --git a/agentscope-extensions/agentscope-spring-boot-starters/agentscope-openai-spring-boot-starter/src/main/java/io/agentscope/spring/boot/openai/OpenAIAutoConfiguration.java b/agentscope-extensions/agentscope-spring-boot-starters/agentscope-openai-spring-boot-starter/src/main/java/io/agentscope/spring/boot/openai/OpenAIAutoConfiguration.java
index a79bf7128b..33e1b708dd 100644
--- a/agentscope-extensions/agentscope-spring-boot-starters/agentscope-openai-spring-boot-starter/src/main/java/io/agentscope/spring/boot/openai/OpenAIAutoConfiguration.java
+++ b/agentscope-extensions/agentscope-spring-boot-starters/agentscope-openai-spring-boot-starter/src/main/java/io/agentscope/spring/boot/openai/OpenAIAutoConfiguration.java
@@ -46,11 +46,6 @@ public OpenAIChatModel openAIChatModel(
             OpenAIProperties properties,
             ObjectProvider<OpenAIChatModelBuilderCustomizer> customizerObjectProvider) {
         String apiKey = trimToNull(properties.getApiKey());
-        if (apiKey == null) {
-            throw new IllegalStateException(
-                    "agentscope.openai.api-key must be configured when OpenAI provider is"
-                            + " selected");
-        }
 
         String modelName = trimToNull(properties.getModelName());
         if (modelName == null) {
diff --git a/agentscope-extensions/agentscope-spring-boot-starters/agentscope-openai-spring-boot-starter/src/main/java/io/agentscope/spring/boot/openai/OpenAIProperties.java b/agentscope-extensions/agentscope-spring-boot-starters/agentscope-openai-spring-boot-starter/src/main/java/io/agentscope/spring/boot/openai/OpenAIProperties.java
index 3fe7c08421..234d80f42d 100644
--- a/agentscope-extensions/agentscope-spring-boot-starters/agentscope-openai-spring-boot-starter/src/main/java/io/agentscope/spring/boot/openai/OpenAIProperties.java
+++ b/agentscope-extensions/agentscope-spring-boot-starters/agentscope-openai-spring-boot-starter/src/main/java/io/agentscope/spring/boot/openai/OpenAIProperties.java
@@ -45,6 +45,9 @@ public class OpenAIProperties {
 
     /**
      * OpenAI API key.
+     *
+     * <p>Optional: some OpenAI-compatible providers (for example free model endpoints)
+     * do not require an API key. Leave unset for those providers.
      */
     private String apiKey;
 
diff --git a/agentscope-extensions/agentscope-spring-boot-starters/agentscope-openai-spring-boot-starter/src/test/java/io/agentscope/spring/boot/openai/OpenAIAutoConfigurationTest.java b/agentscope-extensions/agentscope-spring-boot-starters/agentscope-openai-spring-boot-starter/src/test/java/io/agentscope/spring/boot/openai/OpenAIAutoConfigurationTest.java
index 1d36ebea63..7951cf6300 100644
--- a/agentscope-extensions/agentscope-spring-boot-starters/agentscope-openai-spring-boot-starter/src/test/java/io/agentscope/spring/boot/openai/OpenAIAutoConfigurationTest.java
+++ b/agentscope-extensions/agentscope-spring-boot-starters/agentscope-openai-spring-boot-starter/src/test/java/io/agentscope/spring/boot/openai/OpenAIAutoConfigurationTest.java
@@ -100,15 +100,30 @@ void shouldNotCreateOpenAIModelWhenDisabled() {
     }
 
     @Test
-    void shouldFailClearlyWhenApiKeyMissing() {
+    void shouldCreateOpenAIModelWhenApiKeyMissing() {
         contextRunner
-                .withPropertyValues("agentscope.model.provider=openai")
+                .withPropertyValues(
+                        "agentscope.model.provider=openai",
+                        "agentscope.openai.model-name=gpt-4.1-mini")
+                .run(
+                        context -> {
+                            assertThat(context).hasSingleBean(Model.class);
+                            assertThat(context).hasSingleBean(OpenAIChatModel.class);
+                        });
+    }
+
+    @Test
+    void shouldCreateOpenAIModelForApiKeyFreeProvider() {
+        contextRunner
+                .withPropertyValues(
+                        "agentscope.model.provider=openai",
+                        "agentscope.openai.model-name=opencode-free-model",
+                        "agentscope.openai.base-url=https://api.opencode.example.com/v1")
                 .run(
-                        context ->
-                                assertThat(context.getStartupFailure())
-                                        .isNotNull()
-                                        .hasMessageContaining(
-                                                "agentscope.openai.api-key must be configured"));
+                        context -> {
+                            assertThat(context).hasSingleBean(Model.class);
+                            assertThat(context).hasSingleBean(OpenAIChatModel.class);
+                        });
     }
 
     @Test