OpenCode Web 界面启动与配置教程
📚 分类: 工具配置 ⏱️ 预计耗时: 15 分钟 🎯 难度: 入门 🔧 环境要求: 已安装 OpenCode CLI 工具，并有一个可用的终端
你将学到什么
完成本教程后，你将能够：
- [ ] 在浏览器中启动 OpenCode 的 Web 界面
- [ ] 配置 Web 服务器的端口、主机名和密码
- [ ] 在同一网络中的其他设备上访问你的 OpenCode 服务
- [ ] 同时使用 Web 界面和终端 TUI 管理同一个会话
最终效果
你将能在浏览器中打开一个功能完整的 OpenCode 界面，无需在终端中操作，即可获得同样强大的 AI 编码体验。你将看到一个会话管理页面，并能创建、查看和管理 AI 编码会话。
前置准备
在开始前，请确认你的环境满足以下条件：
| 检查项 | 要求 | 验证命令 |
|---|---|---|
| OpenCode CLI | 已安装 | opencode --version |
| 网络连接 | 可用 | ping 8.8.8.8 |
1. 确认 OpenCode 安装
$ opencode --version // 验证 OpenCode 是否安装成功✅ 验证：如果看到类似 opencode version x.x.x 的输出，说明安装成功。
💡 提示：如果你还没有安装 OpenCode，请先访问 OpenCode 官方文档 完成安装。
第 1 步：启动 Web 界面
🎯 目标：在本地启动 OpenCode 的 Web 服务器，并自动在浏览器中打开界面。
📝 操作：
打开你的终端（在 Windows 上，建议使用 WSL 终端以获得最佳体验），然后运行以下命令：
$ opencode web✅ 验证： 执行后，终端将输出类似以下信息：
Local access: http://localhost:XXXX同时，你的默认浏览器应该会自动打开并显示 OpenCode 的 Web 界面。
💡 提示：
XXXX是一个随机分配的可用端口号，每次启动可能不同。
第 2 步：设置访问密码（安全保护）
🎯 目标：为你的 Web 服务器设置一个密码，防止未经授权的访问。
📝 操作：
首先，停止上一步中正在运行的 Web 服务器（在终端中按
Ctrl + C）。设置环境变量
OPENCODE_SERVER_PASSWORD并重新启动服务器。bash# 设置密码，请将 'your-secret-password' 替换为你自己的密码 $ export OPENCODE_SERVER_PASSWORD=your-secret-password # 使用密码保护启动服务器 $ opencode web
✅ 验证： 启动后，打开浏览器访问 http://localhost:XXXX。你应该会看到一个登录页面，要求输入用户名和密码。
- 用户名: 默认为
opencode - 密码: 你刚才设置的
your-secret-password
输入正确的凭据后，你将成功进入 Web 界面。
🤔 为什么要这样做？ 如果不设置密码，任何能访问你电脑网络的人都可以直接使用你的 OpenCode 服务，存在安全隐患。设置密码可以确保只有你知道的授权用户才能访问。
⚠️ 常见错误：
- 问题：找不到
export命令。- 解决方案：
export是 Linux/macOS 的命令。如果你在 Windows 的 PowerShell 中，请使用$env:OPENCODE_SERVER_PASSWORD="your-secret-password"。如果你在 Windows 的命令提示符中，请使用set OPENCODE_SERVER_PASSWORD=your-secret-password。
- 解决方案：
第 3 步：配置端口和主机名（网络访问）
🎯 目标：指定一个固定端口，并让 OpenCode 在同一局域网内的其他设备上可以被访问。
📝 操作：
再次停止正在运行的服务器（
Ctrl + C）。使用
--port和--hostname标志启动服务器。bash$ opencode web --port 4096 --hostname 0.0.0.0
✅ 验证： 启动后，终端输出会显示两个访问地址：
Local access: http://localhost:4096
Network access: http://192.168.1.100:4096 // 你的IP地址可能不同现在，在同一局域网内的其他设备（如手机、另一台电脑）的浏览器中，输入 http://192.168.1.100:4096，并输入之前设置的密码，即可访问你的 OpenCode 服务。
🤔 为什么要这样做？
--port 4096：我们指定了端口为4096，这样每次启动地址都是固定的，方便记忆和配置。--hostname 0.0.0.0：默认情况下，服务器只监听本地地址 (127.0.0.1)，这意味着只有你本机可以访问。设置为0.0.0.0可以让服务器监听所有网络接口，从而允许局域网内的其他设备连接。
💡 提示：你可以使用
--mdns标志来启用 mDNS 发现，这样你的服务器会在本地网络中被自动发现为opencode.local，无需手动输入 IP 地址。
第 4 步：使用配置文件管理设置
🎯 目标：将常用的服务器配置写入文件，避免每次启动都输入一长串命令。
📝 操作：
在 OpenCode 的项目根目录或用户主目录下，创建或编辑 opencode.json 文件，并添加以下内容：
{
"server": {
"port": 4096, // 固定端口
"hostname": "0.0.0.0", // 允许网络访问
"mdns": true, // 启用 mDNS 发现
"cors": ["https://example.com"] // 允许跨域访问的自定义域名
}
}保存文件后，启动服务器：
$ opencode web✅ 验证： 服务器将自动读取配置文件中的设置，并按照 4096 端口、0.0.0.0 主机名启动。你可以通过 http://localhost:4096 或 http://opencode.local 访问。
💡 提示：命令行标志的优先级高于配置文件。例如，如果你在配置文件中设置了
port: 4096，但在命令行中使用了--port 5000，那么服务器将使用5000端口。
进阶技巧（可选）
掌握基础后，你可以尝试：
同时使用 Web 界面和终端 TUI： 在一个终端中启动 Web 服务器：
bash$ opencode web --port 4096在另一个终端中，连接到同一个服务器：
bash$ opencode attach http://localhost:4096这样，你可以在浏览器和终端中共享同一个会话，操作非常灵活。
自定义 mDNS 域名： 在同一网络中运行多个 OpenCode 实例时，可以使用不同的 mDNS 域名来区分它们：
bash$ opencode web --mdns --mdns-domain myproject.local
常见问题 (FAQ)
Q1: 启动时提示 command not found: opencode 怎么办？A: 说明 OpenCode 没有正确安装或没有添加到系统 PATH 中。请重新安装或手动将 OpenCode 的安装目录添加到 PATH 环境变量。
Q2: 设置密码后，浏览器访问时一直提示密码错误？A: 检查你是否正确设置了环境变量。另外，注意密码中不要有空格。如果问题依旧，可以尝试重启终端或电脑后重试。
Q3: 如何修改 Web 界面的默认用户名？A: 通过 OPENCODE_SERVER_USERNAME 环境变量设置。例如：
$ export OPENCODE_SERVER_USERNAME=myadmin
$ opencode webQ4: 我想让其他人在公网上访问我的 OpenCode，应该怎么做？A: 这涉及到网络安全和端口转发，超出了本教程的范围。强烈建议不要直接在公网上暴露未加密的 OpenCode 服务。你应该使用反向代理（如 Nginx）并配置 HTTPS 和更强的身份验证。请参考 OpenCode 的企业版文档。
总结
恭喜你完成了本教程！🎉
回顾一下我们今天学到的核心内容：
- 启动 Web 界面：通过
opencode web命令，可以快速在本地启动一个基于浏览器的 OpenCode 界面。 - 安全配置：通过设置
OPENCODE_SERVER_PASSWORD环境变量，可以保护你的服务器不被未授权访问。 - 网络访问：通过
--port和--hostname参数，可以固定端口并允许局域网内的其他设备连接。 - 配置文件：使用
opencode.json文件可以持久化你的服务器配置，简化启动流程。
下一步
如果你想继续深入，建议学习：
- 📖 [OpenCode 终端 TUI 教程]：学习如何在终端中使用 OpenCode 的全部功能。
- 📖 [OpenCode 配置文件详解]：了解
opencode.json文件中所有可用的配置项。
💡 练习任务：尝试修改本教程的配置，将端口改为
8080，并启用 mDNS 发现。然后，用你的手机浏览器访问该服务。这是巩固知识的最佳方式。
## 相关文档
- [OpenCode 对话分享实战教程](/docs/jie-mian-cao-zuo/opencode-dui-hua-fen-xiang-shi-zhan-jiao-cheng.html)