在项目目录里试用 OpenCode 的记录

项目里有一个小问题：按钮文字需要调整，但你还不知道它写在哪个文件。过去，你可能会先搜索目录，再逐个打开文件。使用 OpenCode 时，可以直接在项目目录里描述这个任务，让它查找相关代码、提出修改，并展示结果。你负责说明目标，也负责检查最终改动。

这就是终端智能体的一种日常用法。OpenCode 把对话、代码阅读和工具操作放进终端，适合从范围明确的小任务开始。这里的“轻量”主要指工作入口简洁：打开项目后，就能围绕当前文件开展工作。

§ 先认识它能做什么

普通聊天窗口主要接收你粘贴的内容。OpenCode 则可以借助工具查看项目文件、搜索代码、执行命令，并在权限允许时修改文件。模型负责理解需求和判断下一步，OpenCode 负责把这些判断落实到本地操作。

它适合解释陌生函数、寻找报错位置、补充测试，或完成局部修改。不过，能够操作文件不代表理解一定准确。项目约定、运行环境和需求边界，仍然需要你提供。

§ 第一次启动，选一个容易检查的项目

先准备可用的终端和一个本地项目，再按照 OpenCode 官方安装说明完成安装。不同系统的安装方式可能不同。安装成功后，进入项目目录，运行 opencode，打开交互界面。

第一次使用时，建议选择已有版本管理的练习项目，并确认当前改动已经保存。这样，稍后可以清楚地查看新增、删除和修改了哪些内容，也方便撤销不合适的结果。

不必立即要求它重写整个项目。可以先输入：“请解释这个项目如何启动，指出入口文件和运行命令，暂时不要修改文件。”这一轮既能帮助你认识项目，也能确认它是否找到了正确的上下文。

§ 给它接上模型

OpenCode 是工作工具，实际回答问题的模型需要另外连接。使用前，你需要配置模型提供方、API 密钥和模型标识。具体字段和配置位置，应以当前版本的 OpenCode 文档为准。

如果希望通过统一入口调用模型，可以使用 Vana API。它提供 OpenAI 兼容端点 https://api.vanaapi.com，同时支持 Anthropic Messages 和 Gemini 原生协议。接入 OpenCode 时，应按所选提供方的要求填写地址和密钥，并确认请求路径与模型标识匹配。

你可以创建一个 Vana API 账户，获取密钥后完成连接。服务按实际 token 用量计费，没有月费。第一次可以选用 Claude Sonnet 5.5，先完成几次小任务，再根据结果和用量判断是否适合自己的工作。

密钥应保存在工具支持的本地配置或环境变量中，避免写进代码仓库。连接完成后，先发送一个简单问题，确认能够收到回答，再开始操作项目。

§ 把任务说到可以验收

“帮我优化一下”很难判断是否完成。更实用的请求会说明位置、预期行为和边界，例如：“找到登录表单，把空邮箱的提示改成中文；保持现有校验逻辑，并说明修改了哪些文件。”

• 先交代现象：发生了什么，怎样复现。
• 再说明目标：希望用户看到什么结果。
• 最后划定范围：允许修改哪里，用什么方式验证。

任务较陌生时，可以先让它调查并说明计划，确认方向后再修改。遇到执行命令或写入文件的权限请求，先看清具体操作；不理解的命令，可以要求它解释用途。

§ 用检查结束一次会话

看到“已完成”之后，还需要查看文件差异，并运行与改动相关的测试。修改了界面文字，就打开页面检查显示；修改了输入校验，就试一次有效输入和一次无效输入。工具报告通过，是判断依据的一部分。

会话越长，读取文件、执行工具和生成回答消耗的 token 通常也越多。把任务拆成独立的小步骤，既方便检查，也更容易观察费用。熟悉之后，再逐渐扩大任务范围。对于初次使用 OpenCode 的人，一次能看懂、能验证的小修改，就是合适的起点。