> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/zh/gai-lan/troubleshooting-sign-in.md).

# 登录故障排查

诊断登录失败、未完成的 OAuth 回调，以及远程核心 RPC 身份验证问题。

当社交登录卡住、返回欢迎界面，或核心记录到未授权的 /auth 请求时，请使用此检查清单 `/auth` 请求。

## 检查后端可达性

从与桌面应用相同的网络中，验证公开的 OpenHuman 端点：

```bash
curl -I https://tinyhumans.ai/
curl -I https://api.tinyhumans.ai/health
```

如果网站能打开但 API 端点失败，桌面应用可能无法将 OAuth 回调交换为会话。请在问题报告中记录 HTTP 状态、地区和 DNS 结果。

## 检查所选核心

如果你使用 **高级** 远程核心模式，在开始 OAuth 之前请确认 RPC URL 和 bearer token：

```bash
curl -sS https://your-core.example/rpc \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer CORE_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"core.ping","params":{}}'
```

一个 `401` 响应，表示桌面端 token 与远程核心 token 不匹配。请先修复这一点，再重试 Google 或 GitHub 登录。

## 检查深度链接回调

成功的桌面 OAuth 最终会以 `openhuman://auth?...` 回调结束。如果浏览器显示了该 URL，但应用仍停留在欢迎界面：

1. 确保只运行了一个 OpenHuman 桌面实例。
2. 重启应用，保持相同的远程核心设置，然后重试登录。
3. 如果使用远程核心，检查核心是否收到 `openhuman.auth_set_credential` （桌面外壳会先向后端验证会话，然后再将凭证交给核心）。

## Windows： `openhuman://` 处理程序未注册

在 Windows 上， `openhuman://` URL 方案会在首次启动时通过 `HKEY_CURRENT_USER\Software\Classes\openhuman\shell\open\command` 注册到正在运行的可执行文件。如果该注册静默失败，或者安装在首次启动后被移动/复制，浏览器就无法把 OAuth 回调交回应用，登录会在提供方步骤后卡住（问题 #2699）。

Tauri 外壳现在会在发生这种情况时输出一条 `log::error!` 启动日志行。请在日志文件中查找它（默认位置 `%USERPROFILE%\.openhuman\logs\openhuman.*.log`):

```
[deep-link] openhuman:// 方案注册异常 — OAuth 回调可能永远无法到达应用。
register_all_error=…, hkcu_status=NotRegistered|MissingCommand|Stale { … }|ReadError(…)
```

要手动修复，请打开 PowerShell **使用运行 OpenHuman 的同一用户** （无需管理员权限；HKCU 是按用户区分的）并将路径替换为你的实际安装位置：

```powershell
$exe = 'C:\Path\To\OpenHuman.exe'   # 在此更新
New-Item -Path 'HKCU:\Software\Classes\openhuman' -Force | Out-Null
Set-ItemProperty -Path 'HKCU:\Software\Classes\openhuman' -Name '(Default)' -Value 'URL:OpenHuman Protocol'
New-ItemProperty -Path 'HKCU:\Software\Classes\openhuman' -Name 'URL Protocol' -Value '' -Force | Out-Null
New-Item -Path 'HKCU:\Software\Classes\openhuman\shell\open\command' -Force | Out-Null
Set-ItemProperty -Path 'HKCU:\Software\Classes\openhuman\shell\open\command' -Name '(Default)' -Value ('"' + $exe + '" "%1"')
```

随后重启 OpenHuman 并重试登录。如果 `register_all_error` 不是`None` 在日志中为非空（例如因为杀毒软件或受限镜像阻止写入 `HKCU\Software\Classes`），则需要修复底层策略；上面的手动脚本也会遇到同样的阻止。

对于远程核心，临时手动注入可以确认核心本身是正常的（核心会按提供的值存储凭证；除非 JWT 携带 subject 声明，否则请提供令牌所属的用户 ID）：

```bash
curl -sS https://your-core.example/rpc \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer CORE_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"openhuman.auth_set_credential","params":{"token":"JWT_FROM_CALLBACK","userId":"YOUR_USER_ID"} }'
```

请勿将真实 JWT 粘贴到公开的 GitHub 问题中。请打码令牌，并且只附上状态码、主机名、应用版本、操作系统以及相关日志行。

## 漏洞报告中应包含的内容

* 应用版本和操作系统。
* 核心模式是本地还是远程。
* RPC URL 主机、已打码的令牌状态，以及 `core.ping` 结果。
* 所使用的 OAuth 提供方。
* 是否出现了一个 `openhuman://auth` URL 在浏览器中。
* 第一条未授权日志行（如果有）。