메인 콘텐츠로 건너뛰기
OpenShell은 OpenClaw용 관리형 샌드박스 백엔드입니다. Docker 컨테이너를 로컬에서 실행하는 대신, OpenClaw는 샌드박스 수명 주기를 openshell CLI에 위임하며, 이 CLI는 SSH 기반 명령 실행을 사용하는 원격 환경을 프로비저닝합니다. OpenShell Plugin은 범용 SSH 백엔드와 동일한 핵심 SSH 전송 및 원격 파일 시스템 브리지를 재사용합니다. 여기에 OpenShell 전용 수명 주기(sandbox create/get/delete, sandbox ssh-config)와 선택적 mirror 작업 공간 모드를 추가합니다.

​
사전 요구 사항

  • OpenShell Plugin 설치됨(openclaw plugins install @openclaw/openshell-sandbox)
  • openshell CLI가 설치되어 있고 PATH에 있음(또는 plugins.entries.openshell.config.command를 통해 사용자 지정 경로 설정)
  • 샌드박스 접근 권한이 있는 OpenShell 계정
  • 호스트에서 실행 중인 OpenClaw Gateway

​
빠른 시작

  1. Plugin을 설치하고 활성화한 다음 샌드박스 백엔드를 설정합니다.
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",
        },
      },
    },
  },
}
  1. Gateway를 다시 시작합니다. 다음 에이전트 턴에서 OpenClaw가 OpenShell 샌드박스를 만들고 도구 실행을 그 샌드박스를 통해 라우팅합니다.
  2. 확인합니다. 
openclaw sandbox list
openclaw sandbox explain

​
작업 공간 모드

OpenShell을 사용할 때 가장 중요한 결정입니다.

​
mirror

로컬 작업 공간을 정본으로 유지하려면 plugins.entries.openshell.config.mode: "mirror"를 사용하세요. 동작:
  • exec 전에 OpenClaw가 로컬 작업 공간을 OpenShell 샌드박스로 동기화합니다.
  • exec 후에 OpenClaw가 원격 작업 공간을 로컬 작업 공간으로 다시 동기화합니다.
  • 파일 도구는 여전히 샌드박스 브리지를 통해 동작하지만, 로컬 작업 공간은 턴 사이의 단일 진실 공급원으로 유지됩니다.
적합한 경우:
  • OpenClaw 외부에서 파일을 로컬로 편집하고, 해당 변경 사항이 샌드박스에 자동으로 표시되기를 원할 때.
  • OpenShell 샌드박스가 가능한 한 Docker 백엔드처럼 동작하기를 원할 때.
  • 각 exec 턴 후 호스트 작업 공간에 샌드박스 쓰기 결과가 반영되기를 원할 때.
트레이드오프: 각 exec 전후에 추가 동기화 비용이 듭니다.

​
remote

OpenShell 작업 공간을 정본으로 만들고 싶다면 plugins.entries.openshell.config.mode: "remote"를 사용하세요. 동작:
  • 샌드박스가 처음 만들어질 때 OpenClaw가 로컬 작업 공간을 원격 작업 공간에 한 번 시드합니다.
  • 이후 exec, read, write, edit, apply_patch는 원격 OpenShell 작업 공간에 대해 직접 동작합니다.
  • OpenClaw는 원격 변경 사항을 로컬 작업 공간으로 다시 동기화하지 않습니다.
  • 파일 및 미디어 도구가 샌드박스 브리지를 통해 읽기 때문에 프롬프트 시점의 미디어 읽기는 계속 동작합니다.
적합한 경우:
  • 샌드박스가 주로 원격 측에 있어야 할 때.
  • 턴당 동기화 오버헤드를 낮추고 싶을 때.
  • 호스트 로컬 편집이 원격 샌드박스 상태를 조용히 덮어쓰지 않기를 원할 때.
초기 시드 후 OpenClaw 외부에서 호스트의 파일을 편집하면 원격 샌드박스는 해당 변경 사항을 보지 못합니다. 다시 시드하려면 openclaw sandbox recreate를 사용하세요.

​
모드 선택

mirrorremote
정본 작업 공간로컬 호스트원격 OpenShell
동기화 방향양방향(각 exec)1회 시드
턴당 오버헤드높음(업로드 + 다운로드)낮음(직접 원격 작업)
로컬 편집 표시 여부예, 다음 exec에서아니요, 다시 만들 때까지
적합한 경우개발 워크플로장기 실행 에이전트, CI

​
구성 참조

모든 OpenShell 구성은 plugins.entries.openshell.config 아래에 있습니다.
키유형기본값설명
mode"mirror" 또는 "remote""mirror"작업 공간 동기화 모드
commandstring"openshell"openshell CLI의 경로 또는 이름
fromstring"openclaw"최초 생성 시 사용할 샌드박스 소스
gatewaystring—OpenShell Gateway 이름(--gateway)
gatewayEndpointstring—OpenShell Gateway 엔드포인트 URL(--gateway-endpoint)
policystring—샌드박스 생성용 OpenShell 정책 ID
providersstring[][]샌드박스 생성 시 연결할 Provider 이름
gpubooleanfalseGPU 리소스 요청
autoProvidersbooleantrue샌드박스 생성 중 --auto-providers 전달
remoteWorkspaceDirstring"/sandbox"샌드박스 내부의 기본 쓰기 가능 작업 공간
remoteAgentWorkspaceDirstring"/agent"에이전트 작업 공간 마운트 경로(읽기 전용 접근용)
timeoutSecondsnumber120openshell CLI 작업의 제한 시간
샌드박스 수준 설정(mode, scope, workspaceAccess)은 다른 백엔드와 마찬가지로 agents.defaults.sandbox 아래에서 구성합니다. 전체 매트릭스는 샌드박싱을 참조하세요.

​
예시

​
최소 원격 설정

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

​
GPU를 사용하는 Mirror 모드

{
  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,
        },
      },
    },
  },
}

​
사용자 지정 Gateway를 사용하는 에이전트별 OpenShell

{
  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",
        },
      },
    },
  },
}

​
수명 주기 관리

OpenShell 샌드박스는 일반 샌드박스 CLI를 통해 관리됩니다. 
# List all sandbox runtimes (Docker + OpenShell)
openclaw sandbox list

# Inspect effective policy
openclaw sandbox explain

# Recreate (deletes remote workspace, re-seeds on next use)
openclaw sandbox recreate --all
remote 모드에서는 다시 만들기가 특히 중요합니다. 해당 범위의 정본 원격 작업 공간을 삭제하기 때문입니다. 다음 사용 시 로컬 작업 공간에서 새 원격 작업 공간을 시드합니다. mirror 모드에서는 로컬 작업 공간이 정본으로 유지되므로 다시 만들기는 주로 원격 실행 환경을 재설정합니다.

​
다시 만들어야 하는 경우

다음 중 하나를 변경한 후 다시 만드세요.
  • agents.defaults.sandbox.backend
  • plugins.entries.openshell.config.from
  • plugins.entries.openshell.config.mode
  • plugins.entries.openshell.config.policy
openclaw sandbox recreate --all

​
보안 강화

OpenShell은 작업 공간 루트 fd를 고정하고 각 읽기 전에 샌드박스 ID를 다시 확인하므로, 심볼릭 링크 교체나 다시 마운트된 작업 공간이 읽기를 의도한 원격 작업 공간 밖으로 리디렉션할 수 없습니다.

​
현재 제한 사항

  • 샌드박스 브라우저는 OpenShell 백엔드에서 지원되지 않습니다.
  • sandbox.docker.binds는 OpenShell에 적용되지 않습니다.
  • sandbox.docker.* 아래의 Docker 전용 런타임 노브는 Docker 백엔드에만 적용됩니다.

​
작동 방식

  1. OpenClaw가 openshell sandbox create를 호출합니다(구성된 대로 --from, --gateway, --policy, --providers, --gpu 플래그 사용).
  2. OpenClaw가 openshell sandbox ssh-config <name>을 호출하여 샌드박스의 SSH 연결 세부 정보를 가져옵니다.
  3. 코어가 SSH 구성을 임시 파일에 쓰고, 범용 SSH 백엔드와 동일한 원격 파일 시스템 브리지를 사용해 SSH 세션을 엽니다.
  4. mirror 모드: exec 전에 로컬을 원격으로 동기화하고, 실행한 뒤 exec 후 다시 동기화합니다.
  5. remote 모드: 생성 시 한 번 시드한 뒤 원격 작업 공간에서 직접 동작합니다.

​
관련 항목