OpenShell 推理故障排查指南：以 Provider 授权网络流量视角诊断 Ollama、vLLM、NIM 等推理客户端

【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载OpenShell 已将推理能力彻底收敛为「Provider 授权的普通网络流量」应用调用模型提供方的原生端点OpenShell 只负责下发凭据、授权网络路径与二进制。本文以 skills/debug-inference/SKILL.md 为核心结合仓库中的网关、沙箱、supervisor 网络层源码与官方文档给出从网关上下文、Provider Profile、附件状态到客户端配置的完整五步诊断流程并覆盖host.openshell.internal主机本地推理、credential_endpoint_mismatch、request_authority_mismatch等高频故障的根因与修复以及从已移除的托管推理端点managed inference route的迁移路径。一、先建立正确的心智模型推理 普通 Provider 授权流量诊断任何推理故障之前必须先确认当前版本的行为边界。OpenShell 不再提供托管推理路由managed inference route不会改写请求形状也不会替客户端选择模型。应用自己调用 Provider 的原生端点并自己拥有base URL、模型 ID、请求格式与超时设置。从 crates/openshell-supervisor-network/src/l7/relay.rs 的实现可以看到沙箱代理proxy对出站 HTTP 请求只做两件事先按网络策略授权流量再在授权通过且端点绑定匹配时把请求中的凭据占位符替换为真实值。这意味着「能连通」与「能用凭据」是两层独立的授权任何一层不通过都会表现为推理失败。关注点归属方凭据与刷新生命周期Provider 实例被授权的 host、port、path 与二进制Provider Profile哪个工作负载获得访问权沙箱 Provider 附件attachmentbase URL、模型、请求形状、超时原生客户端 / 工作负载配置诊断时以本机安装的openshell --help输出为命令语法的权威来源当前行为的完整说明可参考 docs/sandboxes/manage-providers.mdx 与 docs/providers/profiles.mdx。二、五步诊断工作流步骤 1确认网关与沙箱上下文先确认当前网关、沙箱状态以及故障是否与拓扑有关openshell status openshell gateway info openshell sandbox get sandbox这里有一个关键概念需要厘清host.openshell.internal标识的是运行网关的那台机器而不是操作员的笔记本。当网关部署在远程机器上时它并不指向你的本地电脑。从源码看该保留名是各沙箱驱动主动注入的宿主机别名Docker 驱动在 crates/openshell-driver-docker/src/lib.rs 定义了HOST_OPEN_SHELL_INTERNAL常量并将宿主 loopback 发布为该名称的后端地址见 crates/openshell-driver-docker/README.mdPodman 驱动通过host-gateway特殊值解析crates/openshell-driver-podman/src/container.rsVM 驱动同样注册了该别名crates/openshell-driver-vm/src/driver.rs。策略 DNS 会通过受控路径解析该保留名使策略可以到达宿主机服务而无需 Docker 网桥、容器 DNS 别名或额外的网关监听器。因此一个只在127.0.0.1上监听的模型服务在容器/沙箱内通常是不可达的loopback 在不同运行时中指向不同的网络命名空间。应把服务绑定到网关运行时可达的地址并使用host.openshell.internal作为沙箱内的访问主机。步骤 2检查 Provider 与其 Profileopenshell provider get provider openshell profile export profile-id -o yaml逐项核对 Profile是否写明了客户端要调用的确切端点host、port、协议是否放行了客户端二进制binaries是否声明了凭据键env_vars与预期的认证风格auth_style当 Provider 只应暴露 API 的一部分时是否使用了收窄的 HTTP 规则rules/deny_rules。对于自定义或自托管的 OpenAI 兼容端点必须导入一个携带端点的 Profile。仅把 base URL 存在 Provider 配置里并不会授权任何新端点——这是 docs/providers/profiles.mdx 中明确的行为如果 Provider 的*_BASE_URL指向其 Profile 声明之外的 host该 Profile 会被视为无端点endpointless凭据只能通过沙箱策略的显式绑定生效。换句话说OPENAI_BASE_URL指向别处并不意味着凭据会自动「跟着走」。正确的导入流程openshell profile lint -f ./provider-profile.yaml openshell profile import -f ./provider-profile.yaml openshell provider create --name provider --type profile-id创建 Provider 时按 Profile 的提示补齐--credential KEY或--credential KEYVALUE参数。永远不要为了压掉一个凭据绑定错误而去放宽端点策略——credential_endpoint_mismatch是安全机制在工作而不是配置冗余。步骤 3确认附件Attachment已生效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从 CLI 源码看附件与解除附件的操作都依赖网关返回的 mutation receipt命令在保存变更后会以 receipt 为依据等待沙箱应用该变更见 crates/openshell-cli/src/commands/provider.rs 与同文件的 detach 处理。等待成功意味着沙箱已为新进程应用了凭据、策略与环境如果状态是 pending等待中、failed失败、withheld被扣留或 superseded被取代务必先检查 reason再启动客户端。附件等待成功后再启动客户端确保其拿到更新后的环境openshell sandbox exec sandbox -- client-command注意修订作用域引用revision-scoped reference更新一个普通静态 Provider 后已存在的进程持有的是旧修订的引用等待就绪并不会让旧引用解析到新值——必须等待变更生效并启动新进程。托管刷新managed-refresh凭据则按其自身生命周期诊断。诊断输出中应避免暴露凭据与已签发的引用。已确认acknowledged的 detach 会撤销未来的凭据解析并把引用从未来进程环境中移除已经转发出去的请求仍可能完成openshell sandbox provider detach sandbox provider --wait --timeout 30步骤 4校验原生客户端配置应用必须使用真实的 upstream 契约逐项确认原生 Provider base URL而不是已退役的托管虚拟端点真实模型 ID而不是 OpenShell 曾经用来改写的占位模型原生请求形状OpenAI、Anthropic、Vertex 或其他 Provider 的 API 格式应用自有的超时与重试设置所附 Profile 声明的凭据环境变量。随后从新启动的沙箱进程内探测确切端点若 Provider 提供非机密发现端点discovery endpoint先探测它再用 Provider 文档化的 API 形状发送一个最小推理请求。一次成功的原生请求同时验证了端点策略、二进制归因、凭据替换、DNS 与上游服务行为参见 docs/sandboxes/inference-routing.mdx。步骤 5解读常见故障下表完整覆盖 SKILL 文档归纳的故障现象与处置并补充实现层面的依据症状可能原因修复credential_placeholder_in_request_body请求体中的引用无效/已撤销或分类元数据不可用检查受控拒绝原因从对话历史中移除该引用或恢复 Provider 访问。不要为了发送工具输出而开启请求体凭据改写或绕过开关。未知字面量与有效签发的占位符包括模型 Provider 自己的占位符原样通过Header 解析不会启用请求体改写已退役的托管端点 DNS 解析失败客户端仍在使用已移除的托管端点配置 Provider 原生 base URL并附件一个携带端点的 Provider Profile直接请求被拒绝缺少附件、端点策略、HTTP 规则或二进制授权检查所附 Provider Profile 与沙箱生效策略credential_endpoint_mismatch凭据 Profile 未授权该请求的接收方修正 host/port/path或为预期端点导入一个收窄范围的 Profilerequest_authority_mismatchHTTP authority 与 CONNECT 目标不一致在两个 authority 中使用相同的 host 与有效端口凭据变量缺失进程启动时 Provider 未附件或多个 Profile 在同一键上冲突附件 Provider 并启动新进程显式解决重复键上游拒绝模型或请求体客户端依赖了已移除的模型/请求改写在应用中配置真实模型与 Provider 原生请求格式宿主机上127.0.0.1可用但沙箱内不可用loopback 指向不同运行时改用host.openshell.internal或其他网关可达端点与 Profile主机本地请求超时服务器绑定地址、网关拓扑或宿主机防火墙阻断了容器到主机的流量验证监听器仅放行所需的网关网络路径与端口这些错误不是随机字符串而是 supervisor 网络层在 crates/openshell-supervisor-network/src/l7/relay.rs 中主动拒绝并结构化输出的结果credential_endpoint_mismatch策略放行了请求但凭据绑定不覆盖该端点。代理返回 HTTP 403响应体为{error:credential_endpoint_mismatch,message:Credential is not authorized for this request endpoint}同时发出 denied activity 事件与 OCSF 安全发现见reject_credential_resolution的实现relay.rs。记录与发现均不含秘密、占位符、环境键或查询串。request_authority_mismatchHTTP 请求的 authority 与 CONNECT 隧道目标不一致时代理直接拒绝并返回{error:request_authority_mismatch,...}relay.rs。credential_placeholder_in_request_body请求体中出现了无法转发的凭据占位符时代理返回 HTTP 403 并携带code与机器可读reason请求体凭据改写默认关闭relay.rs。三、主机本地推理清单针对 Ollama、LM Studio、vLLM、SGLang、TRT-LLM 以及本地 NIM 部署按以下顺序排查从网关主机验证推理引擎本身可用验证它监听在网关运行时可达的地址上不要只绑127.0.0.1导入一个命名了host.openshell.internal与实际端口的自定义 Profile把 Profile 收窄到预期的二进制与 API 路径创建并附件 Provider配置应用的 base URL、模型与超时从新启动的沙箱进程内探测原生端点。一个可直接落地的无凭据 Ollama 示例 Profile来自 docs/sandboxes/inference-routing.mdxid: ollama-openai display_name: Ollama description: Host-local Ollama OpenAI-compatible API category: inference inference_capable: true credentials: [] endpoints: - host: host.openshell.internal port: 11434 protocol: rest access: read-write enforcement: enforce binaries: - /usr/bin/curl - /usr/local/bin/curl - /usr/bin/python3 - /usr/local/bin/python - /sandbox/.uv/python/** - /sandbox/.venv/**lint、导入并创建实例然后创建沙箱并注入OPENAI_BASE_URLopenshell provider profile lint -f ollama-openai.yaml openshell provider profile import -f ollama-openai.yaml openshell provider create --name ollama --type ollama-openai openshell sandbox create \ --name ollama-client \ --from registry.example.com/team/python-agent:1.0 \ --provider ollama \ --env OPENAI_BASE_URLhttp://host.openshell.internal:11434/v1 \ -- python app.py若客户端库对不鉴权的服务器仍强制要求 API key可传入任意非空占位值import os from openai import OpenAI client OpenAI( base_urlos.environ[OPENAI_BASE_URL], api_keyunused, ) response client.chat.completions.create( modelqwen3.5:0.8b, messages[{role: user, content: Hello}], )对于需要鉴权的备用端点则应在自定义 Profile 中声明凭据、绑定到该端点并从原始凭据源创建 Provider——OpenShell 永远不会导出已存储的凭据值。仓库还提供了一个完整的可运行示例examples/local-inference/README.md 展示了通过 NVIDIA API Catalog 原生端点完成「导出内置 Profile → 改 ID/二进制 → lint → import → 创建 Provider → 附件 → 原生请求」的完整闭环并附带了nvidia-inference.yaml、inference.py与最小化sandbox-policy.yamlproviders/目录下则有 OpenAI、Anthropic、NVIDIA、DeepInfra 等内置 Profile 可作为起点模板先读文件头按你的镜像调整binaries与endpoints再导入切勿原样照搬。四、从已移除的托管推理端点迁移升级到无托管推理路由的版本后旧的 workspace 级openshell inference命令与托管虚拟端点已移除升级过程会删除存储的路由记录Provider 记录、刷新配置与现有沙箱附件会保留。首次在升级后创建沙箱之前必须先导入每个被保留 Provider 所引用的 Profile并为新部署在独立 ID 下建一个显式 Profile。旧路由无法自动转换它把同一个 Provider 和模型应用到 workspace 内每个沙箱而新的附件模型是按沙箱授权OpenShell 无法推断哪些沙箱应获得该权限。迁移清单要点升级前用旧版本的openshell inference get记录 Provider、模型与超时导出源 Profile编辑id、display_name、endpoints、binaries在新 ID 下导入从原始凭据源创建替换 Provider例如openshell provider create --name nvidia-native-prod --type nvidia-native --from-existing只把它附件到确需访问的沙箱逐项更新工作负载调用原生端点、读取 Profile 声明的凭据变量、发送真实模型 ID、在客户端配置超时、使用 Provider 原生请求格式附件后启动新进程先验证一次原生请求再升级生产负载仍调用已退役托管虚拟端点的代码会遭遇 DNS 解析失败——OpenShell 不再解析或信任该 host特殊场景带备用OPENAI_BASE_URL/ANTHROPIC_BASE_URL的 Provider 需要携带该 host 的自定义 Profile主机本地服务用host.openshell.internal或可达的 LAN/服务主机名而非127.0.0.1/localhost。五、上报故障无秘密的最小化报告向维护者或团队上报推理故障时按以下五点组织信息且不得包含秘密当前生效的网关以及拓扑是否构成故障因素openshell gateway info确认涉及的 Provider、Profile、附件、端点与客户端二进制openshell provider get、openshell profile export、openshell sandbox provider list失败的确切 host、port、path 与请求 authority不含任何秘密客户端是否仍依赖已移除的托管路由行为是否还在调用退役虚拟端点能解决问题的最收窄变更是收窄 Profile、修正附件还是调整应用配置而不是放宽安全策略。参考与延伸阅读skills/debug-inference/SKILL.md本文依据的诊断技能原文docs/sandboxes/inference-routing.mdx推理路由、自定义端点与迁移的完整示例docs/sandboxes/manage-providers.mdxProvider 的创建、刷新与附件管理docs/providers/profiles.mdxProfile 格式、端点绑定与凭据刷新crates/openshell-supervisor-network/src/l7/relay.rscredential_endpoint_mismatch、request_authority_mismatch与请求体凭据拒绝的实现与 OCSF 事件crates/openshell-driver-docker/README.mdhost.openshell.internal的解析与发布机制examples/local-inference/README.md原生端点推理的最小可运行示例providers/内置 Provider Profile 模板目录赞分享【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载相关推荐从零到一Ubuntu 24.04上ROCm 6.5软件源配置的完整指南 从零到一Ubuntu 24.04上ROCm 6.5软件源配置的完整指南 想要在Ubuntu 24.04上体验AMD ROCm 6.5的强大GPU计算能力开发工具高性能计算文档Kimera-Semantics 在自动驾驶中的应用实时语义地图构建技术解析Kimera Semantics 在自动驾驶中的应用实时语义地图构建技术解析 Kimera Semantics 是一款开源的实时语义地图构建库能够从 2DMetallb网络故障排查终极指南从ping到tcpdump的完整诊断流程Metallb网络故障排查终极指南从ping到tcpdump的完整诊断流程 Metallb是一个为Kubernetes集群实现网络负载均衡的开源项目它使用标云原生网络上一篇2025推理革命RLPR框架如何让AI摆脱考官依赖症下一篇Desmos Bezier Renderer核心功能解析Canny边缘检测与Bezier曲线转换原理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考