08-OpenCode 独有技巧

08-OpenCode 独有技巧

掌握 OpenCode 特有的高级功能和进阶使用技巧，提升开发效率。

一、OpenCode 特色功能

1.1 多界面模式

OpenCode 提供多种使用界面，适应不同场景：

1.2 独有特性

• TUI 终端界面：专为终端设计的交互式界面，支持快捷键、主题、会话管理
• @ 文件引用：在对话中用@模糊搜索并引用项目文件
• ! Shell 命令：在消息前加!直接执行 Shell 命令
• 自定义命令系统：通过.opencode/commands/*.md创建可复用的斜杠命令
• Git 驱动的撤销/重做：/undo和/redo基于 Git 管理文件变更
• 会话分享：/share生成公开链接，与团队分享对话
• Plan/Build 模式切换：用 Tab 键在规划模式和构建模式间切换
• 子 Agent 会话：支持子 Agent 独立执行任务，不污染主上下文

二、TUI 交互技巧

2.1 文件引用（@）

在对话中使用@引用文件，OpenCode 会进行模糊搜索并自动将文件内容加入上下文：

@packages/functions/src/api/index.ts 中的认证逻辑是如何实现的？ 对比 @src/models/User.ts 和 @src/models/Post.ts 的结构差异 参考 @src/components/Button.tsx 的设计风格，创建一个新的 Input 组件

2.2 Shell 命令（!）

在消息前加!可直接执行 Shell 命令，输出自动作为工具结果返回：

!ls -la !npm test !git log --oneline -5

2.3 Plan/Build 模式切换

OpenCode 支持两种工作模式，用Tab键切换：

# Plan 模式（右下角显示 Plan） - AI 只做规划，不修改文件 - 适合复杂功能，先讨论方案再动手 # Build 模式（右下角显示 Build） - AI 直接修改文件 - 适合明确的、具体的任务

使用流程：

1. 按 Tab 切换到 Plan 模式
2. 描述需求，让 AI 生成实现计划
3. 审查并迭代计划
4. 按 Tab 切回 Build 模式
5. 让 AI 执行计划

2.4 思考过程可见性

对于支持扩展思考的模型，可以切换思考过程的可见性：

/thinking # 切换思考块显示/隐藏

注意：这只控制显示，不改变模型的推理能力。要切换模型变体，使用ctrl+t。

三、自定义命令系统

3.1 创建自定义命令

在.opencode/commands/目录下创建 Markdown 文件即可定义命令：

.opencode/commands/ ├── test.md # /test ├── review.md # /review ├── component.md # /component └── analyze-coverage.md # /analyze-coverage

3.2 命令格式

每个命令文件包含 YAML frontmatter 和 Markdown 内容：

--- description: 运行测试并分析覆盖率 agent: build model: anthropic/claude-sonnet-4-20250514 --- 运行完整测试套件并生成覆盖率报告。 关注失败的测试并建议修复方案。

3.3 参数化命令

使用$ARGUMENTS或位置参数$1,$2,$3：

--- description: 创建新的 React 组件 --- 创建一个名为 $ARGUMENTS 的 React 组件，包含 TypeScript 类型定义和基本结构。

使用：

/test Button

--- description: 创建文件 --- 在目录 $2 中创建名为 $1 的文件，内容如下：$3

使用：

/create-file config.json src '{"key": "value"}'

3.4 注入 Shell 输出

使用!`命令`将 Shell 命令输出注入到提示词中：

--- description: 审查最近的代码变更 --- 最近的 Git 提交记录： !`git log --oneline -10` 审查这些变更并提出改进建议。

3.5 引用文件

在命令中使用@文件名自动包含文件内容：

--- description: 审查组件代码 --- 审查 @src/components/Button.tsx 组件。 检查性能问题并提出改进建议。

3.6 JSON 配置方式

也可以在opencode.json中配置命令：

{"$schema":"https://opencode.ai/config.json","command":{"test":{"template":"运行测试套件并分析覆盖率，关注失败的测试。","description":"运行测试并分析覆盖率","agent":"build","model":"anthropic/claude-sonnet-4-20250514"}}}

3.7 命令选项

四、会话管理

4.1 会话操作

4.2 撤销/重做

OpenCode 的撤销/重做基于 Git，会同时回退文件变更：

/undo # ctrl+x u 撤销最后一条消息及其文件变更 /redo # ctrl+x r 重做之前撤销的操作

注意：项目需要是 Git 仓库才能使用此功能。

4.3 子 Agent 会话

OpenCode 支持子 Agent 独立执行任务：

• 子 Agent 在独立上下文中工作，不污染主会话
• 可以在命令配置中设置subtask: true强制以子 Agent 执行
• 使用方向键在父子会话间导航：
  • 上箭头：回到父会话
  • 下箭头：进入第一个子会话
  • 右箭头：切换到下一个子会话
  • 左箭头：切换到上一个子会话

4.4 CLI 会话管理

# 继续上次会话opencode--continueopencode-c# 指定会话 IDopencode--session<id>opencode-s<id># 列出所有会话opencode session list opencode session list-n5# 最近 5 个opencode session list--formatjson# Fork 会话opencode--continue--fork# 查看统计信息opencode stats opencode stats--days7# 最近 7 天opencode stats--models5# 显示前 5 个模型使用情况

五、模型切换

5.1 快速切换

5.2 启动时指定模型

opencode--modelanthropic/claude-sonnet-4-20250514 opencode-mopenai/gpt-4o opencode run"解释闭包"--modelanthropic/claude-sonnet-4-20250514

5.3 查看可用模型

opencode models# 列出所有模型opencode models anthropic# 只看 Anthropic 的模型opencode models--refresh# 刷新模型缓存opencode models--verbose# 显示详细信息（含价格）

六、会话分享

6.1 分享对话

/share # ctrl+x s 生成公开链接并复制到剪贴板

生成的链接格式：opncd.ai/s/<share-id>

6.2 取消分享

/unshare # 停止分享，删除公开链接和相关数据

6.3 分享模式配置

在opencode.json中配置：

{"$schema":"https://opencode.ai/config.json","share":"manual"}

6.4 自动分享

# 环境变量方式exportOPENCODE_AUTO_SHARE=true# 或在 opencode.json 中设置 "share": "auto"

6.5 CLI 分享

# 运行时分享opencode run"消息"--share# 导出会话opencodeexport<sessionID># 导入会话opencodeimportsession.json opencodeimporthttps://opncd.ai/s/abc123

七、快捷键系统

7.1 Leader 键

OpenCode 使用 leader 键机制避免终端快捷键冲突。默认 leader 键为ctrl+x。

使用方式：先按ctrl+x，再按对应功能键。

7.2 常用快捷键

7.3 导航快捷键

7.4 自定义快捷键

在tui.json中自定义：

{"$schema":"https://opencode.ai/tui.json","keybinds":{"leader":"ctrl+x","session_compact":"none"}}

设置为"none"可禁用某个快捷键。

7.5 输入编辑快捷键

八、主题与界面

8.1 切换主题

/themes # ctrl+x t 列出并切换主题

8.2 TUI 配置

在tui.json中配置界面行为：

{"$schema":"https://opencode.ai/tui.json","theme":"opencode","keybinds":{"leader":"ctrl+x"},"scroll_speed":3,"scroll_acceleration":{"enabled":true},"diff_style":"auto","mouse":true}

九、CLI 进阶

9.1 非交互模式运行

# 快速查询opencode run"解释 JavaScript 中的闭包"# 多行消息opencode run"分析项目结构""给出架构建议"# 附加文件opencode run"审查这个组件"-fsrc/components/Button.tsx# JSON 格式输出（适合脚本解析）opencode run"列出所有 API 端点"--formatjson

9.2 附加到运行中的服务

# 终端 1：启动无头服务opencode serve--port4096# 终端 2：附加到服务（避免 MCP 冷启动）opencode run--attachhttp://localhost:4096"解释异步编程"

9.3 Web 界面

opencode web# 启动 Web 服务并打开浏览器opencode web--port4096# 指定端口opencode web--hostname0.0.0.0# 允许远程访问

设置密码保护：

exportOPENCODE_SERVER_PASSWORD=yourpassword opencode web

9.4 远程附加

# 远程机器上启动后端opencode web--port4096--hostname0.0.0.0# 本地附加 TUIopencode attach http://10.20.30.40:4096 opencode attach http://10.20.30.40:4096--dir/path/to/project

9.5 ACP 协议

opencode acp# 启动 ACP 服务器（stdin/stdout 通信）opencode acp--port4096# 或监听端口

9.6 统计信息

opencode stats# 显示 token 用量和费用opencode stats--days7# 最近 7 天opencode stats--tools10# 显示前 10 个工具使用opencode stats--models5# 显示前 5 个模型opencode stats--project"my-project"# 按项目过滤

十、项目初始化

10.1 /init 命令

/init

引导式创建或更新AGENTS.md文件，OpenCode 会分析项目结构并生成适合的项目说明。

建议将AGENTS.md提交到 Git，帮助 OpenCode 理解项目结构和编码规范。

10.2 AGENTS.md 的作用

AGENTS.md是项目级的 AI 指令文件，告诉 OpenCode：

• 项目使用的技术栈和框架
• 代码风格和命名规范
• 项目目录结构
• 测试和构建流程
• 其他需要 AI 遵循的约定

十一、外部编辑器

11.1 打开外部编辑器

/editor # ctrl+x e 在外部编辑器中编写消息

使用EDITOR环境变量指定的编辑器。

11.2 配置编辑器

# Linux/macOSexportEDITOR="vim"exportEDITOR="code --wait"# Windows PowerShell$env:EDITOR="code --wait"

注意：VS Code 等 GUI 编辑器需要加--wait参数。

十二、实用技巧

12.1 压缩上下文

当对话过长、响应变慢时：

/compact # ctrl+x c 压缩会话上下文

OpenCode 会将历史对话压缩为摘要，节省 token 用量。

12.2 命令面板

ctrl+p # 打开命令面板，搜索所有可用命令

12.3 中断响应

escape # 中断正在生成的响应

12.4 环境变量

# 禁用自动压缩exportOPENCODE_DISABLE_AUTOCOMPACT=true# 禁用模型获取exportOPENCODE_DISABLE_MODELS_FETCH=true# 指定配置文件exportOPENCODE_CONFIG=/path/to/config.json# 禁用 Claude Code 兼容读取exportOPENCODE_DISABLE_CLAUDE_CODE=true# 启用实验性功能exportOPENCODE_EXPERIMENTAL=true

12.5 升级与卸载

# 升级到最新版本opencode upgrade# 升级到指定版本opencode upgrade v0.1.48# 卸载（保留配置）opencode uninstall --keep-config --keep-data# 卸载预览（不实际删除）opencode uninstall --dry-run

十三、下一步

掌握独有技巧后，建议学习：

1. 09-实战：PythonWebAPI开发.md - 完整项目实战
2. 10-多模型配置指南.md - 多模型配置
3. 11-项目规划测试代码审查实战.md - 全流程实战

文档版本: 2.0 | 建议学习时长: 30分钟