OpenCode 概述
OpenCode 是一个完全开源的 AI 编程代理（Coding Agent），支持终端界面（TUI）、桌面应用和 IDE 扩展。它旨在帮助开发者通过自然语言与 AI 协作，完成代码编写、分析、重构及调试任务。
核心特性
- 100% 开源：MIT 许可证，代码透明可审计。
- 多模型支持：兼容 Claude、OpenAI、Google、本地模型等 75+ 提供商。
- 内置 LSP：开箱即用的语言服务器支持，提供智能诊断。
- TUI 优先：专为终端用户设计，体验流畅。
- MCP 协议：支持扩展外部工具和服务。
相比闭源的竞品，OpenCode 在开源性、Provider 选择自由度和扩展性上更具优势，且原生支持 LSP 集成。
安装指南
前置要求
确保你的终端模拟器支持现代特性，推荐 WezTerm、Alacritty、Ghostty 或 Kitty。此外，你需要至少一个 LLM Provider 的 API 密钥。
通用安装
适用于 macOS 和 Linux 的最简方式：
curl -fsSL https://opencode.ai/install | bash
平台特定安装
macOS 推荐使用 Homebrew：
brew install anomalyco/tap/opencode
# 或者
brew install opencode
Linux Debian/Ubuntu 用户可使用 npm 或安装脚本：
npm install -g opencode-ai
# 或使用脚本
curl -fsSL https://opencode.ai/install | bash
Arch Linux 用户：
paru -S opencode-bin
Windows 支持 Chocolatey、Scoop 或 npm：
choco install opencode
scoop install opencode
npm install -g opencode-ai
Docker
docker run -it --rm ghcr.io/anomalyco/opencode
桌面应用
目前处于 Beta 阶段，可从 GitHub Releases 下载对应平台的安装包（.dmg, .exe, .deb 等）。
快速开始
首次配置
进入项目目录后启动 OpenCode：
opencode
运行 /connect 命令连接你的 Provider。以 OpenCode Zen 为例，访问授权页面获取 API 密钥并粘贴即可。
初始化项目
执行 /init 命令，系统会生成 AGENTS.md 文件，帮助 AI 理解你的项目结构。建议将此文件提交到 Git 仓库以便团队协作。
基础交互
- 询问问题：直接输入文本，例如'介绍一下这个代码库'。
- 引用文件：使用
@符号，如@src/components/Button.tsx。 - 执行命令：使用
!前缀，如!npm test。
模式切换
OpenCode 提供两种主要模式，按 Tab 键切换：
- Build 模式：拥有完整权限，可修改文件，适合实际开发。
- Plan 模式：只读模式，仅分析不修改，适合代码审查或方案规划。
建议先用 Plan 模式确认方案，再切回 Build 模式执行。撤销操作依赖 Git 仓库，使用 /undo 和 /redo 命令。
配置文件详解
OpenCode 支持 JSON 和 JSONC 格式的配置。优先级顺序为：远程组织配置 > 全局用户配置 > 环境变量 > 项目专属配置。
典型配置示例如下：
{
"$schema": "https://opencode.ai/config.json",
"theme": "tokyonight",
"model": "anthropic/claude-sonnet-4-5",
"autoupdate": true,
"tui": {
"scroll_speed": 3
},
"permission": {
"edit": "allow",
"bash": "ask"
}
}
变量替换功能允许你通过环境变量或文件内容注入敏感信息，例如：
{"model":"{env:OPENCODE_MODEL}"}
Provider 配置
OpenCode 支持 75+ 个 LLM 提供商。常用配置包括：
- Anthropic/OpenAI：支持订阅认证或手动输入 API Key。
- 本地模型：配置 Ollama 或 LM Studio，需设置正确的
baseURL。 - 云厂商：Amazon Bedrock、Google Vertex AI 等。
禁用或启用特定 Provider 可在配置文件中设置 disabled_providers 或 enabled_providers。
TUI 终端界面
启动后，你可以通过快捷键高效操作：
- 发送消息：Enter 键。
- 换行：Shift+Enter。
- 引用文件：输入
@搜索。 - 内置命令：如
/models切换模型，/new新建会话，/share分享会话。
导航方面，PageUp/PageDown 翻页，Ctrl+g 跳转顶部。编辑器设置可通过 EDITOR 环境变量指定，VS Code 需加上 --wait 参数。
Agent 系统
Agent 分为主 Agent 和子 Agent。主 Agent 默认为 Build 和 Plan 模式，通过 Tab 切换。子 Agent 如 General 或 Explore 可通过 @ 提及调用。
自定义 Agent 支持 JSON 配置或 Markdown 文件定义。你可以限制其工具权限，例如禁止写入文件但允许读取，打造专用的代码审查专家。
自定义命令
通过创建 .opencode/commands/ 下的文件或直接在配置中定义快捷命令。模板语法支持 $ARGUMENTS 占位符和 Shell 命令输出插入，方便封装常用工作流。
MCP 服务器
Model Context Protocol (MCP) 允许 OpenCode 集成外部工具，如数据库、API 或第三方服务。
配置本地 MCP 服务器时，指定 command 即可；远程服务器则需提供 url。常用示例包括 Sentry 错误监控、Context7 文档搜索等。注意管理好 MCP 权限，避免不必要的上下文开销。
LSP 语言服务器
OpenCode 内置多种语言的 LSP 支持，包括 TypeScript、Python、Rust、Go 等。当打开文件时，它会自动启动对应的语言服务器并提供诊断反馈。
若需禁用自动下载或特定语言支持，可在配置中设置 lsp 选项或环境变量 OPENCODE_DISABLE_LSP_DOWNLOAD。
主题与个性化
终端需支持 Truecolor 才能正确显示主题。内置主题包括 Tokyo Night、Catppuccin、Gruvbox 等。自定义主题需遵循特定的 JSON Schema 定义颜色变量。
Rules 自定义指令
AGENTS.md 文件用于向 LLM 提供项目特定的编码规范和上下文。它支持引用外部文件，甚至兼容 Claude Code 的 CLAUDE.md 约定。合理维护此文件能显著提升 AI 输出的质量。
最佳实践
- 先规划后执行：利用 Plan 模式梳理思路，减少试错成本。
- 上下文管理：合理使用
@引用关键文件，避免无关信息干扰。 - 性能优化：为轻量任务配置
small_model，启用自动压缩上下文。 - 安全控制：对敏感命令（如
rm,git push）设置为ask权限。
常见问题
- 更换模型：使用
/models命令或在配置中指定。 - 本地模型：配置 Ollama 或 LM Studio 的兼容接口。
- 撤销失败：确保项目已初始化为 Git 仓库。
- 重置数据：删除
~/.config/opencode和~/.local/share/opencode目录。
更多资源请参考官方文档和 GitHub 仓库。
