从零开始使用 opencode：安装、实战与进阶

最近我开始接触 opencode。以前使用 ai 写代码时，我经常把代码复制到对话窗口，等它回答后再复制回来。文件一多，就需要反复说明项目结构，也很难知道它的建议是否真的适合当前代码。

opencode 的思路是把 ai 助手带到项目目录中：你提出任务，它可以根据权限读取文件、查找代码、运行命令和修改文件。你仍然要决定目标、审查改动，并验证结果。

这篇文章从第一次安装开始，以 windows 和 vscode 终端为例，带你完成一个小练习，再逐步认识模型、项目规则、权限和进阶功能。macos 和 linux 的使用思路相同，安装命令和目录写法请参考官方文档。

本文以 opencode 2.x 为准，资料查阅于 2026 年 10 月 29 日。产品更新较快，界面、模型和命令可能变化，请以 opencode --help 和官方文档为准。文中练习和提示词是教学示例；本机已验证安装、模型连接和简短请求，完整练习及进阶配置没有逐项实测。

1 先弄明白：它是什么，有什么用

先看一个具体任务：项目里有一个计算价格的函数，你想增加折扣并补充测试。传统对话需要你提供代码、复制答案、自己找到位置修改；使用 opencode 时，可以在项目目录里描述需求，让它先查看相关文件，再按约定实施和验证。

几个容易混淆的概念：

opencode 可以连接不同 provider，也有终端、桌面和网页入口。本文先使用终端界面：它可以在 vscode 内置终端运行，不需要先安装编辑器扩展。官方介绍

它可以帮你读项目、解释错误、编写代码、补测试和整理文档。它也可能理解错需求、运行错误命令或生成有问题的代码，所以要给清楚范围，并查看差异和测试结果。

2 准备工作：终端、网络和模型账号

你需要一台电脑、网络连接、一个可以使用的模型服务账号，以及一个用于练习的目录。调用商业模型通常按服务商规则计费；模型是否可用由账号权限、额度、地区和服务状态共同决定。

chatgpt 订阅和 openai api 是不同的使用方式。 如果选择 api key，要确认 api 账户和计费状态；不要假设已有聊天订阅就一定包含 api 额度。opencode 也可能支持其他认证方式，实际以 provider 的提示和条款为准。

在 windows 打开 vscode，选择“终端 → 新建终端”，下面的命令输入在终端中。命令中的 > 或 $ 如果出现在其他教程里，通常是提示符，不需要复制。

先检查 node.js 和 npm：

node --version
npm --version

如果提示找不到命令，先安装 node.js，关闭并重新打开终端，再检查一次。在 PowerShell 遇到 npm 脚本执行限制时，可以用 npm.cmd；不要为了安装这个工具随意修改系统的全局执行策略。

后面的折扣计算器练习还需要 Python 3。在终端运行 python --version 检查；如果没有安装，请先从 Python 官网安装并重新打开终端。安装时按提示将 Python 加入命令搜索路径；部分 Windows 环境也可以用 py 代替 python。

3 安装并检查版本

下面使用官方的 2.x npm 包：

npm.cmd install -g @opencode/cli@latest
opencode --version

如果国内网络访问官方 npm 较慢，可先尝试国内镜像，保持同一个官方包名和版本：

npm.cmd install -g @opencode/cli@latest --registry=https://registry.npmmirror.com

镜像不可用或没有所需版本时，再使用上面的官方源命令。安装完成后，版本输出例如 opencode v2.2.1；你看到的版本可能更新。若提示找不到 opencode，重新打开终端，检查 npm 全局命令目录是否在当前用户的 PATH 中。

注意，旧资料可能使用 1.x 的 opencode-ai 包或旧配置字段。本文使用 @opencode/cli 和 2.x 语法，不要把两套示例混用。官方安装说明

4 第一次连接模型

先启动 opencode：

opencode

进入界面后，在输入区输入 /connect 并回车，选择 provider。以 openai api key 为例，选择 openai 和 api key 认证，按界面提示输入已有密钥。界面选项可能随版本变化；如果不确定认证方式，先看 provider 说明。

连接后输入 /models，选择你账号有权限使用的模型。也可以在普通终端查看认证状态和模型目录：

opencode auth list
opencode models

auth list 中显示已保存，只说明认证条目存在；模型出现在列表中，也不保证账号有该模型的访问权限。最直接的检查是发送一个简短请求：

opencode run --model openai/gpt-5-mini "只回复 OK，不使用工具。"

把示例模型替换成你实际可用的型号。看到模型回复 OK，只能证明这一次请求通过，不能证明所有模型和后续请求都可用。

不要把真实密钥写进博客、源码、提交记录、截图或聊天记录，也不要将它作为命令行参数。通过交互式认证输入，或使用服务商支持的安全凭据管理方式。发现泄露时，在服务商处撤销并更换，而不是只删除文件中的文字。

5 第一次动手：让它认识一个小项目

我建议先用一个没有真实数据的练习目录。下面在 PowerShell 中创建目录并进入；如果目录已有内容，请先检查，避免覆盖自己的文件。

mkdir opencode-practice
cd opencode-practice
opencode

现在输入第一句话：

请先查看当前目录，告诉我里面有什么。
只做只读检查，不创建或修改文件，也不要运行安装命令。

空目录可能没有文件，这也是正常结果。你可以继续问：“如果我想写一个计算折扣价格的小程序，建议拆成哪些步骤？先不要写代码。”先练习让它理解目标，再决定是否让它动手。

终端里的命令和对话中的文字不同。 opencode 是在 PowerShell 中启动程序；启动后，在 opencode 输入区输入的是任务描述。/models 这样的斜杠命令由 opencode 处理，不是 PowerShell 命令。

需要回到 PowerShell 时，在 opencode 输入 / 查找退出命令，或通过 Ctrl+P 打开命令面板查找退出操作。重新进入练习时，先 cd 到同一个练习目录再启动 opencode。

6 从需求到可验收的代码：四轮练习

下面是一个完整的学习案例。你可以直接复制提示词，逐轮观察结果；其中“预期”是验收目标，不是声称本文已经运行过该练习。

第一轮：先让它给方案

我想用 Python 写一个命令行折扣计算器，供初学者练习。
输入原价和折扣百分比，输出折扣后的价格，保留两位小数。
原价不能为负，折扣范围是 0 到 100。

先给出文件结构、输入输出示例和测试方案，不要创建或修改文件。
使用 Python 标准库，不安装第三方依赖。

这里需要先明确“折扣百分比”的含义：例如原价 100、折扣 20%，结果是 80。若它理解为“付原价的 20%”，应先纠正，不要急着写代码。

第二轮：确认后实现

如果方案符合预期，再输入：

按刚才确认的方案实现。
只修改当前练习目录；不要安装依赖，不要操作其他目录。
创建程序和标准库测试，并写出运行方法。
实现后运行测试，说明修改了哪些文件、测试结果和未验证项。

当界面要求批准文件或命令操作时，先看具体操作和路径，再决定是否允许。提示词中的限制是重要约定，但不能替代权限配置和人工核对。

第三轮：自己验收

对照 opencode 给出的文件名与运行方法，在自己的终端运行测试。若文件名是 test_discount.py，一个常见运行方式是：

python -m unittest test_discount

再实际运行程序，检查正常输入、边界值和错误输入：例如 100 与 20 应得到 80.00；负原价或超过 100 的折扣应被拒绝。具体运行命令以实际生成的程序说明为准。

如果失败，把错误信息、运行命令和期望结果一起交给它，要求定位原因；不要把终端里的密钥或其他敏感内容一并粘贴。

第四轮：让它审查，再由你看差异

请只读审查刚才的实现。
重点检查输入边界、金额精度和测试遗漏。
指出文件位置、问题和影响，不直接修改文件。

在已有 git 仓库中，可以用 git status 和 git diff 查看已跟踪文件的改动；新建的未跟踪文件要单独打开查看，普通 git diff 不会展示其内容。确认改动符合要求后，再按自己的流程提交。测试通过只说明覆盖到的场景通过，不代表程序没有其他问题。

7 常用操作：先记住这几个

在 opencode 界面输入 / 可以查看当前版本的命令。常用的有：

多行输入可以用 Shift+Enter；Ctrl+P 打开命令面板。撤销不是备份，使用前仍应检查未提交改动和版本控制状态。终端界面文档

终端里的 opencode run 适合一次性任务或脚本；交互式界面更适合多轮沟通。不要在不理解权限的情况下使用自动批准选项，尤其是在有重要文件的目录。

8 怎样给出好任务

“帮我优化项目”很难验收。更好的任务至少包含四件事：目标、范围、约束、验收。

目标：修复价格计算在小数输入时出现的精度问题。
范围：只检查和修改价格计算及对应测试。
约束：不改变现有接口，不新增第三方依赖；保留其他已有改动。
验收：给出一个原来失败的例子，补测试并运行相关检查。
完成后列出差异、测试结果和未验证项；不要提交或推送。

这不是固定格式。关键是让助手知道哪些事可以做、什么结果才算完成。遇到需求冲突时，让它先列出选项和影响；遇到验证失败时，让它报告实际错误，而不是重复说“已经修复”。

对不熟悉的仓库，先问“入口在哪、数据怎样流动、哪些地方还不确定”，再进入修改。复杂任务可以先做一个很小的端到端闭环，验收后再扩展。

9 配置默认模型与项目约定

全局配置和项目配置

opencode 2.x 支持 JSON 或 JSONC。用户全局配置通常位于 ~/.config/opencode/opencode.json；项目也可以有自己的 opencode.json 或 opencode.jsonc。在 windows 中，~ 表示当前用户的主目录。项目配置可能覆盖全局配置，系统托管配置优先级更高。配置位置和优先级

一个只设置默认模型的例子：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "openai/gpt-6.1-terra"
}

使用你自己的可用模型替换该值。已有配置时要合并字段，不要直接覆盖原文件；配置中不要写真实密钥。默认值对新工作生效，已有会话中选定的模型可能优先。模型支持和访问权限会变化，先通过 /models 选择，再做简短请求验证。模型选择说明

用 AGENTS.md 保存团队约定

在项目根目录放一份简短的 AGENTS.md，写清楚项目结构、测试命令和工作边界。例如：

# 项目约定

- 修改前先检查工作区，保留已有改动。
- 只处理当前任务；改变公开接口前说明影响。
- 运行与改动相关的测试，并报告未验证项。
- 未经明确要求，不提交、推送或发布。

实际命令应根据项目填写，不要照搬不存在的测试。opencode 2.x 会按目录发现 AGENTS.md；它是给助手的项目说明，不等于操作系统级访问控制。多个文件的内容也可能冲突，需要人维护。项目说明文档

10 进阶：权限、agent、skill 和 mcp

这些功能可以等第一次练习熟悉后再用。先理解各自负责什么，比一开始装一堆插件更有帮助。

权限：让敏感操作停下来

权限规则决定一个动作是允许、询问还是拒绝。下面是 2.x 的示例：shell 命令默认询问，明确禁止推送。

{
  "permissions": [
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git push *", "effect": "deny" }
  ]
}

规则按匹配顺序处理，最后匹配的规则生效；实际命令形式和更多规则请参照权限文档。这段示例只限制匹配到的 shell 动作，不能视为对所有外部写入的完整防护，也不能代替系统权限、代码审查与备份。

agent：让不同角色做不同工作

agent 可以带不同提示、模型和权限。比如让主要助手实现功能，再请求一个只读 reviewer 检查错误处理。先分清谁修改、谁审查，避免两个角色同时改同一份文件。/agents 可以选择当前角色；自定义 agent 的文件和配置见官方说明。

skill：把反复使用的流程保存下来

skill 是可复用的任务说明，例如“检查一个发布说明是否包含版本、变更和验证”。在项目的 .opencode/skills/<名称>/SKILL.md 中描述适用场景和步骤，助手可以在相关任务中加载。先把流程跑通，再提炼稳定步骤；包含脚本的 skill 要先审阅脚本内容。skill 文档

mcp：让助手连接外部工具

mcp 可以理解为连接外部工具和数据源的协议：例如让助手使用一个提供文档查询能力的服务。是否能读取或修改数据取决于具体服务和授权，并非连接后就天然安全。先确认来源、权限、数据范围和费用，用最小权限测试，再按官方 mcp 文档配置。

11 常见问题

命令找不到？ 重新打开终端，检查 node --version、npm --version 和 npm 全局命令目录；确认是安装在当前使用的 windows 用户环境，而不是另一个系统或 wsl 中。

已连接但模型不可用？ 先看 /models、模型 ID、provider、账号权限与额度，再看具体错误。目录里列出了模型不代表该账号有权限。不要不断更换密钥或在公开渠道粘贴错误中的敏感信息。

认证通过但请求超时？ 检查网络、代理、服务状态和 provider 的具体报错；先用一个短请求定位。不要为了排错关闭全局安全设置。

改错文件怎么办？ 先停止继续操作，查看 git status、差异和备份；需要时使用会话的 /undo，但先了解它会撤销哪些工作。不要用不理解的清理命令覆盖未提交内容。

为什么费用比想象中高？ 模型价格、上下文长度、多次工具调用和重试都可能影响费用。先用小任务和适合的模型，查看服务商的用量与计费；不要把一次短请求的费用当作复杂项目的成本。

模型切换了，但旧会话还是原来的？ 当前会话选择可能优先于全局默认值。在该会话输入 /models 切换，或新建会话后核对；项目或系统配置也可能影响结果。

12 给自己的学习路线

第一天，完成安装、连接模型和一次简短请求；再让它只读解释一个自己能看懂的小目录。第二天，用上面的折扣计算器练习方案、实现、测试和审查。熟悉后，把同样的方法用在真实项目的一个小问题上：先检查工作区，再给明确边界，完成后由自己看差异和测试。

等你反复遇到同一种工作，再写 AGENTS.md 或 skill；确实需要外部资料时，再考虑 mcp。每引入一种能力，都要知道它连接了哪里、能做什么，以及如何验证结果。

我觉得学习这类工具最重要的不是记住多少命令，而是练习把需求说清楚、把操作范围限定清楚，并用自己的验收判断结果。先完成一个小闭环，你就可以逐渐把更复杂的工作交给 opencode。

参考资料

• opencode 2.x 官方文档
• 终端界面与常用操作
• provider 连接与认证
• 配置与模型
• 权限控制