OpenShell Go SDK 完整开发指南：面向 Kubernetes 生态的云沙箱客户端

【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载本指南以sdk/go/README.md为骨架结合仓库源码系统讲解 OpenShell Go SDK 的设计动机、客户端架构、认证体系、沙箱生命周期管理与命令执行等核心能力。读完本文你将掌握如何用与 Kubernetes client-go 同构的 Go 客户端连接 OpenShell 网关、创建并等待沙箱就绪、执行/流式/交互式命令、处理分页与令牌自动刷新以及如何借助内置 Fake 客户端进行无网关测试。为什么需要 Go SDKOpenShell 是面向自治 AI Agent 的安全、私有运行时。如果你要构建 Operator、Controller 或任何将 OpenShell 资源当作原生 Kubernetes 对象来管理的自动化程序就需要一个 Go 客户端——Go 正是 Kubernetes 生态的语言。因此这个 SDK 刻意对标k8s.io/client-go每个 Kubernetes Operator 开发者都熟悉的标准客户端库模式高度一致见 client.go 中的ClientInterface定义按资源划分的类型化子客户端client.Sandboxes()、client.Providers()、client.Exec()就像clientset.CoreV1().Pods()一样领域类型与线上格式分离干净的 Go 结构体集中在types包公共 API 不泄露 proto 细节类似k8s.io/api源码中的类型别名集中定义在 types_reexport.goWatch 原语基于 channel 的 Watcher提供ResultChan()与Stop()与 client-go 的watch.Interface行为一致函数式选项列表过滤、分页、watch 配置都通过变参 option 传递每个入口点对 nil option 静默忽略所以条件性构造的 option 切片可以原样传入无需预先过滤 nil可组合的带令牌刷新的认证封装oauth2.TokenSource实现令牌自动缓存与合并刷新合并并发刷新调用对应 client-go 的cachingTokenSource模式Fake 客户端完整客户端接口的内存实现对标k8s.io/client-go/kubernetes/fake无需真实网关即可测试 Operator。架构总览Client 子客户端树从 client.go 的接口定义可以看到 SDK 顶层形态。NewClient创建 gRPC 连接后把全部子客户端一次性接线完毕client.goClient ├── Sandboxes() → SandboxInterface (create, get, list, delete, watch, wait, logs) ├── SandboxTemplates() → SandboxTemplateInterface (可复用工作负载模板) ├── Exec() → ExecInterface (run, stream, interactive) ├── Files() → FileInterface (upload, download) ├── Health() → HealthInterface (health check, gateway info, current user) ├── Services() → ServiceInterface (expose, get, list, delete) ├── Providers() → ProviderInterface (CRUD ensure) │ ├── Profiles() → ProfileInterface (list, get, import, update, lint, delete) │ └── Refresh() → RefreshInterface (configure, status, rotate, delete) ├── Workspaces() → WorkspaceInterface (create, get, list, delete, members) ├── Config() → ConfigInterface (网关/沙箱配置读写) ├── Policy() → PolicyInterface (draft review, approve, reject, merge, status) ├── SSH() → SSHInterface (SSH 会话) └── TCP() → TCPInterface (TCP 端口转发)所有领域类型都位于openshell/v1/types/包proto 到 Go 的转换发生在内部 converter 层sdk/go/openshell/v1/internal/converter/公共 API 通过类型别名保持单包导入。Close()是幂等的内部用sync.Once保护可安全多次调用client.go。快速开始连接、建沙箱、跑命令最小可运行示例也是 README.md 的核心示例如下import v1 github.com/NVIDIA/OpenShell/sdk/go/openshell/v1 // Connect to a gateway client, err : v1.NewClient(v1.Config{ Address: gateway.example.com:443, Auth: v1.StaticToken(my-token), }) if err ! nil { log.Fatal(err) } defer client.Close() // Create a sandbox and wait until its ready sandbox, err : client.Sandboxes().Create(ctx, default, my-sandbox, v1.SandboxSpec{ Template: v1.SandboxTemplate{Image: python:3.12}, }, nil) if err ! nil { log.Fatal(err) } sandbox, err client.Sandboxes().WaitReady(ctx, default, sandbox.Name) if err ! nil { log.Fatal(err) } // Run a command result, err : client.Exec().Run(ctx, default, sandbox.Name, []string{python3, -c, print(hello from sandbox)}, v1.ExecOptions{}, ) if err ! nil { log.Fatal(err) } fmt.Println(string(result.Stdout))几个值得注意的底层行为NewClient要求cfg.Address非空否则返回ErrorInvalidArgument类型的StatusErrorcfg.Auth为 nil 时自动降级为NoAuth()client.go。Config还支持TLSCertFile/KeyFile/CAFile/Insecure、Timeout、RetryPolicy、Logger等字段。SandboxInterface的完整能力见 sandbox.go除Create/Get/Delete外还有Start/Stop、WaitReady/WaitStopped、Watch、GetLogs以及AttachProvider/DetachProvider和ListProviders等 provider 挂载操作。ExecInterface提供三种执行模式exec.goRun收集型返回完整ExecResult、Stream逐块输出迭代器、Interactive双向 I/O 的 PTY 会话。分页惰性 PagerList 方法返回一个惰性分页器不会立即发出请求。NextPage用传入的 context 拉取一页ListAll显式耗尽所有页。PageSize是每页请求上限PageToken用于从之前的查询位置续读pager, err : client.Sandboxes().List(default, v1.ListOptions{PageSize: 100}) if err ! nil { log.Fatal(err) } for { page, err : pager.NextPage(ctx) if err ! nil { log.Fatal(err) } if page nil { break } for _, sandbox : range page.Items { fmt.Println(sandbox.Name) } }认证体系从静态令牌到 OIDC 与边缘代理SDK 的认证通过实现 gRPCcredentials.PerRPCCredentials接口的AuthProvider抽象可任意组合。基础实现见 auth.goStaticToken发送Authorization: Bearer tokenNoAuth不发送任何凭证。自动令牌刷新RefreshableToken针对 OIDC 网关RefreshableToken包装任意oauth2.TokenSource提供自动缓存与合并刷新。其实现位于 auth_refresh.goimport golang.org/x/oauth2 tokenSource : oauth2Config.TokenSource(ctx, initialToken) auth, err : v1.RefreshableToken(tokenSource, v1.WithLeeway(30*time.Second), ) if err ! nil { log.Fatal(err) } client, err : v1.NewClient(v1.Config{ Address: gateway.example.com:443, Auth: auth, }) if err ! nil { log.Fatal(err) } defer client.Close()关键实现细节全部可在源码中验证LeewayWithLeeway设置在令牌到期前多少时间触发主动刷新默认 10 秒defaultLeeway 10 * time.Second负值会被截为 0。合并刷新并发调用者共享同一次刷新通过singleflight.Group的DoChan实现auth_refresh.go避免令牌端点雪崩。失败降级与退避令牌源刷新失败时SDK 会回退到已缓存令牌并记录警告日志需用WithLogger配置 logger否则警告静默丢弃同时进入指数退避1s、2s、4s……上限 30s避免放大令牌端点故障。退避期间若无缓存令牌会直接返回错误。日志接口WithLogger(l types.Logger)可注入结构化 logger用于输出刷新失败警告与隧道事件。边缘代理extra headers、Cloudflare Access 与 WebSocket 隧道当网关位于零信任反向代理之后时用WithExtraHeaders在标准认证之外附加代理专用请求头base : v1.StaticToken(my-gateway-token) auth, err : v1.WithExtraHeaders(base, map[string]string{ x-proxy-auth: proxy-secret, }) if err ! nil { log.Fatal(err) } client, err : v1.NewClient(v1.Config{ Address: gateway.example.com:443, Auth: auth, })对于 Cloudflare Accessedge包提供便捷构造器cloudflare.go它会设置cf-access-jwt-assertion头与CF_Authorizationcookieimport github.com/NVIDIA/OpenShell/sdk/go/openshell/v1/edge auth, err : edge.CloudflareAccess(base, os.Getenv(CF_ACCESS_TOKEN))对于拒绝 HTTP/2 的边缘代理可以使用 WebSocket 隧道。edge.NewTunnelProxytunnel.go在127.0.0.1上监听一个临时端口每个被接受的连接都通过携带边缘令牌的 WebSocket 握手拨号到网关并双向拷贝数据。gRPC 客户端改拨tunnel.Addr()即可tunnel, err : edge.NewTunnelProxy( wss://gateway.example.com/ws, os.Getenv(CF_ACCESS_TOKEN), ) if err ! nil { log.Fatal(err) } defer tunnel.Close() client, err : v1.NewClient(v1.Config{ Address: tunnel.Addr(), Auth: v1.StaticToken(my-token), TLS: v1.TLSConfig{Insecure: true}, // local tunnel, no TLS })隧道实现细节ws://仅允许 loopback 主机携带边缘令牌的远程连接必须使用wss://每条桥接连接设置 64 MiB 的读取上限以容纳 gRPC 帧Close()默认等待在途连接最多 5 秒排空WithCloseTimeout可调超时后强制关闭。OIDC 登录与可再生服务认证oidc包提供网关感知的 OIDC 认证涵盖浏览器、键盘、设备码和客户端凭证四种流程import github.com/NVIDIA/OpenShell/sdk/go/openshell/v1/oidc // Gateway-aware login: reads OIDC config from gateway metadata token, err : oidc.Login(ctx, my-gateway) if err ! nil { log.Fatal(err) } // Use the token with the SDK client client, err : v1.NewClient(v1.Config{ Address: gateway.example.com:443, Auth: v1.StaticToken(token.AccessToken), })无头环境使用设备码流程token, err : oidc.DeviceLogin(ctx, oidc.WithIssuer(https://auth.example.com), oidc.WithClientID(my-app), )一次性服务账号令牌交换用ClientCredentials长驻 SDK 客户端则挂载可再生、仅内存的认证提供者auth, err : oidc.NewClientCredentialsAuth( oidc.WithGateway(my-gateway), oidc.WithClientSecretProvider(func(context.Context) (string, error) { return os.Getenv(OPENSHELL_OIDC_CLIENT_SECRET), nil }), ) if err ! nil { log.Fatal(err) } client, err : v1.NewClient(v1.Config{ Address: gateway.example.com:443, Auth: auth, TLS: tlsConfig, }) if err ! nil { log.Fatal(err) } defer client.Close()除WithGateway从网关元数据自动读取 OIDC 配置外也可显式指定WithIssuer、WithClientID、WithScopes、WithAudience。该提供者会在凭证到期前重复授权且绝不把 client secret 或 access token 写入磁盘。完整选项与流程见 oidc 包源码。从 CLI 配置自动接线gateway 包gateway包能直接加载 CLI 侧已保存的网关配置并自动装配认证gateway.go。gateway.NewClient(name)解析网关目录、读取metadata.json、惰性加载令牌并按认证模式映射到对应的 SDKAuthProviderAuthModeNone/AuthModePlaintext映射到NoAuth()AuthModeCloudflareJWT映射到惰性边缘认证令牌文件缺失时NewClient依然成功错误在首次认证时才暴露AuthModeOIDC映射到RefreshableToken磁盘令牌源。name为空时使用活动网关由openshell gateway use设置LoadConfig则只解析配置不建连。ListGateways枚举用户与系统目录下所有网关同名时用户网关优先。调用方也可用WithAuth()/WithTLS()等ClientOption覆盖默认行为。交互式会话控制与退出码语义SDK 会话实现可选的InteractiveSessionControl接口exec.go在原有InteractiveSessionRead/Write/Resize/ExitCode/Close之外新增CloseWrite()关闭 stdin、保留输出与Cancel()中止 RPCCloseInteractiveInput(session)对支持CloseWrite的会话关闭输入对不支持如自定义 mock的会话返回ErrorUnimplemented并保持会话打开。CancelInteractive(session)优先调用Cancel()否则回退到Close()。SDK 的关闭/取消操作是幂等的输入关闭后的写入与 resize 返回io.ErrClosedPipe。ExitCode()会等待最终 gRPC 状态返回观察到的进程退出码及随后的流错误——退出事件本身并不代表流成功结束需要并发地Read排空输出并同时等待ExitCode()。功能一览功能接口源码入口沙箱生命周期create/get/list/delete/watch/wait/logsSandboxInterfacesandbox.go命令执行收集、流式、交互式 PTYExecInterfaceexec.goProvider 管理CRUD 幂等 ensureProviderInterfaceprovider.goProvider 配置list/import/lint/updateProfileInterfaceprofile.go凭证刷新configure/rotate/statusRefreshInterfacerefresh.go服务暴露expose/list/deleteServiceInterfaceservice.go文件传输受传输能力门控FileInterfacefile.go策略管理draft review/approve/reject/merge/globalPolicyInterfacepolicy.go沙箱日志流式获取支持行数/时间/来源/级别过滤SandboxInterfacesandbox.go工作区管理create/get/list/delete/membersWorkspaceInterfaceworkspace.go沙箱 provider 挂载attach/detach/listSandboxInterfacesandbox.go网关信息与当前用户身份HealthInterfacehealth.goSSH 隧道与 TCP 转发SSHInterface,TCPInterfacessh.go, tcp.go认证静态令牌、可刷新令牌oauth2.TokenSourceAuthProviderauth.go, auth_refresh.go边缘认证extra headers、Cloudflare Access、WebSocket 隧道AuthProvider,edge.TunnelProxycloudflare.go, tunnel.go类型化错误IsNotFound/IsAlreadyExists/IsConflict…StatusErrorerrors.go实时 watch终态自动停止WatchInterface[T]watch.go无 gRPC 服务器的 Fake 客户端fake.Clientfake.goOIDC 登录与可再生服务认证oidc.Login/oidc.DeviceLogin/oidc.ClientCredentials/oidc.NewClientCredentialsAuthoidc 包网关配置便捷加载gateway.NewClient/gateway.LoadConfiggateway.go用 Fake 客户端做无网关测试fake.Clientfake.go完整实现v1.ClientInterface所有子客户端基于内存 store。它特别适合在 CI 中测试 Operator 逻辑NewClient(opts...)直接构造无网络、无 gRPCAddSandbox/AddProvider/AddWorkspace/AddMember/AddRevision等Add*方法用于在测试开始前预置 fixture插入时深拷贝、不触发 watch 事件Close()停止所有 watcher 并让后续调用返回 Unavailable。也可用WithHealthResult/WithGatewayInfo/WithCurrentUser定制健康检查返回值。编译期通过var _ v1.ClientInterface (*Client)(nil)保证接口完整。从 v0.0.101 迁移预 1.0 版本 SDK 刻意包含一批源码不兼容的 API 修正README 明确声明迁移时注意TCP.Listen返回ForwardListener生命周期句柄SDK 拥有 accept 循环调用方拨Addr()并Close()而不是自己调Accept()或把句柄交给http.Serve资源操作改为显式传工作区携带工作区的领域类型保留该作用域若干公共结构体字段顺序变化请使用键控结构体字面量keyed struct literals首字母缩写采用 Go 拼写包括JSONRPCMaxBodyBytesProvider 配置时长使用精确的RefreshBefore、MaxLifetime、CacheTTL字段旧的整秒字段已移除。这些是模块停留在 v1 之下的有意变更建议作为一次整体迁移升级而不是继续依赖 v0.0.101 的 API 形态。前置条件与构建测试SDK 要求Go 1.25.13 或更高版本并推荐使用 mise。在克隆本仓库后进入 SDK 目录即可cd sdk/go mise run test # Run tests with coverage mise run lint # Run golangci-lint mise run ci # Full CI pipeline (lint build test)许可证为 Apache-2.0详见仓库根目录 LICENSECopyright (c) 2026 NVIDIA CORPORATION AFFILIATES. All rights reserved.赞分享【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载相关推荐OpenShell Go SDK Sandboxes 完整指南沙箱生命周期管理 API 详解OpenShell Go SDK Sandboxes 完整指南沙箱生命周期管理 API 详解 本篇技术指南聚焦 OpenShell 官方 Go SDK sdOpenShell Go SDK TCP 端口转发指南用 gRPC 双向流将沙箱端口直通本地OpenShell Go SDK TCP 端口转发指南用 gRPC 双向流将沙箱端口直通本地 OpenShell 的 Go SDK 提供了 client.TCOpenShell Go SDK 开发指南以原生 Go 类型驱动 OpenShell 网关的沙箱、执行与策略编排OpenShell Go SDK 开发指南以原生 Go 类型驱动 OpenShell 网关的沙箱、执行与策略编排 导读 OpenShell Go SDK s上一篇bspwm源码单元测试test_window.c解析与扩展方法下一篇Python高级编程使用Jinja2模板引擎打造智能代码生成器的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考