桌面端故障排除

如果问题发生在 Codex、ZCode 等工具调用 KeenKind API 时，请先看 API 常见问题。

遇到问题时，先确认当前对话、工作目录、模型和权限。很多失败来自上下文与当前页面不一致，而不是功能不可用。

模型无法回复

打开 设置 > 配置，确认配置和模型已启用。
检查 API 地址、模型 ID 和密钥。
确认厂商与接口类型匹配。
新建一个空对话发送简单消息，排除当前对话状态影响。
查看服务商是否返回限流、余额或区域错误。

DeepSeek 等兼容 OpenAI Chat Completions 的服务仍应选择对应厂商，以使用正确的默认设置。

工具没有执行

检查输入框附近的权限模式；
确认当前工作目录正确；
在 设置 > 扩展 检查依赖的 Skill、MCP 或插件；
展开失败的工具调用，查看具体原因；
停止当前任务后重试，避免上一项操作仍在运行。

文件或图片无法使用

检查格式、大小和数量限制；
确认文件仍在原位置；
工作区相对路径必须基于当前项目；
对 Office、PDF 或图片先尝试在右侧栏预览；
受密码保护、损坏或只包含扫描图像的文件可能无法提取文本。

浏览器显示错误页面

浏览器状态按对话保存，先确认当前对话；
在浏览器标签栏检查当前标签和地址；
关闭无用标签，避免模型重复打开页面；
登录、验证码、扫码和支付操作需要用户处理；
页面发生变化后让 Keenkind 重新查看页面，再继续操作。

扩展无法加载

在扩展页面停用后重新启用。
检查本机平台、命令路径和环境变量。
打开详情或插件调试查看诊断。
更新或重新安装扩展。
第三方扩展仍失败时，联系扩展作者并附上版本与错误信息。

子代理和持续任务

子代理没有执行工具：检查角色的批准策略和允许的风险类别；
子代理一直排队：并发名额已被其他运行占用，等待结束后会自动开始；
角色修改后不生效：已启动的运行使用创建时的快照，重建运行后再试；
长任务没有推进：检查对话是否还需要你补充信息或确认计划；
规划器/验证器无法使用：在 设置 > 持续化任务 确认是否为规划器和验证器指定了可用模型。

收集日志

向支持人员反馈时，请提供：

Keenkind 版本；
操作系统版本；
使用的模型厂商和接口类型；
可复现步骤；
错误截图；
对应时间段的日志。

Windows 生产版日志通常位于：

%LOCALAPPDATA%\Keenkind\production\logs

本地开发版则位于 %LOCALAPPDATA%\Keenkind\development\logs。

发送前检查日志和截图，移除 API Key、Cookie、个人文件内容和其他敏感信息。