应通过五种方法开启debug日志以排查workbuddy部署异常：一、启动参数强制启用；二、claw设置中启用开发者日志；三、web管理控制台实时捕获；四、cli工具动态监听；五、容器内读取原始日志。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试排查WorkBuddy部署过程中的异常行为，但日志仅显示简略状态或无错误信息，则可能是由于默认日志级别过低，未捕获详细执行上下文。以下是开启Debug模式并获取部署日志详细输出的多种方法：
一、通过启动参数强制启用Debug日志
该方式在服务启动阶段即加载完整调试上下文，适用于冷启动失败、Claw连接中断、权限校验异常等底层问题定位，日志将直接输出至终端或指定文件。
1、关闭当前正在运行的WorkBuddy进程。
2、打开终端（Windows使用PowerShell，macOS/Linux使用Terminal），进入WorkBuddy安装目录下的bin子路径。
3、执行带参数的启动命令：./WorkBuddy --debug --log-level=debug --log-file ./deploy_debug.log（macOS/Linux）或WorkBuddy.exe --debug --log-level=debug --log-file "C:\logs\deploy_debug.log"（Windows）。
4、触发一次部署操作（如重新加载技能包、重启Claw服务或执行远程配置同步）。
5、执行完成后，打开生成的deploy_debug.log文件，搜索关键词deploy、claw-init、agent-startup，重点关注包含ERROR、WARN及Caused by的行。
二、在Claw设置中启用开发者级部署日志
该方法不依赖外部终端，所有部署相关日志自动写入本地结构化文件，便于归档分析或提交技术支持，且支持记录初始化阶段的环境变量与路径解析过程。
1、点击WorkBuddy界面右上角的Claw设置图标。
2、在弹出菜单中选择“高级配置” → “开发者选项”。
3、勾选“启用完整部署日志”与“记录Claw握手过程与证书验证详情”两项。
4、重启WorkBuddy，日志文件将生成于%APPDATA%\WorkBuddy\logs\deploy\（Windows）或~/Library/Application Support/WorkBuddy/logs/deploy/（macOS）。
5、打开最新命名的deploy_YYYYMMDD_HHMMSS.log文件，查找以[DEPLOY]为前缀的日志行，特别注意cert validation failed、webhook registration timeout、missing required env var类提示。
三、通过Web管理控制台实时捕获部署事件流
该方式适用于已部署为服务端模式的WorkBuddy实例，无需登录服务器即可查看部署任务的全链路状态，支持按模块筛选与时间回溯。
1、使用具有系统管理员权限的账号登录WorkBuddy Web管理界面。
2、在左侧导航栏点击【系统监控】→【日志中心】。
使用 draw.io（.drawio 格式）和 SVG 生成兼容 Microsoft Visio 的架构图。当用户需要以下任一场景时触发： - 用于 Visio 或技术文档的架构/系统/网络图 - 带连接标注的分层控制系统图 - 将 draw.io XML 转换为稳定、可嵌入的 SVG - 修复 Visio 或 draw.io 无法打开的故障排查类图表 - 任何需专业级布局且文本可编辑的图表
3、在顶部筛选栏中，将“服务模块”设为claw-engine或deploy-manager，日志级别设为DEBUG，时间范围设为最近10分钟。
4、输入关键词deploy或bootstrap进行搜索，结果中高亮显示的条目将包含部署触发源、目标环境标识、签名验证摘要及最终状态码。
5、点击某条日志右侧的“展开详情”按钮，查看其原始JSON payload，确认environment、config_hash、signature_valid字段值是否符合预期。
四、使用CLI工具动态监听部署日志流
该方式避免手动刷新文件，可实时滚动显示部署过程中的每一条DEBUG级输出，特别适合观察Claw注册、证书加载、配置热更新等瞬时事件。
1、确保WorkBuddy CLI工具已正确安装并识别（通常随主程序自动注册）。
2、打开终端或PowerShell，执行命令：workbuddy log tail --module deploy-manager --level debug。
3、在另一窗口中触发部署动作（例如：点击Web控制台中的【重新部署Claw】按钮，或执行workbuddy deploy --force）。
4、观察CLI窗口中持续输出的日志，重点识别含"Starting deployment sequence"、"Loading TLS certificate from /opt/workbuddy/certs/"、"Applying config diff: added 3, removed 1"的行。
5、若日志突然中断或卡在某一步超过15秒，立即按下Ctrl+C终止监听，并检查前一条日志末尾是否出现java.net.ConnectException或Permission denied (publickey)类异常。
五、从容器内部读取部署阶段原始日志
当WorkBuddy以Docker容器方式部署时，部署脚本、init容器及Claw守护进程的日志均写入容器内固定路径，该方式可获取未上报至Web控制台的初始化失败信息，包括挂载点不可达、secrets注入失败等底层错误。
1、执行docker ps | grep workbuddy获取运行中WorkBuddy容器的CONTAINER ID。
2、运行docker exec -it
3、切换至部署日志目录：cd /var/log/workbuddy/deploy/。
4、列出部署相关日志文件：ls -lt deploy_*.log，识别最新生成的文件。
5、使用tail -n 300 deploy_20260419_162201.log查看末尾内容，特别关注含"failed to mount volume"、"secrets not found in /run/secrets"、"exec user process caused: no such file or directory"的错误行。
