关于 debug-inference
debug-inference 是用于排查 OpenShell 沙箱向模型提供方发送推理请求问题的技能。它指导检查网关、提供方配置与绑定、客户端原生设置，以及常见网络或授权故障。
主要功能
- 01检查网关与沙箱环境
- 02检查提供方配置文件和绑定状态
- 03核对原生端点及客户端设置
- 04诊断常见网络与授权错误
- 05指导排查主机本地推理
适用场景
- 01排查提供方请求被拒绝
- 02诊断沙箱连接本地模型服务器的问题
- 03路由变更后查找过期端点或客户端配置
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/debug-inference确认已加载。
详细介绍
调试推理
将推理诊断为普通的、经提供方授权的网络流量。OpenShell 不再提供托管推理路由、重写请求格式或选择模型。应用会调用提供方的原生端点，并自行管理基础 URL、模型、请求格式和超时。
命令语法以已安装的 openshell --help 输出为准。
有关当前行为，请参阅已发布的提供方管理指南和提供方配置文件指南。
诊断工作流
1. 确认网关和沙箱上下文
openshell status
openshell gateway info
openshell sandbox get <sandbox>
对于主机本地模型服务，host.openshell.internal 指向运行网关的机器。如果网关位于远程，它并不指向操作者的笔记本电脑。仅监听 127.0.0.1 的服务也可能无法从容器访问；请将其绑定到网关运行时可访问的地址。
2. 检查提供方及其配置文件
openshell provider get <provider>
openshell profile export <profile-id> -o yaml
检查配置文件是否：
- 指定了客户端调用的确切端点主机、端口和协议。
- 允许客户端二进制文件。
- 声明了凭据键和预期的身份验证方式。
- 在提供方应仅公开 API 的部分功能时，使用范围有限的 HTTP 规则。
对于自定义或自托管的 OpenAI 兼容端点，请导入包含端点信息的配置文件。仅存储在提供方配置中的基础 URL 不会授权新的端点。
openshell profile lint -f ./provider-profile.yaml
openshell profile import -f ./provider-profile.yaml
openshell provider create --name <provider> --type <profile-id>
添加配置文件中显示的必需 --credential KEY 或 --credential KEY=VALUE 参数。切勿仅为消除凭据绑定错误而放宽端点策略。
3. 确认附加状态
openshell sandbox provider list <sandbox>
openshell sandbox provider attach <sandbox> <provider> --wait --timeout 30
保存此次更改的 receipt_id，并使用 openshell sandbox provider status <sandbox> <provider> --receipt <receipt-id> --wait --timeout 30 检查更改何时生效。成功表示沙箱已为新进程应用凭据、策略和环境。如果结果为待处理、失败、已暂缓或已取代，请先检查原因，再启动客户端。
附加等待成功后再启动客户端，以便客户端获取更新后的环境：
openshell sandbox exec <sandbox> -- <client-command>
更新普通静态提供方后，请等待更改生效，再启动新的客户端。现有进程保留其版本范围内的引用；就绪状态不会让旧引用解析到替换后的值。请根据各自的生命周期诊断托管刷新凭据。
请勿在诊断输出中泄露凭据和已签发的引用。确认分离后，会撤销后续凭据解析，并从未来进程的环境中移除该引用。已转发的请求仍可能完成：
openshell sandbox provider detach <sandbox> <provider> --wait --timeout 30
4. 验证原生客户端配置
应用必须使用真实的上游契约：
- 使用提供方的原生基础 URL，而不是已弃用的托管虚拟端点。
- 使用真实模型 ID，而不是 OpenShell 曾用于重写的占位符。
- 使用原生的 OpenAI、Anthropic、Vertex 或其他提供方请求格式。
- 由应用自行管理超时和重试设置。
- 使用已附加配置文件中声明的凭据环境变量。
从新启动的沙箱进程探测确切端点。如果提供方提供非敏感的发现端点，请先从该端点开始，然后按照提供方文档中的 API 格式发送最简推理请求。
5. 解读常见故障
| 症状 | 可能原因 | 解决方法 |
|---|---|---|
credential_placeholder_in_request_body | 请求体引用无效或已撤销，或者分类元数据不可用 | 检查受控拒绝原因；从对话历史中移除该引用，或恢复提供商访问权限。不要启用请求体凭据重写或绕过标志来发送工具输出。未知字面值和有效的已签发占位符（包括模型提供商自己的占位符）都会原样通过。解析请求头不会启用请求体重写。 |
| 已停用的托管端点无法进行 DNS 解析 | 客户端仍在使用已移除的托管端点 | 配置提供商原生基础 URL，并附加一个包含端点信息的提供商配置文件 |
| 直接请求被拒绝 | 缺少附加项、端点策略、HTTP 规则或二进制授权 | 检查已附加的提供商配置文件和沙盒的有效策略 |
credential_endpoint_mismatch | 凭据配置文件未授权请求接收方 | 更正主机、端口或路径，或者为目标端点导入范围严格受限的配置文件 |
request_authority_mismatch | HTTP authority 与 CONNECT 目标不一致 | 在两个 authority 中使用相同的主机和有效端口 |
| 凭据变量缺失 | 启动此进程时未附加提供商，或者多个配置文件使用了相同的键 | 附加提供商并启动新进程；明确解决重复键的问题 |
| 上游拒绝模型或请求体 | 客户端依赖已移除的模型／请求重写功能 | 在应用中配置真实模型和提供商原生请求格式 |
127.0.0.1 在主机上可用，但在沙盒中不可用 | 回环地址指向不同的运行时 | 使用 host.openshell.internal 或其他网关可访问的端点和配置文件 |
| 主机本地请求超时 | 服务器绑定地址、网关拓扑或主机防火墙阻止容器到主机的流量 | 验证侦听器，并仅允许所需的网关网络路径和端口 |
主机本地推理检查清单
适用于 Ollama、LM Studio、vLLM、SGLang、TRT-LLM 和本地 NIM 部署：
- 在网关主机上验证引擎。
- 验证引擎是否侦听网关运行时可访问的地址。
- 导入一个自定义配置文件，指定
host.openshell.internal和实际端口。 - 将配置文件限制为目标二进制文件和 API 路径。
- 创建并附加提供商。
- 配置应用的基础 URL、模型和超时。
- 从新启动的沙盒进程探测原生端点。
报告问题
报告以下信息：
- 当前使用的网关，以及拓扑是否导致了故障。
- 涉及的提供商、配置文件、附加项、端点和客户端二进制文件。
- 失败的主机、端口、路径和请求 authority 的准确值（不含机密）。
- 客户端是否仍依赖已移除的托管路由行为。
- 能够解决问题的最小范围配置文件、附加项或应用配置变更。