1. 为什么要把 OpenCode 机器人搬到浏览器里
OpenCode 机器人跑在终端里其实已经够用了，问答、检索、代码生成都能干活。但问题也很明显：每次给团队演示，都得对着黑底绿字的终端窗口；同事想自己试一下，得先学一堆命令行操作；想展示一张流程图或者一段高亮代码，终端里只能靠 ASCII 凑合。说白了，能力有了，但“脸”没有。
这篇要做的，就是给 OpenCode 机器人装上一张 Web 可视化交互界面。核心链路是：浏览器页面通过 HTTP 请求打到 Fastify 服务，Fastify 直接调用 QABot 核心方法，QABot 再走 OpenCode 的机制干活。整条链路跑在同一个进程里，没有额外的网络跳转，也没有序列化开销，单机部署非常省心。
适合谁看？如果你已经跟着前面的项目篇把 QABot 核心类和热加载能力跑通了，现在想给它加一个“所有人打开浏览器就能用”的入口，那这篇就是为你写的。我会把 Fastify 服务端、SSE 实时推送、热加载生效验证这三块拆开讲，配置和代码都给到能直接复制的程度。另外，AI 工具接入这块我会用 TaoToken 的统一 Key 通道来演示，这样你不需要在多个模型供应商之间来回切换配置。
先明确一下本文的产出物：一个可复制的config.toml与settings.json配置骨架、一段能跑的 SSE 事件流代码、以及热加载生效后的验证动作。跟着做，你能在本地跑通一个带会话管理、Markdown 渲染、代码高亮的 Web 聊天界面。
2. TaoToken 前置：统一 Key 与 API 通道准备
在动手写 Web 服务之前，先把 AI 工具的接入通道理顺。OpenCode 机器人要调用模型能力，传统做法是每个供应商配一套 Key，换模型就得改配置。TaoToken 的思路是提供一个统一的 API 通道，你只需要维护一份 Key，就能在模型对话、编码计划、控制台管理之间切换。
我试过把模型调用统一走 TaoToken 的 API 地址，配置项收敛得很干净。你需要准备的东西不多：一个 TaoToken 账号，然后在控制台生成 API Key。这个 Key 后面会写进 OpenCode 的配置文件里，作为模型调用的凭证。
具体操作路径是这样的：先访问官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 了解统一 Key 的接入方式，然后进控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，API Key 管理页在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。生成之后先复制保存，后面配置里要用。
API 的基础地址是 https://taotoken.net/api ，注意这个地址不带 UTM 参数，直接作为 base_url 写进配置即可。如果你后面要验证模型是否通，可以用模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite 先手动发一条消息确认 Key 有效。长期做编码和 Agent 任务的话，Coding Plan 页面 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 有更细的额度说明，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。
注意：API Key 属于敏感凭证，不要提交到 Git 仓库。建议放在环境变量或者本地配置文件里，并在
.gitignore中排除。
3. 可复制配置：config.toml 与 settings.json 骨架
配置分两块：一块是 OpenCode 机器人本身的config.toml，负责模型通道和 Web 服务参数；另一块是settings.json，负责前端界面和 SSE 行为。两块都给出骨架，你按自己的端口和路径改。
先看config.toml。这里把 TaoToken 的 API 地址和 Key 写进模型通道，同时开启 Web 服务：
# config.toml [model] # 统一走 TaoToken API 通道 provider = "taotoken" base_url = "https://taotoken.net/api" api_key = "${TAOTOKEN_API_KEY}" # 从环境变量读取，避免硬编码 model = "claude-sonnet" # 按需替换为可用模型标识 timeout = 60 [web_server] enabled = true port = 3000 host = "0.0.0.0" static_dir = "./public" enable_cors = true [hot_reload] enabled = true watch_dir = "./src/plugins" debounce_ms = 300这里有几个点值得说明。api_key用${TAOTOKEN_API_KEY}占位，实际运行时从环境变量注入，这样配置文件可以安全地进版本库。base_url固定为 TaoToken 的 API 地址，不带任何查询参数。web_server段控制 Fastify 的监听端口和静态目录，static_dir指向你放index.html的目录。
再看settings.json，这块主要给前端和 SSE 用：
{ "api": { "base": "/api", "chatEndpoint": "/api/chat", "streamEndpoint": "/api/chat/stream", "sessionsEndpoint": "/api/sessions", "statusEndpoint": "/api/status" }, "sse": { "enabled": true, "retryMs": 3000, "heartbeatMs": 15000, "eventTypes": ["start", "chunk", "end", "error", "reload"] }, "ui": { "markdown": true, "codeHighlight": true, "maxMessageWidth": "85%", "theme": "github-dark" }, "hotReload": { "notifyWeb": true, "broadcastEvent": "reload" } }settings.json里的sse.eventTypes定义了前端要监听的事件类型，后面 SSE 代码会按这个约定发事件。hotReload.notifyWeb打开后，插件热加载完成会通过 SSE 广播reload事件，前端收到后刷新状态提示，不用手动刷新页面。
提示：两个配置文件的路径建议放在项目根目录，OpenCode 启动时会按约定读取。如果你的项目结构不同，在初始化代码里显式指定路径即可。
4. Fastify 服务端与 SSE 事件流代码
配置就绪后，开始写服务端。Fastify 的注册方式和 Express 略有不同，但 API 很直观。先装依赖：
npm install fastify @fastify/static @fastify/cors然后创建src/services/web-server.ts，核心是注册路由、绑定 QABot 实例、暴露 SSE 端点。下面这段是精简后的骨架，保留了关键逻辑：
// src/services/web-server.ts import Fastify from 'fastify' import fastifyStatic from '@fastify/static' import fastifyCors from '@fastify/cors' import * as path from 'path' import * as fs from 'fs' export interface WebServerConfig { port: number host: string staticDir?: string enableCors: boolean } export class WebServer { private fastify: any private config: WebServerConfig private bot: any private isRunning = false constructor(config: Partial<WebServerConfig> = {}) { this.config = { port: 3000, host: '0.0.0.0', staticDir: path.join(process.cwd(), 'public'), enableCors: true, ...config } this.fastify = Fastify({ logger: { level: 'warn' } }) } setBot(bot: any): void { this.bot = bot } private registerRoutes(): void { // 健康检查 this.fastify.get('/api/health', async (_req: any, reply: any) => { return reply.send({ success: true, data: { status: 'ok', botInitialized: this.bot?.isInitialized || false } }) }) // 普通问答 this.fastify.post('/api/chat', async (request: any, reply: any) => { const { question, sessionId } = request.body as any if (!question || !question.trim()) { return reply.status(400).send({ success: false, error: '问题不能为空' }) } const result = await this.handleChat({ question, sessionId }) return reply.send({ success: true, data: result }) }) // SSE 流式问答 this.fastify.post('/api/chat/stream', async (request: any, reply: any) => { const { question } = request.body as any if (!question || !question.trim()) { return reply.status(400).send({ success: false, error: '问题不能为空' }) } reply.raw.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive', 'Access-Control-Allow-Origin': '*' }) const send = (type: string, payload: any = {}) => { reply.raw.write(`data: ${JSON.stringify({ type, ...payload })}\n\n`) } try { send('start') // 这里接入 OpenCode 的流式能力，逐块推送 const stream = await this.bot.streamAnswer(question) for await (const chunk of stream) { send('chunk', { content: chunk }) } send('end') } catch (err) { send('error', { error: err instanceof Error ? err.message : '未知错误' }) } finally { reply.raw.end() } }) // 会话列表、创建、切换、删除 this.fastify.get('/api/sessions', async (_req: any, reply: any) => { const sessions = await this.bot.listSessions() return reply.send({ success: true, data: sessions }) }) this.fastify.post('/api/sessions', async (request: any, reply: any) => { const { title } = request.body as any const session = await this.bot.createNewSession(title) return reply.send({ success: true, data: session }) }) // 静态文件与 CORS if (this.config.staticDir && fs.existsSync(this.config.staticDir)) { this.fastify.register(fastifyStatic, { root: this.config.staticDir, prefix: '/' }) } if (this.config.enableCors) { this.fastify.register(fastifyCors, { origin: '*', methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'] }) } } private async handleChat(req: { question: string; sessionId?: string }) { if (req.sessionId) { try { await this.bot.switchSession(req.sessionId) } catch { /* 忽略 */ } } await this.bot.saveUserMessage(req.question) const result = await this.bot.processUserInput(req.question) await this.bot.saveAssistantMessage(result.response) return { answer: result.response, sessionId: await this.bot.getCurrentSessionId(), intent: result.intent?.type } } async start(): Promise<void> { if (this.isRunning) return this.registerRoutes() await this.fastify.listen({ port: this.config.port, host: this.config.host }) this.isRunning = true } async stop(): Promise<void> { if (!this.isRunning) return await this.fastify.close() this.isRunning = false } getUrl(): string { return `http://${this.config.host}:${this.config.port}` } }SSE 这段的关键在于reply.raw.writeHead设置text/event-stream，然后每次write都按data: {...}\n\n的格式发。前端用EventSource或者fetch的流式读取都能接。注意send('start')和send('end')是成对的，前端靠这两个事件判断流是否结束。
把 WebServer 集成到 QABot 里，在initialize方法中根据配置启动：
// src/core/bot.ts 片段 if (this.config?.webServer?.enabled) { this.webServer = new WebServer({ port: this.config.webServer.port, host: this.config.webServer.host, staticDir: this.config.webServer.staticDir, enableCors: true }) this.webServer.setBot(this) await this.webServer.start() }5. 验证请求与成功结果
服务端跑起来后，先别急着开浏览器，用命令行验证接口是否通。启动 OpenCode，观察日志里是否出现 Web 服务监听提示。然后开一个终端，发一条健康检查：
curl -s http://localhost:3000/api/health | jq预期返回：
{ "success": true, "data": { "status": "ok", "botInitialized": true } }接着验证普通问答接口：
curl -s -X POST http://localhost:3000/api/chat \ -H "Content-Type: application/json" \ -d '{"question":"Fastify 和 Express 有什么区别？"}' | jq如果返回里success为true，data.answer有内容，说明 QABot 核心链路通了。再验证 SSE 流式接口，用curl的-N参数关闭缓冲：
curl -N -X POST http://localhost:3000/api/chat/stream \ -H "Content-Type: application/json" \ -d '{"question":"用一句话解释 SSE"}'你应该能看到类似这样的逐行输出：
data: {"type":"start"} data: {"type":"chunk","content":"S"} data: {"type":"chunk","content":"S"} data: {"type":"chunk","content":"E"} data: {"type":"end"}最后打开浏览器访问http://localhost:3000，应该能看到一个深色主题的聊天界面，左侧是会话列表，右侧是消息区，底部是输入框。输入一个问题，观察回复是否逐字出现，代码块是否有高亮。如果这些都正常，说明 Web 可视化交互界面已经跑通了。
6. 本篇常见错排查
报错一：端口被占用
Error: listen EADDRINUSE: address already in use :::3000原因是 3000 端口已经被其他进程占用。解决办法有两个：改配置里的web_server.port为 3001 或其他空闲端口；或者找到占用进程并结束：
lsof -i :3000 kill -9 <PID>报错二：静态文件路径不存在
Error: ENOENT: no such file or directory, stat '/project/public/index.html'说明static_dir指向的目录不存在，或者index.html没放进去。检查config.toml里的static_dir路径，确保public/目录存在且里面有入口文件。如果你不想用 Fastify 托管静态文件，也可以单独部署前端，通过 CORS 跨域调 API。
报错三：SSE 连接被缓冲，消息不实时
有些反向代理或者中间层会缓冲text/event-stream响应，导致前端收不到逐块消息。排查时先确认响应头里有Cache-Control: no-cache和Connection: keep-alive。如果前面挂了 Nginx，需要关掉对应 location 的proxy_buffering。本地直连 Fastify 一般不会有这个问题。
报错四：热加载后 Web 界面没反应
插件热加载完成，但前端状态提示没更新。检查settings.json里hotReload.notifyWeb是否为true，以及 SSE 事件类型里有没有reload。另外确认热加载管理器在 reload 成功后确实调用了广播方法。如果广播走了但前端没收到，打开浏览器开发者工具的 Network 面板，看 SSE 连接是否还活着。
报错五：模型调用返回鉴权失败
如果问答接口返回的错误里提到鉴权或 Key 无效，先确认环境变量TAOTOKEN_API_KEY是否注入成功，再确认base_url写的是https://taotoken.net/api而不是其他地址。可以到模型对话页面手动发一条消息，确认 Key 本身有效。
7. 接入文档与后续动作
Web 界面跑通之后，你手里就有了一个能演示、能协作的 OpenCode 机器人入口。接下来如果要把模型调用做得更规范，建议把 API Key 的管理和接入文档过一遍。API Key 的创建和管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有不同语言和框架的调用示例。
如果你后面要做长期编码任务或者 Agent 编排，可以看看 Coding Plan 的额度说明：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。模型对话的验证入口在 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite ，控制台在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。
最后留一个实操建议：把 SSE 的heartbeatMs设成 15000 左右，长时间没有消息时发一个心跳注释行，防止中间层把空闲连接掐掉。这个细节在本地开发时不容易暴露，但部署到有反向代理的环境后很关键。
