常见问题排查

调用失败时，agent 会收到一条以 ScholarMuse 和错误代码开头的消息，比如 ScholarMuse insufficient_credits: …。下面逐一说明每个错误代码。返回错误的调用都不扣积分。

授权页面打不开

**自己发起登录。**很多 agent 只有在你要求时才会打开浏览器：在 Claude Code 里输入 /mcp，选中 scholarmuse，选择 Authenticate；在 Codex 里运行 codex mcp login scholarmuse；在 Gemini CLI 里运行 /mcp auth scholarmuse。连接你的 agent列出了每种 agent 的做法。
**找一找链接。**有些 agent 不直接打开浏览器，而是打印出授权链接。把它复制到浏览器里打开。
**重启 agent。**添加服务器后重启一次，再试。
**使用 mcp-remote。**有些应用能添加 MCP 服务器，但完全不能完成浏览器登录。这时通过 mcp-remote 添加 ScholarMuse，做法见无法打开授权页面的应用。

ScholarMuse 从来不需要你把 API key、token 或密码粘贴给 agent。如果 agent 在安装过程中向你索要，请不要提供。

连接上的 agent 可以使用 ScholarMuse 所有学科的全部工具，不需要另外开启。如果 agent 看不到工具：

**确认服务器已连接。**大多数 agent 会在 MCP 设置里或输入 /mcp 后显示状态。如果显示需要登录，重新登录一次。
**重启 agent，或者新建一个对话。**很多 agent 只在启动时加载工具列表。
**检查应用自己的开关。**有些应用添加的服务器默认是关闭的，或者需要在每个对话里选中：在 Cherry Studio 里要启用服务器，并在对话的 MCP 选择器里选中它；在 ChatGPT 里输入 @ 并选中 ScholarMuse。
**检查模型。**你正在用的模型必须支持工具调用。
问一句：“列出 ScholarMuse 的能力。”如果能列出来，说明连接没有问题，可能只是请求需要说得更清楚。

REST 接口返回 HTTP 402。这次调用需要的积分比你剩下的多，所以没有执行。消息里会写明这次调用需要多少积分。

可以在账号设置的积分页面充值，或者在价格页面选择套餐。免费账号每月也会收到 30 积分。详见积分。

REST 接口返回 HTTP 402。画插图需要付费套餐或积分包。新账号赠送的免费积分只能用于数据工具，因为每张插图的生成都有实际成本。

购买任意套餐或积分包后即可使用插图。付款后最多可能需要一分钟才会生效。详见科研插图。

REST 接口返回 HTTP 429，并带有 Retry-After 响应头。你的账号发出的调用超过了套餐允许的频率。稍等一会儿再试。

只买了积分包、没有订阅套餐的账号，按 Starter 的限制计算。agent 一次发出的调用超过套餐能同时运行的数量时，多出来的会排队等候；等待太久的调用会返回 rate_limited。通过 REST 调用时，每个 API key 每分钟最多还只能发 60 个请求。

如果经常碰到这个限制，可以让 agent 少发几次、每次多取一些（比如一次检索把数量调大，而不是分成很多次小检索），或者换更高的套餐。

在已连接的 agent里断开它。
在 agent 里重新发起登录（比如在 Claude Code 里输入 /mcp 后选择 Authenticate，或者运行 codex mcp login scholarmuse）。如果没有弹出登录，把 ScholarMuse 服务器从 agent 里删掉，再重新添加。
在 scholarmuse.ai 登录并点击允许。

发邮件到 davie@daviechen.com，写明你用的 agent、你提出的请求和错误信息。活动日志页面列出了每次调用的状态，可以帮我们快速找到问题。