OpenCode 使用指南

OpenCode 是一款运行在终端中的 AI 编程助手（Terminal User Interface），提供键盘驱动的编码体验。本指南基于 v1.18.1 整理。

关于插件依赖：本指南中部分进阶能力依赖以下插件，非 OpenCode 原生功能，已逐处标注：

• [oh-my-opencode-slim] — 提供 designer、fixer、librarian、oracle、observer 等 specialist agent 类型
• [superpowers] — 提供技能系统（skill 工具、brainstorming、systematic-debugging 等工作流模板）、subagent-driven-development、AGENTS.md 委托工作流等

目录

• 第一部分：高效工作方法论
  • Agent 分工机制
  • 上下文管理
  • 背景并行任务
  • 委托决策参考
  • 会话复用
  • 技能与工作流模板
  • 描述需求与验收标准
• 第二部分：快捷键与操作
  • 输入框操作
  • Leader 键体系
  • 全局快捷键
• 第三部分：命令系统
  • Slash 命令
  • TUI 快捷用法
• 第四部分：CLI 命令行
• 第五部分：配置与定制
  • tui.json 配置
  • 编辑器集成
• 第六部分：进阶功能
  • Agent 体系
  • 通知与声音

第一部分：高效工作方法论

掌握 OpenCode 的第一步不是背快捷键，而是理解它的工作机制。以下几点直接影响你每天的实际效率。

Agent 分工机制 [oh-my-opencode-slim]

⚠️ 本节介绍的 specialist agent 类型来自 oh-my-opencode-slim 插件。OpenCode 原生仅有 orcherstrator、explore、general 等基础 agent 类型。tab/shift+tab 切换 agent 是内置功能，但可用 agent 列表依赖插件配置。

调度者（orchestrator）本身不应该做所有事，而是把专业任务分发到更有针对性的 agent。

一个简单的判断原则：如果是单行修改或确认性问题，自己完成；否则，委托出去。

上下文管理

LLM 的上下文窗口是有限且昂贵的资源。每一条消息都在消耗 token，而 token 直接影响成本和响应质量。

• 不要让调度者直接读取大文件。用 @explorer 搜索特定行或模式，它读完只返回摘要。
• 一个消息只问一个核心问题。把多个问题拆分，逐个处理，比挤在一轮里结果更好。
• 复杂需求先写计划、达成共识、再执行。不要在方向模糊时就开始写代码。

背景并行任务

这是最能提升效率的技巧：把没有依赖关系的任务同时发给不同 agent，而不是串行等待。

❌ 低效模式：
  调度者搜文件 → 找到 → 调查文档 → 查到 → 开始改

✅ 高效模式：
  调度者同时发起：
  ├── @explorer 搜索接口定义  ───┐
  └── @librarian 查阅库文档     ──┤
        两者完成后 ←──────────────┘
  调度者整合结果，规划修改方案

判断标准：如果两个任务之间没有依赖关系，就应该并行执行。

委托决策参考 [oh-my-opencode-slim]

下面这张对照表总结了最常见的“自己动手”误区：

会话复用

多次委托同一个 agent 时，传入 task_id 可以复用该 agent 之前的会话上下文。这避免了每一次都重新理解项目和环境，显著降低 token 开销。这是 OpenCode 内置的 task 工具功能。

技能与工作流模板 [superpowers]

⚠️ 技能系统（skill 工具及所有技能文件）来自 superpowers 插件。未安装时，OpenCode 不提供这些工作流模板。

OpenCode 的技能系统为常见工作场景提供了预置流程。有对应技能时优先加载，它提供了完整的工作清单。下表列出最常用的几个：

描述需求与验收标准

指令的清晰度直接决定输出质量：

❌ 模糊指令：
  "把这个页面改好看点"

✅ 明确指令：
  "把按钮间距从 8px 改为 16px，
   卡片圆角改为 12px，
   标题字号加大到 20px"

给出明确的验收条件后，agent 可以自主迭代到目标，无需反复确认。

如果发现某些指令反复出现，可以考虑将它们写入项目的 CLAUDE.md 或 AGENTS.md 规则文件，例如：“本项目使用 pnpm，不要用 npm”、“修改之前先跑一遍现有测试”。

第二部分：快捷键与操作

OpenCode 的交互主要靠键盘。熟悉以下快捷键后，手不用离开键盘就能完成多数操作。

输入框操作

输入框遵循 Readline/Emacs 编辑风格。最值得记住的是清空输入框（ctrl+c）和快速删除整行（ctrl+shift+d）。

光标移动

文本删除

编辑与历史

提交与换行

部分终端默认不发送 shift+enter，需要在终端设置中额外配置。

Leader 键体系

OpenCode 使用 Leader 键 避免快捷键与终端冲突。默认 Leader 键为 ctrl+x，操作方式是：先按下 ctrl+x 然后松开，再按第二个键。Leader 键的等待超时默认为 2000 毫秒，可在配置中调整。

以下是完整的 Leader 键映射：

全局快捷键

以下快捷键无需 Leader 键，在 TUI 的任何位置都可以直接使用：

消息区导航：

子会话导航（当 agent 产生子会话时）：

第三部分：命令系统

Slash 命令

在输入框直接键入 / 加命令名即可执行。多数 Slash 命令都有对应的 Leader 键快捷键。

TUI 快捷用法

除了快捷键和命令之外，输入框还支持两种特殊前缀：

@ 还支持引用配置好的 references（参考目录），用法为 @别名/。

第四部分：CLI 命令行

除了 TUI，OpenCode 也提供了完整的命令行接口，适合脚本化、自动化或快速操作。

启动与运行

# 基本启动
opencode                  # 在当前目录打开 TUI
opencode /path/to/project # 在指定目录打开 TUI

# 会话恢复
opencode -c               # 继续上一次的会话
opencode -s <sessionID>   # 恢复指定会话
opencode --fork            # 派生会话（配合 -c 或 -s）

# 指定模型和 Agent
opencode -m openai/gpt-4   # 指定模型启动
opencode --agent explorer  # 指定 Agent 启动
opencode --prompt "..."    # 指定初始提示词

# 特殊模式
opencode --mini            # 极简界面
opencode --auto            # 自动批准权限（⚠️ 高风险）
opencode --pure            # 不加载插件，干净启动
opencode --no-replay       # 禁用历史回放
opencode --replay-limit 10 # 限制回放的消息数量
opencode --log-level DEBUG --print-logs  # 调试模式

# 单次运行
opencode run "分析这个项目的架构"  # 执行一次后退出

会话管理

opencode session list              # 列出所有会话
opencode session delete <sessionID> # 删除指定会话
opencode export <sessionID>         # 导出为 JSON
opencode import <file>              # 从 JSON 或 URL 导入会话

模型与用量

opencode models            # 列出所有可用模型
opencode models openai     # 列出指定 Provider 的模型
opencode stats             # 查看 token 用量和费用
opencode providers         # 管理 Provider 和 API 凭证

调试工具

opencode debug config      # 查看最终合并的配置
opencode debug info        # 版本、系统、插件信息
opencode debug paths       # 全局路径（data/config/cache/state）
opencode debug skill       # 列出所有可用技能
opencode debug agent fixer # 查看指定 agent 的配置
opencode debug startup     # 启动耗时分析

插件与其他

opencode plugin oh-my-opencode-slim   # 安装插件
opencode plugin oh-my-opencode-slim -g # 全局安装
opencode plugin <pkg> -f              # 强制替换已有版本
opencode completion                   # 生成 shell 自动补全脚本
opencode upgrade                      # 升级到最新版
opencode upgrade 1.18.0               # 升级到指定版本
opencode uninstall                    # 卸载并清理
opencode serve                        # 启动 headless 服务器
opencode web                          # 启动服务器并打开 Web 界面
opencode mcp                          # 管理 MCP 服务器
opencode pr 42                        # 拉 GitHub PR 分支并启动

启动选项（服务器模式）

第五部分：配置与定制

tui.json 配置

TUI 的界面行为通过 ~/.config/opencode/tui.json 控制（也支持 .jsonc 格式）。这个文件独立于 opencode.json（后者控制运行时行为）。keybinds 字段与内置默认值合并，这意味着只需写你要改的项。

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "opencode",
  "leader_timeout": 2000,
  "keybinds": {
    "leader": "ctrl+x"
  },
  "scroll_speed": 3,
  "scroll_acceleration": {
    "enabled": true
  },
  "diff_style": "auto",
  "mouse": true,
  "attention": {
    "enabled": true,
    "notifications": true,
    "sound": true,
    "volume": 0.4,
    "sound_pack": "opencode.default",
    "sounds": {
      "error": "./sounds/error.mp3"
    }
  }
}

各配置项说明

外观

快捷键

滚动

通知与声音

快捷键绑定语法

{
  "keybinds": {
    "action_name": "ctrl+k",
    "multi_keys": "ctrl+a,ctrl+b",
    "array_keys": ["ctrl+a", "ctrl+b"],
    "disable_key": "none",
    "advanced": {
      "key": "ctrl+v",
      "preventDefault": false
    }
  }
}

• 绑定值可以是字符串（支持逗号分隔多键）、数组或对象（高级用法）
• 设 "none" 或 false 可禁用某个快捷键
• <leader> 指代当前 Leader 键
• macOS 上用 super 表示 Cmd 键
• 可通过环境变量 OPENCODE_TUI_CONFIG 指定自定义配置文件路径

命令面板中的隐藏设置

通过 ctrl+p 打开命令面板后，可以搜索并切换一些界面设置，这些设置会自动持久化：

• 搜索 username 或 hide username：切换聊天消息中用户名的显示

编辑器集成

ctrl+x e（外部编辑）和 ctrl+x x（导出）会调用系统配置的 EDITOR。在 ~/.zshrc 或 ~/.bashrc 中添加：

export EDITOR="code --wait"   # VS Code
export EDITOR="nvim"          # Neovim
export EDITOR="vim"           # Vim
export EDITOR="nano"          # Nano
export EDITOR="subl --wait"   # Sublime Text

GUI 编辑器需要 --wait 参数，表示进程会一直阻塞直到窗口关闭。

第六部分：进阶功能

Agent 体系 [oh-my-opencode-slim]

⚠️ orchestrator 是 OpenCode 原生 agent；explorer、librarian、fixer、oracle、designer、observer 由 oh-my-opencode-slim 插件提供；councillor 由 superpowers 插件提供。tab/shift+tab 切换 agent 是内置功能，但可用列表依赖插件配置。

通知与声音

当 attention.enabled 设为 true 后：

• 声音提醒：所有内置事件（完成、报错、请求权限等）都会播放音效。
• 桌面通知：非子 agent 事件（权限请求、会话完成、错误）在终端失焦时会发送系统通知。
• 事件类型：default、question、permission、error、done、subagent_done，每种事件的音效均可单独覆盖。