08-OpenCode 独有技巧

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

一、OpenCode 特色功能

1.1 多界面模式

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

界面 启动方式 适用场景
TUI（终端界面） opencode 日常开发，交互式对话
CLI（命令行） opencode run "消息" 脚本自动化，快速查询
Web opencode web 远程访问，浏览器操作
IDE 扩展 安装对应插件 在编辑器内使用
桌面应用 下载桌面版 独立窗口体验

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 命令选项

选项 说明
template 发送给 LLM 的提示词（必需）
description TUI 中显示的操作描述
agent 指定执行该命令的 Agent
model 为该命令指定默认模型
subtask 强制以子 Agent 方式执行

四、会话管理

4.1 会话操作

命令 快捷键 说明
/new ctrl+x n 新建会话（别名 /clear）
/sessions ctrl+x l 列出并切换会话（别名 /resume, /continue）
/compact ctrl+x c 压缩当前会话上下文（别名 /summarize）
/export ctrl+x x 导出当前会话为 Markdown

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 --continue
opencode -c

# 指定会话 ID
opencode --session <id>
opencode -s <id>

# 列出所有会话
opencode session list
opencode session list -n 5        # 最近 5 个
opencode session list --format json

# Fork 会话
opencode --continue --fork

# 查看统计信息
opencode stats
opencode stats --days 7           # 最近 7 天
opencode stats --models 5         # 显示前 5 个模型使用情况

五、模型切换

5.1 快速切换

操作 快捷键 说明
列出模型 /models 或 ctrl+x m 显示可用模型列表
切换变体 ctrl+t 在当前模型的不同变体间循环
最近模型 F2 在最近使用的模型间循环
最近模型（反向） Shift+F2 反向循环

5.2 启动时指定模型

opencode --model anthropic/claude-sonnet-4-20250514
opencode -m openai/gpt-4o

opencode run "解释闭包" --model anthropic/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"
}
模式 说明
"manual" 默认，手动分享
"auto" 自动分享所有新对话
"disabled" 完全禁用分享

6.4 自动分享

# 环境变量方式
export OPENCODE_AUTO_SHARE=true

# 或在 opencode.json 中设置 "share": "auto"

6.5 CLI 分享

# 运行时分享
opencode run "消息" --share

# 导出会话
opencode export <sessionID>

# 导入会话
opencode import session.json
opencode import https://opncd.ai/s/abc123

七、快捷键系统

7.1 Leader 键

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

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

7.2 常用快捷键

功能 快捷键 说明
新建会话 ctrl+x n 开始新对话
会话列表 ctrl+x l 列出并切换会话
压缩上下文 ctrl+x c 压缩历史节省 token
撤销 ctrl+x u 撤销最后一条消息
重做 ctrl+x r 重做撤销的操作
模型列表 ctrl+x m 列出可用模型
主题列表 ctrl+x t 列出可用主题
帮助 ctrl+x h 显示帮助对话框
外部编辑器 ctrl+x e 打开外部编辑器编写消息
导出会话 ctrl+x x 导出为 Markdown
工具详情 ctrl+x d 切换工具执行详情显示
初始化项目 ctrl+x i 创建/更新 AGENTS.md
退出 ctrl+x q 退出 OpenCode

7.3 导航快捷键

功能 快捷键 说明
上一页 PageUp / ctrl+alt+b 向上翻页
下一页 PageDown / ctrl+alt+f 向下翻页
到顶部 ctrl+g / Home 跳到第一条消息
到底部 ctrl+alt+g / End 跳到最后一条消息
复制消息 ctrl+x y 复制当前消息内容
隐藏/显示提示 ctrl+x h 切换提示可见性

7.4 自定义快捷键

在 tui.json 中自定义：

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

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

7.5 输入编辑快捷键

快捷键 操作
ctrl+a 移到行首
ctrl+e 移到行尾
ctrl+b / 左箭头 后退一个字符
ctrl+f / 右箭头 前进一个字符
alt+b / alt+左箭头 后退一个单词
alt+f / alt+右箭头 前进一个单词
ctrl+w / ctrl+backspace 删除前一个单词
alt+d / alt+delete 删除后一个单词
ctrl+k 删除到行尾
ctrl+u 删除到行首
ctrl+d / delete 删除光标处字符
ctrl+- / super+z 撤销输入
ctrl+. / super+shift+z 重做输入
ctrl+c 清空输入框
shift+return 换行

八、主题与界面

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
}
选项 说明
theme 设置主题
scroll_speed 滚动速度（默认 3）
scroll_acceleration.enabled 启用 macOS 风格滚动加速
diff_style "auto" 自适应终端宽度，"stacked" 单列布局
mouse 启用/禁用鼠标捕获

九、CLI 进阶

9.1 非交互模式运行

# 快速查询
opencode run "解释 JavaScript 中的闭包"

# 多行消息
opencode run "分析项目结构" "给出架构建议"

# 附加文件
opencode run "审查这个组件" -f src/components/Button.tsx

# JSON 格式输出（适合脚本解析）
opencode run "列出所有 API 端点" --format json

9.2 附加到运行中的服务

# 终端 1：启动无头服务
opencode serve --port 4096

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

9.3 Web 界面

opencode web                  # 启动 Web 服务并打开浏览器
opencode web --port 4096      # 指定端口
opencode web --hostname 0.0.0.0  # 允许远程访问

设置密码保护：

export OPENCODE_SERVER_PASSWORD=yourpassword
opencode web

9.4 远程附加

# 远程机器上启动后端
opencode web --port 4096 --hostname 0.0.0.0

# 本地附加 TUI
opencode 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 --port 4096  # 或监听端口

9.6 统计信息

opencode stats                          # 显示 token 用量和费用
opencode stats --days 7                 # 最近 7 天
opencode stats --tools 10               # 显示前 10 个工具使用
opencode stats --models 5               # 显示前 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/macOS
export EDITOR="vim"
export EDITOR="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 环境变量

# 禁用自动压缩
export OPENCODE_DISABLE_AUTOCOMPACT=true

# 禁用模型获取
export OPENCODE_DISABLE_MODELS_FETCH=true

# 指定配置文件
export OPENCODE_CONFIG=/path/to/config.json

# 禁用 Claude Code 兼容读取
export OPENCODE_DISABLE_CLAUDE_CODE=true

# 启用实验性功能
export OPENCODE_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分钟

Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

Windows 本地部署 OpenClaw 教程｜快速搭建 AI 自动化智能体

avatar AtomGit开源社区
cover

OpenClaw 成语压缩 Token 实战，6 个文件节省 50% 成本的完整指南

avatar AtomGit开源社区
cover

OpenClaw（小龙虾）全平台下载安装指南：5分钟完成私有化AI智能体部署

avatar AtomGit开源社区