OpenCode 快速入门最佳实践

开源 AI 编程助手 OpenCode 的安装配置与高效使用指南

---

什么是 OpenCode

OpenCode 是一款开源的 AI 编程助手，支持终端界面（TUI）、桌面应用和 IDE 扩展三种使用方式。它基于 AI SDK 支持 75+ 种 LLM 提供商，包括 Anthropic、OpenAI、DeepSeek 等主流服务。

核心特点：

• 开源免费：完全开源，可自由使用和定制
• 多模型支持：支持 Claude、GPT、DeepSeek 等 75+ 种模型
• 终端原生：专为终端用户设计，支持 Vim 风格快捷键
• 项目感知：通过 AGENTS.md 理解项目结构和编码规范

---

安装 OpenCode

方式一：一键安装脚本（推荐）

curl -fsSL https://opencode.ai/install | bash

方式二：使用包管理器

# macOS/Linux - Homebrew
brew install opencode

# Node.js - npm
npm install -g opencode-ai

# Node.js - pnpm
pnpm install -g opencode-ai

# Windows - Chocolatey
choco install opencode

# Windows - Scoop
scoop bucket add extras
scoop install extras/opencode

方式三：Docker

docker run -it --rm ghcr.io/anomalyco/opencode

终端要求

为获得最佳体验，建议使用现代终端模拟器：WezTerm、Alacritty、Ghostty 或 Kitty。

---

在 VSCode 中使用 OpenCode

除了终端界面，OpenCode 还提供 VSCode 扩展，让你在熟悉的编辑器中使用 AI 编程助手。

安装步骤：

1. 打开 VSCode，进入扩展市场（快捷键 Cmd+Shift+X 或 Ctrl+Shift+X）
2. 搜索 "OpenCode"
3. 点击安装 OpenCode 扩展

使用方式：

• 使用命令面板（Cmd+Shift+P 或 Ctrl+Shift+P）搜索 "OpenCode" 相关命令
• 扩展会在侧边栏添加 OpenCode 面板，可以直接与 AI 对话
• 支持选中代码后右键调用 OpenCode 进行解释或重构

配置说明：

VSCode 扩展会复用终端版本的配置文件（~/.config/opencode/opencode.json），所以你只需配置一次即可在两个环境中使用。

TIP

如果你更喜欢图形界面，OpenCode 还提供独立的桌面应用，可以从 GitHub Releases 下载。

---

配置 LLM 提供商

OpenCode 需要配置 LLM 提供商才能使用。以下是几种常见的配置方式：

方式一：使用 OpenCode Zen（最简单）

OpenCode 官方提供的模型服务，已经过测试验证：

# 启动 OpenCode 后运行
/connect
# 选择 opencode，然后访问 opencode.ai/auth 获取 API Key

方式二：使用 Anthropic Claude

/connect
# 选择 Anthropic
# 如果有 Claude Pro/Max 订阅，选择对应选项
# 或者手动输入 API Key

方式三：使用 OpenAI

/connect
# 选择 OpenAI
# 输入你的 API Key

方式四：使用 DeepSeek（国内推荐）

/connect
# 选择 DeepSeek
# 输入你的 API Key

方式五：使用智谱 GLM（国内推荐）

智谱 GLM 4.7 是国产大模型中编程能力较强的选择。由于 OpenCode 没有内置智谱，需要通过自定义提供商配置：

1. 前往 智谱开放平台 注册账号并获取 API Key

2. 在 OpenCode 中添加凭证：

/connect
# 滚动到底部选择 Other
# 输入提供商 ID：zhipu
# 输入你的智谱 API Key

3. 创建或编辑配置文件 ~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "zhipu": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "智谱 AI",
      "options": {
        "baseURL": "https://open.bigmodel.cn/api/paas/v4"
      },
      "models": {
        "glm-4-plus": {
          "name": "GLM-4 Plus",
          "limit": {
            "context": 128000,
            "output": 4096
          }
        },
        "glm-4.7": {
          "name": "GLM-4.7（推荐）",
          "limit": {
            "context": 128000,
            "output": 16384
          }
        },
        "codegeex-4": {
          "name": "CodeGeeX-4（代码专用）",
          "limit": {
            "context": 128000,
            "output": 4096
          }
        }
      }
    }
  },
  "model": "zhipu/glm-4.7"
}

4. 重启 OpenCode，运行 /models 即可看到智谱的模型选项

智谱模型推荐

• GLM-4.7：最新版本，综合能力强，推荐日常使用
• CodeGeeX-4：代码专用模型，适合纯编程任务
• GLM-4 Plus：稳定版本，性价比高

配置完成后，使用 /models 命令选择要使用的模型。

---

初始化项目

进入你的项目目录，启动 OpenCode：

cd /path/to/your/project
opencode

首次使用时，运行初始化命令：

/init

这会让 OpenCode 分析你的项目结构，并在项目根目录创建 AGENTS.md 文件。这个文件帮助 OpenCode 理解：

• 项目的技术栈和框架
• 代码风格和命名规范
• 目录结构和模块划分

重要

AGENTS.md 文件建议提交到版本控制，这样团队成员都能获得一致的 AI 辅助体验。

---

核心使用技巧

Plan 模式 vs Build 模式

OpenCode 有两种工作模式，通过 Tab 键切换：

• Plan 模式：AI 只提供建议和计划，不修改代码
• Build 模式：AI 可以直接修改代码文件

最佳实践是先用 Plan 模式讨论方案，确认后再切换到 Build 模式执行。

提问技巧

# 询问代码逻辑
How is authentication handled in @src/auth/index.ts

# 添加功能（先规划）
<Tab 切换到 Plan 模式>
我想添加一个用户删除功能，删除后数据保留 30 天可恢复

# 确认方案后执行
<Tab 切换到 Build 模式>
方案看起来不错，请开始实现

引用文件

使用 @ 符号引用项目中的文件：

参考 @src/utils/helper.ts 的实现方式，在 @src/services/user.ts 中添加类似的错误处理

撤销和重做

/undo  # 撤销上一次修改
/redo  # 重做撤销的修改

---

常用命令速查

命令	说明
/init	初始化项目，生成 AGENTS.md
/connect	配置 LLM 提供商
/models	选择使用的模型
/undo	撤销上一次修改
/redo	重做撤销的修改
/share	分享当前对话
Tab	切换 Plan/Build 模式

---

快捷键速查

OpenCode 使用 Leader 键（默认 Ctrl+X）作为快捷键前缀：

快捷键	说明
Ctrl+X 然后 n	新建会话
Ctrl+X 然后 l	会话列表
Ctrl+X 然后 m	模型列表
Ctrl+X 然后 u	撤销
Ctrl+X 然后 r	重做
Tab	切换 Agent 模式
Escape	中断当前操作

---

配置文件

OpenCode 支持 JSON 配置文件，可以放在以下位置：

• 全局配置：~/.config/opencode/opencode.json
• 项目配置：项目根目录的 opencode.json

示例配置：

{
  "$schema": "https://opencode.ai/config.json",
  "theme": "opencode",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

常用配置项：

• theme：界面主题
• model：默认使用的模型
• autoupdate：是否自动更新
• permission：工具权限设置（ask 表示需要确认）

---

本地模型支持

OpenCode 支持通过 Ollama、LM Studio 等运行本地模型：

Ollama 配置示例：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "llama2": {
          "name": "Llama 2"
        }
      }
    }
  }
}

---

最佳实践总结

1. 先规划后执行：复杂任务先用 Plan 模式讨论方案
2. 维护 AGENTS.md：保持项目说明文件的更新，提升 AI 理解准确度
3. 善用文件引用：用 @ 引用相关文件，让 AI 有更多上下文
4. 及时撤销：发现问题立即 /undo，避免错误扩散
5. 选择合适的模型：简单任务用快速模型，复杂任务用强力模型

---

相关资源

• 官方文档：https://opencode.ai/docs/
• GitHub 仓库：https://github.com/anomalyco/opencode
• 模型列表：https://models.dev/