From cb86323e1941e18b48b15429f511ffa78b4bd6ec Mon Sep 17 00:00:00 2001
From: Aref Behboudi <behboodiaref@gmail.com>
Date: Mon, 6 Apr 2026 12:30:08 +0300
Subject: [PATCH 1/2] Multi-Agent Runtime

---
 .../java/ai/javaclaw/JavaClawApplication.java |   9 +-
 .../ai/javaclaw/api/AgentsController.java     |  54 +++++
 .../java/ai/javaclaw/chat/ChatChannel.java    |  30 ++-
 .../main/java/ai/javaclaw/chat/ChatHtml.java  |  23 +-
 .../chat/ws/ChatWebSocketHandler.java         |  51 ++++-
 .../onboarding/steps/S2_ProviderStep.java     |  79 ++++++-
 .../onboarding/steps/S3_CredentialsStep.java  | 101 +++++++--
 .../onboarding/steps/S4_AgentMdStep.java      |  56 ++++-
 app/src/main/resources/application.yaml       |  14 +-
 .../main/resources/templates/agents.html.peb  | 127 +++++++++++
 .../main/resources/templates/chat.html.peb    |  10 +-
 .../onboarding/steps/S2-provider.html.peb     |  10 +-
 .../onboarding/steps/S3-credentials.html.peb  |  12 +-
 .../ai/javaclaw/api/AgentsControllerTest.java |  44 ++++
 .../api/OnboardingControllerTest.java         |   6 +-
 .../ai/javaclaw/chat/ChatChannelTest.java     |  62 +++--
 .../chat/ws/ChatWebSocketHandlerTest.java     |  25 +-
 .../onboarding/steps/S4_AgentMdStepTest.java  |  87 +++++++
 app/workspace/app.mv.db                       | Bin 53248 -> 0 bytes
 base/build.gradle                             |   1 +
 .../ai/javaclaw/JavaClawConfiguration.java    |  80 +------
 .../main/java/ai/javaclaw/agent/Agent.java    |  12 +-
 .../java/ai/javaclaw/agent/DefaultAgent.java  |  58 ++++-
 .../FileSystemChatMemoryRepository.java       |  72 +++++-
 .../agents/AgentChatClientFactory.java        | 214 ++++++++++++++++++
 .../javaclaw/agents/AgentConversationId.java  |  34 +++
 .../ai/javaclaw/agents/AgentRegistry.java     | 134 +++++++++++
 .../agents/AgentWorkspaceResolver.java        |  91 ++++++++
 .../ai/javaclaw/agents/ConfiguredAgent.java   |  14 ++
 .../configuration/ConfigurationManager.java   |  24 ++
 .../onboarding/AgentOnboardingProvider.java   |   8 +
 .../ai/javaclaw/providers/AgentProvider.java  |   2 -
 .../FileSystemChatMemoryRepositoryTest.java   |  10 +-
 .../models/AgentChatClientFactoryTest.java    |  83 +++++++
 .../ai/javaclaw/models/ModelRegistryTest.java |  81 +++++++
 .../models/ModelWorkspaceResolverTest.java    |  42 ++++
 .../openai/OpenAIAgentOnboardingProvider.java |   5 +
 37 files changed, 1569 insertions(+), 196 deletions(-)
 create mode 100644 app/src/main/java/ai/javaclaw/api/AgentsController.java
 create mode 100644 app/src/main/resources/templates/agents.html.peb
 create mode 100644 app/src/test/java/ai/javaclaw/api/AgentsControllerTest.java
 create mode 100644 app/src/test/java/ai/javaclaw/onboarding/steps/S4_AgentMdStepTest.java
 delete mode 100644 app/workspace/app.mv.db
 create mode 100644 base/src/main/java/ai/javaclaw/agents/AgentChatClientFactory.java
 create mode 100644 base/src/main/java/ai/javaclaw/agents/AgentConversationId.java
 create mode 100644 base/src/main/java/ai/javaclaw/agents/AgentRegistry.java
 create mode 100644 base/src/main/java/ai/javaclaw/agents/AgentWorkspaceResolver.java
 create mode 100644 base/src/main/java/ai/javaclaw/agents/ConfiguredAgent.java
 create mode 100644 base/src/test/java/ai/javaclaw/models/AgentChatClientFactoryTest.java
 create mode 100644 base/src/test/java/ai/javaclaw/models/ModelRegistryTest.java
 create mode 100644 base/src/test/java/ai/javaclaw/models/ModelWorkspaceResolverTest.java

diff --git a/app/src/main/java/ai/javaclaw/JavaClawApplication.java b/app/src/main/java/ai/javaclaw/JavaClawApplication.java
index e396ce6..0f80245 100644
--- a/app/src/main/java/ai/javaclaw/JavaClawApplication.java
+++ b/app/src/main/java/ai/javaclaw/JavaClawApplication.java
@@ -5,6 +5,7 @@
 import org.slf4j.LoggerFactory;
 import org.springframework.boot.ApplicationArguments;
 import org.springframework.boot.ApplicationRunner;
+import org.springframework.boot.DefaultApplicationArguments;
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 import org.springframework.context.ConfigurableApplicationContext;
@@ -44,12 +45,16 @@ public void run(ApplicationArguments args) throws Exception {
 
         @EventListener
         public void on(ConfigurationChangedEvent configurationChangedEvent) {
-            ApplicationArguments args = applicationContext.getBean(ApplicationArguments.class);
+
             
             Thread thread = new Thread(() -> {
                 try {
+                    ApplicationArguments args = new DefaultApplicationArguments();
+                    if(applicationContext != null){
+                        args = applicationContext.getBean(ApplicationArguments.class);
+                        applicationContext.close();
+                    }
                     Thread.sleep(2000);
-                    applicationContext.close();
                     applicationContext = SpringApplication.run(JavaClawApplication.class, args.getSourceArgs());
                 } catch (InterruptedException e) {
                     Thread.currentThread().interrupt();
diff --git a/app/src/main/java/ai/javaclaw/api/AgentsController.java b/app/src/main/java/ai/javaclaw/api/AgentsController.java
new file mode 100644
index 0000000..b4dc403
--- /dev/null
+++ b/app/src/main/java/ai/javaclaw/api/AgentsController.java
@@ -0,0 +1,54 @@
+package ai.javaclaw.api;
+
+import ai.javaclaw.agents.AgentRegistry;
+import ai.javaclaw.agents.AgentWorkspaceResolver;
+import ai.javaclaw.agents.ConfiguredAgent;
+import org.springframework.stereotype.Controller;
+import org.springframework.ui.Model;
+import org.springframework.web.bind.annotation.GetMapping;
+
+import java.nio.file.Path;
+import java.util.List;
+
+@Controller
+public class AgentsController {
+
+    private final AgentRegistry agentRegistry;
+    private final AgentWorkspaceResolver agentWorkspaceResolver;
+
+    public AgentsController(AgentRegistry agentRegistry, AgentWorkspaceResolver agentWorkspaceResolver) {
+        this.agentRegistry = agentRegistry;
+        this.agentWorkspaceResolver = agentWorkspaceResolver;
+    }
+
+    @GetMapping("/agents")
+    public String agents(Model model) {
+        List<AgentView> agents = agentRegistry.getAgents().stream()
+                .map(configuredAgent -> new AgentView(
+                        configuredAgent.id(),
+                        configuredAgent.provider(),
+                        configuredAgent.model(),
+                        resolveWorkspace(configuredAgent),
+                        configuredAgent.id().equals(agentRegistry.getDefaultAgentId())
+                ))
+                .toList();
+
+        model.addAttribute("agents", agents);
+        model.addAttribute("hasAgents", !agents.isEmpty());
+        return "agents";
+    }
+
+    private String resolveWorkspace(ConfiguredAgent configuredAgent) {
+        Path workspacePath = agentWorkspaceResolver.resolveWorkspacePath(configuredAgent.workspacePath(), configuredAgent.id());
+        return workspacePath.toString();
+    }
+
+    public record AgentView(
+            String id,
+            String provider,
+            String model,
+            String workspace,
+            boolean isDefault
+    ) {
+    }
+}
diff --git a/app/src/main/java/ai/javaclaw/chat/ChatChannel.java b/app/src/main/java/ai/javaclaw/chat/ChatChannel.java
index 2050c31..2c2f539 100644
--- a/app/src/main/java/ai/javaclaw/chat/ChatChannel.java
+++ b/app/src/main/java/ai/javaclaw/chat/ChatChannel.java
@@ -1,6 +1,8 @@
 package ai.javaclaw.chat;
 
 import ai.javaclaw.agent.Agent;
+import ai.javaclaw.agents.AgentConversationId;
+import ai.javaclaw.agents.AgentRegistry;
 import ai.javaclaw.channels.Channel;
 import ai.javaclaw.channels.ChannelMessageReceivedEvent;
 import ai.javaclaw.channels.ChannelRegistry;
@@ -36,13 +38,15 @@ public class ChatChannel implements Channel {
     private static final Logger log = LoggerFactory.getLogger(ChatChannel.class);
 
     private final Agent agent;
+    private final AgentRegistry agentRegistry;
     private final ChannelRegistry channelRegistry;
     private final ChatMemoryRepository chatMemoryRepository;
     private final ConcurrentLinkedQueue<String> pendingMessages = new ConcurrentLinkedQueue<>();
     private final AtomicReference<WebSocketSession> wsSession = new AtomicReference<>();
 
-    public ChatChannel(Agent agent, ChannelRegistry channelRegistry, ChatMemoryRepository chatMemoryRepository) {
+    public ChatChannel(Agent agent, AgentRegistry agentRegistry, ChannelRegistry channelRegistry, ChatMemoryRepository chatMemoryRepository) {
         this.agent = agent;
+        this.agentRegistry = agentRegistry;
         this.channelRegistry = channelRegistry;
         this.chatMemoryRepository = chatMemoryRepository;
         channelRegistry.registerChannel(this);
@@ -96,10 +100,24 @@ public void sendMessage(String message) {
     /**
      * Returns all known conversation IDs, always with "web" first.
      */
-    public List<String> conversationIds() {
+    public List<String> agentIds() {
+        List<String> ids = agentRegistry.getAgents().stream().map(ai.javaclaw.agents.ConfiguredAgent::id).toList();
+        if (!ids.isEmpty()) {
+            return ids;
+        }
+        return List.of(agentRegistry.getDefaultAgentId());
+    }
+
+    public String defaultAgentId() {
+        return agentRegistry.getDefaultAgentId();
+    }
+
+    public List<String> conversationIds(String agentId) {
         List<String> result = new ArrayList<>();
         result.add("web");
         chatMemoryRepository.findConversationIds().stream()
+                .filter(id -> agentId.equals(AgentConversationId.agentId(id)))
+                .map(AgentConversationId::rawConversationId)
                 .filter(id -> !id.equals("web"))
                 .forEach(result::add);
         return result;
@@ -109,8 +127,8 @@ public List<String> conversationIds() {
      * Loads conversation history for the given conversationId as HTML bubbles.
      * Returns a single welcome bubble if no history exists yet.
      */
-    public List<String> loadHistoryAsHtml(String conversationId) {
-        List<Message> history = chatMemoryRepository.findByConversationId(conversationId);
+    public List<String> loadHistoryAsHtml(String agentId, String conversationId) {
+        List<Message> history = chatMemoryRepository.findByConversationId(AgentConversationId.scoped(agentId, conversationId));
         if (history.isEmpty()) {
             return List.of(ChatHtml.agentBubble("Hi! I'm your JavaClaw assistant. How can I help you today?"));
         }
@@ -125,9 +143,9 @@ public List<String> loadHistoryAsHtml(String conversationId) {
     /**
      * Handles a chat message from the web UI for the given conversationId.
      */
-    public String chat(String conversationId, String message) {
+    public String chat(String agentId, String conversationId, String message) {
         channelRegistry.publishMessageReceivedEvent(new ChannelMessageReceivedEvent(getName(), message));
-        return agent.respondTo(conversationId, message);
+        return agent.respondTo(agentId, conversationId, message);
     }
 
     private static String buildBackgroundMessageHtml(String text) {
diff --git a/app/src/main/java/ai/javaclaw/chat/ChatHtml.java b/app/src/main/java/ai/javaclaw/chat/ChatHtml.java
index c6416c8..b4a2121 100644
--- a/app/src/main/java/ai/javaclaw/chat/ChatHtml.java
+++ b/app/src/main/java/ai/javaclaw/chat/ChatHtml.java
@@ -34,11 +34,11 @@ public static String typingDots() {
                 </div>""";
     }
 
-    public static String chatInputArea(String conversationId) {
+    public static String chatInputArea(String agentId, String conversationId) {
         if ("web".equals(conversationId)) {
             return """
                     <form id="chat-form" ws-send hx-boost="false"
-                          hx-vals='js:{"type": "userMessage", "conversationId": document.getElementById("channel-select") ? document.getElementById("channel-select").value : "web"}'>
+                          hx-vals='js:{"type": "userMessage", "agentId": document.getElementById("agent-select") ? document.getElementById("agent-select").value : "%s", "conversationId": document.getElementById("channel-select") ? document.getElementById("channel-select").value : "web"}'>
                         <div class="field is-grouped" style="align-items: flex-end; margin: 0;">
                             <div class="control is-expanded">
                                 <textarea id="message-input" class="textarea" name="message" rows="1"
@@ -57,7 +57,7 @@ public static String chatInputArea(String conversationId) {
                                 </button>
                             </div>
                         </div>
-                    </form>""";
+                    </form>""".formatted(HtmlUtils.htmlEscape(agentId));
         }
         String label = HtmlUtils.htmlEscape(labelFor(conversationId));
         return """
@@ -70,7 +70,7 @@ public static String conversationSelector(List<String> ids, String selectedId) {
         sb.append("""
                 <select id="channel-select" class="select" name="conversationId" \
                 ws-send hx-trigger="change" \
-                hx-vals='{"type": "channelChanged"}'>""");
+                hx-vals='js:{"type": "channelChanged", "agentId": document.getElementById("agent-select") ? document.getElementById("agent-select").value : ""}'>""");
         for (String id : ids) {
             sb.append("<option value=\"").append(HtmlUtils.htmlEscape(id)).append("\"");
             if (id.equals(selectedId)) sb.append(" selected");
@@ -80,6 +80,21 @@ public static String conversationSelector(List<String> ids, String selectedId) {
         return sb.toString();
     }
 
+    public static String agentSelector(List<String> ids, String selectedId) {
+        StringBuilder sb = new StringBuilder();
+        sb.append("""
+                <select id="agent-select" class="select" name="agentId" \
+                ws-send hx-trigger="change" \
+                hx-vals='{"type": "agentChanged"}'>""");
+        for (String id : ids) {
+            sb.append("<option value=\"").append(HtmlUtils.htmlEscape(id)).append("\"");
+            if (id.equals(selectedId)) sb.append(" selected");
+            sb.append(">").append(HtmlUtils.htmlEscape(id)).append("</option>");
+        }
+        sb.append("</select>");
+        return sb.toString();
+    }
+
     private static String labelFor(String conversationId) {
         if ("web".equals(conversationId)) return "Web Chat";
         if (conversationId.startsWith("discord-")) return "Discord (" + conversationId.substring("discord-".length()) + ")";
diff --git a/app/src/main/java/ai/javaclaw/chat/ws/ChatWebSocketHandler.java b/app/src/main/java/ai/javaclaw/chat/ws/ChatWebSocketHandler.java
index 2132c7a..6acf689 100644
--- a/app/src/main/java/ai/javaclaw/chat/ws/ChatWebSocketHandler.java
+++ b/app/src/main/java/ai/javaclaw/chat/ws/ChatWebSocketHandler.java
@@ -35,13 +35,17 @@ public void afterConnectionEstablished(WebSocketSession session) throws Exceptio
         chatChannel.setWsSession(session);
         log.info("WebChat WebSocket connected: {}", session.getId());
 
-        List<String> ids = chatChannel.conversationIds();
-        String selectedId = ids.getFirst();
-
-        String conversationSelector = ChatHtml.conversationSelector(ids, selectedId);
-        String bubbles = String.join(System.lineSeparator(), chatChannel.loadHistoryAsHtml(selectedId));
-        String inputArea = ChatHtml.chatInputArea(selectedId);
+        List<String> agentIds = chatChannel.agentIds();
+        String selectedAgentId = agentIds.contains(chatChannel.defaultAgentId()) ? chatChannel.defaultAgentId() : agentIds.getFirst();
+        List<String> conversationIds = chatChannel.conversationIds(selectedAgentId);
+        String selectedConversationId = conversationIds.getFirst();
+
+        String agentSelector = ChatHtml.agentSelector(agentIds, selectedAgentId);
+        String conversationSelector = ChatHtml.conversationSelector(conversationIds, selectedConversationId);
+        String bubbles = String.join(System.lineSeparator(), chatChannel.loadHistoryAsHtml(selectedAgentId, selectedConversationId));
+        String inputArea = ChatHtml.chatInputArea(selectedAgentId, selectedConversationId);
         chatChannel.sendHtml(
+                Htmx.oobInnerHtml("agent-selector", agentSelector),
                 Htmx.oobInnerHtml("channel-selector", conversationSelector),
                 Htmx.oobInnerHtml("chat-messages", bubbles),
                 Htmx.oobInnerHtml("chat-input-area", inputArea));
@@ -61,29 +65,54 @@ protected void handleTextMessage(WebSocketSession session, TextMessage message)
 
         if ("channelChanged".equals(type)) {
             handleChannelChanged(payload);
+        } else if ("agentChanged".equals(type)) {
+            handleAgentChanged(payload);
         } else if ("userMessage".equals(type)) {
             handleUserMessage(payload);
         }
     }
 
+    private void handleAgentChanged(Map<String, Object> payload) throws Exception {
+        String agentId = (String) payload.get("agentId");
+        if (agentId == null || agentId.isBlank()) {
+            agentId = chatChannel.defaultAgentId();
+        }
+
+        List<String> conversationIds = chatChannel.conversationIds(agentId);
+        String selectedConversationId = conversationIds.getFirst();
+        String conversationSelector = ChatHtml.conversationSelector(conversationIds, selectedConversationId);
+        String bubbles = String.join(System.lineSeparator(), chatChannel.loadHistoryAsHtml(agentId, selectedConversationId));
+        String inputArea = ChatHtml.chatInputArea(agentId, selectedConversationId);
+        chatChannel.sendHtml(
+                Htmx.oobInnerHtml("channel-selector", conversationSelector),
+                Htmx.oobInnerHtml("chat-messages", bubbles),
+                Htmx.oobInnerHtml("chat-input-area", inputArea));
+    }
+
     private void handleChannelChanged(Map<String, Object> payload) throws Exception {
+        String agentId = (String) payload.get("agentId");
         String conversationId = (String) payload.get("conversationId");
         if (conversationId == null || conversationId.isBlank()) return;
+        if (agentId == null || agentId.isBlank()) {
+            agentId = chatChannel.defaultAgentId();
+        }
 
-        String bubbles = String.join(System.lineSeparator(), chatChannel.loadHistoryAsHtml(conversationId));
-        String inputArea = ChatHtml.chatInputArea(conversationId);
+        String bubbles = String.join(System.lineSeparator(), chatChannel.loadHistoryAsHtml(agentId, conversationId));
+        String inputArea = ChatHtml.chatInputArea(agentId, conversationId);
         chatChannel.sendHtml(
                 Htmx.oobInnerHtml("chat-messages", bubbles),
                 Htmx.oobInnerHtml("chat-input-area", inputArea));
     }
 
     private void handleUserMessage(Map<String, Object> payload) throws Exception {
+        String agentId = (String) payload.get("agentId");
         String conversationId = (String) payload.get("conversationId");
         String userMessage = (String) payload.get("message");
 
         if (userMessage == null || userMessage.isBlank()) return;
         userMessage = userMessage.trim();
         if (conversationId == null || conversationId.isBlank()) conversationId = "web";
+        if (agentId == null || agentId.isBlank()) agentId = chatChannel.defaultAgentId();
 
         // Echo user message + show typing indicator
         chatChannel.sendHtml(
@@ -92,12 +121,12 @@ private void handleUserMessage(Map<String, Object> payload) throws Exception {
 
         try {
             // Call agent (blocking — background tasks may push messages via ChatChannel during this)
-            String response = chatChannel.chat(conversationId, userMessage);
+            String response = chatChannel.chat(agentId, conversationId, userMessage);
             chatChannel.sendHtml(
                     Htmx.oobAppend("chat-messages", ChatHtml.agentBubble(response)),
                     Htmx.oobReplace("typing-indicator", ""));
         } catch (RuntimeException ex) {
-            log.warn("Chat request failed for conversation {}", conversationId, ex);
+            log.warn("Chat request failed for agent {} conversation {}", agentId, conversationId, ex);
             chatChannel.sendHtml(
                     Htmx.oobAppend("chat-messages", ChatHtml.agentBubble(genericUserFacingError(ex))),
                     Htmx.oobReplace("typing-indicator", ""));
@@ -116,4 +145,4 @@ private static String summarizeError(Throwable ex) {
 
         return message;
     }
-}
\ No newline at end of file
+}
diff --git a/app/src/main/java/ai/javaclaw/onboarding/steps/S2_ProviderStep.java b/app/src/main/java/ai/javaclaw/onboarding/steps/S2_ProviderStep.java
index 7f97889..5f453f0 100644
--- a/app/src/main/java/ai/javaclaw/onboarding/steps/S2_ProviderStep.java
+++ b/app/src/main/java/ai/javaclaw/onboarding/steps/S2_ProviderStep.java
@@ -1,6 +1,7 @@
 package ai.javaclaw.onboarding.steps;
 
 import ai.javaclaw.configuration.ConfigurationManager;
+import ai.javaclaw.agents.AgentWorkspaceResolver;
 import ai.javaclaw.onboarding.AgentOnboardingProvider;
 import ai.javaclaw.onboarding.AgentOnboardingProviders;
 import ai.javaclaw.onboarding.OnboardingProvider;
@@ -17,14 +18,17 @@
 public class S2_ProviderStep implements OnboardingProvider {
 
     static final String SESSION_PROVIDER = "onboarding.provider";
+    static final String SESSION_AGENT_ID = "onboarding.agentId";
     static final String SESSION_MODEL = "onboarding.model";
     static final String SESSION_API_KEY = "onboarding.apiKey";
 
     private final AgentOnboardingProviders agentOnboardingProviders;
+    private final AgentWorkspaceResolver agentWorkspaceResolver;
     private final Environment env;
 
-    public S2_ProviderStep(AgentOnboardingProviders agentOnboardingProviders, Environment env) {
+    public S2_ProviderStep(AgentOnboardingProviders agentOnboardingProviders, AgentWorkspaceResolver agentWorkspaceResolver, Environment env) {
         this.agentOnboardingProviders = agentOnboardingProviders;
+        this.agentWorkspaceResolver = agentWorkspaceResolver;
         this.env = env;
     }
 
@@ -40,15 +44,23 @@ public S2_ProviderStep(AgentOnboardingProviders agentOnboardingProviders, Enviro
     @Override
     public void prepareModel(Map<String, Object> session, Map<String, Object> model) {
         model.put("providers", agentOnboardingProviders.getAll());
-        model.put("selectedProvider", session.getOrDefault(SESSION_PROVIDER, env.getProperty("spring.ai.model.chat", "")));
+        model.put("selectedProvider", session.getOrDefault(SESSION_PROVIDER, existingProviderId()));
+        model.put("agentId", session.getOrDefault(SESSION_AGENT_ID, existingAgentId()));
     }
 
     @Override
     public String processStep(Map<String, String> formParams, Map<String, Object> session) {
         String providerId = formParams.get("provider");
+        String agentId = normalizeAgentId(formParams.get("agentId"));
         if (providerId == null || providerId.isBlank()) {
             return "Choose one of the supported providers to continue.";
         }
+        if (agentId == null || agentId.isBlank()) {
+            return "Enter a unique agent id to continue.";
+        }
+        if (!agentId.matches("[a-zA-Z0-9][a-zA-Z0-9_-]*")) {
+            return "Agent id may contain only letters, numbers, dashes, and underscores.";
+        }
         AgentOnboardingProvider agentOnboardingProvider = agentOnboardingProviders.getById(providerId);
         // Clear downstream session state when provider changes
         String currentProvider = (String) session.get(SESSION_PROVIDER);
@@ -57,20 +69,77 @@ public String processStep(Map<String, String> formParams, Map<String, Object> se
             session.remove(SESSION_API_KEY);
         }
         session.put(SESSION_PROVIDER, agentOnboardingProvider.getId());
+        session.put(SESSION_AGENT_ID, agentId);
         return null;
     }
 
     @Override
     public void saveConfiguration(Map<String, Object> session, ConfigurationManager configurationManager) throws IOException {
         String providerId = (String) session.get(SESSION_PROVIDER);
+        String agentId = normalizeAgentId((String) session.get(SESSION_AGENT_ID));
         String model = (String) session.get(SESSION_MODEL);
         String apiKey = (String) session.getOrDefault(SESSION_API_KEY, "");
 
         AgentOnboardingProvider agentOnboardingProvider = agentOnboardingProviders.getById(providerId);
         Map<String, Object> props = new LinkedHashMap<>();
-        agentOnboardingProvider.saveProperty(props, "chat.options.model", model);
-        agentOnboardingProvider.saveProperty(props, "api-key", apiKey);
-        props.put("spring.ai.model.chat", agentOnboardingProvider.getId().replace(".", "-"));
+        if (agentOnboardingProvider.usesRuntimeRegistry()) {
+            saveRuntimeAgent(props, agentOnboardingProvider, agentId, model, apiKey);
+            clearSpringAiProviderConfig(props);
+        } else {
+            clearRuntimeDefaultAgent(props);
+            agentOnboardingProvider.saveProperty(props, "chat.options.model", model);
+            agentOnboardingProvider.saveProperty(props, "api-key", apiKey);
+            props.put("spring.ai.model.chat", agentOnboardingProvider.getId().replace(".", "-"));
+        }
         configurationManager.updateProperties(props);
     }
+
+    private String existingProviderId() {
+        String runtimeProvider = env.getProperty(runtimeAgentKey(existingAgentId(), "provider"), "");
+        if (!runtimeProvider.isBlank()) {
+            return runtimeProvider;
+        }
+        return env.getProperty("spring.ai.model.chat", "");
+    }
+
+    private String existingAgentId() {
+        return env.getProperty("agent.agents.default", "default");
+    }
+
+    private void saveRuntimeAgent(Map<String, Object> props, AgentOnboardingProvider provider, String agentId, String model, String apiKey) {
+        props.put("agent.agents.default", agentId);
+        props.put(runtimeAgentKey(agentId, "enabled"), true);
+        props.put(runtimeAgentKey(agentId, "provider"), provider.getId());
+        props.put(runtimeAgentKey(agentId, "model"), model);
+        props.put(runtimeAgentKey(agentId, "api-key"), apiKey);
+        props.put(runtimeAgentKey(agentId, "workspace"), existingWorkspacePath(agentId));
+        provider.runtimeModelProperties().forEach((key, value) -> props.put(runtimeAgentKey(agentId, key), value));
+    }
+
+    private String existingWorkspacePath(String agentId) {
+        String configuredWorkspace = env.getProperty(runtimeAgentKey(agentId, "workspace"), "");
+        if (!configuredWorkspace.isBlank()) {
+            return configuredWorkspace;
+        }
+        return agentWorkspaceResolver.defaultWorkspacePath(agentId).toString();
+    }
+
+    private void clearSpringAiProviderConfig(Map<String, Object> props) {
+        props.put("spring.ai.model.chat", null);
+        props.put("spring.ai.openai.api-key", null);
+        props.put("spring.ai.openai.base-url", null);
+        props.put("spring.ai.openai.chat.options.model", null);
+    }
+
+    private void clearRuntimeDefaultAgent(Map<String, Object> props) {
+        props.put("agent.agents.default", null);
+    }
+
+    static String runtimeAgentKey(String agentId, String suffix) {
+        return "agent.agents.items." + agentId + "." + suffix;
+    }
+
+    private static String normalizeAgentId(String value) {
+        return value == null ? null : value.trim();
+    }
 }
diff --git a/app/src/main/java/ai/javaclaw/onboarding/steps/S3_CredentialsStep.java b/app/src/main/java/ai/javaclaw/onboarding/steps/S3_CredentialsStep.java
index ab76499..5ce9d4c 100644
--- a/app/src/main/java/ai/javaclaw/onboarding/steps/S3_CredentialsStep.java
+++ b/app/src/main/java/ai/javaclaw/onboarding/steps/S3_CredentialsStep.java
@@ -33,27 +33,26 @@ public S3_CredentialsStep(Environment env, AgentOnboardingProviders agentOnboard
 
     @Override
     public void prepareModel(Map<String, Object> session, Map<String, Object> model) {
-        String providerId = (String) session.getOrDefault(S2_ProviderStep.SESSION_PROVIDER, env.getProperty("spring.ai.model.chat", ""));
-        AgentOnboardingProvider provider = agentOnboardingProviders.findById(providerId).orElse(null);
+        AgentOnboardingProvider provider = resolveProvider(session);
         if (provider == null) return;
 
-        String currentModel = (String) session.get(S2_ProviderStep.SESSION_MODEL);
-        String existingModel = env.getProperty(provider.createPropertyKey("chat.options.model"), "");
-        String existingApiKey = env.getProperty(provider.createPropertyKey("api-key"), "");
+        CredentialsFormState formState = buildFormState(session, provider);
         model.put("selectedProvider", provider.getId());
+        model.put("agentId", formState.agentId());
         model.put("providerLabel", provider.getLabel());
-        model.put("providerApiPropertyKey", provider.createPropertyKey("api-key"));
-        model.put("chatModelPropertyKey", provider.createPropertyKey("chat.options.model"));
+        model.put("providerApiPropertyKey", formState.apiKeyPropertyKey());
+        model.put("chatModelPropertyKey", formState.modelPropertyKey());
+        model.put("baseUrlPropertyKey", formState.baseUrlPropertyKey());
+        model.put("baseUrl", formState.baseUrl());
         model.put("requiresApiKey", provider.requiresApiKey());
-        model.put("apiKey", session.getOrDefault(S2_ProviderStep.SESSION_API_KEY, existingApiKey));
-        model.put("model", currentModel != null && !currentModel.isBlank() ? currentModel : (!existingModel.isBlank() ? existingModel : provider.defaultModel()));
+        model.put("apiKey", formState.apiKey());
+        model.put("model", formState.model());
         provider.systemWideToken().ifPresent(t -> model.put("systemWideTokenName", t.name()));
     }
 
     @Override
     public String processStep(Map<String, String> formParams, Map<String, Object> session) {
-        String providerId = (String) session.getOrDefault(S2_ProviderStep.SESSION_PROVIDER, env.getProperty("spring.ai.model.chat", ""));
-        AgentOnboardingProvider provider = agentOnboardingProviders.findById(providerId).orElse(null);
+        AgentOnboardingProvider provider = resolveProvider(session);
         if (provider == null) {
             return "Provider selection is missing. Please go back and select a provider.";
         }
@@ -82,8 +81,82 @@ public String processStep(Map<String, String> formParams, Map<String, Object> se
         return null;
     }
 
-    AgentOnboardingProvider getAgentProvider(Map<String, Object> session) {
-        String providerId = (String) session.getOrDefault(S2_ProviderStep.SESSION_PROVIDER, env.getProperty("spring.ai.model.chat", ""));
-        return agentOnboardingProviders.getById(providerId);
+    private AgentOnboardingProvider resolveProvider(Map<String, Object> session) {
+        String providerId = (String) session.getOrDefault(S2_ProviderStep.SESSION_PROVIDER, existingProviderId());
+        return agentOnboardingProviders.findById(providerId).orElse(null);
+    }
+
+    private CredentialsFormState buildFormState(Map<String, Object> session, AgentOnboardingProvider provider) {
+        String agentId = currentAgentId(session);
+        String persistedModel = existingModel(provider, agentId);
+        String persistedApiKey = existingApiKey(provider, agentId);
+        String currentModel = (String) session.get(S2_ProviderStep.SESSION_MODEL);
+
+        return new CredentialsFormState(
+                agentId,
+                modelPropertyKey(provider, agentId),
+                apiKeyPropertyKey(provider, agentId),
+                baseUrlPropertyKey(provider, agentId),
+                provider.runtimeModelProperties().get("base-url"),
+                (String) session.getOrDefault(S2_ProviderStep.SESSION_API_KEY, persistedApiKey),
+                currentModel != null && !currentModel.isBlank() ? currentModel : (!persistedModel.isBlank() ? persistedModel : provider.defaultModel())
+        );
+    }
+
+    private String existingModel(AgentOnboardingProvider provider, String agentId) {
+        return provider.usesRuntimeRegistry()
+                ? env.getProperty(S2_ProviderStep.runtimeAgentKey(agentId, "model"), "")
+                : env.getProperty(provider.createPropertyKey("chat.options.model"), "");
+    }
+
+    private String existingApiKey(AgentOnboardingProvider provider, String agentId) {
+        return provider.usesRuntimeRegistry()
+                ? env.getProperty(S2_ProviderStep.runtimeAgentKey(agentId, "api-key"), "")
+                : env.getProperty(provider.createPropertyKey("api-key"), "");
     }
+
+    private String modelPropertyKey(AgentOnboardingProvider provider, String agentId) {
+        return provider.usesRuntimeRegistry()
+                ? S2_ProviderStep.runtimeAgentKey(agentId, "model")
+                : provider.createPropertyKey("chat.options.model");
+    }
+
+    private String apiKeyPropertyKey(AgentOnboardingProvider provider, String agentId) {
+        return provider.usesRuntimeRegistry()
+                ? S2_ProviderStep.runtimeAgentKey(agentId, "api-key")
+                : provider.createPropertyKey("api-key");
+    }
+
+    private String baseUrlPropertyKey(AgentOnboardingProvider provider, String agentId) {
+        if (!provider.usesRuntimeRegistry() || !provider.runtimeModelProperties().containsKey("base-url")) {
+            return null;
+        }
+        return S2_ProviderStep.runtimeAgentKey(agentId, "base-url");
+    }
+
+    private String existingProviderId() {
+        String runtimeProvider = env.getProperty(S2_ProviderStep.runtimeAgentKey(currentAgentId(Map.of()), "provider"), "");
+        if (!runtimeProvider.isBlank()) {
+            return runtimeProvider;
+        }
+        return env.getProperty("spring.ai.model.chat", "");
+    }
+
+    private String currentAgentId(Map<String, Object> session) {
+        Object sessionAgentId = session.get(S2_ProviderStep.SESSION_AGENT_ID);
+        if (sessionAgentId instanceof String stringValue && !stringValue.isBlank()) {
+            return stringValue;
+        }
+        return env.getProperty("agent.agents.default", "default");
+    }
+
+    private record CredentialsFormState(
+            String agentId,
+            String modelPropertyKey,
+            String apiKeyPropertyKey,
+            String baseUrlPropertyKey,
+            Object baseUrl,
+            String apiKey,
+            String model
+    ) {}
 }
diff --git a/app/src/main/java/ai/javaclaw/onboarding/steps/S4_AgentMdStep.java b/app/src/main/java/ai/javaclaw/onboarding/steps/S4_AgentMdStep.java
index 9b1f44c..192c8dd 100644
--- a/app/src/main/java/ai/javaclaw/onboarding/steps/S4_AgentMdStep.java
+++ b/app/src/main/java/ai/javaclaw/onboarding/steps/S4_AgentMdStep.java
@@ -1,19 +1,23 @@
 package ai.javaclaw.onboarding.steps;
 
 import ai.javaclaw.configuration.ConfigurationManager;
+import ai.javaclaw.agents.AgentWorkspaceResolver;
+import ai.javaclaw.onboarding.AgentOnboardingProviders;
 import ai.javaclaw.onboarding.OnboardingProvider;
-import org.springframework.beans.factory.annotation.Value;
 import org.springframework.core.annotation.Order;
+import org.springframework.core.env.Environment;
 import org.springframework.core.io.Resource;
 import org.springframework.stereotype.Component;
 
 import java.io.IOException;
 import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
+import java.nio.file.Path;
 import java.nio.file.StandardOpenOption;
 import java.util.Map;
 
 import static ai.javaclaw.JavaClawConfiguration.AGENT_MD;
+import static ai.javaclaw.JavaClawConfiguration.AGENT_PRIVATE_MD;
 
 @Component
 @Order(40)
@@ -21,10 +25,16 @@ public class S4_AgentMdStep implements OnboardingProvider {
 
     static final String SESSION_AGENT_CONTENT = "onboarding.agent.content";
 
-    private final Resource agentWorkspace;
+    private final Environment environment;
+    private final AgentOnboardingProviders agentOnboardingProviders;
+    private final AgentWorkspaceResolver agentWorkspaceResolver;
 
-    public S4_AgentMdStep(@Value("${agent.workspace}") Resource agentWorkspace) {
-        this.agentWorkspace = agentWorkspace;
+    public S4_AgentMdStep(Environment environment,
+                          AgentOnboardingProviders agentOnboardingProviders,
+                          AgentWorkspaceResolver agentWorkspaceResolver) {
+        this.environment = environment;
+        this.agentOnboardingProviders = agentOnboardingProviders;
+        this.agentWorkspaceResolver = agentWorkspaceResolver;
     }
 
     @Override
@@ -40,16 +50,16 @@ public S4_AgentMdStep(@Value("${agent.workspace}") Resource agentWorkspace) {
     public void prepareModel(Map<String, Object> session, Map<String, Object> model) {
         Object agentContent = session.get(SESSION_AGENT_CONTENT);
         if (agentContent == null) {
-            agentContent = readFile(AGENT_MD);
-            if (agentContent == null) agentContent = readFile("AGENT.md");
+            agentContent = readFile(session, AGENT_PRIVATE_MD);
+            if (agentContent == null) agentContent = readFile(session, AGENT_MD);
             if (agentContent == null) agentContent = "";
         }
         model.put("agentContent", agentContent);
     }
 
-    private String readFile(String name) {
+    private String readFile(Map<String, Object> session, String name) {
         try {
-            return agentWorkspace.createRelative(name).getContentAsString(StandardCharsets.UTF_8);
+            return resolveAgentWorkspace(session).createRelative(name).getContentAsString(StandardCharsets.UTF_8);
         } catch (IOException e) {
             return null;
         }
@@ -70,8 +80,9 @@ public void saveConfiguration(Map<String, Object> session, ConfigurationManager
         String agentContent = (String) session.getOrDefault(SESSION_AGENT_CONTENT, "");
         if (agentContent.isBlank()) return;
         try {
+            Resource agentWorkspace = resolveAgentWorkspace(session);
             Files.writeString(
-                    agentWorkspace.createRelative(AGENT_MD).getFilePath(),
+                    agentWorkspace.createRelative(AGENT_PRIVATE_MD).getFilePath(),
                     agentContent,
                     StandardCharsets.UTF_8,
                     StandardOpenOption.CREATE, StandardOpenOption.TRUNCATE_EXISTING, StandardOpenOption.WRITE
@@ -80,4 +91,31 @@ public void saveConfiguration(Map<String, Object> session, ConfigurationManager
             throw new RuntimeException("Failed to write AGENT.private.md", e);
         }
     }
+
+    private Resource resolveAgentWorkspace(Map<String, Object> session) throws IOException {
+        if (!usesAgentWorkspace(session)) {
+            return agentWorkspaceResolver.rootWorkspace();
+        }
+
+        String agentId = (String) session.getOrDefault(S2_ProviderStep.SESSION_AGENT_ID, environment.getProperty("agent.agents.default", "default"));
+        String configuredWorkspace = environment.getProperty(S2_ProviderStep.runtimeAgentKey(agentId, "workspace"), "");
+        Path workspacePath = agentWorkspaceResolver.initializeWorkspace(
+                agentWorkspaceResolver.resolveWorkspacePath(configuredWorkspace, agentId)
+        );
+        return agentWorkspaceResolver.asResource(workspacePath);
+    }
+
+    private boolean usesAgentWorkspace(Map<String, Object> session) {
+        String providerId = (String) session.get(S2_ProviderStep.SESSION_PROVIDER);
+        if (providerId == null || providerId.isBlank()) {
+            String agentId = (String) session.getOrDefault(S2_ProviderStep.SESSION_AGENT_ID, environment.getProperty("agent.agents.default", "default"));
+            providerId = environment.getProperty(S2_ProviderStep.runtimeAgentKey(agentId, "provider"), "");
+        }
+        if (providerId == null || providerId.isBlank()) {
+            return false;
+        }
+        return agentOnboardingProviders.findById(providerId)
+                .map(provider -> provider.usesRuntimeRegistry())
+                .orElse(false);
+    }
 }
diff --git a/app/src/main/resources/application.yaml b/app/src/main/resources/application.yaml
index 8137b6f..1264960 100644
--- a/app/src/main/resources/application.yaml
+++ b/app/src/main/resources/application.yaml
@@ -1,13 +1,25 @@
 spring:
   application:
     name: JavaClaw
+  autoconfigure:
+    exclude:
+      - org.springframework.ai.model.anthropic.autoconfigure.AnthropicChatAutoConfiguration
+      - org.springframework.ai.model.google.genai.autoconfigure.chat.GoogleGenAiChatAutoConfiguration
+      - org.springframework.ai.model.ollama.autoconfigure.OllamaApiAutoConfiguration
+      - org.springframework.ai.model.ollama.autoconfigure.OllamaChatAutoConfiguration
+      - org.springframework.ai.model.ollama.autoconfigure.OllamaEmbeddingAutoConfiguration
+      - org.springframework.ai.model.openai.autoconfigure.OpenAiChatAutoConfiguration
+      - org.springframework.ai.model.openai.autoconfigure.OpenAiAudioSpeechAutoConfiguration
+      - org.springframework.ai.model.openai.autoconfigure.OpenAiAudioTranscriptionAutoConfiguration
+      - org.springframework.ai.model.openai.autoconfigure.OpenAiEmbeddingAutoConfiguration
+      - org.springframework.ai.model.openai.autoconfigure.OpenAiImageAutoConfiguration
+      - org.springframework.ai.model.openai.autoconfigure.OpenAiModerationAutoConfiguration
   config:
     import: optional:classpath:application.private.yaml
   datasource:
     url: jdbc:h2:file:./workspace/app
   ai:
     model:
-      chat: unknown
       audio.speech: unknown
       audio.transcription: unknown
       embedding: unknown
diff --git a/app/src/main/resources/templates/agents.html.peb b/app/src/main/resources/templates/agents.html.peb
new file mode 100644
index 0000000..dd2f532
--- /dev/null
+++ b/app/src/main/resources/templates/agents.html.peb
@@ -0,0 +1,127 @@
+{% extends "base" %}
+
+{% block title %} Agents{% endblock %}
+
+{% block head %}
+<style>
+.agents-shell {
+    min-height: 100vh;
+    background:
+        radial-gradient(circle at top left, rgba(72, 199, 142, .14), transparent 32%),
+        radial-gradient(circle at bottom right, rgba(50, 115, 220, .10), transparent 28%),
+        linear-gradient(180deg, #0f1419 0%, #151b21 100%);
+    color: #e8edf3;
+}
+
+.agents-shell .navbar {
+    background: transparent;
+    border-bottom: 1px solid rgba(255, 255, 255, .08);
+}
+
+.agents-shell .card {
+    background: rgba(16, 22, 29, .86);
+    border: 1px solid rgba(255, 255, 255, .08);
+    box-shadow: 0 22px 50px rgba(0, 0, 0, .18);
+}
+
+.agents-shell .table {
+    background: transparent;
+    color: #dce4ee;
+}
+
+.agents-shell .table thead th {
+    color: rgba(220, 228, 238, .72);
+    border-color: rgba(255, 255, 255, .08);
+}
+
+.agents-shell .table td {
+    border-color: rgba(255, 255, 255, .06);
+    vertical-align: middle;
+}
+
+.agents-shell .tag.is-default {
+    background: rgba(72, 199, 142, .14);
+    color: #7ee2b2;
+    border: 1px solid rgba(72, 199, 142, .28);
+}
+
+.agents-shell code {
+    color: #d9f5e6;
+    background: rgba(255, 255, 255, .06);
+}
+</style>
+{% endblock %}
+
+{% block content %}
+<section class="section agents-shell">
+    <nav class="navbar" role="navigation" aria-label="main navigation">
+        <div class="navbar-brand">
+            <span class="navbar-item">
+                <div class="brand-lockup">
+                    <p class="brand-word"><span class="brand-agent">Java</span><span class="brand-runr">Claw</span></p>
+                </div>
+            </span>
+        </div>
+        <div class="navbar-end">
+            <div class="navbar-item">
+                <a href="/chat" class="button is-dark is-small">Chat</a>
+            </div>
+            <div class="navbar-item">
+                <a href="/onboarding" class="button is-primary is-small">Add Agent</a>
+            </div>
+        </div>
+    </nav>
+
+    <div class="container mt-6">
+        <div class="columns is-variable is-6">
+            <div class="column is-8">
+                <h1 class="title is-2 has-text-white mb-2">Agents</h1>
+                <p class="subtitle has-text-grey-light mb-0">Configured runtime agents, their provider, workspace, and which one is currently default.</p>
+            </div>
+        </div>
+
+        <div class="card mt-5">
+            <div class="card-content">
+                {% if hasAgents %}
+                <div class="table-container">
+                    <table class="table is-fullwidth is-hoverable">
+                        <thead>
+                        <tr>
+                            <th>Agent</th>
+                            <th>Provider</th>
+                            <th>Model</th>
+                            <th>Workspace</th>
+                            <th>Status</th>
+                        </tr>
+                        </thead>
+                        <tbody>
+                        {% for agent in agents %}
+                        <tr>
+                            <td><strong>{{ agent.id }}</strong></td>
+                            <td>{{ agent.provider }}</td>
+                            <td><code>{{ agent.model }}</code></td>
+                            <td><code>{{ agent.workspace }}</code></td>
+                            <td>
+                                {% if agent.isDefault %}
+                                <span class="tag is-rounded is-default">Default</span>
+                                {% else %}
+                                <span class="tag is-rounded is-dark">Secondary</span>
+                                {% endif %}
+                            </td>
+                        </tr>
+                        {% endfor %}
+                        </tbody>
+                    </table>
+                </div>
+                {% else %}
+                <article class="message is-warning is-dark">
+                    <div class="message-body">
+                        No runtime agents are configured yet. Start with onboarding to add the first one.
+                    </div>
+                </article>
+                {% endif %}
+            </div>
+        </div>
+    </div>
+</section>
+{% endblock %}
diff --git a/app/src/main/resources/templates/chat.html.peb b/app/src/main/resources/templates/chat.html.peb
index 4728c84..7117780 100644
--- a/app/src/main/resources/templates/chat.html.peb
+++ b/app/src/main/resources/templates/chat.html.peb
@@ -164,9 +164,17 @@
             </span>
         </div>
         <div class="navbar-end">
+            <div class="navbar-item">
+                <div class="select is-small is-dark" id="agent-selector"></div>
+            </div>
             <div class="navbar-item">
                 <div class="select is-small is-dark" id="channel-selector"></div>
             </div>
+            <div class="navbar-item">
+                <a href="/agents" class="button is-small is-dark">
+                    <span>Agents</span>
+                </a>
+            </div>
             <div class="navbar-item">
                 <a href="/onboarding" class="button is-small is-dark">
                     <span>Settings</span>
@@ -194,7 +202,7 @@
     <div class="chat-footer">
         <div class="container" id="chat-input-area">
             <form id="chat-form" ws-send hx-boost="false"
-                  hx-vals='js:{"type": "userMessage", "conversationId": document.getElementById("channel-select") ? document.getElementById("channel-select").value : "web"}'>
+                  hx-vals='js:{"type": "userMessage", "agentId": document.getElementById("agent-select") ? document.getElementById("agent-select").value : "", "conversationId": document.getElementById("channel-select") ? document.getElementById("channel-select").value : "web"}'>
                 <div class="field is-grouped" style="align-items: flex-end; margin: 0;">
                     <div class="control is-expanded">
                         <textarea id="message-input" class="textarea" name="message" rows="1"
diff --git a/app/src/main/resources/templates/onboarding/steps/S2-provider.html.peb b/app/src/main/resources/templates/onboarding/steps/S2-provider.html.peb
index 6923e3f..89469c0 100644
--- a/app/src/main/resources/templates/onboarding/steps/S2-provider.html.peb
+++ b/app/src/main/resources/templates/onboarding/steps/S2-provider.html.peb
@@ -24,10 +24,18 @@
             </div>
         </div>
 
+        <div class="field">
+            <label class="label" for="agentId">Agent id</label>
+            <div class="control">
+                <input id="agentId" class="input is-medium" type="text" name="agentId" value="{{ agentId }}" placeholder="e.g. openai-main" autocomplete="off">
+            </div>
+            <p class="help">Use a unique agent id so you can have multiple agents backed by the same provider later.</p>
+        </div>
+
         <div class="buttons mt-4">
             <a class="button is-light is-medium" href="{{ previousStepUrl }}">Back</a>
             <button class="button is-primary is-medium" type="submit">Continue</button>
             <span class="button is-ghost is-medium htmx-indicator">Saving...</span>
         </div>
     </form>
-</div>
\ No newline at end of file
+</div>
diff --git a/app/src/main/resources/templates/onboarding/steps/S3-credentials.html.peb b/app/src/main/resources/templates/onboarding/steps/S3-credentials.html.peb
index 9061301..e93eb00 100644
--- a/app/src/main/resources/templates/onboarding/steps/S3-credentials.html.peb
+++ b/app/src/main/resources/templates/onboarding/steps/S3-credentials.html.peb
@@ -14,6 +14,12 @@
     {% endif %}
 
     <form method="post" action="/onboarding/credentials">
+        <div class="field">
+            <label class="label" for="agentId">Agent id</label>
+            <div class="control">
+                <input id="agentId" class="input is-medium" type="text" value="{{ agentId }}" disabled>
+            </div>
+        </div>
         {% if requiresApiKey %}
         {% if systemWideTokenName %}
         <div class="message is-link mb-4">
@@ -47,6 +53,10 @@
             {% if requiresApiKey %}
             <p class="has-text-grey-dark">{{ providerApiPropertyKey }}</p>
             {% endif %}
+            {% if baseUrlPropertyKey %}
+            <p class="has-text-grey-dark">{{ baseUrlPropertyKey }}</p>
+            <p class="has-text-grey-dark">Value: {{ baseUrl }}</p>
+            {% endif %}
         </div>
 
         <div class="buttons mt-4">
@@ -55,4 +65,4 @@
             <span class="button is-ghost is-medium htmx-indicator">Saving...</span>
         </div>
     </form>
-</div>
\ No newline at end of file
+</div>
diff --git a/app/src/test/java/ai/javaclaw/api/AgentsControllerTest.java b/app/src/test/java/ai/javaclaw/api/AgentsControllerTest.java
new file mode 100644
index 0000000..19dbe86
--- /dev/null
+++ b/app/src/test/java/ai/javaclaw/api/AgentsControllerTest.java
@@ -0,0 +1,44 @@
+package ai.javaclaw.api;
+
+import ai.javaclaw.agents.AgentRegistry;
+import ai.javaclaw.agents.AgentWorkspaceResolver;
+import ai.javaclaw.agents.ConfiguredAgent;
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
+import org.springframework.test.context.bean.override.mockito.MockitoBean;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.beans.factory.annotation.Autowired;
+
+import java.nio.file.Path;
+import java.util.List;
+import static org.mockito.Mockito.when;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+@WebMvcTest(AgentsController.class)
+class AgentsControllerTest {
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @MockitoBean
+    private AgentRegistry agentRegistry;
+
+    @MockitoBean
+    private AgentWorkspaceResolver agentWorkspaceResolver;
+
+    @Test
+    void agentsPageShowsConfiguredAgentsAndDefaultBadge() throws Exception {
+        ConfiguredAgent configuredAgent = new ConfiguredAgent("openai-main", "openai", "gpt-5.4", "secret", "", "");
+        when(agentRegistry.getAgents()).thenReturn(List.of(configuredAgent));
+        when(agentRegistry.getDefaultAgentId()).thenReturn("openai-main");
+        when(agentWorkspaceResolver.resolveWorkspacePath("", "openai-main")).thenReturn(Path.of("/tmp/workspace/agents/openai-main"));
+
+        mockMvc.perform(get("/agents"))
+                .andExpect(status().isOk())
+                .andExpect(content().string(org.hamcrest.Matchers.containsString("Agents")))
+                .andExpect(content().string(org.hamcrest.Matchers.containsString("openai-main")))
+                .andExpect(content().string(org.hamcrest.Matchers.containsString("Default")));
+    }
+}
diff --git a/app/src/test/java/ai/javaclaw/api/OnboardingControllerTest.java b/app/src/test/java/ai/javaclaw/api/OnboardingControllerTest.java
index c14439b..6e40eda 100644
--- a/app/src/test/java/ai/javaclaw/api/OnboardingControllerTest.java
+++ b/app/src/test/java/ai/javaclaw/api/OnboardingControllerTest.java
@@ -1,6 +1,7 @@
 package ai.javaclaw.api;
 
 import ai.javaclaw.configuration.ConfigurationManager;
+import ai.javaclaw.agents.AgentWorkspaceResolver;
 import ai.javaclaw.onboarding.AgentOnboardingProviders;
 import ai.javaclaw.onboarding.api.OnboardingController;
 import ai.javaclaw.onboarding.steps.S1_WelcomeStep;
@@ -33,6 +34,9 @@ class OnboardingControllerTest {
     @MockitoBean
     private AgentOnboardingProviders agentOnboardingProviders;
 
+    @MockitoBean
+    private AgentWorkspaceResolver agentWorkspaceResolver;
+
     @Test
     void providerSubmissionWithoutSelectionShowsFlashError() throws Exception {
         mockMvc.perform(post("/onboarding/provider"))
@@ -40,4 +44,4 @@ void providerSubmissionWithoutSelectionShowsFlashError() throws Exception {
                 .andExpect(redirectedUrl("/onboarding/provider"))
                 .andExpect(flash().attribute("error", "Choose one of the supported providers to continue."));
     }
-}
\ No newline at end of file
+}
diff --git a/app/src/test/java/ai/javaclaw/chat/ChatChannelTest.java b/app/src/test/java/ai/javaclaw/chat/ChatChannelTest.java
index 206bf42..3d1ad40 100644
--- a/app/src/test/java/ai/javaclaw/chat/ChatChannelTest.java
+++ b/app/src/test/java/ai/javaclaw/chat/ChatChannelTest.java
@@ -1,6 +1,9 @@
 package ai.javaclaw.chat;
 
 import ai.javaclaw.agent.Agent;
+import ai.javaclaw.agents.AgentConversationId;
+import ai.javaclaw.agents.AgentRegistry;
+import ai.javaclaw.agents.ConfiguredAgent;
 import ai.javaclaw.channels.ChannelRegistry;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
@@ -19,6 +22,7 @@
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.lenient;
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.never;
 import static org.mockito.Mockito.verify;
@@ -28,13 +32,16 @@
 class ChatChannelTest {
 
     @Mock Agent agent;
+    @Mock AgentRegistry agentRegistry;
     @Mock ChatMemoryRepository chatMemoryRepository;
 
     ChatChannel chatChannel;
 
     @BeforeEach
     void setUp() {
-        chatChannel = new ChatChannel(agent, new ChannelRegistry(), chatMemoryRepository);
+        lenient().when(agentRegistry.getDefaultAgentId()).thenReturn("openai-main");
+        lenient().when(agentRegistry.getAgents()).thenReturn(List.of(new ConfiguredAgent("openai-main", "openai", "gpt-5.4", "", "", "")));
+        chatChannel = new ChatChannel(agent, agentRegistry, new ChannelRegistry(), chatMemoryRepository);
     }
 
     // -----------------------------------------------------------------------
@@ -43,9 +50,12 @@ void setUp() {
 
     @Test
     void conversationIdsAlwaysContainsWebFirst() {
-        when(chatMemoryRepository.findConversationIds()).thenReturn(List.of("telegram-42", "web"));
+        when(chatMemoryRepository.findConversationIds()).thenReturn(List.of(
+                AgentConversationId.scoped("openai-main", "telegram-42"),
+                AgentConversationId.scoped("openai-main", "web")
+        ));
 
-        List<String> ids = chatChannel.conversationIds();
+        List<String> ids = chatChannel.conversationIds("openai-main");
 
         assertThat(ids).first().isEqualTo("web");
     }
@@ -54,25 +64,31 @@ void conversationIdsAlwaysContainsWebFirst() {
     void conversationIdsIncludesWebEvenWhenRepositoryReturnsEmpty() {
         when(chatMemoryRepository.findConversationIds()).thenReturn(List.of());
 
-        List<String> ids = chatChannel.conversationIds();
+        List<String> ids = chatChannel.conversationIds("openai-main");
 
         assertThat(ids).containsExactly("web");
     }
 
     @Test
     void conversationIdsIncludesOtherChannelsAfterWeb() {
-        when(chatMemoryRepository.findConversationIds()).thenReturn(List.of("telegram-42", "telegram-99"));
+        when(chatMemoryRepository.findConversationIds()).thenReturn(List.of(
+                AgentConversationId.scoped("openai-main", "telegram-42"),
+                AgentConversationId.scoped("openai-main", "telegram-99")
+        ));
 
-        List<String> ids = chatChannel.conversationIds();
+        List<String> ids = chatChannel.conversationIds("openai-main");
 
         assertThat(ids).containsExactly("web", "telegram-42", "telegram-99");
     }
 
     @Test
     void conversationIdsDeduplicatesWeb() {
-        when(chatMemoryRepository.findConversationIds()).thenReturn(List.of("web", "telegram-42"));
+        when(chatMemoryRepository.findConversationIds()).thenReturn(List.of(
+                AgentConversationId.scoped("openai-main", "web"),
+                AgentConversationId.scoped("openai-main", "telegram-42")
+        ));
 
-        List<String> ids = chatChannel.conversationIds();
+        List<String> ids = chatChannel.conversationIds("openai-main");
 
         assertThat(ids.stream().filter("web"::equals)).hasSize(1);
     }
@@ -83,9 +99,9 @@ void conversationIdsDeduplicatesWeb() {
 
     @Test
     void loadHistoryReturnsWelcomeBubbleWhenNoHistory() {
-        when(chatMemoryRepository.findByConversationId("web")).thenReturn(List.of());
+        when(chatMemoryRepository.findByConversationId("openai-main::web")).thenReturn(List.of());
 
-        List<String> bubbles = chatChannel.loadHistoryAsHtml("web");
+        List<String> bubbles = chatChannel.loadHistoryAsHtml("openai-main", "web");
 
         assertThat(bubbles).hasSize(1);
         assertThat(bubbles.get(0)).contains("ar-msg--agent");
@@ -93,12 +109,12 @@ void loadHistoryReturnsWelcomeBubbleWhenNoHistory() {
 
     @Test
     void loadHistoryRendersUserAndAgentBubbles() {
-        when(chatMemoryRepository.findByConversationId("web")).thenReturn(List.of(
+        when(chatMemoryRepository.findByConversationId("openai-main::web")).thenReturn(List.of(
                 new UserMessage("Hello"),
                 new AssistantMessage("Hi there")
         ));
 
-        List<String> bubbles = chatChannel.loadHistoryAsHtml("web");
+        List<String> bubbles = chatChannel.loadHistoryAsHtml("openai-main", "web");
 
         assertThat(bubbles).hasSize(2);
         assertThat(bubbles.get(0)).contains("ar-msg--user").contains("Hello");
@@ -107,22 +123,22 @@ void loadHistoryRendersUserAndAgentBubbles() {
 
     @Test
     void loadHistoryEscapesHtmlInMessages() {
-        when(chatMemoryRepository.findByConversationId("web")).thenReturn(List.of(
+        when(chatMemoryRepository.findByConversationId("openai-main::web")).thenReturn(List.of(
                 new UserMessage("<script>alert('xss')</script>")
         ));
 
-        List<String> bubbles = chatChannel.loadHistoryAsHtml("web");
+        List<String> bubbles = chatChannel.loadHistoryAsHtml("openai-main", "web");
 
         assertThat(bubbles.get(0)).doesNotContain("<script>").contains("&lt;script&gt;");
     }
 
     @Test
     void loadHistoryUsesSuppliedConversationId() {
-        when(chatMemoryRepository.findByConversationId("telegram-42")).thenReturn(List.of());
+        when(chatMemoryRepository.findByConversationId("openai-main::telegram-42")).thenReturn(List.of());
 
-        chatChannel.loadHistoryAsHtml("telegram-42");
+        chatChannel.loadHistoryAsHtml("openai-main", "telegram-42");
 
-        verify(chatMemoryRepository).findByConversationId("telegram-42");
+        verify(chatMemoryRepository).findByConversationId("openai-main::telegram-42");
     }
 
     // -----------------------------------------------------------------------
@@ -131,21 +147,21 @@ void loadHistoryUsesSuppliedConversationId() {
 
     @Test
     void chatDelegatesToAgentWithConversationId() {
-        when(agent.respondTo("web", "hello")).thenReturn("hi");
+        when(agent.respondTo("openai-main", "web", "hello")).thenReturn("hi");
 
-        String response = chatChannel.chat("web", "hello");
+        String response = chatChannel.chat("openai-main", "web", "hello");
 
         assertThat(response).isEqualTo("hi");
-        verify(agent).respondTo(eq("web"), eq("hello"));
+        verify(agent).respondTo(eq("openai-main"), eq("web"), eq("hello"));
     }
 
     @Test
     void chatUsesSuppliedConversationId() {
-        when(agent.respondTo(eq("telegram-42"), any())).thenReturn("reply");
+        when(agent.respondTo(eq("openai-main"), eq("telegram-42"), any())).thenReturn("reply");
 
-        chatChannel.chat("telegram-42", "hello");
+        chatChannel.chat("openai-main", "telegram-42", "hello");
 
-        verify(agent).respondTo(eq("telegram-42"), eq("hello"));
+        verify(agent).respondTo(eq("openai-main"), eq("telegram-42"), eq("hello"));
     }
 
     // -----------------------------------------------------------------------
diff --git a/app/src/test/java/ai/javaclaw/chat/ws/ChatWebSocketHandlerTest.java b/app/src/test/java/ai/javaclaw/chat/ws/ChatWebSocketHandlerTest.java
index c150440..b588dbb 100644
--- a/app/src/test/java/ai/javaclaw/chat/ws/ChatWebSocketHandlerTest.java
+++ b/app/src/test/java/ai/javaclaw/chat/ws/ChatWebSocketHandlerTest.java
@@ -15,7 +15,6 @@
 import static org.mockito.Mockito.inOrder;
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.verify;
-import static org.mockito.Mockito.verifyNoMoreInteractions;
 import static org.mockito.Mockito.when;
 
 class ChatWebSocketHandlerTest {
@@ -26,7 +25,8 @@ void handleUserMessageShowsNonTransientErrorAndClearsTypingIndicatorWhenAgentFai
         WebSocketSession session = mock(WebSocketSession.class);
         ChatWebSocketHandler handler = new ChatWebSocketHandler(chatChannel, new ObjectMapper());
 
-        when(chatChannel.chat("web", "hello")).thenThrow(new RuntimeException("""
+        when(chatChannel.defaultAgentId()).thenReturn("openai-main");
+        when(chatChannel.chat("openai-main", "web", "hello")).thenThrow(new RuntimeException("""
                 HTTP 401 - {
                     "error": {
                         "message": "Incorrect API key provided: Test.",
@@ -44,10 +44,8 @@ void handleUserMessageShowsNonTransientErrorAndClearsTypingIndicatorWhenAgentFai
         ArgumentCaptor<String[]> htmlCaptor = ArgumentCaptor.forClass(String[].class);
         var inOrder = inOrder(chatChannel);
         inOrder.verify(chatChannel).sendHtml(htmlCaptor.capture());
-        inOrder.verify(chatChannel).chat("web", "hello");
+        inOrder.verify(chatChannel).chat("openai-main", "web", "hello");
         inOrder.verify(chatChannel).sendHtml(htmlCaptor.capture());
-        verifyNoMoreInteractions(chatChannel);
-
         assertThat(String.join("", htmlCaptor.getAllValues().get(0)))
                 .contains("hello")
                 .contains("typing-indicator")
@@ -66,7 +64,8 @@ void handleUserMessageShowsGenericProviderErrorForUnexpectedFailures() throws Ex
         WebSocketSession session = mock(WebSocketSession.class);
         ChatWebSocketHandler handler = new ChatWebSocketHandler(chatChannel, new ObjectMapper());
 
-        when(chatChannel.chat(anyString(), anyString())).thenThrow(new RuntimeException("boom"));
+        when(chatChannel.defaultAgentId()).thenReturn("openai-main");
+        when(chatChannel.chat(anyString(), anyString(), anyString())).thenThrow(new RuntimeException("boom"));
 
         handler.handleTextMessage(session, new TextMessage(new ObjectMapper().writeValueAsString(Map.of(
                 "type", "userMessage",
@@ -77,7 +76,7 @@ void handleUserMessageShowsGenericProviderErrorForUnexpectedFailures() throws Ex
         ArgumentCaptor<String[]> htmlCaptor = ArgumentCaptor.forClass(String[].class);
         var inOrder = inOrder(chatChannel);
         inOrder.verify(chatChannel).sendHtml(htmlCaptor.capture());
-        inOrder.verify(chatChannel).chat("web", "hello");
+        inOrder.verify(chatChannel).chat("openai-main", "web", "hello");
         inOrder.verify(chatChannel).sendHtml(htmlCaptor.capture());
 
         assertThat(String.join("", htmlCaptor.getAllValues().get(1)))
@@ -91,7 +90,8 @@ void handleChannelChangedSendsHistoryAndInputArea() throws Exception {
         WebSocketSession session = mock(WebSocketSession.class);
         ChatWebSocketHandler handler = new ChatWebSocketHandler(chatChannel, new ObjectMapper());
 
-        when(chatChannel.loadHistoryAsHtml("web")).thenReturn(List.of("<div>history</div>"));
+        when(chatChannel.defaultAgentId()).thenReturn("openai-main");
+        when(chatChannel.loadHistoryAsHtml("openai-main", "web")).thenReturn(List.of("<div>history</div>"));
 
         handler.handleTextMessage(session, new TextMessage(new ObjectMapper().writeValueAsString(Map.of(
                 "type", "channelChanged",
@@ -113,8 +113,10 @@ void afterConnectionEstablishedSendsSelectorHistoryAndInputArea() throws Excepti
         WebSocketSession session = mock(WebSocketSession.class);
         ChatWebSocketHandler handler = new ChatWebSocketHandler(chatChannel, new ObjectMapper());
 
-        when(chatChannel.conversationIds()).thenReturn(List.of("web"));
-        when(chatChannel.loadHistoryAsHtml("web")).thenReturn(List.of("<div>history</div>"));
+        when(chatChannel.agentIds()).thenReturn(List.of("openai-main"));
+        when(chatChannel.defaultAgentId()).thenReturn("openai-main");
+        when(chatChannel.conversationIds("openai-main")).thenReturn(List.of("web"));
+        when(chatChannel.loadHistoryAsHtml("openai-main", "web")).thenReturn(List.of("<div>history</div>"));
 
         handler.afterConnectionEstablished(session);
 
@@ -123,8 +125,9 @@ void afterConnectionEstablishedSendsSelectorHistoryAndInputArea() throws Excepti
 
         assertThat(String.join("", htmlCaptor.getValue()))
                 .contains("channel-selector")
+                .contains("agent-selector")
                 .contains("chat-messages")
                 .contains("history")
                 .contains("chat-input-area");
     }
-}
\ No newline at end of file
+}
diff --git a/app/src/test/java/ai/javaclaw/onboarding/steps/S4_AgentMdStepTest.java b/app/src/test/java/ai/javaclaw/onboarding/steps/S4_AgentMdStepTest.java
new file mode 100644
index 0000000..8dbdbd1
--- /dev/null
+++ b/app/src/test/java/ai/javaclaw/onboarding/steps/S4_AgentMdStepTest.java
@@ -0,0 +1,87 @@
+package ai.javaclaw.onboarding.steps;
+
+import ai.javaclaw.agents.AgentWorkspaceResolver;
+import ai.javaclaw.onboarding.AgentOnboardingProvider;
+import ai.javaclaw.onboarding.AgentOnboardingProviders;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import org.springframework.mock.env.MockEnvironment;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.LinkedHashSet;
+import java.util.Map;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.Mockito.mock;
+
+class S4_AgentMdStepTest {
+
+    @TempDir
+    Path tempDir;
+
+    @Test
+    void saveConfigurationWritesAgentInstructionsToSelectedAgentWorkspace() throws IOException {
+        Path rootWorkspace = tempDir.resolve("workspace");
+        Files.createDirectories(rootWorkspace);
+        Files.writeString(rootWorkspace.resolve("AGENT.md"), "root agent");
+        Files.writeString(rootWorkspace.resolve("INFO.md"), "root info");
+
+        String agentId = "openai-main";
+        Path modelWorkspace = rootWorkspace.resolve("agents").resolve(agentId);
+        MockEnvironment environment = new MockEnvironment()
+                .withProperty("agent.workspace", "file:" + rootWorkspace + "/")
+                .withProperty(S2_ProviderStep.runtimeAgentKey(agentId, "provider"), "openai")
+                .withProperty(S2_ProviderStep.runtimeAgentKey(agentId, "workspace"), modelWorkspace.toString());
+
+        AgentOnboardingProvider provider = new RuntimeProvider();
+        AgentOnboardingProviders providers = new AgentOnboardingProviders(new LinkedHashSet<>(java.util.List.of(provider)));
+        AgentWorkspaceResolver resolver = new AgentWorkspaceResolver(new org.springframework.core.io.DefaultResourceLoader(), environment);
+        S4_AgentMdStep step = new S4_AgentMdStep(environment, providers, resolver);
+
+        step.saveConfiguration(
+                Map.of(
+                        S2_ProviderStep.SESSION_PROVIDER, "openai",
+                        S2_ProviderStep.SESSION_AGENT_ID, agentId,
+                        S4_AgentMdStep.SESSION_AGENT_CONTENT, "model specific agent"
+                ),
+                mock(ai.javaclaw.configuration.ConfigurationManager.class)
+        );
+
+        assertThat(modelWorkspace.resolve("AGENT.private.md")).hasContent("model specific agent");
+        assertThat(rootWorkspace.resolve("AGENT.private.md")).doesNotExist();
+    }
+
+    private static final class RuntimeProvider implements AgentOnboardingProvider {
+        @Override
+        public String getId() {
+            return "openai";
+        }
+
+        @Override
+        public String getLabel() {
+            return "OpenAI";
+        }
+
+        @Override
+        public String slogan() {
+            return "";
+        }
+
+        @Override
+        public boolean requiresApiKey() {
+            return true;
+        }
+
+        @Override
+        public String defaultModel() {
+            return "gpt-5.4";
+        }
+
+        @Override
+        public boolean usesRuntimeRegistry() {
+            return true;
+        }
+    }
+}
diff --git a/app/workspace/app.mv.db b/app/workspace/app.mv.db
deleted file mode 100644
index 5495ecf769ab11fdfd29b028bce4ca2cd2b770b8..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 53248
zcmeG_OKc>^bv@0`&XUXBm7(=VS}C)mm6nv)qpnZ?CJ3w{Ijg0_UuK3Yt&n8UpXwDY
zF1g`nB{>NqBOeEd4@uxd0yswCQ*sXMoD4Y0AqaAF5ZEz-oB||A`4R+n4tZ78-P1js
zCVOPAtUx`7sjlu<^<KSt^?k2i-D%=QZ+G8+r|HYEyYpq%M7pjo`fnfaz0*W!(cfk6
zUK7Ft<{q)2i5x%lE!PZfZ!z3Ic;Fs2$>Jk+aJaJ%U}!PiWk>$o?4U^zaV=A~W|Z<*
za-ifu$$^psB?n3llpH8IP;#K;K*@oU10@Ga4*VQBaHm}V{~WnrqAod5a-ifu$$^ps
zB?n3llpH8IP;#K;K*@oU10N3uq>|rT++};P6Y$Wz&kmc`;sf`+CJIa)9v(I+UOd>}
zKWbthtO9hyGYq_VwDW*9DRmi36#w4h9((Ty5+CjRU?O1nwR8J%`+?_`KTy<4MN!o6
zDGL6f2rD1HdHw0C?b*J8iLWTr|2=J1)ayzWv(UGRZdM8QOlA;LB_{P9!r+Zfs70tz
zC7z*&l;A2QItpFlR1K352Q#B;*gEk@h^mI;nyzla19N>BIW9bS*tYGkY9r+9Hr1<u
z$3|cZ!Rc^xpAqq3BZ|dCXt;<!xH>|R3LXMxhzHNNP{7}K0d_=kFEEYhjf<i;K_K5S
zBw>8wSw2tYQ!{ksgX=|anB^|+AKY)ejT;Xh9Uko;u*T7Qjl0q`g9Ufp-DB2!{~^11
z+x6k=`_B&n2VSGI|L%%=<ffsnTs<L+j{(c{g&50oC#l*v-rW_{$FzOYU>*ZQCZ{Ar
zhAZg^DzLHi{t;^(9Juet40#L$OiT&_9z)LR1kd>~WPCAgYBW~<MFeWNCPp_GRaI1_
zQVe!t4A{xBU{!UZAPv)F<XasJwm1z{RaGYo(#v6|#(<q31NK5e*o$NE;Udsmv@SSo
zQ9f|kDHsqhJgNM<sy?lVv49VR^1+Bk2g8x01JnJ`=ARg{EmJ=DM82_+VTm`k9~k1n
z(H;3FG&}(u>WEPODb#5w-<U2Ez@cS0V$=&Q$KY=qpM;!@(8UJUY1Kgn<3noIF~K0v
z0$jf764SSgYJhB;!dO;i#Ig{x?J9FUreh1<1bP@U>{S^vJ;>RwhLl=5b?j<rP+#|~
zpjad0j4CPw9JaU+sA{#Kz|4&yFmpgdQGwyGMFr;a7&KfSg9Z*;l!hx~&~Rl88aQlG
z8m^8(!__fp;IKt$xHtiIJULyd4b64L;J&uMcmFYt>zA*{iN)am+(*i>GA!1Ls~0~a
zy~VPhyFAEVJdIU^BC`iPRMjwhSljoyFb{`S*Sh=g=F;xI*I^+$V0%8h$!Fl_PQ$rp
zs1+&HIy-X5FHf<0yZXdXy~$|(^8Zd$qUGYmcja<%>WhDL{rVIvX&WJ|6)#kOI$61{
zO!GJjWWZz)3Lq>ZSeHQ*BQi#1AOYn&A_0j6B+*L=NDKi_EE(7`aAe?$fFc=Sf!h%O
zruetSzb*b9@$ZR$-`aCw6@KJ;yR3oD$UHw<?18!dJM8^tJOnR3a(A2Yl2xYL*$dcv
z4Q!20$JdvztQ6_uQ9F~)&QAyH(oDK(L1#ac+{sVQ7qOh&QD{kg3Sp?2d<y_3Jo)Kx
zE<V1V&ZIL1xspBk+~L!z5y@n2<S-|i4~b;)&cro=ZT}(L>m9gzhp;Y(Qxu138gf}B
zb`ml)q$L976gf>qywQ=Vnp_q;d@o}JKFKOX^H?mlKJwEUIqBpqazr}GV^l!m<9TAH
zd?W{-E#|Q!@I@^pw|rvSo1ZSPe0Inu(3y143Sl_j3-;Ic?>B}k!peRgu3zf~ky>&`
zKiT}_%6?ve!B_)h&Pk|vj=dl=V-Fs}AT<&)-W*HvgRx8G7ti2D(c;}TNgQD16PuH0
z<IJSs%QECtR7QZKeYtdd$*m`cZ^~u(ttgcrT&qv<VSpF6(Vr7REYO*lk&a=MiIGf<
zW@6cNR_2?Xi8<*Q$zUM(Qi?K~j#%l4BO?);XGI!W)5$Z`lIU|9!+nlS8i|i2C2DCn
z6Eo8>Y^IZubi}?Q&>tltbXmj`>CQ%R1*?Rr#83%QiLDYxC9aB?ib56ZD#j`%6<@^w
zqF0=XS+Ogm0>F^UQc+OxR2)_;l_Hg5*c|@qllP{TS>=M*-)`7Z=tQA=;Q>rZ8au%>
z-`Q>;8Q=>dhC>;`fG*;O3_Kb5->k?zb2~aWhllpgcXuAKEwPWzx6ff8oxwgjf4L5k
zp&fO;p)PjRX|kj4+l$A0$A@stPHwNuNb4vb@L-IKPTJXWr`^SPao_ikAG&+~`%NqS
zdPJWS(MJV+B--1z1u2p~xzCS{U_c)x5P=!dVAG#+5^a+?dO~90MI;WWauTW>K@}!W
zkfO@gzY$U8MpQ|S1B$3ZDXJvb2pmAnVVcb;(y`;D)DU`6rn!PV0@I!W&vaBlvr@YO
zN&!luXFy@Yvt$5ubUS`FiI1aa4g+ZgjNv;*3}d;v17fIrpePH!BSWsUfH>$ZAbdrc
z`1Z04`Q#MhFgb-#QKr7#X;QmEv8kK(Ti0&7o=2%iY|Zs7SEHbM&}`Q?Gz%l_P-=r(
z!<~ESk*=HlzPo$G4*H_e_P@069roQI=pQiu_~2k??>@X~9RB)lAM4oEbfO`vhm0mQ
z1v+9NOaL8qVPnN4rp7$W(kQcu=C~-(0>k#rfCj|&$=ojjIxCCLbNzSjAM8Wp=7`w=
z2&upxFgOg#`u_f2xO4v$^swKA0X-p<1fdgZ9<zLnB1_jC%VC;fxR@G_X?RGV!+_q-
zq8Fvz+2bcv4;e3e>+rS1{k{GnoMt@@D=|&LYFjw4C}SFIjA4x$lxi*`hDI><iJ`-0
zlON7GfYs^u{kPq{`vS$m@!kPP1%*4_1I8crkM?<7yyyK(03%&Ka*B1s0p!dHm~Bu`
z3k~FG)U~MwJ6nMk`phvb-?mUlf9;Wu^fd1N;gNfEcuMBPun;eqX_%%%4Go1{di;QC
zE}}#uW@us9S2I9<=U#-|QIb1|NK}7EpwHuFdgLBJsSi%WW*a(S3qso_mhNk=?S{N4
zhUNq|2pdB%PFp6gz_})1!wEK6{KE0#NOFgn2b|qKesESTQi>3-MZn?sC~!0a?9^yL
zUCq-e(vX2X0;iP?D|F`&U?*AGNg9Z#Ox|RogU+p^Q;KXN%8TrHf#J~5)<PCS?S&p7
z^-ZKP$8q`LXUhn1A8^usf9Ju&gZ)QBbk3|k({Xr_4BLZ6SQu&sC^4b&n-<TVXcjYU
zYGFGhy3d;fGO|U=YmH(6&g}!JBN^#KkHc7ifQK$LLfgd}D1C`$_<+<P2KGHRw+L91
zE(a>^P?kwFdiPy-=LmWn&d^hY)X;50-h#pUTh|vRFFm15LLC~q8$uB^YzDeUJp*fQ
zNOg@E26V4345dMMrC3$Z6zfec7VGn-04#6`@m)uA2?!YtJX`aiSJHw2^vVJCFtF{3
zVs$og?WRc`;&?2pe~*WDI9DH^p||zG;GOTeDbq6<%}D&g&>Vr!TX+p*rUE3H3M2!s
z2cvXMb0GEqFp~lOKZZt`LG&|4xKi&K<vYq$1=JlAuPBQCBN0x#_@hf#U^8>}zh+;k
zOkGkcu%$Y6p?Yy<_R?kLM(u?+yX{_Wxzld-+Wn>N)wPuxjMVj7eGbc)we4=ZQ(L`V
z+t}>Y+HbCQd)->SUhB5jdbL}(YIj=QJ3MTytgmi7SF6qabtOu-+*-cVUa9q3OKa^~
zeQSGZZFRZcsK2(k)Y;zX^w(Ek?X-HUn;YHw{0uL7eRZW?TfWokw3d7A&O9*}1j>!=
zwY5bF&|U7VZuL??wY#m(z159Z=S_M7cy*)OYpt!dS2j0BrNGW0#mvIZ+KstRME6!_
zbse&;z23f;B0GB9hqwLP_1fk}>f5Ly@zN|jUweM;D;3}raIgR$fQc)$W#CA!(^}o=
zr7#R$a^xur=LMeH>c&d@%@ll=+FMY%AS&H3WK27R{m$}ge|6=}oYDaVR8_sxUf%9>
zfawtDHOA|wTf4p5>Gl@pq5i+67OekvueH+ZwMN!{QnAQ5DFz#@_4cSLb?~4{BZ=93
zW24;}1v^4u?zYypN98*#g|c`+dcD?LU2lVwt#1v(Y;VE$b`H$U!U9ytR$*}iCXW`k
zgo8o|UIbzL;4EQ_lN1uQ6*{i0t<+!QB5)}x+wINHa=UhSwf#m)Hd7MU?F09ET&jAT
z&{*q>wR-D~)@l!=i$8aH2eJ)Km`B<hzr5Yvmd{(A&E<Bt8-YbJ`RR6RHA>LkUS4ju
zSLAEx2}EV3->tOQ+E7V6^Npp>=Iy1{^6Rg5Hn%rcxTv=~ciWwA@-Z#;-TFeU)t%`=
z`sJSJnwB?PYwhlGd%nB9K3`vkJbLwo#hT9HYH{ICLN2$u?b;i6+R&MBMu7DFQtejE
zfm^kn_#$(wwbuYvueCQ;1{ueobt&!{Dn{m=aI`??32foq<0>kUc??=O??IIp$bA4j
zZvO3+;@NZ2DOjgcDhp&Ci*Lbv6B#d%bpks~^?XW@`9KVk)0-E6^{7t-As!6ONQeFl
z-mJ8jVW3=_M>-eu1wrxc&gS}vroNtZJN4Jr>jDy_z5~+&h&Fid#RdQH*!N*d%>s>2
ziM43OsQJ6chp=+Il@j|CjkzGZq849(SxMg@az4Q!-oWQyJhjXtdlT6ooYLETWOPaY
z)EDD)3Q_V!e3%hcBxhVh^&a&>Ql^C<M8y=HnCylGeL1x(^XCb9FS=D*g87r|)@BxJ
z^}b%8N#4&xW!C1tUvR3Jlt7kk<a7~X`^4zaJ8+m_)?s?oYrhI}Fg}G%%_o82R`<2;
z$O+;wY--eBT78wz&Q{vDTibjRtlvt2XBHYTw0}7o{_^Hpnez0bocpcbDU+{E5<Xz2
z=t<AO6lLbi)BmPUT~V%Fz4qD9ef|qiJ$?O|XMdq~LwOkp`|UFb<25LT<aR%r!JI;p
zsP6fA;7Snz<7sOCllrhQc@=8?Kc*ro&R8IfY(OLHe#BDYjm^&M?atQb=3004Ef`mG
zBw%ZEZH<5GKt~4)hBnNzSGu{-Vv>8O-Rks~V7Zi<{>`79q^?0HS`ZYLLmPZ5lSgFt
zUboj?7c->w_WEY$UcDBH;E+5^z}ua6y9nI!*7n+FOU&Tc+nv?rd9qkLIfIUd()HGx
zr{@{LosB#KgbCT^GM^(C%C;D-veQn+IWC~B+fccq761e<L~Detc4xh{(cb8--IEy<
zOqaI|;XTpJ!sIn*Z+9a}Pc7I|qhorJX6DTCPqcf!tepHTO!a^NjH&)m%3>3KXelXL
z3oI_p`sC-JpucrS$Fjs%i`~xMPPcy>+Qrf--OA`@UmtFJnQrCtK*DbpCt>ZQkucPx
zGZcIQDEO7awGHd4kt@2KvWq%@3cAj(O++Zp=sIQBEXHavxf)E~Ms$_uIZATGtFLaf
zdfS~*OX+z~pqv<`qm@rWW3u)iL8~l&&bm5k&#AE|cYU6$Z8F_>ltI#Rpfr4HdXloJ
zi9ZdMe(wyi6Qw&v++|gb7)2K*uS524pOHNz?<X8T8%?%;G7|g@U<(Uii>l!C=}J_p
z2$nNBgX>x7zy9!y{%d4gDAbFgaXT?upM)9G+?NWJJ`tQk<xikbaG(bG)*^hV9ye!n
zAUXX-#AeYy+yI{b#_3y)0=y6lLF!Xf6&MFd9c=7>_3H7&>=Q}_HkiS3knb?hUA}Vl
ziO(pY0@A^3Jz!Y#T_V&afd(e+j^_K0t$U!N@qBOY251kt22Z%q?LXMLf8Yv3FR87~
z*E1nRO|EB()CGp-QqZbV(6nhTSPy9dwp|8Vt`HP?pe59~9#7(ch31)=8=yz$nzI60
zm${peJJ;LE+_OqEX(y7aSc08S+W<U8G$>rLq=SYo!ZXlh3GH00nG`mU`S?tmaP=AJ
za51w$0qIyF=ygK^+E2=ehHb-kY@ZoUNPR#D%DEKNgle__XotO<UoDs-lL7|UVV0+d
zf#&#Lpiwx(puu?tLj$MBJ~rUgLqGzK0rYdn4?!QC(*B)=q16AE`u|e@U+Vuq75abe
z)2jbJbwHmhX23IB%z~*>Y^rj#m{H4xVuN3`m<8KsuH7tRb#l3wjnQ<mq5o1b<122J
z_s)%_sh2BCMe$DG$$x9~=hvf+{tcaPA&cMakN@(E|MR>5dHsVQPo^FL)k`=2YFY<W
zXJ7(I^{db67Y0VIv2m*x8M*rBVB{JbkxFyTQAVWFTr*=tnl&4V3@Arikb;pbw;>re
za)px>k&)|2bJ8%3ja<Dmjc`qAgv*^-#P+1fE#}!`m?|%!%9EzIa3(cnMoJSS*XSyZ
zCKF~g`9`i_P?HdqWg3{j@*fzv4lIL1GB9#IooT)_a`n9wb*CD+My5T&$Tc?e;YP0V
zSsJ;@XKCarpCcpJ$}3>x`V}yxhmafQKnR98!a>K>KZ3FA1T3Ha;!nUz=X*+ZwW=tW
z6s79_9mp?)d+@&el^iHJP;#K;K*@oU10@Ga4wM}D)Nmkce;==Uf`R?N<AVLa`<U(j
z!=Z%=xBushlk`bIBHaIFmL#4&IE@%e^Z!6BJ*ah#*8jB{*#A%b(}brebMb-BlWSeU
z$VL#Yec3s#ee(}cmTTYm*y+i&uQeo6!^dJj-nDPMUl2t51#k=&9A1vv&xj7i^20Cj
ze!+=DvGEd_4UV9WT960Het~Qi{7_74MLswb%L*QfJ%wk<q1a@<z|)QNet~;plV#w#
zlYOlF1-x%x`1(C@+ys=dBdtXet6Hg_E$#ogv3_ho4W_4QTmRDjUzk`Y1_=dBpcB|(
zdvSioVdUw8*r>li<}qmDyay)z1#%w%kDGsK|6khw^CLT@{XZyRgvmb~b13cqYiWD?
z(*9o@;EjyWBJ<6ZeP3z+4~LnDjD-_R)DcGoO8fu(BMo9Cm+Sv{{T;9W!@>IB#jyVO
zAM^Sj&bjgR5RKgNFrhQ0h-7yFVEF;RAasL)0{~<tiyX*A+yEf`5`puJbM#ptZvgmn
zc>@4<OHM$s2w~;J9}eFD@KSjLKzRc|bb~<=x2)#{GnQ-BV!lnw8vxSRP!!`?c>{pF
z+GBDI$JONx0Fr0?W`W|)-<86*JaDJ-MIE|x*uqZ40XDh;;2+8x0KkzpYmB~<qr3q?
z3V3+~faF7Y1HiC?b*$M-ktx$y85SGb%NqdBxX$a`>!nDBpVS)wp1J&^3E?mfmWdPJ
zeM&4Br~l@u$YI>nrODD^T<l`5bQqWQ-v`@&rNg+=VO#^eoy86d`=!IU(qWwNz9(Ey
zob8S-)&dt$>BgYrDs;iIPJ!G@h4BdQf++)vY<-?^hgLd_D;384z+R~^9ylvb`9Ari
zD~zvxXR34<S2~Q#*TPE2a>bmmMMG)nFfMXUK5#TwI*bF~>7~Os;VFHxbQs4c4E#2L
z#C_Q)Piv*axZ!&fa?P$vhjAm^w-@quRyvH!xuZkKS|JvGM2B(pr>9GYaizn!=zg`*
zVO)7(TzO$!eA^&}E85Bn<H`%;;10u&c41tja^X{YVO;4jPF#8ViFX+Ha-;fjIgESx
zrx%Mkj8p0_|LaVp0+;B4O~j=MX+l5udsnYtpMsPAjZjghFPKlw^6Rj990f99G6)3_
z77?t=Ac_$gqcV_y@*P~F%(EgAkVG#fATi`OO9r+K92vMGphyN-;5Nj+DgG_-Z;O9N
z{Cncxmv_BOkHomZ9q~3ozHU=Jb4R?DcSpQW;X=;L9pagEc78fD1ZN5EZqqU0XoO{0
z;>Pi2Ka<?aPtL4t@^m^fd{aD<7p!}>Zx};pGwFt}kRPNYo|P?T`iAv<?ikJxchdK{
z=P)OIpF6>x30IvGaYK1?_=fT{4Y{mx17?I7PRk-oi9k6;P7`6+I`K$|(yYR{EOtV}
zMI-RVm&oT;sSB6xj-oS4XXK=Fd=ipu)nv+7K;lEV&{&5%hBM_OIr!|*G8~dyK1}n|
zIfjv+F0XucXo6q!OuA?JwYAOU-uNMeR`&C7{aP=G)Ux(<*)B#^_VWU4ci&rgAD)B?
zDYbO!*b6eV<VyRKkcQ)$u5O_uzYYrp6mvbMV~dKSQKF;JC5|Kxu&%&~mHf=otth9W
zGG&6>mR$sd2x_H3<<=8iU`}y{-*Bwz2i8Ad;==&XpwXWbK`hXjn30ZQl!=i{jAmll
zbXMk@oryW=7|CED_)>~8nvPiMh$ABrn`cEDS<}fg)RO3P8pC~#Od5%gBqi=iGBGn9
z!)7`eNk{A}0{u}ULYGB6k?w31SFlQ`N(_|{mDnnARN|_LsVG#ju41fWQt?#`AbQ2A
zm=(K1DgX?rEENS6PsL%yQYlg?Tt~0|vGJw3fy3C?QEcoqCp-tIIcGa$l}>X|+97N9
zm?0L9h77oJIyq+OGM4gX0%s0~U9&<*8aa#|>6+CFzgdYrEqS~9{yT8gG0y=^<kTna
z047V{sor0>L)%m78|exr48IZ47e=mNeg^kBqy02Vj-5$f82fKZIjRw^W98vbFLZq}
zE1z}j>hUw&f==z|y%&Px+US{hhL56W7!I5S2KxaBr1F8Hya@hbdB{(6LI@{1r3=|_
z|E&zU=`OgG1=C&OQugBZp9+_<vy0ysE@fx`<&JPEJNuyu>0eQ1fAaSt6w_OX!}J#7
z;5zCj0AKz}4wM`yIq=EhfE<;Q^Y`&61~0;0cI3a!4w@M57Q#BkT&aBCznKU>8uHdQ
z$^jsi-9C2Fz{eOGcxp!|?E#Pk!FkfkJpdXLU*kP}Rgm03dgSWwJZCX~7LCHdemPB$
ze&Pmx5e8oDf`N~O*iRf`#T+IKPhJ39s@{+G{U&#wkRE__tj80Wa)MP(u*R5RK~MMM
zlPtLF?jE!857SS;J|X-b!&yF+&-xxm#^w3{^89~V(D|AE=}N%^rT|->{|}6+?b*!H
z9ZNifhG+7JP)CHy2O7#Ze5+2p;d_Mg0akhNAa^ONcC;&1br9Tz2fM1(c=x;Nn=UbZ
z%cuqjZp^cNT4iv19)hbBtMN`*l?8ejGVE0uGd&A#TdBtTaMgGZvslHJ=l{#||LIPl
zJpa!}-}G;+A->45@Ub#1){4vX|K<7r&i=bxRg!7UPoxDodH(-#{(orwovZ^<YW>dw
P3nMzXI_?}7)-(SHgzsox

diff --git a/base/build.gradle b/base/build.gradle
index 9114197..082e39e 100644
--- a/base/build.gradle
+++ b/base/build.gradle
@@ -13,6 +13,7 @@ dependencies {
 
     implementation 'org.springframework.ai:spring-ai-client-chat'
     implementation 'org.springframework.ai:spring-ai-starter-mcp-client'
+    implementation 'org.springframework.ai:spring-ai-openai'
 
     implementation 'org.springaicommunity:spring-ai-agent-utils:0.6.0-SNAPSHOT'
 
diff --git a/base/src/main/java/ai/javaclaw/JavaClawConfiguration.java b/base/src/main/java/ai/javaclaw/JavaClawConfiguration.java
index f818d3e..521c789 100644
--- a/base/src/main/java/ai/javaclaw/JavaClawConfiguration.java
+++ b/base/src/main/java/ai/javaclaw/JavaClawConfiguration.java
@@ -1,19 +1,7 @@
 package ai.javaclaw;
 
-import ai.javaclaw.configuration.ConfigurationManager;
 import ai.javaclaw.tasks.TaskManager;
-import ai.javaclaw.tools.AgentEnvironment;
-import ai.javaclaw.tools.AutoDiscoveredTool;
-import ai.javaclaw.tools.CheckListTool;
-import ai.javaclaw.tools.McpTool;
 import ai.javaclaw.tools.TaskTool;
-import org.springaicommunity.agent.tools.FileSystemTools;
-import org.springaicommunity.agent.tools.SkillsTool;
-import org.springaicommunity.agent.tools.SmartWebFetchTool;
-import org.springframework.ai.chat.client.ChatClient;
-import org.springframework.ai.chat.client.advisor.MessageChatMemoryAdvisor;
-import org.springframework.ai.chat.client.advisor.SimpleLoggerAdvisor;
-import org.springframework.ai.chat.client.advisor.ToolCallAdvisor;
 import org.springframework.ai.chat.memory.ChatMemory;
 import org.springframework.ai.chat.memory.ChatMemoryRepository;
 import org.springframework.ai.chat.memory.MessageWindowChatMemory;
@@ -21,27 +9,19 @@
 import org.springframework.ai.chat.model.ChatModel;
 import org.springframework.ai.chat.model.ChatResponse;
 import org.springframework.ai.chat.model.Generation;
-import org.springframework.ai.mcp.SyncMcpToolCallbackProvider;
 import org.springframework.ai.model.SpringAIModelProperties;
-import org.springframework.beans.factory.ObjectProvider;
-import org.springframework.beans.factory.annotation.Value;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
-import org.springframework.context.annotation.DependsOn;
-import org.springframework.core.io.Resource;
 
-import java.io.IOException;
-import java.nio.charset.StandardCharsets;
-import java.nio.file.Files;
-import java.nio.file.Path;
 import java.util.List;
-import java.util.Set;
 
 @Configuration
 public class JavaClawConfiguration {
 
-    public static final String AGENT_MD = "AGENT.private.md";
+    public static final String AGENT_MD = "AGENT.md";
+    public static final String AGENT_PRIVATE_MD = "AGENT.private.md";
+    public static final String INFO_MD = "INFO.md";
 
     @Bean
     @ConditionalOnProperty(name = SpringAIModelProperties.CHAT_MODEL, havingValue = "unknown", matchIfMissing = true)
@@ -58,58 +38,4 @@ public ChatMemory chatMemory(ChatMemoryRepository chatMemoryRepository) {
     public TaskTool taskTool(TaskManager taskManager) {
         return TaskTool.builder().taskManager(taskManager).build();
     }
-
-    @Bean
-    public ChatClient.Builder chatClientBuilder(ObjectProvider<ChatModel> chatModelProvider) {
-        ChatModel chatModel = chatModelProvider.getIfUnique(() -> prompt -> new ChatResponse(List.of(new Generation(new AssistantMessage("No AI model has been configured. If you did configure a model recently, restart JavaClaw manually for the changes to take effect.")))));
-        return ChatClient.builder(chatModel);
-    }
-
-    @Bean
-    @DependsOn({"mcpHeaderCustomizer"})
-    public ChatClient chatClient(ChatClient.Builder chatClientBuilder,
-                                 ChatMemory chatMemory,
-                                 SyncMcpToolCallbackProvider mcpToolProvider,
-                                 TaskManager taskManager,
-                                 ConfigurationManager configurationManager,
-                                 @Value("${agent.workspace:Unknown}") Resource workspace,
-                                 Set<AutoDiscoveredTool<?>> autoDiscoveredTools
-    ) throws IOException {
-
-        Resource agentMd = workspace.createRelative(AGENT_MD);
-        if (!agentMd.exists()) {
-            agentMd = workspace.createRelative("AGENT.md");
-        }
-        String agentPrompt = agentMd.getContentAsString(StandardCharsets.UTF_8) + System.lineSeparator()
-                + workspace.createRelative("INFO.md").getContentAsString(StandardCharsets.UTF_8) + System.lineSeparator();
-
-        chatClientBuilder
-                .defaultAdvisors(new SimpleLoggerAdvisor())
-                .defaultSystem(p -> p.text(agentPrompt).param(AgentEnvironment.ENVIRONMENT_INFO_KEY, AgentEnvironment.info()))
-                .defaultToolCallbacks(mcpToolProvider.getToolCallbacks())
-                .defaultToolCallbacks(SkillsTool.builder().addSkillsDirectory(skillsDir(workspace).toString()).build())
-                .defaultTools(
-                        TaskTool.builder().taskManager(taskManager).build(),
-                        CheckListTool.builder().build(),
-                        McpTool.builder().configurationManager(configurationManager).build(),
-                        //Bash execution tool
-                        //ShellTools.builder().build(),// built-in shell tools
-                        // Read, Write and Edit files tool
-                        FileSystemTools.builder().build(),// built-in file system tools
-                        // Smart web fetch tool
-                        SmartWebFetchTool.builder(chatClientBuilder.clone().build()).build())
-                .defaultAdvisors(
-                        ToolCallAdvisor.builder().build(),
-                        MessageChatMemoryAdvisor.builder(chatMemory).build()
-                );
-
-        autoDiscoveredTools.forEach(autoDiscoveredTool -> chatClientBuilder.defaultTools(autoDiscoveredTool.tool()));
-        return chatClientBuilder.build();
-    }
-
-    private static Path skillsDir(Resource workspace) throws IOException {
-        Path skillsDir = workspace.getFilePath().resolve("skills");
-        Files.createDirectories(skillsDir);
-        return skillsDir;
-    }
 }
diff --git a/base/src/main/java/ai/javaclaw/agent/Agent.java b/base/src/main/java/ai/javaclaw/agent/Agent.java
index c01efa2..ef37f51 100644
--- a/base/src/main/java/ai/javaclaw/agent/Agent.java
+++ b/base/src/main/java/ai/javaclaw/agent/Agent.java
@@ -2,8 +2,16 @@
 
 public interface Agent {
 
-    String respondTo(String conversationId, String question);
+    default String respondTo(String conversationId, String question) {
+        return respondTo(null, conversationId, question);
+    }
 
-    <T> T prompt(String conversationId, String input, Class<T> result);
+    String respondTo(String agentId, String conversationId, String question);
+
+    default <T> T prompt(String conversationId, String input, Class<T> result) {
+        return prompt(null, conversationId, input, result);
+    }
+
+    <T> T prompt(String agentId, String conversationId, String input, Class<T> result);
 
 }
diff --git a/base/src/main/java/ai/javaclaw/agent/DefaultAgent.java b/base/src/main/java/ai/javaclaw/agent/DefaultAgent.java
index abb5010..b81322b 100644
--- a/base/src/main/java/ai/javaclaw/agent/DefaultAgent.java
+++ b/base/src/main/java/ai/javaclaw/agent/DefaultAgent.java
@@ -1,33 +1,69 @@
 package ai.javaclaw.agent;
 
+import ai.javaclaw.agents.AgentChatClientFactory;
+import ai.javaclaw.agents.AgentConversationId;
+import ai.javaclaw.agents.AgentRegistry;
 import org.springframework.ai.chat.client.ChatClient;
 import org.springframework.ai.chat.memory.ChatMemory;
+import org.springframework.ai.chat.model.ChatModel;
+import org.springframework.beans.factory.ObjectProvider;
 import org.springframework.stereotype.Component;
 
 @Component
 public class DefaultAgent implements Agent {
 
-    private final ChatClient chatClient;
+    private final AgentRegistry agentRegistry;
+    private final AgentChatClientFactory chatClientFactory;
+    private final ObjectProvider<ChatModel> fallbackChatModelProvider;
 
-    public DefaultAgent(ChatClient chatClient) {
-        this.chatClient = chatClient;
+    public DefaultAgent(AgentRegistry agentRegistry, AgentChatClientFactory chatClientFactory, ObjectProvider<ChatModel> fallbackChatModelProvider) {
+        this.agentRegistry = agentRegistry;
+        this.chatClientFactory = chatClientFactory;
+        this.fallbackChatModelProvider = fallbackChatModelProvider;
     }
 
     @Override
-    public String respondTo(String conversationId, String question) {
-        return chatClient
+    public String respondTo(String agentId, String conversationId, String question) {
+        return resolveAgent(agentId)
+                .map(configuredAgent -> chatClient(configuredAgent)
                 .prompt(question)
-                .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, conversationId))
+                .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, AgentConversationId.scoped(configuredAgent.id(), conversationId)))
                 .call()
-                .content();
+                .content())
+                .orElseGet(() -> fallbackChatClient()
+                        .prompt(question)
+                        .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, conversationId))
+                        .call()
+                        .content());
     }
 
     @Override
-    public <T> T prompt(String conversationId, String input, Class<T> result) {
-        return chatClient
+    public <T> T prompt(String agentId, String conversationId, String input, Class<T> result) {
+        return resolveAgent(agentId)
+                .map(configuredAgent -> chatClient(configuredAgent)
                 .prompt(input)
-                .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, conversationId))
+                .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, AgentConversationId.scoped(configuredAgent.id(), conversationId)))
                 .call()
-                .entity(result);
+                .entity(result))
+                .orElseGet(() -> fallbackChatClient()
+                        .prompt(input)
+                        .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, conversationId))
+                        .call()
+                        .entity(result));
+    }
+
+    private ChatClient chatClient(ai.javaclaw.agents.ConfiguredAgent configuredAgent) {
+        return chatClientFactory.getClient(configuredAgent);
+    }
+
+    private java.util.Optional<ai.javaclaw.agents.ConfiguredAgent> resolveAgent(String agentId) {
+        return agentRegistry.findAgent(agentId)
+                .or(() -> agentRegistry.getDefaultAgent());
+    }
+
+    private ChatClient fallbackChatClient() {
+        return chatClientFactory.createClient(
+                fallbackChatModelProvider.getIfUnique(chatClientFactory::noModelConfiguredChatModel)
+        );
     }
 }
diff --git a/base/src/main/java/ai/javaclaw/agent/memory/FileSystemChatMemoryRepository.java b/base/src/main/java/ai/javaclaw/agent/memory/FileSystemChatMemoryRepository.java
index 9da13f8..6446548 100644
--- a/base/src/main/java/ai/javaclaw/agent/memory/FileSystemChatMemoryRepository.java
+++ b/base/src/main/java/ai/javaclaw/agent/memory/FileSystemChatMemoryRepository.java
@@ -1,11 +1,13 @@
 package ai.javaclaw.agent.memory;
 
+import ai.javaclaw.agents.AgentRegistry;
+import ai.javaclaw.agents.AgentConversationId;
+import ai.javaclaw.agents.AgentWorkspaceResolver;
 import ai.javaclaw.files.YamlDocument;
 import ai.javaclaw.files.YamlParser;
 import org.springframework.ai.chat.memory.AppendableChatMemoryRepository;
 import org.springframework.ai.chat.messages.Message;
-import org.springframework.beans.factory.annotation.Value;
-import org.springframework.core.io.Resource;
+import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.stereotype.Component;
 
 import java.io.IOException;
@@ -16,14 +18,15 @@
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.ArrayList;
 import java.util.stream.Stream;
 
 /**
- * Persists chat conversation history as YAML files inside the agent workspace.
+ * Persists chat conversation history as YAML files inside the active agent workspace.
  *
  * <p>The conversation ID is the channel name, e.g. {@code web} or
  * {@code telegram-123456789}. The repository maps this to a flat file:
- * {@code {workspace}/conversations/chat-{channel}.yaml}
+ * {@code {workspace}/agents/{agentId}/conversations/chat-{channel}.yaml}
  *
  * <p>Each file has a frontmatter block with timestamps and a body containing the
  * message list:
@@ -41,21 +44,47 @@
 @Component
 public class FileSystemChatMemoryRepository implements AppendableChatMemoryRepository {
 
-    private final Path conversationsDir;
+    private final AgentRegistry agentRegistry;
+    private final AgentWorkspaceResolver agentWorkspaceResolver;
+    private final Path testWorkspacePath;
 
-    public FileSystemChatMemoryRepository(@Value("${agent.workspace:Unknown}") Resource workspaceDir) throws IOException {
-        this.conversationsDir = workspaceDir.getFilePath().resolve("conversations");
+    @Autowired
+    public FileSystemChatMemoryRepository(AgentRegistry agentRegistry, AgentWorkspaceResolver agentWorkspaceResolver) {
+        this.agentRegistry = agentRegistry;
+        this.agentWorkspaceResolver = agentWorkspaceResolver;
+        this.testWorkspacePath = null;
+    }
+
+    FileSystemChatMemoryRepository(Path testWorkspacePath) {
+        this.agentRegistry = null;
+        this.agentWorkspaceResolver = null;
+        this.testWorkspacePath = testWorkspacePath;
     }
 
     @Override
     public List<String> findConversationIds() {
+        if (testWorkspacePath != null) {
+            return listConversationIds(testWorkspacePath.resolve("conversations"));
+        }
+
+        List<String> conversationIds = new ArrayList<>();
+        agentRegistry.getAgents().forEach(configuredAgent -> {
+            Path agentWorkspacePath = agentWorkspaceResolver.resolveWorkspacePath(configuredAgent.workspacePath(), configuredAgent.id());
+            listConversationIds(agentWorkspacePath.resolve("conversations")).stream()
+                    .map(conversationId -> AgentConversationId.scoped(configuredAgent.id(), conversationId))
+                    .forEach(conversationIds::add);
+        });
+        return conversationIds;
+    }
+
+    private List<String> listConversationIds(Path conversationsDir) {
         if (!Files.exists(conversationsDir)) return List.of();
         try (Stream<Path> files = Files.list(conversationsDir)) {
             return files
-                    .map(p -> p.getFileName().toString())
-                    .filter(name -> name.startsWith("chat-") && name.endsWith(".yaml"))
-                    .map(name -> name.substring("chat-".length(), name.length() - ".yaml".length()))
-                    .toList();
+                .map(p -> p.getFileName().toString())
+                .filter(name -> name.startsWith("chat-") && name.endsWith(".yaml"))
+                .map(name -> name.substring("chat-".length(), name.length() - ".yaml".length()))
+                .toList();
         } catch (IOException e) {
             throw new RuntimeException("Failed to list conversations", e);
         }
@@ -121,7 +150,26 @@ public void deleteByConversationId(String conversationId) {
      * {@code conversations/chat-{channel}.yaml}.
      */
     private Path resolveFile(String conversationId) {
-        return conversationsDir.resolve("chat-" + conversationId + ".yaml");
+        Path conversationsDir = conversationsDirFor(conversationId);
+        String rawConversationId = AgentConversationId.rawConversationId(conversationId);
+        return conversationsDir.resolve("chat-" + rawConversationId + ".yaml");
+    }
+
+    private Path conversationsDirFor(String conversationId) {
+        if (testWorkspacePath != null) {
+            return testWorkspacePath.resolve("conversations");
+        }
+
+        String scopedAgentId = AgentConversationId.agentId(conversationId);
+        try {
+            Path workspacePath = agentRegistry.findAgent(scopedAgentId)
+                    .or(() -> agentRegistry.getDefaultAgent())
+                    .map(configuredAgent -> agentWorkspaceResolver.resolveWorkspacePath(configuredAgent.workspacePath(), configuredAgent.id()))
+                    .orElseGet(agentWorkspaceResolver::rootWorkspacePath);
+            return agentWorkspaceResolver.initializeWorkspace(workspacePath).resolve("conversations");
+        } catch (IOException e) {
+            throw new RuntimeException("Failed to resolve active agent conversations directory", e);
+        }
     }
 
     private static Path ensureDirectory(Path dir) {
diff --git a/base/src/main/java/ai/javaclaw/agents/AgentChatClientFactory.java b/base/src/main/java/ai/javaclaw/agents/AgentChatClientFactory.java
new file mode 100644
index 0000000..b8f3e77
--- /dev/null
+++ b/base/src/main/java/ai/javaclaw/agents/AgentChatClientFactory.java
@@ -0,0 +1,214 @@
+package ai.javaclaw.agents;
+
+import ai.javaclaw.configuration.ConfigurationChangedEvent;
+import ai.javaclaw.configuration.ConfigurationManager;
+import ai.javaclaw.tasks.TaskManager;
+import ai.javaclaw.tools.AgentEnvironment;
+import ai.javaclaw.tools.AutoDiscoveredTool;
+import ai.javaclaw.tools.CheckListTool;
+import ai.javaclaw.tools.McpTool;
+import ai.javaclaw.tools.TaskTool;
+import io.micrometer.observation.ObservationRegistry;
+import org.springaicommunity.agent.tools.FileSystemTools;
+import org.springaicommunity.agent.tools.SkillsTool;
+import org.springaicommunity.agent.tools.SmartWebFetchTool;
+import org.springframework.ai.chat.client.ChatClient;
+import org.springframework.ai.chat.client.advisor.MessageChatMemoryAdvisor;
+import org.springframework.ai.chat.client.advisor.SimpleLoggerAdvisor;
+import org.springframework.ai.chat.client.advisor.ToolCallAdvisor;
+import org.springframework.ai.chat.memory.ChatMemory;
+import org.springframework.ai.chat.messages.AssistantMessage;
+import org.springframework.ai.chat.model.ChatModel;
+import org.springframework.ai.chat.model.ChatResponse;
+import org.springframework.ai.chat.model.Generation;
+import org.springframework.ai.mcp.SyncMcpToolCallbackProvider;
+import org.springframework.ai.model.tool.DefaultToolExecutionEligibilityPredicate;
+import org.springframework.ai.model.tool.ToolCallingManager;
+import org.springframework.ai.model.tool.ToolExecutionEligibilityPredicate;
+import org.springframework.ai.openai.OpenAiChatModel;
+import org.springframework.ai.openai.OpenAiChatOptions;
+import org.springframework.ai.openai.api.OpenAiApi;
+import org.springframework.beans.factory.ObjectProvider;
+import org.springframework.context.event.EventListener;
+import org.springframework.core.io.Resource;
+import org.springframework.core.retry.RetryTemplate;
+import org.springframework.stereotype.Component;
+import org.springframework.web.client.RestClient;
+import org.springframework.web.reactive.function.client.WebClient;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ConcurrentMap;
+
+@Component
+public class AgentChatClientFactory {
+
+    private static final String NO_MODEL_MESSAGE = "No AI model has been configured. If you did configure a model recently, restart JavaClaw manually for the changes to take effect.";
+
+    private final ChatMemory chatMemory;
+    private final SyncMcpToolCallbackProvider mcpToolProvider;
+    private final TaskManager taskManager;
+    private final ConfigurationManager configurationManager;
+    private final AgentWorkspaceResolver agentWorkspaceResolver;
+    private final Set<AutoDiscoveredTool<?>> autoDiscoveredTools;
+    private final ToolCallingManager toolCallingManager;
+    private final ObservationRegistry observationRegistry;
+    private final ToolExecutionEligibilityPredicate toolExecutionEligibilityPredicate;
+    private final RetryTemplate retryTemplate;
+    private final RestClient.Builder restClientBuilder;
+    private final WebClient.Builder webClientBuilder;
+    private final ConcurrentMap<String, ChatClient> cachedClients = new ConcurrentHashMap<>();
+
+    public AgentChatClientFactory(ChatMemory chatMemory,
+                                  SyncMcpToolCallbackProvider mcpToolProvider,
+                                  TaskManager taskManager,
+                                  ConfigurationManager configurationManager,
+                                  AgentWorkspaceResolver agentWorkspaceResolver,
+                                  Set<AutoDiscoveredTool<?>> autoDiscoveredTools,
+                                  ToolCallingManager toolCallingManager,
+                                  ObjectProvider<ObservationRegistry> observationRegistry,
+                                  ObjectProvider<ToolExecutionEligibilityPredicate> toolExecutionEligibilityPredicate,
+                                  ObjectProvider<RetryTemplate> retryTemplate,
+                                  ObjectProvider<RestClient.Builder> restClientBuilder,
+                                  ObjectProvider<WebClient.Builder> webClientBuilder) {
+        this.chatMemory = chatMemory;
+        this.mcpToolProvider = mcpToolProvider;
+        this.taskManager = taskManager;
+        this.configurationManager = configurationManager;
+        this.agentWorkspaceResolver = agentWorkspaceResolver;
+        this.autoDiscoveredTools = autoDiscoveredTools;
+        this.toolCallingManager = toolCallingManager;
+        this.observationRegistry = observationRegistry.getIfUnique(() -> ObservationRegistry.NOOP);
+        this.toolExecutionEligibilityPredicate = toolExecutionEligibilityPredicate.getIfUnique(DefaultToolExecutionEligibilityPredicate::new);
+        this.retryTemplate = retryTemplate.getIfUnique(RetryTemplate::new);
+        this.restClientBuilder = restClientBuilder.getIfAvailable(RestClient::builder);
+        this.webClientBuilder = webClientBuilder.getIfAvailable(WebClient::builder);
+    }
+
+    public ChatClient getClient(ConfiguredAgent configuredAgent) {
+        return cachedClients.computeIfAbsent(configuredAgent.id(), ignored -> createRuntimeClient(configuredAgent));
+    }
+
+    public ChatClient createClient(ChatModel chatModel) {
+        return createClient(chatModel, agentWorkspaceResolver.rootWorkspace());
+    }
+
+    private ChatClient createClient(ChatModel chatModel, Resource workspace) {
+        ChatClient.Builder builder = ChatClient.builder(chatModel);
+        configure(builder, chatModel, workspace);
+        return builder.build();
+    }
+
+    public ChatModel noModelConfiguredChatModel() {
+        return _ -> new ChatResponse(List.of(new Generation(new AssistantMessage(NO_MODEL_MESSAGE))));
+    }
+
+    @EventListener
+    public void onConfigurationChanged(ConfigurationChangedEvent ignored) {
+        cachedClients.clear();
+    }
+
+    private ChatClient createRuntimeClient(ConfiguredAgent configuredAgent) {
+        if (!configuredAgent.isOpenAiCompatible()) {
+            return createClient(noModelConfiguredChatModel());
+        }
+
+        OpenAiApi.Builder openAiApiBuilder = OpenAiApi.builder()
+                .apiKey(configuredAgent.apiKey())
+                .restClientBuilder(restClientBuilder.clone())
+                .webClientBuilder(webClientBuilder.clone());
+        if (!configuredAgent.baseUrl().isBlank()) {
+            openAiApiBuilder.baseUrl(configuredAgent.baseUrl());
+        }
+        OpenAiApi openAiApi = openAiApiBuilder.build();
+
+        OpenAiChatOptions options = OpenAiChatOptions.builder()
+                .model(configuredAgent.model())
+                .build();
+
+        OpenAiChatModel chatModel = OpenAiChatModel.builder()
+                .openAiApi(openAiApi)
+                .defaultOptions(options)
+                .toolCallingManager(toolCallingManager)
+                .toolExecutionEligibilityPredicate(toolExecutionEligibilityPredicate)
+                .retryTemplate(retryTemplate)
+                .observationRegistry(observationRegistry)
+                .build();
+
+        return createClient(chatModel, resolveWorkspace(configuredAgent));
+    }
+
+    private void configure(ChatClient.Builder builder, ChatModel chatModel, Resource workspace) {
+        String agentPrompt;
+        String skillsDirectory;
+        try {
+            agentPrompt = loadAgentPrompt(workspace);
+            skillsDirectory = skillsDir(workspace).toString();
+        } catch (IOException e) {
+            throw new IllegalStateException("Failed to load agent prompt", e);
+        }
+
+        builder.defaultAdvisors(new SimpleLoggerAdvisor())
+                .defaultSystem(p -> p.text(agentPrompt).param(AgentEnvironment.ENVIRONMENT_INFO_KEY, AgentEnvironment.info()))
+                .defaultToolCallbacks(mcpToolProvider.getToolCallbacks())
+                .defaultTools(
+                        TaskTool.builder().taskManager(taskManager).build(),
+                        CheckListTool.builder().build(),
+                        McpTool.builder().configurationManager(configurationManager).build(),
+                        FileSystemTools.builder().build(),
+                        SmartWebFetchTool.builder(ChatClient.builder(chatModel).build()).build())
+                .defaultAdvisors(
+                        ToolCallAdvisor.builder().build(),
+                        MessageChatMemoryAdvisor.builder(chatMemory).build()
+                );
+
+        if (hasSkillsDirectoryContent(Path.of(skillsDirectory))) {
+            builder.defaultToolCallbacks(SkillsTool.builder().addSkillsDirectory(skillsDirectory).build());
+        }
+
+        autoDiscoveredTools.forEach(autoDiscoveredTool -> builder.defaultTools(autoDiscoveredTool.tool()));
+    }
+
+    private String loadAgentPrompt(Resource workspace) throws IOException {
+        Resource agentMd = workspace.createRelative(ai.javaclaw.JavaClawConfiguration.AGENT_PRIVATE_MD);
+        if (!agentMd.exists()) {
+            agentMd = workspace.createRelative(ai.javaclaw.JavaClawConfiguration.AGENT_MD);
+        }
+        return agentMd.getContentAsString(StandardCharsets.UTF_8)
+                + System.lineSeparator()
+                + workspace.createRelative(ai.javaclaw.JavaClawConfiguration.INFO_MD).getContentAsString(StandardCharsets.UTF_8)
+                + System.lineSeparator();
+    }
+
+    private Resource resolveWorkspace(ConfiguredAgent configuredAgent) {
+        try {
+            Path workspacePath = agentWorkspaceResolver.initializeWorkspace(
+                    agentWorkspaceResolver.resolveWorkspacePath(configuredAgent.workspacePath(), configuredAgent.id())
+            );
+            return agentWorkspaceResolver.asResource(workspacePath);
+        } catch (IOException e) {
+            throw new IllegalStateException("Failed to initialize workspace for agent " + configuredAgent.id(), e);
+        }
+    }
+
+    private static Path skillsDir(Resource workspace) throws IOException {
+        Path skillsDir = workspace.getFilePath().resolve("skills");
+        Files.createDirectories(skillsDir);
+        return skillsDir;
+    }
+
+    private static boolean hasSkillsDirectoryContent(Path skillsDir) {
+        try (var paths = Files.walk(skillsDir)) {
+            return paths
+                    .filter(Files::isRegularFile)
+                    .anyMatch(path -> path.getFileName().toString().equals("SKILL.md"));
+        } catch (IOException e) {
+            return false;
+        }
+    }
+}
diff --git a/base/src/main/java/ai/javaclaw/agents/AgentConversationId.java b/base/src/main/java/ai/javaclaw/agents/AgentConversationId.java
new file mode 100644
index 0000000..4233f85
--- /dev/null
+++ b/base/src/main/java/ai/javaclaw/agents/AgentConversationId.java
@@ -0,0 +1,34 @@
+package ai.javaclaw.agents;
+
+public final class AgentConversationId {
+
+    private static final String SEPARATOR = "::";
+
+    private AgentConversationId() {
+    }
+
+    public static String scoped(String agentId, String conversationId) {
+        if (agentId == null || agentId.isBlank()) {
+            return conversationId;
+        }
+        return agentId + SEPARATOR + conversationId;
+    }
+
+    public static boolean isScoped(String conversationId) {
+        return conversationId != null && conversationId.contains(SEPARATOR);
+    }
+
+    public static String agentId(String conversationId) {
+        if (!isScoped(conversationId)) {
+            return null;
+        }
+        return conversationId.substring(0, conversationId.indexOf(SEPARATOR));
+    }
+
+    public static String rawConversationId(String conversationId) {
+        if (!isScoped(conversationId)) {
+            return conversationId;
+        }
+        return conversationId.substring(conversationId.indexOf(SEPARATOR) + SEPARATOR.length());
+    }
+}
diff --git a/base/src/main/java/ai/javaclaw/agents/AgentRegistry.java b/base/src/main/java/ai/javaclaw/agents/AgentRegistry.java
new file mode 100644
index 0000000..c07d51a
--- /dev/null
+++ b/base/src/main/java/ai/javaclaw/agents/AgentRegistry.java
@@ -0,0 +1,134 @@
+package ai.javaclaw.agents;
+
+import ai.javaclaw.configuration.ConfigurationChangedEvent;
+import ai.javaclaw.configuration.ConfigurationManager;
+import org.springframework.context.event.EventListener;
+import org.springframework.stereotype.Component;
+
+import java.io.IOException;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+@Component
+public class AgentRegistry {
+
+    public static final String DEFAULT_AGENT_ID = "default";
+
+    private volatile String defaultAgentId = DEFAULT_AGENT_ID;
+    private volatile Map<String, ConfiguredAgent> agents = Map.of();
+
+    public AgentRegistry(ConfigurationManager configurationManager) throws IOException {
+        reload(configurationManager.readApplicationYaml());
+    }
+
+    public Optional<ConfiguredAgent> getDefaultAgent() {
+        ConfiguredAgent configuredAgent = agents.get(defaultAgentId);
+        if (configuredAgent != null) {
+            return Optional.of(configuredAgent);
+        }
+        return agents.values().stream().findFirst();
+    }
+
+    public Optional<ConfiguredAgent> findAgent(String agentId) {
+        if (agentId == null || agentId.isBlank()) {
+            return Optional.empty();
+        }
+        return Optional.ofNullable(agents.get(agentId));
+    }
+
+    public List<ConfiguredAgent> getAgents() {
+        return List.copyOf(agents.values());
+    }
+
+    public String getDefaultAgentId() {
+        return defaultAgentId;
+    }
+
+    @EventListener
+    public void onConfigurationChanged(ConfigurationChangedEvent event) {
+        reload(event.allConfig());
+    }
+
+    @SuppressWarnings("unchecked")
+    private void reload(Map<String, Object> config) {
+        Object agentSection = config.get("agent");
+        if (!(agentSection instanceof Map<?, ?> agentMap)) {
+            clear();
+            return;
+        }
+
+        Object agentsSection = ((Map<String, Object>) agentMap).get("agents");
+        if (!(agentsSection instanceof Map<?, ?> agentsMap)) {
+            clear();
+            return;
+        }
+
+        Map<String, Object> agentsConfig = (Map<String, Object>) agentsMap;
+        String configuredDefaultAgentId = stringValue(agentsConfig.get("default"), "");
+
+        Object itemsSection = agentsConfig.get("items");
+        Map<String, Object> itemsConfig;
+        if (itemsSection instanceof Map<?, ?> itemsMap) {
+            itemsConfig = (Map<String, Object>) itemsMap;
+        } else {
+            itemsConfig = Map.of();
+        }
+
+        Map<String, ConfiguredAgent> loadedAgents = new LinkedHashMap<>();
+        itemsConfig.forEach((id, value) -> {
+            if (!(value instanceof Map<?, ?> rawAgentProperties)) {
+                return;
+            }
+
+            Map<String, Object> agentProperties = (Map<String, Object>) rawAgentProperties;
+            if (!booleanValue(agentProperties.get("enabled"), true)) {
+                return;
+            }
+
+            String provider = stringValue(agentProperties.get("provider"), "");
+            String model = stringValue(agentProperties.get("model"), "");
+            String apiKey = stringValue(agentProperties.get("api-key"), "");
+            String baseUrl = stringValue(agentProperties.get("base-url"), "");
+            String workspacePath = stringValue(agentProperties.get("workspace"), "");
+            if (provider.isBlank() || model.isBlank()) {
+                return;
+            }
+            loadedAgents.put(id, new ConfiguredAgent(id, provider, model, apiKey, baseUrl, workspacePath));
+        });
+
+        agents = Map.copyOf(loadedAgents);
+        defaultAgentId = resolveDefaultAgentId(configuredDefaultAgentId, loadedAgents);
+    }
+
+    private void clear() {
+        defaultAgentId = DEFAULT_AGENT_ID;
+        agents = Map.of();
+    }
+
+    private String resolveDefaultAgentId(String configuredDefaultAgentId, Map<String, ConfiguredAgent> loadedAgents) {
+        if (!configuredDefaultAgentId.isBlank() && loadedAgents.containsKey(configuredDefaultAgentId)) {
+            return configuredDefaultAgentId;
+        }
+        return loadedAgents.keySet().stream().findFirst().orElse(DEFAULT_AGENT_ID);
+    }
+
+    private static String stringValue(Object value, String defaultValue) {
+        if (value == null) {
+            return defaultValue;
+        }
+        String stringValue = value.toString().trim();
+        return stringValue.isBlank() ? defaultValue : stringValue;
+    }
+
+    private static boolean booleanValue(Object value, boolean defaultValue) {
+        if (value == null) {
+            return defaultValue;
+        }
+        if (value instanceof Boolean booleanValue) {
+            return booleanValue;
+        }
+        return Boolean.parseBoolean(value.toString());
+    }
+}
diff --git a/base/src/main/java/ai/javaclaw/agents/AgentWorkspaceResolver.java b/base/src/main/java/ai/javaclaw/agents/AgentWorkspaceResolver.java
new file mode 100644
index 0000000..130d4b9
--- /dev/null
+++ b/base/src/main/java/ai/javaclaw/agents/AgentWorkspaceResolver.java
@@ -0,0 +1,91 @@
+package ai.javaclaw.agents;
+
+import org.springframework.core.env.Environment;
+import org.springframework.core.io.Resource;
+import org.springframework.core.io.ResourceLoader;
+import org.springframework.stereotype.Component;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.stream.Stream;
+
+import static ai.javaclaw.JavaClawConfiguration.AGENT_MD;
+import static ai.javaclaw.JavaClawConfiguration.AGENT_PRIVATE_MD;
+import static ai.javaclaw.JavaClawConfiguration.INFO_MD;
+
+@Component
+public class AgentWorkspaceResolver {
+
+    private final ResourceLoader resourceLoader;
+    private final Path rootWorkspacePath;
+
+    public AgentWorkspaceResolver(ResourceLoader resourceLoader, Environment environment) {
+        this.resourceLoader = resourceLoader;
+        try {
+            this.rootWorkspacePath = resourceLoader.getResource(environment.getProperty("agent.workspace", "file:./workspace/")).getFilePath();
+        } catch (IOException e) {
+            throw new IllegalStateException("Failed to resolve root workspace path", e);
+        }
+    }
+
+    public Path rootWorkspacePath() {
+        return rootWorkspacePath;
+    }
+
+    public Path defaultWorkspacePath(String agentId) {
+        return rootWorkspacePath.resolve("agents").resolve(agentId);
+    }
+
+    public Path resolveWorkspacePath(String configuredPath, String agentId) {
+        if (configuredPath == null || configuredPath.isBlank()) {
+            return defaultWorkspacePath(agentId);
+        }
+        return Path.of(configuredPath);
+    }
+
+    public Resource rootWorkspace() {
+        return asResource(rootWorkspacePath);
+    }
+
+    public Resource asResource(Path workspacePath) {
+        return resourceLoader.getResource("file:" + workspacePath.toAbsolutePath() + "/");
+    }
+
+    public Path initializeWorkspace(Path workspacePath) throws IOException {
+        Files.createDirectories(workspacePath);
+        copyIfMissing(rootWorkspacePath.resolve(INFO_MD), workspacePath.resolve(INFO_MD));
+        copyIfMissing(rootWorkspacePath.resolve(AGENT_MD), workspacePath.resolve(AGENT_MD));
+        copyIfMissing(rootWorkspacePath.resolve(AGENT_PRIVATE_MD), workspacePath.resolve(AGENT_PRIVATE_MD));
+        copyDirectoryContentsIfMissing(rootWorkspacePath.resolve("skills"), workspacePath.resolve("skills"));
+        Files.createDirectories(workspacePath.resolve("context"));
+        return workspacePath;
+    }
+
+    private static void copyIfMissing(Path source, Path target) throws IOException {
+        if (!Files.exists(source) || Files.exists(target)) {
+            return;
+        }
+        Files.createDirectories(target.getParent());
+        Files.copy(source, target);
+    }
+
+    private static void copyDirectoryContentsIfMissing(Path sourceDir, Path targetDir) throws IOException {
+        Files.createDirectories(targetDir);
+        if (!Files.isDirectory(sourceDir)) {
+            return;
+        }
+
+        try (Stream<Path> paths = Files.walk(sourceDir)) {
+            for (Path source : paths.toList()) {
+                Path relativePath = sourceDir.relativize(source);
+                Path target = targetDir.resolve(relativePath);
+                if (Files.isDirectory(source)) {
+                    Files.createDirectories(target);
+                } else {
+                    copyIfMissing(source, target);
+                }
+            }
+        }
+    }
+}
diff --git a/base/src/main/java/ai/javaclaw/agents/ConfiguredAgent.java b/base/src/main/java/ai/javaclaw/agents/ConfiguredAgent.java
new file mode 100644
index 0000000..f2c67e2
--- /dev/null
+++ b/base/src/main/java/ai/javaclaw/agents/ConfiguredAgent.java
@@ -0,0 +1,14 @@
+package ai.javaclaw.agents;
+
+public record ConfiguredAgent(
+        String id,
+        String provider,
+        String model,
+        String apiKey,
+        String baseUrl,
+        String workspacePath
+) {
+    public boolean isOpenAiCompatible() {
+        return "openai".equalsIgnoreCase(provider);
+    }
+}
diff --git a/base/src/main/java/ai/javaclaw/configuration/ConfigurationManager.java b/base/src/main/java/ai/javaclaw/configuration/ConfigurationManager.java
index 884f419..f92f966 100644
--- a/base/src/main/java/ai/javaclaw/configuration/ConfigurationManager.java
+++ b/base/src/main/java/ai/javaclaw/configuration/ConfigurationManager.java
@@ -87,9 +87,33 @@ private Path resolveConfigPath(String location) {
 
     @SuppressWarnings("unchecked")
     private void setNestedValue(Map<String, Object> map, String[] keys, Object value) {
+        if (value == null) {
+            removeNestedValue(map, keys, 0);
+            return;
+        }
+
         for (int i = 0; i < keys.length - 1; i++) {
             map = (Map<String, Object>) map.computeIfAbsent(keys[i], k -> new LinkedHashMap<>());
         }
         map.put(keys[keys.length - 1], value);
     }
+
+    @SuppressWarnings("unchecked")
+    private boolean removeNestedValue(Map<String, Object> map, String[] keys, int index) {
+        if (index == keys.length - 1) {
+            map.remove(keys[index]);
+            return map.isEmpty();
+        }
+
+        Object nested = map.get(keys[index]);
+        if (!(nested instanceof Map<?, ?> nestedMap)) {
+            return map.isEmpty();
+        }
+
+        boolean shouldRemoveChild = removeNestedValue((Map<String, Object>) nestedMap, keys, index + 1);
+        if (shouldRemoveChild) {
+            map.remove(keys[index]);
+        }
+        return map.isEmpty();
+    }
 }
diff --git a/base/src/main/java/ai/javaclaw/onboarding/AgentOnboardingProvider.java b/base/src/main/java/ai/javaclaw/onboarding/AgentOnboardingProvider.java
index e4919d6..8b90759 100644
--- a/base/src/main/java/ai/javaclaw/onboarding/AgentOnboardingProvider.java
+++ b/base/src/main/java/ai/javaclaw/onboarding/AgentOnboardingProvider.java
@@ -28,5 +28,13 @@ default void saveProperty(Map<String, Object> properties, String propertySuffix,
         properties.put(createPropertyKey(propertySuffix), value);
     }
 
+    default Map<String, Object> runtimeModelProperties() {
+        return Map.of();
+    }
+
+    default boolean usesRuntimeRegistry() {
+        return false;
+    }
+
     record SystemWideToken(String name, String token) {}
 }
diff --git a/base/src/main/java/ai/javaclaw/providers/AgentProvider.java b/base/src/main/java/ai/javaclaw/providers/AgentProvider.java
index 793fa60..533b291 100644
--- a/base/src/main/java/ai/javaclaw/providers/AgentProvider.java
+++ b/base/src/main/java/ai/javaclaw/providers/AgentProvider.java
@@ -3,11 +3,9 @@
 import ai.javaclaw.onboarding.AgentOnboardingProvider;
 import org.springframework.ai.chat.model.ChatModel;
 import org.springframework.core.env.Environment;
-import org.springframework.stereotype.Component;
 
 import java.util.SequencedCollection;
 
-@Component
 public class AgentProvider {
 
     private final Environment environment;
diff --git a/base/src/test/java/ai/javaclaw/agent/memory/FileSystemChatMemoryRepositoryTest.java b/base/src/test/java/ai/javaclaw/agent/memory/FileSystemChatMemoryRepositoryTest.java
index 70fed58..656ab36 100644
--- a/base/src/test/java/ai/javaclaw/agent/memory/FileSystemChatMemoryRepositoryTest.java
+++ b/base/src/test/java/ai/javaclaw/agent/memory/FileSystemChatMemoryRepositoryTest.java
@@ -6,7 +6,6 @@
 import org.springframework.ai.chat.messages.AssistantMessage;
 import org.springframework.ai.chat.messages.Message;
 import org.springframework.ai.chat.messages.UserMessage;
-import org.springframework.core.io.FileSystemResource;
 
 import java.io.IOException;
 import java.nio.file.Files;
@@ -23,7 +22,7 @@ class FileSystemChatMemoryRepositoryTest {
 
     @BeforeEach
     void setUp() throws IOException {
-        repository = new FileSystemChatMemoryRepository(new FileSystemResource(workspaceDir));
+        repository = new FileSystemChatMemoryRepository(workspaceDir);
     }
 
     // -----------------------------------------------------------------------
@@ -58,6 +57,13 @@ void saveCreatesFileAtCorrectPath() throws IOException {
                 .contains("user: Hi");
     }
 
+    @Test
+    void saveStoresConversationInsideAgentWorkspaceConversationsFolder() {
+        repository.saveAll("web", List.of(new UserMessage("Hi")));
+
+        assertThat(workspaceDir.resolve("conversations").resolve("chat-web.yaml")).exists();
+    }
+
     @Test
     void savePreservesCreatedAtOnSubsequentSaves() throws IOException {
         repository.saveAll("web", List.of(new UserMessage("First")));
diff --git a/base/src/test/java/ai/javaclaw/models/AgentChatClientFactoryTest.java b/base/src/test/java/ai/javaclaw/models/AgentChatClientFactoryTest.java
new file mode 100644
index 0000000..fb260a3
--- /dev/null
+++ b/base/src/test/java/ai/javaclaw/models/AgentChatClientFactoryTest.java
@@ -0,0 +1,83 @@
+package ai.javaclaw.models;
+
+import ai.javaclaw.agents.AgentChatClientFactory;
+import ai.javaclaw.agents.AgentWorkspaceResolver;
+import ai.javaclaw.configuration.ConfigurationManager;
+import ai.javaclaw.tasks.TaskManager;
+import ai.javaclaw.tools.AutoDiscoveredTool;
+import io.micrometer.observation.ObservationRegistry;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import org.springframework.ai.chat.client.ChatClient;
+import org.springframework.ai.chat.memory.ChatMemory;
+import org.springframework.ai.chat.model.ChatModel;
+import org.springframework.ai.mcp.SyncMcpToolCallbackProvider;
+import org.springframework.ai.tool.ToolCallback;
+import org.springframework.ai.model.tool.ToolCallingManager;
+import org.springframework.ai.model.tool.ToolExecutionEligibilityPredicate;
+import org.springframework.beans.factory.ObjectProvider;
+import org.springframework.core.io.DefaultResourceLoader;
+import org.springframework.core.retry.RetryTemplate;
+import org.springframework.mock.env.MockEnvironment;
+import org.springframework.web.client.RestClient;
+import org.springframework.web.reactive.function.client.WebClient;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Set;
+
+import static org.assertj.core.api.Assertions.assertThatNoException;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+class AgentChatClientFactoryTest {
+
+    @TempDir
+    Path tempDir;
+
+    @Test
+    void createClientSkipsSkillsToolWhenWorkspaceHasNoSkills() throws Exception {
+        Path rootWorkspace = tempDir.resolve("workspace");
+        Files.createDirectories(rootWorkspace);
+        Files.writeString(rootWorkspace.resolve("AGENT.md"), "root agent");
+        Files.writeString(rootWorkspace.resolve("INFO.md"), "root info");
+
+        AgentWorkspaceResolver resolver = new AgentWorkspaceResolver(
+                new DefaultResourceLoader(),
+                new MockEnvironment().withProperty("agent.workspace", "file:" + rootWorkspace + "/")
+        );
+
+        SyncMcpToolCallbackProvider mcpToolProvider = mock(SyncMcpToolCallbackProvider.class);
+        when(mcpToolProvider.getToolCallbacks()).thenReturn(new ToolCallback[0]);
+
+        AgentChatClientFactory factory = new AgentChatClientFactory(
+                mock(ChatMemory.class),
+                mcpToolProvider,
+                mock(TaskManager.class),
+                mock(ConfigurationManager.class),
+                resolver,
+                Set.<AutoDiscoveredTool<?>>of(),
+                mock(ToolCallingManager.class),
+                stubProvider(ObservationRegistry.NOOP),
+                stubProvider(mock(ToolExecutionEligibilityPredicate.class)),
+                stubProvider(new RetryTemplate()),
+                stubProvider(RestClient.builder()),
+                stubProvider(WebClient.builder())
+        );
+
+        ChatModel chatModel = factory.noModelConfiguredChatModel();
+
+        assertThatNoException().isThrownBy(() -> {
+            ChatClient client = factory.createClient(chatModel);
+            client.prompt("hello");
+        });
+    }
+
+    private static <T> ObjectProvider<T> stubProvider(T value) {
+        @SuppressWarnings("unchecked")
+        ObjectProvider<T> provider = mock(ObjectProvider.class);
+        when(provider.getIfUnique(org.mockito.ArgumentMatchers.any())).thenAnswer(invocation -> value != null ? value : invocation.getArgument(0, java.util.function.Supplier.class).get());
+        when(provider.getIfAvailable(org.mockito.ArgumentMatchers.any())).thenAnswer(invocation -> value != null ? value : invocation.getArgument(0, java.util.function.Supplier.class).get());
+        return provider;
+    }
+}
diff --git a/base/src/test/java/ai/javaclaw/models/ModelRegistryTest.java b/base/src/test/java/ai/javaclaw/models/ModelRegistryTest.java
new file mode 100644
index 0000000..68771b6
--- /dev/null
+++ b/base/src/test/java/ai/javaclaw/models/ModelRegistryTest.java
@@ -0,0 +1,81 @@
+package ai.javaclaw.models;
+
+import ai.javaclaw.agents.AgentRegistry;
+import ai.javaclaw.agents.ConfiguredAgent;
+import ai.javaclaw.configuration.ConfigurationManager;
+import org.junit.jupiter.api.Test;
+import org.springframework.mock.env.MockEnvironment;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class ModelRegistryTest {
+
+    @Test
+    void loadsRuntimeDefaultModelFromConfiguration() throws IOException {
+        Path tempDir = Files.createTempDirectory("model-registry-test");
+        MockEnvironment environment = new MockEnvironment().withProperty("spring.allConfig.location", "file:" + tempDir + "/");
+        ConfigurationManager configurationManager = new ConfigurationManager(environment, event -> {});
+
+        Map<String, Object> props = new LinkedHashMap<>();
+        props.put("agent.agents.default", "openai-main");
+        props.put("agent.agents.items.openai-main.provider", "openai");
+        props.put("agent.agents.items.openai-main.model", "gpt-5.4");
+        props.put("agent.agents.items.openai-main.api-key", "secret");
+        props.put("agent.agents.items.openai-main.workspace", "/tmp/openai-main");
+        configurationManager.updateProperties(props);
+
+        AgentRegistry modelRegistry = new AgentRegistry(configurationManager);
+
+        ConfiguredAgent model = modelRegistry.getDefaultAgent().orElseThrow();
+        assertEquals("openai-main", model.id());
+        assertEquals("openai", model.provider());
+        assertEquals("gpt-5.4", model.model());
+        assertEquals("", model.baseUrl());
+        assertEquals("/tmp/openai-main", model.workspacePath());
+    }
+
+    @Test
+    void ignoresDisabledModels() throws IOException {
+        Path tempDir = Files.createTempDirectory("model-registry-disabled-test");
+        MockEnvironment environment = new MockEnvironment().withProperty("spring.allConfig.location", "file:" + tempDir + "/");
+        ConfigurationManager configurationManager = new ConfigurationManager(environment, event -> {});
+
+        Map<String, Object> props = new LinkedHashMap<>();
+        props.put("agent.agents.default", "openai-main");
+        props.put("agent.agents.items.openai-main.provider", "openai");
+        props.put("agent.agents.items.openai-main.model", "gpt-5.4");
+        props.put("agent.agents.items.openai-main.enabled", false);
+        configurationManager.updateProperties(props);
+
+        AgentRegistry modelRegistry = new AgentRegistry(configurationManager);
+
+        assertTrue(modelRegistry.getDefaultAgent().isEmpty());
+    }
+
+    @Test
+    void fallsBackToFirstAgentWhenDefaultKeyIsMissing() throws IOException {
+        Path tempDir = Files.createTempDirectory("agent-registry-missing-default-test");
+        MockEnvironment environment = new MockEnvironment().withProperty("spring.allConfig.location", "file:" + tempDir + "/");
+        ConfigurationManager configurationManager = new ConfigurationManager(environment, event -> {});
+
+        Map<String, Object> props = new LinkedHashMap<>();
+        props.put("agent.agents.items.openai-main.provider", "openai");
+        props.put("agent.agents.items.openai-main.model", "gpt-5.4");
+        props.put("agent.agents.items.openai-main.workspace", "/tmp/openai-main");
+        configurationManager.updateProperties(props);
+
+        AgentRegistry modelRegistry = new AgentRegistry(configurationManager);
+
+        assertFalse(modelRegistry.getAgents().isEmpty());
+        assertEquals("openai-main", modelRegistry.getDefaultAgentId());
+        assertEquals("openai-main", modelRegistry.getDefaultAgent().orElseThrow().id());
+    }
+}
diff --git a/base/src/test/java/ai/javaclaw/models/ModelWorkspaceResolverTest.java b/base/src/test/java/ai/javaclaw/models/ModelWorkspaceResolverTest.java
new file mode 100644
index 0000000..c2d3c20
--- /dev/null
+++ b/base/src/test/java/ai/javaclaw/models/ModelWorkspaceResolverTest.java
@@ -0,0 +1,42 @@
+package ai.javaclaw.models;
+
+import ai.javaclaw.agents.AgentWorkspaceResolver;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import org.springframework.core.io.DefaultResourceLoader;
+import org.springframework.mock.env.MockEnvironment;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class ModelWorkspaceResolverTest {
+
+    @TempDir
+    Path tempDir;
+
+    @Test
+    void initializeWorkspaceCopiesPromptFilesAndSkills() throws IOException {
+        Path rootWorkspace = tempDir.resolve("workspace");
+        Files.createDirectories(rootWorkspace.resolve("skills").resolve("skill-creator"));
+        Files.writeString(rootWorkspace.resolve("AGENT.md"), "root agent");
+        Files.writeString(rootWorkspace.resolve("AGENT.private.md"), "private agent");
+        Files.writeString(rootWorkspace.resolve("INFO.md"), "root info");
+        Files.writeString(rootWorkspace.resolve("skills").resolve("skill-creator").resolve("SKILL.md"), "skill body");
+
+        AgentWorkspaceResolver resolver = new AgentWorkspaceResolver(
+                new DefaultResourceLoader(),
+                new MockEnvironment().withProperty("agent.workspace", "file:" + rootWorkspace + "/")
+        );
+
+        Path modelWorkspace = resolver.initializeWorkspace(rootWorkspace.resolve("agents").resolve("openai-main"));
+
+        assertThat(modelWorkspace.resolve("AGENT.md")).hasContent("root agent");
+        assertThat(modelWorkspace.resolve("AGENT.private.md")).hasContent("private agent");
+        assertThat(modelWorkspace.resolve("INFO.md")).hasContent("root info");
+        assertThat(modelWorkspace.resolve("skills").resolve("skill-creator").resolve("SKILL.md")).hasContent("skill body");
+        assertThat(modelWorkspace.resolve("context")).isDirectory();
+    }
+}
diff --git a/providers/openai/src/main/java/ai/javaclaw/providers/openai/OpenAIAgentOnboardingProvider.java b/providers/openai/src/main/java/ai/javaclaw/providers/openai/OpenAIAgentOnboardingProvider.java
index f981f98..5faa8e3 100644
--- a/providers/openai/src/main/java/ai/javaclaw/providers/openai/OpenAIAgentOnboardingProvider.java
+++ b/providers/openai/src/main/java/ai/javaclaw/providers/openai/OpenAIAgentOnboardingProvider.java
@@ -30,4 +30,9 @@ public boolean requiresApiKey() {
     public String defaultModel() {
         return "gpt-5.4";
     }
+
+    @Override
+    public boolean usesRuntimeRegistry() {
+        return true;
+    }
 }

From 66f3f343e3bddcae18ffc082024812bd727b14e2 Mon Sep 17 00:00:00 2001
From: Aref Behboudi <behboodiaref@gmail.com>
Date: Tue, 7 Apr 2026 08:52:12 +0300
Subject: [PATCH 2/2] Fix: remove usesRuntimeRegistry

---
 .../onboarding/steps/S2_ProviderStep.java      | 11 ++---------
 .../onboarding/steps/S3_CredentialsStep.java   | 18 +++++-------------
 .../onboarding/steps/S4_AgentMdStep.java       | 18 ------------------
 .../onboarding/steps/S4_AgentMdStepTest.java   |  4 ----
 .../onboarding/AgentOnboardingProvider.java    |  4 ----
 .../openai/OpenAIAgentOnboardingProvider.java  |  4 ----
 6 files changed, 7 insertions(+), 52 deletions(-)

diff --git a/app/src/main/java/ai/javaclaw/onboarding/steps/S2_ProviderStep.java b/app/src/main/java/ai/javaclaw/onboarding/steps/S2_ProviderStep.java
index 5f453f0..495892b 100644
--- a/app/src/main/java/ai/javaclaw/onboarding/steps/S2_ProviderStep.java
+++ b/app/src/main/java/ai/javaclaw/onboarding/steps/S2_ProviderStep.java
@@ -82,15 +82,8 @@ public void saveConfiguration(Map<String, Object> session, ConfigurationManager
 
         AgentOnboardingProvider agentOnboardingProvider = agentOnboardingProviders.getById(providerId);
         Map<String, Object> props = new LinkedHashMap<>();
-        if (agentOnboardingProvider.usesRuntimeRegistry()) {
-            saveRuntimeAgent(props, agentOnboardingProvider, agentId, model, apiKey);
-            clearSpringAiProviderConfig(props);
-        } else {
-            clearRuntimeDefaultAgent(props);
-            agentOnboardingProvider.saveProperty(props, "chat.options.model", model);
-            agentOnboardingProvider.saveProperty(props, "api-key", apiKey);
-            props.put("spring.ai.model.chat", agentOnboardingProvider.getId().replace(".", "-"));
-        }
+        saveRuntimeAgent(props, agentOnboardingProvider, agentId, model, apiKey);
+        clearSpringAiProviderConfig(props);
         configurationManager.updateProperties(props);
     }
 
diff --git a/app/src/main/java/ai/javaclaw/onboarding/steps/S3_CredentialsStep.java b/app/src/main/java/ai/javaclaw/onboarding/steps/S3_CredentialsStep.java
index 5ce9d4c..1dbccb2 100644
--- a/app/src/main/java/ai/javaclaw/onboarding/steps/S3_CredentialsStep.java
+++ b/app/src/main/java/ai/javaclaw/onboarding/steps/S3_CredentialsStep.java
@@ -104,31 +104,23 @@ private CredentialsFormState buildFormState(Map<String, Object> session, AgentOn
     }
 
     private String existingModel(AgentOnboardingProvider provider, String agentId) {
-        return provider.usesRuntimeRegistry()
-                ? env.getProperty(S2_ProviderStep.runtimeAgentKey(agentId, "model"), "")
-                : env.getProperty(provider.createPropertyKey("chat.options.model"), "");
+        return env.getProperty(S2_ProviderStep.runtimeAgentKey(agentId, "model"), "");
     }
 
     private String existingApiKey(AgentOnboardingProvider provider, String agentId) {
-        return provider.usesRuntimeRegistry()
-                ? env.getProperty(S2_ProviderStep.runtimeAgentKey(agentId, "api-key"), "")
-                : env.getProperty(provider.createPropertyKey("api-key"), "");
+        return env.getProperty(S2_ProviderStep.runtimeAgentKey(agentId, "api-key"), "");
     }
 
     private String modelPropertyKey(AgentOnboardingProvider provider, String agentId) {
-        return provider.usesRuntimeRegistry()
-                ? S2_ProviderStep.runtimeAgentKey(agentId, "model")
-                : provider.createPropertyKey("chat.options.model");
+        return S2_ProviderStep.runtimeAgentKey(agentId, "model");
     }
 
     private String apiKeyPropertyKey(AgentOnboardingProvider provider, String agentId) {
-        return provider.usesRuntimeRegistry()
-                ? S2_ProviderStep.runtimeAgentKey(agentId, "api-key")
-                : provider.createPropertyKey("api-key");
+        return S2_ProviderStep.runtimeAgentKey(agentId, "api-key");
     }
 
     private String baseUrlPropertyKey(AgentOnboardingProvider provider, String agentId) {
-        if (!provider.usesRuntimeRegistry() || !provider.runtimeModelProperties().containsKey("base-url")) {
+        if (!provider.runtimeModelProperties().containsKey("base-url")) {
             return null;
         }
         return S2_ProviderStep.runtimeAgentKey(agentId, "base-url");
diff --git a/app/src/main/java/ai/javaclaw/onboarding/steps/S4_AgentMdStep.java b/app/src/main/java/ai/javaclaw/onboarding/steps/S4_AgentMdStep.java
index 192c8dd..9d784f0 100644
--- a/app/src/main/java/ai/javaclaw/onboarding/steps/S4_AgentMdStep.java
+++ b/app/src/main/java/ai/javaclaw/onboarding/steps/S4_AgentMdStep.java
@@ -93,10 +93,6 @@ public void saveConfiguration(Map<String, Object> session, ConfigurationManager
     }
 
     private Resource resolveAgentWorkspace(Map<String, Object> session) throws IOException {
-        if (!usesAgentWorkspace(session)) {
-            return agentWorkspaceResolver.rootWorkspace();
-        }
-
         String agentId = (String) session.getOrDefault(S2_ProviderStep.SESSION_AGENT_ID, environment.getProperty("agent.agents.default", "default"));
         String configuredWorkspace = environment.getProperty(S2_ProviderStep.runtimeAgentKey(agentId, "workspace"), "");
         Path workspacePath = agentWorkspaceResolver.initializeWorkspace(
@@ -104,18 +100,4 @@ private Resource resolveAgentWorkspace(Map<String, Object> session) throws IOExc
         );
         return agentWorkspaceResolver.asResource(workspacePath);
     }
-
-    private boolean usesAgentWorkspace(Map<String, Object> session) {
-        String providerId = (String) session.get(S2_ProviderStep.SESSION_PROVIDER);
-        if (providerId == null || providerId.isBlank()) {
-            String agentId = (String) session.getOrDefault(S2_ProviderStep.SESSION_AGENT_ID, environment.getProperty("agent.agents.default", "default"));
-            providerId = environment.getProperty(S2_ProviderStep.runtimeAgentKey(agentId, "provider"), "");
-        }
-        if (providerId == null || providerId.isBlank()) {
-            return false;
-        }
-        return agentOnboardingProviders.findById(providerId)
-                .map(provider -> provider.usesRuntimeRegistry())
-                .orElse(false);
-    }
 }
diff --git a/app/src/test/java/ai/javaclaw/onboarding/steps/S4_AgentMdStepTest.java b/app/src/test/java/ai/javaclaw/onboarding/steps/S4_AgentMdStepTest.java
index 8dbdbd1..8cf9f9a 100644
--- a/app/src/test/java/ai/javaclaw/onboarding/steps/S4_AgentMdStepTest.java
+++ b/app/src/test/java/ai/javaclaw/onboarding/steps/S4_AgentMdStepTest.java
@@ -79,9 +79,5 @@ public String defaultModel() {
             return "gpt-5.4";
         }
 
-        @Override
-        public boolean usesRuntimeRegistry() {
-            return true;
-        }
     }
 }
diff --git a/base/src/main/java/ai/javaclaw/onboarding/AgentOnboardingProvider.java b/base/src/main/java/ai/javaclaw/onboarding/AgentOnboardingProvider.java
index 8b90759..be8a213 100644
--- a/base/src/main/java/ai/javaclaw/onboarding/AgentOnboardingProvider.java
+++ b/base/src/main/java/ai/javaclaw/onboarding/AgentOnboardingProvider.java
@@ -32,9 +32,5 @@ default Map<String, Object> runtimeModelProperties() {
         return Map.of();
     }
 
-    default boolean usesRuntimeRegistry() {
-        return false;
-    }
-
     record SystemWideToken(String name, String token) {}
 }
diff --git a/providers/openai/src/main/java/ai/javaclaw/providers/openai/OpenAIAgentOnboardingProvider.java b/providers/openai/src/main/java/ai/javaclaw/providers/openai/OpenAIAgentOnboardingProvider.java
index 5faa8e3..2934e44 100644
--- a/providers/openai/src/main/java/ai/javaclaw/providers/openai/OpenAIAgentOnboardingProvider.java
+++ b/providers/openai/src/main/java/ai/javaclaw/providers/openai/OpenAIAgentOnboardingProvider.java
@@ -31,8 +31,4 @@ public String defaultModel() {
         return "gpt-5.4";
     }
 
-    @Override
-    public boolean usesRuntimeRegistry() {
-        return true;
-    }
 }