跳转至

OpenCode: Go 编写的终端 AI 编程工具

为什么要学 OpenCode

终端 AI 编程工具正在改变开发者的日常工作流。Claude Code、Aider 等工具证明了"在终端里与 AI 结对编程"这一范式的可行性,但它们各有局限——要么绑定单一模型,要么缺乏 LSP 集成,要么会话管理不够灵活。

OpenCode 是一个用 Go 编写的开源终端 AI 编程助手,解决了以下痛点:

痛点OpenCode 的解决方案
模型锁定支持 OpenAI、Anthropic、Google、Groq、OpenRouter 等多种 Provider
无代码感知内置 LSP 客户端,提供符号级代码理解
会话丢失SQLite 持久化会话,随时恢复上下文
扩展性差MCP (Model Context Protocol) 集成,可接入外部工具
启动慢Go 单二进制,毫秒级启动

如果你已经在用 Claude Code 或 Aider,学习 OpenCode 可以让你在需要多模型切换、更好的 LSP 支持或轻量部署时多一个选择。


核心概念

白话解释

OpenCode 本质上是一个"能读懂你代码的终端聊天工具"。它在终端里提供一个 TUI(终端用户界面),你可以: - 与 AI 对话,让它修改你的代码文件 - AI 通过 LSP 理解你项目的符号结构(函数、类、变量定义等) - 切换不同的 AI 模型来完成不同任务 - 历史会话全部存在本地 SQLite 数据库里

核心概念表

概念说明类比
ProviderAI 模型的提供商(如 Anthropic、OpenAI)类似快递公司
Model具体的 AI 模型(如 claude-sonnet-4-20250514、gpt-4o)具体的快递员
Session一次完整的对话上下文一个聊天窗口
LSP Client语言服务器协议客户端,用于代码理解编辑器的智能感知
MCP模型上下文协议,用于工具扩展插件系统
TUI终端用户界面终端里的图形化交互
ToolAI 可调用的工具(读写文件、执行命令等)AI 的"手"
Context发送给模型的上下文信息给 AI 看的背景资料

架构概览

┌─────────────────────────────────────┐
│           TUI (Bubble Tea)          │
├─────────────────────────────────────┤
│         Session Manager             │
│    (SQLite 持久化 / 会话切换)        │
├──────────┬──────────┬───────────────┤
│ Provider │   LSP    │     MCP       │
│ Manager  │  Client  │   Server      │
├──────────┴──────────┴───────────────┤
│         Tool System                  │
│  (文件读写/Shell执行/代码搜索)       │
└─────────────────────────────────────┘

安装配置

系统要求

  • Go 1.23+(从源码编译时需要)
  • macOS、Linux 或 WSL
  • 至少一个 AI Provider 的 API Key

安装方式

方式一:直接安装(推荐)

# 使用 Go install
go install github.com/opencode-ai/opencode@latest

# 或者使用 Homebrew (macOS/Linux)
brew install opencode-ai/tap/opencode

方式二:下载预编译二进制

# 从 GitHub Releases 下载
# https://github.com/opencode-ai/opencode/releases
# 选择对应系统的二进制文件

# Linux/macOS 示例
curl -fsSL https://github.com/opencode-ai/opencode/releases/latest/download/opencode_$(uname -s)_$(uname -m).tar.gz | tar xz
sudo mv opencode /usr/local/bin/

方式三:从源码编译

git clone https://github.com/opencode-ai/opencode.git
cd opencode
go build -o opencode .
sudo mv opencode /usr/local/bin/

配置 API Key

OpenCode 通过环境变量读取 API Key:

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI
export OPENAI_API_KEY="sk-..."

# Google AI
export GOOGLE_API_KEY="..."

# OpenRouter
export OPENROUTER_API_KEY="sk-or-..."

# 建议写入 shell 配置文件
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc

项目配置

在项目根目录创建 opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    }
  }
}

也可以使用 TOML 格式创建 opencode.toml

provider = "anthropic"
model = "claude-sonnet-4-20250514"

[mcpServers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "."]

快速上手

启动 OpenCode

# 在项目目录下启动
cd your-project
opencode

启动后你会看到一个终端界面,包含: - 消息区域:显示与 AI 的对话 - 输入框:输入你的请求 - 状态栏:显示当前模型、会话信息

基本对话

在输入框中直接输入你的需求:

请阅读 main.go 文件,然后解释这个项目的架构
帮我给 handleRequest 函数添加错误处理
在 utils/ 目录下创建一个新的 logger 模块

快捷键

快捷键功能
Ctrl+L清屏
Ctrl+C中断当前操作
Ctrl+O打开文件选择
Ctrl+K打开命令面板
Ctrl+N新建会话
Ctrl+P列出可用操作

上下文引用

使用 @ 符号引用文件:

@src/main.go 这个文件里的 init 函数有什么问题?

会话管理

# 查看历史会话列表
# 在 TUI 中使用 Ctrl+K 打开命令面板,选择 sessions

# 切换到之前的会话
# 从会话列表中选择即可恢复上下文

进阶用法

多模型切换

OpenCode 的一大优势是可以在会话中切换模型:

{
  "providers": {
    "anthropic": {
      "apiKey": "env:ANTHROPIC_API_KEY"
    },
    "openai": {
      "apiKey": "env:OPENAI_API_KEY"
    }
  },
  "models": {
    "default": "anthropic:claude-sonnet-4-20250514",
    "fast": "openai:gpt-4o-mini",
    "reasoning": "anthropic:claude-opus-4-20250514"
  }
}

在 TUI 中通过命令面板切换模型,适用于: - 简单任务用快速模型(省钱) - 复杂推理用高级模型(更准) - 代码生成用代码专用模型

LSP 集成

OpenCode 内置 LSP 客户端,自动检测并连接项目的语言服务器:

{
  "lsp": {
    "go": {
      "command": "gopls",
      "args": ["serve"]
    },
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"]
    },
    "python": {
      "command": "pyright-langserver",
      "args": ["--stdio"]
    }
  }
}

LSP 提供的能力: - 符号解析:AI 可以理解函数定义、类结构、导入关系 - 诊断信息:自动获取编译错误和警告 - 代码导航:跳转到定义、查找引用

MCP 服务器集成

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "env:GITHUB_TOKEN"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

自定义工具

OpenCode 提供了内置工具系统:

工具功能
read_file读取文件内容
write_file写入文件
edit_file编辑文件的特定部分
shell执行 Shell 命令
glob文件模式匹配搜索
grep内容搜索
lsp_diagnostics获取 LSP 诊断信息
lsp_symbols获取代码符号

非交互模式

# 直接执行单次请求
opencode -p "解释 main.go 的功能"

# 管道输入
cat error.log | opencode -p "分析这个错误日志"

# 与 shell 脚本集成
opencode -p "给 $(find . -name '*.go' | head -5) 添加注释" --output result.md

自定义系统提示词

{
  "systemPrompt": "你是一个 Go 语言专家。回答时优先使用标准库,避免不必要的第三方依赖。"
}

常见问题

Q1: OpenCode 和 Claude Code 有什么区别?

特性OpenCodeClaude Code
语言GoTypeScript/Node
模型支持多模型多 Provider仅 Anthropic
LSP 集成内置无原生 LSP
启动速度毫秒级秒级
开源完全开源官方工具
生态成长中成熟

Q2: 连接不上 API 怎么办?

# 检查 API Key 是否正确设置
echo $ANTHROPIC_API_KEY

# 检查网络连接
curl -s https://api.anthropic.com/v1/messages -H "x-api-key: $ANTHROPIC_API_KEY" -H "content-type: application/json" -H "anthropic-version: 2023-06-01" -d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

# 如需代理
export HTTPS_PROXY="http://127.0.0.1:7890"

Q3: LSP 不工作怎么办?

确保语言服务器已安装并在 PATH 中:

# Go
go install golang.org/x/tools/gopls@latest

# TypeScript
npm install -g typescript-language-server typescript

# Python
pip install pyright

Q4: 如何减少 Token 消耗?

  • 使用 @ 精确引用文件,避免让 AI 搜索整个项目
  • 简单任务使用快速模型(如 gpt-4o-mini)
  • 利用 LSP 提供符号信息,减少 AI 读取整个文件的需要
  • 新建会话处理不相关的任务,避免上下文膨胀

Q5: 会话数据存在哪里?

OpenCode 使用 SQLite 存储会话数据,默认位置:

~/.local/share/opencode/sessions.db

可以通过配置更改存储位置。所有数据存储在本地,不会上传到任何服务器。

Q6: 如何在团队中共享配置?

opencode.json 提交到项目仓库,但注意: - API Key 使用 env: 前缀引用环境变量 - 个人偏好放在 ~/.config/opencode/config.json - 项目级配置只包含团队共享的设置


参考资源

资源链接
GitHub 仓库https://github.com/opencode-ai/opencode
官方文档https://opencode.ai/docs
配置参考https://opencode.ai/docs/configuration
MCP 协议https://modelcontextprotocol.io
OpenRouter(多模型聚合)https://openrouter.ai
Go LSP 协议库https://pkg.go.dev/golang.org/x/tools/gopls

总结:OpenCode 是终端 AI 编程工具中多模型支持最好的选择之一。如果你需要在不同 AI Provider 之间灵活切换,或者想要一个轻量快速的终端编程助手,OpenCode 值得尝试。它的 LSP 集成和 MCP 支持使其在代码理解和工具扩展方面表现出色。