OpenClaw Code Execution vs Exec: 적절한 명령 인터페이스(Command Surface) 선택하기

에이전트 도구 사용 시 발생하는 대부분의 운영자 실수는 잘못된 명령 인터페이스(Command Surface) 선택에서 시작됩니다. 작업은 사소해 보이고, 에이전트는 충분히 적절해 보이는 도구를 선택하지만, 갑자기 무해한 분석 작업이 로컬 파일(local files)을 읽으려 시도하거나, 로컬 빌드(local build)가 리포지토리(repo)를 볼 수 없는 원격 분석 샌드박스(remote analysis sandbox)로 전송되는 상황이 발생합니다.

OpenClaw는 code_execution과 exec를 모두 제공하지만, 이 둘은 서로 교체하여 사용할 수 있는 것이 아닙니다. 이 차이는 단순한 브랜딩의 차이가 아닙니다. 이는 원격의 휘발성(ephemeral) Python 분석과 사용자의 머신, Gateway 호스트, 샌드박스(sandbox), 또는 페어드 노드(paired node) 상에서 상태를 변경하는(mutating) 쉘(shell) 인터페이스 간의 차이입니다.

수익 창출 작업, 지원 운영, 배포 또는 마케팅 자동화를 위해 OpenClaw를 실행한다면, 이 구분은 매우 중요합니다. 올바른 인터페이스는 에이전트에게 불필요한 권한을 부여하지 않으면서도 유용성을 유지하게 합니다. 잘못된 인터페이스는 작업을 차단하거나, 작업에 필요한 것보다 더 많은 권한을 넘겨주게 됩니다.

요약 버전

에이전트가 원격 Python 샌드박스 내에서 인라인 데이터(inline data)를 분석해야 할 때는 code_execution을 사용하세요. 에이전트가 사용자의 로컬 쉘(local shell), 리포지토리(repo), 파일(files), 빌드 도구(build tools), 배포 CLI(deployment CLI) 또는 페어드 디바이스(paired devices)를 사용해야 할 때는 exec를 사용하세요.

공식 문서에서는 그 경계를 명확히 규정하고 있습니다: code_execution은 xAI의 Responses API를 통해 샌드박스 처리된 원격 Python 분석을 실행합니다. exec는 설정에 따라 워크스페이스(workspace), Gateway 호스트, 샌드박스 런타임(sandbox runtime) 또는 페어드 노드(paired node)에서 쉘 명령(shell commands)을 실행합니다.

따라서 code_execution은 계산, 표 작성(tabulation), 빠른 통계, 차트 스타일 분석, 그리고 web_search 또는 x_search에 의해 반환된 데이터를 처리하는 데 적합합니다. 이는 지속적인 노트북(persistent notebook)이 아니며, 로컬 파일, 리포지토리, 쉘 또는 연결된 디바이스를 볼 수 있을 것이라고 기대해서는 안 됩니다.

exec는 정반대의 성격을 가진 도구입니다. 이는 작업이 정말로 로컬(local)에서 이루어져야 할 때 사용하는 것입니다. 빌드를 실행하거나, 리포지토리(repo)를 검사하거나, 스크립트를 실행하거나, CLI로 배포하거나, 테스트 러너(test runner)를 호출하거나, 특정 노드(node)를 대상으로 할 때 사용합니다. 공개 문서에서는 또한 exec가 상태를 변경하는 쉘 표면(mutating shell surface)이라고 경고합니다. 명령은 선택된 호스트(host)나 샌드박스(sandbox) 파일 시스템이 허용하는 곳 어디에서든 파일을 생성, 수정 또는 삭제할 수 있습니다. 파일 시스템 쓰기 도구를 비활성화한다고 해서 exec가 읽기 전용(read-only)이 되는 것은 아닙니다.

이것이 구매 의도(buyer-intent)의 문제인 이유

팀들이 에이전트 운영 플레이북(agent operations playbook)을 구매하는 이유는 더 많은 도구를 원해서가 아닙니다. 에이전트가 잘못된 시점에 잘못된 도구를 계속 선택하기 때문입니다. 한 번의 실수는 배포 시간(deploy window)을 날려버립니다. 또 다른 실수는 로컬의 가정을 원격 환경으로 유출합니다. 또 다른 실수는 실제로 어떤 머신에서 명령이 실행되었는지 아무도 설명할 수 없게 만들어 비즈니스 프로세스를 취약하게 만듭니다.

도구 선택은 지루하고 반복 가능해야 합니다. 작업이 "이 숫자들을 비교해줘"라면, 에이전트에게 쉘(shell) 액세스가 필요해서는 안 됩니다. 작업이 "프로덕션 빌드를 실행해줘"라면, 원격 Python 샌드박스(sandbox)는 적절한 장소가 아닙니다. 작업이 "웹을 검색한 다음 요약하고 카테고리를 세어줘"라면, 에이전트는 로컬 쉘 명령이 아니라 먼저 web_search를 사용하고 그다음에 code_execution을 사용해야 할 수도 있습니다.

이것이 제가 비즈니스 워크스페이스(business workspace)에서 원하는 운영 패턴입니다. 가장 작은 권한을 가진 표면(smallest capable surface)을 우선시하고, 작업에 실제로 필요할 때만 더 강력한 권한을 부여하는 것입니다.

code_execution이 잘하는 것

code_execution은 프롬프트(prompt)와 함께 이동할 수 있는 분석을 위한 것입니다. 이 도구는 내부적으로 단일 task 파라미터(parameter)를 취하므로, 에이전트는 전체 요청과 모든 인라인 데이터(inline data)를 하나의 분석 프롬프트에 담아 보내야 합니다. 입력값이 숫자 리스트, 채팅창에 붙여넣은 표, 또는 소량의 검색 결과라면 이는 자연스럽게 적합합니다.

문서에는 일반적인 용도가 직접 나열되어 있습니다: 계산, 표 작성, 빠른 통계, 차트 스타일 분석, 그리고 x_search 또는 web_search에 의해 반환된 데이터 분석 등입니다. 문서에 명시된 검증된 예시는 다음과 같습니다:

`web_search`를 사용하여 최신 AI 벤치마크 수치를 수집한 다음, `code_execution`을 사용하여 백분율 변화를 비교하세요.

핵심 문구는 "반환된 데이터"입니다. code_execution은 로그인이 필요한 대시보드를 브라우징하거나 사용자의 프로젝트 파일을 읽는 도구가 아닙니다. 대신 에이전트가 전달해 주는 데이터를 분석할 수 있습니다. 최신 X(구 트위터) 데이터를 얻으려면, 문서에서는 먼저 x_search를 사용한 다음 그 결과를 code_execution으로 파이프라인(pipe) 연결하여 사용하라고 명시하고 있습니다.

설정 또한 의도적으로 xAI와 연결되어 있습니다. 공개 문서에는 번들로 제공되는 xai 플러그인, xAI OAuth 또는 API 키 자격 증명, XAI_API_KEY 환경 변수, 그리고 플러그인 설정이 유효한 자격 증명 경로로 설명되어 있습니다. 튜닝된 설정은 다음과 같은 형태일 수 있습니다:

{
  plugins: {
    entries: {
...

저는 다음과 같은 질문들에 대해 해당 인터페이스(surface)를 사용할 것입니다:

• 붙여넣은 매출 표에서 이동 평균(moving average) 계산하기.
• 에이전트가 이미 가져온 웹 검색(web-search) 결과들을 소스 유형별로 그룹화하기.
• 적은 양의 벤치마크 수치들 사이의 백분율 변화 비교하기.
• 인라인 JSON으로부터 콘텐츠 캘린더나 큐(queue) 분포를 무결성 검사(sanity-check)하기.

하지만 로컬 패키지 설치, 빌드 검증, 파일 마이그레이션, 스크린샷 검사, 장치 제어, Git 상태 확인, 또는 현재 워크스페이스(workspace)에 의존하는 작업에는 사용하지 않을 것입니다. 그러한 작업들은 원격 분석(remote-analysis) 문제에 해당하지 않습니다.

모호한 에이전트 데모가 아닌, 실제 운영 규칙이 필요하신가요?

ClawKit은 도구 선택, 명령 안전성, 메모리, 그리고 프로덕션 실행을 위한 실질적인 패턴을 제공합니다. ClawKit을 $9.99에 구매하세요.

exec가 잘하는 것

exec는 셸(shell)입니다. 포그라운드(foreground) 명령과 백그라운드(background) 명령을 실행할 수 있고, TTY 전용 CLI를 위해 의사 터미널(pseudo-terminal)을 사용할 수 있으며, 작업 디렉터리(working directory) 설정, 환경 변수 재정의(environment overrides) 전달, 그리고 명령 타임아웃(command timeouts) 강제 적용이 가능합니다. 현재 문서에서는 host 라우팅을 auto, sandbox, gateway, 또는 node로 설명합니다. auto는 샌드박스 런타임(sandbox runtime)이 활성화되어 있으면 sandbox로 결정되고, 그렇지 않으면 Gateway로 결정됩니다.

이는 로컬, 상태 유지(stateful), 또는 머신 특정(machine-specific) 작업에 적합한 인터페이스입니다:

• npm run build, 테스트, 린터(linters) 또는 검증 스크립트 실행.
• 저장소 상태 및 스테이징된 변경 사항(staged changes) 조사.
• 로컬 인증 또는 프로젝트 파일에 의존하는 배포 CLI 실행.
• 웹사이트 또는 제품 워크스페이스 내의 스크립트 실행.
• 명령이 특정 머신에서 실행되어야 하는 경우 페어링된 노드(paired node)를 대상으로 지정.

exec는 상태를 변경(mutate)할 수 있기 때문에, 보안 태세(safety posture)를 명시적으로 설정해야 합니다. 문서는 ~/.openclaw/exec-approvals.json에 있는 승인 파일, 세션별 /exec 재정의(overrides), 노드 바인딩(node binding), 안전한 바이너리(safe bins), 허용 목록(allowlists), 그리고 엄격한 인라인 평가(inline-eval) 제어에 대해 설명합니다. 만약 이러한 사항들을 고려하지 않았다면, exec에 대한 고민을 끝낸 것이 아닙니다.

/exec host=auto security=allowlist ask=on-miss node=mac-1

해당 세션 재정의(session override)는 host, security, ask, node에 대한 세션별 기본값을 설정하는 방법으로 문서화되어 있습니다. 이는 세션 상태만 업데이트하며, 영구적인 설정(persistent config)을 작성하지는 않습니다. 이는 유용한 경계(boundary)입니다. 임시 라우팅(Temporary routing)은 기업 전체의 명령 정책(command policy)을 변경하는 것과는 다릅니다.

web_search와 web_fetch의 역할

세 번째 실수는 두 명령 인터페이스(command surface) 중 어느 하나에 웹 작업을 강요하는 것입니다. OpenClaw의 web_search는 구성된 제공자(provider)를 통해 웹을 검색합니다. 문서는 이를 브라우저 자동화(browser automation)가 아닌 경량 HTTP 도구라고 부릅니다. JavaScript 비중이 높은 사이트나 로그인이 필요한 경우에는 브라우저 도구를 사용하십시오. 특정 URL을 가져오려면 web_fetch를 사용하십시오.

이를 통해 다음과 같은 깔끔한 체인을 구성할 수 있습니다:

1. 에이전트가 제공자로부터 최신 웹 검색 결과가 필요할 때는 web_search를 사용합니다.
2. 이미 특정 URL을 가지고 있고 경량 페이지 콘텐츠가 필요한 경우에는 web_fetch를 사용합니다.
3. 소스 데이터가 X(구 트위터) 포스트인 경우에는 x_search를 사용합니다.
4. 데이터가 확보되었고 남은 작업이 분석인 경우에만 code_execution을 사용합니다.
5. 로컬 셸 상태, 파일, 스크립트, 빌드, 배포 또는 노드가 실제로 필요한 경우에만 exec를 사용합니다.

그러한 순서는 웹 탐색 (web discovery)이 셸 (shell) 내부로 들어오는 것을 방지하고, 단순한 분석 작업에 로컬 셸 권한 (local shell authority)이 포함되지 않도록 유지합니다. 또한 실패 시 디버깅을 더 쉽게 만들어 줍니다. 검색이 실패하면 제공자 자격 증명 (provider credentials)이나 쿼리 형태 (query shape)를 수정하면 됩니다. 분석이 실패하면 인라인 데이터 (inline data)를 검사하면 됩니다. 만약 exec가 실패하면 호스트 (host), 작업 디렉토리 (workdir), 승인 정책 (approval policy), 명령 (command) 또는 로컬 환경 (local environment)을 검사하면 됩니다.

실질적인 결정 규칙

에이전트 (agent)가 스스로 선택하게 하기 전에, 세 가지 질문을 던져보십시오.

작업에 로컬 파일이나 로컬 인증 (local auth)이 필요한가?

만약 그렇다면, 아마도 exec를 사용해야 합니다. 빌드 (builds), 배포 (deploys), Git 작업, 로컬 스크립트, Vercel CLI 호출, 그리고 노드에 종속된 명령 (node-bound commands)은 로컬 환경에 의존합니다. 원격 Python 샌드박스 (remote Python sandbox)는 해당 컨텍스트 (context)를 안전하게 추론할 수 없습니다.

필요한 모든 입력값이 프롬프트 (prompt) 안에 들어갈 수 있는가?

만약 그렇고, 출력값이 분석 (analysis)이라면, code_execution만으로도 충분할 것입니다. 이는 특히 숫자, 붙여넣은 JSON, 작은 표, 그리고 검색 결과 요약의 경우에 그러합니다. 이를 워크스페이스 런타임 (workspace runtime)이 아닌, 일회성 분석 도우미로 취급하십시오.

누락된 입력값이 공개 웹 (public web)에 있는가?

만약 그렇다면, web_search 또는 web_fetch로 시작하십시오. 그 결과에 대해 개수 세기, 그룹화 또는 수치 분석이 필요하다면, 해당 결과를 code_execution으로 전달하십시오. 작업이 구체적으로 로컬 명령줄 도구 (local command-line tooling)를 필요로 하지 않는 한, exec로 시작하지 마십시오.

운영자급 패턴 (The operator-grade pattern)

운영 환경의 워크스페이스 (production workspace)에서, 저는 에이전트가 다음과 같은 단계 (ladder)를 기본값으로 사용하기를 원합니다.

1. 웹 탐색 (web discovery)을 위해 관리형 웹 도구 (managed web tools)를 사용한다.
2. 명시적인 데이터에 대한 원격 분석 (remote analysis)을 위해 code_execution을 사용한다.
3. 실제 셸 작업 (real shell work)을 위해 exec를 사용하되, 실질적으로 가장 좁은 범위의 호스트 (host) 및 승인 태세 (approval posture)를 유지한다.
4. 작업이 페어링된 머신 (paired machine)에서 반드시 수행되어야 하는 경우에만 노드 라우팅 (node routing)을 사용한다.
5. 격상된 권한이나 전체 호스트 권한 (full host authority)은 일상적인 분석이 아닌, 감독 하의 복구 (supervised recovery)를 위해 남겨둔다.

핵심은 에이전트(agent)를 소심하게 만드는 것이 아닙니다. 핵심은 권한(authority)을 작업 내용에 맞게 설정하는 것입니다. 원격 분석(Remote analysis)은 원격 상태로 유지되어야 합니다. 로컬 셸(Local shell) 작업은 명확하고, 검토 가능하며, 정책에 따라 제한되어야 합니다. 웹 검색(Web lookup)은 셸이 브라우저인 것처럼 가장하는 대신 웹 도구(web tools)를 사용해야 합니다.

이것이 바로 OpenClaw 설정을 비즈니스 업무에 충분히 신뢰할 수 있도록 유지하는 방법입니다. 에이전트는 단순히 명령어를 실행하는 방법만 아는 것이 아닙니다. 어떤 명령 인터페이스(command surface)가 해당 작업에 적합한지를 알고 있습니다.

전체 가이드를 원하시나요? Get ClawKit — $9.99

원문 게시 위치: https://www.openclawplaybook.ai/blog/openclaw-code-execution-vs-exec/

OpenClaw Playbook 받기 → https://www.openclawplaybook.ai?utm_source=devto&utm_medium=article&utm_campaign=parasite-seo