OpenCode 详细使用技巧及案例指南

本文内容整理自知乎文章 《OpenCode 详细使用技巧及案例指南》，原作者：鲸落成古，访问地址：https://zhuanlan.zhihu.com/p/2015100901883402220

目录

• 1. 简介与安装
  • 1.1 什么是 OpenCode？
  • 1.2 安装方式
  • 1.3 初始配置
• 2. 基础入门
  • 2.1 基本命令
  • 2.2 提问技巧
  • 2.3 添加功能
  • 2.4 直接修改代码
• 3. 进阶技巧
  • 3.1 AGENTS.md 文件
  • 3.2 多会话并行处理
  • 3.3 自定义 Rules
  • 3.4 常用快捷键
• 4. 高级用法
  • 4.1 自定义 Tools
  • 4.2 MCP 服务器集成
  • 4.3 自定义 Commands
  • 4.4 连接到其他 LLM 提供商
  • 4.5 性能优化

1. 简介与安装

1.1 什么是 OpenCode？

OpenCode 是一个开源的 AI 编程助手，可作为终端界面、桌面应用或 IDE 扩展使用。它支持：

• 多模型支持：75+ LLM 提供商，包括 Claude、GPT、Gemini 等
• 多平台：终端、桌面应用、IDE 扩展
• LSP 自动加载：自动加载正确的语言服务器
• 多会话：可并行启动多个代理
• 隐私优先：不存储代码或上下文数据

1.2 安装方式

# 官方安装脚本（推荐）
curl -fsSL https://opencode.ai/install | bash

# 使用 npm
npm install -g opencode-ai

# 使用 Bun
bun install -g opencode-ai

# 使用 Homebrew (macOS/Linux)
brew install anomalyco/tap/opencode

# Windows (使用 Chocolatey)
choco install opencode

# Windows (使用 Scoop)
scoop install opencode

1.3 初始配置

# 1. 运行 OpenCode 并连接提供商
opencode/connect

# 2. 选择 opencode 登录
# 3. 访问 opencode.ai/auth 获取 API Key
# 4. 粘贴 API Key 完成配置

# 5. 初始化项目
cd /你的项目目录
opencode/init

提示：建议将 AGENTS.md 文件提交到 Git，帮助 OpenCode 理解项目结构。

2. 基础入门

2.1 基本命令

命令	说明
opencode	启动 OpenCode
opencode -c	继续上次会话
/init	初始化项目分析
/connect	连接 LLM 提供商
/share	分享当前会话链接
/editor	打开外部编辑器
/undo	撤销上一次更改
/redo	重做上一次更改
/exit	退出 OpenCode

2.2 提问技巧

使用 @ 引用文件

# 直接询问关于特定文件的问题
How is authentication handled in @packages/functions/src/api/index.ts

使用 @ 模糊搜索文件

# 按文件名模糊搜索项目中的文件
@auth
@*.controller.ts

2.3 添加功能

Plan Mode（计划模式）
按 Tab 键切换到计划模式，此时 OpenCode 只会生成计划而不会实际修改代码。

# 切换到计划模式
<Tab>

# 描述你想要的功能
当用户删除笔记时，我们希望在数据库中将其标记为已删除。然后创建一个显示所有最近删除笔记的屏幕。用户可以从这个屏幕恢复笔记或永久删除它。

# 迭代计划
# 提供更多细节
我们希望使用我之前用过的设计来设计这个新屏幕。[图片 #1] 查看这张图片并将其作为参考。

提示：可以将图片拖拽到终端中，OpenCode 会扫描并将其添加到提示中。

切换到构建模式

# 切换回构建模式
<Tab>

# 让 OpenCode 执行计划
Sounds good! Go ahead and make the changes.

2.4 直接修改代码

对于更简单的修改，可以直接要求 OpenCode 进行修改：

# 直接要求添加功能
We need to add authentication to the /settings route. Take a look at how this is
handled in the /notes route in @packages/functions/src/notes.ts and implement
the same logic in @packages/functions/src/settings.ts

3. 进阶技巧

3.1 AGENTS.md 文件

创建 AGENTS.md 文件来指导 OpenCode：

# AGENTS.md

## 项目概述
这是一个使用 React + Node.js 的全栈项目

## 技术栈
- 前端: React 18, TypeScript, TailwindCSS
- 后端: Express, PostgreSQL, Prisma

## 代码规范
- 使用函数式组件
- 组件文件以 .tsx 结尾
- 使用 CSS Modules 进行样式管理

## 重要文件结构
- /src/components - React 组件
- /src/hooks - 自定义 hooks
- /src/api - API 路由处理

3.2 多会话并行处理

OpenCode 支持启动多个代理并行处理同一项目：

# 在不同终端窗口中运行
opencode

# 每个会话都是独立的，可以并行处理不同任务

3.3 自定义 Rules

在 .opencode/rules.md 中添加项目特定的规则：

# .opencode/rules.md

## 代码审查规则
- 所有 PR 需要至少 2 人 review
- 必须包含单元测试

## 提交规范
- 使用 conventional commits 格式
- 类型: 描述

3.4 常用快捷键

快捷键	说明
Tab	切换 Plan/Build 模式
Ctrl+C	取消当前操作
Ctrl+K	搜索命令
Ctrl+P	命令列表
Ctrl+T	切换模型变体
↑/↓	导航历史消息

4. 高级用法

4.1 自定义 Tools

创建自定义工具扩展 OpenCode 功能：

// .opencode/tools/my-tool.ts
import { tool } from "@opencode-ai/plugin"

export default tool({
  description: "执行自定义操作",
  args: {
    input: tool.schema.string()
  },
  async execute(args, context) {
    // 自定义逻辑
    return { result: 'success' }
  }
})

注意：自定义工具需放在 .opencode/tools/ 目录下。

4.2 MCP 服务器集成

配置 MCP (Model Context Protocol) 服务器，注意使用 JSON 格式：

// opencode.json
{
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "environment": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

4.3 自定义 Commands

创建自定义命令，需将命令文件放在 .opencode/commands/ 目录：

---
description: 运行测试
agent: build
---

运行完整的测试套件并显示结果。

4.4 连接到其他 LLM 提供商

Anthropic (Claude)

/connect
# 选择 Anthropic
# 输入 API Key

OpenAI (GPT)

/connect
# 选择 OpenAI
# 输入 API Key

自定义 Provider

// opencode.json
{
  "providers": [
    {
      "name": "custom",
      "apiKey": "${OPENAI_API_KEY}"  // 使用环境变量
    }
  ]
}

4.5 性能优化

• 使用 /init：首次运行时初始化项目分析
• 合理使用计划模式：复杂功能先计划再执行
• 批量操作：将相关修改合并为一个请求

---

原文链接：OpenCode 详细使用技巧及案例指南
原作者：鲸落成古
发布时间：2024年