OpenCode + OhMyOpenCode 使用教程

快速开始（Quick Start）

1) 检查版本 / 路径

opencode --version

opencode debug paths

2) 配置文件入口（你这台机器）

3) 最小启动方式

# 进入项目目录（示例）
cd "D:\+宝\AI编程文件\opencode学习"

# 启动 TUI（默认命令）
opencode

基础用法（Basics）

启动模式速览

常用参数（以 opencode v1.1.48 为准）

会话管理（session/export/import）

# 列出会话
opencode session list

# 导出会话为 JSON（把 <sessionID> 替换成真实值）
opencode export <sessionID> > session.json

# 导入会话（支持 JSON 文件路径 或 share URL）
opencode import .\session.json

MCP（Model Context Protocol）

# 查看 MCP 列表及状态
opencode mcp list

# 添加 MCP server（交互式）
opencode mcp add

# OAuth 登录/退出
opencode mcp auth <name>
opencode mcp logout <name>

# 调试 OAuth
opencode mcp debug <name>

Auth（凭据管理）

opencode auth list
opencode auth login
opencode auth logout

进阶技巧（Advanced）

1) 多智能体心法：把你当“技术负责人”

2) “脚本化”工作：opencode run

# 发送一句话（非交互）
opencode run "在这个项目里搜索所有 TODO 并汇总"

# 指定 agent / model
opencode run --agent sisyphus --model openai/gpt-5.2 "给我一个修复方案，并说明验证步骤"

# 分享会话（用于复盘或跨设备导入）
opencode run --share "把本次对话整理成可复制的 checklist"

3) LSP / AST-grep：把“找改查”变成确定性

4) 会话复用与导出：把“好一次”变成“好很多次”

• 复用：--continue 或 --session 继续讨论（适合多天任务）。
• 导出：opencode export 将会话变成 JSON，便于归档、分享、审计。
• 导入：opencode import 把别人的经验迁移到你这里（或跨机器恢复）。

5) TUI 高收益小技巧（少打字，少跑偏）

Skills 使用技巧（Agent Skills）

Skill 的本质：把一套高质量工作流固化成可复用指令（通常以 /skill-name 的形式调用）。它是否可用，取决于你本机的 skills 目录与权限配置。

1) Skill 放哪里才会被发现？

2) SKILL.md 该怎么写（最小可用模板）

---
name: my-skill
description: When to use me (Recommended). Do X safely and repeatably.
---

Rules:
- Ask 1-2 clarifying questions only if blocked.
- Provide a verification step.

Workflow:
1) ...
2) ...

3) 实战心法：让模型“更愿意正确选 skill”

• 把 description 写得像“触发条件”：例如“浏览器交互必须用 Playwright”。描述越具体，越容易被正确匹配。
• Skill 不是魔法：它通常只是给智能体一段更严格的系统提示。真正的能力来自工具（例如 Playwright、git、LSP、MCP）。
• 权限要配对：例如你把 permission.edit 设为 deny，那么任何写文件的 skill 都会被限制。

4) 常见排错（Skill 没出现 / 不生效）

/ 指令命令列表（Slash Commands）

说明：/xxx 属于 OpenCode/OhMyOpenCode 的“快捷流程指令”。不同安装/配置下可用项可能略有差异，请以你实际环境为准。

@ 子智能体/代理列表（Subagents / Agents）

说明：@name 用来把一部分工作交给更合适的“专家”。你这套环境里还启用了 oh-my-opencode 的一组编排/顾问型智能体。

快捷键（Keyboard Shortcuts）

高频快捷键速查（默认值）

如何自定义快捷键（opencode.json）

你可以在 C:\Users\27072\.config\opencode\opencode.json 里添加/覆盖 keybinds 字段。

{
  "$schema": "https://opencode.ai/config.json",
  "keybinds": {
    "leader": "ctrl+x",
    "command_list": "ctrl+p",
    "agent_cycle": "tab",
    "variant_cycle": "ctrl+t"
  }
}

// %LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json
"actions": [
  {
    "command": { "action": "sendInput", "input": "\\u001b[13;2u" },
    "id": "User.sendInput.ShiftEnterCustom"
  }
],
"keybindings": [
  { "keys": "shift+enter", "id": "User.sendInput.ShiftEnterCustom" }
]

常见工作流示例（Playbooks）

1) 修一个 bug（最小修复 + 验证）

# 在 TUI 里：
@explore
“帮我定位 bug 相关代码：错误信息/函数名/关键词…（给出你知道的线索）”

@build
“按最小改动修复，并给出可运行的验证命令（测试/运行步骤）”

2) 加一个小功能（不确定范围时先 plan）

@plan
“我想加功能 X。请先问我 2-3 个关键问题，并输出一个可执行的工作计划（含验收步骤）。”

/start-work

3) 写文档/教程（你正在做的事）

@general
“基于本机 opencode 的 help 输出和配置文件，生成一份离线 HTML 教程（含 / 与 @ 列表、工作流示例）。”

4) 重构（用 /refactor 提升确定性）

/refactor <要重构的目标>

（如果遇到复杂 trade-off）
@oracle
“这个重构的风险点和最佳策略是什么？如何最小化破坏？”

5) 写测试（或补测试）

@explore
“找出项目当前测试框架/测试模式，并给我 2-3 个类似测试文件作为参考。”

@build
“新增/补齐测试：先写 failing test，再实现，再跑测试到全绿。”

6) 生成一个前端页面（避免 AI 模板化）

@frontend-design
“做一个单页 HTML（或 React 组件），要求：有明确视觉方向、排版有性格、配色不紫、带少量动效。”

7) 做一个 PR（如果你在 GitHub 项目里）

@build
“按仓库 commit 风格拆分原子提交，并用 gh 创建 PR（不要 force push）。
如果本地没装 gh，就告诉我安装/替代步骤。”

FAQ / 排错

Q1：为什么有时工具输出里出现 BunInstallFailedError？

• 先看日志文件：C:\Users\27072\.local\share\opencode\log\ 下对应时间戳的 .log。
• 用 opencode debug paths 确认路径是否符合预期。
• 确认插件配置：C:\Users\27072\.config\opencode\opencode.json 的 plugin 数组。

Q2：我怎么确认 oh-my-opencode 是否生效？

• 确认配置里已启用：C:\Users\27072\.config\opencode\opencode.json。
• 确认存在配置文件：C:\Users\27072\.config\opencode\oh-my-opencode.json。
• 在对话里尝试使用 /start-work、/refactor 或 @oracle 等（如果可用，会被识别）。

Q3：为什么本页没有列出所有 TUI 快捷键？

• 为了不误导：快捷键可能随版本变化，且 TUI/Web/Desktop 可能不同。
• 你把 TUI 里帮助面板的快捷键列表截图/抄一份给我，我可以把本页“快捷键表”补成最终版。

附录：CLI 命令速查（opencode v1.1.48）

以下来自你本机 opencode --help（只列顶层）。