1. 项目概述本项目旨在构建一个具备实时交互能力的 AI 数字人智能体系统结合 Coze 智能体平台与 Live2D 数字人渲染项目实现自然语言理解、知识问答、情绪响应与视觉化数字人展示。本文围绕工单“全栈开发-网约车-数字人Coze智能体任务工单”的实战内容重点记录三个核心键路OpenClaw 中的人物切换、Coze 智能体对接以及音色配置与情感调优。1.1 技术栈概览层面技术选型智能体平台Coze插件 工作流 知识库后端服务Go (net/http) 作为 Coze 转发层不暴露 Token前端框架Next.js React TypeScript Vite3D 动画渲染Live2D Cubism SDK WebGL语音模块Coze TTS API Web Speech API 降级通信协议WebSocket SSE RESTful API状态管理Zustand (persist)1.2 系统架构整体链路为浏览器前端 → Go 后端 → Coze 发布 API。其中 Go 后端作为安全中间层负责保管 Coze Token、转发流式响应、提供 TTS/ASR 服务。前端通过 SSE 流式接收智能体回复并将文本分句后通过 Coze TTS 转为音频再驱动 Live2D 模型的口型同步与表情变化。2. OpenClaw 人物切换OpenClaw 提供了 persona-switch 技能支持在预设人设与自定义人设之间自由切换。在数字人场景中人物切换可以让同一个数字人展现不同的“人格”——例如从品牌代言人切换到虚拟讲解员。2.1 人设文件结构OpenClaw 的人设存储在 SOUL.md 文件中通过 persona-switch 技能可以定义多套预设人设# 预设人设一品牌代言人- 风格专业、亲切、品牌化- 角色某品牌官方虚拟代言人- 语言正式但不死板可加入 emoji# 预设人设二虚拟讲解员- 风格知识型、引导性、教育性- 角色景区智能导览- 语言简洁、信息密度高2.2 人物切换与 Live2D 联动在数字人场景中人物切换不仅是文本风格的变化还可以联动 Live2D 模型切换。前端存储了当前所有可用的 Live2D 角色用户在“设置 → 角色”面板中切换后系统会重新加载对应的 .model3.json并重置聊天记录。切换时的关键代码逻辑建议在 Coze 智能体层面配合人设设置不同的角色可以对应不同的知识库和提示词使得切换人物后整体交互体验一致。3. Coze 智能体对接实战3.1 架构设计为什么需要 Go 转发层直接从前端调用 Coze API 会暴露 Token存在安全风险。因此我们引入了 Go 后端作为中间转发层Token 安全仅从环境变量读取不落盘到任何源码文件协议透明前端发送标准 JSONGo 转换为 Coze 格式后转发音色统一TTS 由 Go 后端调用 Coze 音频接口确保数字人声音一致降级策略TTS 失败时自动降级到浏览器 Web Speech API3.2 Go 后端核心实现环境配置SSE 流式对话转发前端通过 fetchEventSource 发起 POST 请求Go 后端接收后调用 Coze 对话 API并将 SSE 事件流转发给前端Coze 发布页 stream_run 兼容当通过 Coze 发布页部署时请求体格式与 API 直调不同需要包装为 stream_run 格式判断逻辑如果 COZE_CHAT_URL 中包含 /stream_run 或 .coze.site则自动使用 stream_run 模式否则使用 API v3 直调模式。3.3 前端对接实现Agent 流式调用前端通过 api_agent_stream 函数发起 SSE 请求并在回调中处理不同类型的事件事件类型包括CONVERSATION_ID、MESSAGE_ID、THINK、TEXT、DONE、ERROR。其中 THINK 事件对应 Coze 的推理过程TEXT 事件对应最终回复内容。流式事件处理与 TTS 联动3.4 OpenClaw 中配置 Coze 代理在 OpenClaw 中配置 Coze 智能体代理时“代理功能描述”应包含以下关键信息智能体名称内部HR问答助手智能体ID7655620274246926388智能体平台Coze插件 工作流 知识库通信协议SSE流式响应通过 Go 服务端转发能力范围自然语言理解、多轮对话、知识检索、情绪响应、动作指令下发安全策略Token仅存储在Go服务端环境变量前端不保存任何密钥4. 音色配置与情感调优数字人的语音是用户体验的核心。本项目采用 Coze TTS API 作为主要语音引擎支持自定义音色和情感参数。4.1 音色自动解析策略Go 后端实现了智能音色解析链前端显式指定用户在设置面板输入 voice_id优先级最高环境变量 COZE_VOICE_ID服务端默认音色智能体音色查询调用 GET /v1/bots/{bot_id} 获取智能体配置的音色账号音色查询调用 GET /v1/audio/voices 优先选择非系统音色降级所有方式都失败时前端自动使用浏览器 Web Speech API4.2 音色解析代码func (c *Client) resolveVoiceID(ctx, overrideVoiceID) (string, error) {// 1. 前端 override 优先if overrideVoiceID ! { return overrideVoiceID, nil }// 2. 环境变量if c.cfg.VoiceID ! { return c.cfg.VoiceID, nil }// 3. 查询 Bot 音色if c.cfg.BotID ! {voiceID, err : c.lookupBotVoiceID(ctx)if err nil { return voiceID, nil }}// 4. 查询账号可用音色优先非系统return c.lookupAvailableVoiceID(ctx)}4.3 情感参数配置Coze TTS API 支持多种情感语调情感参数值适用场景开心happy欢迎语、正面反馈悲伤sad逗乐、遗憾回复生气angry投诉场景、严肃提醒惊讶surprised意外情况、惊喜回复恐惧fear风险提示讨厌hate负面事件关怀兴奋excited活动宣传、促销冷漠coldness正式通知、官方声明中性neutral普通对话、日常交流4.4 前端音色设置界面用户可以在“设置 → TTS”面板中手动调整音色参数包括 voice_id、emotion、emotion_scale。前端配置优先于后端环境变量留空则使用后端默认值。// TTS 参数定义parameters: [{ name: voice_id, type: string,default: 7468518753626767397 },{ name: emotion, type: string,choices: [happy,sad,angry,surprised,fear,hate,excited,coldness,neutral],default: angry },{ name: emotion_scale, type: float,range: [0, 5], default: 0 },]5. Live2D 动作与表情系统5.1 指令体系设计数字人支持两种指令方式纯控制指令/motion nod 或 /expression smile仅触发动作不发送给智能体嵌入指令[motion:bow_light]欢迎回来会触发鞠躬动作并将“欢迎回来”发送给智能体这意味着 Coze 智能体可以主动控制数字人动作在回复中输出 [motion:bow_light]欢迎回来前端会自动执行鞠躬动作并移除标记。5.2 指令解析实现// 嵌入指令解析匹配 [motion:xxx] 或 [expression:xxx]runEmbeddedCommands(text: string): string {return text.replace(/[([motion|动作|expression|表情):([a-zA-Z0-9_-])]/g,(_match, type, command) {if (type motion || type 动作) {this.applyCommand(command);} else {this.applyCommand(expression:${command});}return ; // 从展示文本中移除});}5.3 事件驱动表情当智能体开始回复时前端自动触发随机表情让数字人更自然reactToAgentEvent(event: string): void {switch (event) {case start_speaking:case positive:manager.playRandomExpression();break;case interrupted:this.stopAudio();manager.playRandomExpression();break;}}