常见问题

现象	先检查什么
找不到 Agent 组件	Spring 扫描范围、Bean 名和 EL 节点名是否一致
提示缺少 API Key	DeepSeek 使用 openai-compatible.deepseek.api-key；确认环境变量进入实际 Java 进程
第二轮忘记前文	是否复用同一会话 ID；应用名、组件名、存储路径是否改变
提示缺少本地工作目录	开启本地 Shell 后需设置 harness.local.workspace-root；纯对话可关闭 Shell
命令被拒绝或找不到程序	同时检查白名单和实际执行环境中的安装情况
Docker 无法连接	在 Java 服务相同账户与环境下运行 docker info
容器内不能联网	默认 network=NONE；有需要时使用 BRIDGE
对话还在，容器文件不在	JSON 模式是否保存快照目录；Redis／MySQL 快照保存是否成功
Redis／MySQL 无法初始化	依赖、连接方式是否冲突，以及连接、库表和账号权限
设置了流式，浏览器还是最后才收到	是否监听增量事件并通过 SSE／WebSocket 实时发送，不能只返回最终字符串
人工确认一直等待	是否有处理器返回实际决定，单纯监听确认事件不会继续执行
调用正常返回，但没有结果	先看 response.isSuccess()，失败原因在 response.getCause()
删除会话后文件仍在	删除 API 不会清除全部工作区和快照，按业务保留策略另行清理
本地命令提示 Unsynchronized files	先备份错误提示中的执行目录、恢复未保存文件，再处理 pending 标记；不要直接清空目录重试

查看调用失败原因

LiteflowResponse response = flowExecutor.execute2Resp("chatChain", input);
if (!response.isSuccess()) {
    throw new IllegalStateException("Agent 执行失败", response.getCause());
}

配置项和默认值见配置速查。从旧版本升级后遇到类找不到、方法不能覆写或配置无效时，先对照2.16.2 升级说明。