技巧与窍门

充分发挥 OpenCode 潜力的实用技巧。这是一个持续更新的文档 — 随着发现更多有效的工作流，会不断添加新技巧。

高效提示词

具体而详细

像对团队中的初级开发者说话一样与 OpenCode 交流。提供足够的上下文：

❌ 修复认证 bug
✅ @src/pages/Login.tsx 中的登录页面在用户提交有效凭据时返回 401 错误。
   请检查 @src/api/auth.ts 中的认证处理程序并修复 token 验证逻辑。

使用 @ 文件引用

按 @ 模糊搜索文件。这会将文件内容包含在提示中，给 LLM 精确的上下文：

查看 @src/router/index.ts 中如何处理路由，并为仪表板页面添加新路由。

提供示例

请求新代码时，引用现有模式：

创建一个用户偏好的新 API 端点。遵循 @src/api/notes.ts 中用于
错误处理和响应格式的相同模式。

拖放图片

将图片直接拖入终端以提供视觉上下文：

• UI 原型作为设计参考
• Bug 截图
• 架构图
• 设计系统

工作流策略

先规划再构建

对于复杂功能，始终从 Plan 模式开始（按 Tab 切换）：

1. 规划 — 描述功能，审查 AI 的计划
2. 迭代 — 通过反馈完善计划
3. 构建 — 切换到 Build 模式并让它实施

这可以避免在不正确的实现上浪费时间。

积极使用撤销

不要犹豫使用 /undo，如果结果不对。这是工作流的核心部分：

/undo          # 恢复更改，显示原始提示
# 调整提示
/undo          # 需要时多次撤销
/redo          # 撤销过多时重做

分解大任务

不要用一个巨大的提示，将工作分解为较小的步骤：

第 1 步："为用户偏好创建数据库 Schema"
第 2 步："使用第 1 步的 Schema 添加 API 端点"
第 3 步："创建调用这些端点的前端设置页面"

多会话工作流

OpenCode 支持在同一项目上运行多个会话。用于并行任务：

• 会话 1：开发某个功能
• 会话 2：修复代码库其他部分的 Bug
• 会话 3：编写测试

上下文管理

保持上下文聚焦

LLM 的上下文窗口有限。通过以下方式优化：

• 使用 @ 引用特定文件，而不是描述它们
• 将长对话拆分为新会话
• 先使用 Plan 模式缩小需要更改的文件范围

上下文压缩

当对话变长时，OpenCode 可以自动压缩上下文：

{
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  }
}

• auto — 上下文满时自动压缩
• prune — 移除旧的工具输出以节省 token
• reserved — 压缩期间用于避免溢出的 token 缓冲区

使用指令文件

将 OpenCode 指向项目特定的指导文件：

{
  "instructions": [
    "CONTRIBUTING.md",
    "docs/coding-standards.md",
    ".cursor/rules/*.md"
  ]
}

这确保 AI 遵循你团队的约定。

权限控制

团队推荐设置

对于团队环境，要求批准破坏性操作：

{
  "permission": {
    "edit": "ask",
    "bash": "ask",
    "write": "ask",
    "read": "allow",
    "grep": "allow",
    "glob": "allow"
  }
}

锁定 MCP 服务器

使用通配符控制 MCP 服务器的所有工具：

{
  "permission": {
    "mymcp_*": "ask"
  }
}

本地模型技巧

选择合适的模型

• 小型快速任务：使用较小模型（Haiku、Gemma）进行快速问答
• 复杂编码：使用较大模型（Claude Sonnet/Opus、GPT-4）进行多文件更改
• 预算有限：使用 OpenCode Go 或通过 Ollama 运行本地模型

Ollama 性能优化

本地使用 Ollama 时：

• 将 num_ctx 增加到至少 16k–32k 以使工具调用正常工作
• 使用量化模型以获得更快的响应时间
• 确保有足够的 VRAM 用于模型大小

设置小模型

为轻量任务配置较便宜的模型：

{
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

项目组织

提交 AGENTS.md

运行 /init 后，将生成的 AGENTS.md 提交到仓库。这有助于 OpenCode 跨会话理解你的项目。

使用 .opencode 目录

组织项目特定的自定义内容：

.opencode/
├── agents/       # 项目特定的代理
├── commands/     # 项目特定的命令
├── skills/       # 项目特定的 skills
└── plugins/      # 项目特定的插件

分享有用的会话

解决棘手问题后，与团队分享会话：

/share

这会创建一个参考链接，其他人可以从中学习。

性能技巧

对大型仓库禁用快照

如果 OpenCode 在大型仓库上运行缓慢：

{
  "snapshot": false
}

注意：这会禁用撤销/重做功能。

配置文件监视器忽略

排除嘈杂的目录：

{
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

使用 .ignore 控制搜索范围

控制 grep 和 glob 等工具可以搜索的文件：

# .ignore
!node_modules/
!dist/

键盘快捷键

按键	操作
Tab	在 Build 和 Plan 模式之间切换
@	模糊搜索文件引用
/	打开命令菜单

在 tui.json 中自定义快捷键：

{
  "$schema": "https://opencode.ai/tui.json",
  "keybinds": {}
}

延伸阅读

• 官方文档
• Discord 社区 — 获取帮助和分享技巧
• GitHub Issues — 报告 Bug
• 更新日志 — 了解最新动态