> 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 结果。

## 检查所选核心

如果你使用 **Advanced** 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 scheme 会通过以下方式注册到正在运行的可执行文件： `HKEY_CURRENT_USER\Software\Classes\openhuman\shell\open\command` 在首次启动时。如果该注册静默失败，或者安装在首次启动后被移动/复制，浏览器就无法将 OAuth 回调传回应用，登录会在提供方步骤之后卡住（issue #2699）。

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

```
[deep-link] openhuman:// scheme registration unhealthy — OAuth callbacks may never reach the app.
register_all_error=…, hkcu_status=NotRegistered|MissingCommand|Stale { … }|ReadError(…)
```

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

```powershell
$exe = 'C:\Path\To\OpenHuman.exe'   # update this
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 出现在浏览器中。
* 如果有的话，第一条未授权日志行。