LowHow 文档

中文

English

中文

English

深色模式

在 Windows (WSL) 上安装配置 OpenCode 实战教程 ​

📚 分类: 环境搭建与配置 ⏱️ 预计耗时: 15 分钟 🎯 难度: 入门 🔧 环境要求: Windows 10（版本 2004 及以上）或 Windows 11，BIOS 中已启用虚拟化技术

你将学到什么 ​

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

  • [ ] 在 Windows 上安装并配置 WSL 2（Windows Subsystem for Linux）
  • [ ] 在 WSL 环境中成功安装 OpenCode
  • [ ] 从 WSL 访问 Windows 文件系统
  • [ ] 通过桌面应用或 Web 浏览器连接到 WSL 中的 OpenCode 服务

最终效果 ​

你将拥有一个配置完善的 WSL 环境，并且可以在其中运行 OpenCode 服务。你可以通过桌面应用或 Windows 浏览器访问它，实现跨平台无缝开发。你将看到类似以下提示信息：

text
OpenCode server is running on http://localhost:4096

前置准备 ​

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

检查项要求版本验证方法
Windows 系统Windows 10 版本 2004（内部版本 19041）及更高版本，或 Windows 11设置 > 系统 > 关于
虚拟化支持BIOS/UEFI 中已启用虚拟化技术任务管理器 > 性能 > CPU，查看"虚拟化"是否已启用

💡 提示：如果你不确定是否满足条件，请先尝试安装 WSL。如果安装过程中遇到错误，可以根据错误提示进行排查。

第 1 步：安装 WSL ​

🎯 目标：在你的 Windows 系统上安装并启用 WSL 2。

📝 操作：

  1. 右键点击"开始"按钮，选择"Windows PowerShell (管理员)"或"终端(管理员)"，以管理员身份打开终端。

  2. 在打开的窗口中，复制并粘贴以下命令，然后按回车键执行：

bash
# 安装 WSL 2 并下载 Ubuntu 发行版
$ wsl --install -d Ubuntu

这个命令会自动完成以下操作：

  • 启用 WSL 功能
  • 安装 WSL 2 内核
  • 下载并安装 Ubuntu Linux 发行版

✅ 验证： 执行完命令后，系统会提示你重启计算机。重启后，WSL 安装完成。下次启动时，Ubuntu 会自动完成初始化。

💡 提示：

  • 如果你想安装其他 Linux 发行版（如 Debian、Kali），可以将命令中的 Ubuntu 替换为其他名称。例如：wsl --install -d Debian。
  • 如果命令执行失败，请参考 Microsoft 官方文档：安装 WSL。

⚠️ 常见错误： 如果出现错误 0x80070003 或 0x80370102，说明 BIOS 中的虚拟化技术未启用。请重启电脑进入 BIOS 设置，找到"Intel Virtualization Technology"（Intel VT-x）或"AMD Virtualization"（AMD-V）选项，将其设置为"Enabled"后保存退出。

第 2 步：初始化 WSL 并设置用户名密码 ​

🎯 目标：完成 WSL 的首次启动，并创建一个 Linux 用户。

📝 操作：

  1. 重启电脑后，WSL 会自动启动。或者，你也可以在开始菜单中找到并打开 Ubuntu 应用。

  2. 首次启动时，WSL 会要求你设置一个 Linux 用户名和密码。

    • 用户名：建议使用小写字母，例如 yourname。
    • 密码：输入密码时不会显示任何字符，这是正常现象。输入完成后按回车键即可。
bash
# 首次启动 WSL 的界面示例
Installing, this may take a few minutes...
Please create a default UNIX user account.
Username: yourname
Password:

✅ 验证： 设置完成后，你会看到类似以下命令行提示符，表示你已经成功登录到 WSL 的 Linux 环境：

bash
yourname@YourComputer:~$

第 3 步：在 WSL 中安装 OpenCode ​

🎯 目标：在你的 WSL 环境中安装 OpenCode 工具。

📝 操作：

  1. 确保你已经在 WSL 终端中（提示符为 $ 或 ~$）。

  2. 执行以下命令来安装 OpenCode：

bash
# 使用官方安装脚本安装 OpenCode
$ curl -fsSL https://opencode.ai/install | bash

这个命令会从 OpenCode 官网下载并运行安装脚本。

  1. 安装完成后，重新加载 shell 配置文件，使 OpenCode 命令生效：
bash
# 重新加载 shell 配置文件
$ source ~/.bashrc

✅ 验证： 执行以下命令，如果看到 OpenCode 的版本号，说明安装成功：

bash
# 验证 OpenCode 是否安装成功
$ opencode --version
# 预期输出：opencode version x.x.x

⚠️ 常见错误： 如果提示 curl: command not found，说明你的 WSL 环境中没有安装 curl。执行以下命令安装它：

bash
$ sudo apt update && sudo apt install curl -y

安装完 curl 后，重新执行第 2 步的安装命令。

第 4 步：从 WSL 访问 Windows 文件 ​

🎯 目标：学会如何在 WSL 中访问你的 Windows 文件，例如 C: 盘或 D: 盘中的项目。

📝 操作：

WSL 将你的 Windows 驱动器自动挂载到 /mnt/ 目录下。你可以像在 Linux 中一样访问它们。

bash
# 切换到 C: 盘的用户目录（将 YourName 替换为你的 Windows 用户名）
$ cd /mnt/c/Users/YourName/project

# 查看当前目录下的文件
$ ls

# 如果你想导航到 D: 盘
$ cd /mnt/d/MyProject

✅ 验证： 执行 pwd 命令，你应该看到路径以 /mnt/ 开头，例如 /mnt/c/Users/YourName/project。

🤔 为什么要这样做？ 因为 WSL 和 Windows 共享文件系统，你可以直接在 WSL 中编辑、运行 Windows 驱动器上的项目，而无需复制文件。这非常方便。

⚠️ 性能提示： 虽然可以访问 Windows 文件，但为了获得最佳性能，建议将你的项目仓库克隆或复制到 WSL 的文件系统中（例如 ~/code/ 目录下），然后在 WSL 中运行 OpenCode。WSL 对 Linux 文件系统的访问速度远快于跨文件系统访问。

bash
# 在 WSL 中创建一个项目目录（推荐）
$ mkdir -p ~/code/my-project
$ cd ~/code/my-project

第 5 步：启动 OpenCode 服务 ​

🎯 目标：在你的 WSL 环境中启动 OpenCode 服务，以便通过桌面应用或 Web 浏览器访问。

📝 操作：

方式一：仅启动服务器（供桌面应用连接）

在 WSL 终端中执行以下命令：

bash
# 启动 OpenCode 服务器，监听所有网络接口
$ opencode serve --hostname 0.0.0.0 --port 4096
  • --hostname 0.0.0.0：允许来自任何 IP 地址的连接（包括 Windows 主机）。
  • --port 4096：指定服务端口。

方式二：启动 Web 客户端（供浏览器访问）

在 WSL 终端中执行以下命令：

bash
# 启动 OpenCode Web 客户端
$ opencode web --hostname 0.0.0.0

✅ 验证：

  • 对于 opencode serve：终端会输出类似 OpenCode server is running on http://localhost:4096 的信息。
  • 对于 opencode web：终端会输出一个 URL，例如 http://localhost:8080。

⚠️ 安全警告： 当使用 --hostname 0.0.0.0 时，你的服务将对局域网内所有设备开放。为了保护你的服务器，强烈建议设置一个密码：

bash
# 设置密码并启动服务器
$ OPENCODE_SERVER_PASSWORD=your-password opencode serve --hostname 0.0.0.0 --port 4096

将 your-password 替换为你自己的密码。

第 6 步：从 Windows 连接到 WSL 中的 OpenCode ​

🎯 目标：从你的 Windows 系统（桌面应用或浏览器）连接到 WSL 中运行的 OpenCode 服务。

📝 操作：

通过桌面应用连接：

  • 在你的 Windows 桌面上启动 OpenCode 桌面应用。
  • 在连接设置中，输入 http://localhost:4096（或你在上一步中指定的端口）。
  • 如果设置了密码，在提示时输入密码。

通过 Web 浏览器连接：

  • 打开你的 Windows 浏览器（如 Chrome、Edge）。
  • 在地址栏输入 http://localhost:8080（或你在 opencode web 命令中看到的 URL）。
  • 如果设置了密码，在提示时输入密码。

💡 提示：如果 localhost 在你的环境中无法使用，请尝试使用 WSL 的 IP 地址。在 WSL 终端中运行以下命令来获取 IP 地址：

bash
# 获取 WSL 的 IP 地址
$ hostname -I

然后在 Windows 浏览器中访问 http://<wsl-ip>:4096 或 http://<wsl-ip>:8080。

✅ 验证： 你应该能够看到 OpenCode 的界面或编辑器，表明连接成功。

进阶技巧（可选） ​

掌握基础后，你可以尝试：

  1. 搭配 VS Code：安装 VS Code 的 WSL 扩展 (ms-vscode-remote.remote-wsl)。这样你可以直接在 VS Code 中打开 WSL 内的项目，并使用 VS Code 的所有功能。

  2. 配置存储位置：OpenCode 的配置和会话数据存储在 WSL 环境中的 ~/.local/share/opencode/ 目录下。你可以根据需要备份或迁移这些数据。

常见问题 (FAQ) ​

Q1: 安装 WSL 时出现错误 0x80070003 或 0x80370102？A: 这通常是因为 BIOS/UEFI 中的虚拟化技术未启用。请重启电脑进入 BIOS 设置，找到"Intel Virtualization Technology"（Intel VT-x）或"AMD Virtualization"（AMD-V）选项，并将其设置为"Enabled"。保存设置并重启后重试。

Q2: 安装 OpenCode 时提示 curl: command not found？A: 你的 WSL 环境中没有安装 curl。执行以下命令安装它：

bash
$ sudo apt update && sudo apt install curl -y

Q3: 无法通过 localhost 连接到 OpenCode 服务？A: 尝试使用 WSL 的 IP 地址。在 WSL 终端中运行 hostname -I 获取 IP，然后在 Windows 浏览器中访问 http://<wsl-ip>:<port>。

Q4: 忘记 WSL 的密码了怎么办？A: 你可以重置 WSL 的密码。在 PowerShell（管理员）中执行 wsl --user root 进入 WSL 的 root 用户，然后使用 passwd yourname 命令重置密码。

总结 ​

恭喜你完成了本教程！🎉

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

  1. WSL 环境搭建：学会了在 Windows 上安装和初始化 WSL 2。
  2. OpenCode 安装：在 WSL 中成功安装了 OpenCode。
  3. 文件访问：掌握了从 WSL 访问 Windows 文件系统的方法。
  4. 服务连接：学会了启动 OpenCode 服务并通过桌面应用或浏览器进行连接。

© 2026 LowHow