\r \r

连接器修复\r

\r 修复 WorkBuddy 连接器 OAuth 授权失败，恢复连接器正常连接。\r \r

适用场景\r

\r 触发条件：用户在 WorkBuddy 中连接第三方连接器时出现以下任一错误：\r \r

• streamableHttp connect failed: Failed to open: 找不到应用程序 (0x800401F5)\r
• sse connect failed: SSE error: Non-200 status code (405)\r
• 连接器"授权超时"\r
• 错误码 0x800401F5\r
• "找不到应用程序"\r \r

诊断流程\r

\r 按以下四步执行，每一步都可能终结排查（找到根因即可跳到修复）。\r \r

步骤 1：日志定位\r

\r 从 WorkBuddy 日志中确认错误来源和连接器名称。\r \r

grep -i "streamableHttp\|0x800401F5\|sse connect\|405\|授权超时" ~/.workbuddy/logs/$(date +%Y-%m-%d)/*.log | tail -30\r
```\r
\r
关注关键信息：\r
- 哪个连接器失败？（如 `connector:qq-mail`）\r
- 连接的目标 URL 是什么？（如 `https://api.mail.qq.com/mcp`）\r
- 是否有 `captureResourceMetadataUrl` 日志？（表示 OAuth 发现阶段成功）\r
\r
### 步骤 2：网络排除\r
\r
验证目标 MCP 服务端是否可达，排除网络问题。\r
\r
```bash\r
# 测试 MCP 端点（返回 405 或 401 通常说明服务端可达）\r
curl -s -o /dev/null -w "%{http_code}" "https://\x3C目标域名>/mcp"\r
\r
# 测试 OAuth 发现端点（应返回 JSON）\r
curl -s "https://\x3C目标域名>/.well-known/oauth-protected-resource" | head -20\r
```\r
\r
如果两个请求都正常返回 → **问题不在网络，在本地**。跳到步骤 3。\r
\r
如果网络不通 → 检查代理设置：\r
```bash\r
reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings" /v ProxyEnable\r
```\r
\r
### 步骤 3：默认浏览器诊断（核心）\r
\r
**这是最常见的根因**：Windows 默认浏览器 ProgId 指向已卸载的浏览器，OAuth 流程调用 ShellExecute 打开授权页面时失败。\r
\r
```bash\r
# 从日志中提取默认浏览器 ProgId，或直接查询常见问题 ProgId\r
reg query "HKEY_CLASSES_ROOT\ChromeCoreHTM\shell\open\command" 2>/dev/null\r
reg query "HKEY_CLASSES_ROOT\SogouExplorerHTML\shell\open\command" 2>/dev/null\r
```\r
\r
验证浏览器程序是否存在：\r
```bash\r
# 从注册表值中提取路径，确认文件存在\r
# 例：注册表指向 "C:\Program Files (x86)\ChromeCore\ChromeCore.exe"\r
ls "/c/Program Files (x86)/ChromeCore/ChromeCore.exe" 2>/dev/null\r
```\r
\r
**如果文件不存在 → 这就是根因。跳到修复方案。**\r
\r
### 步骤 4：确认可用浏览器\r
\r
找出系统中实际安装的浏览器：\r
\r
```bash\r
ls "/c/Program Files/Google/Chrome/Application/chrome.exe" 2>/dev/null      # Chrome 64位\r
ls "/c/Program Files (x86)/Google/Chrome/Application/chrome.exe" 2>/dev/null # Chrome 32位\r
ls "/c/Program Files/Microsoft/Edge/Application/msedge.exe" 2>/dev/null      # Edge 64位\r
ls "/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe" 2>/dev/null # Edge 32位\r
```\r
\r
## 修复方案\r
\r
### 方案 A：HKCU 覆写 ProgId（推荐，无需管理员权限）\r
\r
在 `HKCU` 层覆写浏览器命令，优先级高于 `HKCR`，不破坏原始注册表，仅当前用户生效：\r
\r
```powershell\r
New-Item -Path "HKCU:\Software\Classes\\x3CProgId>\shell\open\command" -Force | Out-Null\r
Set-ItemProperty -Path "HKCU:\Software\Classes\\x3CProgId>\shell\open\command" -Name "(Default)" -Value '"\x3C可用浏览器路径>" --single-argument %1'\r
```\r
\r
常见示例：\r
\r
| 失效 ProgId | 覆写目标 |\r
|---|---|\r
| `ChromeCoreHTM` → Edge x86 | `"C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" --single-argument %1` |\r
| `ChromeCoreHTM` → Edge 64位 | `"C:\Program Files\Microsoft\Edge\Application\msedge.exe" --single-argument %1` |\r
| `ChromeCoreHTM` → Chrome | `"C:\Program Files\Google\Chrome\Application\chrome.exe" --single-argument %1` |\r
| `SogouExplorerHTML` → Edge | 同上，替换 ProgId |\r
\r
### 方案 B：用户手动修改默认浏览器（治本）\r
\r
引导用户：**Windows 设置 → 应用 → 默认应用 → Web 浏览器** → 选择 Edge 或 Chrome\r
\r
此方案彻底清除残留，但需要用户手动操作，适合作为方案 A 之后的后续建议。\r
\r
## 修复后验证\r
\r
1. 确认注册表修改生效：\r
```bash\r
reg query "HKEY_CURRENT_USER\Software\Classes\\x3CProgId>\shell\open\command"\r
```\r
\r
2. 让用户在 WorkBuddy 中重新连接该连接器\r
\r
3. 确认连接状态变为 `connected`\r
\r
## 根因链路\r
\r
```\r
已卸载浏览器 → 注册表残留 ProgId 仍为默认浏览器\r
→ WorkBuddy OAuth 流程调用 ShellExecute 打开授权页面\r
→ Windows 按注册表查找浏览器程序 → 文件不存在\r
→ COM 错误 0x800401F5 "找不到应用程序"\r
→ streamableHttp 连接中断\r
→ SSE 降级也不被服务端支持 (405)\r
→ 最终显示"授权超时"\r
```\r
\r
## 注意事项\r
\r
- 方案 A 只在当前用户生效，不影响其他用户\r
- 修改 `HKCU` 不需要管理员权限\r
- 建议修复后提示用户到系统设置中正式更改默认浏览器，彻底解决\r
- 如果浏览器程序存在但仍报错，可能是代理或防火墙问题\r
- 如果网络不通且非代理问题，检查 DNS 或防火墙规则