OpenShell

기준일: 2026-07-26
공식 기준: OpenShell

OpenShell 문서는 OpenClaw 공식 문서(gateway/openshell)를 한국어로 정리한 가이드입니다. Use OpenShell as a managed sandbox backend for OpenClaw agents 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Use OpenShell as a managed sandbox backend for OpenClaw agents

한국어 가이드 범위: gateway/openshell 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• 사전 요구사항
• 빠른 시작
• Workspace modes
• mirror (default)
• remote
• Choosing a mode
• Configuration reference
• 예제
• Minimal remote setup
• Mirror mode with GPU
• Per-agent OpenShell with custom gateway
• Lifecycle management
• List all sandbox runtimes (Docker + OpenShell)
• Inspect effective policy
• Recreate (deletes remote workspace, re-seeds on next use)
• Security hardening
• Current limitations
• 동작 방식
• 관련 문서

상세 내용

본문

OpenShell is a managed sandbox backend: instead of running Docker containers locally, OpenClaw delegates sandbox lifecycle to the openshell CLI, which provisions remote environments and executes commands over SSH.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

사전 요구사항

plugins.entries.openshell.config.command)

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• OpenShell plugin installed (openclaw plugins install @openclaw/openshell-sandbox)
• openshell CLI on PATH (or a custom path via
• An OpenShell account with sandbox access
• OpenClaw Gateway running on the host

빠른 시작

Restart the Gateway. On the next agent turn OpenClaw creates an OpenShell sandbox and routes tool execution through it. Verify with:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

openclaw plugins install @openclaw/openshell-sandbox

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
        },
      },
    },
  },
}

openclaw sandbox list
openclaw sandbox explain

Workspace modes

This is the most important OpenShell decision.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

mirror (default)

plugins.entries.openshell.config.mode: "mirror" keeps the local workspace canonical:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Before exec, OpenClaw syncs the local workspace into the sandbox.
• After exec, OpenClaw syncs the remote workspace back to local.
• File tools go through the sandbox bridge, but local stays source of truth

remote

mode: "remote" makes the OpenShell workspace canonical:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• On first sandbox creation, OpenClaw seeds the remote workspace from local
• After that, exec, read, write, edit, and apply_patch operate
• Prompt-time media reads still work (file/media tools read through the

Choosing a mode

	mirror	remote
Canonical workspace	Local host	Remote OpenShell
Sync direction	Bidirectional (every exec)	One-time seed
Per-turn overhead	Higher (upload + download)	Lower (direct remote ops)
Local edits visible?	Yes, on next exec	No, until recreate
Best for	Development workflows	Long-running agents, CI

Configuration reference

All OpenShell config lives under plugins.entries.openshell.config:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Key	Type	Default	Description
mode	"mirror" or "remote"	"mirror"	Workspace sync mode
command	string	"openshell"	Path or name of the openshell CLI
from	string	"openclaw"	Sandbox source for first-time create
gateway	string	unset	OpenShell gateway name (top-level --gateway)
gatewayEndpoint	string	unset	OpenShell gateway endpoint (top-level --gateway-endpoint)
policy	string	unset	OpenShell policy ID for sandbox creation
providers	string[]	[]	Provider names attached at sandbox creation (deduped, one --provider flag per entry)
gpu	boolean	false	Request GPU resources (--gpu)
autoProviders	boolean	true	Pass --auto-providers (or --no-auto-providers when false) during create
remoteWorkspaceDir	string	"/sandbox"	Primary writable workspace inside the sandbox
remoteAgentWorkspaceDir	string	"/agent"	Agent workspace mount path (read-only when workspace access is not rw)
timeoutSeconds	number	120	Timeout for openshell CLI operations

예제

이 섹션의 세부 항목은 공식 문서 예제를 참고하세요.

Minimal remote setup

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
        },
      },
    },
  },
}

Mirror mode with GPU

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "agent",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "mirror",
          gpu: true,
          providers: ["openai"],
          timeoutSeconds: 180,
        },
      },
    },
  },
}

Per-agent OpenShell with custom gateway

{
  agents: {
    defaults: {
      sandbox: { mode: "off" },
    },
    list: [
      {
        id: "researcher",
        sandbox: {
          mode: "all",
          backend: "openshell",
          scope: "agent",
          workspaceAccess: "rw",
        },
      },
    ],
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
          gateway: "lab",
          gatewayEndpoint: "https://lab.example",
          policy: "strict",
        },
      },
    },
  },
}

Lifecycle management

### List all sandbox runtimes (Docker + OpenShell)

openclaw sandbox list

### Inspect effective policy

openclaw sandbox explain

### Recreate (deletes remote workspace, re-seeds on next use)

For `remote` mode, recreate is especially important: it deletes the canonical remote workspace for that scope, and the next use seeds a fresh one from local. For `mirror` mode, recreate mainly resets the remote execution environment since local stays canonical.

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

주요 항목:

- `agents.defaults.sandbox.backend`
- `plugins.entries.openshell.config.from`
- `plugins.entries.openshell.config.mode`
- `plugins.entries.openshell.config.policy`

### Security hardening

The mirror-mode filesystem bridge pins the local workspace root and rechecks canonical paths (via realpath) before every read, write, mkdir, remove, and rename, rejecting mid-path symlinks. A symlink swap or remounted workspace cannot redirect file access outside the mirrored tree.

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

### Current limitations

주요 항목:

- Sandbox browser is not supported on the OpenShell backend.
- `sandbox.docker.binds` does not apply to OpenShell; sandbox creation fails
- Docker-specific runtime knobs under `sandbox.docker.*` (other than `env`)

### 동작 방식

1. OpenClaw runs `sandbox get` for the sandbox name (with any configured `--gateway`/`--gateway-endpoint`); if that fails it creates one with `sandbox create`, passing `--name`, `--from`, `--policy` when set, `--gpu` when enabled, `--auto-providers`/`--no-auto-providers`, and one `--provider` flag per configured provider. 2. OpenClaw runs `sandbox ssh-config` for the sandbox name to fetch SSH connection details. 3. Core writes the SSH config to a temp file and opens an SSH session through the same remote filesystem bridge as the generic SSH backend. 4. In `mirror` mode: sync local to remote before exec, run, sync back after. 5. In `remote` mode: seed once on create, then operate directly on the remote workspace.

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 `--help`를 확인하세요.

### 관련 문서

주요 항목:

- Sandboxing - modes, scopes, and backend comparison
- Sandbox vs Tool Policy vs Elevated - debugging blocked tools
- Multi-Agent Sandbox and Tools - per-agent overrides
- Sandbox CLI - `openclaw sandbox` commands

## 실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: `https://docs.openclaw.ai/gateway/openshell`
2. 관련 CLI는 `openclaw --help` 및 하위 명령 `--help`로 옵션을 확인합니다.
3. 설정 변경 시 `openclaw config` / `openclaw doctor`로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

## 자주 쓰는 명령·설정 예시

```bash
openclaw plugins install @openclaw/openshell-sandbox

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
        },
      },
    },
  },
}

openclaw sandbox list
openclaw sandbox explain

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
        },
      },
    },
  },
}

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "agent",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "mirror",
          gpu: true,
          providers: ["openai"],
          timeoutSeconds: 180,
        },
      },
    },
  },
}

{
  agents: {
    defaults: {
      sandbox: { mode: "off" },
    },
    list: [
      {
        id: "researcher",
        sandbox: {
          mode: "all",
          backend: "openshell",
          scope: "agent",
          workspaceAccess: "rw",
        },
      },
    ],
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
          gateway: "lab",
          gatewayEndpoint: "https://lab.example",
          policy: "strict",
        },
      },
    },
  },
}

관련 링크

• 공식 원문: gateway/openshell
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.