feat(config): make BASE_URL a required field and update related documentation

backend/app/api/board_group_memory.py

@@ -331,7 +331,7 @@ async def _notify_group_memory_targets(
     if len(snippet) > MAX_SNIPPET_LENGTH:
         snippet = f"{snippet[: MAX_SNIPPET_LENGTH - 3]}..."
 
-    base_url = settings.base_url or "http://localhost:8000"
+    base_url = settings.base_url
 
     context = _NotifyGroupContext(
         session=session,

backend/app/api/board_memory.py

@@ -191,7 +191,7 @@ async def _notify_chat_targets(
     snippet = memory.content.strip()
     if len(snippet) > MAX_SNIPPET_LENGTH:
         snippet = f"{snippet[: MAX_SNIPPET_LENGTH - 3]}..."
-    base_url = settings.base_url or "http://localhost:8000"
+    base_url = settings.base_url
     for agent in targets.values():
         if not agent.openclaw_session_id:
             continue

backend/app/api/board_onboarding.py

@@ -229,7 +229,7 @@ async def start_onboarding(
         return onboarding
 
     dispatcher = BoardOnboardingMessagingService(session)
-    base_url = settings.base_url or "http://localhost:8000"
+    base_url = settings.base_url
     prompt = (
         "BOARD ONBOARDING REQUEST\n\n"
         f"Board Name: {board.name}\n"

backend/app/core/config.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from pathlib import Path
 from typing import Self
+from urllib.parse import urlparse
 
 from pydantic import Field, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
@@ -48,7 +49,7 @@ class Settings(BaseSettings):
     clerk_leeway: float = 10.0
 
     cors_origins: str = ""
-    base_url: str = ""
+    base_url: str
     # Security response headers (blank disables header injection)
     security_header_x_content_type_options: str = ""
     security_header_x_frame_options: str = ""
@@ -93,6 +94,15 @@ class Settings(BaseSettings):
                 raise ValueError(
                     "LOCAL_AUTH_TOKEN must be at least 50 characters and non-placeholder when AUTH_MODE=local.",
                 )
+        base_url = self.base_url.strip()
+        if not base_url:
+            raise ValueError("BASE_URL must be set and non-empty.")
+        parsed_base_url = urlparse(base_url)
+        if parsed_base_url.scheme not in {"http", "https"} or not parsed_base_url.netloc:
+            raise ValueError(
+                "BASE_URL must be an absolute http(s) URL (e.g. http://localhost:8000).",
+            )
+        self.base_url = base_url.rstrip("/")
         # In dev, default to applying Alembic migrations at startup to avoid
         # schema drift (e.g. missing newly-added columns).
         if "db_auto_migrate" not in self.model_fields_set and self.environment == "dev":

backend/app/services/openclaw/coordination_service.py

@@ -93,7 +93,7 @@ class GatewayCoordinationService(AbstractGatewayMessagingService):
         reply_tags: list[str] | None,
         reply_source: str | None,
     ) -> str:
-        base_url = settings.base_url or "http://localhost:8000"
+        base_url = settings.base_url
         header = "GATEWAY MAIN QUESTION" if kind == "question" else "GATEWAY MAIN HANDOFF"
         correlation = correlation_id.strip() if correlation_id else ""
         correlation_line = f"Correlation ID: {correlation}\n" if correlation else ""
@@ -440,7 +440,7 @@ class GatewayCoordinationService(AbstractGatewayMessagingService):
         tags = payload.reply_tags or ["gateway_main", "user_reply"]
         tags_json = json.dumps(tags)
         reply_source = payload.reply_source or "user_via_gateway_main"
-        base_url = settings.base_url or "http://localhost:8000"
+        base_url = settings.base_url
         message = (
             "LEAD REQUEST: ASK USER\n"
             f"Board: {board.name}\n"

backend/app/services/openclaw/provisioning.py

@@ -370,7 +370,7 @@ def _build_context(
     workspace_root = gateway.workspace_root
     workspace_path = _workspace_path(agent, workspace_root)
     session_key = agent.openclaw_session_id or ""
-    base_url = settings.base_url or "REPLACE_WITH_BASE_URL"
+    base_url = settings.base_url
     main_session_key = GatewayAgentIdentity.session_key(gateway)
     identity_context = _identity_context(agent)
     user_context = _user_context(user)
@@ -411,7 +411,7 @@ def _build_main_context(
     auth_token: str,
     user: User | None,
 ) -> dict[str, str]:
-    base_url = settings.base_url or "REPLACE_WITH_BASE_URL"
+    base_url = settings.base_url
     identity_context = _identity_context(agent)
     user_context = _user_context(user)
     return {