使用指南
本指南将带你了解 OpenCode 的典型工作流 — 从初始化到分享会话。
快速开始
进入项目目录
cd /path/to/project启动 OpenCode
opencode初始化项目
在 TUI 中运行 /init 命令：
/init这会分析你的项目并在项目根目录创建一个 AGENTS.md 文件。将此文件提交到 Git — 它帮助 OpenCode 理解你的项目结构和编码模式。
模式
OpenCode 有两种主要模式。按 Tab 键在它们之间切换：
| 模式 | 用途 | 可修改文件？ |
|---|---|---|
| Build（构建） | 对代码库进行更改 | ✅ |
| Plan（规划） | 建议和讨论，不做更改 | ❌ |
TIP
对于复杂功能，始终从 Plan 模式开始。审查计划，给出反馈，然后切换到 Build 模式实施。
核心工作流
提问
让 OpenCode 解释代码库的某个部分。使用 @ 模糊搜索文件：
@packages/functions/src/api/index.ts 中的认证是如何处理的？这对理解不是你编写的代码特别有用。
添加功能（Plan → Build）
第 1 步：规划 — 按 Tab 切换到 Plan 模式：
<TAB>详细描述你想要的内容：
当用户删除笔记时，我们希望在数据库中将其标记为已删除。
然后创建一个显示所有最近删除笔记的页面。
在该页面上，用户可以恢复笔记或永久删除它。TIP
像对团队中的初级开发者说话一样与 OpenCode 交流。提供足够的上下文和示例。
第 2 步：迭代 — 审查计划并提供反馈：
我们希望使用之前用过的设计来设计这个新页面。
[图片 #1] 请看这张图片并以它为参考。你可以将图片拖放到终端中以添加视觉上下文。
第 3 步：构建 — 按 Tab 切换回 Build 模式，然后：
计划看起来不错！请继续进行更改。直接进行更改
对于简单的更改，跳过规划步骤：
我们需要为 /settings 路由添加认证。查看 @packages/functions/src/notes.ts
中如何处理此问题，并在 @packages/functions/src/settings.ts 中实现相同的逻辑。提供足够的细节，以便 OpenCode 做出正确的更改。
撤销 / 重做
如果更改不是你想要的，撤销它们：
/undo这会恢复更改并再次显示你的原始消息，以便你可以调整提示并重试。
多次运行 /undo 可以撤销多个更改。要重做：
/redo斜杠命令
| 命令 | 描述 |
|---|---|
/init | 为当前项目初始化 OpenCode |
/connect | 添加或管理 LLM 供应商凭据 |
/models | 选择要使用的模型 |
/share | 创建当前会话的可分享链接 |
/undo | 撤销上一组更改 |
/redo | 重做之前撤销的更改 |
文件引用
使用 @ 后跟文件名在提示中引用文件。OpenCode 提供模糊搜索帮助你找到正确的文件：
@src/components/Header.tsx这会将文件内容包含在发送给 LLM 的上下文中，让它精确了解你正在讨论的代码。
图片支持
将图片直接拖放到终端以包含视觉参考。适用于：
- UI 原型和设计参考
- Bug 截图或预期行为
- 架构图
分享会话
使用 /share 命令分享你的对话：
/share这会创建一个链接并复制到剪贴板。对话默认不会被分享 — 你必须主动分享。
这是一个从 OpenCode 分享的示例对话。
CLI 用法
除了交互式 TUI，OpenCode 还支持 CLI 命令：
# 运行一次性提示，无需进入 TUI
opencode run "解释这个项目中的认证流程"
# 启动服务器
opencode serve
# 启动 Web 界面
opencode web
# 列出认证凭据
opencode auth list