版本: 2026年3月最新版
适用版本: OpenCode Beta
最后更新: 2026年3月27日
目录
- OpenCode 简介
- 安装指南
- 快速入门
- 核心功能详解
- 实战技巧
- 配置与自定义
- Oh My OpenCode 扩展
- 常见问题与故障排除
- 参考资源
一、OpenCode 简介
1.1 什么是 OpenCode？
OpenCode 是一个100%开源的 AI 编程代理（AI Coding Agent），由 OpenCode AI 团队开发。它将人工智能助手直接集成到终端环境中，让开发者能够通过自然语言与 AI 交互完成代码相关任务。
核心定位: Claude Code 等商业工具的最佳开源替代品
1.2 主要特点
|
特性 |
说明 |
|
完全开源 |
代码完全开放，社区驱动发展 |
|
多平台支持 |
终端、桌面应用、IDE 扩展三端覆盖 |
|
多模型支持 |
支持 75+ 模型提供商（Claude、GPT、Gemini、本地模型等） |
|
内置免费模型 |
提供 Zen 服务，内置经过测试验证的免费模型 |
|
隐私优先 |
不存储用户代码或上下文数据 |
|
LSP 支持 |
自动加载 Language Server Protocol，提升代码理解能力 |
|
多会话并行 |
可在同一项目中启动多个代理会话 |
1.3 适用场景
- ✅ 代码理解与重构
- ✅ 新功能开发
- ✅ Bug 修复与调试
- ✅ 代码审查与优化
- ✅ 自动化测试
- ✅ 项目文档生成
二、安装指南
2.1 系统要求
- macOS: Apple Silicon 或 Intel 芯片
- Windows: Windows 10/11 (x64)
- Linux: Debian/Ubuntu (.deb) 或 Red Hat/Fedora (.rpm)
2.2 终端版本安装
方式一：一键安装（推荐）
curl -fsSL https://opencode.ai/install | bash
方式二：包管理器安装
macOS (Homebrew):
brew install anomalyco/tap/opencode
Windows (Chocolatey):
choco install opencode
Windows (npm):
npm install -g opencode-ai
Linux (Arch):
paru -S opencode
通用 (npm):
npm i -g opencode-ai
通用 (bun):
bun add -g opencode-ai
2.3 桌面版安装
桌面版目前为 Beta 版本，支持 macOS、Windows 和 Linux。
macOS (Homebrew):
brew install –cask opencode-desktop
手动下载: 访问 opencode.ai/download 下载对应平台的安装包。
2.4 IDE 扩展安装
OpenCode 支持以下编辑器的扩展：
- VS Code
- Cursor
- Zed
- Windsurf
- VSCodium
安装方式：在对应编辑器的扩展商店搜索 “OpenCode” 安装。
三、快速入门
3.1 首次启动
在终端中输入以下命令启动 OpenCode：
opencode
首次启动会引导你进行初始配置：
- 选择模型提供商（可选择免费模型或配置 API Key）
- 完成认证（如需使用商业模型）
3.2 基本命令
|
命令 |
说明 |
|
/models |
查看可用模型列表 |
|
/connect |
配置 API 密钥 |
|
/init |
初始化项目（生成 AGENTS.md） |
|
/exit 或 Ctrl+D |
退出 OpenCode |
3.3 第一个项目
# 进入项目目录
cd /path/to/your/project
# 启动 OpenCode
opencode
# 初始化项目
/init
# 开始对话
“请帮我分析这个项目的结构”
3.4 文件引用
使用 @ 符号引用项目中的文件：
“请解释 @src/auth/index.ts 中的认证流程”
“优化 @components/Button.tsx 的代码”
四、核心功能详解
4.1 两种 Agent 模式
OpenCode 提供两种工作模式，适用于不同场景：
Build 模式（构建模式）
- 权限: 全权限，可直接编辑文件、执行命令
- 适用场景: 熟悉项目后的实际开发工作
- 特点: AI 会直接修改代码并执行必要命令
Plan 模式（规划模式）
- 权限: 只读，不会直接修改代码
- 适用场景:探索陌生代码库分析项目结构制定修改方案
- 特点: AI 只提供分析和提议，需确认后才执行
最佳实践: 在不熟悉的项目中，默认使用 plan 模式，确认理解后再切换到 build 模式。
4.2 内置工具
OpenCode 内置了多种开发工具：
|
工具 |
功能 |
|
Bash |
执行终端命令 |
|
File Read/Write |
文件读写操作 |
|
Grep Search |
代码搜索 |
|
LSP |
语言服务器协议支持，提供代码诊断 |
|
Git |
Git 操作支持 |
4.3 会话管理
|
命令 |
功能 |
|
/new |
新建会话 |
|
/sessions |
查看所有会话 |
|
/undo |
撤销上次修改（需 Git 仓库） |
|
/redo |
重做上次修改 |
|
/share |
分享当前会话链接 |
4.4 视图设置
|
命令 |
功能 |
|
/theme |
切换主题 |
|
/thinking |
显示/隐藏 AI 推理过程 |
五、实战技巧
5.1 在陌生代码库中使用 Plan 模式
场景: 刚接手一个不熟悉的新项目
做法:
“请解释 @src/auth/index.ts 里的认证流程。然后给我两个最小修改方案。先不要编辑。”
好处: 避免在不完全理解代码结构时仓促修改，降低引入 Bug 的风险。
5.2 使用 AGENTS.md 固化项目规则
作用: 将项目规则（构建命令、风格规范、禁止修改的范围）写入 AGENTS.md，避免每次对话重复约束。
操作:
- 运行 /init 生成 AGENTS.md
- 编辑文件，添加项目特定规则：
- # 项目规则
## 构建命令
– 开发: npm run dev
– 构建: npm run build
– 测试: npm run test
## 代码规范
– 使用 TypeScript
– 遵循 ESLint 规则
– 不要修改 /config 目录下的文件
- 提交到 Git 仓库
5.3 权限配置：先收紧，再逐步放开
安全提议: 初期将敏感操作设置为需要确认。
在 opencode.json 中配置：
{
“$schema”: “https://opencode.ai/config.json”,
“permission”: {
“edit”: “ask”,
“bash”: “ask”
}
}
选项说明:
- “allow”: 允许自动执行
- “ask”: 每次询问确认
- “deny”: 禁止执行
5.4 创建自定义命令
将常用工作流封装成快捷命令，提升效率。
步骤:
- 在项目根目录创建 .opencode/commands/ 目录
- 创建命令文件，例如 test.json:
- {
“name”: “test”,
“description”: “运行相关测试并给出修复提议”,
“prompt”: “请查找与当前修改相关的测试文件并运行，如果测试失败请提供修复提议。”
}
- 使用命令: /test
5.5 选择合适的界面
|
界面 |
适用场景 |
|
终端 |
追求最快编辑-测试循环，习惯命令行 |
|
桌面应用 |
需要更好的可视化、会话管理 |
|
IDE 扩展 |
不想离开现有编辑环境 |
六、配置与自定义
6.1 模型配置
使用内置免费模型（Zen）
OpenCode 提供 Zen 服务，内置经过专门测试和优化的 AI 模型：
# 启动后选择 Zen 模型即可使用
opencode
配置商业模型
OpenAI (GPT):
/connect openai
# 按提示输入 API Key
Anthropic (Claude):
/connect anthropic
# 按提示输入 API Key
其他提供商: 支持 75+ 模型提供商，通过 Models.dev 集成。
使用本地模型
配置本地 Ollama 服务：
# 在配置文件中添加本地模型端点
6.2 项目配置 (opencode.json)
在项目根目录创建 opencode.json：
{
“$schema”: “https://opencode.ai/config.json”,
“permission”: {
“edit”: “ask”,
“bash”: “ask”,
“file_read”: “allow”,
“file_write”: “ask”
},
“model”: {
“provider”: “openai”,
“model”: “gpt-4”
}
}
6.3 快捷键自定义
桌面版和 IDE 扩展支持快捷键自定义：
默认快捷键:
- macOS: Cmd + K
- Windows/Linux: Ctrl + K
可在”首选项”中调整快捷键以符合个人习惯。
七、Oh My OpenCode 扩展
7.1 什么是 Oh My OpenCode？
Oh My OpenCode 是建立在 OpenCode 之上的编排层，提供更强劲的多智能体协作能力。
功能特点:
- 多模型协作
- 并行任务处理
- 专家 Agent 分工
- 更复杂的自动化工作流
7.2 何时使用 Oh My OpenCode？
|
场景 |
推荐方案 |
|
新手入门 |
先单独使用 OpenCode 本体 |
|
日常开发任务 |
OpenCode 本体 |
|
复杂、并行任务 |
Oh My OpenCode |
|
需要多专家协作 |
Oh My OpenCode |
7.3 安装与使用
安装: 在 OpenCode 对话框中粘贴 Oh My OpenCode 的安装指南链接，按提示完成安装。
核心命令:
ultrawork 或 ulw
使用 ultrawork 命令可激活完整自动化模式，处理明确的中等规模任务。
八、常见问题与故障排除
8.1 安装问题
Q: 安装后无法找到 opencode 命令
A:
- macOS/Linux: 检查 $PATH 是否包含安装目录，或尝试重新加载 shell 配置：source ~/.bashrc 或 source ~/.zshrc
- Windows: 确保 npm 全局安装路径已添加到系统 PATH
Q: 权限问题（Mac/Linux）
A:
sudo chmod +x /usr/local/bin/opencode
8.2 模型问题
Q: 模型不可用或响应慢
A:
- 检查 API Key 是否正确配置
- 检查网络连接
- 切换到 OpenCode Zen 免费模型
- 切换轻量模型（如 Claude 3.7 Haiku）
- 减少上下文长度
Q: 如何切换模型？
A:
/models # 查看可用模型
# 然后选择要使用的模型
8.3 使用问题
Q: 生成代码后如何撤销？
A:
- 使用 /undo 命令（需要项目在 Git 仓库中）
- 或手动使用 Git 回滚：git checkout — <file>
Q: 如何分享会话？
A:
/share
会生成一个分享链接，可发送给他人查看。
8.4 性能优化
Q: 代码生成速度慢
A:
- 切换轻量模型
- 减少上下文窗口大小
- 关闭不必要的 LSP 功能
- 使用 Plan 模式先规划，再切换到 Build 模式执行
九、参考资源
9.1 官方资源
|
资源 |
链接 |
|
官网 |
https://opencode.ai/zh |
|
下载页面 |
https://opencode.ai/download |
|
官方文档 |
https://opencode.ai/docs/zh-cn |
|
GitHub |
https://github.com/anomalyco/opencode |
9.2 中文社区资源
|
资源 |
链接 |
|
OpenCode 中文站 |
https://www.opencodecn.com |
|
中文教程 |
https://www.opencodecn.com/tutorials |
|
菜鸟教程 |
https://www.runoob.com/ai-agent/opencode-coding-agent.html |
9.3 相关工具
- Oh My OpenCode: OpenCode 的多智能体扩展
- Models.dev: 支持 75+ 模型提供商的模型聚合服务
总结
OpenCode 是一个功能强劲且完全开源的 AI 编程助手，通过合理的配置和使用技巧，可以显著提升开发效率。
核心提议:
- 从简入手: 先掌握 OpenCode 本体，再思考 Oh My OpenCode
- 安全第一: 初期收紧权限，熟悉后再逐步放开
- 善用 AGENTS.md: 固化项目规则，提升 AI 理解能力
- Plan 先行: 在陌生项目中先使用 Plan 模式分析
本指南基于 OpenCode 官方文档和社区资料整理，如有更新请以官方文档为准。
© 版权声明
文章版权归作者所有，未经允许请勿转载。
相关文章
[db:评论]