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..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
@@ -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,70 @@ 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(".", "-"));
+        saveRuntimeAgent(props, agentOnboardingProvider, agentId, model, apiKey);
+        clearSpringAiProviderConfig(props);
         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..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
@@ -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,74 @@ 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 env.getProperty(S2_ProviderStep.runtimeAgentKey(agentId, "model"), "");
+    }
+
+    private String existingApiKey(AgentOnboardingProvider provider, String agentId) {
+        return env.getProperty(S2_ProviderStep.runtimeAgentKey(agentId, "api-key"), "");
     }
+
+    private String modelPropertyKey(AgentOnboardingProvider provider, String agentId) {
+        return S2_ProviderStep.runtimeAgentKey(agentId, "model");
+    }
+
+    private String apiKeyPropertyKey(AgentOnboardingProvider provider, String agentId) {
+        return S2_ProviderStep.runtimeAgentKey(agentId, "api-key");
+    }
+
+    private String baseUrlPropertyKey(AgentOnboardingProvider provider, String agentId) {
+        if (!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..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
@@ -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,13 @@ 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 {
+        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);
+    }
 }
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..8cf9f9a
--- /dev/null
+++ b/app/src/test/java/ai/javaclaw/onboarding/steps/S4_AgentMdStepTest.java
@@ -0,0 +1,83 @@
+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";
+        }
+
+    }
+}
diff --git a/app/workspace/app.mv.db b/app/workspace/app.mv.db
deleted file mode 100644
index 5495ecf..0000000
Binary files a/app/workspace/app.mv.db and /dev/null differ
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..be8a213 100644
--- a/base/src/main/java/ai/javaclaw/onboarding/AgentOnboardingProvider.java
+++ b/base/src/main/java/ai/javaclaw/onboarding/AgentOnboardingProvider.java
@@ -28,5 +28,9 @@ default void saveProperty(Map<String, Object> properties, String propertySuffix,
         properties.put(createPropertyKey(propertySuffix), value);
     }
 
+    default Map<String, Object> runtimeModelProperties() {
+        return Map.of();
+    }
+
     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..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
@@ -30,4 +30,5 @@ public boolean requiresApiKey() {
     public String defaultModel() {
         return "gpt-5.4";
     }
+
 }