OpenAvatarChat Chat Agent 模式接入指南：通过 OpenClaw oac-bridge 构建多轮工具调用数字人

原创2026-10-03 15:44:181,446 阅读

文章标签：数字人AI 应用语音多模态音视频后端

OpenAvatarChat Chat Agent 模式接入指南：通过 OpenClaw oac-bridge 构建多轮工具调用数字人

本文基于 OpenAvatarChat 仓库中 docs/beta/chat-agent.md 编写，围绕 Chat Agent 模式（OpenClaw 集成）的架构、oac-bridge 插件部署、双向配置、数据流与启动验证展开，并辅以仓库源码佐证。该功能目前处于 Beta 阶段，API 与配置格式可能随时变化，请以当前仓库为准。

功能与定位：从单轮 LLM 到多轮工具调用 Agent

传统数字人架构中，LLMOpenAICompatible Handler 负责“一问一答”的单轮推理；而 Chat Agent 模式用一个多轮工具调用 Agent 替换它，让数字人获得以下能力：

工具调用：Agent 可以在多轮对话中反复调用工具（获取时间、系统信息等），而不只是做一次问答；
人格与长期记忆：通过 OpenClaw 的 Agent Profile（IDENTITY.md / SOUL.md / USER.md）赋予数字人持久人格与用户偏好；
对话上下文压缩：对话过长时自动压缩历史，保留关键上下文；
后台任务协作：通过 OpenClaw 的 oac-bridge 通道，数字人可以在后台执行复杂任务（如代码执行），并把结果以自然口语反馈给用户；
视觉感知：结合 PerceptionAgent 处理摄像头输入，让数字人具备环境感知与主动交互能力；
双工打断：支持用户随时打断数字人的回答。

架构关系：Chat Agent 替代了配置中原有的 LLMOpenAICompatible Handler。它在内部仍使用 OpenAI 兼容 API 完成 LLM 推理，同时增加了工具调用循环、记忆管理与 OpenClaw 桥接能力。从源码看，ChatAgentHandler 合并了原 ManagerAgent（记忆管理、感知缓存、主动触发、事件处理）与 PersonaAgent（PromptCompiler 编排、LLM 调用、流式输出）的全部职责，其数据流为：

HUMAN_TEXT / PERCEPTION_CONTEXT / ENVIRONMENT_EVENT → ChatAgent → AVATAR_TEXT

核心输入输出

根据 get_handler_detail，ChatAgent 接收三类输入、输出一类数据：

方向	数据类型	说明
输入	`HUMAN_TEXT`	用户语音 ASR 后的文本
输入	`PERCEPTION_CONTEXT`	视觉感知场景摘要（来自 PerceptionAgent）
输入	`ENVIRONMENT_EVENT`	环境事件（如挥手、离场、展示物品）
输出	`AVATAR_TEXT`	交给 TTS → Avatar 合成的回复文本

前置条件

OpenClaw：需要安装并运行 OpenClaw Gateway；
百炼 API Key：Agent 与 TTS 均使用百炼 API，需设置 DASHSCOPE_API_KEY 环境变量（ChatAgentHandler 中 context.config.api_key or os.getenv("DASHSCOPE_API_KEY") 兜底）；
oac-bridge 插件：需要将本仓库中的 oac-bridge 插件部署到 OpenClaw。

认识 oac-bridge：连接 OAC 与 OpenClaw 的频道插件

oac-bridge 是一个 OpenClaw 频道插件，负责 OAC 与 OpenClaw 之间的双向消息传递和工具调用。插件源码位于本仓库的 extensions/openclaw/oac-bridge/ 目录。

从插件入口 index.ts 可以看出，插件通过 defineChannelPluginEntry 注册，并暴露了两类能力：

频道（channel）：以 OpenClaw 频道的形式承接 OAC 发来的消息，见 oacBridgePlugin（src/channel.ts）；
Agent 工具：通过 registerFull 注册 get_agent_profile（读取工作区 IDENTITY.md / SOUL.md / USER.md）与 list_scheduled_tasks（列出定时任务）。

也就是说，oac-bridge 同时承担“消息通道”和“工具服务”两种角色，分别对应 OAC 侧的两个客户端：HTTP 通道客户端与 Plugin Tools MCP 客户端（详见下文“数据流”）。

部署 oac-bridge 插件到 OpenClaw

步骤 1：将插件复制到 OpenClaw 的 extensions 目录

# 假设 OpenClaw 仓库克隆在 ~/Code/openclaw
# 将 oac-bridge 插件复制到 OpenClaw 的 extensions 目录
cp -r extensions/openclaw/oac-bridge ~/Code/openclaw/extensions/oac-bridge

步骤 2：在 OpenClaw 中注册工作区包

编辑 OpenClaw 根目录的 package.json，在 workspaces 数组中添加 oac-bridge：

{
  "workspaces": [
    "extensions/oac-bridge"
  ]
}

[!NOTE] 如果 OpenClaw 的 package.json 已经有 workspaces 字段，只需在数组中追加 "extensions/oac-bridge" 即可。

步骤 3：安装依赖并编译

cd ~/Code/openclaw

# 安装依赖（会自动链接 oac-bridge 工作区包）
pnpm install

# 编译 OpenClaw（oac-bridge 依赖编译产物）
pnpm build

[!IMPORTANT] pnpm build 必须成功完成，因为 OAC 侧的 plugin_tools_cmd 需要指向编译后的 dist/mcp/plugin-tools-serve.js。

步骤 4：配置 OpenClaw

OpenClaw 的配置默认写在 ~/.openclaw/openclaw.json（若设置了环境变量 OPENCLAW_CONFIG_PATH，则以该路径为准）。oac-bridge 读取的是其中的 channels<a href="https://link.gitcode.com/i/5eee3df7cc6c61cda4b9a3f26f889277" target="_blank">"oac-bridge"] 段——这一点与 [src/accounts.ts 中 cfg?.channels?.["oac-bridge"] 的读取逻辑一致。

方式 A：CLI（推荐）

OpenClaw 自带子命令 openclaw config set <点号路径> <值>，会合并写入上述配置文件。路径里的 oac-bridge 是一个键名（含连字符），点号只分隔层级，因此应写成：

# 设置 OAC 回调地址（端口需与 OAC 的 oc_bridge.callback_port 一致，默认 8011）
openclaw config set channels.oac-bridge.callbackUrl "http://localhost:8011/oc-reply"

# （可选）共享认证 token，需与 OAC 侧 oc_bridge.token 一致
openclaw config set channels.oac-bridge.token "your-shared-token"

方式 B：直接编辑配置文件

与上面 CLI 等价，可在 ~/.openclaw/openclaw.json 中手动加入或修改（JSON / JSON5 中键名需加引号）：

{
  "channels": {
    "oac-bridge": {
      "callbackUrl": "http://localhost:8011/oc-reply",
      "token": "your-shared-token"
    }
  }
}

方式 C：环境变量（覆盖缺省）

插件在解析配置时，若配置文件里未设置对应项，会回退到环境变量（src/accounts.ts 的 resolveAccount 实现）：

环境变量	对应配置项
`OAC_CALLBACK_URL`	`channels.oac-bridge.callbackUrl`
`OAC_BRIDGE_TOKEN`	`channels.oac-bridge.token`

修改配置或环境变量后，需要重启 OpenClaw Gateway 才会生效。

步骤 5：启动 OpenClaw Gateway

openclaw gateway run

启动成功后，在 OpenClaw 日志中应能看到：

Registered HTTP route: /webhook/oac-bridge for OAC Bridge

插件配置参数说明

以下参数写在 OpenClaw 的 ~/.openclaw/openclaw.json（或 OPENCLAW_CONFIG_PATH）里，也可用 openclaw config set 或环境变量（见上文）设置：

参数	默认值	说明
`channels.oac-bridge.callbackUrl`	-	OC Agent 回复消息时回调的 OAC HTTP 地址，必填
`channels.oac-bridge.token`	`""`	共享认证 token，用于双向 HTTP 请求的 Bearer 认证
`channels.oac-bridge.webhookPath`	`/webhook/oac-bridge`	OAC 发送消息到 OC 时使用的 webhook 路径
`channels.oac-bridge.enabled`	`true`	是否启用此通道

插件提供的工具

oac-bridge 插件还注册了两个 Agent 工具，OAC 通过 Plugin Tools MCP 调用（注册逻辑见 index.ts）：

工具	说明
`get_agent_profile`	读取 OpenClaw workspace 中的 `IDENTITY.md`、`SOUL.md`、`USER.md`，用于获取 Agent 的人格和用户偏好
`list_scheduled_tasks`	列出 OpenClaw 中已配置的定时任务/提醒

在 OAC 侧，这两个工具（以及 OpenClaw 可能提供的 memory_search、memory_get）会被封装成统一的 BaseTool 注册进 ToolRegistry。相关适配代码见 oc_tools.py：register_oc_tools 会先通过 MCP 探测 OpenClaw 实际暴露了哪些工具，再按需注册，避免注册不存在的工具。

OAC 侧配置：ChatAgent 与 oc_bridge 参数

Agent 示例配置文件为 config/chat_with_openai_compatible_bailian_cosyvoice_flashhead_duplex_agent.yaml，其中关键的 oc_bridge 部分：

ChatAgent:
  module: agent/chat_agent_handler
  llm_model: "qwen3.6-plus"
  api_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
  # ...其他配置...
  oc_bridge:
    enabled: true
    # Plugin Tools MCP 启动命令 — 需指向 OpenClaw 编译产物的绝对路径
    plugin_tools_cmd: "node /home/you/Code/openclaw/dist/mcp/plugin-tools-serve.js"
    # OpenClaw Gateway 的 HTTP 地址（本地连接使用 localhost）
    gateway_http_url: "http://localhost:18789"
    # OAC 回调 HTTP 服务端口（OpenClaw 的 callbackUrl 中的端口需与此一致）
    callback_port: 8011

oc_bridge 各参数说明（与源码 OcBridgeConfig 的默认值一致）：

参数	默认值	说明
`oc_bridge.enabled`	`false`	是否启用 OpenClaw Bridge
`oc_bridge.plugin_tools_cmd`	-	Plugin Tools MCP 启动命令，需修改为你本地 OpenClaw 编译产物的绝对路径
`oc_bridge.gateway_http_url`	`http://localhost:18789`	OpenClaw Gateway 的 HTTP 地址
`oc_bridge.webhook_path`	`/webhook/oac-bridge`	OC Gateway 上的 webhook 路径
`oc_bridge.callback_port`	`8011`	OAC 回调 HTTP 服务端口
`oc_bridge.token`	`""`	共享认证 token（留空表示不认证）

[!IMPORTANT] plugin_tools_cmd 中的路径必须是绝对路径，因为 OAC 进程可能在不同的工作目录下启动。例如：
plugin_tools_cmd: "node /home/luyi/Code/openclaw/dist/mcp/plugin-tools-serve.js"
从 mcp_client.py 可以看到，该命令会被按空格拆分为 command 与 args，作为 MCP StdioServerParameters 启动子进程，因此路径错误将直接导致 MCP 连接失败。

补充：ChatAgent 的本地能力配置

即使不与 OpenClaw 集成，ChatAgent 也具备完整的本地能力。围绕 ChatAgentConfig，示例配置中还包含以下关键分组：

LLM：llm_model / api_url / api_key，以及 enable_thinking（仅当 api_url 指向 dashscope 时通过 extra_body 注入，见 _apply_llm_extra_body）；
Prompt 分层：stable_core（L1 实时规则与输出约束）、persona_snapshot（L2 本地默认人格，启用 oc_bridge 后优先使用 OpenClaw workspace 下的 IDENTITY.md/SOUL.md）、persona_max_chars（默认 2500）、perception_max_chars（默认 800）；
记忆与压缩：perception_max_entries（100）、perception_decay_rate（0.1）、max_dialogue_turns（20），以及 context_compact 分组（enabled: true、compact_threshold: 15、keep_recent: 5、save_transcript、rehydrate_task_brief、rehydrate_env_state，可用 compact_model 指定压缩用模型，默认跟随主模型）；
工具调用：tool_use 分组（enabled、max_tool_rounds 默认 5、register_demo_tools）。本地 demo 工具为 get_current_time 与 get_system_info，见 demo_tools.py；
主动消息触发：proactive 分组，含事件触发（waving / showing_object / asking_for_attention / arriving / leaving，各带 cooldown 与 hint）和空闲触发（idle_trigger，默认关闭，支持按会话模式 mode_overrides 覆盖空闲秒数）。

示例配置同时演示了与 Chat Agent 协作的完整链路：RtcClient（RTC 客户端）、InterruptHandler（打断信号处理）、SileroVad（双工 VAD）、SenseVoice（ASR）、SmartTurnEOU、SemanticTurnDetector（语义轮次与打断检测）、CosyVoice（百炼 TTS）、PerceptionAgent（视觉感知）以及 FlashHead（Avatar 动画）。这些 Handler 共同构成了双工数字人的完整管线。

数据流：一次对话如何穿越 OAC 与 OpenClaw

OAC (port 8283)                          OpenClaw Gateway (port 18789)
     │                                        │
     ├──POST /webhook/oac-bridge──────────▶   │  用户消息 → OC Agent
     │                                        │
     │   ◀──POST localhost:8011/oc-reply───   │  OC Agent 回复 → OAC
     │                                        │
     ├──stdio── Plugin Tools MCP ─────────▶   │  工具调用（profile, memory, tasks）

消息流程详解：

用户说话 → OAC 的 ChatAgent 处理用户输入；
OAC → OC：ChatAgent 通过 HTTP POST 将消息发送到 OpenClaw Gateway 的 /webhook/oac-bridge 端点。发送逻辑见 OcChannelClient.send_message，请求体包含 oac_session_id、text、sender_name，并可选携带 Bearer token；
OC Agent 处理：OpenClaw Agent 接收消息，可能调用工具、查询记忆等；
OC → OAC：OpenClaw Agent 的回复通过 HTTP POST 发送到 OAC 的回调地址 http://localhost:8011/oc-reply。接收端是 OAC 侧本地启动的 HTTP 回调服务（_CallbackHandler），校验 token、限制请求体不超过 256 KB，按 oac_session_id 将回复投递到线程安全的 OcReplyQueue；
OAC TTS → Avatar：ChatAgent 将回复文本交给 TTS 和 Avatar 合成语音和动画；
Plugin Tools MCP：OAC 的 ChatAgent 通过 stdio 管道直接调用 OpenClaw 的 MCP 工具（get_agent_profile、list_scheduled_tasks、memory_search、memory_get 等）。连接在后台线程异步建立，见 oc_bridge_init.py 与 mcp_client.py。

Agent 循环：LLM、工具与流式输出如何协作

在 chat_agent_handler.py 的 _agent_loop 中，实现了标准的“LLM 调用 → 工具执行 → 结果回填 → 再次调用”多轮循环：

将注册的工具 schema 作为 OpenAI tools 参数传入（工具定义不拼进 system prompt，见 _debug_log_prompt 的说明）；
流式读取回复，同时累积文本与 tool_calls 增量；
若无工具调用，则返回最终文本结束；
若有工具调用，将 assistant 消息与每条 tool 结果追加进 messages，继续下一轮；轮次上限为 max_tool_rounds（默认 5），超限后强制输出文本；
整个循环期间，若用户双工打断触发 STREAM_CANCEL 信号，流会被取消、循环提前终止（见 on_signal 与 _stream_response 中对 active_stream_keys 的检查）。

启动与验证

[!IMPORTANT] 请确保 OAC 和 OpenClaw 运行在同一台机器上（本地连接），目前暂未测试跨机器部署。

# 1. 启动 OpenClaw Gateway（在终端 A）
cd ~/Code/openclaw
openclaw gateway run

# 2. 安装 OAC 依赖（在终端 B）
cd ~/Code/OpenAvatarChat
uv run install.py --config config/chat_with_openai_compatible_bailian_cosyvoice_flashhead_duplex_agent.yaml

# 3. 下载模型
uv run scripts/download_models.py --handler flashhead

# 4. 启动 OAC Agent 模式
uv run src/demo.py --config config/chat_with_openai_compatible_bailian_cosyvoice_flashhead_duplex_agent.yaml

验证连接

启动后在日志中确认以下关键信息：

OAC 侧日志：

<a href="https://link.gitcode.com/i/ce5a276c2fe8e844a07449ed3b737d4f" target="_blank">ChatAgent] OC Channel Client started — OAC ↔ OC HTTP 通道已建立（对应 [oc_bridge_init.py）
[ChatAgent] OC MCP Client connected — Plugin Tools MCP 已连接

OpenClaw 侧日志：

Registered HTTP route: /webhook/oac-bridge — webhook 已注册
Starting OAC Bridge channel — oac-bridge 通道已启动

常见问题

问题	可能原因	解决方案
`OC MCP Client` 连接失败	`plugin_tools_cmd` 路径错误	确认路径指向 OpenClaw 编译后的 `dist/mcp/plugin-tools-serve.js`，需先运行 `pnpm build`
`OC Channel Client` 连接失败	OpenClaw Gateway 未启动或端口不对	确认 `openclaw gateway run` 已运行，默认端口 18789
OC Agent 不回复	`callbackUrl` 未配置	运行 `openclaw config set channels.oac-bridge.callbackUrl "http://localhost:8011/oc-reply"`
`401 Invalid token`	token 不匹配	确保 OAC 的 `oc_bridge.token` 与 OpenClaw 的 `channels.oac-bridge.token` 一致

降级运行：无需 OpenClaw 也能使用 Agent

[!TIP] 如果不需要 OpenClaw 集成，可以将 oc_bridge.enabled 设为 false，Agent 仍然可以独立运行，保留工具调用、上下文压缩等本地能力。此时 ChatAgentHandler.create_context 会跳过 OC Bridge 初始化，L2 人格回退到本地 persona_snapshot，工具注册仅包含 demo 工具；OAC 侧日志会输出提示：OC Bridge 未启用：不会从 OpenClaw 拉取 L2 人格，也不会注册 OC 工具。

小结

Chat Agent 模式是 OpenAvatarChat 数字人体系从“问答”走向“Agent 化协作”的关键一步：它用多轮工具调用 Agent 取代单轮 LLM，通过 oac-bridge 频道插件打通 OAC 与 OpenClaw 的双向消息和 MCP 工具通道，并结合 PerceptionAgent 的视觉感知、上下文压缩、主动触发与双工打断，构成一个具备持久人格、长期记忆和后台任务能力的人形数字人 Agent。按本文步骤完成插件部署、两端配置与启动验证后，即可在本地体验完整的 Chat Agent 数字人会话。

登录后查看全文

数字人AI 应用语音多模态音视频后端

OpenAvatarChat

OpenAvatarChat Chat Agent 模式接入指南：通过 OpenClaw oac-bridge 构建多轮工具调用数字人

OpenAvatarChat Chat Agent 模式接入指南：通过 OpenClaw oac-bridge 构建多轮工具调用数字人

功能与定位：从单轮 LLM 到多轮工具调用 Agent

核心输入输出

前置条件

认识 oac-bridge：连接 OAC 与 OpenClaw 的频道插件

部署 oac-bridge 插件到 OpenClaw

步骤 1：将插件复制到 OpenClaw 的 extensions 目录

步骤 2：在 OpenClaw 中注册工作区包

步骤 3：安装依赖并编译

步骤 4：配置 OpenClaw

步骤 5：启动 OpenClaw Gateway

插件配置参数说明

插件提供的工具

OAC 侧配置：ChatAgent 与 oc_bridge 参数

补充：ChatAgent 的本地能力配置

数据流：一次对话如何穿越 OAC 与 OpenClaw

Agent 循环：LLM、工具与流式输出如何协作

启动与验证

验证连接

常见问题

降级运行：无需 OpenClaw 也能使用 Agent

小结

相关推荐

热门文章