openshell-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenShell CLI

Guide agents through using the

openshell

CLI for sandbox and platform management -- from basic operations to advanced multi-step workflows.

指导Agent使用

openshell

CLI进行沙箱和平台管理——从基础操作到高级多步骤工作流。

Overview

概述

The OpenShell CLI (

openshell

) is the primary interface for managing sandboxes, providers, policies, inference routes, and gateway registrations. Gateway service lifecycle is handled outside the CLI by packages, systemd, Helm, or development tasks. This skill teaches agents how to orchestrate CLI commands for common and complex workflows.

Companion skill: For creating or modifying sandbox policy YAML content (network rules, L7 inspection, access presets), use the

generate-sandbox-policy

skill. This skill covers the CLI commands for the policy lifecycle;

generate-sandbox-policy

covers policy content authoring.

Self-teaching: The CLI has comprehensive built-in help. When you encounter a command or option not covered in this skill, walk the help tree:

bash

openshell --help                    # Top-level commands
openshell <group> --help            # Subcommands in a group
openshell <group> <cmd> --help      # Flags for a specific command

This is your primary fallback. Use it freely -- the CLI's help output is authoritative and always up-to-date.

OpenShell CLI（

openshell

）是管理沙箱、提供商、策略、推理路由和网关注册的主要接口。网关服务生命周期由包、systemd、Helm或开发任务在CLI外部处理。本技能将教授Agent如何编排CLI命令以完成常见和复杂的工作流。

配套技能：若要创建或修改沙箱策略YAML内容（网络规则、L7检查、访问预设），请使用

generate-sandbox-policy

技能。本技能涵盖策略生命周期的CLI命令；

generate-sandbox-policy

则涵盖策略内容的编写。

自学方法：CLI内置了全面的帮助文档。当遇到本技能未涵盖的命令或选项时，请查阅帮助树：

bash

openshell --help                    # 顶级命令
openshell <group> --help            # 命令组中的子命令
openshell <group> <cmd> --help      # 特定命令的标志

这是你的主要备用方法。请放心使用——CLI的帮助输出是权威且始终最新的。

Prerequisites

前提条件

openshell

is on the PATH (install via

cargo install --path crates/openshell-cli

)

A reachable OpenShell gateway backed by Docker, Podman, Kubernetes, or the experimental VM driver
Docker is running only when using BYOC local builds or Docker-backed development workflows
For Kubernetes deployments:
```
kubectl
```
and Helm access to the target cluster

openshell

已添加至PATH（通过

cargo install --path crates/openshell-cli

安装）

可访问的OpenShell网关，由Docker、Podman、Kubernetes或实验性VM驱动程序提供支持
仅在使用BYOC本地构建或Docker支持的开发工作流时，Docker需处于运行状态
对于Kubernetes部署：拥有目标集群的
```
kubectl
```
和Helm访问权限

Command Reference

命令参考

See cli-reference.md for the full command tree with all flags and options. Use it as a quick-reference to avoid round-tripping through

--help

for common commands.

完整的命令树及所有标志和选项请参见cli-reference.md。将其用作快速参考，避免反复通过

--help

查询常见命令。

Workflow 1: Getting Started

工作流1：入门

Use this workflow when the user has a gateway endpoint and wants to get a sandbox running for the first time.

当用户拥有网关端点并首次想要运行沙箱时，使用此工作流。

Step 1: Register a gateway

步骤1：注册网关

bash

openshell gateway add http://127.0.0.1:8080 --local --name local

Use an

http://

endpoint only for trusted local port-forwarding or a protected private path. For a gateway behind an authenticated reverse proxy, register its HTTPS endpoint with

openshell gateway add https://gateway.example.com

bash

openshell gateway add http://127.0.0.1:8080 --local --name local

仅在受信任的本地端口转发或受保护的私有路径中使用

http://

端点。对于位于已认证反向代理后的网关，请使用

openshell gateway add https://gateway.example.com

注册其HTTPS端点。

Step 2: Verify the gateway

步骤2：验证网关

bash

openshell status

Confirm the gateway is reachable and shows a version.

bash

openshell status

确认网关可访问并显示版本信息。

Step 3: Create a sandbox

步骤3：创建沙箱

The simplest way to get a sandbox running:

bash

openshell sandbox create

This creates a sandbox with defaults and drops you into an interactive shell.

Shortcut for known tools: When the trailing command is a recognized tool, the CLI auto-creates the required provider from local credentials:

bash

openshell sandbox create -- claude        # Auto-creates claude provider
openshell sandbox create -- codex         # Auto-creates codex provider

The agent will be prompted interactively if credentials are missing.

运行沙箱的最简单方式：

bash

openshell sandbox create

这将创建一个默认配置的沙箱，并进入交互式shell。

已知工具快捷方式：当后续命令为已识别工具时，CLI会自动从本地凭据创建所需的提供商：

bash

openshell sandbox create -- claude        # 自动创建claude提供商
openshell sandbox create -- codex         # 自动创建codex提供商

如果缺少凭据，Agent将收到交互式提示。

Step 4: Exit and clean up

步骤4：退出并清理

Exit the sandbox shell (

exit

or Ctrl-D), then:

bash

openshell sandbox delete <name>

退出沙箱shell（

exit

或Ctrl-D），然后执行：

bash

openshell sandbox delete <name>

Workflow 2: Provider Management

工作流2：提供商管理

Providers supply credentials to sandboxes (API keys, tokens, etc.). Manage them before creating sandboxes that need them.

Supported types:

claude

opencode

codex

generic

nvidia

gitlab

github

outlook

提供商为沙箱提供凭据（API密钥、令牌等）。在创建需要凭据的沙箱之前，先管理提供商。

支持的类型：

claude

、

opencode

、

codex

、

generic

、

nvidia

、

gitlab

、

github

、

outlook

。

Create a provider from local credentials

从本地凭据创建提供商

bash

openshell provider create --name my-github --type github --from-existing

The

--from-existing

flag discovers credentials from local state (e.g.,

gh auth

tokens, Claude config files).

bash

openshell provider create --name my-github --type github --from-existing

--from-existing

标志会从本地状态中发现凭据（例如

gh auth

令牌、Claude配置文件）。

Create a provider with explicit credentials

使用显式凭据创建提供商

bash

openshell provider create --name my-api --type generic \
  --credential API_KEY=sk-abc123 \
  --config base_url=https://api.example.com

Bare

KEY

(without

=VALUE

) reads the value from the environment variable of that name:

bash

openshell provider create --name my-api --type generic --credential API_KEY

bash

openshell provider create --name my-api --type generic \
  --credential API_KEY=sk-abc123 \
  --config base_url=https://api.example.com

不带

=VALUE

的裸

KEY

会从同名环境变量中读取值：

bash

openshell provider create --name my-api --type generic --credential API_KEY

List, inspect, update, delete

列出、查看、更新、删除

bash

openshell provider list
openshell provider get my-github
openshell provider update my-github --type github --from-existing
openshell provider delete my-github

bash

openshell provider list
openshell provider get my-github
openshell provider update my-github --type github --from-existing
openshell provider delete my-github

Workflow 3: Sandbox Lifecycle

工作流3：沙箱生命周期

Create with options

使用选项创建沙箱

bash

openshell sandbox create \
  --name my-sandbox \
  --provider my-github \
  --provider my-claude \
  --policy ./my-policy.yaml \
  --upload .:/sandbox \
  -- claude

Key flags:

```
--provider
```
: Attach one or more providers (repeatable)
```
--policy
```
: Custom policy YAML (otherwise uses built-in default or
```
OPENSHELL_SANDBOX_POLICY
```
env var)
```
--cpu
```
,
```
--memory
```
: Set per-sandbox compute sizing. Docker/Podman apply limits; Kubernetes applies matching requests and limits.
```
--upload <PATH>[:<DEST>]
```
: Upload local files into the sandbox (default dest:
```
/sandbox
```
)
```
--no-keep
```
: Delete the sandbox after the initial command or shell exits
```
--forward <PORT>
```
: Forward a local port and keep the sandbox alive

bash

openshell sandbox create \
  --name my-sandbox \
  --provider my-github \
  --provider my-claude \
  --policy ./my-policy.yaml \
  --upload .:/sandbox \
  -- claude

关键标志：

```
--provider
```
：附加一个或多个提供商（可重复使用）
```
--policy
```
：自定义策略YAML（否则使用内置默认值或
```
OPENSHELL_SANDBOX_POLICY
```
环境变量）
```
--cpu
```
、
```
--memory
```
：设置每个沙箱的计算资源大小。Docker/Podman应用限制；Kubernetes应用匹配的请求和限制。
```
--upload <PATH>[:<DEST>]
```
：将本地文件上传到沙箱（默认目标：
```
/sandbox
```
）
```
--no-keep
```
：在初始命令或shell退出后删除沙箱
```
--forward <PORT>
```
：转发本地端口并保持沙箱运行

List and inspect sandboxes

列出和查看沙箱

bash

openshell sandbox list
openshell sandbox get my-sandbox

bash

openshell sandbox list
openshell sandbox get my-sandbox

Connect to a running sandbox

连接到运行中的沙箱

bash

openshell sandbox connect my-sandbox

Opens an interactive SSH shell. To configure VS Code Remote-SSH:

bash

openshell sandbox ssh-config my-sandbox >> ~/.ssh/config

bash

openshell sandbox connect my-sandbox

打开交互式SSH shell。若要配置VS Code Remote-SSH：

bash

openshell sandbox ssh-config my-sandbox >> ~/.ssh/config

Upload and download files

上传和下载文件

bash

undefined

bash

undefined

Upload local files to sandbox

将本地文件上传到沙箱

openshell sandbox upload my-sandbox ./src /sandbox/src

Download files from sandbox

从沙箱下载文件

openshell sandbox download my-sandbox /sandbox/output ./local-output

undefined

openshell sandbox download my-sandbox /sandbox/output ./local-output

undefined

View logs

查看日志

bash

undefined

bash

undefined

Recent logs

Stream live logs

流式传输实时日志

openshell logs my-sandbox --tail

Filter by source and level

按来源和级别过滤

openshell logs my-sandbox --tail --source sandbox --level warn

Logs from the last 5 minutes

最近5分钟的日志

openshell logs my-sandbox --since 5m

undefined

openshell logs my-sandbox --since 5m

undefined

Delete sandboxes

删除沙箱

bash

openshell sandbox delete my-sandbox
openshell sandbox delete sandbox-1 sandbox-2 sandbox-3   # Multiple at once

bash

openshell sandbox delete my-sandbox
openshell sandbox delete sandbox-1 sandbox-2 sandbox-3   # 批量删除

Workflow 4: Policy Iteration Loop

工作流4：策略迭代循环

This is the most important multi-step workflow. It enables a tight feedback cycle where sandbox policy is refined based on observed activity.

Key concept: Policies have static fields (immutable after creation:

filesystem_policy

landlock

process

) and one dynamic field (

network_policies

). Only

network_policies

can be updated without recreating the sandbox.

Create sandbox with initial policy
        │
        ▼
   Monitor logs ◄──────────────────┐
        │                          │
        ▼                          │
  Observe denied actions           │
        │                          │
        ▼                          │
  Pull current policy              │
        │                          │
        ▼                          │
  Modify policy YAML               │
  (use generate-sandbox-policy)    │
        │                          │
        ▼                          │
  Push updated policy              │
        │                          │
        ▼                          │
  Verify reload succeeded ─────────┘

这是最重要的多步骤工作流。它实现了一个紧密的反馈循环，可根据观察到的活动优化沙箱策略。

核心概念：策略包含静态字段（创建后不可变：

filesystem_policy

、

landlock

、

process

）和一个动态字段（

network_policies

）。只有

network_policies

可以在不重新创建沙箱的情况下更新。

使用初始策略创建沙箱
        │
        ▼
   监控日志 ◄──────────────────┐
        │                          │
        ▼                          │
  观察被拒绝的操作           │
        │                          │
        ▼                          │
  获取当前政策              │
        │                          │
        ▼                          │
  修改策略YAML               │
  (使用generate-sandbox-policy)    │
        │                          │
        ▼                          │
  推送更新后的政策              │
        │                          │
        ▼                          │
  验证重新加载成功 ─────────┘

Step 1: Create sandbox with initial policy

步骤1：使用初始策略创建沙箱

bash

openshell sandbox create --name dev --policy ./initial-policy.yaml -- claude

Sandboxes stay alive by default for iteration. Add

--no-keep

only when the sandbox should be deleted automatically after the initial session.

bash

openshell sandbox create --name dev --policy ./initial-policy.yaml -- claude

默认情况下，沙箱会保持运行以进行迭代。仅当沙箱应在初始会话后自动删除时，才添加

--no-keep

。

Step 2: Monitor logs for denied actions

步骤2：监控日志中的被拒绝操作

In a separate terminal or as the agent:

bash

openshell logs dev --tail --source sandbox

Look for log lines with

action: deny

-- these indicate blocked network requests. The logs include:

Destination host and port (what was blocked)
Binary path (which process attempted the connection)
Deny reason (why it was blocked)

在单独的终端中或作为Agent执行：

bash

openshell logs dev --tail --source sandbox

查找包含

action: deny

的日志行——这些表示被阻止的网络请求。日志包含：

目标主机和端口（被阻止的对象）
二进制文件路径（尝试连接的进程）
拒绝原因（被阻止的原因）

Step 3: Pull the current policy

步骤3：获取当前策略

bash

openshell policy get dev --full > current-policy.yaml

The

--full

flag outputs valid YAML that can be directly re-submitted. This is the round-trip format.

bash

openshell policy get dev --full > current-policy.yaml

--full

标志输出可直接重新提交的有效YAML。这是往返格式。

Step 4: Modify the policy

步骤4：修改策略

Edit

current-policy.yaml

to allow the blocked actions. For policy content authoring, delegate to the
generate-sandbox-policy
skill. That skill handles:

Network endpoint rule structure
L4 vs L7 policy decisions
Access presets (
```
read-only
```
,
```
read-write
```
,
```
full
```
)
TLS termination configuration
Enforcement modes (
```
audit
```
vs
```
enforce
```
)
Binary matching patterns

Only

network_policies

can be modified at runtime. If

filesystem_policy

landlock

, or

process

need changes, the sandbox must be recreated.

编辑

current-policy.yaml

以允许被阻止的操作。**对于策略内容编写，请委托给

generate-sandbox-policy

技能。**该技能处理：

网络端点规则结构
L4与L7策略决策
访问预设（
```
read-only
```
、
```
read-write
```
、
```
full
```
）
TLS终止配置
执行模式（
```
audit
```
vs
```
enforce
```
）
二进制匹配模式

只有

network_policies

可以在运行时修改。如果需要更改

filesystem_policy

、

landlock

或

process

，则必须重新创建沙箱。

Step 5: Push the updated policy

步骤5：推送更新后的策略

bash

openshell policy set dev --policy current-policy.yaml --wait

The

--wait

flag blocks until the sandbox confirms the policy is loaded (polls every second). Exit codes:

0: Policy loaded successfully
1: Policy load failed
124: Timeout (default 60 seconds)

bash

openshell policy set dev --policy current-policy.yaml --wait

--wait

标志会阻塞，直到沙箱确认策略已加载（每秒轮询一次）。退出代码：

0：策略加载成功
1：策略加载失败
124：超时（默认60秒）

Step 6: Verify the update

步骤6：验证更新

bash

openshell policy list dev

Check that the latest revision shows status

loaded

. If

failed

, check the error column for details.

bash

openshell policy list dev

检查最新版本的状态是否为

loaded

。如果是

failed

，请查看错误列获取详细信息。

Step 7: Repeat

步骤7：重复

Return to Step 2. Continue monitoring logs and refining the policy until all required actions are allowed and no unnecessary permissions exist.

返回步骤2。继续监控日志并优化策略，直到所有必要操作都被允许且不存在不必要的权限。

Policy revision history

策略修订历史

View all revisions to understand how the policy evolved:

bash

openshell policy list dev --limit 50

Fetch a specific historical revision:

bash

openshell policy get dev --rev 3 --full

查看所有修订版本以了解策略的演变：

bash

openshell policy list dev --limit 50

获取特定历史版本：

bash

openshell policy get dev --rev 3 --full

Workflow 5: BYOC (Bring Your Own Container)

工作流5：BYOC（Bring Your Own Container，自带容器）

Build a custom container image and run it as a sandbox.

构建自定义容器镜像并将其作为沙箱运行。

Step 1: Create a sandbox from a Dockerfile

步骤1：从Dockerfile创建沙箱

bash

openshell sandbox create --from ./Dockerfile --name my-app

The

--from

flag accepts a Dockerfile path, a directory containing a Dockerfile, a full image reference (e.g.

myregistry.com/img:tag

), or a community sandbox name (e.g.

openclaw

When given a Dockerfile or directory, the image is built locally via Docker and delivered through the selected compute driver. Docker and Podman-backed gateways can use local images directly. Kubernetes gateways usually need the image available to the cluster through a registry or driver-supported image push path.

When

--from

is specified, the CLI:

Clears default
```
run_as_user
```
/
```
run_as_group
```
(custom images may not have the
```
sandbox
```
user)
Uses a supervisor bootstrap pattern (init container copies the sandbox supervisor into a shared volume)

bash

openshell sandbox create --from ./Dockerfile --name my-app

--from

标志接受Dockerfile路径、包含Dockerfile的目录、完整镜像引用（例如

myregistry.com/img:tag

）或社区沙箱名称（例如

openclaw

）。

当给定Dockerfile或目录时，镜像将通过Docker在本地构建，并通过所选的计算驱动程序交付。Docker和Podman支持的网关可以直接使用本地镜像。Kubernetes网关通常需要镜像通过注册表或驱动程序支持的镜像推送路径对集群可用。

指定

--from

时，CLI会：

清除默认的
```
run_as_user
```
/
```
run_as_group
```
（自定义镜像可能没有
```
sandbox
```
用户）
使用supervisor引导模式（初始化容器将沙箱supervisor复制到共享卷）

Step 2: Forward ports (if the container runs a service)

步骤2：转发端口（如果容器运行服务）

bash

undefined

bash

undefined

Foreground (blocks)

前台运行（阻塞）

openshell forward start 8080 my-app

Background (returns immediately)

后台运行（立即返回）

openshell forward start 8080 my-app -d


The service is now reachable at `localhost:8080`.

openshell forward start 8080 my-app -d


现在可通过`localhost:8080`访问该服务。

Step 3: Manage port forwards

步骤3：管理端口转发

bash

undefined

bash

undefined

List active forwards

列出活跃的转发

openshell forward list

Stop a forward

停止转发

openshell forward stop 8080 my-app

undefined

openshell forward stop 8080 my-app

undefined

Step 4: Iterate

步骤4：迭代更新

To update the container:

bash

openshell sandbox delete my-app
openshell sandbox create --from ./Dockerfile --name my-app --forward 8080

要更新容器：

bash

openshell sandbox delete my-app
openshell sandbox create --from ./Dockerfile --name my-app --forward 8080

Shortcut: Create with port forward in one command

快捷方式：一步创建并转发端口

bash

openshell sandbox create --from ./Dockerfile --forward 8080 -- ./start-server.sh

The

--forward

flag starts a background port forward before the command runs, so the service is reachable immediately.

bash

openshell sandbox create --from ./Dockerfile --forward 8080 -- ./start-server.sh

--forward

标志会在命令运行前启动后台端口转发，因此服务可立即访问。

Limitations

限制

Distroless /
```
FROM scratch
```
images are not supported (the supervisor needs glibc,
```
/proc
```
, and a shell)
Missing
```
iproute2
```
or required capabilities blocks startup in proxy mode

不支持Distroless /
```
FROM scratch
```
镜像（supervisor需要glibc、
```
/proc
```
和shell）
缺少
```
iproute2
```
或所需权限会阻止代理模式下的启动

Workflow 6: Agent-Assisted Sandbox Session

工作流6：Agent辅助沙箱会话

This workflow supports a human working in a sandbox while an agent monitors activity and refines the policy in parallel.

此工作流支持人类在沙箱中工作，同时Agent监控活动并并行优化策略。

Step 1: Create sandbox with providers and keep alive

步骤1：创建带提供商的沙箱并保持运行

bash

openshell sandbox create \
  --name work-session \
  --provider github \
  --provider claude \
  --policy ./dev-policy.yaml \
  # sandbox create keeps the sandbox alive by default

bash

openshell sandbox create \
  --name work-session \
  --provider github \
  --provider claude \
  --policy ./dev-policy.yaml \
  # 默认情况下，sandbox create会保持沙箱运行

Step 2: User connects in a separate shell

步骤2：用户在单独的shell中连接

Tell the user to run:

bash

openshell sandbox connect work-session

Or for VS Code:

bash

openshell sandbox ssh-config work-session >> ~/.ssh/config

告知用户运行：

bash

openshell sandbox connect work-session

或者对于VS Code：

bash

openshell sandbox ssh-config work-session >> ~/.ssh/config

Then connect via VS Code Remote-SSH to the host "work-session"

然后通过VS Code Remote-SSH连接到主机"work-session"

undefined

undefined

Step 3: Agent monitors logs

步骤3：Agent监控日志

While the user works, monitor the sandbox logs:

bash

openshell logs work-session --tail --source sandbox --level warn

Watch for

deny

actions that indicate the user's work is being blocked by policy.

用户工作时，监控沙箱日志：

bash

openshell logs work-session --tail --source sandbox --level warn

留意

deny

操作，这些表示用户的工作被策略阻止。

Step 4: Agent refines policy

步骤4：Agent优化策略

When denied actions are observed:

Prefer incremental updates for additive network changes:

openshell policy update work-session --add-endpoint api.github.com:443:read-only:rest:enforce --binary /usr/bin/gh --wait

openshell policy update work-session --add-allow 'api.github.com:443:POST:/repos/*/issues' --wait

Use full YAML replacement when the change is broad or touches non-network fields:
```
openshell policy get work-session --full > policy.yaml
```
Modify the policy to allow the blocked actions (use
```
generate-sandbox-policy
```
skill for content)
```
openshell policy set work-session --policy policy.yaml --wait
```
Verify:
```
openshell policy list work-session
```

The user does not need to disconnect -- policy updates are hot-reloaded within ~30 seconds (or immediately when using

--wait

, which polls for confirmation).

观察到被拒绝的操作时：

对于附加网络更改，优先使用增量更新：

openshell policy update work-session --add-endpoint api.github.com:443:read-only:rest:enforce --binary /usr/bin/gh --wait

openshell policy update work-session --add-allow 'api.github.com:443:POST:/repos/*/issues' --wait

当更改范围较广或涉及非网络字段时，使用完整YAML替换：
```
openshell policy get work-session --full > policy.yaml
```
修改策略以允许被阻止的操作（使用
```
generate-sandbox-policy
```
技能处理内容）
```
openshell policy set work-session --policy policy.yaml --wait
```
验证：
```
openshell policy list work-session
```

用户无需断开连接——策略更新会在约30秒内热加载（或使用

--wait

时立即加载，该标志会轮询确认）。

Step 5: Clean up when done

步骤5：完成后清理

bash

openshell sandbox delete work-session

bash

openshell sandbox delete work-session

Workflow 7: Gateway Inference

工作流7：网关推理

Configure the gateway's managed inference route for

inference.local

配置网关的托管推理路由

inference.local

。

Set gateway inference

设置网关推理

First ensure the provider record exists:

bash

openshell provider list

Then point gateway inference at that provider and model:

bash

openshell inference set \
  --provider nvidia \
  --model nvidia/nemotron-3-nano-30b-a3b

This updates the gateway-managed

inference.local

route. There is no per-route create/list/update/delete workflow for sandbox inference.

首先确保提供商记录存在：

bash

openshell provider list

然后将网关推理指向该提供商和模型：

bash

openshell inference set \
  --provider nvidia \
  --model nvidia/nemotron-3-nano-30b-a3b

这会更新网关托管的

inference.local

路由。沙箱推理没有每条路由的创建/列出/更新/删除工作流。

Inspect current inference config

查看当前推理配置

bash

openshell inference get

bash

openshell inference get

How sandboxes use it

沙箱如何使用它

Agents send HTTPS requests to
```
inference.local
```
.
The sandbox intercepts those requests locally and routes them through the gateway inference config.
Sandbox policy is separate from gateway inference configuration.

Agent向
```
inference.local
```
发送HTTPS请求。
沙箱在本地拦截这些请求，并通过网关推理配置路由。
沙箱策略与网关推理配置是分离的。

Workflow 8: Gateway Management

工作流8：网关管理

List and switch gateways

列出和切换网关

bash

openshell gateway select            # See all gateways (no args shows list)
openshell gateway select production # Switch active gateway
openshell status                    # Verify connectivity

bash

openshell gateway select            # 查看所有网关（无参数时显示列表）
openshell gateway select production # 切换到活跃网关
openshell status                    # 验证连接性

Registration

注册

bash

openshell gateway add http://127.0.0.1:8080 --local --name local
openshell gateway add https://gateway.example.com --name production
openshell gateway remove local                         # Remove local registration

bash

openshell gateway add http://127.0.0.1:8080 --local --name local
openshell gateway add https://gateway.example.com --name production
openshell gateway remove local                         # 删除本地注册

Platform-specific deployment inspection

特定平台的部署检查

bash

undefined

bash

undefined

Inspect a Kubernetes Helm release and gateway pod

检查Kubernetes Helm版本和网关Pod

helm -n openshell status openshell kubectl -n openshell get pods,svc kubectl -n openshell logs statefulset/openshell --tail=100


For Docker, Podman, and VM-backed gateways, inspect the gateway process or container logs and the selected runtime directly.

---

helm -n openshell status openshell kubectl -n openshell get pods,svc kubectl -n openshell logs statefulset/openshell --tail=100


对于Docker、Podman和VM支持的网关，请直接检查网关进程或容器日志以及所选的运行时。

---

Self-Teaching via

--help

通过

--help

自学

When you encounter a command or option not covered in this skill:

Start broad:
```
openshell --help
```
to see all command groups.

Narrow down:

openshell <group> --help

to see subcommands (e.g.,

openshell sandbox --help

Get specific:

openshell <group> <cmd> --help

for flags and usage (e.g.,

openshell sandbox create --help

The CLI help is always authoritative. If the help output contradicts this skill, follow the help output -- the CLI may have been updated since this skill was written.

当遇到本技能未涵盖的命令或选项时：

从宽泛开始：
```
openshell --help
```
查看所有命令组。
逐步缩小范围：
```
openshell <group> --help
```
查看子命令（例如
```
openshell sandbox --help
```
）。

获取详细信息：

openshell <group> <cmd> --help

查看标志和用法（例如

openshell sandbox create --help

）。

CLI帮助始终是权威的。如果帮助输出与本技能矛盾，请遵循帮助输出——CLI可能在本技能编写后已更新。

Example: discovering an unfamiliar command

示例：发现不熟悉的命令

bash

$ openshell sandbox --help

bash

$ openshell sandbox --help

Shows: create, get, list, delete, connect, upload, download, ssh-config, image

显示：create, get, list, delete, connect, upload, download, ssh-config, image

$ openshell sandbox upload --help

Shows: positional arguments (name, path, dest), usage examples

显示：位置参数（名称、路径、目标）、用法示例

---

---

Quick Reference

快速参考

Task	Command
Register local port-forwarded gateway	`openshell gateway add http://127.0.0.1:8080 --local --name local`
Check gateway health	`openshell status`
List/switch gateways	`openshell gateway select [name]`
Create sandbox (interactive)	`openshell sandbox create`
Create sandbox with tool	`openshell sandbox create -- claude`
Create with custom policy	`openshell sandbox create --policy ./p.yaml`
Connect to sandbox	`openshell sandbox connect <name>`
Stream live logs	`openshell logs <name> --tail`
Incremental policy update	`openshell policy update <name> --add-endpoint host:443:read-only:rest:enforce --binary /usr/bin/curl --wait`
Pull current policy	`openshell policy get <name> --full > p.yaml`
Push updated policy	`openshell policy set <name> --policy p.yaml --wait`
Policy revision history	`openshell policy list <name>`
Create sandbox from Dockerfile	`openshell sandbox create --from ./Dockerfile`
Forward a port	`openshell forward start <port> <name> -d`
Upload files to sandbox	`openshell sandbox upload <name> <path>`
Download files from sandbox	`openshell sandbox download <name> <path>`
Create provider	`openshell provider create --name N --type T --from-existing`
List providers	`openshell provider list`
Configure gateway inference	`openshell inference set --provider P --model M`
View gateway inference	`openshell inference get`
Delete sandbox	`openshell sandbox delete <name>`
Remove gateway registration	`openshell gateway remove <name>`
Self-teach any command	`openshell <group> <cmd> --help`

任务	命令
注册本地端口转发网关	`openshell gateway add http://127.0.0.1:8080 --local --name local`
检查网关健康状态	`openshell status`
列出/切换网关	`openshell gateway select [name]`
创建沙箱（交互式）	`openshell sandbox create`
使用工具创建沙箱	`openshell sandbox create -- claude`
使用自定义策略创建沙箱	`openshell sandbox create --policy ./p.yaml`
连接到沙箱	`openshell sandbox connect <name>`
流式传输实时日志	`openshell logs <name> --tail`
增量更新策略	`openshell policy update <name> --add-endpoint host:443:read-only:rest:enforce --binary /usr/bin/curl --wait`
获取当前策略	`openshell policy get <name> --full > p.yaml`
推送更新后的策略	`openshell policy set <name> --policy p.yaml --wait`
策略修订历史	`openshell policy list <name>`
从Dockerfile创建沙箱	`openshell sandbox create --from ./Dockerfile`
转发端口	`openshell forward start <port> <name> -d`
上传文件到沙箱	`openshell sandbox upload <name> <path>`
从沙箱下载文件	`openshell sandbox download <name> <path>`
创建提供商	`openshell provider create --name N --type T --from-existing`
列出提供商	`openshell provider list`
配置网关推理	`openshell inference set --provider P --model M`
查看网关推理	`openshell inference get`
删除沙箱	`openshell sandbox delete <name>`
删除网关注册	`openshell gateway remove <name>`
自学任何命令	`openshell <group> <cmd> --help`

Companion Skills

配套技能

Skill	When to use
`generate-sandbox-policy`	Creating or modifying policy YAML content (network rules, L7 inspection, access presets, endpoint configuration)
`debug-openshell-cluster`	Diagnosing gateway deployment, runtime, or health failures
`debug-inference`	Diagnosing `inference.local` , host-backed local inference, and provider base URL issues
`tui-development`	Developing features for the OpenShell TUI ( `openshell term` )

技能	使用场景
`generate-sandbox-policy`	创建或修改策略YAML内容（网络规则、L7检查、访问预设、端点配置）
`debug-openshell-cluster`	诊断网关部署、运行时或健康故障
`debug-inference`	诊断 `inference.local` 、主机支持的本地推理以及提供商基础URL问题
`tui-development`	开发OpenShell TUI（ `openshell term` ）的功能

openshell-cli

Original

Translation

OpenShell CLI

OpenShell CLI

Overview

概述

Prerequisites

前提条件

Command Reference

命令参考

Workflow 1: Getting Started

工作流1：入门

Step 1: Register a gateway

步骤1：注册网关

Step 2: Verify the gateway

步骤2：验证网关

Step 3: Create a sandbox

步骤3：创建沙箱

Step 4: Exit and clean up

步骤4：退出并清理

Workflow 2: Provider Management

工作流2：提供商管理

Create a provider from local credentials

从本地凭据创建提供商

Create a provider with explicit credentials

使用显式凭据创建提供商

List, inspect, update, delete

列出、查看、更新、删除

Workflow 3: Sandbox Lifecycle

工作流3：沙箱生命周期

Create with options

使用选项创建沙箱

List and inspect sandboxes

列出和查看沙箱

Connect to a running sandbox

连接到运行中的沙箱

Upload and download files

上传和下载文件

Upload local files to sandbox

将本地文件上传到沙箱

Download files from sandbox

从沙箱下载文件

View logs

查看日志

Recent logs

最近的日志

Stream live logs

流式传输实时日志

Filter by source and level

按来源和级别过滤

Logs from the last 5 minutes

最近5分钟的日志

Delete sandboxes

删除沙箱

Workflow 4: Policy Iteration Loop

工作流4：策略迭代循环

Step 1: Create sandbox with initial policy

步骤1：使用初始策略创建沙箱

Step 2: Monitor logs for denied actions

步骤2：监控日志中的被拒绝操作

Step 3: Pull the current policy

步骤3：获取当前策略

Step 4: Modify the policy

步骤4：修改策略

Step 5: Push the updated policy

步骤5：推送更新后的策略

Step 6: Verify the update

步骤6：验证更新

Step 7: Repeat

步骤7：重复

Policy revision history

策略修订历史

Workflow 5: BYOC (Bring Your Own Container)

工作流5：BYOC（Bring Your Own Container，自带容器）

Step 1: Create a sandbox from a Dockerfile

步骤1：从Dockerfile创建沙箱

Step 2: Forward ports (if the container runs a service)

步骤2：转发端口（如果容器运行服务）

Foreground (blocks)

Self-Teaching via
`--help`

通过
`--help`
自学