# 故障排查

在下面找到你遇到的症状。每一节都说明错误的含义和处理方法。

## 我的 AI 应用连不上 Lune

如果连接彻底失败（超时，或提示「couldn't reach the server」）：

1. 确认地址。服务器地址是 `https://mcp.luneresearch.com`。旧地址 `https://mcp.luneresearch.com/mcp` 和 `https://mcp.luneresearch.com/v1/mcp` 仍然可用。
2. 确认你的网络能访问它。在终端里运行：

   ```sh
   curl -sS -o /dev/null -w "%{http_code}\n" \
     https://mcp.luneresearch.com/.well-known/oauth-protected-resource
   ```

   你应该看到 `200`。看到 `5xx` 说明 Lune 出了问题，过几分钟再试，一直不恢复就发邮件给客服。完全没有响应，则是你这一侧的网络或 DNS 有问题。

3. 打开[状态页面](https://luneresearch.com/zh-Hans/status)。它会从你的浏览器检测 MCP 服务器是否有响应，但不发布故障公告。

## 手动测试连接

用访问密钥列出工具。这次调用不计入请求数。

```sh
curl -sS https://mcp.luneresearch.com \
  -H "Authorization: Bearer lune_your_access_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

密钥有效时会以事件流返回工具列表：先是一行 `event: message`，再是一行 `data:`，里面就是 JSON-RPC 响应。其他结果的含义：

- `401`：密钥错误或已经撤销，见下一节。
- `405`：请求以 `GET` 发出。服务器只接受 `POST`。用浏览器打开这个地址会跳转到[把 Lune 接入你的 AI 应用](https://luneresearch.com/zh-Hans/docs/mcp)。
- `406`：`Accept` 请求头少了两种类型中的一种。
- `415`：`Content-Type` 请求头不是 `application/json`。
- `400`：请求体不是合法的 JSON，或者 JSON-RPC 批量请求超过 50 条消息。修正 JSON，或把批量请求拆开发送。
- `403` 并提示「origin not allowed」：请求来自网页。请从后端或原生应用调用服务器。

## 我遇到「401 unauthorized」或「invalid_token」

服务器没有接受这个凭证。

- **通过登录接入的应用（OAuth）。** 应用会自己续期访问令牌。如果错误反复出现，说明登录已经结束：有人在凭证页面撤销了它、它闲置了 90 天，或者重复使用刷新令牌，Lune 撤销了整条令牌链。在应用里断开 Lune，再重新接入。
- **访问密钥。** 密钥输错、已经撤销，或已过创建时设定的有效期。在[凭证页面](https://luneresearch.com/dashboard/settings/credentials)创建新密钥，替换旧的。成员只能撤销自己的密钥，所有者和管理员可以撤销团队里的任何密钥。
- **账户已暂停。** 托管服务器对已暂停的账户返回的 `401` 和凭证无效时一样，本地 stdio 服务器则会返回一条说明账户已暂停的错误。如果重新接入后 `401` 依然存在，或者你看到了这条提示，请发邮件至 [appeal@luneresearch.com](mailto:appeal@luneresearch.com)。换新凭证没有用。

### 如果你在开发连接器

OAuth 发现从一次不带凭证的请求开始：

1. 不带 `Authorization` 请求头向服务器发 `POST`。返回的 `401` 带有 `WWW-Authenticate: Bearer resource_metadata="https://mcp.luneresearch.com/.well-known/oauth-protected-resource", scope="papers:read guidance:read account:read"`。过期或无法验证的令牌会得到同样的响应头，并多出 `error="invalid_token"`，客户端应据此刷新令牌。
2. 获取这份资源元数据。其中 `authorization_servers` 的值是 `https://api.luneresearch.com`。
3. 获取 `https://api.luneresearch.com/.well-known/oauth-authorization-server` 拿到各端点，再按 [auth.md](https://luneresearch.com/auth.md) 的说明注册、授权、换取令牌。

令牌端点拒绝表单编码的请求时，返回 `400` 和扁平的响应体 `{"error": "...", "error_description": "..."}`。请求体不是表单编码，或者缺少 `grant_type` 时，返回的则是 `422` 和 `{"detail": [...]}` 列表。注册时缺少 `redirect_uris` 返回 `422`，列表为空或含有 Lune 拒收的地址时返回 `400`。常见的 `error` 值：

| `error`                | 原因                                                                                                                               | 处理                                                   |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `invalid_grant`        | 授权码已过期（有效期 10 分钟）、已经用过，或与 client ID、回调地址、PKCE verifier 不匹配；或刷新令牌已过期、已撤销，或重复使用过。 | 重新发起授权。                                         |
| `invalid_target`       | `resource` 与授权请求或刷新令牌上的值不一致。                                                                                      | 每次请求都带 `resource=https://mcp.luneresearch.com`。 |
| `invalid_redirect_uri` | 注册时拒收回调地址：非回环主机上的 `http`、带片段，或不安全的 scheme。                                                             | 改用 `https`、回环地址或私有 scheme。                  |

授权请求的 `redirect_uri` 与已注册地址不完全一致时返回 `400`（`http` 回环地址的端口除外）；缺少 `scope` 时返回 `422`。客户端常见的错误见 [auth.md](https://luneresearch.com/auth.md)。

## 我遇到「403」或缺少权限的错误

凭证本身有效，但缺少某个工具需要的权限。无论有哪些权限，工具列表都会显示全部工具，只是调用会失败。

- **OAuth。** 服务器返回 `403`，`WWW-Authenticate` 响应头里的 `error` 是 `insufficient_scope`，`scope` 写明缺少的权限。在应用里断开 Lune，再重新接入。客户端应重新发起授权，并申请全部三个权限 `papers:read guidance:read account:read`，因为新的授权只包含请求里写明的权限。
- **访问密钥。** 工具会返回一条写明缺少哪项权限的错误。创建一个包含该权限的密钥。各工具需要的权限见[权限](https://luneresearch.com/zh-Hans/docs/concepts/scopes)。

## 请求用完了，或者遇到「429」

这是两种不同的限制。

**请求用完了。** 每日额度和点数都不够这次调用时，工具返回错误，最后一行带有 `http_status=402` 和 `quota_reason`：

- `no_capacity`：每日额度和点数都已用完。等到 UTC 午夜重置、购买点数，或在[账单页面](https://luneresearch.com/dashboard/settings/billing)升级。点数包 $0.99 可换 300 次额外请求。
- `batch_too_large`：批量工具请求的条目，既超过剩余的每日额度，也超过剩余点数。一次调用要么全用额度，要么全用点数，不会拆开支付。减少查询、Paper 或论断的数量后重试。
- `retry_now`：调用进行期间额度恢复了。重试一次即可。

**429。** 这是防止脚本失控的每秒突发限流，与每日额度无关。等待 `retry_after_seconds` 给出的秒数，重试同一个调用，并让应用减少同时发出的调用。

每日额度和计费方式见[套餐、请求与点数](https://luneresearch.com/zh-Hans/docs/concepts/quotas-and-billing)。

## 我的 AI 应用连上了，但工具不显示

- 重启 AI 应用。大多数客户端只在启动时获取工具列表。
- 网页 AI 应用：移除连接器再重新添加。
- Claude Desktop：完全退出（只关窗口不够）再重新打开。

各类应用的更多提示见[本地 AI Agent](https://luneresearch.com/zh-Hans/docs/mcp/stdio) 和[网页 AI 应用](https://luneresearch.com/zh-Hans/docs/mcp/remote)。

## 用量记到了错误的团队

通过登录接入的应用，用量始终记在你的个人团队名下。访问密钥的用量记在创建它的团队名下。想用共享团队的套餐，请在该团队下创建访问密钥，再用它连接。详见[团队与访问密钥](https://luneresearch.com/zh-Hans/docs/concepts/orgs-and-keys)。

## 搜索结果看起来不对、缺失或过时

- **覆盖范围。** Lune 收录经同行评审的顶会。[顶会页面](https://luneresearch.com/zh-Hans/conferences)和 `list_conferences` 工具列出主会论文已全部收录的顶会。Lune 仍在补全的顶会，其 Paper 也能搜到。其余会议的 Paper 不在文献库里。
- **时效性。** Lune 下一次抓取某个顶会时，才会加入它的新 Paper。抓取由人工发起，不按固定计划运行，所以最近发表的 Paper 可能要过几周才会出现。
- **措辞。** 完整的自然语言查询（「methods for retrieval-augmented generation that reduce hallucination on long-form QA」）比关键词堆砌（「RAG hallucination」）找得更全。
- **顶会筛选。** Lune 不认识的 `conference` 名称会直接报错，而不是返回未经筛选的结果。`venues` 列表会保留认识的名称、丢掉其余的，一个都不认识时报错。名称有歧义时会返回候选名称供选择。可以让 Agent 先用 `list_conferences` 查准确的简称。

## 我还是卡住了

发邮件至 [support@luneresearch.com](mailto:support@luneresearch.com)，并附上：

- 你使用的 AI 应用（Claude、Cursor 等）
- 如果错误来自某次工具调用，写上工具名称
- 发生的时间（UTC）
- 完整的错误信息
- 这是新的配置，还是以前能正常工作的配置

我们通常当天回复。