Open Code 文档

主题

首页文档搜索

OpenCode AI 编程助手安装实战教程 ​

📚 分类: 开发工具 ⏱️ 预计耗时: 5 分钟 🎯 难度: 入门 🔧 环境要求: 能连接互联网的电脑 (macOS / Linux / Windows)

你将学到什么 ​

完成本教程后，你将能够：

  • [ ] 在你的电脑上成功安装 OpenCode 命令行工具
  • [ ] 使用终端命令验证安装是否成功
  • [ ] 了解 OpenCode 桌面版应用的存在和用途
  • [ ] 启动 OpenCode 并体验一次免费的 AI 对话

最终效果 ​

在你的终端（Terminal）中输入 opencode --version 并按下回车后，屏幕上会显示类似 opencode x.x.x 的版本号信息。这意味着你已经成功安装了这个强大的 AI 编程助手，可以开始你的第一次 AI 对话了。

前置准备 ​

在开始前，请确认你的环境满足以下条件：

检查项要求版本验证命令
终端 (Terminal)任意在电脑上找到并打开它
网络连接可正常访问 opencode.ai在浏览器中打开该网址

1. 了解你的操作系统 ​

本教程会根据你的操作系统提供不同的安装命令。请先确定你的电脑是 macOS / Linux 还是 Windows。

  • 💡 提示: 如果不确定，可以在“关于本机”或“系统信息”中查看。

第 1 步：安装 OpenCode ​

🎯 目标：在你的电脑上运行一条命令，完成 OpenCode 的安装。

📝 操作：

首先，请打开你的终端（Terminal）应用。

  • macOS: 在“启动台” -> “其他” 中找到“终端”，或使用 Spotlight (Cmd+空格) 搜索“终端”。
  • Linux: 通常通过快捷键 Ctrl+Alt+T 打开。
  • Windows: 搜索并打开“PowerShell”或“命令提示符”。

根据你的操作系统，在终端中执行对应的命令。

如果你是 macOS 或 Linux 用户 ​

复制下面这行命令，粘贴到终端中，然后按回车键：

bash
$ curl -fsSL https://opencode.ai/install | bash

如果你是 Windows 用户 ​

Windows 推荐使用 Scoop 包管理器进行安装。如果你的电脑上已经安装了 Scoop，请直接运行：

powershell
$ scoop install opencode

如果你的电脑上没有安装 Scoop，请按以下步骤操作：

  1. 允许运行脚本：在 PowerShell 中运行以下命令（只需执行一次）：

    powershell
    $ Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

  2. 安装 Scoop：运行以下命令：

    powershell
    $ Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression

    ⚠️ 注意：如果你的 PowerShell 是以“管理员身份”运行的（窗口标题带有“管理员”字样），上面的命令会报错。你需要改用这个命令：

    powershell
    $ iex "& {$(irm get.scoop.sh)} -RunAsAdmin"

  3. 安装 Git：Scoop 需要 Git 来添加软件源，运行：

    powershell
    $ scoop install git

  4. 安装 OpenCode：最后，运行：

    powershell
    $ scoop install opencode

✅ 验证：

  • macOS/Linux 用户：应该看到终端输出以 ✓ Installation complete! 结尾的信息。
  • Windows 用户：应该看到类似 Installing 'opencode' (x.x.x) [main] 的成功提示。

第 2 步：重启终端 ​

🎯 目标：让安装程序修改的环境变量生效，使系统能识别 opencode 命令。

📝 操作：

安装脚本修改了系统的环境变量（PATH），但当前正在运行的终端窗口使用的是旧的配置。为了让新配置生效，你需要：

  1. 关闭当前终端窗口（点击窗口左上角的红色叉号，或按 Cmd+Q / Alt+F4）。
  2. 重新打开一个新的终端窗口。

💡 提示：如果你不想关闭窗口，也可以手动重新加载配置文件，但为了更稳妥，建议直接重启终端。

  • macOS/Linux (zsh):
    bash
    $ source ~/.zshrc
  • macOS/Linux (bash):
    bash
    $ source ~/.bashrc

第 3 步：验证安装 ​

🎯 目标：确认 OpenCode 已经成功安装，并且可以被终端调用。

📝 操作：

在新的终端窗口中，输入以下命令并按回车：

bash
$ opencode --version

✅ 验证：

你应该会看到类似如下的输出：

text
opencode x.x.x

其中 x.x.x 是具体的版本号（例如 1.2.20）。只要能正常显示版本号，就说明安装成功了！

🎉 恭喜！你已经成功安装了 OpenCode！

第 4 步：体验首次对话（可选） ​

🎯 目标：启动 OpenCode，并使用其内置的免费模型进行一次 AI 对话，快速感受它的能力。

📝 操作：

  1. 在终端中输入以下命令并回车，启动 OpenCode：

    bash
    $ opencode

  2. OpenCode 启动后，你会进入它的交互界面。在输入框中输入 /models 并按回车，查看可用的模型列表。

  3. 找到一个名称带有 -free 后缀的模型（如 opencode/glm-4.7-free）。这就是免费模型，无需注册账号或 API Key。

  4. 在输入框中输入你想要问的问题，例如：

    text
    用 Python 写一个打印 "Hello, World!" 的程序。

    然后按回车发送消息。

✅ 验证：OpenCode 应该会调用 AI 模型并生成相应的 Python 代码回复。这证明你的安装和网络连接都是正常的。

进阶技巧（可选） ​

安装桌面版应用 ​

OpenCode 也提供图形界面的桌面版应用，适合需要长时间后台运行或偏好窗口化操作的用户。

平台下载方式
macOS (Apple Silicon)下载 opencode-desktop-darwin-aarch64.dmg
macOS (Intel)下载 opencode-desktop-darwin-x64.dmg
Windows下载 opencode-desktop-windows-x64.exe
Linux下载 .deb / .rpm 或 AppImage 文件

包管理器安装：

  • macOS:
    bash
    $ brew install --cask opencode-desktop
  • Windows:
    powershell
    $ scoop bucket add extras
$ scoop install extras/opencode-desktop

💡 建议：你可以同时安装终端版和桌面版。日常编码使用终端版（效率更高），需要长时间运行任务时使用桌面版（可以最小化，任务完成时会发送系统通知）。

常见问题 (FAQ) ​

Q1: 安装时提示 command not found: curl 怎么办？A: 你的系统缺少 curl 工具。macOS 和大多数 Linux 系统自带，Windows 用户可能需要安装。建议尝试使用其他安装方式，如 Windows 的 Scoop 或直接下载桌面版。

Q2: 安装后输入 opencode --version 提示 command not found 怎么办？A: 这说明环境变量未生效。请确保你已经重启了终端。如果问题依旧，尝试手动执行 source ~/.zshrc (或 source ~/.bashrc)。如果仍然不行，可能需要检查安装脚本是否成功将 OpenCode 的路径添加到了你的 shell 配置文件中。

Q3: 安装时出现网络超时或下载失败怎么办？A: 你的网络可能无法稳定访问 OpenCode 的下载服务器。请尝试：

  1. 更换网络环境（例如切换到手机热点）。
  2. 稍后再试，可能是服务器临时问题。
  3. 使用其他安装方式，如通过 Git 源码安装（请参考官方文档）。

Q4: 如何卸载 OpenCode？A: 删除安装目录即可。通常，安装脚本会将 OpenCode 安装到 ~/.opencode/bin/ 目录下。你可以运行 rm -rf ~/.opencode 来卸载。如果你使用的是 Scoop，运行 scoop uninstall opencode。

总结 ​

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

  1. 一键安装：根据操作系统选择合适的命令，即可快速完成 OpenCode 的安装。
  2. 环境配置：安装后需要重启终端，让 PATH 环境变量生效。
  3. 验证安装：通过 opencode --version 命令确认安装成功。
  4. 快速体验：启动 OpenCode 并使用免费模型，感受 AI 编程助手的强大功能。

下一步 ​

你已经成功迈出了第一步！接下来，你可以：

  • 📖 配置网络与模型：学习如何连接你专属的 AI 模型（如智谱、DeepSeek、GPT 等），发挥 OpenCode 的全部潜力。
  • 📖 学习 Git 入门：掌握如何将 OpenCode 与 Git 工作流结合，实现 AI 驱动的代码版本管理。

💡 练习任务：尝试用 OpenCode 改写一段你之前写过的代码，比如给它增加注释或重构为一个函数。这是熟悉 AI 交互的最佳方式。

yaml

## 相关文档

- [OpenCode 实战教程：从零配置到免费接入顶级 AI 模型](/docs/huan-jing-da-jian/opencode-shi-zhan-jiao-cheng-cong-ling-pei-zhi-dao-mian-fei-jie-ru-ding-ji-ai-mo-xing.html)
- [OpenCode 备用安装方式实战教程](/docs/huan-jing-da-jian/opencode-bei-yong-an-zhuang-fang-shi-shi-zhan-jiao-cheng.html)

Open Code 文档社区

© 2026 Open Code. All rights reserved.