LowHow 文档

中文

English

中文

English

深色模式

OpenCode Web 界面启动与配置教程：浏览器中使用 AI 编码助手 ​

📚 分类: 工具配置与使用 ⏱️ 预计耗时: 15 分钟 🎯 难度: 入门 🔧 环境要求: 已安装 OpenCode CLI 工具，并完成基础配置

你将学到什么 ​

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

  • [ ] 使用一条命令在浏览器中启动 OpenCode 的 Web 界面
  • [ ] 配置端口、主机名和密码，确保服务安全且可访问
  • [ ] 在本地网络中通过 mDNS（多播 DNS）自动发现你的 OpenCode 服务
  • [ ] 同时使用 Web 界面和终端 TUI（文本用户界面）进行协同工作

最终效果 ​

你将能够在浏览器中打开一个功能完整的 AI 编码界面，像使用专业 IDE 一样与 AI 进行对话、管理代码会话，并查看后端服务器的运行状态。

前置准备 ​

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

检查项要求验证命令
OpenCode CLI已安装opencode --version
网络环境正常-

1. 确认 OpenCode CLI 已安装 ​

如果你还没有安装 OpenCode，请先根据其官方文档完成安装。

bash
$ opencode --version    // 验证 OpenCode 是否已安装

✅ 验证：如果看到类似 opencode version x.y.z 的输出，说明安装成功。

第 1 步：启动 Web 界面（基础模式） ​

🎯 目标：在本地启动 OpenCode 的 Web 服务，并在浏览器中打开它。

📝 操作：

打开你的终端，输入以下命令：

bash
$ opencode web

🤔 为什么要这样做？opencode web 命令会启动一个轻量级的 Web 服务器。默认情况下，它会绑定到 127.0.0.1（即你的本机），并自动选择一个未被占用的端口。

✅ 验证： 执行命令后，你应该会看到类似以下的输出，并且你的默认浏览器会自动打开一个新标签页：

text
OpenCode Web interface is running on http://127.0.0.1:XXXXX

其中 XXXXX 是一个随机端口号（例如 4096、8080 等）。

⚠️ 常见错误与安全警告：

  • 错误：端口被占用：如果你看到 Error: listen EADDRINUSE :::XXXXX，说明该端口已被其他程序占用。解决方法见第 2 步。
  • 安全警告：此时你启动的服务器没有密码保护。这意味着局域网内任何知道你 IP 的人都可以访问。强烈建议在下一步中设置密码。

第 2 步：配置端口与主机名 ​

🎯 目标：手动指定端口，并使服务在局域网内可被其他设备访问。

📝 操作：

  1. 指定端口：如果你不想用随机端口，或者需要固定端口（例如用于调试），可以使用 --port 参数。

    bash
    $ opencode web --port 4096

  2. 允许局域网访问：默认的 127.0.0.1 只允许本机访问。要让同一局域网内的其他电脑或手机也能访问，需要将主机名设置为 0.0.0.0。

    bash
    $ opencode web --port 4096 --hostname 0.0.0.0

✅ 验证： 执行后，终端输出会变为：

text
Local access: http://localhost:4096
Network access: http://192.168.1.100:4096

你现在可以在局域网内的任何设备上，用 http://192.168.1.100:4096 这个地址访问你的 OpenCode 服务了。

⚠️ 常见错误： 如果你在另一台设备上无法访问，请检查你的电脑防火墙设置，确保 4096 端口是放行的。

第 3 步：设置密码保护（安全加固） ​

🎯 目标：为你的 Web 界面设置密码，防止未经授权的访问。

📝 操作：

OpenCode 通过环境变量 OPENCODE_SERVER_PASSWORD 来设置密码。你需要在启动 Web 服务之前设置它。

bash
# 设置密码（请将 'your_strong_password' 替换为你自己的密码）
$ export OPENCODE_SERVER_PASSWORD='your_strong_password'

# 然后启动服务
$ opencode web --port 4096 --hostname 0.0.0.0

💡 提示：

  • 默认的用户名是 opencode。如果你想修改，可以设置环境变量 OPENCODE_SERVER_USERNAME：export OPENCODE_SERVER_USERNAME='myuser'。
  • Windows 用户请注意：在 PowerShell 中，设置环境变量的命令不同：
    powershell
    $env:OPENCODE_SERVER_PASSWORD='your_strong_password'

✅ 验证： 重新在浏览器中访问 http://192.168.1.100:4096（或你的局域网地址）。你应该会看到一个登录页面，需要输入用户名和密码才能进入。

第 4 步：启用 mDNS 自动发现（可选） ​

🎯 目标：让局域网内的设备能自动发现你的 OpenCode 服务，无需手动输入 IP 地址。

📝 操作：

mDNS（多播 DNS）可以让你的服务在本地网络中被广播。启用它非常简单：

bash
$ opencode web --mdns

💡 提示：

  • 启用 --mdns 后，OpenCode 会自动将主机名设置为 0.0.0.0，并将服务广播为 opencode.local。
  • 如果你在同一网络中有多个 OpenCode 实例，可以通过 --mdns-domain 参数自定义域名来区分它们：
    bash
    $ opencode web --mdns --mdns-domain myproject.local

✅ 验证： 现在，你可以在局域网内的其他设备（如 Mac 或 iOS 设备）上，直接在浏览器中输入 http://opencode.local 来访问你的服务，而不需要知道 IP 地址。

第 5 步：使用 Web 界面并连接终端 ​

🎯 目标：熟悉 Web 界面的核心功能，并学习如何将终端 TUI（文本用户界面）连接到同一个会话。

📝 操作：

  1. 探索 Web 界面：

    • 主页：启动后，你会看到主页，可以创建新的会话或查看已有的活跃会话。
    • 服务器状态：点击 “See Servers” 按钮，可以查看已连接的 AI 模型服务器及其状态。

  2. 同时使用终端：OpenCode 的一大特色是，你可以在一个终端运行 Web 界面，在另一个终端使用 TUI 连接到同一个服务，共享会话状态。

    bash
    # 终端 1: 启动 Web 服务器
$ opencode web --port 4096

# 终端 2: 连接到正在运行的 Web 服务器
$ opencode attach http://localhost:4096

✅ 验证： 在终端 2 中执行 opencode attach 后，你会进入 OpenCode 的 TUI 模式。你可以在 Web 界面中开始一个对话，然后在终端 TUI 中看到相同的对话历史，反之亦然。

进阶技巧（可选） ​

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

  1. 配置 CORS（跨域资源共享）：如果你在开发一个自定义前端，并想让它跨域访问你的 OpenCode 服务，可以使用 --cors 参数添加允许的域名：
    bash
    $ opencode web --cors https://your-frontend.com
  2. 使用配置文件：为了避免每次启动都输入一堆参数，你可以将配置写在 opencode.json 文件中：
    json
    {
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "cors": ["https://example.com"]
  }
}
    注意：命令行标志的优先级高于配置文件中的设置。

常见问题 (FAQ) ​

Q1: 报错 command not found: opencode 怎么办？A: 这说明 OpenCode 没有正确安装或没有添加到 PATH 环境变量中。请重新安装或检查你的安装步骤。

Q2: 我设置了密码，但网页还是可以直接访问，没有弹出登录框？A: 请确保你在同一个终端会话中先设置了环境变量，再启动了 opencode web。如果你关闭了终端或在新终端中启动，需要重新设置环境变量。

Q3: 如何在 Windows 上获得最佳体验？A: 官方文档建议，Windows 用户最好从 WSL (Windows Subsystem for Linux， Windows 子系统 for Linux) 中而非 PowerShell 中运行 opencode web。这可以确保正确的文件系统访问和终端集成。

总结 ​

恭喜你完成了本教程！🎉

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

  1. 启动 Web 界面：使用 opencode web 命令，即可在浏览器中体验 AI 编码。
  2. 网络配置：通过 --port 和 --hostname 参数，你可以精确控制服务的监听地址和端口。
  3. 安全加固：使用 OPENCODE_SERVER_PASSWORD 环境变量为服务设置密码，是保护数据安全最重要的一步。
  4. 便捷发现：--mdns 参数让你的服务在局域网内自动可见，省去了手动输入 IP 的麻烦。
  5. 协同工作：Web 界面和终端 TUI 可以连接到同一个会话，提供灵活的工作方式。

© 2026 LowHow