Debug Inference 是 OpenShell 中用于诊断推理客户端连接问题的技能。其核心思路是把推理视为普通的、由 provider 授权的网络流量：OpenShell 不再提供托管推理路由，不再改写请求结构，也不再选择模型。应用直接调用 provider 的原生端点，并自行负责 base URL、模型、请求格式和超时。命令语法以已安装的 openshell --help 输出为准，当前行为可参考 provider 管理指南和 provider profile 指南。
一、诊断流程
-
确认网关与沙箱上下文 使用 openshell status、openshell gateway info、openshell sandbox get <sandbox> 查看状态。对于主机本地模型服务器，host.openshell.internal 标识运行网关的机器；当网关为远程时，它并不标识操作者的笔记本。仅监听 127.0.0.1 的服务器可能无法从容器访问，应将其绑定到网关运行时可达的地址。
-
检查 provider 及其 profile 使用 openshell provider get <provider> 和 openshell profile export <profile-id> -o yaml。检查 profile 是否：命名客户端调用的确切端点主机、端口和协议；允许客户端二进制；声明凭据键和预期的认证方式；在 provider 只应暴露部分 API 时使用窄化的 HTTP 规则。对于自定义或自托管的 OpenAI 兼容端点，需导入带端点的 profile；仅存储在 provider 配置中的 base URL 不会授权新端点。相关命令包括 openshell profile lint -f ./provider-profile.yaml、openshell profile import -f ./provider-profile.yaml、openshell provider create --name <provider> --type <profile-id>，并按 profile 所示添加必需的 --credential KEY 或 --credential KEY=VALUE 参数。切勿仅为消除凭据绑定错误而放宽端点策略。
-
确认挂载 使用 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 检查何时生效。成功表示沙箱已为新进程应用凭据、策略和环境。若结果为 pending、failed、withheld 或 superseded，应在启动客户端前检查其原因。挂载等待成功后再启动客户端，使其获得更新后的环境：openshell sandbox exec <sandbox> -- <client-command>。更新普通静态 provider 后，需等待该变更并启动新客户端；已有进程保留其修订范围引用，就绪不会让旧引用解析到替换值。托管刷新凭据按其自身生命周期诊断。诊断输出中不要包含凭据和已签发的引用。已确认的 detach 会撤销未来的凭据解析并从未来进程环境中移除引用，但已转发的请求仍可能完成：openshell sandbox provider detach <sandbox> <provider> --wait --timeout 30。
-
验证原生客户端配置 应用必须使用真实的上游契约：原生 provider base URL（而非已退役的托管虚拟端点）、真实模型 ID（而非 OpenShell 过去用于改写的占位符）、原生 OpenAI、Anthropic、Vertex 或其他 provider 请求结构、应用自有的超时和重试设置，以及已挂载 profile 声明的凭据环境变量。从新启动的沙箱进程探测确切端点：先使用 provider 提供的非机密发现端点，再用 provider 文档化的 API 结构发送最小推理请求。
-
解读常见失败
- credential_placeholder_in_request_body：请求体引用无效/已撤销，或分类元数据不可用。检查受控拒绝原因；从对话历史中移除该引用或恢复 provider 访问。不要启用请求体凭据改写或绕过标志来发送工具输出。未知字面量和有效签发的占位符会原样通过，包括模型 provider 自身的占位符。头部解析不会启用请求体改写。
- 已退役托管端点 DNS 解析失败：客户端仍使用已移除的托管端点。配置 provider 的原生 base URL 并挂载带端点的 provider profile。
- 直接请求被拒：缺少挂载、端点策略、HTTP 规则或二进制授权。检查已挂载的 provider profile 和沙箱有效策略。
- credential_endpoint_mismatch：凭据 profile 未授权请求接收方。修正主机/端口/路径，或为预期端点导入窄范围 profile。
- request_authority_mismatch：HTTP authority 与 CONNECT 目标不同。在两个 authority 中使用相同主机和有效端口。
- 凭据变量缺失：此进程启动时 provider 未挂载，或 profile 在某个键上冲突。挂载 provider 并启动新进程；显式解决重复键。
- 上游拒绝模型或请求体：客户端依赖已移除的模型/请求改写。在应用中配置真实模型和 provider 原生请求格式。
- 127.0.0.1 在主机上可用但在沙箱中不可用：回环地址指向不同运行时。使用 host.openshell.internal 或其他网关可达的端点与 profile。
- 主机本地请求超时：服务器绑定地址、网关拓扑或主机防火墙阻止容器到主机的流量。验证监听器，并仅允许所需的网关网络路径和端口。
二、主机本地推理检查清单 对于 Ollama、LM Studio、vLLM、SGLang、TRT-LLM 和本地 NIM 部署：从网关主机验证引擎；验证其监听网关运行时可达的地址；导入命名 host.openshell.internal 和实际端口的自定义 profile；将 profile 限制为预期的二进制和 API 路径；创建并挂载 provider；配置应用的 base URL、模型和超时；从新启动的沙箱进程探测原生端点。
三、报告 报告内容应包括：活动网关以及拓扑是否导致失败；涉及的 provider、profile、挂载、端点和客户端二进制；确切的失败主机、端口、路径和请求 authority（不含机密）；客户端是否仍依赖已移除的托管路由行为；解决问题所需的最小范围 profile、挂载或应用配置变更。