OpenCode

概述

OpenCode 是一款开源的终端 AI 编程助手，基于 Go 语言构建，提供美观的 TUI（终端用户界面）。它支持多种 AI 模型提供商，让你可以在终端中直接与 AI 交互来完成编码任务。

开发者：kujtimiihoxha 及社区
类型：开源软件
许可：MIT License
语言：Go
GitHub：https://github.com/opencode-ai/opencode
Stars：12,164+

WARNING

OpenCode 项目已归档（2025-09），不再维护。项目已由原作者与 Charm 团队继任为 Crush（https://github.com/charmbracelet/crush），建议新用户直接使用 Crush。

系统要求

要求	说明
操作系统	macOS / Linux（Windows 未官方支持）
Go 版本	1.24.0+（仅从源码构建时需要）
终端	支持 TUI 的终端模拟器
SQLite	内置（用于持久化存储）
网络	需要互联网连接（调用 AI API）

安装

Windows 用户请使用 WSL2 安装

OpenCode 官方不支持 Windows，必须通过 WSL2（Ubuntu 24.04）安装使用：

powershell

# 1. 先安装 WSL2 + Ubuntu 24.04（PowerShell 管理员）
wsl --install -d Ubuntu-24.04

# 2. 进入 WSL2
wsl

# 3. 在 WSL2 中安装 OpenCode
curl -fsSL https://raw.githubusercontent.com/opencode-ai/opencode/refs/heads/main/install | bash

# 4. 访问 Windows 磁盘文件
cd /mnt/d/projects/my-app
opencode

通过 /mnt/磁盘号/ 路径访问 Windows 文件，如 /mnt/c/、/mnt/d/。

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

bash

# 最新版本
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）

bash

brew install opencode-ai/tap/opencode

方式三：AUR（Arch Linux）

bash

yay -S opencode-ai-bin
# 或
paru -S opencode-ai-bin

方式四：Go Install

bash

go install github.com/opencode-ai/opencode@latest

方式五：从源码构建

bash

git clone https://github.com/opencode-ai/opencode.git
cd opencode
go build -o opencode
./opencode

认证配置

OpenCode 支持多种 AI 提供商，通过环境变量或配置文件（.opencode.json）设置 API Key：

环境变量方式

环境变量	提供商
`ANTHROPIC_API_KEY`	Anthropic（Claude 系列模型）
`OPENAI_API_KEY`	OpenAI（GPT 系列模型）
`GEMINI_API_KEY`	Google Gemini
`GITHUB_TOKEN`	GitHub Copilot
`GROQ_API_KEY`	Groq
`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` + `AWS_REGION`	AWS Bedrock
`AZURE_OPENAI_ENDPOINT` + `AZURE_OPENAI_API_KEY`	Azure OpenAI
`VERTEXAI_PROJECT` + `VERTEXAI_LOCATION`	Google Cloud VertexAI
`LOCAL_ENDPOINT`	自托管 / OpenAI 兼容模型

配置文件方式

json

{
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-xxxxx",
      "disabled": false
    },
    "openai": {
      "apiKey": "sk-xxxxx",
      "disabled": false
    },
    "copilot": {
      "disabled": false
    }
  }
}

GitHub Copilot 认证

支持通过以下方式认证：

VS Code Copilot 扩展
gh CLI
Neovim Copilot 插件
显式设置 GITHUB_TOKEN 环境变量

基础使用

启动

bash

# 启动交互式 TUI
opencode

# 启用调试日志
opencode -d

# 指定工作目录
opencode -c /path/to/project

非交互模式

bash

# 提示模式（文本输出）
opencode -p "解释 Go 中 context 的用法"

# JSON 输出
opencode -p "解释 Go 中 context 的用法" -f json

# 安静模式（无 spinner，适合脚本）
opencode -p "解释 Go 中 context 的用法" -q

键盘快捷键

快捷键	说明
`Ctrl+K`	命令对话框（自定义命令）
`Ctrl+O`	模型选择
`Ctrl+A`	切换会话
`Ctrl+N`	新建会话
`Ctrl+S` / `Enter`	发送消息
`Ctrl+E`	打开外部编辑器
`?`	帮助对话框
`i`	聚焦编辑器

核心功能

交互式 TUI

基于 Charm 团队的 Bubble Tea 框架构建，提供美观的终端界面：

会话管理
模型快速切换
文件变更跟踪
内置 Vim 风格编辑器

多 AI 提供商支持

提供商	示例模型
OpenAI	GPT-4.1, GPT-4.5, GPT-4o, O1, O3, O4 Mini
Anthropic	Claude 4 Sonnet/Opus, Claude 3.5/3.7 Sonnet
Google	Gemini 2.5, Gemini 2.5 Flash, Gemini 2.0 Flash
AWS Bedrock	Claude 3.7 Sonnet
Azure OpenAI	GPT-4.1 系列, O1, O3, O4 Mini
Groq	Llama 4 Maverick/Scout, QWEN QWQ-32b
GitHub Copilot	GPT-4o, Claude 3.5/3.7 Sonnet, O1, O3 Mini
OpenRouter	通过 API Key 配置
自托管	通过 `LOCAL_ENDPOINT` 连接 OpenAI 兼容端点

工具集成

AI 可以执行以下操作：

运行 Bash 命令
搜索/ grep 文件
查看/编辑/写入/修补文件
获取 URL 内容
搜索 Sourcegraph
生成子代理任务（agent 工具）

LSP 集成

支持语言服务器协议，为 AI 提供代码诊断信息：

json

{
  "lsp": {
    "go": {
      "disabled": false,
      "command": "gopls"
    },
    "typescript": {
      "disabled": false,
      "command": "typescript-language-server",
      "args": ["--stdio"]
    }
  }
}

MCP 支持

支持 Model Context Protocol 扩展外部工具：

json

{
  "mcpServers": {
    "example": {
      "type": "stdio",
      "command": "path/to/mcp-server",
      "env": [],
      "args": []
    }
  }
}

会话管理

多会话支持，基于 SQLite 持久化
保存和管理多个对话会话
自动压缩：上下文窗口接近 95% 时自动总结

自定义命令

用户级命令：$XDG_CONFIG_HOME/opencode/commands/ 或 $HOME/.opencode/commands/

项目级命令：<PROJECT DIR>/.opencode/commands/

命令文件为 .md 格式，支持命名参数。

配置

配置文件位置（优先级从高到低）

./.opencode.json（项目本地）
$XDG_CONFIG_HOME/opencode/.opencode.json
$HOME/.opencode.json

完整配置示例

json

{
  "data": {
    "directory": ".opencode"
  },
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-xxxxx",
      "disabled": false
    },
    "openai": {
      "apiKey": "sk-xxxxx",
      "disabled": false
    },
    "copilot": {
      "disabled": false
    },
    "groq": {
      "apiKey": "gsk_xxxxx",
      "disabled": false
    },
    "openrouter": {
      "apiKey": "sk-or-xxxxx",
      "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
}

代理配置

OpenCode 有三种内置代理角色：

代理	用途	默认模型
`coder`	主要编码代理	claude-3.7-sonnet
`task`	子任务代理	claude-3.7-sonnet
`title`	生成会话标题	claude-3.7-sonnet

Shell 配置

json

{
  "shell": {
    "path": "/bin/bash",
    "args": ["-l"]
  }
}

常见工作流

代码探索

bash

opencode -p "解释这个项目的架构"

Bug 修复

bash

# 在 TUI 中
> 用户登录时出现 500 错误，帮我找到原因

代码生成

bash

opencode -p "为 user 模型编写 CRUD API 端点，使用 Go 和 Gin 框架"

代码审查

bash

# 在 TUI 中选中文件后
> 审查这个文件的安全性和性能问题

批量操作

bash

opencode -p "将所有 .js 文件中的 var 替换为 const 或 let"

迁移到 Crush

由于 OpenCode 已归档，建议迁移到其继任者 Crush：

GitHub：https://github.com/charmbracelet/crush
Stars：23,379+
维护者：Charm 团队 + 原作者
语言：Go
状态：活跃维护

Crush 保留了 OpenCode 的核心功能，并持续获得更新和改进。

故障排查

bash

# 启用调试模式启动
opencode -d

# 检查 LSP 问题
# 在配置中设置 "debugLSP": true

# 常见问题
# - API Key 无效：检查环境变量是否正确设置
# - 模型不可用：检查提供商是否禁用
# - TUI 显示异常：确保终端支持 TUI
# - 文件搜索失败：确保项目目录正确

OpenCode ​

概述 ​

系统要求 ​

安装 ​

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

方式二：Homebrew（macOS / Linux） ​

方式三：AUR（Arch Linux） ​

方式四：Go Install ​

方式五：从源码构建 ​

认证配置 ​

环境变量方式 ​

配置文件方式 ​

GitHub Copilot 认证 ​

基础使用 ​

启动 ​

非交互模式 ​

键盘快捷键 ​

核心功能 ​

交互式 TUI ​

多 AI 提供商支持 ​

工具集成 ​

LSP 集成 ​

MCP 支持 ​

会话管理 ​

自定义命令 ​

配置 ​

配置文件位置（优先级从高到低） ​

完整配置示例 ​

代理配置 ​

Shell 配置 ​

常见工作流 ​

代码探索 ​

Bug 修复 ​

代码生成 ​

代码审查 ​

批量操作 ​

迁移到 Crush ​

故障排查 ​

OpenCode

概述

系统要求

安装

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

方式二：Homebrew（macOS / Linux）

方式三：AUR（Arch Linux）

方式四：Go Install

方式五：从源码构建

认证配置

环境变量方式

配置文件方式

GitHub Copilot 认证

基础使用

启动

非交互模式

键盘快捷键

核心功能

交互式 TUI

多 AI 提供商支持

工具集成

LSP 集成

MCP 支持

会话管理

自定义命令

配置

配置文件位置（优先级从高到低）

完整配置示例

代理配置

Shell 配置

常见工作流

代码探索

Bug 修复

代码生成

代码审查

批量操作

迁移到 Crush

故障排查