opencode-ai/opencode
GitHub: opencode-ai/opencode
一款基于 Go 的终端 AI 编程助手，通过 TUI 界面集成多家 AI 供应商帮助开发者在命令行中完成编码、调试等工作。
Stars: 13226 | Forks: 1521
For a quick video overview, check out
OpenCode + Gemini 2.5 Pro: BYE Claude Code! I'm SWITCHING To the FASTEST AI Coder!
## 功能
- **交互式 TUI**：基于 [Bubble Tea](https://github.com/charmbracelet/bubbletea) 构建，提供流畅的终端体验
- **多 AI 供应商**：支持 OpenAI、Anthropic Claude、Google Gemini、AWS Bedrock、Groq、Azure OpenAI 和 OpenRouter
- **会话管理**：保存并管理多个对话会话
- **工具集成**：AI 可以执行命令、搜索文件和修改代码
- **类 Vim 编辑器**：具备文本输入功能的集成编辑器
- **持久化存储**：使用 SQLite 数据库存储对话和会话
- **LSP 集成**：支持 Language Server Protocol 以实现代码智能
- **文件更改跟踪**：跟踪并可视化会话期间的文件更改
- **外部编辑器支持**：打开您首选的编辑器来撰写消息
- **自定义命令的命名参数**：使用多个命名占位符创建强大的自定义命令
## 安装说明
### 使用安装脚本
```
# 安装最新版本
curl -fsSL https://raw.githubusercontent.com/opencode-ai/opencode/refs/heads/main/install | bash
# 安装特定版本
curl -fsSL https://raw.githubusercontent.com/opencode-ai/opencode/refs/heads/main/install | VERSION=0.1.0 bash
```
### 使用 Homebrew (macOS 和 Linux)
```
brew install opencode-ai/tap/opencode
```
### 使用 AUR (Arch Linux)
```
# 使用 yay
yay -S opencode-ai-bin
# 使用 paru
paru -S opencode-ai-bin
```
### 使用 Go
```
go install github.com/opencode-ai/opencode@latest
```
## 配置
OpenCode 会在以下位置查找配置文件：
- `$HOME/.opencode.json`
- `$XDG_CONFIG_HOME/opencode/.opencode.json`
- `./.opencode.json`（本地目录）
### 自动压缩功能
OpenCode 包含一项自动压缩功能，当对话接近模型的上下文窗口限制时，它会自动总结您的对话。启用后（默认设置），此功能将：
- 监控对话期间的 token 使用情况
- 当使用量达到模型上下文窗口的 95% 时自动触发总结
- 使用总结创建一个新会话，让您可以在不丢失上下文的情况下继续工作
- 帮助防止长对话中可能出现的“上下文超限”错误
您可以在配置文件中启用或禁用此功能：
```
{
"autoCompact": true // default is true
}
```
### 环境变量
您可以使用环境变量来配置 OpenCode：
| 环境变量 | 用途 |
| -------------------------- | -------------------------------------------------------------------------------- |
| `ANTHROPIC_API_KEY` | 用于 Claude 模型 |
| `OPENAI_API_KEY` | 用于 OpenAI 模型 |
| `GEMINI_API_KEY` | 用于 Google Gemini 模型 |
| `GITHUB_TOKEN` | 用于 Github Copilot 模型（参见 [使用 Github Copilot](#using-github-copilot)） |
| `VERTEXAI_PROJECT` | 用于 Google Cloud VertexAI (Gemini) |
| `VERTEXAI_LOCATION` | 用于 Google Cloud VertexAI (Gemini) |
| `GROQ_API_KEY` | 用于 Groq 模型 |
| `AWS_ACCESS_KEY_ID` | 用于 AWS Bedrock (Claude) |
| `AWS_SECRET_ACCESS_KEY` | 用于 AWS Bedrock (Claude) |
| `AWS_REGION` | 用于 AWS Bedrock (Claude) |
| `AZURE_OPENAI_ENDPOINT` | 用于 Azure OpenAI 模型 |
| `AZURE_OPENAI_API_KEY` | 用于 Azure OpenAI 模型（使用 Entra ID 时可选） |
| `AZURE_OPENAI_API_VERSION` | 用于 Azure OpenAI 模型 |
| `LOCAL_ENDPOINT` | 用于自托管模型 |
| `SHELL` | 默认使用的 shell（如果未在配置中指定） |
### Shell 配置
OpenCode 允许您配置 bash 工具使用的 shell。默认情况下，它使用 `SHELL` 环境变量中指定的 shell，如果未设置，则回退到 `/bin/bash`。
您可以在配置文件中覆盖此设置：
```
{
"shell": {
"path": "/bin/zsh",
"args": ["-l"]
}
}
```
如果您想使用与系统默认 shell 不同的 shell，或者需要向 shell 传递特定参数，这会非常有用。
### 配置文件结构
```
{
"data": {
"directory": ".opencode"
},
"providers": {
"openai": {
"apiKey": "your-api-key",
"disabled": false
},
"anthropic": {
"apiKey": "your-api-key",
"disabled": false
},
"copilot": {
"disabled": false
},
"groq": {
"apiKey": "your-api-key",
"disabled": false
},
"openrouter": {
"apiKey": "your-api-key",
"disabled": false
}
},
"agents": {
"coder": {
"model": "claude-3.7-sonnet",
"maxTokens": 5000
},
"task": {
"model": "claude-3.7-sonnet",
"maxTokens": 5000
},
"title": {
"model": "claude-3.7-sonnet",
"maxTokens": 80
}
},
"shell": {
"path": "/bin/bash",
"args": ["-l"]
},
"mcpServers": {
"example": {
"type": "stdio",
"command": "path/to/mcp-server",
"env": [],
"args": []
}
},
"lsp": {
"go": {
"disabled": false,
"command": "gopls"
}
},
"debug": false,
"debugLSP": false,
"autoCompact": true
}
```
## 支持的 AI 模型
OpenCode 支持来自不同供应商的各种 AI 模型：
### OpenAI
- GPT-4.1 系列 (gpt-4.1, gpt-4.1-mini, gpt-4.1-nano)
- GPT-4.5 Preview
- GPT-4o 系列 (gpt-4o, gpt-4o-mini)
- O1 系列 (o1, o1-pro, o1-mini)
- O3 系列 (o3, o3-mini)
- O4 Mini
### Anthropic
- Claude 4 Sonnet
- Claude 4 Opus
- Claude 3.5 Sonnet
- Claude 3.5 Haiku
- Claude 3.7 Sonnet
- Claude 3 Haiku
- Claude 3 Opus
### GitHub Copilot
- GPT-3.5 Turbo
- GPT-4
- GPT-4o
- GPT-4o Mini
- GPT-4.1
- Claude 3.5 Sonnet
- Claude 3.7 Sonnet
- Claude 3.7 Sonnet Thinking
- Claude Sonnet 4
- O1
- O3 Mini
- O4 Mini
- Gemini 2.0 Flash
- Gemini 2.5 Pro
### Google
- Gemini 2.5
- Gemini 2.5 Flash
- Gemini 2.0 Flash
- Gemini 2.0 Flash Lite
### AWS Bedrock
- Claude 3.7 Sonnet
### Groq
- Llama 4 Maverick (17b-128e-instruct)
- Llama 4 Scout (17b-16e-instruct)
- QWEN QWQ-32b
- Deepseek R1 distill Llama 70b
- Llama 3.3 70b Versatile
### Azure OpenAI
- GPT-4.1 系列 (gpt-4.1, gpt-4.1-mini, gpt-4.1-nano)
- GPT-4.5 Preview
- GPT-4o 系列 (gpt-4o, gpt-4o-mini)
- O1 系列 (o1, o1-mini)
- O3 系列 (o3, o3-mini)
- O4 Mini
### Google Cloud VertexAI
- Gemini 2.5
- Gemini 2.5 Flash
## 用法
```
# 启动 OpenCode
opencode
# 以 debug 日志记录启动
opencode -d
# 以特定工作目录启动
opencode -c /path/to/project
```
## 非交互式 Prompt 模式
您可以通过将 prompt 直接作为命令行参数传递，以非交互式模式运行 OpenCode。这适用于脚本编写、自动化，或者当您想在不启动完整 TUI 的情况下快速获得答案时。
```
# 运行单个 prompt 并将 AI 的响应打印到终端
opencode -p "Explain the use of context in Go"
# 以 JSON 格式获取响应
opencode -p "Explain the use of context in Go" -f json
# 运行时不显示 spinner（适用于 scripts）
opencode -p "Explain the use of context in Go" -q
```
在此模式下，OpenCode 将处理您的 prompt，将结果打印到标准输出，然后退出。该会话的所有权限都会被自动批准。
默认情况下，在模型处理您的查询时会显示加载动画。您可以使用 `-q` 或 `--quiet` 标志禁用此动画，这在通过脚本或自动化工作流运行 OpenCode 时特别有用。
### 输出格式
OpenCode 在非交互式模式下支持以下输出格式：
| 格式 | 描述 |
| ------ | ------------------------------ |
| `text` | 纯文本输出（默认） |
| `json` | 封装在 JSON 对象中的输出 |
输出格式在代码库中作为强类型的 `OutputFormat` 实现，确保在处理输出时的类型安全和验证。
## 命令行标志
| 标志 | 简写 | 描述 |
| ----------------- | ---- | -------------------------------------------- |
| `--help` | `-h` | 显示帮助信息 |
| `--debug` | `-d` | 启用 debug 模式 |
| `--cwd` | `-c` | 设置当前工作目录 |
| `--prompt` | `-p` | 在非交互式模式下运行单个 prompt |
| `--output-format` | `-f` | 非交互式模式的输出格式 |
| `--quiet` | `-q` | 在非交互式模式下隐藏加载动画 |
## 键盘快捷键
### 全局快捷键
| 快捷键 | 操作 |
| -------- | ----------------------------------------- |
| `Ctrl+C` | 退出应用程序 |
| `Ctrl+?` | 切换帮助对话框 |
| `?` | 切换帮助对话框（非编辑模式下） |
| `Ctrl+L` | 查看日志 |
| `Ctrl+A` | 切换会话 |
| `Ctrl+K` | 命令对话框 |
| `Ctrl+O` | 切换模型选择对话框 |
| `Esc` | 关闭当前覆盖层/对话框或返回上一个模式 |
### 聊天页面快捷键
| 快捷键 | 操作 |
| -------- | ----------------------------- |
| `Ctrl+N` | 创建新会话 |
| `Ctrl+X` | 取消当前操作/生成 |
| `i` | 聚焦编辑器（非写入模式下） |
| `Esc` | 退出写入模式并聚焦消息 |
### 编辑器快捷键
| 快捷键 | 操作 |
| -------------------- | ----------------------------- |
| `Ctrl+S` | 发送消息（编辑器聚焦时） |
| `Enter` 或 `Ctrl+S` | 发送消息（编辑器未聚焦时） |
| `Ctrl+E` | 打开外部编辑器 |
| `Esc` | 取消聚焦编辑器并聚焦消息 |
### 会话对话框快捷键
| 快捷键 | 操作 |
| ---------- | ------------ |
| `↑` 或 `k` | 上一个会话 |
| `↓` 或 `j` | 下一个会话 |
| `Enter` | 选择会话 |
| `Esc` | 关闭对话框 |
### 模型对话框快捷键
| 快捷键 | 操作 |
| ---------- | ------------- |
| `↑` 或 `k` | 向上移动 |
| `↓` 或 `j` | 向下移动 |
| `←` 或 `h` | 上一个供应商 |
| `→` 或 `l` | 下一个供应商 |
| `Esc` | 关闭对话框 |
### 权限对话框快捷键
| 快捷键 | 操作 |
| ----------------------- | -------------------- |
| `←` 或 `left` | 向左切换选项 |
| `→` 或 `right` 或 `tab` | 向右切换选项 |
| `Enter` 或 `space` | 确认选择 |
| `a` | 允许权限 |
| `A` | 本次会话允许权限 |
| `d` | 拒绝权限 |
### 日志页面快捷键
| 快捷键 | 操作 |
| -------------------- | -------------- |
| `Backspace` 或 `q` | 返回聊天页面 |
## AI 助手工具
OpenCode 的 AI 助手可以访问各种工具来帮助处理编码任务：
### 文件和代码工具
| 工具 | 描述 | 参数 |
| ------------- | --------------------- | ---------------------------------------------------------------------------------------- |
| `glob` | 按模式查找文件 | `pattern`（必填），`path`（可选） |
| `grep` | 搜索文件内容 | `pattern`（必填），`path`（可选），`include`（可选），`literal_text`（可选） |
| `ls` | 列出目录内容 | `path`（可选），`ignore`（可选的模式数组） |
| `view` | 查看文件内容 | `file_path`（必填），`offset`（可选），`limit`（可选） |
| `write` | 写入文件 | `file_path`（必填），`content`（必填） |
| `edit` | 编辑文件 | 用于文件编辑的各种参数 |
| `patch` | 对文件应用补丁 | `file_path`（必填），`diff`（必填） |
| `diagnostics` | 获取诊断信息 | `file_path`（可选） |
### 其他工具
| 工具 | 描述 | 参数 |
| ------------- | ------------------------------ | ----------------------------------------------------------------------------------------- |
| `bash` | 执行 shell 命令 | `command`（必填），`timeout`（可选） |
| `fetch` | 从 URL 获取数据 | `url`（必填），`format`（必填），`timeout`（可选） |
| `sourcegraph` | 跨公共仓库搜索代码 | `query`（必填），`count`（可选），`context_window`（可选），`timeout`（可选） |
| `agent` | 使用 AI agent 运行子任务 | `prompt`（必填） |
## 架构
OpenCode 采用模块化架构构建：
- **cmd**：使用 Cobra 的命令行界面
- **internal/app**：核心应用服务
- **internal/config**：配置管理
- **internal/db**：数据库操作和迁移
- **internal/llm**：LLM 供应商和工具集成
- **internal/tui**：终端 UI 组件和布局
- **internal/logging**：日志基础设施
- **internal/message**：消息处理
- **internal/session**：会话管理
- **internal/lsp**：Language Server Protocol 集成
## 自定义命令
OpenCode 支持用户创建自定义命令，以便向 AI 助手快速发送预定义的 prompt。
### 创建自定义命令
自定义命令是作为 Markdown 文件存储在以下三个位置之一的预定义 prompt：
1. **用户命令**（以 `user:` 为前缀）：
$XDG_CONFIG_HOME/opencode/commands/
（在 Linux/macOS 上通常为 `~/.config/opencode/commands/`）
或
$HOME/.opencode/commands/
2. **项目命令**（以 `project:` 为前缀）：