Configure models

Ninja is multi-role. Different agents can use different base URLs, API keys, and model IDs.

Roles

Environment variables

# Planner
export OPENAI_BASE_URL="https://api.example.com/v1"
export OPENAI_API_KEY="sk-..."
export OPENAI_MODEL="planner-model"

# Default for all subagents (unless overridden per role)
export NINJA_SUBAGENT_BASE_URL="http://localhost:8080"
export NINJA_SUBAGENT_API_KEY="sk-local"   # optional
export NINJA_SUBAGENT_MODEL="coder-model"

Base URL tips

Use an OpenAI-compatible base URL (same idea as popular OpenAI SDKs):

• Bare host (e.g. http://localhost:8080) — Ninja adds the usual /v1/... chat path
• Already ending in /v1 — left as-is, then chat path is appended

Local servers often need no API key. Cloud providers need OPENAI_API_KEY (or the matching role key).

Per-role overrides (config.json)

{
  "openai_base_url": "https://api.example.com/v1",
  "openai_api_key": "REPLACE_PLANNER_KEY",
  "openai_model": "planner-model",

  "ninja_subagent_base_url": "http://localhost:8080",
  "ninja_subagent_model": "coder-model",

  "subagent_roles": {
    "coder": {
      "base_url": "http://localhost:8080",
      "model": "coder-model"
    },
    "reviewer": {
      "base_url": "https://api.example.com/v1",
      "api_key": "REPLACE_REVIEWER_KEY",
      "model": "review-model"
    },
    "final_review": {
      "base_url": "https://api.example.com/v1",
      "api_key": "REPLACE_FINAL_KEY",
      "model": "review-model"
    }
  }
}

Useful role fields

Precedence: role override → NINJA_SUBAGENT_* → OPENAI_*.

Interactive /model (TUI)

Multi-model plan panel

Optional plan_panel entries power multi-model planning when you use the plan-debate skill. Each model drafts from a different angle, then they critique each other; the planner synthesizes one plan.

Add this to config.json (alongside your normal openai_* / subagent settings):

{
  "plan_panel": [
    {
      "name": "risk-lens",
      "base_url": "https://api.example.com/v1",
      "api_key": "REPLACE_PANEL_KEY_1",
      "model": "strong-reasoner-model",
      "lens": "risk-first"
    },
    {
      "name": "simple-lens",
      "base_url": "https://api.example.com/v1",
      "api_key": "REPLACE_PANEL_KEY_2",
      "model": "another-strong-model",
      "lens": "simplicity-first"
    }
  ]
}

Lenses

A lens is a short planning bias for one panel model in Round 1. It is not a model id — it only steers how that seat drafts (risk vs simplicity, etc.). Different lenses keep strong models from writing the same plan.

Five built-in defaults (used when lens is omitted — assigned round-robin, then wraps):

You can set a custom string (e.g. cost-first); it is passed through as free text. The five names above are the recommended defaults, not a hard allow-list.

Notes:

• You need at least two working panel models (or Ninja falls back to single-model planning).
• Panel models can reuse the same gateway as the planner with different model names, or call different providers.
• After config is saved, ask in chat, e.g. plan the auth refactor with the plan-debate skill.

First-run config.example.json on your machine includes a filled plan_panel block you can copy.

Recommended layouts

Related

• config.json
• Environment variables

Ninja CLI documentation — configuration and usage. Back to ninja-cli