故障排查

配置中卡住了,先到这里看一下。常见模式和对应的解决方法汇总。

API 相关

「启用」按钮变灰无法点击

原因: 当前选中的项目是组织所有的 Workspace 项目,没有启用 API 的权限。

处理:

• Cloud Console 右上角头像菜单,切换为个人 Google 账户
• 用该账户从 步骤 1 重做(创建新项目)

---

「API 已禁用」错误

原因: 连接时请求的某个工具对应的 API,在项目里没启用。

处理:

• 回到 步骤 2,确认 Gmail API / Calendar API / Drive API 三个都出现在「已启用的 API 和服务」中

---

OAuth 客户端相关

「Access blocked: Authorization Error」

三个典型原因:

1. 步骤 4 选了 Web 应用类型

   • 从凭据列表删除旧客户端
   • 按 步骤 4 用 Desktop app(桌面应用) 重新创建
   • 把新的 Client ID / Secret 在步骤 5 重新粘贴

2. 没把自己加为测试用户

   • 到 步骤 3 的「Test users」区块,加入要连接的 Google 账户邮箱

3. OAuth 同意屏幕没保存完整

   • 同意屏幕各步是否都按了「下一步」「继续」「创建」走完了?

---

「Google hasn’t verified this app」警告

正常情况。测试模式 OAuth 应用即便是自己做的也会显示此警告。

通过方法: 警告页面右下角同时显示 「Continue」文字链接 和 「Back to safety」蓝色实心按钮。点「Continue」(左边那个朴素的文字链接)继续。

点「Back to safety」会中断 OAuth 流程。误点了回仪表盘重新点「Connect」即可。

发布审核(Publishing)后警告会消失,但个人使用保持测试模式即可。

---

Client Secret 丢了

关掉对话框后无法重显,但可以重新颁发:

1. Cloud Console → 「凭据」
2. 点击对应 OAuth 客户端名称
3. 点 「ADD SECRET」 或 「Reset secret」
4. 复制新 Secret → 在 步骤 5 重新粘贴

旧 Secret 立即作废。

---

仪表盘侧

显示「Could not load integrations」

原因: 仪表盘无法和后端(launcher / picoclaw)通信。

处理:

1. 终端中确认 launcher / picoclaw 进程在运行
2. 浏览器直接打开 http://localhost:8080/api/integrations/list,确认能返回 JSON
3. 返回不了就重启进程

---

Client ID / Secret 保存后仍显示「BYO credentials missing」

可能原因与处理:

• 输入时混了空格 → 用「Update credentials」打开重新输入
• 没按下 Save → 再点一次
• 进程缓存了旧设置 → 重启 Kura酱 并刷新仪表盘

---

点了「Connect」但没新标签页打开

原因: 浏览器的弹窗拦截器或广告拦截扩展。

处理:

• 允许来自 localhost 的弹窗
• 暂时关闭广告拦截器
• 浏览器地址栏弹窗拦截通知中点「允许」

---

卡在「Waiting for consent…」不结束

原因: 新标签页中途关闭,或按了「取消」。

处理:

• 再次点「Connect」按钮 → 用新会话重启
• 打开的新标签页不要关,完成 Google 登录 → 「允许」

---

已连接但提示「Insufficient Permission」

原因: 仪表盘请求的权限和 Google 实际授予的权限不一致。

处理:

• Tools 区块把对应工具 Off → Read-only 切换一次
• 再点「Connect」→ Google 会要求确认追加权限,点「允许」

---

想完全重置

要彻底从头来过:

1. Kura酱 侧断开: Connection 行的「Disconnect」断掉所有账户
2. 清空凭据: 「Update credentials」用空值保存(或删除 ~/.config/kuraclaw/ 下对应文件)
3. Google 侧撤销: myaccount.google.com/permissions → 对应应用 → 「移除访问权限」
4. 删除 OAuth 客户端: Google Cloud Console → 「凭据」→ 删除对应客户端
5. 删除项目(可选): 不再用的话,Google Cloud Console → IAM 和管理 → 设置 → 「关闭」(有 30 天恢复期)

然后从 步骤 1 重做。

---

还是不行?

• 按 验证连接 的检查项逐一排查
• 记录仪表盘上的错误信息(按钮下的红色小字)
• 查看 launcher / picoclaw 日志,通常在 ~/.config/kuraclaw/logs/