如何扩展OpenShell：Supervisor Middleware与Gateway Interceptors二次开发指南

如何扩展OpenShellSupervisor Middleware与Gateway Interceptors二次开发指南【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址: https://gitcode.com/gh_mirrors/op/OpenShellOpenShell 是面向自主 AI Agent 的安全、私密运行时它通过两条官方扩展机制让你的 AI Agent 平台长出器官Supervisor Middleware在沙箱出站流量上插入处理阶段Gateway Interceptors在网关控制面 API 上实施治理规则。本文带你从零理解这两大扩展点的定位、请求流程、注册方式和两个可直接运行的官方示例帮助你以最小代价完成 OpenShell 二次开发。OpenShell 扩展体系全景OpenShell 由 CLI、Gateway控制面、Supervisor沙箱内本地安全边界三大组件构成架构总览见 docs/about/how-it-works.mdx。两条扩展机制恰好分别覆盖数据面和控制面机制作用位置能做什么典型场景Supervisor Middleware沙箱出站请求检查/改写 HTTP 请求体与 WebSocket 消息、拒绝请求、上报审计发现内容过滤、敏感词拦截、请求审计Gateway Interceptors网关 API 控制面在 API 写入前修改或校验操作、提交后观察响应策略治理、租户配额、合规审计两者都是独立的外部 gRPC 服务无需修改 OpenShell 本体代码也无需重启沙箱——只需重启网关即可完成注册变更。机制一Supervisor Middleware数据面流量处理中间件在请求链中的位置对于每个被检查的 HTTP 请求Supervisor 的处理顺序是评估网络与 L7 策略按目标主机选择匹配的中间件缓冲请求体按order升序执行匹配的中间件阶段注入 Provider 凭证后转发请求。关键设计每个中间件拿到的都是已被策略放行的负载——凡是替换了请求体的阶段OpenShell 会在转发前重新做协议级校验GraphQL、JSON-RPC、MCP防止上游放行、中间篡改绕过安全边界。同时中间件运行在凭证注入之前因此操作方服务永远看不到 OpenShell 托管的密钥。完整请求流程与 WebSocket 生命周期说明见 docs/extensibility/supervisor-middleware.mdx。选择中间件类型内置还是自研服务类型注册方式部署形态内置无需注册运行在 Supervisor 内部如openshell/regex令牌脱敏操作方服务需在网关 TOML 注册独立 gRPC 服务网关与 Supervisor 均可达内置的openshell/regex是最佳参考实现源码位于 crates/openshell-supervisor-middleware-builtins/src/regex.rs。注册中间件服务三步走第一步在启动网关前先把自研服务跑起来。第二步在本地网关 TOML 中追加注册项openshell/命名空间保留给内置中间件[[openshell.supervisor.middleware]] name local-content-guard grpc_endpoint https://content-guard.example:50051 audience urn:example:content-guard max_payload_bytes 262144 timeout 500ms第三步在沙箱策略的network_middlewares中挂载中间件用主机 include/exclude 选择器决定作用范围network_middlewares: regex-redactor: middleware: openshell/regex order: 10 config: mode: redact on_error: fail_closed endpoints: include: [*.example.com]⚠️ 注意两点策略最多接受 10 个中间件配置且order值在整个策略内必须唯一on_error: fail_closed默认在阶段失败时拒绝请求fail_open则跳过失败阶段并上报检测发现只建议在绕过后仍保安全的场景使用。官方示例内容守卫中间件仓库自带一个可直接运行的内容守卫示例扫描请求体与 WebSocket 文本消息中的字面词命中后替换或拒绝示例说明examples/supervisor-middleware-content-guard/README.md服务实现examples/supervisor-middleware-content-guard/src/main.rs示例策略examples/supervisor-middleware-content-guard/policy.yaml一条命令即可跑通端到端冒烟测试本地网关 内容守卫服务 沙箱创建 双目标请求对比./examples/supervisor-middleware-content-guard/smoke.sh --test-suite测试会向httpbin.org命中中间件选择器发送含敏感词prototype-secret的请求回显中被替换为[FILTERED]而发往httpbingo.org的请求不受影响直观展示了中间件选择器的作用域。机制二Gateway Interceptors控制面 API 治理拦截器如何工作网关在认证之后、请求分发之前执行拦截器完整链路为authenticate → decode and omit secrets → modify_operation → validate → gateway handler → post_commit阶段输入能力modify_operation待处理请求放行、拒绝或返回 RFC 6902 JSON 补丁validate修改后的请求 可选当前状态放行或拒绝post_commit已提交的成功响应观察响应、附加日志注解只能观察不能回滚三大安全保证值得记住补丁原子性一个绑定返回的所有补丁作为整体原子应用任一无效则整体丢弃并触发失败策略密钥不可见protobuf 中标记为 secret 的字段会被递归剔除拦截器无法读取或篡改不可绕过网关不变量modify_operation之后网关仍会执行内置操作与驱动校验补丁改不出非法操作。官方文档见 docs/extensibility/gateway-interceptors.mdx拦截器 gRPC 契约定义在 proto/gateway_interceptor.proto。注册拦截器与绑定策略[[openshell.gateway.interceptors]] name policy-governance grpc_endpoint https://governance.example:18081 order 10 failure_policy fail_closed binding_policy allowlist [[openshell.gateway.interceptors.bindings]] rpc openshell.v1.OpenShell/CreateSandbox phases [modify_operation, validate]binding_policy决定服务清单与网关配置的合成方式三种模式按治理强度递进模式行为适用dynamic启用清单中有效绑定配置可收窄兼容默认allowlist仅启用操作方配置的 RPC 与阶段安全边界推荐exact配置必须与清单完全一致强合规场景阶段选择口诀要改默认用modify_operation要守规则用validate要留审计用post_commit。注意post_commit绑定必须配置为fail_open——观察方无法撤销已提交的操作。官方示例治理拦截器治理示例是学习 OpenShell 二次开发的教科书它展示了一个拦截器能承载的完整治理闭环通过modify_operation为每个新沙箱注入签名过的policy.yaml在validate阶段拒绝任何弱化该策略的变更含沙箱自发的策略提案对外发布vendProvider Profile 目录并设为网关唯一权威来源为每次沙箱创建附加correlation_id审计注解。示例说明examples/governance-interceptor/README.md服务实现examples/governance-interceptor/src/main.rs策略哈希与签名examples/governance-interceptor/src/policy_hash.rs网关 TOML 配置examples/governance-interceptor/smoke.sh运行./smoke.sh --test-suite后测试套件会验证无签名策略扩权被拒绝、策略提案被拒绝、遥测请求被放行、活动策略版本与哈希保持不变。共享扩展基础认证与信任两种扩展服务共享同一套认证基础设施位于 crates/openshell-extension-core/网关为每次远程 RPC 附加短生命周期 EdDSA Bearer Tokencaller_kind区分gateway与supervisor调用方中间件调用还携带沙箱 ID服务侧必须校验typ: openshell-extjwt、alg固定为 EdDSA、签名、期望 issueropenshell-gateway:gateway_id、精确 audience 与有效期开发环境可用allow_insecure_transport true走明文http://不附加凭证生产环境一律使用https://。二次开发路线图从示例到生产选扩展点管流量选 Middleware管API 操作选 Interceptor二者可叠加使用跑通示例先执行 content-guard 与 governance 两个官方示例的smoke.sh --test-suite建立对服务契约的感性认识实现服务实现Describe声明绑定与能力与Evaluate处理各阶段两个 RPC注意平台限制——中间件单次负载上限 4 MiB、每阶段最多 32 条发现注册并重启网关注册是静态的增删改后必须重启网关网关启动时会对所有注册项做能力校验服务不可用则拒绝启动配置失败策略治理边界相关一律fail_closedfail_open会输出检测发现请将其纳入告警接入观测两种机制的评估日志、延迟、fail-open/fail-closed 结果均通过 OCSF 结构化日志输出见 docs/observability/ocsf-json-export.mdx。 当前已知边界仅白名单内的一元写 RPC可被拦截中间件 V1 只检查 HTTP 请求与客户端 WebSocket 文本消息mTLS 客户端认证与运行时动态注册尚不可用——规划生产方案前请在对应文档的 Current Limitations 章节确认最新限制。掌握这两条扩展通道你无需 fork OpenShell 就能把内容安全、组织治理、审计合规等企业级能力插进 AI Agent 运行时这正是 OpenShell 作为可扩展安全运行时的核心价值所在。【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址: https://gitcode.com/gh_mirrors/op/OpenShell创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考