先确认你的电脑系统
安装包必须与操作系统匹配，不能混用。- Windows
- macOS
- Linux
按
Windows + R，输入 winver，再按 Enter。弹出的窗口会显示 Windows 版本。大多数电脑使用 64 位 Windows，应下载文件名包含 x64 或 64-bit 的安装包。认识常见安装包
如何下载和找到文件
- 点击教程中的下载链接。
- 浏览器询问保存位置时，可以直接选择 下载 文件夹。
- 下载完成后，点击浏览器右上角的下载图标。Windows 浏览器通常也可以按
Ctrl+J打开下载记录。 - 点击文件名或 在文件夹中显示。
- 双击安装包开始安装。
如何打开命令行窗口
命令行窗口是输入安装命令的地方。教程中的代码不能粘贴到浏览器地址栏、搜索框或聊天窗口。- Windows PowerShell
- macOS 终端
- Linux 终端
普通打开方式：
- 点击屏幕底部的 开始菜单。
- 输入
PowerShell。 - 点击 Windows PowerShell 或 PowerShell。
- 在搜索结果中右键点击 PowerShell。
- 选择 以管理员身份运行。
- 系统询问“是否允许此应用更改你的设备”时，点击 是。
如何复制并执行命令
例如教程显示：- 只复制灰色代码框中的命令，不要复制代码框外的说明文字。
- 点击 PowerShell 或终端窗口。
- 粘贴命令。
- 按 Enter 执行。
- 等待命令执行结束，再执行下一条。
命令执行后看起来没有反应
- 有些安装命令需要下载文件，请等待几分钟。
- 光标仍在闪烁，且没有出现新的输入行，通常表示命令还在运行。
- 出现新的输入行，表示上一条命令已经结束。
- 不要连续多次按 Enter 或重复运行安装命令。
如何停止卡住的命令
先等待一段时间。如果确认命令长时间没有变化，可以点击终端窗口并按Ctrl+C 停止。这里的 Ctrl+C 表示停止命令，不是复制文字。
认识文件路径
文件路径表示文件在电脑中的位置。
OpenCode 的全局配置文件位置：
- Windows：
%USERPROFILE%\.config\opencode\opencode.json - macOS：
~/.config/opencode/opencode.json - Linux：
~/.config/opencode/opencode.json
.config 文件夹通常是隐藏文件夹。看不到它是正常的，安装教程中的命令会自动创建并打开它。
如何编辑配置文件
OpenCode 使用opencode.json 保存模型和接口配置。JSON 是纯文本文件，不是 Word 文档。
Windows 使用记事本
安装教程会用命令自动打开记事本。粘贴配置后：- 按
Ctrl+S保存。 - 如果出现“另存为”，将 保存类型 选择为 所有文件。
- 文件名填写
opencode.json。 - 编码选择
UTF-8。
macOS 和 Linux 使用 nano
安装教程会在终端中打开 nano 编辑器：- 粘贴配置内容。
- 按
Ctrl+O保存。 - 按 Enter 确认文件名。
- 按
Ctrl+X退出。
^O 表示 Ctrl+O，不是输入 ^ 字符。
JSON 配置注意事项
正确的 JSON 使用英文符号：- 使用中文引号
“ ”，正确写法是英文双引号" "。 - 使用中文逗号
，，正确写法是英文逗号,。 - 最后一项后面多写了逗号。
- 不小心删除了
{、}、[或]。 - 只复制了配置的一部分。
什么是 API Key
API Key 类似服务密码，用于确认账户身份和扣除调用额度。 复制 API Key 时注意：- 不要复制前后的空格。
- 不要添加中文引号。
- 粘贴到 JSON 后，要保留原有英文双引号。
为什么修改后要重启
很多程序只在启动时读取配置。修改opencode.json 后：
- 保存配置文件。
- 完全退出 OpenCode CLI 或桌面端。
- 重新打开 OpenCode。
- 再检查模型列表。
遇到错误时怎么求助
不要只说“安装不了”。请提供以下信息：- 你的操作系统，例如 Windows 11、macOS 15 或 Ubuntu 24.04。
- 正在执行教程的哪一步。
- 输入的命令，API Key 必须用
***遮住。 - 完整错误文字或截图。
node -v、npm -v和opencode --version的输出。
安装相关名词
完成这些基础操作后，继续阅读 OpenCode 安装与配置（推荐）。