本地调试与预览
概述
dbx dev 是豆包应用插件的本地开发调试入口。启动后,它会加载当前项目并启动本地调试服务,主要支持:
- 打开 Web 模拟器;
- 打开真机调试器;
- 查看可用的页面和卡片;
- 直接执行端工具,检查调用参数和返回结果;
- 向已打开全页手动触发 Agent 事件,验证页面订阅与更新;
开发者可以先使用 Web 模拟器预览和验证交互;需要验证真实设备表现时,再通过 PC 端开发者工具连接手机进行调试。
功能简介
在终端运行 dbx dev,即可启动本地调试服务。控制台会显示项目信息和可用命令。
在控制台输入 status 可查看服务状态。服务就绪后,就可以打开 Web 模拟器预览,或连接真机调试页面和卡片。
也可以让 AI 运行 dbx dev,保持服务运行并打开终端显示的 Web 地址。如果需要让 AI 输入下文的控制台命令,请使用交互式终端(TTY)。启动命令不支持 --json。
以下命令均在 dbx dev 启动后的调试控制台中执行。

命令一览
使用 Web 模拟器调试
Web 模拟器用于在浏览器中预览页面和卡片,适合验证基本交互和页面展示,不需要连接真机。
使用真实 AppID 调试沙箱环境
新版 CLI 支持使用真实应用的 db_app_* AppID 调用本地调试沙箱。AppID 用于标识应用,运行环境则由平台 OpenAPI 域名区分;使用真实 AppID 不代表调试请求会进入正式环境。
开始调试前,请确保以下三处使用同一个真实 AppID:
- 项目根目录
manifest.yaml中的app_key - 前端配置中的
runtimeConfig.appId - 业务 Server 实际读取的 AppID
业务 Server 仍使用该真实应用对应的 AppSecret,并按项目现有的安全配置方式读取。AppSecret 只能保存在服务端安全配置中,不要写入前端代码、Manifest、Skill 或日志。
本地调试时,业务 Server 调用豆包平台 OpenAPI 必须使用沙箱域名:
DOUBAO_OPENAPI_BASE_DOMAIN=https://api-sandbox.doubao-dev.com
Web 模拟器生成的登录码、手机号授权码、支付订单和回调状态均位于该沙箱环境。若业务 Server 调用正式 OpenAPI 域名,将无法识别这些调试数据。
注意:runtimeConfig.apiBaseUrl 是前端访问业务 HTTP Server 的地址;manifest.mcp_server.end_point 和 dbx dev --mcp-endpoint 是 MCP Server 地址。它们都不是豆包平台 OpenAPI 域名,不要混用。
原有的 doubao-sandbox-app-* 沙箱 AppID 仍然支持。先执行 dbx sandbox info 确认当前项目沙箱和 Secret 是否存在;只有确实需要 AppSecret 时,才执行 dbx sandbox info --include-secret。
在调试控制台中执行:
命令会打开 Web 模拟器页面。开发者可以在模拟器中选择调试内容、预览运行效果,并使用右侧调试面板定位问题。
调试内容包括对话、卡片、全页和工具:
- 对话:模拟用户对话,查看卡片渲染、消息流、日志、Agent Trace,以及登录、支付等沙箱流程。

- 卡片:选择卡片模板,编辑
structuredContentJSON 后重新渲染,并检查卡片运行状态。

- 全页:调试页面跳转、页面路径、返回和刷新,查看页面运行时内容。

- 工具:选择工具、填写调用参数并运行,查看返回结果,也可以将结果填入卡片预览。

右侧是常驻的 Chrome DevTools 区域,提供:
- Elements:查看和高亮元素
- Console:查看运行日志
- Agent Trace / Sandbox / Preact:查看调试链路、沙箱状态和 React 组件信息
使用真机调试
真机调试用于验证页面和卡片在真实设备上的运行效果。连接真机后,可以通过 CLI 推送调试包,再使用 PC 端开发者工具观察和定位问题。
连接真机
开始前请确认:
- 手机已登录豆包账号并且与开发者工具使用的豆包账号一致;
- 手机登录账号已加入目标应用插件的调试白名单;
- 手机已通过数据线连接 PC,并保证手机和 PC 在同一 WIFI 环境下。
- Android 设备需要开启开发者模式和 USB 调试。iOS 设备连接 USB 后,请在“是否信任此设备”提示中选择“信任”。
在调试控制台中执行 desktop。首次使用或工具版本更新时,CLI 会先准备本机开发者工具,再自动用默认浏览器打开二维码页面,默认等待 60 秒连接。
用手机上的豆包 App 扫描与客户端版本对应的二维码:
- 客户端版本
< 1470:扫描页面中标注< 1470的二维码。 - 客户端版本
>= 1470:扫描页面中标注>= 1470的二维码。

等待连接时请保持二维码页面打开,关闭页面会取消本次等待。连接成功后,CLI 会记录当前活跃设备,后续 page 和 widget 命令默认使用该设备。若设备已连接且可直接调试,CLI 会复用连接并跳过扫码。
二维码过期或需要重新连接时,执行:
推送页面和卡片
设备连接成功后,可以先查看项目中可用的页面和卡片:
然后使用完整页面 URL 或卡片 ID 推送目标:
page [url]使用pages列出的完整 URL,页面参数写入 URL query;省略 URL 时可交互选择页面;widget [id]使用widgets列出的卡片 ID,省略 ID 时可交互选择卡片;widget --data接收合法 JSON,作为卡片的widgetData传递;page不支持--data。
端到端调试
在 dbx dev 控制台中执行:
选择已上传的版本后,在应用插件 Debugger 中调试该版本的 UI 和 MCP 链路。


使用 PC 端开发者工具调试
真机连接成功后,可以使用 PC 端开发者工具查看页面或卡片的实际运行效果,并使用 Elements、Console 等面板定位问题。
首次使用时,工具会自动下载对应版本的开发者工具。

选择页面或组件并注入测试数据,在模拟器或真机中预览,同时使用 Elements、Console 和 JSB 完成调试。
在 GUI 中推送页面或卡片
- 在左侧
调试目标下拉框中选择页面或卡片。 - 在
JSON data中填写可选的业务 JSON。 - 点击
推卡到真机。 - 在
输出结果中查看成功结果或失败诊断。

JSON 输入规则:
- 留空时只发送目标 ID,不传
pageData或widgetData; - 非空时必须是合法 JSON;
- 页面目标使用
pageData,卡片目标使用widgetData; - 目标 ID 由下拉框负责,不需要写进 JSON。
GUI 发送推送前会检查设备连接状态:
- 没有连接设备时,显示
no_connected_device; - 选择的设备已断开时,显示
selected_device_not_connected; - 连接多个设备时,需要明确选择目标设备。
选择调试 session
推送页面或卡片后,会产生对应的调试 session。顶部工具栏会显示当前 session,并优先跟随最新可用的 Lynx session。
如果当前 session 消失,GUI 会回退到其他可用 session;没有可用 session 时,右侧进入空状态。

常见问题
扫码后提示 fail to decode debug info
先确认扫描的是与豆包客户端版本对应的二维码,再确认扫码手机登录的豆包 UID 已加入目标应用插件的调试白名单。不要在终端日志、截图或文档中暴露 UID;由应用管理员通过受控渠道添加后,重新生成二维码扫码。
二维码超时了怎么办
在 dbx dev 控制台里执行:
命令会重新打开浏览器中的二维码页面,按豆包客户端版本选择对应二维码扫码。
页面总是打开成同一个页面
执行 page,从列表中选择目标页面:
也可先执行 pages,再将目标页面的完整 URL 传给 page "<page-url>"。不要传页面 ID 或源码路径;页面参数写入 URL query。
CLI 提示找不到设备
先确认:
- 手机已经扫码并授权真机调试。
- 当前
dbx dev控制台还在运行。 - 没有连接多个未指定的设备。
- 如果之前设备断开过,重新执行
qr扫码,或在 GUI 顶部选择最新调试目标。
PC 工具中显示 调试页面准备中
这表示当前还没有可用 Lynx 调试 session。可以:
- 确认手机已扫码连接。
- 在 CLI 中执行
status查看 dev runtime 是否 running。 - 推送一个页面或卡片。
- 点击 GUI 顶部重载按钮刷新 DevTools iframe。
JSON data 写什么
只写业务数据,不写页面 id 或卡片 id。例如:
目标 id 由 CLI 参数或 GUI 下拉框负责。