OpenClaw 파일 전송 플러그인 가이드 2026: file_fetch·dir_fetch·Mac mini M4 크로스노드 보안 워크플로우 완전 정복

2026년 5월 초에 출시된 OpenClaw v2026.5.3에는 AI Agent가 페어링된 노드 간에 바이너리 파일 작업을 직접 실행할 수 있는 새로운 파일 전송 플러그인이 번들로 포함되었습니다. 수동 SCP 명령이나 공유 네트워크 드라이브가 더 이상 필요 없습니다. 이 플러그인은 4개의 Agent 도구를 도입합니다: file_fetch, dir_list, dir_fetch, file_write. 모두 노드별 경로 정책과 심볼릭 링크 순회 보호를 갖추고 있습니다. 이 가이드는 초기 설정부터 4가지 프로덕션 워크플로우 패턴, 일반적인 오류 트러블슈팅까지 상세히 다룹니다.

OpenClaw 파일 전송 플러그인이란?

v2026.5.3 이전에는 페어링된 OpenClaw 노드 간에 파일을 이동하려면 Agent 세션 외부에서 수동 SSH 명령을 실행하거나, 각 팀이 자체적인 커스텀 MCP 서버 통합을 구축하고 유지해야 했습니다. 파일 전송 플러그인은 OpenClaw Agent에 페어링 노드와의 파일 읽기/쓰기를 위한 네이티브 도구를 제공하여 이 문제를 해결합니다. 권한 모델과 감사 로그는 다른 OpenClaw 도구 호출과 완전히 일치합니다.

이 플러그인은 v2026.5.3부터 메인 패키지에 번들로 포함되어 있어 별도의 npm 설치가 필요 없습니다. 단, 설정에서 명시적으로 활성화해야 합니다. 이를 통해 팀은 어떤 Agent가 어떤 노드에서 파일시스템 쓰기 접근 권한을 갖는지 제어할 수 있습니다.

아키텍처 작동 방식

파일 전송 플러그인은 OpenClaw의 게이트웨이 레이어를 통해 동작합니다. Agent가 file_fetch를 호출하면, 게이트웨이가 요청을 대상 노드의 플러그인 수신기로 라우팅하고, 수신기가 노드의 설정된 경로 정책에 대해 요청 경로를 검증한 후, 파일을 읽어 바이너리 콘텐츠를 게이트웨이를 통해 Agent 컨텍스트로 스트리밍합니다.

이 아키텍처의 3가지 실제적 영향:

• 파일 전송 작업은 OpenClaw의 OTEL 텔레메트리에 요청 경로, 전송 바이트, 레이턴시, 성공/실패 여부를 포함하여 다른 도구 호출과 동일한 수준으로 기록됩니다.
• 경로 정책은 클라이언트 측이 아닌 게이트웨이 레이어에서 적용되므로, 프롬프트 인젝션이나 Agent 환각에 의한 우회가 불가능합니다.
• 바이너리 파일(컴파일된 아티팩트, IPA 패키지, 모델 가중치, 이미지)도 그대로 전송됩니다. 텍스트 파일에만 국한되지 않습니다.

설치 및 설정

파일 전송 플러그인은 OpenClaw v2026.5.3 이상이 필요합니다. 이전 버전을 사용 중이라면 먼저 업데이트하세요:

npx openclaw@latest update

또는 활성 Agent 세션 내에서:

/update

업데이트 후 플러그인이 사용 가능한지 확인하세요:

openclaw plugin list | grep file-transfer

file-transfer bundled v1.0.0이 표시되어야 합니다. 아무것도 반환되지 않으면 업데이트가 완료되지 않은 것입니다. openclaw --version으로 2026.5.3 이상인지 확인하세요.

openclaw.config.js에서 활성화

플러그인은 번들되어 있지만 기본적으로 비활성화되어 있습니다. 설정 파일에 추가하세요:

// openclaw.config.js module.exports = { plugins: ['file-transfer'], pluginConfig: { 'file-transfer': { nodes: { 'hk-node-1': { allowedPaths: ['/Users/runner/builds', '/tmp/openclaw-transfer'], readOnly: false, maxFileSizeBytes: 500 * 1024 * 1024 // 500 MB }, 'sg-node-1': { allowedPaths: ['/Users/runner/artifacts'], readOnly: true // 읽기 전용, 쓰기 불가 } } } } };

allowedPaths 배열은 해당 노드에서 플러그인이 접근할 수 있는 디렉토리 루트 경로를 정의합니다. 화이트리스트 외부의 경로는 권한 오류를 반환하고 작업은 실행되지 않습니다. readOnly: true는 file_fetch, dir_list, dir_fetch를 허용하면서 해당 노드로의 file_write를 방지합니다.

설정을 변경했다면 OpenClaw를 재시작하여 반영하세요:

openclaw restart

플러그인이 활성 상태인지 확인:

/plugin status file-transfer

file_fetch: 페어링 노드에서 파일 가져오기

file_fetch는 페어링 노드의 지정 경로에서 단일 파일을 가져와 그 내용을 Agent가 사용할 수 있도록 합니다. 텍스트 파일의 경우 디코딩하여 Agent 컨텍스트에 배치합니다. 바이너리 파일의 경우 Agent가 원시 바이트를 수신하고 이후 file_write로 다른 위치에 쓸 수 있습니다.

기본 사용법

Agent 프롬프트에서 자연어로 파일 가져오기를 지시하기만 하면 됩니다:

hk-node-1의 /Users/runner/builds/myapp/build.log에서 빌드 로그를 가져와 마지막 100줄을 요약해 주세요.

Agent는 이것을 노드, 경로, 인코딩을 지정한 file_fetch 도구 호출로 변환합니다. 컴파일된 IPA 패키지 같은 바이너리 파일의 경우, Agent는 sg-node-1의 file_fetch와 hk-node-1의 file_write를 연결하여 바이너리 전송을 투명하게 처리합니다.

파일 크기 제한과 스트리밍

10MB 미만 파일은 전송 중 메모리에 버퍼링됩니다. 10MB에서 maxFileSizeBytes까지의 파일은 스트리밍됩니다. maxFileSizeBytes를 초과하는 파일은 크기 제한 오류로 거부됩니다. 100MB를 초과하는 IPA나 대형 모델 가중치에는 maxFileSizeBytes를 적절히 설정하세요.

dir_list와 dir_fetch: 원격 디렉토리 탐색 및 미러링

dir_list는 페어링 노드의 디렉토리 내용을 반환합니다——파일명, 크기, 수정 타임스탬프, 파일 타입(파일/디렉토리/심볼릭 링크). 설계상 심볼릭 링크는 추적하지 않습니다(심볼릭 링크 순회는 설정에 관계없이 항상 차단됩니다).

dir_fetch는 전체 디렉토리 트리를 재귀적으로 가져와 파일 내용을 포함한 구조화된 매니페스트로 반환합니다. 노드 간 빌드 출력 디렉토리를 미러링하는 용도에 가장 강력한 도구입니다.

dir_list: 원격 빌드 출력 확인

예: 아티팩트를 가져오기 전에 CI 노드에서 빌드가 완료되었는지 Agent가 확인하는 경우:

hk-node-1의 /Users/runner/builds/output/ 디렉토리 내용을 수정 시간 순으로 나열하고 지난 10분 이내에 생성된 파일을 알려주세요.

Agent는 정렬 및 필터링 파라미터와 함께 dir_list를 호출합니다. 이를 통해 "아티팩트가 존재하면 가져오고, 없으면 대기 후 재시도"와 같은 조건부 판단이 가능해지며, 개발자가 명시적인 폴링 로직을 작성할 필요가 없어집니다.

dir_fetch: 빌드 아티팩트 미러링

빌드 출력 디렉토리 전체를 CI 노드에서 아카이브 노드로 동기화하는 경우:

sg-node-1의 /Users/runner/builds/v2.3.1/ 디렉토리를 hk-node-1의 /Users/archive/releases/v2.3.1/에 미러링해 주세요. 같은 크기의 파일이 대상에 이미 존재하면 건너뛰세요.

Agent는 sg-node-1의 dir_fetch와 hk-node-1로의 일련의 file_write를 연결하여 크기 비교로 변경되지 않은 파일을 건너뜁니다.

file_write: 원격 노드에 보안 파일 쓰기

file_write는 페어링 노드의 지정 경로에 콘텐츠를 씁니다. 텍스트와 바이너리 콘텐츠 모두 지원하며, 원자적 쓰기 시맨틱을 갖추고 있습니다——대상 노드의 임시 경로에 쓴 후 최종 목적지로 원자적으로 이동하므로 전송 중단 시 부분 쓰기 상태를 방지합니다.

설정 파일 배포

일반적인 사용 사례: 여러 노드에 설정 파일을 동시에 배포하기(각 노드에 별도 SSH 로그인 없이):

다음 nginx.conf 내용을 hk-node-1, jp-node-1, kr-node-1의 /etc/nginx/nginx.conf에 동시에 써 주세요: [내용]

OpenClaw의 멀티 도구 호출이 3개의 file_write 작업을 병렬로 디스패치하여 3번의 SSH 세션 대신 1번의 쓰기 시간에 배포가 완료됩니다.

경로 정책과 보안: 심볼릭 링크 순회 방지

파일 전송 플러그인의 가장 중요한 보안 기능은 무조건적인 심볼릭 링크 순회 보호입니다. 경로 정책 설정에 관계없이 플러그인은 파일 경로를 해석할 때 심볼릭 링크를 추적하지 않습니다. /allowed/path/../../etc/passwd에 접근하려는 Agent나 프롬프트가 받는 것은 파일 내용이 아닌 경로 해석 오류입니다.

보안 기능	동작	설정 가능?
심볼릭 링크 순회 차단	경로 내 모든 심볼릭 링크가 해석 시 거부됨	아니오——항상 적용
경로 화이트리스트 적용	allowedPaths 외부 경로는 권한 오류 반환	예——allowedPaths로 설정
읽기 전용 노드 적용	file_write가 차단되고 가져오기 작업은 허용됨	예——readOnly 플래그로 설정
파일 크기 제한	maxFileSizeBytes를 초과하는 파일은 전송 전 거부	예——기본값 500MB
작업 감사 로그	모든 파일 작업이 OTEL 텔레메트리에 기록	아니오——항상 기록
원자적 쓰기	임시 파일 + 원자적 이름 변경 사용, 중단 시 부분 쓰기 없음	아니오——항상 원자적

모범 사례: 최소 경로 화이트리스트

각 노드의 역할에 따라 allowedPaths를 최대한 좁게 정의하세요. CI 빌드 노드는 빌드 출력 디렉토리에만 접근하면 되고, 홈 디렉토리 전체에 접근할 필요는 없습니다. 아카이브 노드는 아티팩트 저장소에 읽기/쓰기 접근이 필요할 수 있지만, 그 외는 모두 읽기 전용으로 설정해야 합니다.

4가지 실제 워크플로우 (Mac mini M4 실제 사례)

워크플로우 1: 크로스노드 빌드 아티팩트 동기화

시나리오: 홍콩 노드에서 iOS 빌드를 실행(빌드가 빠름)하지만 QA 팀은 싱가포르 노드에 가깝습니다. 각 빌드 후 서명된 IPA를 SG 노드에 자동으로 복사하여 QA에 배포하고 싶습니다.

Agent 프롬프트:

hk-node-1에서 Xcode 아카이브가 완료되면 /Users/runner/builds/output/의 최신 .ipa 파일을 확인하고, 가져와서 sg-node-1의 /Users/qa-distribution/latest/에 써 주세요. 파일명과 크기를 보고해 주세요.

Agent는 빌드를 실행하고, dir_list로 최신 IPA를 검색하고, file_fetch로 가져오고, file_write로 SG 노드에 푸시하고, 파일명과 바이트 수를 보고합니다——수동 SCP 없이 일관된 워크플로우입니다.

워크플로우 2: 멀티노드 로그 집계

시나리오: 홍콩, 일본, 한국, 싱가포르, 미국 동부의 5개 노드에서 테스트 스위트를 병렬로 실행합니다. 각 노드에 수동으로 SSH하지 않고 모든 테스트 결과 JSON 파일을 단일 분석 컨텍스트에 집계하고 싶습니다.

Agent는 5개의 병렬 file_fetch 호출을 발행하고, 5개의 JSON 페이로드를 수신하고, 집계하여 각 노드의 합격/불합격 수와 가장 느린 테스트를 보여주는 테이블을 생성합니다. 수동으로는 10~15분 걸리는 작업이 자동화를 통해 약 90초에 완료됩니다.

워크플로우 3: 롤링 설정 배포

시나리오: OpenClaw Agent 시스템 프롬프트를 업데이트하고, 각 노드가 새 설정을 받아들이는지 확인한 후 다음 노드로 진행하는 방식으로 롤아웃하고 싶습니다. 쓰기→검증→계속 순의 순차적 조건 로직은 Agent가 네이티브로 처리하며 외부 오케스트레이션 스크립트가 필요 없습니다.

워크플로우 4: ML 모델 가중치 배포

시나리오: 개발 노드에서 로컬 LLM을 파인튜닝하고 OpenClaw + Ollama를 실행하는 3개의 추론 노드에 모델 가중치를 배포하고 싶습니다. 플러그인의 스트리밍 모드는 대형 바이너리 파일을 효율적으로 처리합니다. Agent가 보고하는 전송 속도는 노드 간 네트워크 혼잡 여부를 파악하는 데 유용합니다.

트러블슈팅: 일반적인 오류

오류 메시지	가장 가능한 원인	해결 방법
Plugin 'file-transfer' not found	OpenClaw 버전이 2026.5.3 미만	npx openclaw@latest update를 실행하고 버전 확인
Path not within allowed paths	요청 경로가 설정의 allowedPaths 외부	해당 노드의 allowedPaths에 경로 루트 추가
Write not permitted on read-only node	노드에 readOnly: true가 설정되어 Agent가 file_write를 호출	쓰기 접근이 필요하면 readOnly: false로 변경
File exceeds maxFileSizeBytes limit	파일 크기가 설정 제한(기본 500MB)을 초과	플러그인 설정에서 maxFileSizeBytes를 늘리거나 파일 분할
Symlink traversal detected	경로에 심볼릭 링크가 포함되거나 심볼릭 링크를 통해 해석됨	실제(심볼릭 링크가 아닌) 경로 사용; 심볼릭 링크 추적은 항상 불가
Node 'xxx' not configured in file-transfer plugin	노드 ID가 플러그인의 nodes 설정 객체에 없음	플러그인 설정의 nodes 섹션에 노드 추가
대형 파일(> 1GB) 전송이 멈춤	스트리밍 완료 전 게이트웨이 타임아웃	openclaw.config.js에서 gateway.streamTimeoutMs 증가(기본 300000ms)

Mac mini M4 노드가 파일 전송 워크플로우를 실용적으로 만드는 이유

OpenClaw 파일 전송 플러그인의 가치는 VpsGona의 Mac mini M4 노드에서 실행할 때 배가됩니다. 실제적인 이유: M4의 로컬 스토리지는 고속 NVMe SSD이며, 노드 간에는 고대역폭 업링크가 있습니다. 로컬 NVMe에서 읽고 원격 NVMe에 쓰는 것은 회전 디스크나 네트워크 연결 스토리지와 달리 크로스노드 파일 전송의 병목이 거의 항상 디스크 I/O가 아닌 네트워크 대역폭임을 의미합니다.

노드별 경로 정책 모델은 VpsGona의 멀티노드 아키텍처에도 적합합니다: HK 빌드 노드, SG 아카이브 노드, US East QA 배포 노드는 각각 파이프라인에서 다른 역할을 가지며, 각 역할과 관련된 디렉토리에만 접근할 수 있어야 합니다.

이미 OpenClaw를 멀티 Agent 오케스트레이션이나 데이터 파이프라인 자동화에 사용하는 팀에게 파일 전송 플러그인은 완전한 Agent 구동 Mac mini M4 워크플로우의 마지막 공백을 채웁니다: Agent 세션을 떠나지 않고 노드 간 바이너리 아티팩트를 이동할 수 있습니다. 현재 노드 가용성과 요금은 VpsGona 요금 페이지에서 확인하고, 초기 노드 설정은 헬프 문서를 참조하세요.