# 登录故障排查

当社交登录卡住、返回欢迎界面，或核心日志中出现未经授权的 /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` 响应意味着桌面令牌与远程核心令牌不匹配。在重试 Google 或 GitHub 登录之前先修复这一点。

## 检查深度链接回调

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

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

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

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

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

```
[深度链接] openhuman:// 协议注册不健康——OAuth 回调可能永远无法到达应用。
register_all_error=…, hkcu_status=NotRegistered|MissingCommand|Stale { … }|ReadError(…)
```

要手动修复，请以 **运行 OpenHuman 的同一用户身份打开 PowerShell** （不需要管理员权限——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"} }'
```

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

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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://tinyhumans.gitbook.io/openhuman/zh/gai-lan/troubleshooting-sign-in.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.