English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Gateway

OpenShell

OpenShell은 OpenClaw를 위한 관리형 샌드박스 백엔드입니다. Docker 컨테이너를 로컬에서 실행하는 대신, OpenClaw는 샌드박스 수명 주기를 openshell CLI에 위임하며, 이 CLI는 SSH 기반 명령 실행을 사용하는 원격 환경을 프로비저닝합니다.

OpenShell Plugin은 일반 SSH 백엔드와 동일한 핵심 SSH 전송 및 원격 파일 시스템 브리지를 재사용합니다. 여기에 OpenShell 전용 수명 주기(sandbox create/get/delete, sandbox ssh-config)와 선택적 mirror 워크스페이스 모드를 추가합니다.

사전 요구 사항

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

빠른 시작

  1. Plugin을 활성화하고 샌드박스 백엔드를 설정합니다.
{
  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는 원격 변경 사항을 로컬 워크스페이스로 다시 동기화하지 않습니다.
  • 파일 및 미디어 도구가 샌드박스 브리지를 통해 읽기 때문에 프롬프트 시점의 미디어 읽기는 계속 작동합니다.

적합한 경우:

  • 샌드박스가 주로 원격 측에 있어야 하는 경우.
  • 턴당 동기화 오버헤드를 낮추고 싶은 경우.
  • 호스트 로컬 편집이 원격 샌드박스 상태를 조용히 덮어쓰지 않기를 원하는 경우.

모드 선택

mirror remote
기준 워크스페이스 로컬 호스트 원격 OpenShell
동기화 방향 양방향(각 exec) 1회 시드
턴당 오버헤드 더 높음(업로드 + 다운로드) 더 낮음(직접 원격 작업)
로컬 편집 표시 여부 예, 다음 exec에서 아니요, recreate 전까지
가장 적합한 용도 개발 워크플로 장시간 실행 에이전트, CI

구성 참조

모든 OpenShell 구성은 plugins.entries.openshell.config 아래에 있습니다.

키 유형 기본값 설명
mode "mirror" 또는 "remote" "mirror" 워크스페이스 동기화 모드
command string "openshell" openshell CLI의 경로 또는 이름
from string "openclaw" 최초 생성에 사용할 샌드박스 소스
gateway string — OpenShell Gateway 이름(--gateway)
gatewayEndpoint string — OpenShell Gateway 엔드포인트 URL(--gateway-endpoint)
policy string — 샌드박스 생성을 위한 OpenShell 정책 ID
providers string[] [] 샌드박스가 생성될 때 연결할 제공자 이름
gpu boolean false GPU 리소스 요청
autoProviders boolean true 샌드박스 생성 중 --auto-providers 전달
remoteWorkspaceDir string "/sandbox" 샌드박스 내부의 기본 쓰기 가능 워크스페이스
remoteAgentWorkspaceDir string "/agent" 에이전트 워크스페이스 마운트 경로(읽기 전용 접근용)
timeoutSeconds number 120 openshell 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를 사용하는 미러 모드

{
  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를 통해 관리됩니다.

# 모든 샌드박스 런타임 나열(Docker + OpenShell)
openclaw sandbox list

# 유효 정책 검사
openclaw sandbox explain

# 다시 생성(원격 워크스페이스를 삭제하고 다음 사용 시 다시 시드)
openclaw sandbox recreate --all

remote 모드에서는 recreate가 특히 중요합니다. 해당 범위의 기준 원격 워크스페이스를 삭제하기 때문입니다. 다음 사용 시 로컬 워크스페이스에서 새 원격 워크스페이스를 시드합니다.

mirror 모드에서는 로컬 워크스페이스가 기준 상태로 유지되므로, recreate는 주로 원격 실행 환경을 재설정합니다.

다시 생성해야 하는 경우

다음 중 하나를 변경한 후에는 다시 생성하세요.

  • 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가 샌드박스의 SSH 연결 세부 정보를 가져오기 위해 openshell sandbox ssh-config <name>을 호출합니다.
  3. 코어가 SSH 구성을 임시 파일에 쓰고, 일반 SSH 백엔드와 동일한 원격 파일 시스템 브리지를 사용해 SSH 세션을 엽니다.
  4. mirror 모드: exec 전에 로컬을 원격으로 동기화하고, 실행한 뒤 exec 후 다시 동기화합니다.
  5. remote 모드: 생성 시 한 번 시드한 다음, 원격 워크스페이스에서 직접 작동합니다.

관련 항목