OpenCode 最佳实践：从”能用”到”真的好用”

我用 OpenCode 大半年了，踩过的坑比写过的代码还多。

一开始我以为 OpenCode 就是一个”更高级的 Copilot”——在终端里打字，它帮我写代码，完事。后来才发现，这东西的上限远比我想象得高，但前提是你得知道怎么用。

先说配置目录，OpenCode 的配置分两层：

全局配置：~/.config/opencode/ — 存放 opencode.json、自定义 agent、插件、命令等
项目配置：项目根目录的 .opencode/ — 存放项目专属的 agent、命令、AGENTS.md 等

项目配置会覆盖全局配置，适合团队共享。

这篇文章结合官方文档和实战经验，整理了我认为最重要的使用技巧。有些是血泪教训，有些是读文档才知道的隐藏功能。

一、AGENTS.MD：最被低估的功能

如果你只记住这篇文章的一件事，就记这个：写好你的 AGENTS.md。

AGENTS.md 是 OpenCode 在每次对话开始时自动读取的指令文件。它就像你给一个新同事写的 onboarding doc——你希望他知道什么，你就写什么。

很多人不写 AGENTS.md，或者随便写两行。结果就是每次对话都要从头解释项目结构、编码规范、技术栈选择。这就像每天早上都要重新给同事介绍一遍公司。

一个好的 AGENTS.md 应该包含什么

有几个关键原则：

第一，写 OpenCode 从代码里读不出来的东西。 项目的”为什么”比”是什么”更重要。你不需要解释 Vue 怎么用，但你需要告诉它”我们选 Uniapp 是因为团队统一了这个规范”。

第二，控制在 200 行以内。 太长的指令文件会导致模型忽略规则。用 markdown 标题和列表，保持可扫描性。

第三，不要放频繁变化的内容。 详细的 API 文档、逐文件描述这些东西不适合放在 AGENTS.md 里。放链接就好。

用 `/init` 自动生成

OpenCode 提供了一个贴心的命令：

/init

它会自动分析你的项目，生成一份 AGENTS.md 初稿。虽然通常需要手动调整，但比从零开始快得多。

二、提示词的质量决定产出的质量

这听起来像废话，但我见过太多人这样用 OpenCode：

“帮我写一个登录功能”

然后对着生成的一大坨代码发愁——这不是我想要的啊。

好的指令应该包含三个要素：目标、约束、上下文。

差的指令 vs 好的指令

❌ 差：”给用户列表加个搜索功能”

✅ 好：”在 @src/pages/UserList.tsx 的表格上方加一个搜索框。搜索走后端 API /api/users?search=xxx，不要前端过滤。用 debounce 300ms，样式和现有的 Filter 组件保持一致。”

区别在哪？好的指令减少了歧义。OpenCode 不需要猜你要前端搜索还是后端搜索，不需要猜 debounce 时间，不需要猜样式规范。

官方推荐的提示技巧

1. 用 @ 引用具体文件

OpenCode 支持用 @文件路径 直接把文件内容拉进上下文。比起说”那个认证相关的代码”，直接写 @src/auth/login.ts 精确得多。

2. 贴截图和图片

把图片拖进终端，OpenCode 可以扫描并理解。调试 UI 问题时，贴一张”现在长这样”和”我想要这样”的截图，比文字描述有效十倍。

3. 给验证标准

不要只说”帮我修这个 bug”，而是：

“修复登录超时后无法重新认证的问题。修复后，用户在 token 过期后点击任意按钮应该自动跳转到登录页。测试用例在 @tests/auth.test.ts 里，修完后跑一下确认通过。”

给 OpenCode 一个可以自我验证的标准——测试用例、截图、预期输出——它就能自己检查工作质量。

4. 明确”不要做”的事

OpenCode 有时候会过度热心——你让它修一个 bug，它顺手把周围的代码也重构了。明确说”只改这个函数，不要动其他代码”，能省很多事。

三、Build/Plan 模式：先想清楚，再动手

OpenCode 有两种主要模式，用 Tab 键切换。

Build 模式（默认）

完整能力，可以读写文件、执行命令、做任何修改。这是日常开发的主力。

Plan 模式

只读模式。OpenCode 只能读取文件、搜索代码，不能做任何修改。

它会探索代码库，分析你的需求，然后给出一个详细的实现计划。

什么时候用 Plan 模式？

复杂功能的架构设计
检查 OpenCode 是否理解了你的意图
让它先列出所有需要改的文件，你确认后再动手

什么时候不用？

改一个变量名
修一个明显的 typo
加一行日志

判断标准：如果这个任务的实现方式只有一种，直接 Build。如果有多种选择，先 Plan。

四、Subagent：OpenCode 的分身术

Subagent 是 OpenCode 的一个强大机制——它可以启动独立的 AI 进程来并行处理任务，每个 Subagent 有自己的上下文窗口，不会污染你的主对话。

内置的 Subagent

类型	能力	用途
General	完整能力	复杂的多步骤任务
Explore	只读，快速搜索	探索、找文件、找定义

Subagent 最大的价值：隔离上下文

当你让 OpenCode 跑测试、分析日志、搜索大量文件时，这些操作会产生海量输出，塞满你的上下文窗口。

用 Subagent 来做这些事，输出留在 Subagent 的上下文里，只有摘要返回给你。

比如：

“@general 跑一下全量测试，把失败的用例列出来”

“@explore 搜索所有使用了 deprecated API 的文件”

自定义 Agent

你可以在以下位置创建自定义 agent：

全局：~/.config/opencode/agents/ — 所有项目可用
项目级：项目根目录的 .opencode/agents/ — 仅当前项目可用

Primary Agent 示例（日常开发助手）：

# ~/.config/opencode/agents/frontend.md 或 .opencode/agents/frontend.md
---
description: Frontend development agent
mode: primary
model: anthropic/claude-sonnet-4-20250514
---
You are a frontend specialist. Focus on:
- Vue/Uniapp best practices
- Component architecture
- Performance optimization

Subagent 示例（代码审查）：

# ~/.config/opencode/agents/review.md 或 .opencode/agents/review.md
---
description: Code review agent
mode: subagent
permission:
  edit: deny
  bash:
    "git diff": allow
    "git log*": allow
---
You are a code reviewer. Focus on:
- Code quality and best practices
- Potential bugs and edge cases
- Performance implications

Subagent 示例（安全审计）：

# ~/.config/opencode/agents/security.md 或 .opencode/agents/security.md
---
description: Security audit agent
mode: subagent
permission:
  edit: deny
  bash:
    "npm audit": allow
---
You are a security expert. Focus on identifying:
- Input validation vulnerabilities
- Authentication flaws
- Dependency vulnerabilities

然后用 @security 或 @review 调用它。

五、上下文管理：最容易被忽视的关键

OpenCode 的上下文窗口虽然大，但它不是无限的，而且上下文管理直接决定了输出质量。

自动压缩

默认开启。当上下文接近模型限制时，OpenCode 会自动压缩对话历史，保留关键信息。

配置在 ~/.config/opencode/opencode.json：

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

手动压缩

如果对话变长但还没触发自动压缩，你可以手动触发：

/compact

Snapshot 系统

OpenCode 会追踪文件变更，你可以随时撤销：

/undo    # 撤销上一步改动
/redo    # 重做

这比 Git 更轻量，适合快速迭代和回退。

六、权限管理：安全和效率的平衡

OpenCode 提供了细粒度的权限控制，配置在 ~/.config/opencode/opencode.json：

{
  "permission": {
    "edit": "ask",
    "bash": "ask",
    "webfetch": "allow"
  }
}

三种模式：

allow — 允许，不询问
ask — 每次询问
deny — 禁用

按 Agent 配置权限

你可以为不同的 agent 设置不同的权限：

{
  "agent": {
    "build": {
      "permission": {
        "edit": "allow",
        "bash": "ask"
      }
    },
    "plan": {
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

按 Bash 命令配置

甚至可以针对具体的命令：

{
  "permission": {
    "bash": {
      "git push": "ask",
      "npm install": "allow",
      "rm -rf": "deny"
    }
  }
}

七、Plugins：让规则变成铁律

AGENTS.md 里的指令是”建议”——OpenCode 大部分时候会遵守，但偶尔会忘。

Plugins 是”铁律”——无论如何都会执行。

Plugins 可以订阅各种事件钩子，在特定时机自动执行代码。

插件存放位置：

全局：~/.config/opencode/plugins/
项目级：项目根目录的 .opencode/plugins/

关键事件类型

事件	用途
`tool.execute.before`	工具执行前拦截或修改
`tool.execute.after`	工具执行后处理
`session.idle`	会话完成时
`file.edited`	文件被编辑时
`session.compacted`	上下文压缩时

实用示例

保护敏感文件：

// ~/.config/opencode/plugins/env-protection.js 或 .opencode/plugins/env-protection.js
export const EnvProtection = async () => {
  return {
    "tool.execute.before": async (input, output) => {
      if (input.tool === "read" && output.args.filePath.includes(".env")) {
        throw new Error("Do not read .env files")
      }
    }
  }
}

自动通知：

export const NotificationPlugin = async ({ $ }) => {
  return {
    "session.idle": async () => {
      await $`osascript -e 'display notification "Done!" with title "OpenCode"'`
    }
  }
}

压缩时注入关键信息：

export const CompactionPlugin = async () => {
  return {
    "experimental.session.compacting": async (input, output) => {
      output.context.push(`
## Must Remember
- Current task: implementing auth flow
- Key decision: using JWT, not sessions
      `)
    }
  }
}

八、Git 工作流：信任但要验证

OpenCode 能执行 Git 命令，这是一把双刃剑。

几个 Git 铁律

1. 永远不要让 OpenCode 自动 push

它可以 commit，但 push 这个动作应该由你来确认。一旦 push 到远端，回退成本就大了。

2. 频繁 commit

做完一个小功能就 commit。用 /undo 可以回退，但前提是你要有 checkpoint。

3. 警惕破坏性操作

如果 OpenCode 要执行 git reset --hard、git push --force、rm -rf，一定要在脑子里过一遍后果再批准。

你可以在权限里直接 deny 掉这些命令：

{
  "permission": {
    "bash": {
      "git push --force*": "deny",
      "git reset --hard": "deny"
    }
  }
}

九、快捷键和命令速查

OpenCode 使用 leader key 机制，默认是 Ctrl+X。大多数快捷键需要先按 leader，再按具体键。

最常用的快捷键

快捷键	功能
`Tab`	切换 Build/Plan 模式
`Ctrl+P`	命令面板
`Ctrl+X, N`	新建会话
`Ctrl+X, L`	会话列表
`Ctrl+X, M`	切换模型
`Ctrl+X, C`	压缩会话
`Ctrl+X, S`	状态视图

最常用的斜杠命令

命令	功能
`/init`	初始化项目，生成 AGENTS.md
`/undo`	撤销上一步改动
`/redo`	重做
`/share`	分享对话链接
`/compact`	手动压缩上下文

自定义命令

命令存放位置：

全局：~/.config/opencode/commands/
项目级：项目根目录的 .opencode/commands/

创建 ~/.config/opencode/commands/test.md 或 .opencode/commands/test.md：

---
description: Run tests with coverage
agent: build
---
Run the full test suite with coverage report.
Focus on failing tests and suggest fixes.
!`npm test`

然后用 /test 调用。

十、Extended Thinking：让 OpenCode 想深一点

对于复杂问题，你可以开启 Extended Thinking 模式，让 OpenCode 在回答前花更多时间推理。

怎么用

在 ~/.config/opencode/opencode.json 的 agent 配置里设置：

{
  "agent": {
    "deep-thinker": {
      "description": "High reasoning effort for complex problems",
      "model": "openai/gpt-5",
      "reasoningEffort": "high"
    }
  }
}

什么时候该用

复杂的架构决策
棘手的 debug（多个可能原因需要排除）
多步骤的重构方案设计
权衡多个方案的利弊

什么时候不需要

简单的代码修改
格式化、重命名
已经很明确的 bug 修复

十一、MCP Server：让 OpenCode 连接外部世界

MCP（Model Context Protocol）让 OpenCode 能和外部工具通信——GitHub、数据库、Slack、Notion 等等。

在 ~/.config/opencode/opencode.json 中配置：

{
  "mcp": {
    "github": {
      "type": "stdio",
      "command": "mcp-server-github"
    },
    "postgres": {
      "type": "stdio",
      "command": "mcp-server-postgres",
      "env": ["DATABASE_URL"]
    }
  }
}

注意上下文开销

每个 MCP server 会额外消耗上下文空间。不要贪多，常用的 2-3 个就够了。

十二、IDE 集成：不只是终端

OpenCode 不只是终端工具，它还有：

桌面应用 — 独立的 GUI 客户端
IDE 扩展 — 在 VS Code、JetBrains 里直接使用

如果你更喜欢在 IDE 里工作，不用强迫自己切到终端。

十三、审查代码：信任但要验证

OpenCode 写的代码质量总体不错，但你不能盲目信任。

几个常见问题

1. 过度工程

你让它写一个简单的工具函数，它给你搞出一个完整的抽象层。解决方法：在 AGENTS.md 里写上”优先用简单方案”。

2. 幻觉 API

它有时候会用不存在的 API 或者过时的语法。解决方法：跑测试。

3. 改动范围膨胀

你让它改一个函数，它把整个文件都重构了。解决方法：明确说”只改 X，不要动其他代码”。

Writer/Reviewer 模式

官方推荐的一个高级模式：用两个独立的会话分别扮演”写代码”和”审查代码”的角色。

两个会话有独立的上下文，Reviewer 不受 Writer 的思路影响，能发现 Writer 的盲点。

十四、不要用 OpenCode 做的事

说了这么多”应该怎么做”，最后聊聊”不应该做什么”。

1. 不要让它做你完全不了解的事

如果你对 Kubernetes 一无所知，不要让 OpenCode 帮你写部署配置然后直接用。你无法审查你不懂的东西。

2. 不要在没有版本控制的环境下用

没有 Git 就没有回退的能力。OpenCode 的改动可能覆盖你的文件，没有版本控制就是裸奔。

3. 不要一口气扔一个巨大的任务

“把整个项目从 JavaScript 迁移到 TypeScript”

这种指令等于让 OpenCode 自由发挥。结果不可控。拆成小步骤，每一步确认后再做下一步。

4. 不要指望一次就完美

迭代是正常的。用 /undo 回退，用精确的反馈描述”哪里不对”。

总结

OpenCode 的核心使用哲学其实很简单：

它是一个极其能干的协作者，但不是自动驾驶。方向盘始终在你手里。

按重要性排序，我的建议是：

写好 AGENTS.md — 一次投入，每次对话都受益
给精确的指令 — 目标 + 约束 + 验证标准
用 Plan 模式 — 复杂任务先规划再动手
管理上下文 — /compact、subagent
控制权限 — deny 危险操作，ask 关键命令
频繁 commit — 保留回退能力

做到这些，OpenCode 能让你的效率翻好几倍。做不到，它只会更快地帮你制造混乱。

工具的价值，永远取决于使用它的人。

参考来源：

原文来自 Mr Panda (@PandaTalk8) 的 Claude Code 最佳实践文章
本文基于 OpenCode 官方文档改写，由 AI 辅助编写