OpenCode 第一次使用

简介

本教程带你从零跑通 OpenCode v2 首次使用完整流程。
前提：已经完成 OpenCode v2 安装，并且配置好 API Key。

OpenCode 是终端里的 AI 编程代理，可以直接读写项目文件、执行命令、帮你写代码、查bug、重构项目。

1. 准备工作

1. 打开终端（Windows PowerShell / CMD、macOS 终端、Linux Shell）
2. 进入你的项目文件夹

cd /path/to/your/project

建议新建空文件夹做测试，避免误修改正式项目。

3. 检查 OpenCode 是否可用

opencode --version

输出版本号 v2.x.x 即安装成功。

2. 启动 OpenCode

在项目目录执行：

opencode

首次启动会做简单初始化：

• 加载项目目录结构
• 读取 AGENTS.md（如果存在）
• 连接配置好的大模型 API

启动成功后，进入 OpenCode 交互对话界面，你就可以直接提需求。

3. 第一个简单任务测试

在 OpenCode 对话提示符中输入：

帮我创建一个 index.html，写一个最简单的网页，标题为 OpenCode v2 Demo

这里用桌面应用来演示：

OpenCode 会自动：

1. 分析需求
2. 创建 index.html 文件
3. 写入网页代码
4. 输出操作日志

任务完成后，退出交互界面：

/exit

命令说明：OpenCode 内置斜杠指令，输入 /help 查看全部可用指令。

4. 常用基础指令（新手必看）

/help      # 查看帮助
/clear     # 清空当前对话上下文
/files     # 查看当前项目可访问文件列表
/exit      # 退出 OpenCode
/model     # 切换模型

5. 安全提醒（首次使用重点）

1. OpenCode 有权限读写当前目录文件，不要在重要项目直接执行高危操作，先在测试项目试用。
2. 不要让 AI 删除、修改系统文件、配置密钥等敏感文件。
3. API 调用会消耗 Token，大任务前预估成本。
4. AGENTS.md 放在项目根目录，可以自定义 AI 的行为规则，参考《OpenCode AGENTS.md 配置》。

6. 常见问题

Q：启动报错 API 未配置

A：参考《OpenCode API 设置》，检查服务商地址、API Key、模型名称配置。

Q：OpenCode 读取不到项目文件

A：确认在项目根目录启动；检查是否有 .gitignore，被忽略的文件 OpenCode 默认不会读取。

Q：AI 执行命令失败

A：查看终端日志，权限不足、环境缺失是最常见原因。

小结

OpenCode v2 使用流程：进入项目目录 → 执行 opencode 启动 → 输入需求 → 等待 AI 完成文件/代码操作。
新手先从简单创建文件开始上手，熟悉后再做代码重构、调试等复杂任务。