> For the complete documentation index, see [llms.txt](https://docs.goassay.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.goassay.ai/developers/zh/shi-yong-gong-ju-jin-jie/troubleshooting.md).

# 故障排查

对照本地 MCP 拒绝原因和服务器错误，了解含义及下一步处理方式。

先检查客户端使用的配置文件：

```sh
npx -y @goassay-ai/mcp status
npx -y @goassay-ai/mcp doctor
```

如果使用命名配置文件，请为两个命令都添加 `--profile <name>`。修改限额前，先阅读确切的拒绝信息。付费调用超时、结果不明时，请先按[重试与幂等](/developers/zh/shi-yong-gong-ju-jin-jie/retries-and-idempotency.md)处理，再发起另一笔购买。

## 登录和密钥链

| 代码 / 消息                                                         | 含义                        | 解决方法                                                                                                                                                                                                |
| --------------------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 只提供 `assay_sign_in`                                             | 此配置文件已退出登录。               | 按[安装 assay-mcp](/developers/zh/shi-yong-gong-ju-ru-men/install-assay-mcp.md)操作。                                                                                                                     |
| 连接结束后返回登录链接                                                     | 服务器不再接受已保存的登录。            | 打开返回的链接，或为同一配置文件运行 `npx -y @goassay-ai/mcp login`。连接结束后，浏览器不会自动重新打开。                                                                                                                                |
| **The sign-in was declined in the browser.**                    | 用户拒绝了授权。                  | 如果确实要批准，请重新运行登录。                                                                                                                                                                                    |
| **The sign-in answer did not come from Assay; it was refused.** | 回调未通过签发方或响应检查。            | 重新开始登录；不要复用或修改回调 URL。                                                                                                                                                                               |
| **The sign-in did not complete. Try again.**                    | 登录交换失败。                   | 检查连接并重新开始登录。                                                                                                                                                                                        |
| **The sign-in was not finished within 5 minutes. Try again.**   | 等待批准已超时。                  | 重新开始登录，并在新的时限内完成。                                                                                                                                                                                   |
| **The sign-in was cancelled.**                                  | 登录等待被中止。                  | 准备好后重新登录。                                                                                                                                                                                           |
| **Could not open a local port for the sign-in.**                | 本地回调监听器无法绑定端口。            | 允许本地回调监听器运行并重试。                                                                                                                                                                                     |
| **Assay sign-in is already in progress in another window.**     | 此配置文件已有另一个登录正在进行。         | 先完成或取消那个登录。                                                                                                                                                                                         |
| `-32001`：**Assay sign-in in progress in another window.**       | 等待配置文件锁超时。                | 让另一个操作完成后重试。不要删除仍在使用的锁。                                                                                                                                                                             |
| **No OS keychain is available.**（消息开头）                          | 操作系统存储不可用；MCP 不支持回退到文件存储。 | 启用 macOS Keychain、Windows Credential Manager 或 Linux Secret Service。请忽略消息中有关 SDK 的建议。暂不支持没有密钥链的机器，例如 CI 运行器和容器；参阅 [CLI 参考](/developers/zh/shi-yong-gong-ju-jin-jie/cli-reference.md)中的“环境变量与无界面使用”。 |
| **Unlock your keychain, then try again.**                       | 存储已锁定或访问被拒绝。              | 解锁或查看访问提示，然后重试。                                                                                                                                                                                     |
| **Assay refused the API key in the environment.**               | `ASSAY_API_KEY` 的值被拒绝。    | 移除非预期的 `ASSAY_API_KEY` 并使用浏览器登录，或检查该密钥是否仍然有效。参阅 [CLI 参考](/developers/zh/shi-yong-gong-ju-jin-jie/cli-reference.md)中的“环境变量与无界面使用”。                                                                   |

## 付款设置和本地许可

| 消息 / 代码                                                               | 含义                           | 解决方法                                                                                                             |
| --------------------------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Paid calls through this server are off.**                           | 此确切 URL 未获准付款。               | 按 [URL 与配置文件](/developers/zh/shi-yong-gong-ju-jin-jie/urls-and-profiles.md)，在终端允许正确的路径和查询参数。                     |
| **This tool is paid, and paid calls are off for this agent.**         | 密钥需要设置，或缺少有效的钱包批准权限。         | 按[付费流程](/developers/zh/shi-yong-gong-ju-ru-men/how-paying-works.md)操作，包括比对指纹。                                    |
| **This computer has no payment key for this profile yet.**            | 没有密钥可供 `enable-paid` 打开批准页面。 | 先从客户端尝试一次付费调用。                                                                                                   |
| **This profile is not signed in.**                                    | `enable-paid` 要求配置文件已登录。     | 先登录该配置文件。                                                                                                        |
| **The payment key stored on this computer is unreadable.**            | 保存的机密信息不是可用的支付密钥。            | 停止付费尝试并检查密钥链访问权限。如果通过退出登录替换配置文件，也要撤销旧密钥的链上权限；见[安全模型](/developers/zh/shi-yong-gong-ju-jin-jie/security-model.md)。 |
| **Assay asked for a payment this app could not complete. Try again.** | 本地付款流程发生意外故障，未能完成。           | 运行上方两项检查。如果先前授权可能已发送，请先核对调用结果再重试。                                                                                |
| `PAYMENT_VOUCHER_DELEGATE_INACTIVE`                                   | 密钥权限已过期或被撤销，服务器因此拒绝付款授权。     | 检查密钥状态，只有确实需要时才续期。                                                                                               |
| `PAYMENT_DEBT_OUTSTANDING`                                            | 账户欠款阻止付费调用。MCP 会添加充值链接。      | 打开返回的充值链接，在那里解决；重复调用工具无法结清欠款。                                                                                    |

## 付款拒绝

签名前，`assay-mcp` 会运行付款检查。检查失败时会返回 **Assay asked for a payment this app refused:**，后跟原因。请在下表中查找该原因。代码列用于问题报告，不会出现在消息中。

| 消息中的原因                                                                               | 代码                                   | 解决方法                                                                                     |
| ------------------------------------------------------------------------------------ | ------------------------------------ | ---------------------------------------------------------------------------------------- |
| the amount is above the local limit per call                                         | `G7_PER_CALL`                        | 选择更便宜的调用，或提高本地限额；参阅[支出限额](/developers/zh/shi-yong-gong-ju-ru-men/spending-limits.md)。    |
| the amount would pass the local limit per 24 hours                                   | `G7_PER_DAY`                         | 等待较早的金额移出滚动窗口，或提高本地限额。                                                                   |
| the amount is above the confirmation limit and was not confirmed                     | `G7_CONFIRMATION_REQUIRED`           | 在支持确认提示的客户端中批准这笔确切付款。                                                                    |
| the confirmation was for another payment                                             | `G7_CONFIRMATION_MISMATCH`           | 重新尝试，只批准显示的那笔付款。                                                                         |
| the amount is above the payment key's on-chain cap                                   | `G6_DELEGATE_CAP`                    | 使用更便宜的调用，或通过 `enable-paid` 和钱包提高密钥上限。                                                    |
| the amount is above the escrow's on-chain cap                                        | `G6_ESCROW_CAP`                      | 使用更便宜的调用，或通过钱包提高账户上限。                                                                    |
| the provider is not in the allow-list                                                | `G8_PROVIDER_NOT_ALLOWED`            | 检查本地提供方列表；参阅[访问策略](/developers/zh/shi-yong-gong-ju-jin-jie/access-policy.md)。            |
| paid calls through this server are off                                               | `G11_URL_NOT_PAID`                   | 在终端允许此 URL；参阅 [URL 与配置文件](/developers/zh/shi-yong-gong-ju-jin-jie/urls-and-profiles.md)。 |
| the amount is above the quoted price / there is no price quote for this tool         | `G3_ABOVE_QUOTE` / `G3_NO_QUOTE`     | 重新发现工具及其价格。不要批准原因不明的涨价。                                                                  |
| the payment key's grant has expired / is not active                                  | `G4_EXPIRED` / `G4_INACTIVE`         | 只有确实需要时，才通过 `enable-paid` 续期密钥。                                                          |
| the payer has not authorised this payment key                                        | `G4_NOT_DELEGATED`                   | 为此密钥完成[付费流程](/developers/zh/shi-yong-gong-ju-ru-men/how-paying-works.md)。                |
| the payment key's grant could not be read from the chain / the chain read is too old | `G4_NO_CHAIN_READ` / `G4_STALE_READ` | 恢复连接，待可以读取链上状态后再试。                                                                       |
| 其他任何原因                                                                               |                                      | 保留确切文本，不要修改限额，这无济于事。请带上该消息联系 Assay 支持。                                                   |

工具结果还会带有 `_meta["assay-mcp/refused"]`，其中含 `guard`（如 `G7`）和相同的 `reason` 文本。

## 网络和协议

| 代码 / 消息                                                                                 | 含义                                                    | 解决方法                               |
| --------------------------------------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------- |
| `-32002`：**Assay did not answer in time.**                                              | 转发交换（包括消息体）超过 120 秒。                                  | 检查连接，并使用已保存的幂等键重试。                 |
| `-32002`：**Assay is busy with other calls from this app. Try again.**                   | 没有可用转发槽位；此请求未发送。                                      | 减少并行调用，然后重试。                       |
| `-32003`：**Can't reach Assay (…)**                                                      | 网络交换失败。原因可能含网络错误码或 **blocked: not an Assay address**。 | 恢复网络访问，或使用内置 Assay 源站。重试时保留相同键。    |
| `-32003`：消息中含 **could not renew the sign-in; try again**                                | 令牌更新暂时失败。                                             | 恢复连接并重试；如果连接已结束，请重新登录。             |
| `-32000`：**Assay sent no answer.** / **Assay's answer had no result for this request.** | 没有响应匹配转发的请求。                                          | 使用相同键重试；反复失败时提交问题报告。               |
| `-32000`：**Assay's answer was too large.**                                              | 响应超过本地大小限制。                                           | 如果工具支持，请减少请求的输出量。类似超时的故障不能证明没有付款。  |
| `-32000`：**Assay refused the request (HTTP …)**                                         | 非成功响应中没有匹配的 MCP 响应。可能附带已识别的原因。                        | 阅读附带代码。智能体或组织被停用、账户被阻止时，需要账户所有者检查。 |
| `-32600`：**A request with this id is already in flight.**                               | 客户端复用了正在处理的 JSON-RPC ID。                              | 为每次交换使用唯一请求 ID；为同一逻辑操作保留幂等键。       |
| `-32700`、`-32600`、`-32601`                                                              | JSON 无效、MCP 请求无效，或方法不受支持。                             | 修正 MCP 客户端请求，或使用受支持的方法。            |

## 服务器错误

Assay 服务器返回的错误，例如 `TOOL_NOT_ALLOWED`、`MCP_QUOTA_EXCEEDED` 或 `IDEMPOTENCY_IN_PROGRESS`，列在 [MCP 工具](/developers/zh/can-kao/mcp-tools.md)的“共享错误和元数据”中。提高本地限额无法解决这些错误。

## 确认是否成功

为受影响的配置文件重新运行 `status`。报告的原因解决后，重复相应的免费或付费调用。成功重试会返回结果或重放。如果仍被拒绝，请在诊断报告中保留确切消息，以及相关防护代码或服务器代码。

<details>

<summary>可选：启动、安装和日志文件故障</summary>

| 消息 / 范围                                                                       | 含义                         | 解决方法                                                                                                      |
| ----------------------------------------------------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------- |
| **changes local safety settings, so it runs only in an interactive terminal** | 输入或输出使用管道。                 | 请自行运行命令；见 [CLI 参考](/developers/zh/shi-yong-gong-ju-jin-jie/cli-reference.md)。                             |
| `NODE_TLS_REJECT_UNAUTHORIZED=0` 被拒绝                                          | 证书验证被禁用。                   | 从服务器环境移除此设置。                                                                                              |
| 环境 HTTP 代理被拒绝                                                                 | 设置了代理变量，但配置文件未明确允许。        | 移除非预期变量，或通过 `settings set` 启用你自己的代理；见 [CLI 参考](/developers/zh/shi-yong-gong-ju-jin-jie/cli-reference.md)。 |
| `NODE_EXTRA_CA_CERTS` 警告                                                      | 信任了额外证书颁发机构。               | 除非是你自行添加，否则移除此设置。                                                                                         |
| 内置部署表无效 / 没有可用网址                                                              | 此构建缺少必要的部署配置。              | 使用配置正确的发布版本；不要用服务器响应中的值替换内置主机。                                                                            |
| 配置文件、权限或符号链接错误                                                                | 本地状态未通过私有文件检查。             | 恢复所有权和私有权限，不要用项目文件替换。见[安全模型](/developers/zh/shi-yong-gong-ju-jin-jie/security-model.md)。                  |
| 项目范围被拒绝 / 名称过长 / 条目冲突                                                         | 安装输入违反客户端或范围规则。            | 按 [URL 与配置文件](/developers/zh/shi-yong-gong-ju-jin-jie/urls-and-profiles.md)操作；使用受支持的范围和简短唯一名称。            |
| 配置不是普通 JSON / TOML 无效                                                         | 辅助命令无法安全解析客户端配置。           | 通过客户端编辑，或修正语法后重新运行。                                                                                       |
| **refusing to pass … through cmd.exe**                                        | Windows CLI 路径或参数包含不支持的字符。 | 在客户端自己的设置中添加条目。                                                                                           |
| 日志路径、符号链接或文件头错误                                                               | 文件不符合 MCP 日志目标要求。          | 使用已有目录中的绝对 `.log` 路径；见 [CLI 参考](/developers/zh/shi-yong-gong-ju-jin-jie/cli-reference.md)。                |

</details>

## 延伸阅读

* [CLI 参考](/developers/zh/shi-yong-gong-ju-jin-jie/cli-reference.md)
* [重试与幂等](/developers/zh/shi-yong-gong-ju-jin-jie/retries-and-idempotency.md)

## 下一步

你已读完使用工具部分。为另一个客户端设置时，可返回[安装 assay-mcp](/developers/zh/shi-yong-gong-ju-ru-men/install-assay-mcp.md)。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.goassay.ai/developers/zh/shi-yong-gong-ju-jin-jie/troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.