OpenRouter Shell Tool 및 Files API 가이드 (베타)

모델이 파일을 읽고, 코드를 실행하고, 오류를 확인한 뒤 결과물을 다시 내놓아야 한다면 OpenRouter의 셸 워크플로가 꽤 유용합니다. 다만 openrouter:shell, 컨테이너, Files API는 모두 베타 단계입니다. 운영 핵심 경로에 바로 넣기보다는 범위가 명확하고 실패해도 영향이 제한적인 작업부터 시작하는 편이 안전합니다.

결론부터 말하면, OpenRouter 셸은 이런 작업에 적합하다

OpenRouter의 openrouter:shell은 도구 호출이 가능한 모델에 호스팅 Linux 환경을 제공합니다. 모델은 명령을 실행하고 stdout, stderr, 종료 코드를 받은 뒤 결과를 수정해 다시 시도할 수 있습니다. 입력 파일과 출력 결과물을 연결하는 역할은 Files API가 맡습니다.

다음과 같은 요구라면 고려할 만합니다.

애플리케이션 서버와 분리된 환경에서 코드를 실행하는, 특정 모델에 종속되지 않는 에이전트
CSV 분석, PDF 추출, 보고서 생성처럼 반복 실행할 수 있는 파일 처리 작업
직접 샌드박스를 구축하지 않고 서버 측에서 도구를 실행하는 구성

반대로 로컬 셸의 완전한 대체재로 생각해서는 안 됩니다. 네트워크는 기본적으로 차단되고, 컨테이너는 자동으로 영속화되지 않으며, 베타 기간에는 API가 바뀔 수 있습니다.

실제 설계에 영향을 주는 구성 요소

구성 요소	역할	설계할 때 중요한 점
`openrouter:shell`	도구 사용이 가능한 모델이 명령을 실행하도록 함	Responses API와 Anthropic Messages API에서 제공됨 (공식 발표)
컨테이너	격리된 Linux 환경에서 명령을 실행함	세션 또는 컨테이너 참조를 재사용하지 않으면 새 컨테이너는 초기 상태로 시작함
Files API	입력 파일과 저장된 출력 결과물을 관리함	직접 업로드한 파일은 첨부할 수 있지만 다운로드할 수 없는 것으로 문서화되어 있음 (업로드 레퍼런스)

openrouter:bash는 Anthropic 호환 방식의 대안입니다. 기본 실행 경로에서는 애플리케이션이 로컬에서 명령을 실행하도록 요청합니다. 원격 실행이 필요하다면 engine: "openrouter"를 설정해야 하며, 자세한 내용은 셸 공식 발표에 나와 있습니다.

파일은 시스템 안에서 이렇게 이동한다

1. 파일을 업로드하고 입력으로 연결하기

POST /api/v1/files에 multipart form data로 파일을 업로드합니다. 업로드 레퍼런스에 따르면 개별 파일의 최대 크기는 100 MB이며, 선택적으로 workspace_id 쿼리 매개변수를 사용할 수 있습니다.

curl -X POST https://openrouter.ai/api/v1/files \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -F "file=@data/sales.csv"

응답에는 파일 ID, 파일명, MIME 유형, 바이트 단위 크기, 생성 시각, downloadable 플래그 등의 메타데이터가 포함됩니다. 반환된 파일 ID는 셸 환경의 file_ids 배열에 넣어 연결합니다.

첨부한 파일은 쓰기가 가능한 복사본으로 컨테이너에 들어갑니다. 셸 공식 발표에 따르면 컨테이너 하나에는 최대 20개 파일을 첨부할 수 있습니다. 컨테이너 안에서 복사본을 수정해도 원래 워크스페이스 파일은 바뀌지 않습니다.

한 개발자는 이전에 PDF와 OCR을 연동하면서 겪었던 불편을 언급한 뒤 Files API 지원을 반겼습니다. 파일 처리가 실제 통합 과정에서 작지 않은 걸림돌이었다는 점을 보여주는 구체적인 사례입니다 (게시물).

2. 실행 결과를 확인하며 반복하기

모델은 컨테이너에 명령 묶음을 보냅니다. 호출할 때마다 실행 결과와 종료 상태가 돌아오기 때문에, 처음 프롬프트만 보고 추측하는 대신 실패한 스크립트를 직접 수정해 다시 실행할 수 있습니다 (셸 공식 발표).

기본 네트워크 정책은 모두 차단하는 방식입니다. 패키지 다운로드나 외부 요청이 필요한 작업이라면 컨테이너를 만들 때 허용 목록을 설정해야 합니다. OpenRouter는 허용 목록에 등록한 호스트에 대해 80번과 443번 포트를 문서화하고 있으며, 컨테이너가 시작된 뒤에는 정책을 변경할 수 없습니다. 허용 목록에 없는 도메인으로 요청하면 HTTP 520 오류가 발생할 수 있습니다 (셸 공식 발표).

셸 결과에 수집되는 파일은 /workspace/home 아래에 있는 것뿐입니다. API가 결과 파일을 인식해야 한다면 반드시 이 경로에 저장하세요. 셸이 새로 만들거나 변경한 파일에는 cfile_ 식별자가 부여됩니다 (셸 공식 발표).

3. 결과물을 다운로드하거나 워크스페이스에 보관하기

셸이 만든 파일은 다음 컨테이너 파일 콘텐츠 엔드포인트로 가져올 수 있습니다.

GET /api/v1/containers/{container_id}/files/{file_id}/content

cfile_ 식별자는 해당 컨테이너에 속합니다. 컨테이너 수명보다 오래 결과물을 보관해야 한다면 워크스페이스 스토리지로 승격하세요. 승격하면 새로운 or_file_ 식별자가 생성되고, 이후 실행에서 다시 첨부할 수 있습니다 (셸 공식 발표).

파일 유형	일반적인 ID	Files API로 다운로드 가능한가?	적합한 용도
직접 업로드한 파일	`or_file_...`	다운로드 레퍼런스에 따르면 불가	이후 실행의 입력
컨테이너 결과물	`cfile_...`	컨테이너 엔드포인트를 통해 가능	임시 출력
승격된 결과물	`or_file_...`	가능	재사용하거나 오래 보관할 출력

컨테이너 파일은 30일 동안 유지됩니다. 그보다 오래 보관해야 하는 파일은 반드시 승격하세요 (셸 공식 발표). 일반 파일 다운로드 엔드포인트는 원시 바이트를 반환하지만, 사용자 업로드 파일에는 HTTP 400을 반환한다고 문서에 나와 있습니다. 따라서 직접 업로드한 파일은 범용 오브젝트 스토리지처럼 쓰기보다 입력 파일로 다루는 것이 맞습니다.

설계를 바꿀 수 있는 비용과 제한

OpenRouter의 셸 공식 발표에 따르면 활성 샌드박스 사용료는 초당 $0.0001입니다. 콜드 컨테이너에는 30초 최소 사용 시간이 적용되므로, 계산상 최소 샌드박스 비용은 $0.003입니다. 토큰 비용은 별도로 부과됩니다.

제한	문서에 명시된 값	설계 시 의미
활성 샌드박스 사용 시간	$0.0001/초	명령 실행 시간이 길수록 비용이 계속 증가함
콜드 컨테이너 최소 시간	30초	아주 짧은 작업도 최소 비용이 발생할 수 있음
컨테이너 절전	유휴 5분	절전 이후 재사용하면 새로운 콜드 최소 시간이 적용될 수 있음
컨테이너당 파일 수	20개	입력을 묶거나 파일을 단계적으로 준비해야 함
개별 업로드 크기	100 MB	더 큰 파일은 분할하거나 사전 처리해야 함
워크스페이스 스토리지	10 GiB	오래된 결과물을 삭제하거나 보관해야 함
승격하지 않은 컨테이너 파일 보존 기간	30일	중요한 결과물은 승격해야 함

연관된 여러 단계를 처리할 때는 웜 컨테이너를 재사용하고, 불필요한 모델-도구 반복 호출은 줄이세요. 토큰 비용과 샌드박스 비용도 별도로 기록하는 것이 좋습니다. 공식 발표에 따르면 Logs 화면에서는 모델 활동과 샌드박스 실행이 서로 다른 타임라인 행으로 표시됩니다.

기본 요청 구조

베타 기간에는 정확한 환경 스키마가 바뀔 수 있지만, 문서에 나온 흐름은 대체로 다음과 같습니다. 먼저 파일을 업로드하고, 반환된 파일 ID를 셸이 활성화된 요청에 전달합니다. 베타 스키마가 바뀌더라도 쉽게 수정할 수 있도록 요청 어댑터는 작게 유지하세요.

{
  "model": "your/tool-capable-model",
  "tools": [
    {
      "type": "openrouter:shell",
      "environment": {
        "type": "container_auto",
        "file_ids": ["or_file_your_uploaded_file_id"]
      }
    }
  ],
  "input": "Analyze the attached CSV and write a summary to /workspace/home/report.md"
}

이 구조를 공식 발표에 안내된 Responses 엔드포인트로 전송합니다. 운영에 적용하기 전에는 최신 서버 도구 문서를 기준으로 현재 요청 스키마와 응답 필드를 다시 확인하세요.

첫 연동은 다음 순서로 진행하면 됩니다.

작은 입력 파일 하나를 업로드하고 반환된 파일 ID를 기록합니다.
openrouter:shell을 tools에 넣고 도구 사용이 가능한 모델로 요청을 만듭니다.
file_ids를 통해 파일을 명시적으로 첨부합니다.
모델이 출력 결과를 /workspace/home 아래에 쓰도록 지시합니다.
작업 성공으로 처리하기 전에 종료 코드와 파일 목록을 확인합니다.
컨테이너 결과물을 다운로드하거나, 재사용해야 한다면 승격합니다.
토큰 사용량과 샌드박스 실행 시간을 별도의 비용 필드로 기록합니다.

여러 요청으로 이어지는 워크플로라면 session_id 또는 명시적인 컨테이너 참조를 전달하세요. 그렇지 않으면 다음 요청이 이전 상태를 전혀 갖지 않은 새 컨테이너에서 실행될 수 있습니다.

먼저 문제가 생기는 지점과 대응 방법

문제	대응 방법
모델이 도구를 호출하지 못함	도구 호출을 지원하는 모델을 선택하세요. 서버 도구를 선언한다고 해서 모델에 해당 기능이 추가되지는 않습니다.
명령이 인터넷에 연결되지 않음	네트워크를 모두 차단한 상태에서 시작하고, 컨테이너가 시작되기 전에 허용 목록을 설정하세요.
출력 파일이 사라짐	`/workspace/home` 아래에 저장하고 반환된 `cfile_` ID를 사용하세요. 오래 보관할 결과물은 승격해야 합니다.
업로드한 파일을 다운로드할 수 없음	직접 업로드한 파일은 입력으로 취급하세요. 셸 출력은 컨테이너 엔드포인트나 승격 절차를 통해 가져와야 합니다.
두 번째 요청에서 프로젝트 상태가 사라짐	세션 또는 컨테이너 참조를 재사용하세요. 기본값은 새 컨테이너입니다.
예상보다 비용이 많이 나옴	토큰 비용과 샌드박스 실행 시간을 분리해 계산하고, 콜드 컨테이너의 30초 최소 시간을 반영하세요.
인터페이스가 변경됨	베타 연동을 어댑터 뒤에 두고 식별자, 다운로드 가능 여부, 재사용 동작을 테스트하세요.

OpenRouter shell 및 Files API FAQ

OpenRouter 셸은 내 컴퓨터에서 명령을 실행하나요?

아닙니다. openrouter:shell은 OpenRouter가 호스팅하는 샌드박스에서 명령을 실행하도록 설계됐습니다. Anthropic 호환 방식인 openrouter:bash는 기본 동작이 다릅니다. 원격 실행에는 engine: "openrouter"를 사용하세요 (셸 공식 발표).

요청 사이에 파일을 유지하려면 어떻게 해야 하나요?

세션 또는 컨테이너 참조를 재사용하세요. 이를 명시적으로 지정하지 않으면 다음 요청이 새 컨테이너에서 시작될 수 있습니다.

`or_file_`과 `cfile_`의 차이는 무엇인가요?

or_file_은 워크스페이스 Files API 객체를 식별합니다. cfile_은 컨테이너 안에서 생성되거나 변경된 파일을 식별합니다. 컨테이너 결과물을 승격하면 새로운 워크스페이스 파일 ID로 변환됩니다.

Files API 사용료가 별도로 부과되나요?

셸 공식 발표에 따르면 Files API 사용 자체에는 별도 사용료가 없지만, 워크스페이스 스토리지는 10 GiB로 제한됩니다. 샌드박스 사용 시간과 모델 토큰 사용량에는 각각 해당 요금이 적용됩니다.

셸 도구를 운영 환경에서 바로 사용할 수 있나요?

현재 베타로 문서화되어 있으며, 공식 발표에서도 API가 변경될 수 있다고 안내합니다. 무인 운영 워크플로에 넣기 전에는 명시적인 제한, 실행 범위가 정해진 명령, 애플리케이션 수준의 제약, 장애 발생 시 대체 경로를 마련해야 합니다.

실제 결과물을 만드는 워크플로라면 선택할 만하다

OpenRouter의 셸과 Files API는 정제된 CSV, 보고서, 변환된 이미지, 컴파일 결과물처럼 명확한 산출물을 만들어내는 단계형 파이프라인에 잘 맞습니다. 명시적인 파일 ID, 사전에 선언한 네트워크 정책, 컨테이너 재사용, 오래 보관할 결과물의 승격을 기본 설계에 포함하세요.

단순히 텍스트 답변만 필요한 작업이라면 샌드박스 비용과 파일 수명 주기 관리가 불필요합니다. 로컬 자격 증명, 제한 없는 네트워크, 확실한 운영 보장이 필요하다면 베타가 해당 위험을 감당할 만큼 성숙해질 때까지는 직접 통제하는 인프라에서 실행하는 편이 낫습니다.

출처: OpenRouter 셸 및 Files API 공식 발표, Files API 업로드 레퍼런스, 파일 콘텐츠 다운로드 레퍼런스.

결론부터 말하면, OpenRouter 셸은 이런 작업에 적합하다

실제 설계에 영향을 주는 구성 요소

파일은 시스템 안에서 이렇게 이동한다

1. 파일을 업로드하고 입력으로 연결하기

2. 실행 결과를 확인하며 반복하기

3. 결과물을 다운로드하거나 워크스페이스에 보관하기

설계를 바꿀 수 있는 비용과 제한

기본 요청 구조

먼저 문제가 생기는 지점과 대응 방법

OpenRouter shell 및 Files API FAQ

OpenRouter 셸은 내 컴퓨터에서 명령을 실행하나요?

요청 사이에 파일을 유지하려면 어떻게 해야 하나요?

`or_file_`과 `cfile_`의 차이는 무엇인가요?

Files API 사용료가 별도로 부과되나요?

셸 도구를 운영 환경에서 바로 사용할 수 있나요?

실제 결과물을 만드는 워크플로라면 선택할 만하다

Claude Opus 5

Claude Fable 5

Claude Fable 5.1

Claude Opus 4.8

Claude Sonnet 5

OpenRouter Shell Tool 및 Files API 가이드 (베타)

결론부터 말하면, OpenRouter 셸은 이런 작업에 적합하다

실제 설계에 영향을 주는 구성 요소

파일은 시스템 안에서 이렇게 이동한다

1. 파일을 업로드하고 입력으로 연결하기

2. 실행 결과를 확인하며 반복하기

3. 결과물을 다운로드하거나 워크스페이스에 보관하기

설계를 바꿀 수 있는 비용과 제한

기본 요청 구조

먼저 문제가 생기는 지점과 대응 방법

OpenRouter shell 및 Files API FAQ

OpenRouter 셸은 내 컴퓨터에서 명령을 실행하나요?

요청 사이에 파일을 유지하려면 어떻게 해야 하나요?

or_file_과 cfile_의 차이는 무엇인가요?

Files API 사용료가 별도로 부과되나요?

셸 도구를 운영 환경에서 바로 사용할 수 있나요?

실제 결과물을 만드는 워크플로라면 선택할 만하다

`or_file_`과 `cfile_`의 차이는 무엇인가요?