Open Code教程（四）| 高级配置与集成
- OpenCode 高级配置与集成
- 一、前言
- 二、本地模型配置
- 方式一：Ollama（推荐）
- 方式二：LM Studio
- 方式三：llama.cpp
- 本地模型推荐
- 三、AGENTS.md 配置
- 创建方式
- 推荐结构
- 高级配置
- 四、IDE 集成
- VS Code / Cursor
- 非交互模式
- 五、GitHub 集成
- 快速设置（推荐）
- 手动设置
- 使用方法
- 工作流程
- 六、配置文件详解
- 配置文件位置
- 完整配置示例
- 自定义快捷键
- 七、自定义提供商
- OpenAI 兼容 API
- 添加凭证
- 八、主题配置
- 九、故障排查
- 检查凭证配置
- 检查配置文件
- 常见问题
- 十、系列总结
- 继续学习
- 保持更新
OpenCode 高级配置与集成
一、前言
前面三篇我们学习了 OpenCode 的基础使用和实战技巧。本文将深入介绍高级配置，包括本地模型、AGENTS.md 定制、IDE 集成和 GitHub 集成。
二、本地模型配置
如果你注重隐私或想节省 API 费用，可以使用本地模型。
方式一：Ollama（推荐）
Ollama 是最流行的本地模型运行工具。
1. 安装 Ollama
# macOSbrewinstallollama# Linuxcurl-fsSL https://ollama.com/install.sh|sh# Windows# 从 https://ollama.com/download 下载安装包2. 下载模型
# 推荐的编程模型ollama pull deepseek-coder:6.7b ollama pull codellama:7b ollama pull qwen2.5-coder:7b3. 启动 Ollama 服务
ollama serve4. 配置 OpenCode
创建或编辑~/.config/opencode/opencode.json：
{"$schema":"https://opencode.ai/config.json","provider":{"ollama":{"models":{"deepseek-coder:6.7b":{},"codellama:7b":{},"qwen2.5-coder:7b":{}}}}}注意：Ollama 默认运行在localhost:11434，OpenCode 会自动识别。
5. 使用
启动 OpenCode 后，输入/models可以看到本地模型。
方式二：LM Studio
LM Studio 提供图形界面，更适合新手。
1. 安装 LM Studio
从 lmstudio.ai 下载安装。
2. 下载并启动模型
在 LM Studio 中搜索并下载模型，然后点击 “Start Server”。
3. 配置 OpenCode
{"$schema":"https://opencode.ai/config.json","provider":{"lmstudio":{"models":{"your-model-name":{}}}}}注意：LM Studio 默认在localhost:1234启动服务器，OpenCode 会自动识别。
方式三：llama.cpp
如果你想要更底层的控制，可以直接使用 llama.cpp。
1. 启动 llama-server
./llama-server -m your-model.gguf --port80802. 配置 OpenCode
{"$schema":"https://opencode.ai/config.json","provider":{"llamacpp":{"models":{"local-model":{}}}}}本地模型推荐
| 模型 | 参数量 | 显存需求 | 特点 |
|---|---|---|---|
| DeepSeek Coder 6.7B | 6.7B | ~6GB | 中文友好，编程能力强 |
| Code Llama 7B | 7B | ~6GB | Meta 出品，通用编程 |
| Qwen2.5 Coder 7B | 7B | ~6GB | 阿里出品，中文优秀 |
| Mistral 7B | 7B | ~6GB | 通用能力强 |
显存不足？可以选择量化版本（如 Q4_K_M），显存需求减半。
三、AGENTS.md 配置
AGENTS.md 是项目级的 AI 配置文件，帮助 OpenCode 更好地理解你的项目。
创建方式
方式一：自动生成
/initOpenCode 会分析项目并生成初始的 AGENTS.md。
方式二：手动创建
在项目根目录创建AGENTS.md文件。
推荐结构
# 项目名称 ## 项目简介 简要描述项目是做什么的，核心功能有哪些。 ## 技术栈 - 前端：React 18 + TypeScript + Tailwind CSS - 后端：Node.js + Express + PostgreSQL - 工具：Vite、ESLint、Prettier ## 项目结构 ``` src/ ├── components/ # React 组件 ├── pages/ # 页面组件 ├── hooks/ # 自定义 Hooks ├── services/ # API 服务 ├── stores/ # 状态管理（Zustand） ├── utils/ # 工具函数 └── types/ # TypeScript 类型定义 ``` ## 代码规范 - 组件使用函数式组件 + Hooks - 使用 TypeScript 严格模式 - 变量命名使用 camelCase - 组件命名使用 PascalCase - 文件命名使用 kebab-case - 注释使用中文 ## API 规范 - 基础路径：/api/v1 - 认证方式：Bearer Token - 响应格式：{ code: number, message: string, data: T } ## 常用命令 ```bash npm run dev # 启动开发服务器 npm run build # 构建生产版本 npm run test # 运行测试 npm run lint # 代码检查 ``` ## 注意事项 - 敏感配置放在 .env 文件中 - 不要直接修改 node_modules - 提交前运行 lint 和 test高级配置
你还可以在 AGENTS.md 中添加：
特定文件说明
## 重要文件说明 ### src/services/api.ts 封装了所有 HTTP 请求，包括拦截器和错误处理。修改时注意保持向后兼容。 ### src/stores/authStore.ts 用户认证状态管理，包含登录、登出、Token 刷新逻辑。禁止修改的文件
## 禁止修改 以下文件由工具自动生成，请勿手动修改： - src/generated/* - src/types/api.d.ts四、IDE 集成
VS Code / Cursor
方式一：内置终端
- 在 VS Code 中打开终端（`Ctrl+`` ）
- 运行
opencode - 正常使用
方式二：分屏视图
- 运行
opencode - 按
Cmd+Esc（Mac）或Ctrl+Esc（Windows/Linux） - OpenCode 会在 IDE 中以分屏形式打开
非交互模式
适合脚本和自动化，使用opencode run命令：
# 单次提问，执行完自动退出opencode run"解释 @src/utils/api.ts 的作用"# 指定模型opencode run -m anthropic/claude-sonnet-4-20250514"检查代码中是否有安全问题"# 分享会话结果opencode run --share"重构这个函数"五、GitHub 集成
OpenCode 可以直接在 GitHub 工作流中使用，自动处理 Issue 和 PR。
快速设置（推荐）
在项目目录中运行：
opencode githubinstall这会引导你完成：
- 安装 GitHub App
- 创建工作流文件
- 配置 Secrets
手动设置
1. 安装 GitHub App
访问 github.com/apps/opencode-agent，确保已安装到目标仓库。
2. 创建 GitHub Action
在项目中创建.github/workflows/opencode.yml：
name:OpenCodeon:issue_comment:types:[created]pull_request_review_comment:types:[created]jobs:opencode:if:contains(github.event.comment.body,'/opencode')||contains(github.event.comment.body,'/oc')runs-on:ubuntu-lateststeps:-uses:actions/checkout@v4-name:Setup OpenCoderun:curl-fsSL https://opencode.ai/install|bash-name:Run OpenCodeenv:ANTHROPIC_API_KEY:${{secrets.ANTHROPIC_API_KEY}}GITHUB_TOKEN:${{secrets.GITHUB_TOKEN}}run:|opencode github run3. 配置 Secrets
在 GitHub 仓库设置中添加：
ANTHROPIC_API_KEY：你的 AI 提供商 API Key
使用方法
在 Issue 或 PR 评论中：
/opencode 修复这个 issue 中描述的 bug/oc 帮我 review 这个 PR 的代码/opencode 根据这个 issue 的描述，实现功能并提交 PR工作流程
- 你在 Issue/PR 中评论
/opencode+ 指令 - GitHub Action 触发
- OpenCode 分析问题并执行
- 自动创建分支、提交代码、创建 PR
六、配置文件详解
配置文件位置
配置文件按以下优先级加载（后面的覆盖前面的）：
| 优先级 | 位置 | 作用 |
|---|---|---|
| 1 | 远程配置（.well-known/opencode） | 组织默认配置 |
| 2 | ~/.config/opencode/opencode.json | 全局用户配置 |
| 3 | OPENCODE_CONFIG环境变量指定的文件 | 自定义配置 |
| 4 | ./opencode.json（项目根目录） | 项目配置（最高优先级） |
凭证存储位置：~/.local/share/opencode/auth.json
注意：配置文件是合并的，不是替换。后面的配置只覆盖冲突的键，不冲突的设置会保留。
完整配置示例
{"$schema":"https://opencode.ai/config.json",// 默认模型"model":"anthropic/claude-sonnet-4-20250514",// 提供商配置"provider":{"anthropic":{"models":{"claude-sonnet-4-20250514":{"options":{"thinking":{"type":"enabled","budgetTokens":16000}}}}},"ollama":{"models":{"deepseek-coder:6.7b":{"name":"DeepSeek Coder"}}}},// TUI 配置"tui":{"scroll_speed":3,"scroll_acceleration":{"enabled":true}}}自定义快捷键
{"keybinds":{"input_submit":"enter","input_newline":"shift+enter,ctrl+j","app_exit":"ctrl+c,<leader>q"}}七、自定义提供商
如果你使用的 AI 服务不在内置列表中，可以添加自定义提供商。
OpenAI 兼容 API
很多服务提供 OpenAI 兼容的 API：
{"$schema":"https://opencode.ai/config.json","provider":{"my-provider":{"npm":"@ai-sdk/openai-compatible","name":"My Provider","options":{"baseURL":"https://api.my-provider.com/v1"},"models":{"my-model":{"name":"My Model"}}}}}添加凭证
opencode /connect# 选择 "Other"# 输入提供商 ID：my-provider# 输入 API Key八、主题配置
OpenCode 支持多种主题：
/theme选择喜欢的主题，设置会自动保存。
九、故障排查
检查凭证配置
opencode auth list检查配置文件
cat~/.config/opencode/opencode.json常见问题
Q: 模型列表为空？
- 检查 API Key 是否正确配置
- 检查网络连接
Q: 本地模型连接失败？
- 确认 Ollama/LM Studio 服务已启动
- 检查端口是否正确
Q: 配置不生效？
- 项目配置优先级高于全局配置
- 重启 OpenCode 使配置生效
十、系列总结
恭喜你完成了 OpenCode 系列教程！现在你已经掌握了：
- 入门篇：安装、配置、基础使用
- 命令篇：所有命令和快捷键
- 实战篇：10+ 真实开发场景
- 进阶篇：本地模型、高级配置、集成
继续学习
- 官方文档：opencode.ai/docs
- GitHub 仓库：github.com/sst/opencode
- Discord 社区：加入讨论，获取帮助
保持更新
OpenCode 在快速迭代中，建议定期更新：
# 推荐方式opencode upgrade# 或使用 npmnpmupdate -g opencode-ai# 或重新运行安装脚本（macOS / Linux）curl-fsSL https://opencode.ai/install|bash
)
