opencode入门教程和omo使用指导
OpenCode 是一个开源的 AI 编码助手,通过在终端运行命令与 AI 交互来辅助开发。它支持超过 75 种 AI 模型,并能通过插件 Oh My OpenCode (OMO) 扩展为多智能体协作系统,大幅提升处理复杂任务的能力。
本文将从基础到进阶,为你梳理 OpenCode 的配置、常用命令,并重点介绍 OMO 的核心使用方法。
1. OpenCode 的配置
OpenCode 的配置主要通过 opencode.json 文件进行,支持全局和项目级配置。
| 配置类型 | 文件路径 | 说明 |
|---|---|---|
| 全局配置 | ~/.config/opencode/opencode.json | 适用于所有项目,适合配置主题、全局快捷键、通用模型供应商等。 |
| 项目配置 | <项目根目录>/.opencode/opencode.json | 仅对当前项目生效,优先级高于全局配置。通常会被提交到 Git 仓库中与团队共享。 |
| 环境变量 | OPENCODE_CONFIG | 通过设置此环境变量可指定一个自定义的配置文件路径,拥有最高优先级。 |
配置文件通常以 JSON 或 JSONC 格式编写。下面是一个配置示例,展示了如何添加自定义模型供应商和配置 AI 智能体:
json
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"my-custom-provider": {
"name": "MyCustomAI",
"options": {
"baseURL": "https://api.my-custom-ai.com/v1",
"apiKey": "your-api-key-here"
},
"models": {
"my-model-v1": {
"name": "MyModelV1",
"limit": {
"context": 128000,
"output": 8192
}
}
}
}
},
"theme": "dark",
"agents": {
"my-planner": {
"prompt": "你是一个项目规划专家,专注于分析需求、拆分任务和评估风险。"
}
}
}
此外,OpenCode 还支持通过 Markdown 文件定义自定义命令(放在 ~/.config/opencode/commands/ 或 .opencode/commands/ 目录下)。
2. OpenCode 的常见命令
OpenCode 的命令主要分为 CLI 命令和 TUI 交互命令两类。
2.1 CLI 命令
这些命令在终端中直接输入,用于管理 OpenCode 本身。
| 命令 | 说明 |
|---|---|
opencode | 无参数时,直接在终端启动 TUI 界面。 |
opencode auth login | 配置并登录 AI 模型供应商,需要提供 API Key。 |
opencode models | 列出当前可用的所有 AI 模型。 |
opencode agent list | 列出所有可用的 AI 智能体。 |
opencode mcp add | 添加 MCP (模型上下文协议) 服务器以扩展能力。 |
opencode --continue | 启动 TUI 并继续上一个会话。 |
opencode --session <session_id> | 启动 TUI 并恢复到指定的会话。 |
2.2 TUI 交互命令
在 OpenCode 的 TUI 界面中,主要通过斜杠 / 开头的命令与 AI 进行交互。
| 类别 | 命令 | 说明 | 快捷键 (Leader 键为 Ctrl+X) |
|---|---|---|---|
| 核心命令 | /init | 扫描项目,生成 AGENTS.md 文件,为 AI 提供项目上下文。 | Ctrl+X i |
/plan | 进入规划模式,AI 只分析不修改代码。 | ||
/build | 进入构建模式,AI 将实际修改代码。 | ||
| 对话管理 | /new 或 /clear | 开始一个新的对话会话。 | Ctrl+X n |
/sessions 或 /resume | 列出所有历史会话,并可切换。 | Ctrl+X l | |
/compact 或 /summarize | 压缩当前对话内容,以节省上下文 token。 | Ctrl+X c | |
/export | 将当前对话导出为 Markdown 文件。 | Ctrl+X x | |
/share | 生成当前对话的公开分享链接。 | Ctrl+X s | |
| 编辑与撤销 | /undo | 撤销 AI 上一次的修改。 | Ctrl+X u |
/redo | 重做被撤销的操作。 | Ctrl+X r | |
| 其他实用命令 | /models | 在多个 AI 模型之间切换。 | Ctrl+X m |
/themes | 切换终端界面主题。 | Ctrl+X t | |
/help | 显示帮助信息。 | Ctrl+X h | |
/exit 或 /quit | 退出 OpenCode 程序。 | Ctrl+X q |
3. 如何使用 OMO (Oh My OpenCode)
OMO 是 OpenCode 的一款增强插件,它能将单个 AI 模型升级为一个“多智能体协作团队”,自动调度不同角色的专家来协同完成复杂任务。
3.1 安装与配置
-
安装 Bun (若未安装):OMO 的安装脚本依赖 Bun 运行时。
bash
sudo npm install -g bun
-
安装 OMO:运行以下交互式命令进行安装。脚本会询问你订阅了哪些 AI 服务,根据实际情况选择即可。
bash
bunx oh-my-openagent install
注意:
oh-my-openagent是oh-my-opencode的新名称,两者完全兼容。 -
配置 AI 模型:安装完成后,你可以通过修改配置文件来指定不同角色使用的模型,配置文件位于:
-
全局:
~/.config/opencode/oh-my-opencode.json -
项目级:
.opencode/oh-my-opencode.json
在文件中,你可以为不同的agents指定具体的provider/model。
-
3.2 OMO 的核心使用
OMO 的使用非常简单,核心是在提示词中通过特定的“魔法词”来激活其强大的多智能体协作能力,而无需记忆额外命令。
-
/omo命令:这是最基础的使用方式,用于直接调用主协调器 Sisyphus 来处理一个或多个任务。例如:text
/omo 帮我重构这个认证模块,提高可维护性
-
ulw/ultrawork魔法词:激活“全火力”模式。Sisyphus 会自动规划、拆解并调度所有专家智能体,直至任务彻底完成。这是处理复杂任务最推荐的方式。例如:text
ulw 实现用户认证系统:注册、登录、JWT、权限控制
-
@指派特定智能体:你可以在对话中直接使用@符号来指派特定智能体(如oracle、librarian等)执行具体任务。例如:text
Ask @oracle 帮我分析这段代码的潜在并发风险。
3.3 OMO 专家智能体介绍
OMO 内置了多位分工明确的专家智能体,理解他们的专长有助于更好地指派任务。
| 智能体 | 角色定位 | 最佳使用场景 |
|---|---|---|
| Sisyphus | 总协调器 / 项目经理 | 处理一个完整、复杂的大任务,从分析到执行全程推进,无需你拆解步骤。 |
| Prometheus | 规划师 / 架构师 | 在动手写代码前,进行需求分析、技术方案设计、任务拆分和风险评估。 |
| Atlas | 执行者 / 施工队长 | 当你已经有一个明确的、拆解好的任务清单或方案,需要稳定地按计划实现。 |
| Hephaestus | 攻坚专家 / 高级工程师 | 专门解决疑难 Bug、复杂的构建失败、性能瓶颈等深度技术问题。 |
| Oracle | 技术顾问 | 对现有代码进行架构评审、分析潜在风险、提供技术选型建议。 |
| Librarian | 知识库专家 | 查找和整合外部技术文档、研究最佳实践、为任务提供知识支持。 |
简而言之,当你需要对项目进行快速问答或简单修改时,直接使用 OpenCode 本身就很高效。而当面对需要深度分析、多步骤执行或跨模块协作的复杂任务时,引入 OMO 这样的多智能体系统将极大地提升你的开发效率。
更多推荐

所有评论(0)