OpenCode 配置指南:打造你的智能开发环境

本文将带你深入解析 OpenCode 的配置文件,帮助你快速上手并定制属于自己的 AI 开发环境。通过这份指南,你将了解如何配置模型、插件、MCP 工具以及语言服务器,充分发挥 OpenCode 的强大功能。

1. 基础配置

配置文件的基础部分定义了全局设置:

{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": [],
  "model": "YourCompany_provider/qwen3.6-plus"
}
  • $schema: 指定配置文件的 JSON Schema,用于验证配置格式
  • disabled_providers: 禁用的提供商列表(当前为空,表示所有提供商都启用)
  • model: 默认使用的模型,格式为 provider/model_name,当前设置为 YourCompany_provider/qwen3.6-plus

2. 模型提供商配置

2.1 YourCompany Provider 详解

配置文件中定义了一个名为 YourCompany_provider 的模型提供商:

"provider": {
  "YourCompany_provider": {
    "name": "YourCompany provider",
    "npm": "@ai-sdk/openai-compatible",
    "options": {
      "baseURL": "http://www.aliyun.com:123456/v1"
    }
  }
}
  • name: 提供商的显示名称
  • npm: 使用的 SDK 包,这里是 OpenAI 兼容的 SDK
  • options.baseURL: API 基础 URL,指向本地部署的模型服务

2.2 可用模型列表

YourCompany Provider 提供了多个模型,每个模型都有详细的配置:

2.2.1 多模态模型

以下模型支持多模态输入(文本、图像、音频):

qwen3.6-plus:

"qwen3.6-plus": {
  "name": "qwen3.6-plus",
  "limit": {
    "context": 931072,
    "output": 60536
  },
  "modalities": {
    "input": ["text", "image", "audio"],
    "output": ["text"]
  },
  "attachment": true
}

kimi-k2.5:

"kimi-k2.5": {
  "name": "kimi-k2.5",
  "limit": {
    "context": 931072,
    "output": 60536
  },
  "modalities": {
    "input": ["text", "image", "audio"],
    "output": ["text"]
  },
  "attachment": true
}

关键特性:

  • 上下文长度: 931,072 tokens(超长上下文)
  • 输出长度: 60,536 tokens
  • 多模态支持: 支持文本、图像、音频输入
  • 附件功能: attachment: true 表示支持文件附件
2.2.2 文本模型

其他纯文本模型包括:

  • minimax-m2.7
  • qwen3-coder-plus
  • qwen3-coder-next
  • qwen3-max
  • glm-5
  • qwen3-coder-480b
  • glm-5.1

所有文本模型都具有相同的上下文和输出限制(931,072 / 60,536 tokens)。

3. 插件系统

OpenCode 支持通过插件扩展功能:

"plugin": [
  "oh-my-openagent@latest",
  "superpowers-zh@latest"
]
  • oh-my-openagent: 提供基础的 AI Agent 功能
  • superpowers-zh: 中文优化的超级能力插件

建议保持插件为最新版本(使用 @latest 标签)。

4. MCP (Model Control Protocol) 工具

MCP 工具允许模型与外部服务交互:

4.1 Gitee 集成

"gitee": {
  "type": "local",
  "command": ["npx", "-y", "@gitee/mcp-gitee@latest"],
  "enabled": true,
  "environment": {
    "GITEE_API_BASE": "https://gitee.com/api/v5",
    "GITEE_ACCESS_TOKEN": "7815deb52d0f9d12661c911d7b84a7d8"
  }
}
  • 功能: 允许 AI 直接操作 Gitee 仓库
  • 认证: 使用个人访问令牌(注意保护此令牌)
  • API 基础: 指向 Gitee 官方 API

4.2 Playwright 浏览器自动化

"playwright": {
  "type": "local",
  "command": ["npx", "-y", "@playwright/mcp@latest"],
  "enabled": true
}
  • 功能: 提供网页自动化和测试能力
  • 应用场景: 网页内容抓取、UI 测试、自动化操作

5. 语言服务器协议 (LSP)

LSP 配置为不同编程语言提供智能提示和代码分析:

5.1 已启用的语言服务器

Python:

"python": {
  "command": ["pyright-langserver", "--stdio"],
  "enabled": true
}

TypeScript:

"typescript": {
  "command": ["typescript-language-server", "--stdio"],
  "enabled": true
}

Vue:

"vue": {
  "command": ["vue-language-server", "--stdio"],
  "enabled": true
}

5.2 Java 语言服务器(需手动配置)

Java LSP 当前被禁用,需要手动下载配置:

"java": {
  "command": ["java", "..."],
  "enabled": false,
  "note": "jdtls 下载超时,需手动下载: https://download.eclipse.org/jdtls/snapshots/jdt-language-server-latest.tar.gz 解压到 $HOME/.lsp-servers/jdtls/"
}

手动配置步骤:

  1. 下载 JDTLS: https://download.eclipse.org/jdtls/snapshots/jdt-language-server-latest.tar.gz
  2. 解压到 $HOME/.lsp-servers/jdtls/
  3. 将配置中的 enabled 改为 true

6. 最佳实践建议

6.1 模型选择指南

  • 多模态任务: 选择 qwen3.6-pluskimi-k2.5
  • 代码生成: 优先使用 qwen3-coder-* 系列模型
  • 通用任务: glm-5qwen3-max 表现稳定

6.2 安全注意事项

  • Gitee Token: 建议定期更换,并限制权限范围
  • 本地部署: 确保 baseURL 指向可信的本地服务
  • 网络访问: 注意防火墙和网络策略配置

6.3 性能优化

  • 内存分配: Java LSP 配置了 1GB 内存,可根据项目大小调整
  • 模型缓存: 超长上下文模型可能需要更多内存,确保系统资源充足

6.4 装上起飞的插件

oh-my-openagent / ‌superpowers-zh

{
  "plugin": [
    "oh-my-openagent@latest",
    "superpowers-zh@latest"
  ],
}

Oh My OpenAgent(OMO):面向 AI 编程的多智能体编排框架

Oh My OpenAgent(简称 OMO)是一款专为 OpenCode AI 编程助手 打造的开源多智能体(Multi-Agent)编排框架,由开发者 code-yeongyu 创建并维护。它将传统单一 AI 代理升级为一个协同工作的“虚拟开发团队”,通过任务分解、角色分工与流程控制,显著提升复杂编程任务的自动化能力与可靠性。

核心功能与架构
  1. 多智能体协作系统
    OMO 内置 11 个专业化 Agent,各司其职,共同构成一个完整的智能开发团队:
  • Sisyphus:主编排器,负责任务解析、子任务委派与最终结果验证。
  • Hephaestus:代码构建专家,专注于高质量代码生成与实现。
  • Prometheus:战略规划师,主导系统架构设计与执行路径制定。
  • Oracle:架构顾问,擅长处理复杂调试场景与高阶技术咨询。
  • Librarian:文档与知识库专家,负责代码检索、上下文理解与知识沉淀。
  • 其他成员:包括 Explore(探索者)、Metis(策略家)、Momus(批评者)、Atlas(依赖管理)、Frontend Engineer(前端工程师)、Multimodal Looker(多模态分析器)等,覆盖全栈开发链路。
  1. 多模型灵活调度
    OMO 支持主流大模型自由组合,有效避免厂商锁定(Vendor Lock-in):
  • 自动选型:根据任务类型(如代码生成、文档撰写、架构设计)智能选择最优模型。
  • 细粒度配置:可在配置文件中为特定 Agent 指定专属模型(如让 Oracle 使用 Claude,Hephaestus 使用 Qwen3-Coder)。
  • 容错机制:内置模型失败回退(fallback)策略,保障任务连续性。
  1. 核心特性亮点
  • ULW(Ultra Work)模式:输入 ultraworkulw 命令,即可触发全自动、端到端的任务执行流水线。
  • 哈希锚定编辑(Hash-Anchored Editing):基于内容哈希进行精准代码定位与修改,彻底解决因代码变动导致的行号漂移问题。
  • MCP 服务集成:原生支持 Web 搜索、文档查询、GitHub/Gitee 代码搜索等外部服务能力。
  • Tmux 后台执行:支持在后台并行运行多个智能体任务,提升开发效率。

安装与配置

安装方式

⚠️ 注:项目原名为 oh-my-opencode,现已统一为 oh-my-openagent,两者完全兼容。

配置文件

  • 项目级配置(优先级高):.opencode/oh-my-opencode.jsonc
  • 用户级全局配置~/.config/opencode/oh-my-opencode.jsonc
  • 格式支持:采用 JSONC(支持注释的 JSON),并提供 JSON Schema 自动补全,提升配置体验。

常用命令

opencode                    # 启动 OMO 智能代理
bunx oh-my-opencode doctor  # 诊断环境与配置问题
opencode models             # 列出当前可用的所有模型
ultrawork / ulw             # 激活 ULW 全自动工作模式

Superpowers:以流程驱动 AI 编程的纪律框架

Superpowers 是由知名开发者 Jesse Vincent(obra)打造的开源 AI 编程工作流框架,其核心理念是 “Process over Prompt”(流程大于提示词)。它并不直接生成代码,而是为现有 AI 编程助手(如 Claude Code、Cursor、Gemini 等)注入一套工程纪律与行为护栏,引导 AI 像资深工程师一样:先思考 → 再规划 → 后编码 → 必验证,从而有效解决 AI “急于动手”、“误解需求”、“代码质量不稳定”等常见问题。

核心工作流技能(Skills)

Superpowers 通过一组可组合、可复用的“技能”(Skills)来约束和引导 AI 行为,形成严谨的开发闭环:

  1. 🧠 头脑风暴(Brainstorming)
    在编码前,通过苏格拉底式提问深入澄清需求,探索多种技术方案,并自动生成设计文档。

  2. 📋 编写计划(Writing Plans)
    将整体目标拆解为一系列原子化子任务,每个任务明确指定文件路径、修改范围及验证标准。

  3. 🧪 测试驱动开发(Test-Driven Development, TDD)
    强制执行 RED → GREEN → REFACTOR 循环:

    • 先编写会失败的测试用例;
    • 再实现最小可行代码使其通过;
    • 若测试未先写,AI 生成的代码将被自动删除
  4. 👥 子代理驱动开发(Subagent-Driven Development)
    为每个子任务启动独立的子代理(Subagent),进行两阶段审查:

    • 第一阶段:检查是否符合任务规格;
    • 第二阶段:评估代码质量与最佳实践。
      子代理可自主工作数小时而不偏离主计划。
  5. 🔍 代码审查与验证
    任务之间自动交叉审查,所有修改必须通过预设验证步骤才能合并。若发现严重问题(如安全漏洞、逻辑错误),系统将阻止进度继续,确保交付质量。


总结
  • Oh My OpenAgent 聚焦于 “多智能体协同”,通过角色分工构建虚拟开发团队,适用于复杂、长周期的工程任务。
  • Superpowers 则强调 “工程流程纪律”,通过强制工作流规范 AI 行为,提升代码质量与可靠性。

两者虽路径不同,但共同指向一个未来:AI 不再是“魔法打字员”,而是具备工程思维与协作能力的可信开发伙伴

7. 故障排除

常见问题及解决方案

  1. 模型无法连接

    • 检查 baseURL 是否可达
    • 验证本地模型服务是否正常运行
  2. LSP 启动失败

    • 确认相关语言服务器已正确安装
    • 检查命令路径和参数是否正确
  3. MCP 工具报错

    • 验证环境变量是否正确设置
    • 检查网络连接和 API 令牌有效性
  4. 插件加载缓慢

    • 考虑使用国内镜像源
    • 预先安装插件避免运行时下载

通过这份配置指南,你应该能够充分理解和定制你的 OpenCode 环境。记住定期更新插件和工具,以获得最新的功能和安全修复。Happy Coding!

完整的opencode.json配置

{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": [],
  "model": "CQDR_provider/qwen3.6-plus-yfzx",
  "provider": {
    "CQDR_provider": {
      "name": "CQDR provider",
      "npm": "@ai-sdk/openai-compatible",
      "models": {
        "minimax-m2.7": {
          "name": "minimax-m2.7",
		  "limit": {
            "context": 931072, 
            "output": 60536
          }
        },
        "qwen3-coder-plus-yfzx": {
          "name": "qwen3-coder-plus-yfzx",
		  "limit": {
            "context": 931072, 
            "output": 60536
          }
        },
        "qwen3-coder-next-yfzx": {
          "name": "qwen3-coder-next-yfzx",
		  "limit": {
            "context": 931072, 
            "output": 60536
          }
        },
        "qwen3-max-yfzx": {
          "name": "qwen3-max-yfzx",
		  "limit": {
            "context": 931072, 
            "output": 60536
          }
        },
        "qwen3.6-plus-yfzx": {
          "name": "qwen3.6-plus-yfzx",
		  "limit": {
            "context": 931072, 
            "output": 60536
          }, 
		  "modalities": {
            "input": ["text", "image", "audio"],
            "output": ["text"]
          },
          "attachment": true
        },
        "glm-5-yfzx": {
          "name": "glm-5-yfzx",
		  "limit": {
            "context": 931072, 
            "output": 60536
          }
        },
        "qwen3-coder-480b": {
          "name": "qwen3-coder-480b",
		  "limit": {
            "context": 931072, 
            "output": 60536
          }
        },
        "kimi-k2.5-yfzx": {
          "name": "kimi-k2.5-yfzx",
		  "limit": {
            "context": 931072, 
            "output": 60536
          },
		  "modalities": {
            "input": ["text", "image", "audio"],
            "output": ["text"]
          },
          "attachment": true
        },
        "glm-5.1-yfzx": {
          "name": "glm-5.1-yfzx",
		  "limit": {
            "context": 931072, 
            "output": 60536
          }
        }
      },
      "options": {
        "baseURL": "http://11.49.35.177:14000/v1"
      }
    }
  },
  "plugin": [
    "oh-my-openagent@latest",
    "superpowers-zh@latest"
  ],
  "mcp": {
    "gitee": {
      "type": "local",
      "command": ["npx", "-y", "@gitee/mcp-gitee@latest"],
      "enabled": true,
      "environment": {
        "GITEE_API_BASE": "https://gitee.com/api/v5",
        "GITEE_ACCESS_TOKEN": "2222xxxx4e23fsfsvgfdrgvrv"
      }
    },
    "playwright": {
      "type": "local",
      "command": ["npx", "-y", "@playwright/mcp@latest"],
      "enabled": true
    }
  },
  "lsp": {
    "jdtls": {
      "command": ["jdtls", "--stdio"],
      "extensions": [".java"],
      "priority": 10,
      "env": { "NODE_OPTIONS": "--max-old-space-size=4096" },
      "initialization": {
        "preferences": { "includeInlayParameterNameHints": "all" }
      }
    },
    "pyright":  {
      "command": ["pyright-langserver", "--stdio"],
      "extensions": [".py", ".pyi"],
      "priority": 10,
      "env": { "NODE_OPTIONS": "--max-old-space-size=4096" },
      "initialization": {
        "preferences": {
          "python": {
            "analysis": {
              "typeCheckingMode": "basic",
              "autoSearchPaths": true,
              "useLibraryCodeForTypes": true
            }
          }
        }
      }
    },
    "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" }
      }
    }
  }
}

完整的oh-my-openagent.json配置

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",
  "agents": {
    "hephaestus": {
      "model": "CQDR_provider/qwen3.6-plus-yfzx"
    },
    "oracle": {
      "model": "CQDR_provider/qwen3.6-plus-yfzx"
    },
    "librarian": {
      "model": "CQDR_provider/qwen3.6-plus-yfzx"
    },
    "explore": {
      "model": "CQDR_provider/qwen3.6-plus-yfzx"
    },
    "multimodal-looker": {
      "model": "CQDR_provider/qwen3.6-plus-yfzx"
    },
    "prometheus": {
      "model": "CQDR_provider/qwen3.6-plus-yfzx"
    },
    "metis": {
      "model": "CQDR_provider/qwen3.6-plus-yfzx"
    },
    "momus": {
      "model": "CQDR_provider/qwen3.6-plus-yfzx"
    },
    "atlas": {
      "model": "CQDR_provider/qwen3.6-plus-yfzx"
    },
    "sisyphus-junior": {
      "model": "CQDR_provider/qwen3.6-plus-yfzx"
    }
  },
  "categories": {
    "visual-engineering": {
      "model": "CQDR_provider/qwen3.6-plus-yfzx"
    },
    "ultrabrain": {
      "model": "CQDR_provider/qwen3.6-plus-yfzx"
    },
    "deep": {
      "model": "CQDR_provider/qwen3.6-plus-yfzx"
    },
    "artistry": {
      "model": "CQDR_provider/qwen3.6-plus-yfzx"
    },
    "quick": {
      "model": "CQDR_provider/qwen3.6-plus-yfzx"
    },
    "unspecified-low": {
      "model": "CQDR_provider/qwen3.6-plus-yfzx"
    },
    "unspecified-high": {
      "model": "CQDR_provider/qwen3.6-plus-yfzx"
    },
    "writing": {
      "model": "CQDR_provider/qwen3.6-plus-yfzx"
    }
  }
}

完整的全局AGENTS.md

## 交互要求
1. 你在处理所有问题时,**全程思考过程必须使用中文**(包括需求分析、逻辑拆解、方案选择、步骤推导等所有内部推理环节);
2. 最终输出的所有回答内容(包括文字解释、代码注释、步骤说明等)**必须全部使用中文**,仅代码语法本身的英文关键词除外。

## 代码编写规范

### 后端开发规范
**1. 命名与格式规范**
- **命名风格:** 类名使用大驼峰(UpperCamelCase),方法和变量使用小驼峰(lowerCamelCase),常量全大写加下划线(UPPER_SNAKE_CASE),包名全小写。严禁使用拼音与英文混合命名。
- **代码格式:** 使用 4 个空格缩进,单行字符数不超过 120 个。大括号遵循 K&R 风格(左大括号不换行)。保留字(if/for/while)与括号之间必须加空格。
- **注释规范:** 类、接口、公共方法必须使用 Javadoc 注释,注明参数、返回值及异常。行内注释使用 `// `(双斜线后带一个空格)。

**2. 面向对象与类设计**
- **单一职责:** 确保每个类和方法职责单一,避免“上帝类”或超长方法(建议单方法不超过 80 行)。
- **POJO 规范:** POJO 类的布尔类型变量不要加 `is` 前缀(防止序列化错误);属性必须使用包装数据类型(如 Integer 而非 int);必须重写 `toString` 方法。
 - **封装性:** 成员变量必须私有化(private),通过 getter/setter 访问。

 **3. 集合与并发处理**
 - **集合使用:** 使用泛型确保类型安全;优先使用 `java.util.concurrent` 包下的线程安全集合(如 ConcurrentHashMap);不要在 foreach 循环里进行元素的 remove/add 操作。
 - **空指针防御:** 强制进行空指针判断。使用 `Optional` 处理可能为空的返回值;字符串比较时,常量字符串必须放在前面(如 `"test".equals(object)`)。
 - **并发安全:** 避免使用 `synchronized` 关键字修饰过大的代码块;优先使用 `java.util.concurrent` 工具类(如 CountDownLatch, ThreadPoolExecutor)。

 **4. 异常与日志**
 - **异常处理:** 禁止捕获异常后不做任何处理(空 catch 块);禁止直接抛出 `Exception` 或 `Throwable`,应抛出具体的业务异常;事务方法中捕获异常后必须手动回滚或再次抛出。
 - **日志规范:** 禁止使用 `System.out.println`;必须使用 SLF4J(如 `@Slf4j`);日志输出时禁止字符串拼接,应使用占位符(如 `log.info("用户ID: {}", userId)`)。

 **5. 性能与安全**
 - **资源管理:** 必须使用 `try-with-resources` 语句自动关闭 IO 流、数据库连接等资源。
 - **SQL 安全:** 禁止使用字符串拼接方式构造 SQL,必须使用预编译语句(如 MyBatis 的 `#{}`)防止 SQL 注入。
 - **工具类:** 优先使用成熟的工具库(如 Apache Commons Lang, Guava, Hutool)处理字符串、集合等操作,避免重复造轮子。

### 前端开发规范

**1. 命名与代码格式规范**
- **命名风格:** 
  - 变量与函数:使用小驼峰(camelCase),布尔值使用 `is`/`has`/`can` 前缀(如 `isLoading`)。
  - 组件与类名:使用大驼峰(PascalCase),文件名与组件名保持一致。
  - 常量:全大写加下划线(UPPER_SNAKE_CASE)。
  - CSS 类名:优先使用 BEM 命名法(Block__Element--Modifier)或语义化的 kebab-case。
- **代码格式:** 统一使用 2 个空格缩进,单行字符数不超过 100 个,语句结尾必须加分号,字符串优先使用单引号。
- **注释规范:** 公共函数、复杂逻辑必须使用 JSDoc 格式注释,注明参数、返回值及功能描述。待优化代码使用 `// TODO:` 或 `// FIXME:` 标记。

## 单表台账 CRUD 功能开发规范

为确保系统一致性、可维护性与用户体验,所有单表台账类功能的开发须严格遵循以下规范:

### 1. 数据返回要求
- **基础字段透传**:除业务展示字段外,接口必须返回 `create_by`(创建人)和 `create_time`(创建时间),并在前端列表中予以展示。
- **主键返回**:新增或编辑操作成功后,**必须返回记录的主键 ID**,禁止使用 `void` 作为接口返回类型。

### 2. 列表查询规则
- **默认排序**:列表查询(`list`)接口应默认按 `create_time` 字段 **倒序排列**(最新创建的记录在前)。

### 3. 接口路径定义
- **显式路径声明**:Controller 中每个 `@RequestMapping`(或其衍生注解如 `@GetMapping`、`@PostMapping` 等)**必须完整指定目标 URL 路径**,不得依赖类级别的 `@RequestMapping` 通过 HTTP 方法隐式推断路径。

### 4. 删除操作规范
- **统一批量删除接口**:后端仅提供一个 **批量删除接口**(接收 ID 列表),前端无论是单条删除还是批量删除,均复用该接口。

### 5. 前端 UI 要求
- **自适应布局**:台账页面必须采用响应式/自适应布局,适配不同屏幕尺寸。
- **文本溢出处理**:对于描述类或长文本字段,应使用 **省略号(ellipsis)显示**,避免内容溢出破坏页面美观。

### 6. 代码注释规范
- **完整方法注释**:每个 Controller、Service、Mapper 方法必须包含符合 JavaDoc 规范的注释,说明功能、参数及返回值。
- **类级注释**:所有类(包括实体类、Controller、Service 等)顶部必须有完整的类注释,描述其职责与用途。

### 7. 权限控制格式
- **权限标识格式**:所有权限注解(如 `@SaCheckPermission`)中的权限值 **必须严格遵循 `模块:功能:操作` 的三段式命名规范**,例如:
>  @SaCheckPermission("ledger:entry:edit")

### 8. 数据库表结构要求
- **基础字段必备**:创建台账相关数据表时,**必须包含以下通用字段**:
  - `tenant_id`:租户 ID(支持多租户)
  - `create_by`:创建人
  - `create_dept`:创建部门
  - `create_time`:创建时间
  - `update_by`:最后更新人
  - `update_time`:最后更新时间
  - `del_flag`:逻辑删除标志(0-正常,1-已删除)

## 功能任务实现规范
1. 你再接受用户指令之前,识别如果是功能需求必须先使用OpenSpec规范,先创建openspec文件夹,文件夹里面生成对应的OpenSpec规范的相关文件放入里面。
2. 你在处理所有问题时,必须先规划使用头脑风暴的技能,规划好任务之后拆解任务形成任务计划文档,然后再使用多智能体协同实施方案;


Logo

openEuler 是由开放原子开源基金会孵化的全场景开源操作系统项目,面向数字基础设施四大核心场景(服务器、云计算、边缘计算、嵌入式),全面支持 ARM、x86、RISC-V、loongArch、PowerPC、SW-64 等多样性计算架构

更多推荐