> 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).

# 登录疑难解答

当社交登录卡住、返回欢迎界面，或核心记录了未经授权的 `/auth` 请求。

## 检查后端可达性

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

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

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

## 检查所选核心

如果你使用 **高级** remote-core 模式，请在启动 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` 响应意味着桌面令牌和远程核心令牌不匹配。在重试 Google 或 GitHub 登录前先修复这一点。

## 检查深度链接回调

桌面端 OAuth 成功结束时会带有一个 `openhuman://auth?...` 回调。如果浏览器显示该 URL，但应用仍停留在欢迎界面：

1. 确保只运行一个 OpenHuman 桌面实例。
2. 重启应用，保持相同的 remote-core 设置，然后重试登录。
3. 如果使用远程核心，请检查核心是否接收到 `openhuman.auth_store_session`.

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

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

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

```
[深度链接] 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`），则需要修复底层策略；上面的手动脚本也会遇到同样的阻止。

对于远程核心，临时手动注入可以确认核心在其他方面是正常的：

```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_store_session","params":{"token":"JWT_FROM_CALLBACK"} }'
```

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

## 错误报告中应包含什么

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