OpenClaw 코드 실행 스킬 설정

개요

코드 실행 스킬은 OpenClaw의 가장 강력한 생산성 기능 중 하나입니다. AI 에이전트가 코드를 작성하는 것에 그치지 않고, 안전한 샌드박스 환경에서 실제로 코드를 실행하고 출력 결과를 확인한 뒤, 그 결과를 바탕으로 반복적으로 개선할 수 있습니다. 이러한 "작성-실행-관찰-개선"의 순환 구조는 AI 에이전트가 기술적 문제를 처리하는 정확성을 크게 향상시킵니다.

실행 아키텍처

코드 실행 스킬은 OpenClaw의 샌드박스 격리 환경 위에 구축되어 있습니다. Pi SDK의 직접 임베딩 아키텍처 덕분에 코드 생성부터 실행 요청 전달까지 프로세스 간 통신 오버헤드가 없습니다. 실행 흐름은 다음과 같습니다:

AI 에이전트가 코드 조각을 생성합니다
코드가 샌드박스의 컨테이너 실행 모듈을 통해 제출됩니다
컨테이너가 격리된 환경에서 코드를 실행합니다
출력 결과(stdout, stderr, 종료 코드)가 에이전트에게 반환됩니다
에이전트가 결과를 바탕으로 다음 동작을 결정합니다

기본 설정

skills:
  codeExec:
    enabled: true
    sandbox:
      containerExec: true
      image: openclaw/code-sandbox:latest
      timeout: 30s
      memoryLimit: 256m
      cpuLimit: 0.5
    languages:
      - python
      - javascript
      - bash
      - typescript

지원 프로그래밍 언어

Python

Python은 가장 많이 사용되는 실행 언어입니다. 샌드박스 이미지에는 Python 3.11 런타임과 주요 과학 계산 라이브러리가 사전 설치되어 있습니다.

skills:
  codeExec:
    python:
      version: "3.11"
      preinstalledPackages:
        - numpy
        - pandas
        - matplotlib
        - requests
      allowPipInstall: false
      maxOutputSize: 1MB

allowPipInstall은 실행 시 추가 Python 패키지 설치를 허용할지 여부를 제어합니다. 보안상 기본적으로 비활성화되어 있습니다. 활성화할 경우 패키지 화이트리스트와 함께 사용하는 것을 권장합니다.

JavaScript / TypeScript

Node.js 런타임은 JavaScript와 TypeScript 코드 실행을 지원합니다.

skills:
  codeExec:
    javascript:
      runtime: node
      version: "20"
      allowNpmInstall: false
      esModules: true

Bash

Shell 스크립트 실행을 지원하지만, 명령 범위는 샌드박스 경로 제약에 의해 제한됩니다.

skills:
  codeExec:
    bash:
      allowedCommands:
        - ls
        - cat
        - grep
        - awk
        - sed
        - curl
      deniedCommands:
        - rm
        - dd
        - mkfs

보안 메커니즘

컨테이너 격리

모든 코드 실행은 독립된 컨테이너 인스턴스에서 수행됩니다. 컨테이너가 종료되면 실행 환경의 모든 변경 사항이 삭제됩니다. 이는 악성 코드가 호스트 시스템에 영구적인 영향을 미칠 수 없음을 의미합니다.

네트워크 제어

기본적으로 코드 실행 컨테이너에는 네트워크 접근 권한이 없습니다. 네트워크 요청이 필요한 경우(예: 외부 API 호출) 제한된 네트워크 모드를 명시적으로 활성화할 수 있습니다:

skills:
  codeExec:
    network:
      mode: restricted
      allowedHosts:
        - "api.example.com"
        - "pypi.org"
      maxBandwidth: 10MB

리소스 제한

샌드박스는 코드 실행에 엄격한 리소스 제한을 적용합니다:

시간 제한: 기본 30초, 초과 시 컨테이너 강제 종료
메모리 제한: 기본 256MB, 메모리 누수 및 메모리 폭탄 방지
CPU 제한: CPU 사용 비율을 제한하여 마이닝 등 남용 방지
출력 제한: 최대 출력 크기를 제한하여 로그 폭탄 방지
파일 시스템: 쓰기 가능한 파일의 총 크기 제한

시스템 콜 필터링

컨테이너는 seccomp 설정을 사용하여 사용 가능한 시스템 콜을 제한하고, fork bomb, 직접 디바이스 접근 등 위험한 작업을 차단합니다.

실행 모드

단일 실행

가장 기본적인 모드로, 코드를 전송하고 출력을 받습니다. 간단한 계산, 데이터 처리 및 결과 검증에 적합합니다.

인터랙티브 세션

OpenClaw은 실행 상태를 유지하는 인터랙티브 세션을 지원합니다. 여러 번의 코드 실행 간에 변수와 상태를 공유하며, Jupyter Notebook과 유사한 경험을 제공합니다.

skills:
  codeExec:
    interactiveSession:
      enabled: true
      maxDuration: 600s
      persistState: true

인터랙티브 세션의 상태는 컨테이너의 지속적인 실행을 통해 유지됩니다. 세션 타임아웃 후 컨테이너가 회수됩니다.

파일 출력

코드 실행은 파일 출력(차트, CSV 데이터 등)을 생성할 수 있습니다. 출력 파일은 마운트 디렉토리를 통해 호스트 시스템으로 매핑된 후, 메시징 도구를 통해 사용자에게 전송됩니다.

skills:
  codeExec:
    outputDir: /tmp/openclaw/code-output
    allowedOutputTypes:
      - "*.png"
      - "*.csv"
      - "*.json"
      - "*.txt"
    maxOutputFileSize: 5MB

채널과의 통합

코드 포매팅

각 채널은 코드 표시에 대해 서로 다른 포맷 요구사항을 가지고 있습니다. 시스템은 채널 유형에 따라 자동으로 코드 출력을 포매팅합니다:

Discord: Markdown 코드 블록을 사용하며, 구문 강조를 지원합니다
Telegram: <pre> 태그로 코드를 감쌉니다
Slack: Slack 네이티브 코드 블록 형식을 사용합니다
WhatsApp: 고정폭 글꼴 표시를 사용합니다

출력 잘라내기

코드 출력이 채널의 메시지 길이 제한을 초과하면, 시스템이 자동으로 잘라낸 후 "전체 출력 보기" 안내를 첨부합니다. 전체 출력은 파일 첨부 형태로 전송할 수 있습니다.

활용 시나리오

코드 실행 스킬의 주요 활용 시나리오는 다음과 같습니다:

데이터 분석: CSV/JSON 데이터를 처리하고 통계 보고서 생성
수학 계산: 정밀한 수치 계산으로 AI 모델의 산술 오류 방지
차트 생성: matplotlib 등의 라이브러리를 사용하여 시각화 차트 생성
프로토타입 검증: 코드 로직의 정확성을 빠르게 검증
자동화 스크립트: 파일 처리, 포맷 변환 등 자동화 작업 실행

모니터링 및 감사

모든 코드 실행은 제출된 코드, 실행 출력, 리소스 사용량 및 실행 시간을 포함하여 완전히 기록됩니다. 관리자는 실행 기록을 검토하여 남용 행위를 식별할 수 있습니다.

skills:
  codeExec:
    audit:
      enabled: true
      logCode: true
      logOutput: true
      retentionDays: 30

정리

코드 실행 스킬은 AI 에이전트를 "말만 하는 수준"에서 "말도 하고 실행도 하는 수준"으로 업그레이드합니다. OpenClaw의 샌드박스 격리 메커니즘을 통해 코드 실행이 안전하고 통제된 환경에서 이루어지므로, 사용자는 강력한 기능을 누리면서도 보안 위험에 대한 걱정 없이 사용할 수 있습니다.