shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 开发与工程无需 API Key

opencode-docs

OpenCode + OhMyOpenCode 配置参考 - 代理、工具、MCP、技能、命令、钩子、权限、提供者和Sisyphus编排模式

person作者: jakexiaohubgithub
open_in_new仓库download下载资源包

OpenCode + OhMyOpenCode Reference

Quick Reference

Magic Words (OhMyOpenCode)

| Keyword | Effect | |---------|--------| | ultrawork / ulw | Maximum performance - parallel agents, background tasks, relentless execution | | search / find | Maximized search with parallel explore + librarian | | analyze / investigate | Deep analysis with multi-phase expert consultation | | ultrathink | Extended thinking mode for complex reasoning |

Config File Locations (Precedence: later overrides earlier)

1. Remote (.well-known/opencode)     - organizational defaults
2. ~/.config/opencode/opencode.json  - global user preferences
3. ./opencode.json                   - project-specific
4. .opencode/                        - agents, commands, plugins

OhMyOpenCode Config Locations

1. ~/.config/opencode/oh-my-opencode.json  - global
2. .opencode/oh-my-opencode.json           - project

Agents

Agents are specialized AI assistants with custom prompts, models, and tool access.

Agent Types

| Type | Description | Invocation | |------|-------------|------------| | primary | Main assistants for direct interaction | Tab key cycles, or configured switch_agent keybind | | subagent | Specialized assistants for specific tasks | @ mention or invoked by primary agents | | all | Can be used as both (default if not specified) | Both methods |

Built-in Primary Agents

| Agent | Purpose | Default Model | |-------|---------|---------------| | build | Full development with all tools | Configured model | | plan | Analysis without changes (read-only) | Configured model |

Built-in Subagents

| Agent | Purpose | Default Model | |-------|---------|---------------| | general | Multi-step research tasks | Parent's model | | explore | Fast codebase exploration | Parent's model |

OhMyOpenCode Agents

| Agent | Purpose | Model | |-------|---------|-------| | Sisyphus | Main orchestrator | claude-opus-4-5 | | oracle | Architecture, debugging, strategy | gpt-5.2 | | librarian | Docs, OSS examples, multi-repo | glm-4.7-free | | explore | Fast codebase grep | grok-code/gemini-flash/haiku | | frontend-ui-ux-engineer | UI/UX development | gemini-3-pro | | document-writer | Technical writing | gemini-3-flash | | multimodal-looker | PDF/image analysis | gemini-3-flash |

Agent Definition Locations

~/.config/opencode/agent/*.md     - global agents
.opencode/agent/*.md              - project agents
~/.claude/agents/*.md             - Claude Code compat
.claude/agents/*.md               - Claude Code compat (project)

Creating Agents

Interactive CLI:

opencode agent create

This will ask where to save (global/project), description, generate prompt, select tools, and create the markdown file.

Manual - Markdown (recommended): Create ~/.config/opencode/agent/<name>.md:

---
description: Required - what this agent does (shown in @ menu)
mode: subagent           # primary | subagent | all (default: all)
model: anthropic/claude-sonnet-4-20250514
temperature: 0.3         # 0.0-1.0 (default: model-specific)
maxSteps: 10             # Optional: limit agentic iterations
disable: false           # Set true to disable
hidden: false            # Set true to hide from @ autocomplete (subagents only)
tools:
  write: false
  edit: false
  bash: false
  mymcp_*: false         # Wildcards supported
permission:
  edit: deny             # allow | deny | ask
  bash:
    "*": ask             # Default for all commands
    "git status": allow  # Specific command override
    "rm -rf *": deny     # Last matching rule wins
  task:                  # Control which subagents this agent can invoke
    "*": deny
    "code-reviewer": ask
    "my-helper-*": allow
---

System prompt goes here.
You can include:
- Detailed instructions
- Code examples
- Behavioral guidelines

Manual - JSON (opencode.json):

{
  "agent": {
    "my-agent": {
      "description": "Required description",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.3,
      "maxSteps": 10,
      "tools": { "write": false, "edit": false },
      "permission": { 
        "edit": "deny",
        "bash": { "*": "ask", "git *": "allow" }
      },
      "prompt": "{file:./prompts/my-agent.txt}"
    }
  }
}

Configuration Options Reference

| Option | Type | Description | |--------|------|-------------| | description | string | Required. Shown in @ autocomplete menu | | mode | string | primary, subagent, or all (default) | | model | string | provider/model-id format. If not set: primary uses global, subagent uses parent's | | temperature | number | 0.0-1.0. Lower = deterministic, higher = creative | | maxSteps | number | Max agentic iterations before forced text response | | disable | boolean | Set true to disable agent | | hidden | boolean | Hide from @ menu (subagents only, still invokable by Task tool) | | tools | object | Enable/disable tools. Supports wildcards (mcp_*: false) | | permission | object | edit, bash, webfetch, task permissions | | prompt | string | System prompt or {file:./path.txt} for external file | | reasoningEffort | string | Provider-specific (e.g., OpenAI's high/medium/low) |

Temperature Guidelines

  • 0.0-0.2: Deterministic, ideal for code analysis and planning
  • 0.3-0.5: Balanced, good for general development
  • 0.6-1.0: Creative, useful for brainstorming

OhMyOpenCode Agent Override (oh-my-opencode.json)

{
  "agents": {
    "oracle": { "model": "openai/gpt-5.2" },
    "explore": { "model": "anthropic/claude-haiku-4-5" },
    "frontend-ui-ux-engineer": { "disable": true }
  },
  "disabled_agents": ["oracle", "frontend-ui-ux-engineer"]
}

Usage

Switch primary agents: Tab key or switch_agent keybind

Invoke subagents: @agent-name your request here

Navigate sessions: When subagents create child sessions:

  • <Leader>+Right - cycle forward through parent → children
  • <Leader>+Left - cycle backward

Tools

Built-in Tools

| Tool | Purpose | |------|---------| | bash | Execute shell commands | | edit | Modify files (exact string replacement) | | write | Create/overwrite files | | read | Read file contents | | grep | Search file contents (regex) | | glob | Find files by pattern | | list | List directory contents | | webfetch | Fetch web content | | skill | Load skill definitions | | todowrite / todoread | Task management |

OhMyOpenCode Additional Tools

| Tool | Purpose | |------|---------| | lsp_* | LSP operations (hover, goto, rename, etc.) | | ast_grep_* | AST-aware search/replace | | call_omo_agent | Spawn explore/librarian agents | | sisyphus_task | Category-based task delegation | | background_task | Run agents in background | | background_output | Get background task results | | background_cancel | Cancel background tasks | | session_* | Session history management | | look_at | Multimodal file analysis |

Tool Permissions

{
  "permission": {
    "edit": "allow",        // allow | deny | ask
    "bash": "ask",
    "webfetch": "deny",
    "bash": {               // Per-command
      "*": "ask",
      "git status": "allow",
      "rm -rf": "deny"
    }
  }
}

Disable Tools Globally

{
  "tools": {
    "write": false,
    "mymcp_*": false
  }
}

MCP Servers

Config Location

// opencode.json
{
  "mcp": {
    "server-name": { ... }
  }
}

Local MCP

{
  "mcp": {
    "my-local": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-server"],
      "environment": { "API_KEY": "{env:MY_API_KEY}" },
      "enabled": true,
      "timeout": 5000
    }
  }
}

Remote MCP

{
  "mcp": {
    "my-remote": {
      "type": "remote",
      "url": "https://mcp.example.com",
      "headers": { "Authorization": "Bearer {env:TOKEN}" },
      "oauth": {}
    }
  }
}

OhMyOpenCode Built-in MCPs

| MCP | Purpose | |-----|---------| | websearch | Exa AI web search | | context7 | Official documentation lookup | | grep_app | GitHub code search |

Disable via:

// oh-my-opencode.json
{ "disabled_mcps": ["websearch", "context7"] }

Claude Code MCP Compat Locations

~/.claude/.mcp.json
./.mcp.json
./.claude/.mcp.json

Skills

Skill Locations

~/.config/opencode/skill/<name>/SKILL.md  - global
.opencode/skill/<name>/SKILL.md           - project
~/.claude/skills/<name>/SKILL.md          - Claude Code compat
.claude/skills/<name>/SKILL.md            - Claude Code compat (project)

Skill Format

---
name: my-skill
description: What this skill does (1-1024 chars)
license: MIT
compatibility: opencode
mcp:                              # Optional embedded MCP
  playwright:
    command: npx
    args: ["-y", "@anthropic-ai/mcp-playwright"]
---

Instructions for the agent when this skill is loaded.

OhMyOpenCode Built-in Skills

  • playwright - Browser automation
  • git-master - Git operations expert

Disable via:

// oh-my-opencode.json
{ "disabled_skills": ["playwright"] }

Commands

Command Locations

~/.config/opencode/command/*.md   - global
.opencode/command/*.md            - project
~/.claude/commands/*.md           - Claude Code compat
.claude/commands/*.md             - Claude Code compat (project)

Command Format

---
description: What this command does
agent: build
model: anthropic/claude-sonnet-4
subtask: true
---

Template with $ARGUMENTS or $1, $2, etc.

Include files with @path/to/file.ts
Include shell output with !`command`

Providers

Authentication

opencode auth login       # Interactive provider selection
opencode auth list        # Show configured providers

Provider Config

{
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.anthropic.com/v1",
        "timeout": 600000
      }
    }
  },
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

Model Format

provider/model-id - e.g., anthropic/claude-opus-4-5, openai/gpt-5.2

Disable Providers

{
  "disabled_providers": ["openai", "gemini"],
  "enabled_providers": ["anthropic"]  // Allowlist mode
}

OhMyOpenCode Specifics

Sisyphus Agent Config

// oh-my-opencode.json
{
  "sisyphus_agent": {
    "disabled": false,
    "default_builder_enabled": false,
    "planner_enabled": true,
    "replace_plan": true
  }
}

Background Task Concurrency

{
  "background_task": {
    "defaultConcurrency": 5,
    "providerConcurrency": { "anthropic": 3 },
    "modelConcurrency": { "anthropic/claude-opus-4-5": 2 }
  }
}

Categories (sisyphus_task)

{
  "categories": {
    "visual": {
      "model": "google/gemini-3-pro-preview",
      "temperature": 0.7,
      "prompt_append": "Use shadcn/ui and Tailwind"
    },
    "business-logic": {
      "model": "openai/gpt-5.2",
      "temperature": 0.1
    }
  }
}

Hooks

Disable via:

{ "disabled_hooks": ["comment-checker", "agent-usage-reminder"] }

Key hooks:

  • todo-continuation-enforcer - Forces completion of all TODOs
  • comment-checker - Prevents excessive comments
  • context-window-monitor - Warns at 70%+ usage
  • preemptive-compaction - Compacts at 85% usage
  • keyword-detector - Detects ultrawork/search/analyze
  • ralph-loop - Continuous execution until done

Ralph Loop

/ralph-loop "Build a REST API"   # Start loop
/cancel-ralph                     # Stop loop

Hooks (Claude Code Compat)

Hook Locations

~/.claude/settings.json
./.claude/settings.json
./.claude/settings.local.json

Hook Events

  • PreToolUse - Before tool execution
  • PostToolUse - After tool execution
  • UserPromptSubmit - On prompt submit
  • Stop - When session goes idle

Hook Format

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "eslint --fix $FILE" }]
      }
    ]
  }
}

Rules / Instructions

AGENTS.md Locations

./AGENTS.md                       - project root
~/.config/opencode/AGENTS.md      - global

Both are combined. Project can have nested AGENTS.md per directory.

Instructions Array

{
  "instructions": ["CONTRIBUTING.md", "docs/*.md", ".cursor/rules/*.md"]
}

Conditional Rules (.claude/rules/)

---
globs: ["*.ts", "src/**/*.js"]
alwaysApply: false
---

- Use PascalCase for interfaces
- Use camelCase for functions

Common Tasks

Check Current Config

cat ~/.config/opencode/opencode.json
cat ~/.config/opencode/oh-my-opencode.json
cat ./opencode.json
cat ./.opencode/oh-my-opencode.json

Add Custom Agent

  1. Create ~/.config/opencode/agent/my-agent.md or .opencode/agent/my-agent.md
  2. Or add to opencode.json under agent key

Disable OhMyOpenCode Feature

// oh-my-opencode.json
{
  "disabled_hooks": ["feature-name"],
  "disabled_agents": ["agent-name"],
  "disabled_mcps": ["mcp-name"],
  "disabled_skills": ["skill-name"]
}

Override Agent Model

// oh-my-opencode.json
{
  "agents": {
    "oracle": { "model": "anthropic/claude-sonnet-4-20250514" }
  }
}

Add Custom MCP

// opencode.json
{
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-server"]
    }
  }
}

Troubleshooting

Config Not Loading

  1. Check JSON syntax: cat ~/.config/opencode/opencode.json | jq .
  2. Verify file location (precedence matters)
  3. Check OpenCode version: opencode --version (need 1.0.150+)

Agent Not Available

  1. Check disabled_agents in oh-my-opencode.json
  2. Verify agent file exists and has valid frontmatter
  3. Check mode: primary vs subagent

MCP Not Working

  1. Check enabled: true in MCP config
  2. Verify command exists: which npx
  3. Check timeout (default 5000ms)
  4. For OAuth: opencode mcp auth <server-name>

Hooks Not Firing

  1. Check disabled_hooks in oh-my-opencode.json
  2. Verify hook event name matches
  3. Check Claude Code settings.json location

Provider Auth Issues

  1. Run opencode auth login and re-authenticate
  2. Check ~/.local/share/opencode/auth.json exists
  3. For Google: Consider opencode-antigravity-auth plugin

Variable Substitution

Environment Variables

{ "apiKey": "{env:MY_API_KEY}" }

File Contents

{ "instructions": ["{file:./prompts/system.txt}"] }

LSP Configuration

Add LSP Server (oh-my-opencode.json)

{
  "lsp": {
    "typescript-language-server": {
      "command": ["typescript-language-server", "--stdio"],
      "extensions": [".ts", ".tsx"],
      "priority": 10
    },
    "pylsp": { "disabled": true }
  }
}

Claude Code Compatibility Toggles

// oh-my-opencode.json
{
  "claude_code": {
    "mcp": false,       // Disable ~/.claude/.mcp.json loading
    "commands": false,  // Disable ~/.claude/commands/
    "skills": false,    // Disable ~/.claude/skills/
    "agents": false,    // Disable ~/.claude/agents/
    "hooks": false,     // Disable settings.json hooks
    "plugins": false    // Disable marketplace plugins
  }
}