> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/zh/kai-fa/embed/troubleshooting.md).

# 嵌入故障排除

诊断缺失的特性、被阻塞的 turn、凭据、状态路径和生命周期失败。

请将类型化错误与有效能力报告结合起来使用。被编译排除的方法与已配置但提供程序发生失败的方法是不同的问题。请勿在常规诊断中包含凭据、用户提示和原始提供程序载荷。

| 症状                             | 检查与下一步                                                     |
| ------------------------------ | ---------------------------------------------------------- |
| `RuntimeError::AlreadyRunning` | 重用进程运行时；在重启前移除旧的监听器、代理和运行时。配置文件需要它们自己的进程模式。                |
| 在编译时未找到方法或类型                   | 检查命名的 Embed Cargo 门控，尤其是 `mcp`/`skills`。仅核心编译标志不会激活这些外观导出。 |
| `CoreError::Unavailable`       | 检查有效域/模块以及已编译特性。运行时选择可以缩小一个已编译的系列。                         |
| `BACKEND_UNAVAILABLE`          | 安装主机后端传输层，通常通过 `openhuman-tinyhumans`，然后再进行会接触后端的调用。       |
| 凭据主密钥失败                        | 在持久化运行时 API 密钥之前初始化进程主密钥状态；检查无头密钥/文件设置时不要打印其值。             |
| 无效或不安全的提供程序路由                  | 为远程 bearer 路由提供非空端点/密钥，并使用 HTTPS。回环测试夹具与远程端点是分开的。          |
| 嵌套轮次中的栈溢出                      | 使用文档中指定的 Tokio 工作线程栈；默认的 2 MiB 栈不够。请遵循可运行示例的支持设置。          |
| 一个写入一直在等待                      | 轮询同一代理的批准，或保留一个活动的回调订阅。检查来源、已启用的自主性以及受信任的操作根。              |
| 流式传输似乎停滞了                      | 在工作运行时清空有界进度流；检查最终结果。丢弃它会取消转发，并协作式地结束该轮次。                  |
| 某个技能缺失                         | 将一个真实的捆绑包复制到代理的技能目录中；符号链接的捆绑包会被拒绝。新指令需要新的会话。               |
| 代理注册返回 `DuplicateId`           | 另一个实例或清理过程仍在占用该 ID。等待移除/最后一个句柄的清理完成。                       |
| 保留的句柄返回 `AgentRemoved`         | 该实例已被移除；请获取新注册的句柄，而不是继续使用旧的。                               |
| `解码` 类型化外观中的错误                 | 将其视为 API/结果形状不匹配；保留安全元数据并报告回归问题。                           |

## 在不暴露凭据的情况下检查

```rust
    let info = runtime.capabilities();
    assert_eq!(info.schema_version, 1);
    assert!(info.defaults.routed_provider);
    let serialized = serde_json::to_string(&info)?;
    assert!(!serialized.contains("sk-test"));
    assert!(!serialized.contains(&provider.uri()));
    assert!(!serialized.contains(&runtime.workspace_dir().display().to_string()));
    println!("{}", serde_json::to_string_pretty(&info)?);
```

[完整可运行示例](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/examples/capability_report.rs)，包括运行时构造、导入和测试夹具设置。

在启动之前， `RuntimeBuilder::describe` 可以报告一个暂定计划；检查 `configuration_resolved`。启动后， `Runtime::capabilities` 描述已解析的默认值、存储来源/驱动以及选择结果，但不包含其 URL/密钥。运行时事件提供不含内容的生命周期元数据，而显式的轮次进度可以包含文本，应相应处理。

使用 [离线测试](https://tinyhumans.gitbook.io/openhuman/zh/kai-fa/embed/guides/mock-backend-testing.md) 来复现行为，然后再使用实时提供程序。该 [错误概念](https://tinyhumans.gitbook.io/openhuman/zh/kai-fa/embed/concepts/errors.md) 解释了结构化类型和预期用户状态错误。
