OpenCode上手使用和进阶：从安装到Agent工作流

OpenCode 上手使用和进阶：从安装到 Agent 工作流

如果你已经用过 Cursor、Claude Code、Copilot 这类 AI 编程工具，再看 OpenCode，第一感受可能不是“更好上手”，而是“更开放”。

它不是一个被封装好的聊天窗口，而是一个运行在终端里的开源 AI 编程 Agent。你可以自己选择模型、配置工具权限、沉淀项目规则、调用不同 Agent，甚至把它扩展成一个小型的 AI 开发团队。

所以这篇文章不只讲“怎么装”，也讲“怎么真正用起来”。

我会按这个路径展开：

  1. OpenCode 是什么，适合谁
  2. Windows 环境下如何安装
  3. 第一次启动后应该做什么
  4. 日常开发中最常用的命令和输入方式
  5. AGENTS.md 为什么重要
  6. 如何理解主 Agent、子 Agent 和 oh-my-opencode
  7. 从新手到进阶的几套实际工作流

一、OpenCode 到底是什么？

OpenCode 是一个开源的 AI 编程 Agent，主要运行在终端中。

它和普通 AI 聊天工具最大的区别，不是“能不能写代码”，而是它更接近一个能接入项目、调用工具、修改文件、执行命令、维护上下文的开发协作者。

你可以把它理解成三层能力：

  • 第一层：终端里的 AI 编程助手，可以问问题、读代码、改文件。
  • 第二层：可配置的 Agent 框架，可以指定模型、权限、角色和项目规则。
  • 第三层：可编排的开发工作流，可以让不同 Agent 做搜索、规划、实现、审查、验证。

如果只想让 AI 偶尔补几行代码，Cursor 或 Copilot 可能已经够用。OpenCode 更适合下面这类人：

  • 习惯使用终端和 Git。
  • 想把 AI 接入真实项目，而不是只做问答。
  • 希望自己掌控模型、配置、权限和上下文。
  • 经常做代码审查、重构、Bug 分析、文档生成。
  • 想把 AI 从“聊天助手”升级成“执行型 Agent”。

一句话总结：OpenCode 不是最傻瓜的 AI 编程工具，但它的上限很高。

二、Windows 上安装 OpenCode

Windows 上最简单的方式，是先安装 Node.js，再通过 npm 全局安装 OpenCode。

1. 安装 Node.js

先进入 Node.js 官网：

https://nodejs.org/en

下载适合 Windows 的安装包，按默认选项一路安装即可。

安装完成后，打开 cmd、PowerShell 或 Windows Terminal，执行：

node --version
npm --version

如果能看到版本号，说明 Node.js 和 npm 已经可用。

2. 安装 OpenCode

继续在终端里执行：

npm install -g opencode-ai

安装完成后检查版本：

opencode --version

如果返回版本号，就说明安装成功。

3. 启动 OpenCode

进入你想让 AI 工作的项目目录，然后执行：

opencode

也可以指定项目路径启动：

opencode path/to/your-project

这里有一个新手很容易忽略的点：OpenCode 会以当前目录作为工作区。也就是说，你在哪个目录启动，它就默认在哪个目录理解项目、读取文件、生成内容和执行命令。

所以不要随便在桌面、下载目录或者无关文件夹里启动。更好的习惯是：先进入项目根目录，再运行 opencode。

三、第一次启动：先连接模型，再初始化项目

安装只是开始。OpenCode 真正好不好用，取决于第一次配置是否做对。

1. 连接模型提供商

首次进入 OpenCode 的 TUI 后，可以使用：

/connect

它会引导你配置模型提供商。根据你使用的服务不同，可能需要填写 API Key、Base URL、模型名称等信息。

如果你习惯用环境变量，也可以通过类似方式配置：

set ANTHROPIC_API_KEY=your-api-key

PowerShell 中可以这样写：

$env:ANTHROPIC_API_KEY="your-api-key"

如果你用的是中转站或兼容 OpenAI 格式的服务，通常还要确认三件事：

  • API Key 是否正确。
  • Base URL 是否填对。
  • 模型名称是否和服务商后台一致。

很多“连不上模型”的问题，本质上不是 OpenCode 的问题，而是 Key、地址、模型名三者有一个没对上。

2. 初始化项目记忆

连接模型之后，建议立刻在项目里执行：

/init

OpenCode 会分析当前项目结构，并生成一个 AGENTS.md 文件。

这个文件非常重要。它不是临时说明，也不是普通 README，而是 AI 在这个项目里的工作说明书。

建议你把 AGENTS.md 提交到 Git。因为它会让团队里的每一次 AI 协作都更稳定：知道项目结构、知道测试命令、知道代码风格、知道哪些事不能做。

四、日常使用里最常用的几个动作

OpenCode 的 TUI 里功能不少，但真正高频的其实就几类。

1. 直接提需求

最普通的用法就是直接输入任务：

帮我解释一下这个项目的目录结构。

或者：

给用户列表接口增加分页参数，并补充对应测试。

但如果是改代码类任务，建议尽量说清楚边界：

  • 要改哪里。
  • 不要改哪里。
  • 参考哪个现有实现。
  • 验证命令是什么。
  • 是否允许它直接写文件。

提示词越接近真实任务单，AI 越不容易跑偏。

2. 用 @ 精准引用文件

OpenCode 里 @ 很常用。第一种用法是引用文件或目录。

例如：

帮我检查这个鉴权中间件有没有安全问题：@src/middleware/auth.ts

或者：

分析 @src/api/ 目录下接口的分层是否一致。

这比一句“帮我看看鉴权有没有问题”要好得多。因为你把上下文范围明确给了 AI，它就不会在整个项目里乱猜。

3. 用 ! 执行命令

在 TUI 里可以直接用 ! 执行 Shell 命令，例如：

!git status
!npm test
!npm run build

这样做的好处是，命令输出会直接进入当前对话上下文。AI 可以根据测试失败、构建报错、Git diff 继续推理，而你不用在终端和聊天窗口之间来回复制。

4. 用 /session 找回会话

如果你不小心关掉了 OpenCode，可以重新进入项目目录，运行：

opencode

然后在 TUI 中使用：

/session

选择之前的会话继续。

对于多轮调试或长任务，这个功能很实用。

5. 用 /compact 压缩上下文

长时间对话后，上下文会越来越重。这个时候不要硬聊，可以执行：

/compact

它会把当前会话压缩，把重要信息留下来，减少上下文负担。

适合这些场景：

  • 长时间调试一个 Bug。
  • 多轮实现一个功能。
  • 已经读了大量文件。
  • 对话开始变慢或回答变散。

6. 用 /undo 和 /redo 控制改动

如果 AI 改了代码，但你发现方向错了，可以使用：

/undo
/redo

这类能力通常依赖 Git 变更管理。所以在真实项目里用 OpenCode，一个基础前提是：项目必须放在 Git 仓库里，并且你要经常看 git status 和 git diff。

AI 可以很快，但 Git 是安全带。

五、AGENTS.md 是 OpenCode 的核心配置资产

很多人装完 OpenCode 就开始提需求，然后发现 AI 经常写出“能跑但不符合项目习惯”的代码。

常见问题包括：

  • 用错 ORM。
  • 写错目录。
  • 绕过已有封装。
  • 生成和团队风格不一致的代码。
  • 忘记测试命令。
  • 不知道哪些文件不能动。

根本原因通常不是模型能力差，而是你没有把项目规则告诉它。

AGENTS.md 就是为了解决这个问题。

一份实用的 AGENTS.md 至少应该写清楚：

  • 项目技术栈。
  • 常用开发命令。
  • 测试和构建命令。
  • 目录结构说明。
  • 代码风格要求。
  • 分层架构约束。
  • 常见实现参考。
  • 禁止事项。

比如：

# Project Rules

## Commands

- Install: `npm install`
- Dev: `npm run dev`
- Test: `npm test`
- Build: `npm run build`

## Architecture

- API routes live in `src/api`.
- Business logic lives in `src/services`.
- Data access must go through `src/repositories`.
- Controllers should not access the database directly.

## Code Style

- Prefer small changes over large rewrites.
- Follow existing naming and folder conventions.
- Add tests for behavior changes.
- Do not introduce new dependencies without asking first.

这类规则越具体，AI 的表现越稳定。

你不应该每次都在提示词里重复“不要乱加依赖”“先跑测试”“参考现有写法”。这些应该沉淀到 AGENTS.md 里。

六、理解 Agent：别把 OpenCode 只当聊天框

OpenCode 的一个关键概念是 Agent。

如果你只把它当成“终端版 ChatGPT”，那就只用到了表层能力。真正值得用的是它的角色分工。

1. 主 Agent：当前与你对话的执行者

主 Agent 可以理解为当前接手任务的人。

常见的默认角色包括：

  • Build：适合直接开发，能读写文件、执行命令。
  • Plan：适合先规划方案，更审慎，不急着动代码。

很多人以为这是“模式切换”。更准确地说，这是“角色切换”。

例如，一个稳妥的功能开发流程是：

先切到 Plan，让它只分析方案，不改文件。

确认方案后，再切回 Build：

按刚才的方案执行，改完后运行测试。

这比一开始就让 AI 大改项目更安全。

2. 子 Agent：专项任务助手

子 Agent 更像团队里的专业成员。

例如常见的 @explore 就适合做只读搜索：

@explore 找出所有调用 sendEmail 的地方，并按调用链分组说明。

子 Agent 的价值在于分工。你不必让一个 Agent 同时负责搜索、决策、写代码、审查。复杂任务里，先让只读 Agent 做探索，再让主 Agent 做实现，效果通常更稳。

七、oh-my-opencode：把单个助手扩成多角色团队

如果说 OpenCode 是地基，那么 oh-my-opencode 更像是一套增强工作流。

安装方式通常是：

npx oh-my-opencode install

有些环境也会使用：

bunx oh-my-opencode install

安装过程中，它可能会询问 Claude、Gemini、OpenAI 或其他模型服务的账号和 API 配置。有就填，没有也可以先跳过，后续再配置。

oh-my-opencode 的价值不只是“多几个角色名”，而是把 OpenCode 的使用方式推向团队协作：

  • 有的 Agent 负责需求澄清。
  • 有的 Agent 负责计划审查。
  • 有的 Agent 负责代码搜索。
  • 有的 Agent 负责质量把关。
  • 有的 Agent 负责执行长任务。

进阶使用里，最值得先记住的是 ulw。

ulw 通常表示 ultrawork。当你在任务里带上它时，Agent 会更倾向于自主推进：主动搜索项目、拆分任务、调用子 Agent、执行验证，直到得到可交付结果。

例如：

ulw 给 /api/orders 接口增加分页能力，参考 /api/products 的实现方式，完成后运行测试。

或者：

ulw 找出项目里所有 N+1 查询风险，先列出问题清单，再逐个修复并验证。

但 ulw 不是万能按钮。

适合用 ulw 的场景：

  • 任务目标明确。
  • 涉及多个文件。
  • 有可参考的现有实现。
  • 你希望 AI 自主推进。
  • 最终可以通过测试或构建验证。

不适合一上来就用 ulw 的场景：

  • 需求边界还不清楚。
  • 涉及关键架构取舍。
  • 业务规则还没定。
  • 你只想先看方案，不想改代码。

这种情况下，先规划，再执行。

八、几套真正好用的工作流

下面是我认为最容易落地的几种用法。

工作流 1：快速读懂陌生项目

进入项目根目录，启动 OpenCode：

opencode

然后先初始化：

/init

接着让它梳理项目：

@explore 分析这个项目的目录结构、主要入口、核心业务模块和测试命令，输出一份新人 onboarding 笔记。

这个场景里，不建议一开始就让 AI 改代码。先让它读懂项目，生成地图。

工作流 2：做一个中等复杂度功能

比如你要给订单列表增加分页、筛选和排序。

比较稳的做法是：

先不要改文件。请分析现有订单接口和商品列表接口，给出订单列表增加分页、筛选、排序的实现方案。

方案确认后再执行：

按刚才方案实现。要求参考商品列表接口的写法，不引入新依赖，完成后运行测试。

如果你装了 oh-my-opencode，也可以在目标明确后使用：

ulw 按已确认方案实现订单列表分页、筛选和排序，参考商品列表接口，完成后运行测试。

工作流 3：只做代码审查，不改文件

OpenCode 很适合做预审。

例如：

只读分析，不要修改文件。审查 @src/payment/ 目录，重点看幂等性、并发安全、异常处理和权限边界。

或者：

@explore 扫描所有 API 入口，列出可能缺少鉴权校验的接口，并说明判断依据。

这里的关键是明确告诉它“只读分析，不要修改文件”。

工作流 4：追一个复杂 Bug

不要只贴一句“这里报错了”。更好的输入是：

这是测试失败日志。请从报错位置开始追踪调用链，找出根因。先给分析，不要直接改代码。

然后把日志贴进去，或者让它直接跑命令：

!npm test

确认根因后再说：

按最小改动修复这个问题，并补充能覆盖该问题的测试。

复杂 Bug 最忌讳让 AI 直接猜修复。先定位根因，再动代码。

工作流 5：大范围重构

例如你要重构支付模块，但对外接口不能变。

不要直接说：

帮我重构支付模块。

这太宽泛。

更好的说法是：

先分析 @src/payment/ 的现有结构，找出重复逻辑、外部依赖、对外接口和测试覆盖情况。只输出重构计划，不要改文件。

计划确认后，再分阶段执行：

按计划执行第一阶段，只抽取重复逻辑，不改变对外接口。完成后运行支付模块相关测试。

大范围重构一定要分阶段。AI 可以跑得很快，但你要控制节奏。

九、新手最容易踩的坑

1. 在错误目录启动

OpenCode 会围绕当前目录工作。目录错了，后续上下文和文件输出都会错。

启动前先确认：

pwd
git status

Windows 的 cmd 可以用：

cd
git status

2. 没有 Git 就让 AI 改代码

这是高风险用法。

建议真实项目必须先有 Git，并且在大任务前看一眼：

git status

改完后看：

git diff

不要把 AI 当成不可回退的自动脚本。Git 是你和 AI 协作的保险。

3. 不写项目规则

没有 AGENTS.md，AI 只能靠猜。

它可能能猜对技术栈，但猜不出你们团队的偏好、禁忌和历史包袱。

4. 小任务过度编排，大任务一句话梭哈

正确姿势是：

  • 小任务：直接让它改。
  • 中等任务：先方案，再实现。
  • 大任务：计划文件、分阶段执行、持续验证。

5. 只关心生成代码，不关心验证

AI 写完代码不等于任务完成。

你至少要让它跑：

!npm test
!npm run build

具体命令按项目而定。关键是把验证变成工作流的一部分。

十、我建议照抄的提示词模板

1. 项目理解

@explore 分析这个项目的整体结构，说明入口文件、核心模块、数据流、测试命令和最重要的开发约定。只读分析，不要修改文件。

2. 功能规划

先不要改文件。请基于当前项目结构，为「这里写需求」设计实现方案。要求说明需要改哪些文件、为什么这么改、潜在风险、测试策略。

3. 功能实现

按刚才确认的方案实现，保持最小改动，遵循 AGENTS.md。完成后运行相关测试，并总结改了哪些文件。

4. Bug 定位

先定位根因，不要直接修。请根据下面的错误日志追踪调用链，说明问题出现的条件、根本原因和最小修复方案。

5. 代码审查

只读审查，不要修改文件。请审查 @目标文件或目录，重点关注正确性、安全性、边界条件、性能问题和缺失测试。按严重程度排序输出。

6. 进阶自主执行

ulw 按以下目标完成任务：目标是「这里写目标」。约束：不引入新依赖；参考现有实现；保持最小改动；完成后运行测试并汇总结果。

十一、结语：OpenCode 的价值是组织软件开发过程

很多人评价 AI 编程工具，只看它能不能生成代码。

但在真实开发里，最耗时间的往往不是写那几十行代码，而是：

  • 读懂项目。
  • 找到相关文件。
  • 理清调用链。
  • 拆分任务。
  • 对齐项目规则。
  • 控制改动范围。
  • 跑测试和验证。
  • 复盘变更影响。

OpenCode 的价值就在这里。

它不是把 AI 包装成一个更漂亮的聊天窗口，而是把 AI 放进终端、文件系统、Git、Shell 和项目规则里，让它更接近真实研发流程。

如果你刚开始用，先把安装、/connect、/init、@文件引用、!命令执行 这几件事用熟。

如果你已经用顺了，再去折腾 AGENTS.md、子 Agent、oh-my-opencode、ulw 和分阶段执行工作流。

OpenCode 不是越“自动”越好，而是越“可控”越好。

当你能把任务边界、项目规则、执行权限和验证方式都说清楚，它就不只是一个 AI 助手，而会逐渐变成你日常开发流程里稳定的一环。

posted @ 2026-08-31 16:23  IT王师傅  阅读(68)  评论(0)    收藏  举报