跳转到内容
展示 生态 文档

高级配置

高级配置

本文档介绍了 Oh My OpenCode 的高级配置选项，帮助你针对特定需求进行定制。

配置文件位置与优先级

配置文件位置

Oh My OpenCode 按以下顺序查找配置文件：

1. .opencode/oh-my-opencode.json (项目级，优先级最高)
2. ~/.config/opencode/oh-my-opencode.json (用户级，macOS/Linux)
3. %APPDATA%\opencode\oh-my-opencode.json (用户级，Windows)

配置合并规则

多个配置文件按优先级进行合并：

项目级配置 (.opencode/oh-my-opencode.json)：

{
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 2
  }
}

用户级配置 (~/.config/opencode/oh-my-opencode.json)：

{
  "sisyphus": {
    "max_concurrent_tasks": 3  // 覆盖项目级设置
  },
  "agents": {
    "oracle": { "enabled": true }
  }
}

最终生效配置：

{
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 3  // 来自用户级
  },
  "agents": {
    "oracle": { "enabled": true }  // 来自用户级
  }
}

JSONC 支持

Oh My OpenCode 支持带注释的 JSON (JSONC) 格式：

{
  // 这是一个注释
  "sisyphus": {
    "enabled": true,
    /* 
     * 多行注释
     * 根据订阅计划进行调整
     */
    "max_concurrent_tasks": 3
  },
  
  // 代理配置
  "agents": {
    "oracle": {
      "enabled": true,
      // "temperature": 0.7,  // 可以注释掉不使用的配置
    }
  }
}

订阅计划配置

Claude Max20 完整配置

最强大的配置，适合高强度的开发工作：

{
  "subscription": "claude-max20",
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 3,
    "task_timeout": 300,
    "auto_delegate": true,
    "delegation_strategy": "optimal"
  },
  "agents": {
    "oracle": {
      "enabled": true,
      "model": "claude-sonnet-4",
      "temperature": 0.7,
      "max_tokens": 4096
    },
    "librarian": {
      "enabled": true,
      "model": "claude-sonnet-4",
      "temperature": 0.5
    },
    "frontend-engineer": {
      "enabled": true,
      "model": "claude-sonnet-4",
      "temperature": 0.6
    },
    "backend-engineer": {
      "enabled": true,
      "model": "claude-sonnet-4",
      "temperature": 0.6
    },
    "explore": {
      "enabled": true,
      "model": "claude-sonnet-3.5",
      "temperature": 0.3
    }
  },
  "lsp": {
    "enabled": true,
    "languages": ["typescript", "javascript", "python", "go", "rust"]
  },
  "background_task": {
    "defaultConcurrency": 3,
    "providerConcurrency": {
      "anthropic": 3,
      "openai": 5
    }
  }
}

ChatGPT Plus/Pro 配置

平衡性能与成本：

{
  "subscription": "chatgpt-plus",
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 2,
    "delegation_strategy": "balanced"
  },
  "agents": {
    "oracle": {
      "enabled": true,
      "model": "gpt-4-turbo"
    },
    "librarian": {
      "enabled": true,
      "model": "gpt-4-turbo"
    },
    "frontend-engineer": {
      "enabled": true,
      "model": "gpt-4"
    },
    "backend-engineer": {
      "enabled": false  // 节省配额
    },
    "explore": {
      "enabled": true,
      "model": "gpt-4"
    }
  },
  "background_task": {
    "defaultConcurrency": 2,
    "providerConcurrency": {
      "openai": 2
    }
  }
}

Gemini Advanced 配置

极高的性价比：

{
  "subscription": "gemini-advanced",
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 2
  },
  "agents": {
    "oracle": {
      "enabled": false  // Gemini 在架构设计方面稍弱
    },
    "librarian": {
      "enabled": true,
      "model": "gemini-pro-1.5"
    },
    "frontend-engineer": {
      "enabled": true,
      "model": "gemini-pro-1.5"
    },
    "explore": {
      "enabled": true,
      "model": "gemini-pro-1.5"
    }
  }
}

代理定制

完整的代理配置选项

{
  "agents": {
    "oracle": {
      // 基础配置
      "enabled": true,
      "model": "claude-sonnet-4",
      "temperature": 0.7,
      "max_tokens": 4096,
      "top_p": 0.9,
      
      // Prompt 定制
      "prompt_append": "请提供详细的技术决策理由和权衡分析",
      "system_prompt_override": "你是一名资深架构师...",
      
      // 行为控制
      "auto_retry": true,
      "max_retries": 3,
      "retry_delay": 2,
      
      // 工具权限
      "tools": {
        "lsp": true,
        "ast_grep": true,
        "file_operations": true,
        "shell_commands": false  // 安全考量
      },
      
      // 资源限制
      "rate_limit": {
        "requests_per_minute": 20,
        "tokens_per_minute": 50000
      }
    }
  }
}

自定义代理 Prompt

针对特定项目定制代理行为：

{
  "agents": {
    "frontend-engineer": {
      "enabled": true,
      "prompt_append": "你是我们团队的前端工程师。请遵循以下规范：\n\n1. 技术栈：\n   - 使用 TypeScript 的 React 18+\n   - 使用 Tailwind CSS 进行样式开发\n   - 使用 React Query 进行数据获取\n\n2. 代码风格：\n   - 使用函数组件和 Hooks\n   - Props 必须定义 TypeScript 接口\n   - 优先使用组合而非继承\n\n3. 无障碍：\n   - 所有交互元素必须支持键盘操作\n   - 使用语义化 HTML\n   - 提供适当的 ARIA 标签\n\n4. 性能：\n   - 使用 React.memo 优化渲染\n   - 图片必须使用延迟加载\n   - 避免在渲染函数中创建对象"
    }
  }
}

权限控制配置

文件操作权限

{
  "permissions": {
    "file_operations": {
      "read": {
        "allow": ["src/**", "docs/**", "*.md"],
        "deny": [".env*", "*.key", "secrets/**"]
      },
      "write": {
        "allow": ["src/**", "docs/**"],
        "deny": ["package.json", "tsconfig.json"]  // 关键文件需要手动确认
      },
      "delete": {
        "require_confirmation": true,
        "allow": ["temp/**"],
        "deny": ["**"]  // 默认禁止删除
      }
    }
  }
}

Shell 命令权限

{
  "permissions": {
    "shell_commands": {
      "enabled": true,
      "whitelist": [
        "npm test",
        "npm run lint",
        "git status",
        "git diff"
      ],
      "blacklist": [
        "rm -rf",
        "sudo",
        "curl *",  // 防止数据泄露
        "wget *"
      ],
      "require_confirmation_for": [
        "git push",
        "npm publish",
        "docker"
      ]
    }
  }
}

API 调用权限

{
  "permissions": {
    "api_calls": {
      "allowed_domains": [
        "api.github.com",
        "registry.npmjs.org"
      ],
      "rate_limit": {
        "requests_per_minute": 60
      },
      "require_user_secrets": true  // API 密钥必须由用户提供
    }
  }
}

后台任务并发控制

并发策略配置

{
  "background_task": {
    "defaultConcurrency": 5,
    "providerConcurrency": {
      "anthropic": 3,
      "openai": 5
    },
    
    // 优先级配置
    "priority_levels": {
      "high": {
        "max_concurrent": 2,
        "timeout": 600
      },
      "normal": {
        "max_concurrent": 2,
        "timeout": 300
      },
      "low": {
        "max_concurrent": 1,
        "timeout": 120
      }
    },
    
    // 资源分配策略
    "scheduling": {
      "strategy": "fair",  // fair (公平), priority (优先级), round-robin (轮询)
      "preemption": false,  // 是否允许高优先级任务抢占
      "queue_size": 10
    },
    
    // 失败处理
    "error_handling": {
      "retry_failed": true,
      "max_retries": 2,
      "fallback_to_sync": true  // 失败后降级为同步执行
    }
  }
}

任务类型配置

{
  "task_types": {
    "analysis": {
      "can_run_in_background": true,
      "priority": "low",
      "timeout": 120
    },
    "code_generation": {
      "can_run_in_background": false,  // 代码生成需要用户确认
      "priority": "high"
    },
    "documentation": {
      "can_run_in_background": true,
      "priority": "low"
    },
    "testing": {
      "can_run_in_background": true,
      "priority": "normal"
    }
  }
}

Sisyphus 代理配置选项

完整的 Sisyphus 配置

{
  "sisyphus": {
    // 基础配置
    "enabled": true,
    "max_concurrent_tasks": 3,
    "task_timeout": 300,
    
    // 下发策略
    "auto_delegate": true,
    "delegation_strategy": "optimal",  // optimal (最优), balanced (平衡), sequential (顺序), parallel (并行)
    
    // 任务拆解
    "task_decomposition": {
      "enabled": true,
      "max_subtasks": 10,
      "min_subtask_complexity": 2
    },
    
    // 代理选择
    "agent_selection": {
      "strategy": "capability_match",  // capability_match (能力匹配), load_balance (负载均衡), random (随机)
      "consider_workload": true,
      "prefer_specialists": true
    },
    
    // 结果整合
    "result_aggregation": {
      "strategy": "merge",  // merge (合并), vote (投票), best (最优)
      "conflict_resolution": "oracle_decides"
    },
    
    // 上下文管理
    "context_sharing": {
      "enabled": true,
      "share_between_agents": true,
      "max_context_size": 8192
    }
  }
}

Hooks 集成配置

生命周期 Hooks

{
  "hooks": {
    "pre_task": {
      "enabled": true,
      "script": ".opencode/hooks/pre-task.sh",
      "timeout": 30
    },
    "post_task": {
      "enabled": true,
      "script": ".opencode/hooks/post-task.sh"
    },
    "on_error": {
      "enabled": true,
      "script": ".opencode/hooks/error-handler.sh",
      "notify_user": true
    },
    "on_agent_switch": {
      "enabled": true,
      "script": ".opencode/hooks/agent-switch.sh"
    }
  }
}

Hook 脚本示例

#!/bin/bash
# .opencode/hooks/pre-task.sh

# 在任务开始前执行
echo "正在开始任务: $TASK_ID"

# 检查代码质量
npm run lint || {
  echo "代码检查失败。请在继续前修复。"
  exit 1
}

# 拉取最新代码
git pull origin main

exit 0

MCP 服务配置

模型上下文协议 (Model Context Protocol) 集成

{
  "mcp": {
    "enabled": true,
    "servers": [
      {
        "name": "github",
        "command": "mcp-server-github",
        "args": ["--token", "${GITHUB_TOKEN}"],
        "env": {
          "GITHUB_API_URL": "https://api.github.com"
        }
      },
      {
        "name": "database",
        "command": "mcp-server-postgres",
        "args": ["--connection", "${DATABASE_URL}"]
      },
      {
        "name": "slack",
        "command": "mcp-server-slack",
        "args": ["--token", "${SLACK_TOKEN}"]
      }
    ],
    
    // 服务资源限制
    "resource_limits": {
      "max_connections": 5,
      "timeout": 30,
      "retry_attempts": 3
    }
  }
}

完整配置示例

企业级配置模板

{
  "version": "1.0",
  "subscription": "claude-max20",
  
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 3,
    "delegation_strategy": "optimal"
  },
  
  "agents": {
    "oracle": {
      "enabled": true,
      "model": "claude-sonnet-4",
      "temperature": 0.7,
      "prompt_append": "遵循公司的技术栈和架构原则"
    },
    "librarian": {
      "enabled": true,
      "model": "claude-sonnet-4"
    },
    "frontend-engineer": {
      "enabled": true,
      "model": "claude-sonnet-4",
      "prompt_append": "使用 React + TypeScript + Tailwind"
    },
    "backend-engineer": {
      "enabled": true,
      "model": "claude-sonnet-4",
      "prompt_append": "使用 Node.js + Express + PostgreSQL"
    },
    "explore": {
      "enabled": true,
      "model": "claude-sonnet-3.5"
    }
  },
  
  "lsp": {
    "enabled": true,
    "languages": ["typescript", "python", "go"]
  },
  
  "background_task": {
    "defaultConcurrency": 5,
    "providerConcurrency": {
      "anthropic": 3,
      "openai": 5
    }
  },
  
  "permissions": {
    "file_operations": {
      "read": {
        "allow": ["src/**", "docs/**"],
        "deny": [".env*", "secrets/**"]
      },
      "write": {
        "allow": ["src/**", "docs/**"],
        "deny": ["package.json"]
      }
    },
    "shell_commands": {
      "whitelist": ["npm test", "npm run lint", "git status"]
    }
  },
  
  "hooks": {
    "pre_task": {
      "enabled": true,
      "script": ".opencode/hooks/pre-task.sh"
    },
    "post_task": {
      "enabled": true,
      "script": ".opencode/hooks/post-task.sh"
    }
  },
  
  "context_injection": {
    "enabled": true,
    "files": [".opencode/CONTEXT.md", "AGENTS.md"]
  }
}

配置验证

验证配置文件

# 验证配置语法
opencode "验证配置文件"

# 测试配置
opencode "使用当前配置执行测试任务"

# 查看生效配置
opencode "显示当前完整配置"

常见配置错误

// ❌ 错误：并发数超过订阅限制
{
  "sisyphus": {
    "max_concurrent_tasks": 10  // Claude Max20 最大为 3
  }
}
Mode:
// ✅ 正确
{
  "sisyphus": {
    "max_concurrent_tasks": 3
  }
}

// ❌ 错误：禁用了代理
{
  "sisyphus": {
    "auto_delegate": true
  },
  "agents": {
    "oracle": { "enabled": false }  // 但 Sisyphus 可能尝试下发任务
  }
}

// ✅ 正确
{
  "agents": {
    "oracle": { "enabled": true }
  }
}

后续步骤

配置完成后，我们建议你：

  1. 💡 查看 使用案例 了解如何应用配置
  2. 📖 回顾 最佳实践 以优化工作流
  3. 🧪 在实际项目中测试并调整配置