Merge pull request #102 from Electricitysheep/feat/opencode-advanced-config
feat(docs): add advanced OpenCode configuration guide (model config, MCP, troubleshooting)
This commit is contained in:
Sanbu 散步
@@ -611,6 +611,122 @@ Prometheus (claude-opus-4-7 / kimi-k2.6 / glm-5.1) is your strategic planner. Th
|
||||
|
||||
After this, you can use OpenCode with the Oh-My-OpenAgent plugin to complete coding tasks.
|
||||
|
||||
#### Advanced Model and API Configuration
|
||||
|
||||
The `/connect` command offers a quick way to bring in a model through the chat UI. For finer control — assigning different models to different task types or keeping multiple API providers as backups — you can edit OpenCode's configuration file `opencode.json` directly.
|
||||
|
||||
This file lives at `~/.config/opencode/opencode.json` (Windows: `C:\Users\YourUserName\.config\opencode\opencode.json`) and is generated automatically the first time you launch OpenCode.
|
||||
|
||||
Here is a sample configuration for connecting Alibaba Cloud's Qwen model via the Bailian platform:
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "bailian-coding-plan/qwen3.5-plus",
|
||||
"small_model": "bailian-coding-plan/qwen3.5-plus",
|
||||
"provider": {
|
||||
"bailian-coding-plan": {
|
||||
"options": {
|
||||
"apiKey": "sk-your-api-key"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> 💡 The `model` field uses a `provider/model-name` format. Replace the `apiKey` value with your own key after registering on the corresponding platform.
|
||||
|
||||
To route different task types to different models:
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "bailian-coding-plan/qwen3.5-plus",
|
||||
"categories": {
|
||||
"visual-engineering": {
|
||||
"model": "bailian-coding-plan/qwen3.5-plus",
|
||||
"description": "Frontend, UI/UX, design, styling"
|
||||
},
|
||||
"ultrabrain": {
|
||||
"model": "bailian-coding-plan/qwen3-coder-next",
|
||||
"description": "Complex logic, algorithms, architecture"
|
||||
},
|
||||
"quick": {
|
||||
"model": "opencode-go/minimax-m2.5",
|
||||
"description": "Simple edits, typo fixes"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Now OpenCode automatically picks the best model for each task — fast models for simple changes to save cost, stronger models for complex architecture decisions.
|
||||
|
||||
#### Extending OpenCode with MCP Servers
|
||||
|
||||
MCP (Model Context Protocol) is an open standard that lets AI coding tools call external services — browsers, web search, image analysis, and more. OpenCode supports MCP natively, with configuration similar to Claude Code.
|
||||
|
||||
Add server entries to the `mcp` field in `opencode.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcp": {
|
||||
"chrome-devtools": {
|
||||
"type": "local",
|
||||
"command": ["npx", "-y", "chrome-devtools-mcp@latest"]
|
||||
},
|
||||
"zai-mcp-server": {
|
||||
"type": "local",
|
||||
"command": ["npx", "-y", "@z_ai/mcp-server"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
After restarting OpenCode, the AI can call these tools automatically during conversation — opening a browser to take screenshots, analyzing UI mockups, searching the web, and more.
|
||||
|
||||
> 🎯 **Practical example**: With the chrome-devtools MCP configured, you can simply say "Open this page and check why the button is misaligned" — the AI will open the browser, take a screenshot, analyze the layout, and suggest a fix.
|
||||
|
||||
#### Tips and Troubleshooting
|
||||
|
||||
**Guiding AI behavior with AGENTS.md**
|
||||
|
||||
Create an `AGENTS.md` file in your project root to tell OpenCode about your project's conventions and preferences. The AI reads this file automatically on each launch:
|
||||
|
||||
```markdown
|
||||
## Project Conventions
|
||||
- Use TypeScript strict mode
|
||||
- All API responses must conform to JSON Schema
|
||||
- Use custom Error subclasses for error handling
|
||||
|
||||
## Development Workflow
|
||||
1. Understand existing code before making changes
|
||||
2. Commit in small, logical units
|
||||
3. Run npm test to verify after each change
|
||||
|
||||
## Prohibited
|
||||
- Do not use the `any` type
|
||||
- Do not delete test files
|
||||
```
|
||||
|
||||
**Exploring codebases in parallel**
|
||||
|
||||
When you're unfamiliar with a project, ask OpenCode to search multiple aspects at once:
|
||||
|
||||
> Please do the following in parallel:
|
||||
> 1. Find all places handling HTTP requests
|
||||
> 2. Locate database-related code
|
||||
> 3. Map out the project directory structure and module responsibilities
|
||||
|
||||
OpenCode executes these explorations simultaneously, giving you a complete codebase map in one go.
|
||||
|
||||
**Common Issues**
|
||||
|
||||
| Problem | Solution |
|
||||
|---------|----------|
|
||||
| `opencode` command not found | npm global directory not in PATH. Run: `[Environment]::SetEnvironmentVariable("Path", "$env:Path;$env:USERPROFILE\AppData\Roaming\npm", "User")` and restart terminal |
|
||||
| AI response is slow | Use the `quick` category for simple tasks (routes to fast models); start a fresh session if conversation history is too long |
|
||||
| API call fails | Check that your API Key is correct, the model name uses the right format (provider/model-name), and your account has sufficient balance |
|
||||
| Skills not working | Verify that the SKILL.md file has valid YAML frontmatter and that the description accurately describes the trigger condition |
|
||||
| Context too long | Open a new session, or define key conventions in AGENTS.md so new sessions inherit them |
|
||||
|
||||
## More Use Cases for CLI AI Coding Tools
|
||||
|
||||
### Use AI to Write Requirement Documents: Learn to "Concretize Requirements"
|
||||
|
||||
@@ -615,6 +615,122 @@ Prometheus (claude-opus-4-7 / kimi-k2.6 / glm-5.1) 是你的战略规划师。
|
||||
|
||||
了解完这些, 你就可以使用装好 Oh-My-OpenAgent 插件之后的 OpenCode 来完成编码任务了。
|
||||
|
||||
#### 配置模型与 API（进阶）
|
||||
|
||||
通过 `/connect` 可以在聊天界面中快速接入模型，但如果你需要更精细的控制——比如为不同任务指定不同模型、配置多个 API Provider 备用——就可以直接编辑 OpenCode 的配置文件 `opencode.json`。
|
||||
|
||||
这个文件位于 `~/.config/opencode/opencode.json`（Windows 路径：`C:\Users\你的用户名\.config\opencode\opencode.json`），首次启动 OpenCode 时会自动生成。
|
||||
|
||||
以下是一个接入百炼平台（阿里云）Qwen 模型的配置示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "bailian-coding-plan/qwen3.5-plus",
|
||||
"small_model": "bailian-coding-plan/qwen3.5-plus",
|
||||
"provider": {
|
||||
"bailian-coding-plan": {
|
||||
"options": {
|
||||
"apiKey": "sk-你的API密钥"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> 💡 `model` 字段的格式为 `提供商/模型名称`。你可以在对应平台注册并获取 API Key 后，替换上面的 `apiKey` 值。
|
||||
|
||||
如果你想同时配置多个模型，可以在配置中指定不同任务分类：
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "bailian-coding-plan/qwen3.5-plus",
|
||||
"categories": {
|
||||
"visual-engineering": {
|
||||
"model": "bailian-coding-plan/qwen3.5-plus",
|
||||
"description": "前端、UI/UX、设计、样式"
|
||||
},
|
||||
"ultrabrain": {
|
||||
"model": "bailian-coding-plan/qwen3-coder-next",
|
||||
"description": "复杂逻辑、算法、架构决策"
|
||||
},
|
||||
"quick": {
|
||||
"model": "opencode-go/minimax-m2.5",
|
||||
"description": "简单修改、拼写修复"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这样，OpenCode 就会根据任务类型自动选择最合适的模型：简单修改用快模型节省成本，复杂架构问题用更强模型保证质量。
|
||||
|
||||
#### 使用 MCP 服务器扩展 OpenCode
|
||||
|
||||
MCP（Model Context Protocol）是一个开放协议，让 AI 编程工具可以调用外部工具——比如操作浏览器、搜索网络、分析图片等。OpenCode 原生支持 MCP，配置方式和 Claude Code 类似。
|
||||
|
||||
在 `opencode.json` 的 `mcp` 字段中添加服务器配置：
|
||||
|
||||
```json
|
||||
{
|
||||
"mcp": {
|
||||
"chrome-devtools": {
|
||||
"type": "local",
|
||||
"command": ["npx", "-y", "chrome-devtools-mcp@latest"]
|
||||
},
|
||||
"zai-mcp-server": {
|
||||
"type": "local",
|
||||
"command": ["npx", "-y", "@z_ai/mcp-server"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
配置完成后重启 OpenCode，AI 就能在对话中自动调用这些工具——比如帮你打开浏览器截图、分析 UI 设计图、搜索网页信息等。
|
||||
|
||||
> 🎯 **实用场景**：当你需要 AI 帮你分析一个网页的布局问题时，配上 chrome-devtools MCP，直接说「帮我打开这个页面，看看为什么按钮位置不对」，AI 就能自动打开浏览器、截图、分析并给出修复建议。
|
||||
|
||||
#### 日常使用技巧与常见问题
|
||||
|
||||
**使用 AGENTS.md 指导 AI 行为**
|
||||
|
||||
在项目根目录创建 `AGENTS.md` 文件，可以告诉 OpenCode 你的项目约定和偏好。AI 每次启动时会自动读取这个文件：
|
||||
|
||||
```markdown
|
||||
## 项目约定
|
||||
- 使用 TypeScript 严格模式
|
||||
- API 响应必须符合 JSON Schema
|
||||
- 错误处理使用自定义 Error 子类
|
||||
|
||||
## 开发流程
|
||||
1. 修改前先理解现有代码
|
||||
2. 小步提交，每次提交一个逻辑单元
|
||||
3. 完成后运行 npm test 验证
|
||||
|
||||
## 禁止事项
|
||||
- 不要使用 any 类型
|
||||
- 不要删除测试文件
|
||||
```
|
||||
|
||||
**并行探索代码库**
|
||||
|
||||
当你不熟悉一个项目时，可以让 OpenCode 同时搜索多个方面：
|
||||
|
||||
> 帮我同时做这几件事：
|
||||
> 1. 搜索项目中所有处理 HTTP 请求的地方
|
||||
> 2. 找出数据库相关的代码
|
||||
> 3. 列出项目的目录结构和各模块职责
|
||||
|
||||
OpenCode 会并行执行这些探索任务，一次性给你完整的代码库地图。
|
||||
|
||||
**常见问题**
|
||||
|
||||
| 问题 | 解决方法 |
|
||||
|------|---------|
|
||||
| `opencode` 命令找不到 | npm 全局目录不在 PATH 中。在终端执行：`[Environment]::SetEnvironmentVariable("Path", "$env:Path;$env:USERPROFILE\AppData\Roaming\npm", "User")` 后重启终端 |
|
||||
| AI 响应很慢 | 简单任务使用 quick 分类（自动路由到快模型）；对话历史太长时可以开新会话 |
|
||||
| API 调用失败 | 检查 API Key 是否正确、模型名称拼写是否准确（provider/model-name 格式）、账户余额是否充足 |
|
||||
| 技能（Skills）不生效 | 确认 SKILL.md 文件格式正确（需要 YAML frontmatter），且 description 字段准确描述了触发条件 |
|
||||
| 对话上下文太长 | 开启新会话，或在 AGENTS.md 中定义关键约定让新会话也能继承 |
|
||||
|
||||
## CLI AI 编程工具的更多用法
|
||||
|
||||
### 用 AI 写需求文档：学会“具体化需求”
|
||||
|
||||
Reference in New Issue
Block a user