opencode快速上手

发表于 2026-03-09 更新于 2026-03-12 分类于笔记阅读次数： Waline：本文字数： 8.4k 阅读时长 ≈ 31 分钟

快速上手 opencode，体验 oh-my-opencode（现已改名为 oh-my-openagent）的强大功能！

一、基础环境配置

1. Shell 安装

Windows：推荐安装 PowerShell

按 Win + R，输入 cmd 并回车，打开命令提示符后执行：

1 2	winget update winget install --id Microsoft.PowerShell --source winget

Linux / macOS

看个人喜好即可，不改动默认 Shell 也可以。
如果你更习惯 zsh、fish 等，也可以自行安装，安装方法参考各自官网。

2. 运行时安装

安装以下运行环境：

3. 开发必备工具

建议安装：

4. 换源

npm 换源

1	npm config set registry https://registry.npmmirror.com

pip 换源

1	pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

二、安装 opencode

官网：opencode 官网

推荐使用 npm 全局安装：

1	npm i -g opencode-ai

安装完成后，可以通过以下命令验证是否安装成功：

1	opencode --version

为了方便后续更新，建议额外安装 npm-check：

1	npm i -g npm-check

由于 opencode 是全局安装的，所以更新也很简单：

1	npm-check -gu

通过简单的交互即可完成更新。

三、安装 oh-my-opencode（现 oh-my-openagent）

建议后续都使用 Windows Terminal 打开 PowerShell 进行命令行操作。

先启动 opencode：

opencode

然后在聊天框中输入以下内容，让 opencode 自带的免费模型帮你交互式完成安装：

1
2
3

Install and configure oh-my-opencode by following the instructions here:
https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/refs/heads/dev/docs/guide/installation.md
请你用中文回答我，并且一步步引导我完成安装

接下来按照提示一步步完成安装即可。
AI 会问你一些问题，你只需要根据自己的需求进行选择。

四、oh-my-opencode（现 oh-my-openagent）使用

安装完成后，输入 /exit 退出 opencode，再重新执行：

opencode

重新打开后即可开始使用。

五、opencode 基本使用方法

opencode 的界面交互，大多数都可以通过以 / 开头的命令完成。
软件自带智能搜索和自动补齐：输入部分命令后，可以用上下方向键选择，再按 Tab 自动补全，整体体验非常方便。

如果你不喜欢纯命令行交互，也可以按 Ctrl + P 打开 TUI 界面，用图形化界面进行操作。

opencode 的 TUI 交互界面非常好用。除了少数功能需要通过快捷键触发之外，多数可键盘操作的界面其实也支持鼠标点击，鼠标滚轮同样可用。喜欢哪种方式就用哪种，没有强制要求。

一开始建议先输入：

/models

查看当前有哪些模型可用。

然后可以使用：

/connect

连接不同的模型供应商。

opencode 支持的模型供应商非常多。即便不在自带列表中，也可以通过 /connect 中的自定义接口，选择 OpenAI 协议、Anthropic 协议等方式连接其他模型供应商，灵活性很高（当然不是很推荐滥用自定义接入）。

如果你购买了某个模型厂商的 coding plan 订阅，建议直接参考对应厂商文档进行接入。

六、oh-my-opencode（现 oh-my-openagent）基本使用方法

oh-my-opencode（现 oh-my-openagent）是一个基于 opencode 的插件系统。安装完成后即可直接使用。

输入 / 后，如果命令后面的简介是以 (builtin) 开头的，那就是 oh-my-opencode 提供的功能。

后面我会介绍一些常用工作流插件的使用。其实也不用死记硬背，不懂时直接问 AI 就行，因为 AI 可以访问配置文件和代码库，往往比你更懂当前 opencode 的配置状态以及插件的具体用法。

首先需要接入一些模型。这里的建议是：

如果预算有限，可以考虑国内厂商的 coding plan：便宜、量大，但某些 OMO 插件的效果可能不如预期
如果有条件，建议尝试获取一个 GitHub Copilot 订阅，可以使用 OpenAI 和 Anthropic 的较新模型，速度尚可，额度对轻度使用通常也够用
如果预算更充足，也可以购买 OpenAI 的订阅
这里不太推荐 Anthropic 直连方案，因为封号问题比较严重，OMO 官方也不再推荐

另外，oh-my-opencode 支持多模型并行使用。
也就是说，你可以同时接入多个模型供应商，在后续使用插件时按任务类型切换模型，灵活性非常高。

七、OMO 配置快速上手指南

本指南帮助你快速配置 oh-my-opencode（现 oh-my-openagent），让 AI 助手团队发挥最大效能。

1. 配置文件在哪？

配置文件位置如下：

用户级配置
- Windows：C:\Users\你的用户名\.config\opencode\oh-my-opencode.json
- Linux / macOS：~/.config/opencode/oh-my-opencode.json
项目级配置
- 项目根目录下：.opencode/oh-my-opencode.json

这两份配置会合并，并且项目级配置覆盖用户级配置。
一般情况下，只使用用户级配置就够了。

2. 核心概念：Agents 和 Categories

什么是 Agent？

Agent 可以理解为专门负责某类任务的 AI 助手。
OMO 内置了 11 个专业 Agent：

Agent	干啥的	简单理解
Sisyphus	主指挥官	规划任务、分配工作、统筹全局
Hephaestus	自主工作者	给个目标，自己研究代码库、自己实现
Prometheus	战略规划师	像真正的工程师一样帮你做详细计划
Oracle	顾问	只读专家，负责架构咨询、疑难杂症
Librarian	外部搜索员	帮你查官方文档、GitHub 示例、库用法
Explore	内部搜索员	帮你在代码库里找文件、找模式
Atlas	Todo 管理员	执行 Prometheus 的计划，管理任务列表

此外还有几个辅助 Agent：

Metis：需求分析
Momus：计划审核
Multimodal-Looker：看图、看 PDF

什么是 Category？

Category 是一种按任务类型自动匹配模型的机制。
你告诉它“我要做什么”，它会自动帮你选择更合适的模型类型。

Category	干啥的	自动匹配的模型类型
`visual-engineering`	前端、UI、样式、设计	擅长视觉理解的模型（如 Gemini）
`ultrabrain`	困难逻辑、复杂架构	深度推理模型（如 GPT-5.3 Codex）
`deep`	自主执行、深度研究	自主工作型模型
`artistry`	创意、打破常规	创意型模型
`quick`	简单修改、typo 修复	快速便宜的模型
`writing`	写文档、写文章	写作型模型

3. 配置的核心原则

3.1 模型选择原则

按任务复杂度选模型：

复杂度	推荐模型	原因
简单任务	Qwen、Haiku、Gemini Flash	便宜、快速，通常够用
中等任务	GLM-5、Kimi、Sonnet	性价比较高
复杂任务	GPT-5.4、Claude Opus、Gemini Pro	推理能力更强

3.2 Agent 推荐配置

Agent	推荐模型	理由
Sisyphus	GLM-5 / Kimi-K2.5 / Claude Opus	编排能力强
Hephaestus	GPT-5.3 Codex（必须）	为自主工作专门优化
Oracle	GPT-5.4	适合高强度只读推理
Librarian	Gemini Flash / Qwen	便宜快速，适合搜索
Explore	Grok-Code-Fast / Qwen	适合快速代码搜索

3.3 安全覆盖 vs 危险覆盖

安全覆盖：同类型模型互换，一般没问题

1 2	Sisyphus: Claude Opus → GLM-5 / Kimi ✓ Oracle: GPT-5.4 → Gemini Pro ✓

危险覆盖：模型类型不匹配，效果可能明显下降

1 2	Hephaestus → Claude ✗ （Hephaestus 为 Codex 优化） Sisyphus → 旧版 GPT ✗ （编排能力下降）

4. 实际配置示例

我的配置（参考）

我同时使用了 GitHub Copilot 和 阿里云百炼 Coding Plan，配置如下，供大家参考：

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
  "agents": {
    "hephaestus": {
      "model": "github-copilot/gpt-5.3-codex",
      "variant": "medium"
    },
    "oracle": {
      "model": "github-copilot/gpt-5.4",
      "variant": "high"
    },
    "librarian": {
      "model": "bailian-coding-plan/qwen3.5-plus"
    },
    "explore": {
      "model": "github-copilot/grok-code-fast-1"
    },
    "multimodal-looker": {
      "model": "bailian-coding-plan/qwen3.5-plus"
    },
    "prometheus": {
      "model": "bailian-coding-plan/glm-5"
    },
    "metis": {
      "model": "bailian-coding-plan/kimi-k2.5"
    },
    "momus": {
      "model": "github-copilot/gpt-5.4",
      "variant": "xhigh"
    },
    "atlas": {
      "model": "bailian-coding-plan/glm-5"
    },
    "sisyphus": {
      "model": "bailian-coding-plan/glm-5"
    }
  },
  "categories": {
    "visual-engineering": {
      "model": "github-copilot/gemini-3.1-pro-preview"
    },
    "ultrabrain": {
      "model": "github-copilot/gpt-5.3-codex",
      "variant": "xhigh"
    },
    "deep": {
      "model": "github-copilot/gpt-5.3-codex",
      "variant": "medium"
    },
    "artistry": {
      "model": "github-copilot/gemini-3.1-pro-preview"
    },
    "quick": {
      "model": "bailian-coding-plan/qwen3.5-plus"
    },
    "unspecified-low": {
      "model": "bailian-coding-plan/qwen3.5-plus"
    },
    "unspecified-high": {
      "model": "github-copilot/gemini-3.1-pro-preview"
    },
    "writing": {
      "model": "bailian-coding-plan/qwen3.5-plus"
    }
  }
}

配置思路

主力编排（Sisyphus、Prometheus）：使用阿里云 GLM-5，便宜、稳定、性能高
深度执行（Hephaestus、deep、ultrabrain）：必须使用 GPT-5.3 Codex
视觉任务（visual-engineering、artistry）：使用 Gemini
简单任务（quick、writing）：使用便宜的 Qwen

服务	费用	用途
GitHub Copilot	(~~免费拿的不知道多少钱~~)	GPT、Claude 系列模型访问
阿里云百炼 Coding Plan	(~~便宜量又大就是了~~)	GLM、Kimi、Qwen 访问

5. 常见问题

Q：不配置会怎样？

A：不配置也没问题，系统会使用内置默认配置和 fallback 链。
不过配置之后体验通常会更好，因为你可以用上自己订阅的模型。

Q：`variant` 是什么？

A：variant 控制模型的“努力程度”：

1	low < medium < high < xhigh < max

等级越高，推理越强，但通常也越慢、越贵。

Q：`fallback_models` 是什么？

A：它是备用模型链。
如果第一个模型不可用，系统会自动切换到下一个模型，提高可靠性。

Q：怎么知道有哪些模型可用？

A：在 opencode 中输入：

/models

即可查看。

6. 快速参考

四个主 Agent 的 `Tab` 快速选择建议

Agent	推荐做法
Sisyphus	直接使用，或输入 `ulw` 进入 ultrawork 模式
Hephaestus	适合自主执行、目标导向型任务，给目标即可开始工作
Prometheus	适合复杂任务规划，只规划不实施
Atlas	用来执行 Prometheus 给出的计划。一般不独立使用，Prometheus 规划完成后会提醒你通过命令自动调用实施

总结一下，配置不难，记住三点即可：

Hephaestus 必须使用 GPT-5.3 Codex（因为提示词只针对 GPT 系列做了适配）
Sisyphus 适合搭配 GLM-5 / Kimi / Claude Opus 这类编排能力强的模型
简单任务用便宜模型，复杂任务用好模型

八、个人使用心得

1. 新手入门操作建议

入门阶段可以直接一直使用 Sisyphus。
如果遇到比较大的任务，可以加一个 ulw。

在这种情况下，AI 往往比你更清楚如何完成任务。你只需要给出目标，它就会自己规划任务拆解和执行流程。剩下的事情更多是等待它完成。

不用太担心中途会不会卡住或者出问题，因为 opencode 的设计目标之一，就是让它尽量自行处理这些问题。

2. 学会在合适的时候切换 Agent

不同 Agent 适合不同任务：

Sisyphus：适合大多数任务；还有 ulw 模式，能够自己规划和执行任务，适合“不想动脑”或者暂时不清楚具体怎么做的情况
Hephaestus：适合需要自主研究并实现的任务
Prometheus：适合需要详细规划的任务
Atlas：适合执行 Prometheus 给出的计划

根据任务类型选择合适的 Agent，可以显著提升 AI 的工作效率。

3. 焚决：强制更新 OMO 插件版本

OMO 插件更新非常频繁，但官方并没有给出明确的更新说明（没错，基本就是没有）。

不过这里我摸索出一个强制刷新 OMO 插件版本的方法：
通过清理缓存，让 opencode 重新下载最新版依赖。

Windows

1	Remove-Item -Path $env:USERPROFILE\.cache\opencode\ -Recurse -Force -ErrorAction SilentlyContinue

Linux / macOS

1	rm -rf ~/.cache/opencode/

然后重新打开 opencode 即可。
opencode 会自动下载所有依赖的最新版，通常需要十几秒，具体取决于网速。

不过前面已经做过 npm 换源，所以一般不用太担心网络问题。

4. 扩展复用

4.1 `Skills` 生态

opencode 能读取到 Claude Code 中安装的 Skills。
如果你之前在 CC 里装过一些 Skills，opencode 通常可以自动识别并直接使用，无需重复安装。

4.2 MCP

opencode 的 MCP 不能直接从别的软件读取。
不过 MCP 本身是开放且统一的协议，所以再移植一遍到 opencode 中即可。不会的话，直接让 AI 帮你迁移就行。

4.3 插件生态

opencode 有自己的插件生态，不能直接复用 Claude Code 中的插件。

九、OMO 插件内置命令参考

根据对 code-yeongyu/oh-my-openagent（即 Oh My OpenCode）仓库的全面分析，以下是该插件中所有以 / 开头可触发的斜杠命令（Slash Commands）的完整列表和详细解析。

1. 所有 `/` 斜杠命令一览

Oh My OpenCode 的命令分为 3 大类：

内置命令（Built-in）
项目自定义命令（Project Custom）
通过 Skill 系统触发的命令

2. 内置命令（Built-in Commands）— 8 个

#	命令	用法	说明
1	`/init-deep`	`/init-deep [--create-new] [--max-depth=N]`	初始化分层 AGENTS.md 知识库
2	`/ralph-loop`	`/ralph-loop "任务描述" [--max-iterations=N]`	启动自引用开发循环
3	`/ulw-loop`	`/ulw-loop "任务描述" [--strategy=reset\|continue]`	启动 ultrawork 极限模式循环
4	`/cancel-ralph`	`/cancel-ralph`	取消正在运行的 Ralph Loop
5	`/refactor`	`/refactor <目标> [--scope=file\|module\|project] [--strategy=safe\|aggressive]`	智能重构
6	`/start-work`	`/start-work [plan-name]`	从 Prometheus 计划启动工作会话
7	`/stop-continuation`	`/stop-continuation`	停止所有继续机制
8	`/handoff`	`/handoff [goal]`	创建会话交接上下文摘要

详细解析

1）`/init-deep` —— 初始化分层知识库

功能：在项目目录树中自动生成分层的 AGENTS.md 文件，让 AI Agent 在读取文件时自动获得目录级上下文
参数：
- --create-new：创建新文件
- --max-depth=N：限制递归深度
效果：会在 project/、src/、src/components/ 等各级目录生成上下文文件

2）`/ralph-loop` —— 自引用开发循环

功能：Agent 持续朝着目标工作直到完成
命名来源：Anthropic 的 Ralph Wiggum 插件
行为：
- 检测 <promise>DONE</promise> 标记完成
- Agent 停止但未完成时自动继续
- 达到最大迭代次数（默认 100）或通过 /cancel-ralph 中止
配置：

1	{ "ralph_loop": { "enabled": true, "default_max_iterations": 100 } }

3）`/ulw-loop` —— Ultrawork 极限模式循环

功能：与 ralph-loop 相同，但启用 ultrawork 模式
特点：以最高强度运行——并行 Agent、后台任务、激进探索全部开启

4）`/cancel-ralph` —— 取消 Ralph Loop

功能：终止当前正在运行的 Ralph Loop 或 ULW Loop

5）`/refactor` —— 智能重构

功能：利用完整工具链进行智能重构
特性：
- LSP 驱动的重命名和导航
- AST-grep 模式匹配
- 架构分析
- TDD 验证后确认
- 代码地图生成

6）`/start-work` —— 启动工作会话

功能：从 Prometheus Agent 生成的计划启动 Sisyphus 工作会话
Agent：使用 Atlas agent 系统性执行已规划任务
参数：可选指定计划名称

7）`/stop-continuation` —— 停止所有延续机制

功能：停止当前会话中的所有自动继续机制，包括：
- ralph loop
- todo continuation
- boulder state
使用场景：当你希望 Agent 停止其多步工作流时

8）`/handoff` —— 会话交接

功能：生成结构化的交接文档，记录当前状态、已完成工作、待完成事项、关键文件路径
用途：在新会话中无缝继续之前的工作

3. 项目自定义命令（Project Custom Commands）— 4 个

这些命令定义在 .opencode/command/ 目录下的 Markdown 文件中。

#	命令	说明
9	`/publish`	发布 npm 包到 GitHub Actions 工作流
10	`/omomomo`	🥚 彩蛋命令——关于 Oh My OpenCode
11	`/remove-deadcode`	使用 LSP 验证的并行死代码移除
12	`/get-unpublished-changes`	对比未发布的变更

详细解析

9）`/publish` —— npm 发布管理器

用法：/publish <patch|minor|major>
功能：全自动执行 oh-my-opencode 的 npm 发布流程
流程：
1. 确认版本号类型
2. 检查未提交更改
3. 同步远端
4. 触发 GitHub Actions
5. 等待完成
6. 验证 Release
7. 验证 npm 发布
8. 验证 7 个平台二进制包
特点：必须由用户明确提供版本号类型参数才会执行

10）`/omomomo` —— 彩蛋命令 🥚✨

功能：显示关于 Oh My OpenCode 项目的介绍信息
输出内容：项目特性介绍（多 Agent 编排、LSP 工具、AST-Grep、内置 MCP、背景 Agent 等）和作者信息

11）`/remove-deadcode` —— 智能死代码清理

功能：通过大规模并行深度 Agent 移除未使用代码
流程：分为 5 个阶段
1. 扫描（TypeScript strict + Explore agents 并行）
2. LSP 验证（零误判）
3. 批次分配
4. 并行 Agent 执行
5. 最终验证
安全机制：
- 以 LspFindReferences 为法律
- 永不删除入口点、测试文件
- 原子提交
- 失败自动回滚
参数：可指定文件路径 / 目录 / 符号名来缩小范围

12）`/get-unpublished-changes` —— 查看未发布变更

功能：将当前 HEAD 与最新发布的 npm 版本对比，列出所有未发布的变更
特点：
- 不是简单复制 commit message
- 而是读取实际 diff 后用自然语言描述变更
- 支持 Oracle 部署安全评审（通过关键词触发）
输出：按 feat / fix / refactor / docs 分类的变更表格，并附带推荐版本升级建议

4. Skill 触发的命令 — 6 个

Skill 也可以作为斜杠命令调用（通过 auto-slash-command hook 自动检测执行）：

#	命令	触发场景	说明
13	`/git-master`	commit、rebase、squash	Git 专家——原子提交、风格检测、rebase 策略
14	`/playwright`	浏览器任务、测试	Playwright MCP 驱动的浏览器自动化
15	`/playwright-cli`	浏览器 CLI 脚本	Playwright CLI 集成
16	`/agent-browser`	浏览器任务	Vercel agent-browser CLI 驱动的浏览器自动化
17	`/dev-browser`	有状态浏览器脚本	持久页面状态的浏览器自动化
18	`/frontend-ui-ux`	UI/UX 任务	设计师 + 开发者角色的 UI/UX 专家

详细解析

13）`/git-master` —— Git 大师

用法：
- /git-master commit these changes
- /git-master rebase onto main
三大专精：
- Commit Architect：原子提交、依赖排序、风格检测
- Rebase Surgeon：历史重写、冲突解决
- History Archaeologist：查找代码变更历史
特点：会自动检测最近 30 条 commit 的语言和风格，以匹配仓库已有的 commit 规范

14）`/playwright` —— 浏览器自动化（MCP）

功能：通过 Playwright MCP 服务器进行浏览器自动化
能力：
- 导航网页
- 截图 / 导出 PDF
- 填写表单
- 等待网络请求
- 抓取页面内容

15）`/playwright-cli` —— 浏览器自动化（CLI）

功能：通过 Playwright CLI 进行浏览器操作
适用场景：适合偏好直接写 CLI 脚本的使用方式

16）`/agent-browser` —— Agent Browser

功能：通过 Vercel 的 agent-browser CLI 进行浏览器自动化
能力：
- 页面导航
- 快照
- 截图
- 网络检查
- 脚本交互

17）`/dev-browser` —— 开发浏览器

功能：支持持久页面状态的浏览器自动化
适用场景：适合迭代式工作流以及已经登录认证的页面操作

18）`/frontend-ui-ux` —— 前端 UI/UX 专家

功能：以“设计师转开发者”的角色进行 UI / UX 开发
设计流程：
- 目的
- 基调
- 约束
- 差异化
- 美学方向（例如：粗野主义 / 极繁 / 复古未来 / 奢华 / 趣味）

命令加载位置（优先级从高到低）

.opencode/command/*.md（项目级，OpenCode 原生）
~/.config/opencode/command/*.md（用户级，OpenCode 原生）
.claude/commands/*.md（项目级，Claude Code 兼容）
~/.config/opencode/commands/*.md（用户级，Claude Code 兼容）

也支持命名空间命令，例如：

1	/daplug:run-prompt

十、opencode 自带内置命令参考

Let me search the repository for the built-in slash commands available in opencode’s chat interface. 根据 anomalyco/opencode 的官方文档（packages/web/src/content/docs/tui.mdx），以下是 OpenCode 聊天框中以 / 开头能触发的 全部 18 个自带斜杠命令 的详细解析：

1. 全部内置斜杠命令一览

#	命令	别名	快捷键	简述
1	`/connect`	—	—	添加 Provider
2	`/compact`	`/summarize`	`ctrl+x c`	压缩当前会话
3	`/details`	—	`ctrl+x d`	切换工具执行详情
4	`/editor`	—	`ctrl+x e`	打开外部编辑器
5	`/exit`	`/quit`, `/q`	`ctrl+x q`	退出 OpenCode
6	`/export`	—	`ctrl+x x`	导出对话为 Markdown
7	`/help`	—	`ctrl+x h`	显示帮助
8	`/init`	—	`ctrl+x i`	创建 / 更新 AGENTS.md
9	`/models`	—	`ctrl+x m`	列出可用模型
10	`/new`	`/clear`	`ctrl+x n`	开始新会话
11	`/redo`	—	`ctrl+x r`	重做撤销的消息
12	`/sessions`	`/resume`, `/continue`	`ctrl+x l`	列出 / 切换会话
13	`/share`	—	`ctrl+x s`	分享当前会话
14	`/themes`	—	`ctrl+x t`	列出可用主题
15	`/thinking`	—	—	切换思考块显示
16	`/undo`	—	`ctrl+x u`	撤销最后消息
17	`/unshare`	—	—	取消分享会话

注意：除了以上自带命令外，用户还可以通过自定义命令（custom commands）、MCP 工具和 Skill 注册额外的斜杠命令，它们也会出现在 / 弹出菜单中。

2. 每个命令的详细解析

1）`/connect`

功能：将一个 AI Provider 添加到 OpenCode。执行后会弹出选择界面，允许你从可用 Provider 列表中选择，并输入对应的 API Key。

使用场景：首次配置，或需要添加新的模型提供商时（例如 Anthropic、OpenAI、xAI 等）。

2）`/compact`（别名：`/summarize`）

快捷键：ctrl+x c

功能：压缩（compaction）当前会话。
当对话过长时，这个命令会将历史消息进行摘要压缩，减少 Token 消耗，同时尽量保留关键上下文。

使用场景：对话变得很长、接近上下文窗口限制时，可以节省 Token 开支。

3）`/details`

快捷键：ctrl+x d

功能：切换工具执行详情的显示状态。
开启后可以看到每个工具调用的详细输入输出；关闭后则只显示简要结果。

使用场景：调试工具调用时开启，日常使用时关闭以保持界面简洁。

4）`/editor`

快捷键：ctrl+x e

功能：打开外部编辑器来编写较长消息。
使用的编辑器由 EDITOR 环境变量决定，例如 vim、code --wait、nano 等。编辑完成并关闭后，内容会自动发送到聊天框。

使用场景：需要编写多行复杂 Prompt 时更方便。

5）`/exit`（别名：`/quit`, `/q`）

快捷键：ctrl+x q

功能：退出 OpenCode TUI 应用程序。

使用场景：结束使用时退出程序。

6）`/export`

快捷键：ctrl+x x

功能：将当前对话导出为 Markdown 格式，并在默认编辑器（由 EDITOR 环境变量指定）中打开。

使用场景：需要保存、分享或归档对话内容时使用。

7）`/help`

快捷键：ctrl+x h

功能：显示帮助对话框，列出所有可用操作和命令。
本质上它也是“命令面板”（Command Palette），可以在其中搜索和执行各种操作。

使用场景：不确定有哪些命令可用，或者需要查看快捷键时使用。

8）`/init`

快捷键：ctrl+x i

功能：创建或更新项目根目录下的 AGENTS.md 文件。
AGENTS.md 是 OpenCode 的规则文件（Rules），用于定义 AI Agent 在该项目中的行为规范和上下文信息。

使用场景：初始化项目的 AI 代理规则，或更新已有规则时使用。

9）`/models`

快捷键：ctrl+x m

功能：列出当前所有可用模型。
会显示所有已配置 Provider 下可用的模型，便于你切换。

使用场景：需要查看或切换当前模型时。

10）`/new`（别名：`/clear`）

快捷键：ctrl+x n

功能：开始一个新会话，并清空当前对话历史。

使用场景：当前任务完成后开始新话题，或对话走偏后重新开始。

11）`/redo`

快捷键：ctrl+x r

功能：重做之前被 /undo 撤销的消息。
不仅会恢复消息，还会恢复相关的文件更改。

前提条件：

必须先执行过 /undo
当前项目必须是一个 Git 仓库（内部使用 Git 来管理文件变更的撤销 / 重做）

使用场景：误执行 /undo 后，需要恢复时。

12）`/sessions`（别名：`/resume`, `/continue`）

快捷键：ctrl+x l

功能：列出所有已有会话，并允许在它们之间切换。
你可以恢复之前的对话上下文继续工作。

使用场景：需要在多个任务 / 对话之间切换，或者恢复未完成的会话。

13）`/share`

快捷键：ctrl+x s

功能：分享当前会话，生成一个可分享链接，其他人可以通过这个链接查看你的对话内容。

使用场景��需要与团队成员分享调试过程或讨论内容时。

14）`/themes`

快捷键：ctrl+x t

功能：列出所有可用 UI 主题，并允许你切换 TUI 的视觉风格。

使用场景：想自定义 TUI 外观时。

15）`/thinking`

功能：切换对话中思考 / 推理（thinking / reasoning）块的可见性。
开启后，你可以看到支持扩展思考的模型（例如 Claude 的 extended thinking）的内部推理过程。

⚠️ 重要说明：这个命令只控制思考块是否显示，并不会启用或禁用模型本身的推理能力。
要切换实际的推理能力，需要使用 ctrl+t 来循环切换模型变体（variant）。

使用场景：希望观察模型推理过程，以便调试或学习时。

16）`/undo`

快捷键：ctrl+x u

功能：撤销对话中的最后一条消息。
它会移除最近的用户消息、所有后续 AI 响应，以及所有相关的文件更改。

前提条件：项目必须是一个 Git 仓库（内部使用 Git 来管理文件变更的回退）。

使用场景：AI 编辑后一次操作不满意，例如改错了文件，需要完整回退时。

17）`/unshare`

功能：取消分享当前会话，撤回之前通过 /share 生成的分享链接。

使用场景：不再需要公开分享对话内容时。

3. 补充说明

除了以上 17 个自带命令，OpenCode 的斜杠命令系统还支持扩展：

自定义命令（Custom Commands）：用户可在项目配置中定义自己的斜杠命令
MCP 工具命令：通过 MCP（Model Context Protocol）服务器注册的命令也会显示在 / 弹出菜单中，并带有 mcp 标签
Skill 命令：通过 Skill 系统注册的命令会带有 skill 标签

这些扩展命令会在弹出菜单中通过不同标签（badge）进行区分，方便识别命令来源。

十一、opencode CLI 命令解析

1. 默认行为

不带任何参数直接运行 opencode 时，默认会启动 TUI（终端用户界面）：

opencode

2. `opencode [project]` —— 启动 TUI

启动 OpenCode 的终端交互界面，也可以选择性地传入一个项目路径。

Flag	缩写	说明
`--continue`	`-c`	继续上一次会话
`--session`	`-s`	指定要继续的会话 ID
`--fork`	—	在继续会话时分叉（需配合 `--continue` 或 `--session` 使用）
`--prompt`	—	指定使用的 prompt
`--model`	`-m`	指定模型，格式为 `provider/model`
`--agent`	—	指定使用的 agent
`--port`	—	监听端口
`--hostname`	—	监听主机名

3. 子命令（Commands）

3.1 `opencode agent [command]` —— 管理 Agent

管理 OpenCode 的 AI Agent。

子命令

opencode agent create：创建一个新的自定义 Agent，会引导你配置自定义系统提示词和工具
opencode agent list：列出所有可用 Agent

3.2 `opencode attach [url]` —— 附加到远程服务器

将终端 TUI 连接到一个已经通过 serve 或 web 命令启动的 OpenCode 后端服务器。

# 先启动后端
opencode web --port 4096 --hostname 0.0.0.0

# 另一个终端附加
opencode attach http://10.20.30.40:4096

Flag	缩写	说明
`--dir`	—	启动 TUI 的工作目录
`--session`	`-s`	指定要继续的会话 ID

3.3 `opencode auth [command]` —— 管理认证凭据

管理 Provider（如 Anthropic、OpenAI 等）的 API Key 和登录信息。

子命令

opencode auth login：登录 / 配置 Provider API Key，存储在 ~/.local/share/opencode/auth.json
opencode auth list（别名 opencode auth ls）：列出所有已认证 Provider
opencode auth logout：登出某个 Provider，并清除凭据文件中的对应记录

3.4 `opencode github [command]` —— 管理 GitHub Agent

管理 GitHub Agent 以实现仓库自动化。

子命令

opencode github install：在仓库中安装 GitHub Agent（设置 GitHub Actions 工作流并引导配置）
opencode github run：运行 GitHub Agent（通常在 GitHub Actions 中使用）

Flag	说明
`--event`	指定要运行的 GitHub 模拟事件
`--token`	GitHub 个人访问令牌（PAT）

3.5 `opencode mcp [command]` —— 管理 MCP 服务器

管理 Model Context Protocol（模型上下文协议）服务器。

子命令

opencode mcp add：添加一个 MCP 服务器（本地或远程），会有交互式引导
opencode mcp list（别名 opencode mcp ls）：列出所有已配置 MCP 服务器及其连接状态
opencode mcp auth [name]：对支持 OAuth 的 MCP 服务器进行认证；不提供名称时会弹出选择器
- opencode mcp auth list（别名 opencode mcp auth ls）：列出支持 OAuth 的服务器及其认证状态
opencode mcp logout [name]：移除某个 MCP 服务器的 OAuth 凭据
opencode mcp debug <name>：调试某个 MCP 服务器的 OAuth 连接问题

3.6 `opencode models [provider]` —— 列出可用模型

列出所有已配置 Provider 的可用模型，格式为 provider/model。
也可以选择性传入 Provider ID 进行过滤。

1	opencode models anthropic

Flag	说明
`--refresh`	从 models.dev 刷新模型缓存
`--verbose`	输出更详细信息（包含成本等元数据）

3.7 `opencode run [message..]` —— 非交互式运行

直接传入 prompt，以非交互模式运行 OpenCode，适合脚本化和自动化场景。

1	opencode run "Explain the use of context in Go"

也可以连接到一个正在运行的 opencode serve 实例，以避免 MCP 冷启动：

1	opencode run --attach http://localhost:4096 "Explain async/await in JavaScript"

Flag	缩写	说明
`--command`	—	要运行的命令，使用 message 作为参数
`--continue`	`-c`	继续上一次会话
`--session`	`-s`	指定会话 ID
`--fork`	—	在继续会话时分叉
`--share`	—	分享该会话
`--model`	`-m`	指定模型，格式为 `provider/model`
`--agent`	—	指定使用的 Agent
`--file`	`-f`	附加文件到消息
`--format`	—	输出格式：`default`（格式化）或 `json`（原始 JSON 事件）
`--title`	—	会话标题（不提供则使用截断后的 prompt）
`--attach`	—	连接到运行中的 opencode 服务器（例如 `http://localhost:4096`）
`--port`	—	本地服务器端口（默认随机端口）

3.8 `opencode serve` —— 启动无头服务器

启动一个无头 HTTP 服务器，提供 API 访问 OpenCode 功能（不启动 TUI）。

如果设置 OPENCODE_SERVER_PASSWORD 环境变量，还可以启用 HTTP Basic Auth。

Flag	说明
`--port`	监听端口
`--hostname`	监听主机名
`--mdns`	启用 mDNS 发现
`--cors`	额外允许的浏览器跨域来源

3.9 `opencode session [command]` —— 管理会话

子命令

opencode session list：列出所有 OpenCode 会话

Flag	缩写	说明
`--max-count`	`-n`	限制显示最近 N 个会话
`--format`	—	输出格式：`table` 或 `json`（默认 `table`）

3.10 `opencode stats` —— 查看使用统计

显示 Token 使用量和成本统计信息。

Flag	说明
`--days`	显示最近 N 天的统计（默认全部）
`--tools`	显示的工具数量（默认全部）
`--models`	显示模型使用细分（默认隐藏），传入数字可显示 Top N
`--project`	按项目过滤（默认全部项目，空字符串表示当前项目）

3.11 `opencode export [sessionID]` —— 导出会话

将会话数据导出为 JSON 格式。
如果不提供 session ID，则会弹出选择器。

1	opencode export

3.12 `opencode import <file>` —— 导入会话

从 JSON 文件或 OpenCode 分享链接导入会话数据。

1 2	opencode import session.json opencode import https://opncd.ai/s/abc123

3.13 `opencode web` —— 启动 Web 界面

启动一个带 Web 界面的无头 OpenCode 服务器，并自动打开浏览器。

Flag	说明
`--port`	监听端口
`--hostname`	监听主机名
`--mdns`	启用 mDNS 发现
`--cors`	额外允许的浏览器跨域来源

3.14 `opencode acp` —— 启动 ACP 服务器

启动一个 Agent Client Protocol（代理客户端协议）服务器，通过 stdin/stdout 使用 nd-JSON 进行通信。

Flag	说明
`--cwd`	工作目录
`--port`	监听端口
`--hostname`	监听主机名

3.15 `opencode uninstall` —— 卸载 OpenCode

卸载 OpenCode 并移除所有相关文件。

Flag	缩写	说明
`--keep-config`	`-c`	保留配置文件
`--keep-data`	`-d`	保留会话数据和快照
`--dry-run`	—	仅展示将被删除的内容，不实际删除
`--force`	`-f`	跳过确认提示

3.16 `opencode upgrade [target]` —— 升级 OpenCode

将 OpenCode 升级到最新版本或指定版本。

1 2	opencode upgrade # 升级到最新版 opencode upgrade v0.1.48 # 升级到指定版本

Flag	缩写	说明
`--method`	`-m`	指定安装方式：`curl`、`npm`、`pnpm`、`bun`、`brew`

4. 全局 Flags（适用于所有命令）

Flag	缩写	说明
`--help`	`-h`	显示帮助信息
`--version`	`-v`	打印版本号
`--print-logs`	—	将日志打印到 stderr
`--log-level`	—	日志级别：`DEBUG`、`INFO`、`WARN`、`ERROR`

5. 环境变量

OpenCode 支持通过环境变量进行配置，主要包括：

环境变量	类型	说明
`OPENCODE_AUTO_SHARE`	boolean	自动分享会话
`OPENCODE_CONFIG`	string	配置文件路径
`OPENCODE_CONFIG_DIR`	string	配置目录路径
`OPENCODE_CONFIG_CONTENT`	string	内联 JSON 配置内容
`OPENCODE_TUI_CONFIG`	string	TUI 配置文件路径
`OPENCODE_DISABLE_AUTOUPDATE`	boolean	禁用自动更新检查
`OPENCODE_DISABLE_AUTOCOMPACT`	boolean	禁用自动上下文压缩
`OPENCODE_PERMISSION`	string	内联 JSON 权限配置
`OPENCODE_SERVER_PASSWORD`	string	为 `serve` / `web` 启用 Basic Auth
`OPENCODE_SERVER_USERNAME`	string	覆盖 Basic Auth 用户名（默认 `opencode`）
`OPENCODE_CLIENT`	string	客户端标识（默认 `cli`）
`OPENCODE_MODELS_URL`	string	自定义模型配置获取 URL
…	…	还有更多实验性环境变量，详见文档

6. 命令总览图

opencode
├── (default)           → 启动 TUI
├── agent
│   ├── create          → 创建新 Agent
│   └── list            → 列出所有 Agent
├── attach [url]        → 附加到远程后端
├── auth
│   ├── login           → 登录/配置 Provider API Key
│   ├── list / ls       → 列出已认证 Provider
│   └── logout          → 登出 Provider
├── github
│   ├── install         → 安装 GitHub Agent
│   └── run             → 运行 GitHub Agent
├── mcp
│   ├── add             → 添加 MCP 服务器
│   ├── list / ls       → 列出 MCP 服务器
│   ├── auth [name]     → MCP OAuth 认证
│   │   └── list / ls   → 列出 OAuth 状态
│   ├── logout [name]   → 移除 MCP OAuth 凭据
│   └── debug <name>    → 调试 MCP OAuth
├── models [provider]   → 列出可用模型
├── run [message..]     → 非交互式运行
├── serve               → 启动无头 API 服务器
├── session
│   └── list            → 列出所有会话
├── stats               → 查看使用统计
├── export [sessionID]  → 导出会话 JSON
├── import <file>       → 导入会话
├── web                 → 启动 Web 界面
├── acp                 → 启动 ACP 服务器
├── uninstall           → 卸载 OpenCode
└── upgrade [target]    → 升级 OpenCode

一、基础环境配置

1. Shell 安装

Windows：推荐安装 PowerShell

Linux / macOS

2. 运行时安装

3. 开发必备工具

4. 换源

npm 换源

pip 换源

二、安装 opencode

三、安装 oh-my-opencode（现 oh-my-openagent）

四、oh-my-opencode（现 oh-my-openagent）使用

五、opencode 基本使用方法

六、oh-my-opencode（现 oh-my-openagent）基本使用方法

七、OMO 配置快速上手指南

1. 配置文件在哪？

2. 核心概念：Agents 和 Categories

什么是 Agent？

什么是 Category？

3. 配置的核心原则

3.1 模型选择原则

3.2 Agent 推荐配置

3.3 安全覆盖 vs 危险覆盖

4. 实际配置示例

我的配置（参考）

配置思路

推荐订阅组合

5. 常见问题

Q：不配置会怎样？

Q：variant 是什么？

Q：fallback_models 是什么？

Q：怎么知道有哪些模型可用？

6. 快速参考

四个主 Agent 的 Tab 快速选择建议

八、个人使用心得

1. 新手入门操作建议

2. 学会在合适的时候切换 Agent

3. 焚决：强制更新 OMO 插件版本

Windows

Linux / macOS

4. 扩展复用

4.1 Skills 生态

4.2 MCP

4.3 插件生态

九、OMO 插件内置命令参考

1. 所有 / 斜杠命令一览

2. 内置命令（Built-in Commands）— 8 个

详细解析

1）/init-deep —— 初始化分层知识库

2）/ralph-loop —— 自引用开发循环

3）/ulw-loop —— Ultrawork 极限模式循环

4）/cancel-ralph —— 取消 Ralph Loop

5）/refactor —— 智能重构

6）/start-work —— 启动工作会话

7）/stop-continuation —— 停止所有延续机制

8）/handoff —— 会话交接

3. 项目自定义命令（Project Custom Commands）— 4 个

详细解析

9）/publish —— npm 发布管理器

10）/omomomo —— 彩蛋命令 🥚✨

11）/remove-deadcode —— 智能死代码清理

12）/get-unpublished-changes —— 查看未发布变更

4. Skill 触发的命令 — 6 个

详细解析

13）/git-master —— Git 大师

14）/playwright —— 浏览器自动化（MCP）

15）/playwright-cli —— 浏览器自动化（CLI）

16）/agent-browser —— Agent Browser

17）/dev-browser —— 开发浏览器

18）/frontend-ui-ux —— 前端 UI/UX 专家

命令加载位置（优先级从高到低）

十、opencode 自带内置命令参考

1. 全部内置斜杠命令一览

2. 每个命令的详细解析

1）/connect

2）/compact（别名：/summarize）

3）/details

4）/editor

5）/exit（别名：/quit, /q）

6）/export

Q：`variant` 是什么？

Q：`fallback_models` 是什么？

四个主 Agent 的 `Tab` 快速选择建议

4.1 `Skills` 生态

1. 所有 `/` 斜杠命令一览

1）`/init-deep` —— 初始化分层知识库

2）`/ralph-loop` —— 自引用开发循环

3）`/ulw-loop` —— Ultrawork 极限模式循环

4）`/cancel-ralph` —— 取消 Ralph Loop

5）`/refactor` —— 智能重构

6）`/start-work` —— 启动工作会话

7）`/stop-continuation` —— 停止所有延续机制

8）`/handoff` —— 会话交接

9）`/publish` —— npm 发布管理器

10）`/omomomo` —— 彩蛋命令 🥚✨

11）`/remove-deadcode` —— 智能死代码清理

12）`/get-unpublished-changes` —— 查看未发布变更

13）`/git-master` —— Git 大师

14）`/playwright` —— 浏览器自动化（MCP）

15）`/playwright-cli` —— 浏览器自动化（CLI）

16）`/agent-browser` —— Agent Browser

17）`/dev-browser` —— 开发浏览器

18）`/frontend-ui-ux` —— 前端 UI/UX 专家

1）`/connect`

2）`/compact`（别名：`/summarize`）

3）`/details`

4）`/editor`

5）`/exit`（别名：`/quit`, `/q`）

6）`/export`

7）`/help`

8）`/init`

9）`/models`

10）`/new`（别名：`/clear`）

11）`/redo`

12）`/sessions`（别名：`/resume`, `/continue`）

13）`/share`

14）`/themes`

15）`/thinking`

16）`/undo`

17）`/unshare`

2. `opencode [project]` —— 启动 TUI

3.1 `opencode agent [command]` —— 管理 Agent

3.2 `opencode attach [url]` —— 附加到远程服务器

3.3 `opencode auth [command]` —— 管理认证凭据

3.4 `opencode github [command]` —— 管理 GitHub Agent

3.5 `opencode mcp [command]` —— 管理 MCP 服务器

3.6 `opencode models [provider]` —— 列出可用模型

3.7 `opencode run [message..]` —— 非交互式运行

3.8 `opencode serve` —— 启动无头服务器

3.9 `opencode session [command]` —— 管理会话

3.10 `opencode stats` —— 查看使用统计

3.11 `opencode export [sessionID]` —— 导出会话

3.12 `opencode import <file>` —— 导入会话

3.13 `opencode web` —— 启动 Web 界面

3.14 `opencode acp` —— 启动 ACP 服务器

3.15 `opencode uninstall` —— 卸载 OpenCode

3.16 `opencode upgrade [target]` —— 升级 OpenCode