2026 年 OpenCode 安装配置完全指南:从零到上手
如果 2026 年你的开发效率还没有翻倍,很可能是工具链还没升级。
开源、不绑定模型、75+ 种模型自由选择——这个运行在终端里的 AI 编程代理,或许会让你重新理解「AI 辅助写代码」这件事。本文从零开始,带你 10 分钟跑通 OpenCode。
认识 OpenCode:开源的 AI 编程代理
OpenCode 是一个完全开源的 AI 编程代理(AI Coding Agent),它驻留在你的终端中,可以用自然语言帮你完成代码编写、调试、重构等一系列软件工程任务。
一句话说明它的核心定位:
不绑定任何一个模型,不锁定任何一种 IDE,不收取任何许可费用——OpenCode 把 AI 编程的自主权交还给开发者。
它的工作流大致是这样的:
你:帮我写一个带 JWT 认证的用户登录 API
OpenCode:
✅ 分析项目结构
✅ 创建 auth/jwt.go
✅ 更新 routes/user.go
✅ 添加中间件鉴权
✅ 运行测试 → 全部通过
三种使用形态,覆盖不同场景
OpenCode 提供三种使用形态,几乎能适配所有开发环境:
| 形态 | 启动方式 | 适合场景 |
|---|---|---|
| 终端界面(TUI) | 在命令行中输入 opencode |
服务端开发、SSH 远程、服务器运维 |
| Web 网页版 | opencode web 启动浏览器界面 |
需要图形界面、团队协作演示 |
| IDE 扩展 | 在 VS Code / Cursor 集成终端中运行 | 日常开发,边写边问 |
OpenCode
终端 TUI
Web 网页版
IDE 扩展
SSH 远程开发
服务器运维
可视化操作
团队协作演示
VS Code
Cursor
Windsurf
OpenCode 与传统 AI 编程工具的差异
| 能力 | 传统 AI 编程工具 | OpenCode |
|---|---|---|
| 代码补全 | ✅ 行级补全 | ✅ 全项目级补全 |
| 理解项目 | ❌ 只看当前文件 | ✅ 理解整个代码库 |
| 执行命令 | ❌ 只能给出建议 | ✅ 直接运行 bash |
| 编辑文件 | ❌ 需要复制粘贴 | ✅ 自动创建/修改文件 |
| 调试修复 | ❌ 只给建议 | ✅ 定位问题并自动修复 |
| 扩展工具 | ❌ 功能固化 | ✅ MCP + 插件无限扩展 |
安装前的环境要求
开始安装之前,先确认你的环境是否满足以下条件:
| 项目 | 要求 |
|---|---|
| 操作系统 | macOS、Linux、Windows(推荐使用 WSL) |
| 终端 | 任何现代终端(iTerm2、Terminal、Windows Terminal 等) |
| 网络 | 需要访问模型 API(本地模型除外) |
| Go 环境 | 可选,仅在从源码编译时需要 |
安装 OpenCode 的多种方式
macOS / Linux(推荐)
官方安装脚本,一行命令即可完成:
curl -fsSL https://opencode.ai/install | bash
Homebrew(macOS)
# 官方 Tap(推荐,更新及时)
brew install anomalyco/tap/opencode
# 注意:Homebrew 官方源的 opencode formula 更新频率较低,建议用上面的命令
npm 安装
npm install -g opencode-ai
Arch Linux
# 使用 pacman
pacman -S opencode
# 或通过 AUR Helper(如 paru)
paru -S opencode
Windows
# Chocolatey
choco install opencode
# Scoop
scoop install opencode
# 也可以使用 npm
npm install -g opencode-ai
Mise(版本管理工具)
mise use -g opencode
Docker
docker run -it --rm ghcr.io/anomalyco/opencode
从源码编译
git clone https://github.com/opencode-ai/opencode.git
cd opencode
go build -o opencode .
验证安装
安装完毕后,用以下命令检查是否成功:
opencode --version
# 输出示例:opencode version 0.9.x
看到版本号就说明安装成功了。
首次启动与初始化
启动 OpenCode
进入你的项目目录,直接运行:
cd your-project
opencode
第一次启动时,OpenCode 会引导你完成初始设置:
- 选择模型提供商 —— 新手建议选择 OpenCode Zen(内置免费模型)
- 配置 API Key —— 使用云端模型时需要输入对应的密钥
- 确认配置 —— 完成确认后即可使用
启动 Web 版
如果你更习惯图形界面:
# 默认端口启动
opencode web
# 自定义端口
opencode web --port 3000
在 IDE 中使用
在 VS Code / Cursor / Windsurf 的集成终端中运行 opencode,还可以用快捷键快速操作:
- Mac:
Cmd+Esc快速启动 - Windows / Linux:
Ctrl+Esc快速启动
配置文件详解
OpenCode 使用 opencode.json 作为配置文件,支持 JSON 和 JSONC(带注释的 JSON)格式。
配置文件位置与优先级
配置会按以下顺序加载(优先级从高到低):
- Remote 远程配置
- Global ~/.config/opencode/opencode.json
- Custom OPENCODE_CONFIG 环境变量指定
- Project 项目根目录 opencode.json
- .opencode 目录 项目根目录 .opencode/
- Inline OPENCODE_CONFIG_CONTENT 环境变量
💡 实用建议:绝大多数情况下,你只需在项目根目录建一个
opencode.json就够了。
最简配置示例
在项目根目录创建 opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"model": {
"build": "anthropic/claude-sonnet-4-5",
"plan": "anthropic/claude-sonnet-4-5"
},
"autoupdate": true,
"server": {
"port": 4096
}
}
用环境变量保护 API Key
永远不要把 API Key 硬编码在配置文件中。 推荐使用环境变量引用:
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"anthropic": {
"options": {
"apiKey": "{env:ANTHROPIC_API_KEY}"
}
},
"openai": {
"options": {
"apiKey": "{env:OPENAI_API_KEY}"
}
}
}
}
然后再在终端中设置环境变量:
# 临时设置(当前会话有效)
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
# 永久设置(写入 shell 配置文件)
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxx"' >> ~/.zshrc
source ~/.zshrc
从文件读取密钥
{
"provider": {
"anthropic": {
"options": {
"apiKey": "{file:~/.config/opencode/anthropic-key}"
}
}
}
}
完整配置示例
{
"$schema": "https://opencode.ai/config.json",
// 模型配置
"model": {
"build": "anthropic/claude-sonnet-4-5",
"plan": "anthropic/claude-sonnet-4-5"
},
// 提供商配置
"provider": {
"anthropic": {
"options": {
"apiKey": "{env:ANTHROPIC_API_KEY}"
}
},
"openrouter": {
"options": {
"apiKey": "{env:OPENROUTER_API_KEY}"
}
}
},
// 自动更新
"autoupdate": true,
// Web 服务端口
"server": {
"port": 4096
},
// 上下文压缩
"compaction": {
"auto": true
},
// 权限控制
"permission": {
"edit": "ask",
"bash": "ask"
}
}
模型与提供商快速入门
本节只介绍快速上手的必备知识。模型的详细对比、选型建议和高级配置,请阅读本系列第 2 篇《模型与提供商完全指南》。
OpenCode Zen(新手首选)
OpenCode Zen 是官方精选的模型网关,内置了多个免费模型,无需配置 API Key 就能使用。首次启动时选择 Zen 是最简单的入门方式。
使用 /connect 添加提供商
在 OpenCode 对话中输入 /connect,按提示操作即可添加新的模型提供商凭据:
你:/connect
OpenCode:请选择要添加的提供商:
1. Anthropic
2. OpenAI
3. OpenRouter
4. ...
你:1
OpenCode:请输入 Anthropic API Key:
你:sk-ant-xxxxx
✅ Anthropic 提供商已添加
查看和切换模型
# 查看可用模型列表
/models
# 在 TUI 界面中通过快捷键切换当前使用的模型
基础操作指南
对话交互
OpenCode 的核心交互方式就是自然语言对话:
你:这个项目是做什么的?帮我分析一下项目结构
OpenCode:
📖 分析项目结构...
📦 这是一个 Go 语言 Web 服务,使用 Gin 框架
📁 主要模块:
- /handlers: HTTP 请求处理
- /models: 数据模型
- /middleware: 中间件
- /config: 配置管理
你:帮我在 handlers/user.go 里添加一个获取用户列表的接口
OpenCode:
✏️ 正在编辑 handlers/user.go...
✅ 添加 GetUsers handler
✅ 添加路由注册
✅ 添加分页参数验证
📝 修改完成,共改动 3 个文件
用 @ 引用文件
在对话中直接引用项目文件,让 OpenCode 聚焦处理:
你:看一下 @src/main.go 这个文件的性能问题
OpenCode:正在读取 src/main.go...
用 ! 注入 Shell 命令输出
在消息开头使用 ! 前缀,可以将 Shell 命令的输出作为上下文发送给 AI:
你:!go test ./... 帮我看看测试结果,分析失败的用例
撤销与重做
如果改动不符合预期:
你:/undo
OpenCode:
⏪ 已撤销上一次改动
重做操作:
你:/redo
OpenCode:
⏩ 已重做上一次操作
Tab 切换模式
OpenCode 提供两种核心工作模式,通过 Tab 键切换:
| 模式 | 说明 | 适用场景 |
|---|---|---|
| Build 模式 | 默认模式,拥有全部工具,直接执行代码修改 | 编码、修改文件、执行命令 |
| Plan 模式 | 只分析不执行,只读方式浏览代码 | 方案设计、代码审查、风险评估 |
💡 建议:遇到复杂任务时,先切到 Plan 模式看看方案,确认后再切回 Build 模式执行。
常用斜杠命令
以下是 OpenCode 内置的斜杠命令速查表:
| 命令 | 功能 |
|---|---|
/init |
初始化项目配置(创建 AGENTS.md) |
/connect |
添加模型提供商凭据 |
/models |
查看/切换可用模型 |
/undo |
撤销上一次操作 |
/redo |
重做上一次操作 |
/compact |
手动压缩对话上下文 |
/details |
查看当前会话详情 |
/editor |
用外部编辑器编辑消息 |
/export |
导出对话记录 |
/new |
开始新会话 |
/share |
分享对话 |
/unshare |
取消分享 |
/sessions |
查看历史会话 |
/themes |
切换主题 |
/thinking |
切换思维模式 |
/help |
查看帮助 |
/exit |
退出 OpenCode |
快捷键参考
OpenCode TUI 使用 Ctrl+x 作为 leader key 前缀:
| 快捷键 | 功能 |
|---|---|
Ctrl+x c |
压缩上下文(compact) |
Ctrl+x n |
新建会话 |
Ctrl+x h |
查看帮助 |
Ctrl+x q |
退出 |
Tab |
切换 Build / Plan 模式 |
Enter |
发送消息 |
Esc |
取消当前操作 |
重要概念预告
以下概念在本文中只做简要介绍,后续文章会深入讲解。
代理系统(Agents)
OpenCode 内置了一套智能代理系统,不同的代理负责不同的任务:
- Build 代理:主代理,拥有全部工具,负责代码编写和修改
- Plan 代理:只读代理,负责分析和规划,不修改任何文件
- 子代理:包括 General(通用任务)和 Explore(代码探索)
- 系统代理:包括 Compaction(上下文压缩)、Title(会话标题)、Summary(会话摘要)
详细内容请阅读本系列第 3 篇《代理、工具与 MCP 协议》。
MCP 协议
MCP(Model Context Protocol) 是 OpenCode 连接外部工具和服务的标准协议。通过 MCP,你可以让 OpenCode 调用数据库、访问 API、操作文件系统等外部能力。
详细内容请阅读本系列第 3 篇《代理、工具与 MCP 协议》。
插件系统
OpenCode 提供了 30+ 事件钩子,支持使用 JavaScript/TypeScript 编写插件,自由扩展功能。
详细内容请阅读本系列第 4 篇《自定义命令与插件开发》。
AGENTS.md
AGENTS.md 是项目级的 AI 理解文件,相当于给 OpenCode 写的「项目说明书」。使用 /init 命令可以自动生成:
# 在 OpenCode 对话中执行
/init
OpenCode 会自动分析项目结构、技术栈、代码规范,生成一份 AGENTS.md 文件。之后每次对话,OpenCode 都会参考这个文件来更好地理解你的项目。
权限系统
OpenCode 的权限系统控制 AI 对文件和命令的操作权限:
{
"permission": {
"edit": "ask",
"bash": "ask"
}
}
allow:自动允许,不询问ask:每次操作前询问确认(推荐)deny:完全禁止
详细内容请阅读本系列第 3 篇《代理、工具与 MCP 协议》。
常见问题(FAQ)
Q1: OpenCode 真的免费吗?
是的。 OpenCode 本身完全免费开源。不过,使用云端模型(如 OpenAI、Anthropic)时需要各自的 API Key,会产生 API 调用费用。如果使用 OpenCode Zen 的免费模型 或 本地模型(Ollama),则完全零成本。
Q2: 安装后启动报错怎么办?
常见原因和解决方法:
| 问题 | 解决方法 |
|---|---|
command not found: opencode |
检查 PATH 环境变量是否包含安装路径 |
| 权限不足 | 使用 chmod +x 赋予执行权限,或检查安装目录权限 |
| 网络超时 | 检查代理设置,确保能访问模型 API |
| 版本冲突 | 卸载旧版本后重新安装 |
Q3: 不熟悉命令行能用吗?
可以试试 Web 模式(opencode web)或 IDE 扩展,它们提供了更友好的图形界面。基础使用不需要记命令,自然语言对话即可。
Q4: 支持哪些编程语言?
所有语言。 OpenCode 不限制编程语言,它通过内置工具(bash、edit、read 等)支持任何语言的开发。
Q5: 数据安全吗?
OpenCode 不会存储你的代码或上下文数据。所有数据只在你的本地机器和模型提供商之间传输。使用本地模型(Ollama)时,数据完全不出你的电脑。
Q6: OpenCode 和 Claude Code 有什么区别?
最大的区别:Claude Code 只能用 Claude 模型,OpenCode 可以选择 75+ 种模型。 Claude Code 是 Anthropic 的闭源产品,OpenCode 是开源社区项目。详细对比请阅读本系列第 5 篇《OpenCode vs Claude Code 深度对比》。
实用技巧
1. 首次进入新项目,先用 /init
# 自动分析项目结构并生成 AGENTS.md
/init
OpenCode 会识别你的技术栈,生成合适的配置文件,后续对话更精准。
2. 善用 Plan 模式
面对不熟悉的代码或复杂需求,先切到 Plan 模式让 AI 分析一遍,看看它的理解是否正确,再切回 Build 模式执行。这样可以避免大量无效修改。
3. 使用 /compact 管理长对话
对话过长时,OpenCode 会自动压缩上下文(如果开启了 compaction.auto)。你也可以手动执行 /compact 来释放上下文空间。
4. 用 /editor 编辑长消息
当你需要输入很长的需求描述时,使用 /editor 可以用你熟悉的外部编辑器(如 Vim、VS Code)来编写,写完后保存关闭即可发送。
5. /export 导出对话记录
完成的对话可以用 /export 导出保存,方便复盘或分享给同事。
总结
OpenCode = 开源 + 多模型 + Agent 能力 + MCP 扩展 + 插件生态
通过本文,你已经掌握了:
- ✅ OpenCode 是什么,它能做什么
- ✅ 如何在 macOS / Linux / Windows 上安装 OpenCode
- ✅ 如何配置
opencode.json,包括 API Key 的安全管理 - ✅ 如何启动和使用 OpenCode 的三种形态
- ✅ 基础操作:对话、引用文件、注入命令、撤销重做
- ✅ 常用斜杠命令和快捷键
- ✅ 代理、MCP、插件、AGENTS.md 等核心概念的入门理解
接下来,建议按顺序阅读本系列后续文章:
| 篇目 | 主题 | 你将学到 |
|---|---|---|
| 第 2 篇 | 模型与提供商完全指南 | 75+ 模型怎么选、如何配置、成本优化 |
| 第 3 篇 | 代理、工具与 MCP 协议 | 代理系统、14 个内置工具、MCP 扩展 |
| 第 4 篇 | 自定义命令与插件开发 | 插件编写、事件钩子、自动化工作流 |
| 第 5 篇 | OpenCode vs Claude Code 深度对比 | 功能、性能、成本全方位对比 |
延伸阅读
- OpenCode 官方文档[1]
- OpenCode GitHub 仓库[2]
- OpenCode Zen 模型列表[3]
- OpenCode 配置参考[4]
[1] OpenCode 官方文档: https://opencode.ai/docs/zh-cn
[2] OpenCode GitHub 仓库: https://github.com/opencode-ai/opencode
[3] OpenCode Zen 模型列表: https://opencode.ai/docs/zh-cn/zen
[4] OpenCode 配置参考: https://opencode.ai/docs/zh-cn/config