1. 为什么 Agent 的输出需要一块 Live-Canvas传统 Agent 的交互形态很单一你问一句它回一段文字或一段代码。做代码补全、写 SQL、解释报错时这套够用但一旦进入「持续观察 实时决策」的场景纯文本就开始拖后腿。比如你让 Agent 盯着服务器指标、盯着一批任务的执行进度、盯着一个数据管道的健康度它每次只能吐一段 JSON 或一段自然语言你还得自己在脑子里把数字还原成趋势效率极低。Live-Canvas 想解决的就是这件事让 Agent 拥有一个可视化输出层。Agent 不再只输出文字而是输出结构化的 UI 指令由画布实时渲染成仪表盘、折线图、状态卡片、进度条。你看到的不再是「CPU 45%内存 50%」这种句子而是一块会随 Agent 状态自动刷新的面板。这套机制的核心是 A2UIAgent to UI协议。你可以把它理解成 Agent 和画布之间的「普通话」Agent 说「给我画一个 gauge标签 CPU当前值 45上限 100」画布就渲染出一个仪表盘。Agent 不需要知道前端框架、不需要写 HTML它只负责产出结构化指令渲染交给画布。适合谁上手三类人最值得试。第一类是已经在用 OpenClaw 跑 Agent 工作流、但觉得输出太「干」的开发者第二类是想给内部工具加实时监控面板、又不想写一整套前端的后端同学第三类是在做 Agent 产品、需要给用户一个「看得见」的交互层的团队。这篇会从零把画布初始化、事件桥接、端到端验证走一遍代码都能直接复制。需要说明的是Live-Canvas 不是要替代你的编辑器或终端它是 Agent 工作流里的一个「显示层」。Agent 该在终端跑还在终端跑该在 IDE 里补全还在 IDE 里补全画布只是多开了一扇窗让你能实时看到 Agent 内部状态的外化。2. OpenClaw 里接入 Live-Canvas 的前置准备在写桥接代码之前先把运行环境和凭证理顺。OpenClaw 本身是一个 Agent 运行环境Live-Canvas 是它的一块能力模块而 A2UI 指令的生成依赖模型能力所以你需要一个稳定的模型接入点。这里我用 TaoToken 作为模型网关它的接口兼容主流协议配置成本低适合拿来跑这类需要频繁调用模型的 Agent 场景。第一步拿到 API Key。访问 https://taotoken.net/api-keys 创建密钥建议按项目维度建方便后面做用量隔离。创建后立刻复制保存页面刷新后就看不到完整 Key 了。第二步确认 Base URL。TaoToken 的 API 入口是 https://taotoken.net/api注意这个地址不带任何查询参数直接作为 base_url 使用。如果你用的是 OpenAI 兼容的 SDK配置里填这个就行。第三步选模型。A2UI 指令生成对模型的指令遵循能力有要求因为它要输出严格结构的 JSON。建议选指令遵循强的模型具体可用模型列表在 https://taotoken.net/models 查看选一个你额度内、响应速度可接受的即可。第四步装 OpenClaw 和 Canvas 模块。OpenClaw 的安装按官方文档走Canvas 作为可选模块单独启用。装完后确认openclaw --version能正常输出再确认 Canvas 模块被加载。这里有个容易踩的坑很多人把模型 Key 直接写进 OpenClaw 的主配置文件结果 Canvas 模块读不到。正确做法是把模型凭证放在环境变量或独立的 provider 配置里Canvas 通过 OpenClaw 的 provider 接口间接调用而不是自己持有 Key。下面这段是推荐的 provider 配置结构路径放在~/.openclaw/providers/taotoken.json{ provider: taotoken, base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, default_model: your-model-id, timeout_ms: 60000, max_retries: 2 }注意api_key_env这一项它指向的是环境变量名而不是 Key 本身。这样 Key 不会进版本库也不会被日志打印出来。设置环境变量export TAOTOKEN_API_KEYsk-你的密钥如果你在 Windows 上用setx TAOTOKEN_API_KEY sk-你的密钥然后重开终端。配完之后跑一次连通性检查确认 provider 能被 OpenClaw 识别openclaw provider list openclaw provider test taotoken第二条命令会发一个最小请求返回模型名和延迟就说明通了。如果这里就报 401先别往下走回到 Key 和环境变量排查后面 Canvas 的报错会更难定位。3. 可复制的画布初始化与 A2UI 桥接配置环境通了之后进入正题把画布初始化并把 Agent 事件桥接到 Canvas 渲染。整个链路是「Agent 产出事件 → 桥接层转成 A2UI 指令 → Canvas 渲染」。我把它拆成三块配置你按顺序贴。第一块是画布初始化配置放在~/.openclaw/canvas/config.toml[canvas] enabled true renderer dashboard refresh_interval_ms 500 max_widgets 24 theme dark [canvas.a2ui] protocol_version 1.0 strict_schema true fallback_to_text true [canvas.bridge] event_source agent.stdout batch_window_ms 200 drop_on_overflow false几个参数值得解释。refresh_interval_ms控制画布刷新频率500ms 是实时性和性能的平衡点再低会让渲染线程吃满。strict_schema true表示 A2UI 指令必须严格符合 schema不符合就拒绝渲染这能帮你早发现 Agent 输出的结构问题。fallback_to_text true是兜底如果指令解析失败把原始内容当文本显示不至于白屏。batch_window_ms是事件批处理窗口Agent 短时间吐多条事件时会合并成一批渲染避免闪烁。第二块是 A2UI 指令的 schema 约束。桥接层需要知道「什么样的 JSON 才算合法指令」。把下面这份 schema 放到~/.openclaw/canvas/a2ui.schema.json{ $schema: http://json-schema.org/draft-07/schema#, title: A2UICommand, type: object, required: [type], properties: { type: { enum: [render, update, clear, notify] }, target: { type: string }, widgets: { type: array, items: { type: object, required: [type], properties: { type: { enum: [gauge, bar-chart, line-chart, table, status-card, progress] }, label: { type: string }, value: { type: [number, string] }, max: { type: number }, data: { type: array } } } } } }这份 schema 定义了四种指令类型render新建或整体替换、update局部更新某个 widget、clear清空、notify弹提示。widget 类型覆盖了仪表盘、柱状图、折线图、表格、状态卡、进度条日常监控够用了。第三块是桥接代码。这是整篇最核心的部分它负责把 Agent 的事件流翻译成 A2UI 指令。用 Python 写放在~/.openclaw/canvas/bridge.pyimport json import os import time from typing import Any import jsonschema import requests SCHEMA_PATH os.path.expanduser(~/.openclaw/canvas/a2ui.schema.json) CANVAS_ENDPOINT http://127.0.0.1:8765/a2ui TAOTOKEN_BASE https://taotoken.net/api TAOTOKEN_KEY os.environ[TAOTOKEN_API_KEY] MODEL_ID os.environ.get(TAOTOKEN_MODEL, your-model-id) with open(SCHEMA_PATH, r, encodingutf-8) as f: A2UI_SCHEMA json.load(f) def agent_event_to_a2ui(event: dict[str, Any]) - dict[str, Any]: 把 Agent 事件转成 A2UI 指令这里用模型做结构化转换。 prompt ( 你是 A2UI 指令生成器。根据下面的 Agent 事件输出一条符合 schema 的 JSON 指令 只输出 JSON不要解释。事件内容\n json.dumps(event, ensure_asciiFalse) ) resp requests.post( f{TAOTOKEN_BASE}/v1/chat/completions, headers{ Authorization: fBearer {TAOTOKEN_KEY}, Content-Type: application/json, }, json{ model: MODEL_ID, messages: [{role: user, content: prompt}], temperature: 0, response_format: {type: json_object}, }, timeout60, ) resp.raise_for_status() content resp.json()[choices][0][message][content] return json.loads(content) def validate_and_send(command: dict[str, Any]) - bool: try: jsonschema.validate(instancecommand, schemaA2UI_SCHEMA) except jsonschema.ValidationError as e: print(f[bridge] schema 校验失败: {e.message}) return False r requests.post(CANVAS_ENDPOINT, jsoncommand, timeout10) return r.status_code 200 def run_bridge(): 从 stdin 读 Agent 事件逐条转换并推送到画布。 import sys for line in sys.stdin: line line.strip() if not line: continue try: event json.loads(line) except json.JSONDecodeError: continue command agent_event_to_a2ui(event) ok validate_and_send(command) print(f[bridge] event - canvas: {ok if ok else failed}, flushTrue) time.sleep(0.05) if __name__ __main__: run_bridge()这段代码有三个关键设计。第一用模型做事件到指令的转换而不是写死规则这样 Agent 输出格式变化时桥接层不用改。第二response_format强制 JSON 输出配合temperature0让指令结构稳定。第三schema 校验在发送前做非法指令直接拦下不会污染画布状态。启动桥接export TAOTOKEN_MODELyour-model-id python ~/.openclaw/canvas/bridge.py /tmp/agent_events.jsonl如果你用的是 Claude Code 这类工具链模型 ID 和 Base URL 的对应关系要写全三件套Base URL 填https://taotoken.net/apiKey 走环境变量Model ID 填你在模型列表里选的那个。三者缺一请求就会在鉴权或路由阶段失败。4. 端到端验证让画布跟着 Agent 状态实时更新配置写完必须做一次端到端验证确认「Agent 状态变化 → 画布刷新」这条链路真的通。我设计一个最小可复现的验证动作模拟一个 Agent 持续上报 CPU 和内存指标观察画布上的仪表盘是否跟着变。第一步准备事件流。写一个脚本模拟 Agent 每 500ms 吐一条事件存成 JSONLimport json import random import time with open(/tmp/agent_events.jsonl, w, encodingutf-8) as f: for i in range(20): event { kind: metric, ts: time.time(), cpu: random.randint(20, 90), memory: random.randint(30, 85), seq: i, } f.write(json.dumps(event, ensure_asciiFalse) \n) time.sleep(0.5)第二步启动画布服务。OpenClaw 的 Canvas 模块启动后会监听本地端口openclaw canvas start --port 8765 --config ~/.openclaw/canvas/config.toml看到canvas listening on 127.0.0.1:8765就说明画布起来了。第三步跑桥接把事件流喂进去python ~/.openclaw/canvas/bridge.py /tmp/agent_events.jsonl第四步打开 Dashboard 观察。macOS App 或浏览器里的 Dashboard 会显示两个 gaugeCPU 和内存的指针应该随着事件流跳动。如果指针不动先看桥接日志里event - canvas是不是都是 ok再看画布服务有没有收到请求。验证成功的标志有三个桥接日志每条都是 ok画布上 gauge 数值在 20 到 90 之间变化事件流结束后画布保留最后一帧状态而不是白屏。三个都满足说明整条链路通了。如果你想验证更复杂的场景把事件换成带data数组的让 Agent 生成折线图。比如事件里带series: [1,3,2,5,4]桥接层会转成line-chart指令画布渲染出折线。这一步能验证 schema 里data字段的解析是否正常。实测下来从事件产生到画布刷新端到端延迟在 600ms 到 900ms 之间主要开销在模型转换那一步。如果你对延迟敏感可以把桥接层改成规则优先、模型兜底的混合模式常见事件用规则直接映射规则覆盖不到的才走模型。这样能把延迟压到 200ms 以内。5. 常见报错排查401、local proxy failed 与 choices 解析失败接入过程中有几类报错出现频率最高我把它们和对应的排查路径列出来你对照着看。第一类401 Unauthorized。这个几乎都是 Key 的问题。先确认环境变量真的被读到了在桥接脚本里加一行print(os.environ.get(TAOTOKEN_API_KEY, MISSING)[:8])看输出是不是你的 Key 前缀。如果显示 MISSING说明环境变量没生效检查是不是在同一个 shell 里 export 的。如果前缀对但还报 401去 https://taotoken.net/api-keys 确认 Key 没被删除或过期。还有一种情况是 Key 里混入了空格或换行复制时容易带上strip 一下再存。第二类local proxy failed。这个报错通常出现在你本地配了某些网络转发工具、或者系统代理设置和 OpenClaw 的请求路径冲突时。排查方法是先确认 OpenClaw 的 provider 配置里没有多余的 proxy 字段再检查系统环境变量里有没有HTTP_PROXY/HTTPS_PROXY这类设置。如果有临时 unset 掉再试unset HTTP_PROXY HTTPS_PROXY ALL_PROXY openclaw provider test taotoken如果 unset 之后通了说明是代理配置干扰把 OpenClaw 的请求路径加到代理白名单或者干脆让 OpenClaw 直连。第三类reading choices或cannot read property choices of undefined。这个报错的意思是桥接层拿到了响应但响应结构里没有choices字段。常见原因有三个一是模型返回了错误对象而不是正常响应比如额度不足或模型名写错这时候响应体里是error字段二是response_format不被该模型支持返回了非标准结构三是请求根本没到模型被中间层拦截返回了 HTML。排查时先把原始响应打出来print(resp.status_code) print(resp.text[:500])看到error就按错误信息处理看到 HTML 就是路由问题看到正常 JSON 但没有 choices 就检查模型 ID 是否正确。模型 ID 一定要和 https://taotoken.net/models 里列出的完全一致大小写和连字符都不能错。第四类OAuth 相关报错。如果你用的是 Claude Code 这类带 OAuth 流程的工具报错里出现OAuth token expired或invalid_grant说明凭证过期了。这类工具通常有自己的登录态管理重新走一次授权流程即可。注意 OAuth 凭证和 API Key 是两套体系不要混用。如果你在 Claude Code 里接的是 API Key 模式就把 Base URL 和 Key 按前面说的三件套配全不要同时开 OAuth。第五类画布白屏但桥接日志全 ok。这种情况多半是 schema 校验过了、请求也发了但画布渲染器不认识某个 widget 类型。检查你的 A2UI 指令里 widget 的type是不是在 schema 枚举范围内。如果 Agent 生成了枚举外的类型strict_schema会拦下但如果 schema 本身没更新就会漏过去。把 schema 和渲染器支持的 widget 列表对齐一次。排查这类问题的通用思路是分层定位先确认网络和鉴权provider test再确认模型响应结构打印原始响应再确认 schema 校验桥接日志最后确认渲染画布日志。每一层都有明确的成功标志不要跳层猜。6. 把 Live-Canvas 用进日常 Agent 工作流链路跑通之后真正有价值的是把它用起来。我自己的用法是给几类常跑的 Agent 都挂上画布数据同步任务挂进度条和状态卡服务巡检挂 gauge 和折线图批量任务挂表格和完成率。这样我不用盯着终端滚动的日志扫一眼画布就知道 Agent 在干什么、卡在哪。一个实用技巧是给画布加「历史轨迹」。A2UI 的update指令支持局部更新你可以让桥接层维护一个滑动窗口每次只推最新的 N 个数据点画布上的折线图就会呈现滚动效果而不是每次重画。这对观察趋势特别有用。另一个技巧是把画布的notify指令用起来。Agent 遇到异常时除了在日志里记一笔还可以推一条 notify 到画布弹一个提示卡。这样异常不会被淹没在日志里你能第一时间看到。如果你要长期跑 Agent 工作流建议把模型调用走 Coding Plan 这类套餐成本比按量计费可控适合这种高频、小请求的桥接场景。配置入口在 https://taotoken.net/coding-plan按你的调用量选档位即可。最后提醒一点画布是显示层不要让它承担业务逻辑。Agent 该做的决策、该写的文件、该调的接口都在 Agent 侧完成画布只负责把状态可视化。职责分清后面扩展才不会乱。
