Open Code教程（四）| 高级配置与集成

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:7b

3. 启动 Ollama 服务

ollama serve

4. 配置 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 --port8080

2. 配置 OpenCode

{"$schema":"https://opencode.ai/config.json","provider":{"llamacpp":{"models":{"local-model":{}}}}}

本地模型推荐

显存不足？可以选择量化版本（如 Q4_K_M），显存需求减半。

三、AGENTS.md 配置

AGENTS.md 是项目级的 AI 配置文件，帮助 OpenCode 更好地理解你的项目。

创建方式

方式一：自动生成

/init

OpenCode 会分析项目并生成初始的 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

方式一：内置终端

1. 在 VS Code 中打开终端（`Ctrl+`` ）
2. 运行opencode
3. 正常使用

方式二：分屏视图

1. 运行opencode
2. 按Cmd+Esc（Mac）或Ctrl+Esc（Windows/Linux）
3. 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

这会引导你完成：

1. 安装 GitHub App
2. 创建工作流文件
3. 配置 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 run

3. 配置 Secrets

在 GitHub 仓库设置中添加：

• ANTHROPIC_API_KEY：你的 AI 提供商 API Key

使用方法

在 Issue 或 PR 评论中：

/opencode 修复这个 issue 中描述的 bug

/oc 帮我 review 这个 PR 的代码

/opencode 根据这个 issue 的描述，实现功能并提交 PR

工作流程

1. 你在 Issue/PR 中评论/opencode+ 指令
2. GitHub Action 触发
3. OpenCode 分析问题并执行
4. 自动创建分支、提交代码、创建 PR

六、配置文件详解

配置文件位置

配置文件按以下优先级加载（后面的覆盖前面的）：

凭证存储位置：~/.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 系列教程！现在你已经掌握了：

1. 入门篇：安装、配置、基础使用
2. 命令篇：所有命令和快捷键
3. 实战篇：10+ 真实开发场景
4. 进阶篇：本地模型、高级配置、集成

继续学习

• 官方文档：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