Merge pull request #5 from Core-Mate/codex/fix-env-example-startup

[codex] Complete backend env example and startup checks

Author: dxcsmam

server/apps/backend/.env.example

@@ -1,5 +1,10 @@
-# OpenGUI Server Environment Configuration
-# Copy this file to .env and fill in your values
+# OpenGUI Server environment configuration
+#
+# Quick start:
+#   1. Copy this file to .env
+#      cp apps/backend/.env.example apps/backend/.env
+#   2. Fill in the required model settings below.
+#   3. Never commit the real .env file or real API keys.
 
 # App
 NODE_ENV=development
@@ -14,18 +19,40 @@ REDIS_PORT=6379
 REDIS_DB=0
 REDIS_PASSWORD=
 
-# Claude Agent (plan-supervisor, summarizer, executor-a11y)
+# ============================================================
+# Required model configuration
+# ============================================================
+#
+# OpenGUI uses these variables at runtime:
+# - CLAUDE_* is the default text/action model config for:
+#   plan-supervisor, summarizer, executor-a11y, and action-summarizer.
+# - VLM_* is the vision model config for executor-vlm.
+#
+# CLAUDE_BASE_URL and VLM_BASE_URL are optional when you use the provider's
+# default endpoint. Set them when using an OpenAI-compatible gateway.
+#
+# OpenAI-compatible example:
+#   CLAUDE_BASE_URL=https://your-openai-compatible-endpoint/v1
+#   CLAUDE_MODEL=your-text-model
+#   CLAUDE_SMALL_MODEL=your-small-or-cheaper-text-model
+#   VLM_BASE_URL=https://your-openai-compatible-endpoint/v1
+#   VLM_MODEL=your-vision-model
+#
+# Do not put real API keys in this example file.
+
+# Text/action agents
 CLAUDE_API_KEY=
 CLAUDE_BASE_URL=
-CLAUDE_MODEL=anthropic/claude-sonnet-4.6
-CLAUDE_SMALL_MODEL=anthropic/claude-haiku-4.5
+CLAUDE_MODEL=
+CLAUDE_SMALL_MODEL=
 
-# VLM Agent (executor-vlm) — 视觉模型
+# Vision agent
 VLM_API_KEY=
 VLM_BASE_URL=
 VLM_MODEL=
 
-# Creator Agent (Claude Agent SDK)
+# Optional: Creator Agent (Claude Agent SDK)
+# Only required if you use creator-agent SDK features.
 ANTHROPIC_API_KEY=
 # ANTHROPIC_BASE_URL=
 

server/start.sh

@@ -83,9 +83,11 @@ ENV_EXAMPLE=apps/backend/.env.example
 if [ ! -f "$ENV_FILE" ]; then
   if [ -f "$ENV_EXAMPLE" ]; then
     cp "$ENV_EXAMPLE" "$ENV_FILE"
-    warn ".env was created from .env.example. Please edit it and add your API keys:"
+    warn ".env was created from .env.example. Please edit it and add the required model configuration:"
     warn "  File: $ENV_FILE"
-    warn "  CLAUDE_API_KEY, VLM_API_KEY, ANTHROPIC_API_KEY"
+    warn "  Required: CLAUDE_API_KEY, CLAUDE_MODEL, CLAUDE_SMALL_MODEL, VLM_API_KEY, VLM_MODEL"
+    warn "  Optional: CLAUDE_BASE_URL, VLM_BASE_URL for OpenAI-compatible gateways"
+    warn "  Optional: ANTHROPIC_API_KEY only for Creator Agent SDK features"
     warn "Run this script again after editing the file."
     exit 0
   else
@@ -95,8 +97,30 @@ fi
 
 set -a; source "$ENV_FILE" 2>/dev/null || true; set +a
 
-if [ -z "$CLAUDE_API_KEY" ]; then
-  warn "CLAUDE_API_KEY is not set. Please edit .env."
+REQUIRED_MODEL_VARS=(
+  CLAUDE_API_KEY
+  CLAUDE_MODEL
+  CLAUDE_SMALL_MODEL
+  VLM_API_KEY
+  VLM_MODEL
+)
+
+MISSING_MODEL_VARS=()
+for var_name in "${REQUIRED_MODEL_VARS[@]}"; do
+  if [ -z "${!var_name}" ]; then
+    MISSING_MODEL_VARS+=("$var_name")
+  fi
+done
+
+if [ "${#MISSING_MODEL_VARS[@]}" -gt 0 ]; then
+  warn "Missing required model configuration in $ENV_FILE:"
+  for var_name in "${MISSING_MODEL_VARS[@]}"; do
+    warn "  $var_name"
+  done
+  warn "Fill these values and run ./start.sh again."
+  warn "If text and vision use the same provider, fill both CLAUDE_* and VLM_* explicitly."
+  warn "ANTHROPIC_API_KEY is optional unless you use Creator Agent SDK features."
+  exit 1
 fi
 
 info ".env loaded"