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

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

• [OpenCode 高级配置与集成](#OpenCode 高级配置与集成)
• • 一、前言
  • 二、本地模型配置
  • • 方式一：Ollama（推荐）
    • [方式二：LM Studio](#方式二：LM Studio)
    • 方式三：llama.cpp
    • 本地模型推荐
  • [三、AGENTS.md 配置](#三、AGENTS.md 配置)
  • • 创建方式
    • 推荐结构
    • 高级配置
  • [四、IDE 集成](#四、IDE 集成)
  • • [VS Code / Cursor](#VS Code / Cursor)
    • 非交互模式
  • [五、GitHub 集成](#五、GitHub 集成)
  • • 快速设置（推荐）
    • 手动设置
    • 使用方法
    • 工作流程
  • 六、配置文件详解
  • • 配置文件位置
    • 完整配置示例
    • 自定义快捷键
  • 七、自定义提供商
  • • [OpenAI 兼容 API](#OpenAI 兼容 API)
    • 添加凭证
  • 八、主题配置
  • 九、故障排查
  • • 检查凭证配置
    • 检查配置文件
    • 常见问题
  • 十、系列总结
  • • 继续学习
    • 保持更新

OpenCode 高级配置与集成

一、前言

前面三篇我们学习了 OpenCode 的基础使用和实战技巧。本文将深入介绍高级配置，包括本地模型、AGENTS.md 定制、IDE 集成和 GitHub 集成。

---

二、本地模型配置

如果你注重隐私或想节省 API 费用，可以使用本地模型。

方式一：Ollama（推荐）

Ollama 是最流行的本地模型运行工具。

1. 安装 Ollama

# macOS
brew install ollama

# Linux
curl -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 --port 8080

2. 配置 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 更好地理解你的项目。

创建方式

方式一：自动生成

/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 github install

这会引导你完成：

1. 安装 GitHub App
2. 创建工作流文件
3. 配置 Secrets

手动设置

1. 安装 GitHub App

访问 github.com/apps/opencode-agent，确保已安装到目标仓库。

2. 创建 GitHub Action

在项目中创建 .github/workflows/opencode.yml：

name: OpenCode

on:
  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-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup OpenCode
        run: curl -fsSL https://opencode.ai/install | bash
        
      - name: Run OpenCode
        env:
          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

---

六、配置文件详解

配置文件位置

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

优先级	位置	作用
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 系列教程！现在你已经掌握了：

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

继续学习

• 官方文档：opencode.ai/docs
• GitHub 仓库：github.com/sst/opencode
• Discord 社区：加入讨论，获取帮助

保持更新

OpenCode 在快速迭代中，建议定期更新：

# 推荐方式
opencode upgrade

# 或使用 npm
npm update -g opencode-ai

# 或重新运行安装脚本（macOS / Linux）
curl -fsSL https://opencode.ai/install | bash

---