安装 stable OpenCode 时，先使用当前官方安装器或 stable 文档列出的包管理器，确认系统能找到 opencode binary，再通过 /connect 连接 provider。随后从你希望 OpenCode 理解的项目目录启动它，并运行 /init。
本文核验时，官方给出的最短安装命令是：
OpenCode 官方文档在 2026 年 8 月 26 日仍列出这条命令。同日，本机通过 bunx opencode-ai 运行了 OpenCode 1.18.23，确认版本输出并成功加载 CLI 帮助；这不等于已经在所有操作系统上执行过安装脚本。运行前请重新查看当前 stable OpenCode 文档，并遵守组织对远程脚本的安全规定。
安装前先确认你要用 stable OpenCode
本文只讲 stable opencode binary 和 stable v1 配置。
OpenCode v2 目前是独立的 beta，使用 opencode2 binary。它不会替换 stable opencode 命令。不要把 beta 教程、配置结构或功能行为复制进这篇 stable 安装教程。
开始之前，先确定你要用哪条版本轨道：
如果某篇教程要求运行 opencode2，或者使用仅属于 v2 的配置结构，请先停下来。它对 beta 可能有效，但不能作为本文 stable 安装路径的依据。
在 macOS 上安装 OpenCode
官方安装脚本是文档中最简单的 stable 路径：
OpenCode stable 文档还列出了 Homebrew、npm 和 Bun 等包管理器路径。请使用当前官方页面给出的准确命令，并优先选择你已经信任、已经用于管理软件的工具；后续升级也应由同一条安装路径负责。
安装完成后，如果安装器改动了 shell 环境，请重新打开终端，再验证 binary：
能看到版本字符串，只说明当前 shell 可以找到某个 OpenCode binary。它还不能证明你安装的是目标 stable 版本、已经能连接 provider，或者从正确的项目目录启动。请把显示的版本与当前 stable release 信息核对。
在 Linux 上安装 OpenCode
官方文档也为 Unix-like 系统提供同一条 stable 安装命令：
运行前，请检查当前官方页面以及所在环境对下载并执行 shell 脚本的规定。Stable 文档还列出 npm 和 Bun 路径。最好只让一种安装方式负责 OpenCode；同时混用官方脚本和多个包管理器，可能让系统里出现多个 opencode binary，也会让升级来源难以判断。
使用下面的命令验证结果：
如果 shell 提示找不到 opencode，不要立刻反复重装。先查看安装器最后的输出，确认安装目录是否位于当前 shell 的 PATH 中，以及是否需要重新打开终端。准确安装目录会随版本和环境变化，应以当前安装器输出为准，不要照搬另一台机器的路径。
在 Windows 上安装 OpenCode
Stable 官方文档建议优先使用 Windows Subsystem for Linux（WSL），以获得更好的兼容性和性能。简单来说，WSL 在 Windows 中提供一个 Linux 环境，让终端开发工具按更接近 Linux 的方式运行。
推荐路径如下：
- 按 Microsoft 当前 WSL 安装说明配置一个仍受支持的 WSL 发行版。
- 打开 WSL 终端。
- 重新查看 OpenCode Windows/WSL 文档。
- 在 WSL 内使用当前 stable 文档给出的 Linux 安装路径。
- 在同一个 WSL 环境中运行
opencode --version。 - 从团队已经理解其 Windows/WSL 文件行为的项目位置启动。
OpenCode 也记录了通过 Scoop 和 Chocolatey 进行 Windows 原生安装的路径。如果选择 Windows 原生安装而不是 WSL，请从当前 stable 官方文档获取命令，并单独测试这条路径。
不要在没有记录的情况下混用 WSL 和 Windows 原生安装。PowerShell 中能运行的命令，未必与 WSL 中的安装、配置、provider 凭证或项目文件属于同一个环境。
验证并更新 OpenCode 安装
每次安装或升级后，都用 stable CLI 的版本命令检查：
Stable CLI 文档还列出了：
当前 CLI 已提供 upgrade 命令，但安装方式仍决定谁负责升级。由包管理器安装的版本通常应由对应包管理器管理，不要默认每种安装方式都应该同时在两个地方升级。
如果版本不符合预期，先检查这些情况，再修改配置：
- shell 找到了另一种安装方式留下的旧 binary；
- 教程安装的是 stable
opencode，但你期待的是独立的opencode2beta； - 终端在安装前已经打开，仍保留旧 PATH 状态；
- 组织管理的环境有意固定了版本。
不要为了修复版本不一致就删除配置或凭证。先确认当前实际运行的是哪个 binary，以及它由哪条安装路径管理。
连接 provider 并初始化第一个项目
OpenCode 是一个 agent harness：它负责组织交互、工具和项目工作流，provider 则提供兼容模型的访问能力。只安装 binary 并不会自动连接模型账号。
1. 启动 stable OpenCode 并连接 provider
运行 stable OpenCode，然后在产品内使用：
按照当前产品界面，为你有权使用的 provider 完成连接。不要把真实 API Key 粘贴到 Blog、截图、公开 Issue、已提交的配置文件或共享 transcript 中。本文不会展示任何形似真实 secret 的示例。
Provider 选项、认证步骤、模型和计费都可能独立于 OpenCode binary 变化。请在自己的账户中验证准确路径，并使用当前官方 provider 文档，而不是编造一个适用于所有 provider 的登录流程。
2. 从正确的项目目录启动
在你希望 OpenCode 检查的项目目录中打开终端，再运行：
工作目录非常重要。从过高的父目录启动，可能暴露无关文件；从错误的子目录启动，可能看不到项目规则或依赖。第一次运行应使用一次性测试项目或已经纳入版本控制的项目。
3. 初始化项目
在 OpenCode 内使用官方文档记录的 stable 初始化命令：
初始化的目的，是为项目建立上下文，但 /init 可能创建或修改项目文件。只在一次性项目或已纳入版本控制的项目中运行它，随后立即检查 diff；不要把初始化描述成只读步骤，也不要假定它在不同版本中一定修改相同文件。
4. 再给一个只读的后续任务
不要一开始就要求重写整个仓库。先给一个有边界、不修改内容的任务，例如：
解释这个项目的入口，列出你检查过的文件，并指出最小相关测试可能使用哪条命令。暂时不要修改文件，也不要运行命令。
将答案与仓库实际情况核对。确认理解正确后，再进入一个文件范围清楚、有验证命令和回退路径的小改动。
本地 OpenCode 与 Agent.Space Workspace 的区别
本地 OpenCode 安装和托管 Agent Workspace 解决的问题不同。
- 本地 OpenCode 运行在你管理的环境中。安装路径、本地文件、shell、凭证、升级和 provider 连接都由你负责。
- 托管 Workspace 可能提供云端项目边界、持久保存的文件、session 和协作行为——但只有当前产品已经确认这些能力与 OpenCode 集成时，才能写成具体功能。
如果你正在比较本地、自托管和托管三种运行方式，可以继续阅读如何在云端运行 OpenCode；那篇文章负责运行环境的选择，本文仍只负责本地安装和首次启动。
不要因为正在考虑 Agent.Space，就默认需要先在电脑上安装 OpenCode：本地安装只对应你自己管理运行环境的路径。同样，OpenCode 上游文档也不能证明每项能力都已进入托管 Workspace。选择托管路径前，请以当前 Agent.Space 产品界面和公开产品资料为准，确认 OpenCode 是否可用、模型访问方式、版本信息与 Workspace 持久化能力。
常见 OpenCode 安装问题
找不到 opencode
阅读安装器输出，重新打开终端，并确认安装目录位于当前 shell 的 PATH 中。如果用过不止一种安装路径，先确定应该由哪一种负责 binary，再决定是否重装。
版本不是你预期的版本
先确认你需要 stable opencode 还是 beta opencode2，再检查旧包管理器或脚本安装是否在 PATH 中排得更靠前。不要为了处理 binary 问题，把 v2 beta 配置复制进 stable。
/connect 没有显示预期 provider
Provider 可用性和认证不属于安装本身。重新查看当前 stable provider 文档、账号资格、地区、计费路径和网络策略。不要使用会暴露密钥或绕过 provider 限制的所谓解决方法。
/init 从错误的项目开始
退出 OpenCode，从目标项目根目录重新启动。授予写入或命令权限前，先检查当前进程实际能看到哪些文件。
Windows 和 WSL 看到不同的文件或命令
把它们当作两个环境处理。确认哪个 shell 管理 OpenCode、项目放在哪里，以及 provider 配置保存在何处。第一次设置应只走一条有记录的路径，不要在任务进行中途切换 shell。
OpenCode 安装检查表
在判断 OpenCode 已安装完成前，确认：
- 安装的是 stable
opencode，不是独立的opencode2beta； opencode --version返回预期的当前 stable 版本；- 只有一条安装路径负责升级；
/connect能进入经过授权的 provider 流程，并且没有泄露 secret；- OpenCode 从目标项目根目录启动；
/init在一次性项目或版本控制项目中完成；- 第一个只读任务引用了正确的项目文件；
- 你知道如何审查并回退第一次写入任务。
这个完整闭环比“安装器显示成功”更有价值。它确认 stable CLI、provider 路径、项目边界和第一个任务已经正确连接起来。
下一步
先完成 stable OpenCode 的本地检查表。随后可以在云端 Workspace 中比较同一个有边界的项目任务，继续学习 OpenCode Skills 与 OpenCode MCP，或在需要持续保存与协作时查看 Agent.Space Workspace。