luna/oh-my-opencode
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
aadcbbfcc647edcf9f99e9a9df0567f40f78210b
oh-my-opencode/docs/reference/configuration.md
T
YeonGyu-Kim 810e3c7a51 docs: refresh user-facing guide + reference for current code state 
Audit pass against root AGENTS.md (regenerated 2026-05-08) and the
canonical sources in src/shared/model-requirements.ts,
src/features/team-mode/, src/cli/, src/config/schema/. Each touched file
keeps its existing tone but corrects stale facts:

- guide/overview.md: project name + dual-package transition reality
- guide/installation.md: bun-only invocation, dual oh-my-openagent /
  oh-my-opencode CLI surface, current doctor categories
- guide/orchestration.md: 11 agents, category routing through
  sisyphus-junior, background concurrency, team-mode link
- guide/agent-model-matching.md: Metis primary -> claude-sonnet-4-6
  (matches src/shared/model-requirements.ts fallback chain)
- guide/team-mode.md: full schema, member eligibility tiers, 12 team_*
  tools added when enabled
- reference/cli.md: trim to current Commander surface (install, doctor,
  run, mcp-oauth, refresh-model-capabilities, get-local-version)
- reference/configuration.md: trim to schema-driven reference, JSONC
  rules, multi-level merge order, mcp_env_allowlist user-only constraint
- reference/features.md: 5-tier hook composition counts, 3-tier MCPs,
  hashline edit, IntentGate, OpenClaw bidirectional dispatcher

Cross-cutting: every `oh-my-opencode.schema.json` URL replaced with
the canonical `oh-my-openagent.schema.json` (legacy package name in
text bodies preserved where it documents the dual-publish transition).
2026-05-08 16:14:30 +09:00

279 lines
9.3 KiB
Markdown
Raw Blame History

# 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:
```jsonc
{
"$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)
```jsonc
{
"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
```jsonc
{
"$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 },
}
```
Reference in New Issue View Git Blame Copy Permalink