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 数据库里
核心概念表¶
| 概念 | 说明 | 类比 |
|---|---|---|
| Provider | AI 模型的提供商(如 Anthropic、OpenAI) | 类似快递公司 |
| Model | 具体的 AI 模型(如 claude-sonnet-4-20250514、gpt-4o) | 具体的快递员 |
| Session | 一次完整的对话上下文 | 一个聊天窗口 |
| LSP Client | 语言服务器协议客户端,用于代码理解 | 编辑器的智能感知 |
| MCP | 模型上下文协议,用于工具扩展 | 插件系统 |
| TUI | 终端用户界面 | 终端里的图形化交互 |
| Tool | AI 可调用的工具(读写文件、执行命令等) | 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¶
启动后你会看到一个终端界面,包含: - 消息区域:显示与 AI 的对话 - 输入框:输入你的请求 - 状态栏:显示当前模型、会话信息
基本对话¶
在输入框中直接输入你的需求:
快捷键¶
| 快捷键 | 功能 |
|---|---|
Ctrl+L | 清屏 |
Ctrl+C | 中断当前操作 |
Ctrl+O | 打开文件选择 |
Ctrl+K | 打开命令面板 |
Ctrl+N | 新建会话 |
Ctrl+P | 列出可用操作 |
上下文引用¶
使用 @ 符号引用文件:
会话管理¶
进阶用法¶
多模型切换¶
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
自定义系统提示词¶
常见问题¶
Q1: OpenCode 和 Claude Code 有什么区别?¶
| 特性 | OpenCode | Claude Code |
|---|---|---|
| 语言 | Go | TypeScript/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 存储会话数据,默认位置:
可以通过配置更改存储位置。所有数据存储在本地,不会上传到任何服务器。
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 支持使其在代码理解和工具扩展方面表现出色。