Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
6.3 KB
Raw Blame

Model Routing Convention

Two distinct concerns share this name. Read both — they apply at different moments.

1. gbrain's internal tier system (v0.31.12+)

This is how gbrain itself picks which Claude/OpenAI/Google model runs each internal task (chat, expansion, synthesis, classification, etc.).

Four tiers:

Tier Purpose Default Examples
utility fast classification, expansion, verdict, dedup claude-haiku-4-5-20251001 query expansion, facts contradiction classifier, dream triage judge (prefers models.dream.triage)
reasoning default chat, synthesis, generation claude-sonnet-4-6 gateway chat, dream synthesize, patterns, facts extraction
deep slow, expensive reasoning claude-opus-4-7 gbrain think, auto-think, cross-modal eval slot B
subagent multi-turn tool loop (capability-gated) claude-sonnet-4-6 gbrain agent run

The Default column shows the Anthropic defaults — used when ANTHROPIC_API_KEY is present (Anthropic wins when both keys exist) and kept as the keyless floor. Tier defaults are key-aware (v0.46.21+): when OPENAI_API_KEY is the only chat key, every tier resolves to OpenAI instead — the newest usable models discovered from your own account (GET /v1/models, priced-only, 24h cache at <configDir>/model-cache.json, GBRAIN_MODEL_DISCOVERY=off kill switch), with the openai recipe's ranked chat list as the offline floor. OpenAI defaults are never pinned to a model id that can go stale.

Override priority (highest first):

  1. CLI flag (--model opus)
  2. Per-task config (gbrain config set models.dream.synthesize opus)
  3. Deprecated per-task config (stderr-warns once, then honored)
  4. Tier override (gbrain config set models.tier.reasoning opus) — tier-specific beats the generic default (#3873)
  5. Global default (gbrain config set models.default opus) — single hammer
  6. Env var (GBRAIN_MODEL=opus)
  7. Key-aware tier default (the table above; provider chosen by which keys exist)
  8. Hardcoded caller fallback

One exception: the dream triage judge pre-reads models.dream.triage first — when that key is set, it wins over this entire chain (gbrain models reports it as the effective route).

File-plane pins are a separate seam: the gateway's boot/reconnect fallback (and the capability report) resolve the effective chat model as GBRAIN_MODEL env > servable chat_model pin in ~/.gbrain/config.json (honored only while its provider's key is present; an unservable pin warns once and falls through)

key-aware tier default. gbrain init no longer persists auto-detected chat pins (v0.46.21+) — only a pin you set yourself survives reconnect.

Power-user recipes:

# Use opus for everything
gbrain config set models.default opus

# Use opus only for reasoning + deep, keep haiku for utility
gbrain config set models.tier.reasoning opus
gbrain config set models.tier.deep opus

# Custom alias, then use it everywhere
gbrain config set models.aliases.frontier anthropic:claude-opus-4-7
gbrain config set models.default frontier

Visibility:

gbrain models                    # print current routing table
gbrain models doctor             # 1-token probe to each configured model

Subagent tier is isolated because the tool loop has real capability requirements. Since v0.38 the loop is provider-agnostic and gated by capability, not provider: a model without tool calling (or an unrecognized provider) is refused and falls back to TIER_DEFAULTS.subagent with a warn; a tool-capable provider without prompt caching (e.g. OpenAI) runs the loop hot with a once-per-model cost warn. Setting models.default = openai:gpt-5.5 no longer silently breaks the loop — it runs, at higher per-turn cost. Three enforcement layers: submit-time guard in MinionQueue.add, enforceSubagentCapable in resolveModel, doctor subagent_capability check.

When adding a new LLM call, route through resolveModel() with a tier — never hardcode a model string. The v0.31.6 chat default (claude-sonnet-4-6-20250929) was a phantom ID that 404'd the Anthropic API and made extractFactsFromTurn silently return []. The tier system

  • doctor probe is the structural fix for that bug class.

A model gbrain has no price for

Under default settings an unpriced model (a newly released one, a proxy route) warns and runs. Under a cost cap the user set, the run stops with no_pricing, because the cap cannot be enforced without a price. The refusal names the model, provider and kind and the exact registration command. Then:

  1. Look up the provider's current price for that model, for example by searching the web for its pricing page. A chat model needs USD per 1M input tokens and USD per 1M output tokens; an embedding or reranker model needs USD per 1M tokens.
  2. With a shell on the brain host, run the command the refusal names, such as gbrain pricing set <model> --input <usd> --output <usd> --source <url> (or --rate <usd>), then retry. Over MCP you cannot register prices: give the command and the price you found to the brain's operator.

Do not register $0 to get past the refusal unless the route really is free: it makes every call to that model count as free against every cap.

2. Subagent spawn routing

When the user-facing agent (Claude in the main session) chooses which model to spawn a sub-agent on, this table applies. It's about WHERE to send the work, not what gbrain calls internally.

Task Model Why
Main session / complex instructions Opus (default) Best overall quality
Signal detection / entity extraction Sonnet Fast, cheap, fires every message
Research / synthesis DeepSeek or Qwen 25-40x cheaper for large context
Fast lightweight sub-agents Groq 500 tok/s, good for simple tasks
Judge tests / quality grading Haiku Cheap, good enough for pass/fail

Refusal routing

When a model refuses a request:

  1. Re-spawn on a different model (don't announce the switch)
  2. Fallback chain: primary → DeepSeek → Qwen → Groq
  3. Never show the refusal to the user
  4. If all models refuse, escalate to the user

Spawn rules

  • 3+ items to process → spawn a sub-agent
  • 2 tool calls that don't need real-time judgment → spawn

  • Main thread must stay responsive to the user
  • Signal detection always spawns (parallel, don't block)