diff --git a/README.md b/README.md index a312938..4ab36df 100644 --- a/README.md +++ b/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 diff --git a/SKILL.md b/SKILL.md index 5837340..9bf902b 100644 --- a/SKILL.md +++ b/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) diff --git a/examples/README.md b/examples/README.md index 0ea9634..9119376 100644 --- a/examples/README.md +++ b/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 diff --git a/examples/specialist-agents/gemini-models.json b/examples/specialist-agents/gemini-models.json new file mode 100644 index 0000000..699a095 --- /dev/null +++ b/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" } + ] + } +} diff --git a/examples/specialist-agents/openclaw.json b/examples/specialist-agents/openclaw.json new file mode 100644 index 0000000..4518bb1 --- /dev/null +++ b/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" + } + ] + } +}