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

Configuration Reference

This reference documents the current runtime behavior for Oh My OpenAgent plugin config loading and validation.

During the rename transition, both basenames are accepted:

• Preferred: oh-my-openagent.jsonc or oh-my-openagent.json
• Legacy: oh-my-opencode.jsonc or oh-my-opencode.json

Format and Naming Rules

• Config format: JSONC (// comments, /* */ comments, trailing commas)
• Key style: snake_case
• Validation: Zod v4 schema validation
• Auto-migration: legacy keys and values are migrated by migrateConfigFile()

Schema autocomplete:

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

File Discovery and Merge Order

Load order (src/plugin-config.ts):

1. User config in OpenCode config dir (~/.config/opencode on macOS/Linux, %APPDATA%\\opencode on Windows)
2. Walked project configs from the current directory up to $HOME (closer directory wins)

When current directory is outside $HOME, walking is pinned to that directory.

Merge semantics

• Deep merge: agents, categories, team_mode, claude_code
• Set union (dedup arrays):
  • agent_definitions
  • disabled_agents
  • disabled_mcps
  • disabled_hooks
  • disabled_commands
  • disabled_skills
  • disabled_tools
  • mcp_env_allowlist (during merge phase)
• Override replace: all other keys

Security rule: final mcp_env_allowlist is forced to user-config only. Walked/project configs cannot extend it.

Migration Behavior

• Legacy basename can be migrated to canonical basename automatically.
• Config migrations are idempotent and tracked using migration sidecar state (plus legacy _migrations compatibility handling).
• When content changes, migration writes timestamped backups like *.bak.<ISO timestamp>.

Top-level Key Reference

Types/defaults below are from assets/oh-my-openagent.schema.json.

Key	Type	Default
$schema	string	none
_migrations	string[]	none
agent_definitions	string[]	none
agents	object	none
auto_update	boolean	none
babysitting	object	none
background_task	object	none
browser_automation_engine	object	none
categories	object	none
claude_code	object	none
comment_checker	object	none
default_run_agent	string	none
disabled_agents	string[]	none
disabled_commands	string[]	none
disabled_hooks	string[]	none
disabled_mcps	string[]	none
disabled_skills	string[]	none
disabled_tools	string[]	none
experimental	object	none
git_master	object	{ "commit_footer": true, "include_co_authored_by": true, "git_env_prefix": "GIT_MASTER=1" }
hashline_edit	boolean	none
keyword_detector	object	none
mcp_env_allowlist	string[]	none
model_capabilities	object	none
model_fallback	boolean	none
new_task_system_enabled	boolean	none
notification	object	none
openclaw	object	none
ralph_loop	object	none
runtime_fallback	boolean | object	none
sisyphus	object	none
sisyphus_agent	object	none
skills	string[] | object	none
start_work	object	none
team_mode	object	none
tmux	object	none
websearch	object	none

High-use Sections

team_mode (all fields)

{
  "team_mode": {
    "enabled": false,
    "tmux_visualization": false,
    "max_parallel_members": 4,
    "max_members": 8,
    "max_messages_per_run": 10000,
    "max_wall_clock_minutes": 120,
    "max_member_turns": 500,
    "base_dir": "/custom/path", // optional
    "message_payload_max_bytes": 32768,
    "recipient_unread_max_bytes": 262144,
    "mailbox_poll_interval_ms": 3000,
  },
}

Field	Type	Default	Notes
enabled	boolean	false	Master switch
tmux_visualization	boolean	false	Visual tmux mode
max_parallel_members	integer	4	Range 1..8
max_members	integer	8	Range 1..8
max_messages_per_run	integer	10000	Minimum 1
max_wall_clock_minutes	integer	120	Minimum 1
max_member_turns	integer	500	Minimum 1
base_dir	string	none	Optional override path
message_payload_max_bytes	integer	32768	Minimum 1024
recipient_unread_max_bytes	integer	262144	Minimum 1024
mailbox_poll_interval_ms	integer	3000	Minimum 500

tmux

Field	Type	Default
enabled	boolean	false
layout	string	"main-vertical"
main_pane_size	number	60
main_pane_min_width	number	120
agent_pane_min_width	number	40
isolation	string	"inline"

background_task

Field	Type	Default
defaultConcurrency	number	none
providerConcurrency	object	none
modelConcurrency	object	none
maxDepth	integer	none
staleTimeoutMs	number	none
messageStalenessTimeoutMs	number	none
taskTtlMs	number	none
sessionGoneTimeoutMs	number	none
syncPollTimeoutMs	number	none
maxToolCalls	integer	none
circuitBreaker	object	none

experimental

Field	Type	Default
aggressive_truncation	boolean	none
auto_resume	boolean	none
preemptive_compaction	boolean	none
truncate_all_tool_outputs	boolean	none
dynamic_context_pruning	object	none
task_system	boolean	none
plugin_load_timeout_ms	number	none
safe_hook_creation	boolean	none
disable_omo_env	boolean	none
hashline_edit	boolean	none
model_fallback_title	boolean	none
max_tools	integer	none

openclaw

Field	Type	Default
enabled	boolean	false
gateways	object	{}
hooks	object	{}
replyListener	object	none

sisyphus_agent

Field	Type	Default
disabled	boolean	none
default_builder_enabled	boolean	none
planner_enabled	boolean	none
replace_plan	boolean	none
tdd	boolean	true

git_master

Field	Type	Default
commit_footer	boolean | string	true
include_co_authored_by	boolean	true
git_env_prefix	string	"GIT_MASTER=1"

model_capabilities

Field	Type	Default
enabled	boolean	none
auto_refresh_on_start	boolean	none
refresh_timeout_ms	integer	none
source_url	string	none

browser_automation_engine

Field	Type	Default
provider	string	"playwright"

notification, comment_checker, keyword_detector, websearch, ralph_loop, babysitting, start_work

Key	Field	Type	Default
notification	force_enable	boolean	none
comment_checker	custom_prompt	string	none
keyword_detector	disabled_keywords	string[]	none
websearch	provider	string	none
ralph_loop	enabled	boolean	false
ralph_loop	default_max_iterations	number	100
ralph_loop	state_dir	string	none
ralph_loop	default_strategy	string	"continue"
babysitting	timeout_ms	number	120000
start_work	auto_commit	boolean	true

Agents, Categories, Skills

• agents: per-agent overrides. Built-ins include sisyphus, hephaestus, prometheus, oracle, librarian, explore, atlas, metis, momus, multimodal-looker, sisyphus-junior.
• categories: category-level model and prompt routing overrides.
• skills: either array form or object form.
• disabled_agents, disabled_skills, disabled_hooks, disabled_tools, disabled_commands, disabled_mcps: string arrays.

Runtime and Model Fallback

• model_fallback: global switch for proactive model fallback behavior.
• runtime_fallback: boolean or object config for reactive fallback behavior.
• Provider/model fallback chains are defined in code (src/shared/model-requirements.ts).

Verified JSONC Example

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-openagent.schema.json",
  "agents": {
    "sisyphus": { "model": "anthropic/claude-opus-4-7" },
    "explore": { "model": "github-copilot/grok-code-fast-1" },
  },
  "categories": {
    "quick": { "model": "opencode/gpt-5-nano" },
    "deep": { "model": "openai/gpt-5.5" },
  },
  "disabled_hooks": ["startup-toast"],
  "team_mode": {
    "enabled": true,
    "max_parallel_members": 4,
    "max_members": 8,
    "max_messages_per_run": 10000,
    "max_wall_clock_minutes": 120,
    "max_member_turns": 500,
    "message_payload_max_bytes": 32768,
    "recipient_unread_max_bytes": 262144,
    "mailbox_poll_interval_ms": 3000,
    "tmux_visualization": false,
  },
  "tmux": { "enabled": false },
}