oh-my-openagent/docs/reference/configuration.md

Configuration Reference

Complete reference for Oh My OpenCode plugin configuration. During the rename transition, the runtime recognizes both oh-my-openagent.json[c] and legacy oh-my-opencode.json[c] files.

---

Table of Contents

• Getting Started
  • File Locations
  • Quick Start Example
• Core Concepts
  • Agents
  • Categories
  • Model Resolution
• Task System
  • Background Tasks
  • Sisyphus Agent
  • Sisyphus Tasks
• Features
  • Skills
  • Hooks
  • Commands
  • Browser Automation
  • Tmux Integration
  • Git Master
  • Comment Checker
  • Notification
  • MCPs
  • LSP
• Advanced
  • Runtime Fallback
  • Model Capabilities
  • Hashline Edit
  • Experimental
• Reference
  • Environment Variables
  • Provider-Specific

---

Getting Started

File Locations

User config is loaded first, then project config overrides it. In each directory, the compatibility layer recognizes both the renamed and legacy basenames.

1. Project config: .opencode/oh-my-openagent.json[c] or .opencode/oh-my-opencode.json[c]
2. User config (.jsonc preferred over .json):

Platform	Path candidates
macOS/Linux	~/.config/opencode/oh-my-openagent.json[c], ~/.config/opencode/oh-my-opencode.json[c]
Windows	%APPDATA%\opencode\oh-my-openagent.json[c], %APPDATA%\opencode\oh-my-opencode.json[c]

Rename compatibility: The published package and CLI binary remain oh-my-opencode. OpenCode plugin registration prefers oh-my-openagent, while legacy oh-my-opencode entries and config basenames still load during the transition. Config detection checks oh-my-opencode before oh-my-openagent, so if both plugin config basenames exist in the same directory, the legacy oh-my-opencode.* file currently wins. JSONC supports // line comments, /* block comments */, and trailing commas.

Enable schema autocomplete:

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json"
}

Run bunx oh-my-opencode install for guided setup. Run opencode models to list available models.

Quick Start Example

Here's a practical starting configuration:

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",

  "agents": {
    // Main orchestrator: Claude Opus or Kimi K2.5 work best
    "sisyphus": {
      "model": "kimi-for-coding/k2p5",
      "ultrawork": { "model": "anthropic/claude-opus-4-6", "variant": "max" },
    },

    // Research agents: cheap fast models are fine
    "librarian": { "model": "google/gemini-3-flash" },
    "explore": { "model": "github-copilot/grok-code-fast-1" },

    // Architecture consultation: GPT-5.4 or Claude Opus
    "oracle": { "model": "openai/gpt-5.4", "variant": "high" },

    // Prometheus inherits sisyphus model; just add prompt guidance
    "prometheus": {
      "prompt_append": "Leverage deep & quick agents heavily, always in parallel.",
    },
  },

  "categories": {
    // quick - trivial tasks
    "quick": { "model": "opencode/gpt-5-nano" },

    // unspecified-low - moderate tasks
    "unspecified-low": { "model": "anthropic/claude-sonnet-4-6" },

    // unspecified-high - complex work
    "unspecified-high": { "model": "anthropic/claude-opus-4-6", "variant": "max" },

    // writing - docs/prose
    "writing": { "model": "google/gemini-3-flash" },

    // visual-engineering - Gemini dominates visual tasks
    "visual-engineering": {
      "model": "google/gemini-3.1-pro",
      "variant": "high",
    },

    // Custom category for git operations
    "git": {
      "model": "opencode/gpt-5-nano",
      "description": "All git operations",
      "prompt_append": "Focus on atomic commits, clear messages, and safe operations.",
    },
  },

  // Limit expensive providers; let cheap ones run freely
  "background_task": {
    "providerConcurrency": {
      "anthropic": 3,
      "openai": 3,
      "opencode": 10,
      "zai-coding-plan": 10,
    },
    "modelConcurrency": {
      "anthropic/claude-opus-4-6": 2,
      "opencode/gpt-5-nano": 20,
    },
  },

  "experimental": { "aggressive_truncation": true, "task_system": true },
  "tmux": { "enabled": false },
}

---

Core Concepts

Agents

Override built-in agent settings. Available agents: sisyphus, hephaestus, prometheus, oracle, librarian, explore, multimodal-looker, metis, momus, atlas.

{
  "agents": {
    "explore": { "model": "anthropic/claude-haiku-4-5", "temperature": 0.5 },
    "multimodal-looker": { "disable": true }
  }
}

Disable agents entirely: { "disabled_agents": ["oracle", "multimodal-looker"] }

Core agents receive an injected runtime order field for deterministic Tab cycling in the UI: Sisyphus = 1, Hephaestus = 2, Prometheus = 3, Atlas = 4. This is not a user-configurable config key.

Agent Options

Option	Type	Description
model	string	Model override (provider/model)
fallback_models	string|array	Fallback models on API errors. Supports strings or mixed arrays of strings and object entries with per-model settings
temperature	number	Sampling temperature
top_p	number	Top-p sampling
prompt	string	Replace system prompt. Supports file:// URIs
prompt_append	string	Append to system prompt. Supports file:// URIs
tools	array	Allowed tools list
disable	boolean	Disable this agent
mode	string	Agent mode
color	string	UI color
permission	object	Per-tool permissions (see below)
category	string	Inherit model from category
variant	string	Model variant: max, high, medium, low, xhigh. Normalized to supported values
maxTokens	number	Max response tokens
thinking	object	Anthropic extended thinking
reasoningEffort	string	OpenAI reasoning: none, minimal, low, medium, high, xhigh. Normalized to supported values
textVerbosity	string	Text verbosity: low, medium, high
providerOptions	object	Provider-specific options

Anthropic Extended Thinking

{
  "agents": {
    "oracle": { "thinking": { "type": "enabled", "budgetTokens": 200000 } }
  }
}

Agent Permissions

Control what tools an agent can use:

{
  "agents": {
    "explore": {
      "permission": {
        "edit": "deny",
        "bash": "ask",
        "webfetch": "allow"
      }
    }
  }
}

Permission	Values
edit	ask / allow / deny
bash	ask / allow / deny or per-command: { "git": "allow", "rm": "deny" }
webfetch	ask / allow / deny
doom_loop	ask / allow / deny
external_directory	ask / allow / deny

Fallback Models with Per-Model Settings

fallback_models accepts either a single model string or an array. Array entries can be plain strings or objects with individual model settings:

{
  "agents": {
    "sisyphus": {
      "model": "anthropic/claude-opus-4-6",
      "fallback_models": [
        // Simple string fallback
        "openai/gpt-5.4",
        // Object with per-model settings
        {
          "model": "google/gemini-3.1-pro",
          "variant": "high",
          "temperature": 0.2
        },
        {
          "model": "anthropic/claude-sonnet-4-6",
          "thinking": { "type": "enabled", "budgetTokens": 64000 }
        }
      ]
    }
  }
}

Object entries support: model, variant, reasoningEffort, temperature, top_p, maxTokens, thinking.

File URIs for Prompts

Both prompt and prompt_append support loading content from files via file:// URIs. Category-level prompt_append supports the same URI forms.

{
  "agents": {
    "sisyphus": {
      "prompt_append": "file:///absolute/path/to/prompt.txt"
    },
    "oracle": {
      "prompt": "file://./relative/to/project/prompt.md"
    },
    "explore": {
      "prompt_append": "file://~/home/dir/prompt.txt"
    }
  },
  "categories": {
    "custom": {
      "model": "anthropic/claude-sonnet-4-6",
      "prompt_append": "file://./category-context.md"
    }
  }
}

Paths can be absolute (file:///abs/path), relative to project root (file://./rel/path), or home-relative (file://~/home/path). If a file URI cannot be decoded, resolved, or read, OmO inserts a warning placeholder into the prompt instead of failing hard.

Categories

Domain-specific model delegation used by the task() tool. When Sisyphus delegates work, it picks a category, not a model name.

Built-in Categories

Category	Default Model	Description
visual-engineering	google/gemini-3.1-pro (high)	Frontend, UI/UX, design, animation
ultrabrain	openai/gpt-5.4 (xhigh)	Deep logical reasoning, complex architecture
deep	openai/gpt-5.3-codex (medium)	Autonomous problem-solving, thorough research
artistry	google/gemini-3.1-pro (high)	Creative/unconventional approaches
quick	openai/gpt-5.4-mini	Trivial tasks, typo fixes, single-file changes
unspecified-low	anthropic/claude-sonnet-4-6	General tasks, low effort
unspecified-high	anthropic/claude-opus-4-6 (max)	General tasks, high effort
writing	google/gemini-3-flash	Documentation, prose, technical writing

Note

: Built-in defaults only apply if the category is present in your config. Otherwise the system default model is used.

Category Options

Option	Type	Default	Description
model	string	-	Model override
fallback_models	string|array	-	Fallback models on API errors. Supports strings or mixed arrays of strings and object entries with per-model settings
temperature	number	-	Sampling temperature
top_p	number	-	Top-p sampling
maxTokens	number	-	Max response tokens
thinking	object	-	Anthropic extended thinking
reasoningEffort	string	-	OpenAI reasoning effort. Unsupported values are normalized
textVerbosity	string	-	Text verbosity
tools	array	-	Allowed tools
prompt_append	string	-	Append to system prompt
variant	string	-	Model variant. Unsupported values are normalized
description	string	-	Shown in task() tool prompt
is_unstable_agent	boolean	false	Force background mode + monitoring. Auto-enabled for Gemini models.

Disable categories: { "disabled_categories": ["ultrabrain"] }

Model Resolution

Runtime priority:

1. UI-selected model - model chosen in the OpenCode UI, for primary agents
2. User override - model set in config → used exactly as-is. Even on cold cache, explicit user configuration takes precedence over hardcoded fallback chains
3. Category default - model inherited from the assigned category config
4. User fallback_models - user-configured fallback list is tried before built-in fallback chains
5. Provider fallback chain - built-in provider/model chain from OmO source
6. System default - OpenCode's configured default model

Model Settings Compatibility

Model settings are compatibility-normalized against model capabilities instead of failing hard.

Normalized fields:

• variant - downgraded to the closest supported value
• reasoningEffort - downgraded to the closest supported value, or removed if unsupported
• temperature - removed if unsupported by the model metadata
• top_p - removed if unsupported by the model metadata
• maxTokens - capped to the model's reported max output limit
• thinking - removed if the target model does not support thinking

Examples:

• Claude models do not support reasoningEffort - it is removed automatically
• GPT-4.1 does not support reasoning - reasoningEffort is removed
• o-series models support none through high - xhigh is downgraded to high
• GPT-5 supports none, minimal, low, medium, high, xhigh - all pass through

Capability data comes from provider runtime metadata first. OmO also ships bundled models.dev-backed capability data, supports a refreshable local models.dev cache, and falls back to heuristic family detection plus alias rules when exact metadata is unavailable. bunx oh-my-opencode doctor surfaces capability diagnostics and warns when a configured model relies on compatibility fallback.

Agent Provider Chains

Agent	Default Model	Provider Priority
Sisyphus	claude-opus-4-6	claude-opus-4-6 (max) → kimi-k2.5 via OpenCode Go / Kimi providers → gpt-5.4 (medium) → glm-5 → big-pickle
Hephaestus	gpt-5.4	gpt-5.4 (medium)
oracle	gpt-5.4	gpt-5.4 (high) → gemini-3.1-pro (high) → claude-opus-4-6 (max) → glm-5
librarian	minimax-m2.7	opencode-go/minimax-m2.7 → opencode/minimax-m2.5 → claude-haiku-4-5 → gpt-5-nano
explore	grok-code-fast-1	grok-code-fast-1 → opencode-go/minimax-m2.7 → opencode/minimax-m2.5 → claude-haiku-4-5 → gpt-5-nano
multimodal-looker	gpt-5.4	gpt-5.4 (medium) → kimi-k2.5 → glm-4.6v → gpt-5-nano
Prometheus	claude-opus-4-6	claude-opus-4-6 (max) → gpt-5.4 (high) → glm-5 → gemini-3.1-pro
Metis	claude-opus-4-6	claude-opus-4-6 (max) → gpt-5.4 (high) → glm-5 → k2p5
Momus	gpt-5.4	gpt-5.4 (xhigh) → claude-opus-4-6 (max) → gemini-3.1-pro (high) → glm-5
Atlas	claude-sonnet-4-6	claude-sonnet-4-6 → kimi-k2.5 → gpt-5.4 (medium) → minimax-m2.7

Category Provider Chains

Category	Default Model	Provider Priority
visual-engineering	gemini-3.1-pro	gemini-3.1-pro → glm-5 → claude-opus-4-6
ultrabrain	gpt-5.4	gpt-5.4 → gemini-3.1-pro → claude-opus-4-6
deep	gpt-5.3-codex	gpt-5.3-codex → claude-opus-4-6 → gemini-3.1-pro
artistry	gemini-3.1-pro	gemini-3.1-pro → claude-opus-4-6 → gpt-5.4
quick	gpt-5.4-mini	gpt-5.4-mini → claude-haiku-4-5 → gemini-3-flash → minimax-m2.7 → gpt-5-nano
unspecified-low	claude-sonnet-4-6	claude-sonnet-4-6 → gpt-5.3-codex → gemini-3-flash → minimax-m2.7
unspecified-high	claude-opus-4-6	claude-opus-4-6 → gpt-5.4 (high) → glm-5 → k2p5 → kimi-k2.5
writing	gemini-3-flash	gemini-3-flash → claude-sonnet-4-6 → minimax-m2.7

Run bunx oh-my-opencode doctor --verbose to see effective model resolution for your config.

---

Task System

Background Tasks

Control parallel agent execution and concurrency limits.

{
  "background_task": {
    "defaultConcurrency": 5,
    "staleTimeoutMs": 180000,
    "providerConcurrency": { "anthropic": 3, "openai": 5, "google": 10 },
    "modelConcurrency": { "anthropic/claude-opus-4-6": 2 }
  }
}

Option	Default	Description
defaultConcurrency	-	Max concurrent tasks (all providers)
staleTimeoutMs	180000	Interrupt tasks with no activity (min: 60000)
providerConcurrency	-	Per-provider limits (key = provider name)
modelConcurrency	-	Per-model limits (key = provider/model). Overrides provider limits.

Priority: modelConcurrency > providerConcurrency > defaultConcurrency

Sisyphus Agent

Configure the main orchestration system.

{
  "sisyphus_agent": {
    "disabled": false,
    "default_builder_enabled": false,
    "planner_enabled": true,
    "replace_plan": true
  }
}

Option	Default	Description
disabled	false	Disable all Sisyphus orchestration, restore original build/plan
default_builder_enabled	false	Enable OpenCode-Builder agent (off by default)
planner_enabled	true	Enable Prometheus (Planner) agent
replace_plan	true	Demote default plan agent to subagent mode

Sisyphus agents can also be customized under agents using their names: Sisyphus, OpenCode-Builder, Prometheus (Planner), Metis (Plan Consultant).

Sisyphus Tasks

Enable the Sisyphus Tasks system for cross-session task tracking.

{
  "sisyphus": {
    "tasks": {
      "enabled": false,
      "storage_path": ".sisyphus/tasks",
      "claude_code_compat": false
    }
  }
}

Option	Default	Description
enabled	false	Enable Sisyphus Tasks system
storage_path	.sisyphus/tasks	Storage path (relative to project root)
claude_code_compat	false	Enable Claude Code path compatibility mode

---

Features

Skills

Skills bring domain-specific expertise and embedded MCPs.

Built-in skills: playwright, playwright-cli, agent-browser, dev-browser, git-master, frontend-ui-ux

Disable built-in skills: { "disabled_skills": ["playwright"] }

Skills Configuration

{
  "skills": {
    "sources": [
      { "path": "./my-skills", "recursive": true },
      "https://example.com/skill.yaml"
    ],
    "enable": ["my-skill"],
    "disable": ["other-skill"],
    "my-skill": {
      "description": "What it does",
      "template": "Custom prompt template",
      "from": "source-file.ts",
      "model": "custom/model",
      "agent": "custom-agent",
      "subtask": true,
      "argument-hint": "usage hint",
      "license": "MIT",
      "compatibility": ">= 3.0.0",
      "metadata": { "author": "Your Name" },
      "allowed-tools": ["read", "bash"]
    }
  }
}

sources option	Default	Description
path	-	Local path or remote URL
recursive	false	Recurse into subdirectories
glob	-	Glob pattern for file selection

Hooks

Disable built-in hooks via disabled_hooks:

{ "disabled_hooks": ["comment-checker"] }

Available hooks: todo-continuation-enforcer, context-window-monitor, session-recovery, session-notification, comment-checker, grep-output-truncator, tool-output-truncator, directory-agents-injector, directory-readme-injector, empty-task-response-detector, think-mode, anthropic-context-window-limit-recovery, rules-injector, background-notification, auto-update-checker, startup-toast, keyword-detector, agent-usage-reminder, non-interactive-env, interactive-bash-session, compaction-context-injector, thinking-block-validator, claude-code-hooks, ralph-loop, preemptive-compaction, auto-slash-command, sisyphus-junior-notepad, no-sisyphus-gpt, start-work, runtime-fallback

Notes:

• directory-agents-injector - auto-disabled on OpenCode 1.1.37+ (native AGENTS.md support)
• no-sisyphus-gpt - do not disable. It blocks incompatible GPT models for Sisyphus while allowing the dedicated GPT-5.4 prompt path.
• startup-toast is a sub-feature of auto-update-checker. Disable just the toast by adding startup-toast to disabled_hooks.
• session-recovery - automatically recovers from recoverable session errors (missing tool results, unavailable tools, thinking block violations). Shows toast notifications during recovery. Enable experimental.auto_resume for automatic retry after recovery.

Commands

Disable built-in commands via disabled_commands:

{ "disabled_commands": ["init-deep", "start-work"] }

Available commands: init-deep, ralph-loop, ulw-loop, cancel-ralph, refactor, start-work, stop-continuation, handoff

Browser Automation

Provider	Interface	Installation
playwright (default)	MCP tools	Auto-installed via npx
agent-browser	Bash CLI	bun add -g agent-browser && agent-browser install

Switch provider:

{ "browser_automation_engine": { "provider": "agent-browser" } }

Tmux Integration

Run background subagents in separate tmux panes. Requires running inside tmux with opencode --port <port>.

{
  "tmux": {
    "enabled": true,
    "layout": "main-vertical",
    "main_pane_size": 60,
    "main_pane_min_width": 120,
    "agent_pane_min_width": 40
  }
}

Option	Default	Description
enabled	false	Enable tmux pane spawning
layout	main-vertical	main-vertical / main-horizontal / tiled / even-horizontal / even-vertical
main_pane_size	60	Main pane % (20–80)
main_pane_min_width	120	Min main pane columns
agent_pane_min_width	40	Min agent pane columns

Git Master

Configure git commit behavior:

{ "git_master": { "commit_footer": true, "include_co_authored_by": true } }

Comment Checker

Customize the comment quality checker:

{
  "comment_checker": {
    "custom_prompt": "Your message. Use {{comments}} placeholder."
  }
}

Notification

Force-enable session notifications:

{ "notification": { "force_enable": true } }

force_enable (false) - force session-notification even if external notification plugins are detected.

MCPs

Built-in MCPs (enabled by default): websearch (Exa AI), context7 (library docs), grep_app (GitHub code search).

{ "disabled_mcps": ["websearch", "context7", "grep_app"] }

LSP

Configure Language Server Protocol integration:

{
  "lsp": {
    "typescript-language-server": {
      "command": ["typescript-language-server", "--stdio"],
      "extensions": [".ts", ".tsx"],
      "priority": 10,
      "env": { "NODE_OPTIONS": "--max-old-space-size=4096" },
      "initialization": {
        "preferences": { "includeInlayParameterNameHints": "all" }
      }
    },
    "pylsp": { "disabled": true }
  }
}

Option	Type	Description
command	array	Command to start LSP server
extensions	array	File extensions (e.g. [".ts"])
priority	number	Priority when multiple servers match
env	object	Environment variables
initialization	object	Init options passed to server
disabled	boolean	Disable this server

---

Advanced

Runtime Fallback

Auto-switches to backup models on API errors.

Simple configuration (enable/disable with defaults):

{ "runtime_fallback": true }
{ "runtime_fallback": false }

Advanced configuration (full control):

{
  "runtime_fallback": {
    "enabled": true,
    "retry_on_errors": [400, 429, 503, 529],
    "max_fallback_attempts": 3,
    "cooldown_seconds": 60,
    "timeout_seconds": 30,
    "notify_on_fallback": true
  }
}

Option	Default	Description
enabled	false	Enable runtime fallback
retry_on_errors	[400,429,503,529]	HTTP codes that trigger fallback. Also handles classified provider key errors.
max_fallback_attempts	3	Max fallback attempts per session (1–20)
cooldown_seconds	60	Seconds before retrying a failed model
timeout_seconds	30	Seconds before forcing next fallback. Set to 0 to disable timeout-based escalation and provider retry message detection.
notify_on_fallback	true	Toast notification on model switch

Define fallback_models per agent or category:

{
  "agents": {
    "sisyphus": {
      "model": "anthropic/claude-opus-4-6",
      "fallback_models": [
        "openai/gpt-5.4",
        {
          "model": "google/gemini-3.1-pro",
          "variant": "high"
        }
      ]
    }
  }
}

fallback_models also supports object-style entries so you can attach settings to a specific fallback model:

{
  "agents": {
    "sisyphus": {
      "model": "anthropic/claude-opus-4-6",
      "fallback_models": [
        "openai/gpt-5.4",
        {
          "model": "anthropic/claude-sonnet-4-6",
          "variant": "high",
          "thinking": { "type": "enabled", "budgetTokens": 12000 }
        },
        {
          "model": "openai/gpt-5.3-codex",
          "reasoningEffort": "high",
          "temperature": 0.2,
          "top_p": 0.95,
          "maxTokens": 8192
        }
      ]
    }
  }
}

Mixed arrays are allowed, so string entries and object entries can appear together in the same fallback chain.

Object-style fallback_models

Object entries use the following shape:

Field	Type	Description
model	string	Fallback model ID. Provider prefix is optional when OmO can inherit the current/default provider.
variant	string	Explicit variant override for this fallback entry.
reasoningEffort	string	OpenAI reasoning effort override for this fallback entry.
temperature	number	Temperature applied if this fallback model becomes active.
top_p	number	Top-p applied if this fallback model becomes active.
maxTokens	number	Max response tokens applied if this fallback model becomes active.
thinking	object	Anthropic thinking config applied if this fallback model becomes active.

Per-model settings are fallback-only. They are promoted only when that specific fallback model is actually selected, so they do not override your primary model settings when the primary model resolves successfully.

thinking uses the same shape as the normal agent/category option:

Field	Type	Description
type	string	enabled or disabled
budgetTokens	number	Optional Anthropic thinking budget

Object entries can also omit the provider prefix when OmO can infer it from the current/default provider. If you provide both inline variant syntax in model and an explicit variant field, the explicit variant field wins.

Full examples

1. Simple string chain

Use strings when you only need an ordered fallback chain:

{
  "agents": {
    "atlas": {
      "model": "anthropic/claude-sonnet-4-6",
      "fallback_models": [
        "anthropic/claude-haiku-4-5",
        "openai/gpt-5.4",
        "google/gemini-3.1-pro"
      ]
    }
  }
}

2. Same-provider shorthand

If the primary model already establishes the provider, fallback entries can omit the prefix:

{
  "agents": {
    "atlas": {
      "model": "openai/gpt-5.4",
      "fallback_models": [
        "gpt-5.4-mini",
        {
          "model": "gpt-5.3-codex",
          "reasoningEffort": "medium",
          "maxTokens": 4096
        }
      ]
    }
  }
}

In this example OmO treats gpt-5.4-mini and gpt-5.3-codex as OpenAI fallback entries because the current/default provider is already openai.

3. Mixed cross-provider chain

Mix string entries and object entries when only some fallback models need special settings:

{
  "agents": {
    "sisyphus": {
      "model": "anthropic/claude-opus-4-6",
      "fallback_models": [
        "openai/gpt-5.4",
        {
          "model": "anthropic/claude-sonnet-4-6",
          "variant": "high",
          "thinking": { "type": "enabled", "budgetTokens": 12000 }
        },
        {
          "model": "google/gemini-3.1-pro",
          "variant": "high"
        }
      ]
    }
  }
}

4. Category-level fallback chain

fallback_models works the same way under categories:

{
  "categories": {
    "deep": {
      "model": "openai/gpt-5.3-codex",
      "fallback_models": [
        {
          "model": "openai/gpt-5.4",
          "reasoningEffort": "xhigh",
          "maxTokens": 12000
        },
        {
          "model": "anthropic/claude-opus-4-6",
          "variant": "max",
          "temperature": 0.2
        },
        "google/gemini-3.1-pro(high)"
      ]
    }
  }
}

5. Full object entry with every supported field

This shows every supported object-style parameter in one place:

{
  "agents": {
    "oracle": {
      "model": "openai/gpt-5.4",
      "fallback_models": [
        {
          "model": "openai/gpt-5.3-codex(low)",
          "variant": "xhigh",
          "reasoningEffort": "high",
          "temperature": 0.3,
          "top_p": 0.9,
          "maxTokens": 8192,
          "thinking": {
            "type": "disabled"
          }
        }
      ]
    }
  }
}

In this example the explicit "variant": "xhigh" overrides the inline (low) suffix in "model".

This final example is a complete shape reference. In real configs, prefer provider-appropriate settings:

• use reasoningEffort for OpenAI reasoning models
• use thinking for Anthropic thinking-capable models
• use variant, temperature, top_p, and maxTokens only when that fallback model supports them

Model Capabilities

OmO can refresh a local models.dev capability snapshot on startup. This cache is controlled by model_capabilities.

{
  "model_capabilities": {
    "enabled": true,
    "auto_refresh_on_start": true,
    "refresh_timeout_ms": 5000,
    "source_url": "https://models.dev/api.json"
  }
}

Option	Default behavior	Description
enabled	enabled unless explicitly set to false	Master switch for model capability refresh behavior
auto_refresh_on_start	refresh on startup unless explicitly set to false	Refresh the local models.dev cache during startup checks
refresh_timeout_ms	5000	Timeout for the startup refresh attempt
source_url	https://models.dev/api.json	Override the models.dev source URL

Notes:

• Startup refresh runs through the auto-update checker hook.
• Manual refresh is available via bunx oh-my-opencode refresh-model-capabilities.
• Provider runtime metadata still takes priority when OmO resolves capabilities for compatibility checks.

Hashline Edit

Replaces the built-in Edit tool with a hash-anchored version using LINE#ID references to prevent stale-line edits. Disabled by default.

{ "hashline_edit": true }

When enabled, two companion hooks are active: hashline-read-enhancer (annotates Read output) and hashline-edit-diff-enhancer (shows diffs). Opt-in by setting hashline_edit: true. Disable the companion hooks individually via disabled_hooks if needed.

Experimental

{
  "experimental": {
    "truncate_all_tool_outputs": false,
    "aggressive_truncation": false,
    "auto_resume": false,
    "disable_omo_env": false,
    "task_system": false,
    "dynamic_context_pruning": {
      "enabled": false,
      "notification": "detailed",
      "turn_protection": { "enabled": true, "turns": 3 },
      "protected_tools": [
        "task",
        "todowrite",
        "todoread",
        "lsp_rename",
        "session_read",
        "session_write",
        "session_search"
      ],
      "strategies": {
        "deduplication": { "enabled": true },
        "supersede_writes": { "enabled": true, "aggressive": false },
        "purge_errors": { "enabled": true, "turns": 5 }
      }
    }
  }
}

Option	Default	Description
truncate_all_tool_outputs	false	Truncate all tool outputs (not just whitelisted)
aggressive_truncation	false	Aggressively truncate when token limit exceeded
auto_resume	false	Auto-resume after thinking block recovery
disable_omo_env	false	Disable auto-injected <omo-env> block (date/time/locale). Improves cache hit rate.
task_system	false	Enable Sisyphus task system
dynamic_context_pruning.enabled	false	Auto-prune old tool outputs to manage context window
dynamic_context_pruning.notification	detailed	Pruning notifications: off / minimal / detailed
turn_protection.turns	3	Recent turns protected from pruning (1–10)
strategies.deduplication	true	Remove duplicate tool calls
strategies.supersede_writes	true	Prune write inputs when file later read
strategies.supersede_writes.aggressive	false	Prune any write if ANY subsequent read exists
strategies.purge_errors.turns	5	Turns before pruning errored tool inputs

---

Reference

Environment Variables

Variable	Description
OPENCODE_CONFIG_DIR	Override OpenCode config directory (useful for profile isolation)

Provider-Specific

Google Auth

Install opencode-antigravity-auth for Google Gemini. Provides multi-account load balancing, dual quota, and variant-based thinking.

Ollama

Must disable streaming to avoid JSON parse errors:

{
  "agents": {
    "explore": { "model": "ollama/qwen3-coder", "stream": false }
  }
}

Common models: ollama/qwen3-coder, ollama/ministral-3:14b, ollama/lfm2.5-thinking

See Ollama Troubleshooting for JSON Parse error: Unexpected EOF issues.