feat: add specialist agents example and imageModel routing

README.md

@@ -27,7 +27,11 @@ ZeroAPI/
 │   ├── claude-codex/openclaw.json    # 2 providers, 2 agents
 │   ├── claude-gemini/openclaw.json   # 2 providers, 3 agents
 │   │   └── gemini-models.json        # Per-agent Gemini provider (schema workaround)
-│   └── full-stack/openclaw.json      # 4 providers, 5 agents
+│   ├── full-stack/
+│   │   ├── openclaw.json             # 4 providers, 5 agents
+│   │   └── gemini-models.json        # Per-agent Gemini provider (schema workaround)
+│   └── specialist-agents/
+│       ├── openclaw.json             # 4 providers, 9 agents (domain specialists)
 │       └── gemini-models.json        # Per-agent Gemini provider (schema workaround)
 └── content/
     └── x-thread.md                   # Launch thread draft
@@ -178,6 +182,7 @@ All models should show as available. See [`examples/README.md`](examples/README.
 | **Claude + Codex** | $220 | + OpenAI | 2 | Specialist code + math via Codex. |
 | **Claude + Gemini** | $220 | + Google | 3 | Flash speed + Pro research + 1M context. |
 | **Full stack** | $250-430 | + Kimi | 5 | Full specialization across all tiers. |
+| **Specialist agents** | $250-430 | All 4 | 9 | Full stack + domain-specific agents (devops, research, content, community). |
 
 ## Cost Comparison
 

SKILL.md

@@ -183,6 +183,74 @@ When switching models mid-conversation:
 - Sub-agents cannot write to your workspace — output comes back as text.
 - Sub-agents share nothing with each other — complete isolation by design.
 
+## Specialist Agents (Optional)
+
+Beyond the 5 core agents (main, codex, gemini-researcher, gemini-fast, kimi-orchestrator), you can add domain-specific specialist agents. Specialists have their own workspace with tailored AGENTS.md, MEMORY.md, and skills for a specific domain.
+
+### When to use specialists
+
+- You have distinct project domains (infrastructure, content, community, etc.)
+- Each domain needs its own persistent memory and context
+- You want the main agent to orchestrate without carrying all domain knowledge
+
+### Example specialists
+
+| Agent | Primary Model | Why That Model | Use Case |
+|-------|--------------|----------------|----------|
+| `devops` | Codex | Code generation, shell scripts, config files | Infrastructure, deployment, monitoring scripts |
+| `researcher` | Gemini Pro | GPQA 0.908, 1M context | Deep research, fact-checking, literature review |
+| `content-writer` | Opus | Intelligence 53.0, best judgment | Blog posts, documentation, copywriting |
+| `community` | Flash | 206 tok/s, IFBench 0.780 | Moderation, quick responses, community engagement |
+
+### Delegating to specialists
+
+```
+/agent devops Set up a systemd service for the memory API with health checks and auto-restart
+
+/agent researcher Analyze the latest papers on mixture-of-experts architectures. Focus on routing efficiency.
+
+/agent content-writer Write a blog post about multi-model routing. Target audience: developers running self-hosted AI agents.
+
+/agent community Review the last 24 hours of community posts. Flag any that need moderation.
+```
+
+### Specialist workspace structure
+
+Each specialist gets its own workspace directory with domain-specific files:
+
+```
+~/.openclaw/workspace-devops/
+├── AGENTS.md          # DevOps-specific instructions and runbooks
+├── MEMORY.md          # Infrastructure decisions, deployment history
+└── skills/            # DevOps-relevant skills only
+```
+
+This keeps domain context separate. The main orchestrator does not load devops runbooks, and the devops agent does not carry content writing guidelines.
+
+**Note:** Workspace directory names are arbitrary — `workspace-devops`, `workspace-infra`, `workspace-ops` all work. The agent `id` and workspace path don't need to match.
+
+See `examples/specialist-agents/` for a ready-to-use config with 4 specialist agents.
+
+**Fallback depth:** Specialist agents in the example use 2 fallbacks instead of the core agents' 3. This is intentional — specialists are narrower in scope and trade some redundancy for simpler configs. Add more fallbacks if your specialists handle critical tasks.
+
+## Image Model Routing
+
+Set `imageModel` in your agent config to route vision/image analysis tasks to the best multimodal model:
+
+```json
+"imageModel": {
+  "primary": "google-gemini-cli/gemini-3-pro-preview",
+  "fallbacks": [
+    "google-gemini-cli/gemini-3-flash-preview",
+    "anthropic/claude-opus-4-6"
+  ]
+}
+```
+
+Gemini Pro is recommended as the primary image model — it has strong multimodal capabilities and 1M context for analyzing large images or multiple images in one request. Flash is a good fallback for speed, and Opus handles vision well as a last resort.
+
+Place this in `agents.defaults` to apply to all agents, or set it per-agent. Agents without `imageModel` typically fall back to their primary text model for vision tasks (exact behavior may vary by OpenClaw version — check [docs.openclaw.ai](https://docs.openclaw.ai) for current defaults).
+
 ## Collaboration Patterns
 
 ### Pipeline (sequential)

examples/README.md

@@ -10,6 +10,7 @@ Pick the example that matches your subscription setup. Each directory contains a
 | `claude-codex/` | Claude Max + ChatGPT Plus | $220 | 2 (main, codex) |
 | `claude-gemini/` | Claude Max + Gemini Advanced | $220 | 3 (main, gemini-researcher, gemini-fast) |
 | `full-stack/` | Claude Max + ChatGPT + Gemini + Kimi | $250-430 | 5 (main, codex, gemini-researcher, gemini-fast, kimi-orchestrator) |
+| `specialist-agents/` | Claude Max + ChatGPT + Gemini + Kimi | $250-430 | 9 (full-stack + devops, researcher, content-writer, community) |
 
 ## How to Use
 
@@ -66,6 +67,56 @@ openclaw models status
 
 All models should show as available. Any model showing `missing` or `auth_expired` needs fixing before routing will work.
 
+## Specialist Agents (specialist-agents/)
+
+The `specialist-agents/` example extends `full-stack/` with domain-specific agents. Each specialist has its own workspace and is optimized for a particular task type:
+
+| Agent | Primary Model | Role |
+|-------|--------------|------|
+| `devops` | Codex | Infrastructure, deployment, shell scripts, monitoring |
+| `researcher` | Gemini Pro | Deep research, fact-checking, long-context analysis |
+| `content-writer` | Opus | Blog posts, documentation, copywriting |
+| `community` | Flash | Community management, moderation, quick responses |
+
+**When to use specialists vs core agents:**
+- Core agents (codex, gemini-researcher, gemini-fast, kimi-orchestrator) are model-optimized — they pick the best model for a task type
+- Specialist agents are domain-optimized — they have workspace isolation, custom skills, and context relevant to their domain
+- Use specialists when you have distinct workspaces with different files, skills, or AGENTS.md instructions per domain
+
+**Workspace isolation:** Each specialist gets its own workspace directory. This means separate MEMORY.md, AGENTS.md, and skill files per domain. The main orchestrator delegates to specialists via `sessions_spawn`.
+
+This example also includes `imageModel` configuration (see below).
+
+### Image Model Routing
+
+The `specialist-agents/` example includes `imageModel` in the defaults block:
+
+```json
+"imageModel": {
+  "primary": "google-gemini-cli/gemini-3-pro-preview",
+  "fallbacks": [
+    "google-gemini-cli/gemini-3-flash-preview",
+    "anthropic/claude-opus-4-6"
+  ]
+}
+```
+
+This routes image analysis (vision) tasks to Gemini Pro first (multimodal, 1M context), with Flash and Opus as fallbacks. Set this in `agents.defaults` to apply to all agents, or per-agent for fine-grained control.
+
+**Gemini setup for specialists:** Copy `gemini-models.json` to every agent that uses Gemini models:
+
+```bash
+# Core agents
+cp examples/specialist-agents/gemini-models.json ~/.openclaw/agents/gemini-researcher/agent/models.json
+cp examples/specialist-agents/gemini-models.json ~/.openclaw/agents/gemini-fast/agent/models.json
+
+# Specialists that fall back to Gemini
+cp examples/specialist-agents/gemini-models.json ~/.openclaw/agents/devops/agent/models.json
+cp examples/specialist-agents/gemini-models.json ~/.openclaw/agents/researcher/agent/models.json
+cp examples/specialist-agents/gemini-models.json ~/.openclaw/agents/content-writer/agent/models.json
+cp examples/specialist-agents/gemini-models.json ~/.openclaw/agents/community/agent/models.json
+```
+
 ## Customizing
 
 - **Workspace paths**: Change `~/.openclaw/workspace-*` to your preferred directories

examples/specialist-agents/gemini-models.json

@@ -0,0 +1,10 @@
+{
+  "google-gemini-cli": {
+    "api": "google-gemini-cli",
+    "models": [
+      { "id": "gemini-3-pro-preview" },
+      { "id": "gemini-3-flash-preview" },
+      { "id": "gemini-2.5-flash-lite" }
+    ]
+  }
+}

examples/specialist-agents/openclaw.json

@@ -0,0 +1,147 @@
+{
+  "models": {
+    "mode": "merge",
+    "providers": {
+      "openai-codex": {
+        "baseUrl": "https://chatgpt.com/backend-api",
+        "api": "openai-responses",
+        "models": [{ "id": "gpt-5.3-codex" }]
+      },
+      "kimi-coding": {
+        "baseUrl": "https://api.kimi.com/coding/v1",
+        "api": "openai-completions",
+        "models": [{ "id": "k2p5" }, { "id": "k2-thinking" }]
+      }
+    }
+  },
+  "agents": {
+    "defaults": {
+      "model": {
+        "primary": "anthropic/claude-opus-4-6",
+        "fallbacks": [
+          "openai-codex/gpt-5.3-codex",
+          "google-gemini-cli/gemini-3-pro-preview",
+          "kimi-coding/k2p5"
+        ]
+      },
+      "imageModel": {
+        "primary": "google-gemini-cli/gemini-3-pro-preview",
+        "fallbacks": [
+          "google-gemini-cli/gemini-3-flash-preview",
+          "anthropic/claude-opus-4-6"
+        ]
+      },
+      "heartbeat": {
+        "model": "google-gemini-cli/gemini-3-flash-preview"
+      }
+    },
+    "list": [
+      {
+        "id": "main",
+        "default": true,
+        "model": {
+          "primary": "anthropic/claude-opus-4-6",
+          "fallbacks": [
+            "openai-codex/gpt-5.3-codex",
+            "google-gemini-cli/gemini-3-pro-preview",
+            "kimi-coding/k2p5"
+          ]
+        },
+        "workspace": "~/.openclaw/workspace"
+      },
+      {
+        "id": "codex",
+        "model": {
+          "primary": "openai-codex/gpt-5.3-codex",
+          "fallbacks": [
+            "anthropic/claude-opus-4-6",
+            "google-gemini-cli/gemini-3-pro-preview",
+            "kimi-coding/k2p5"
+          ]
+        },
+        "workspace": "~/.openclaw/workspace-codex"
+      },
+      {
+        "id": "gemini-researcher",
+        "model": {
+          "primary": "google-gemini-cli/gemini-3-pro-preview",
+          "fallbacks": [
+            "google-gemini-cli/gemini-3-flash-preview",
+            "anthropic/claude-opus-4-6",
+            "openai-codex/gpt-5.3-codex"
+          ]
+        },
+        "workspace": "~/.openclaw/workspace"
+      },
+      {
+        "id": "gemini-fast",
+        "model": {
+          "primary": "google-gemini-cli/gemini-3-flash-preview",
+          "fallbacks": [
+            "google-gemini-cli/gemini-3-pro-preview",
+            "anthropic/claude-opus-4-6",
+            "openai-codex/gpt-5.3-codex"
+          ]
+        },
+        "workspace": "~/.openclaw/workspace"
+      },
+      {
+        "id": "kimi-orchestrator",
+        "model": {
+          "primary": "kimi-coding/k2p5",
+          "fallbacks": [
+            "kimi-coding/k2-thinking",
+            "google-gemini-cli/gemini-3-pro-preview",
+            "anthropic/claude-opus-4-6"
+          ]
+        },
+        "workspace": "~/.openclaw/workspace"
+      },
+
+      {
+        "id": "devops",
+        "model": {
+          "primary": "openai-codex/gpt-5.3-codex",
+          "fallbacks": [
+            "anthropic/claude-opus-4-6",
+            "google-gemini-cli/gemini-3-pro-preview"
+          ]
+        },
+        "workspace": "~/.openclaw/workspace-devops"
+      },
+      {
+        "id": "researcher",
+        "model": {
+          "primary": "google-gemini-cli/gemini-3-pro-preview",
+          "fallbacks": [
+            "google-gemini-cli/gemini-3-flash-preview",
+            "anthropic/claude-opus-4-6"
+          ]
+        },
+        "workspace": "~/.openclaw/workspace-research"
+      },
+      {
+        "id": "content-writer",
+        "model": {
+          "primary": "anthropic/claude-opus-4-6",
+          "fallbacks": [
+            "google-gemini-cli/gemini-3-pro-preview",
+            "openai-codex/gpt-5.3-codex"
+          ]
+        },
+        "workspace": "~/.openclaw/workspace-content"
+      },
+      {
+        "id": "community",
+        "model": {
+          "primary": "google-gemini-cli/gemini-3-flash-preview",
+          "fallbacks": [
+            "google-gemini-cli/gemini-3-pro-preview",
+            "anthropic/claude-opus-4-6"
+          ]
+        },
+        "workspace": "~/.openclaw/workspace-community"
+      }
+    ]
+  }
+}