Android AI 파일 관리자 에이전트 플러그인: 설치, 권한, 미리 보기와 안전한 파일 작업

AI 파일 에이전트가 구조화할 수 있는 작업

Android AI 파일 관리자 에이전트 플러그인은 자연어 요청을 정확한 경로와 파일 작업으로 바꾸는 데 가치가 있습니다. “다운로드한 문서를 정리해 줘”라는 요청은 바로 실행할 명령이 아닙니다. 어느 폴더를 볼지, 어떤 파일을 찾을지, 텍스트를 읽을지, 새 폴더를 만들지, 이름을 바꿀지, 삭제할지를 단계별로 정해야 합니다. 각 단계의 입력 경로와 예상 결과가 보여야 사용자가 작업 범위를 확인할 수 있습니다.

File Manager Plugin 0.0.4는 외부 저장소에서 파일과 폴더 목록을 가져오고 조건에 맞는 항목을 검색할 수 있습니다. 텍스트 파일은 maxBytes로 읽을 최대 크기를 제한해 내용을 가져옵니다. 파일을 새로 만들거나 텍스트를 쓰고, 폴더를 생성하며, 단일 파일이나 폴더의 이름을 바꾸는 작업도 제공합니다. 여러 항목의 이름을 바꿀 때는 미리 보기와 실제 적용을 분리합니다.

다운로드 폴더에서 회의 문서를 찾는 사례를 생각해 보겠습니다. 사용자가 “이번 주 받은 회의록 텍스트 파일만 찾아 첫 부분을 읽어 줘”라고 요청하면 에이전트는 먼저 지정한 상대 경로에서 파일을 검색합니다. 검색 결과에서 이름, 위치, 파일 유형을 보여 준 뒤 선택된 텍스트만 제한된 크기로 읽습니다. 이 단계에서는 파일을 이동하거나 수정하지 않으므로 사용자가 내용을 확인한 다음 정리 방식을 결정할 수 있습니다.

새 파일 생성과 기존 파일 쓰기도 구분됩니다. 새 파일 생성은 같은 경로에 이미 있는 파일을 덮어쓰지 않는 계약을 사용합니다. 기존 파일에 내용을 쓰는 작업은 대상 경로와 작성할 텍스트를 별도로 확인해야 합니다. 이름이 같은 파일이 발견되면 다른 이름을 선택하거나 기존 파일 작업으로 전환해야 합니다. 에이전트가 “저장했습니다”라고 답하는 것보다 실제 생성된 경로와 파일을 다시 목록에서 확인하는 것이 중요합니다.

삭제와 HTTPS 다운로드는 조회나 텍스트 읽기보다 결과가 큽니다. 현재 플러그인의 삭제는 영구 삭제이며, 다운로드는 HTTPS 주소에서 파일을 받아 외부 저장소 아래의 상대 경로에 기록합니다. 따라서 파일 에이전트의 역할은 명령을 빠르게 호출하는 데서 끝나지 않습니다. 정확한 대상, 경로, 충돌 가능성, 필요한 승인과 작업 후 관찰된 결과를 하나의 흐름으로 연결해야 합니다.

별도 APK로 설치되는 File Manager Plugin

File Manager는 FoneClaw의 기본 제공 도구가 아니라 별도 APK로 설치하는 플러그인입니다. 공식 플러그인 색인은 현재 File Manager Plugin 0.0.4, 버전 코드 4와 패키지 식별자 ai.android.claw.plugin.device.filemanager를 선언합니다. 최소 호스트 기준은 공식 메타데이터가 요구하는 FoneClaw 호스트 기준입니다. 설치된 APK가 이 메타데이터와 일치해야 호스트가 플러그인을 인식하고 도구를 등록할 수 있습니다.

별도 패키지라는 점은 권한과 업데이트 책임도 분명하게 만듭니다. File Manager Plugin은 MANAGE_EXTERNAL_STORAGE와 INTERNET 권한을 요청합니다. 사용자는 플러그인을 설치할 때 패키지 이름과 버전, 예상 서명자, 공식 메타데이터의 파일 식별값과 요청 권한을 확인할 수 있습니다. 설치 후에는 FoneClaw가 플러그인 APK에서 등록한 도구와 현재 활성 상태를 확인합니다.

FoneClaw 공식 플러그인 색인은 현재 설치 제안에 사용할 패키지 메타데이터의 기준입니다. 0.0.4 색인은 상태와 설정, 목록·검색·읽기, 생성·쓰기, 폴더 생성, 이름 변경, 일괄 이름 변경, 삭제와 다운로드를 위한 13개 도구를 선언합니다. 상태 확인은 낮은 영향의 자동 처리 대상으로 분류되며, 다른 파일 작업에는 승인이 적용됩니다. 일괄 변경 적용과 삭제는 파괴적 작업으로 구분됩니다.

플러그인 검색과 설치 요청도 서로 다른 단계입니다. plugin_search는 공식 메타데이터에서 조건에 맞는 플러그인을 찾으며 APK를 설치하지 않습니다. 사용자가 File Manager를 선택하면 plugin_request_install이 화면에 표시할 설치 제안을 만듭니다. 이 요청 자체가 다운로드나 설치를 끝내는 것은 아니며, Home 화면에서 사용자가 패키지와 권한을 확인한 뒤 설치를 결정합니다.

이 구조는 기본 도구와 확장 기능을 쉽게 구별하게 합니다. FoneClaw의 관리되는 기본 도구는 호스트와 함께 제공되고, File Manager의 파일 기능은 설치된 플러그인 APK가 제공합니다. 다른 플러그인의 설치와 로컬 작업 흐름을 비교하려면 FoneClaw 무료 YouTube 다운로더 플러그인: 로컬 Android 다운로드 흐름에서 제안, 설치와 도구 등록 과정을 이어서 볼 수 있습니다.

모든 파일 접근 권한과 상대 경로의 범위

MANAGE_EXTERNAL_STORAGE는 Android 외부 저장소의 넓은 파일 범위를 다루기 위한 특수 접근 권한입니다. 일반적인 미디어 선택 권한보다 범위가 크기 때문에 사용자는 Android 설정에서 File Manager Plugin에 이 접근을 허용할지 직접 결정해야 합니다. 권한이 없으면 외부 저장소 전체를 대상으로 하는 목록, 검색과 변경 작업이 제한될 수 있으며, 권한을 부여한 뒤에도 Android와 대상 앱이 보호하는 모든 영역이 자동으로 열리는 것은 아닙니다.

파일 작업은 외부 저장소의 기준 위치와 그 아래 상대 경로로 표현됩니다. 예를 들어 Download/AgentTest는 외부 저장소 기준 위치 아래의 테스트 폴더를 뜻합니다. 사용자가 “다운로드 폴더를 정리해 줘”라고 요청했다면 에이전트는 먼저 실제 상대 경로와 포함된 항목을 보여 줘야 합니다. 비슷한 이름의 Downloads나 앱별 폴더를 임의로 선택해서는 안 됩니다.

모든 파일 접근 권한과 개별 작업 승인은 역할이 다릅니다. Android 권한은 플러그인이 저장소 기능을 사용할 수 있게 합니다. 작업 승인은 지금 이 파일을 읽거나 바꾸고 삭제해도 되는지를 결정합니다. 사용자가 한 번 특수 접근을 허용했더라도 에이전트가 검색 결과 전체를 수정하거나 영구 삭제할 권한을 포괄적으로 받은 것은 아닙니다. 각 작업은 대상 경로와 영향에 맞는 확인을 거쳐야 합니다.

텍스트 읽기에는 경로뿐 아니라 읽을 크기도 포함됩니다. maxBytes 제한은 큰 로그나 문서 전체를 무조건 가져오는 대신 필요한 범위만 읽도록 합니다. 사용자는 파일 이름과 크기, 읽을 최대 용량을 보고 작업을 승인할 수 있습니다. 문서의 첫 부분만 필요한데 전체 파일을 모델 입력으로 보내는 일을 줄이면 처리 시간과 민감 정보 노출 범위를 함께 관리할 수 있습니다.

권한을 점검할 때는 설치된 플러그인과 요청한 특수 접근을 함께 확인하세요. File Manager를 더 이상 사용하지 않는다면 도구 비활성화, 플러그인 제거와 모든 파일 접근 해제를 순서대로 검토할 수 있습니다. Android 특수 접근과 숨겨진 앱까지 확인하는 방법은 AI Android 휴대전화 상태 점검: 앱 권한, 특수 접근, 숨겨진 앱 감사 가이드에서 자세히 설명합니다.

previewToken으로 일괄 이름 변경을 검토하는 방법

여러 파일의 이름을 한 번에 바꾸는 작업은 제안과 적용을 분리해야 합니다. “사진 이름을 날짜 순으로 정리해 줘”라는 요청만으로는 날짜 출처, 이름 형식, 정렬 기준과 같은 이름 충돌을 판단하기 어렵습니다. File Manager Plugin은 일괄 이름 변경을 먼저 미리 보고, 확인된 변경안을 실제로 적용하는 두 단계 계약을 사용합니다.

첫 단계에서 에이전트는 대상 폴더와 이름 변경 규칙을 전달해 미리 보기를 요청합니다. 결과에는 기존 경로와 바뀔 이름의 대응 관계가 나타나며 previewToken이 함께 반환됩니다. 사용자는 파일이 빠졌는지, 확장자가 유지되는지, 같은 이름이 생기는지, 작업 범위가 지정한 폴더 안에 머무르는지를 확인합니다. 아직 실제 파일 이름은 바뀌지 않은 상태입니다.

예를 들어 Download/TripPhotos의 이미지에 seoul-001, seoul-002 형식의 이름을 붙이려 한다고 해보겠습니다. 미리 보기에는 각 원본 이름과 새 이름이 나란히 표시돼야 합니다. 이미지가 아닌 문서가 포함됐거나 이미 seoul-001.jpg가 존재한다면 적용 전에 규칙이나 선택 범위를 고칠 수 있습니다. 사용자가 수정한 규칙은 새로운 미리 보기와 새 토큰을 만들어야 합니다.

실제 적용 도구는 확인된 previewToken을 요구하며 파괴적 작업으로 처리됩니다. 토큰은 사용자가 본 제안과 적용할 변경을 연결합니다. 대상 폴더의 내용이 바뀌었거나 미리 보기 뒤 시간이 오래 지났다면 현재 파일 목록을 다시 확인하고 새 미리 보기를 만드는 편이 적절합니다. 이전 토큰을 다른 폴더나 다른 규칙의 포괄적인 승인처럼 사용해서는 안 됩니다.

적용 뒤에는 결과를 관찰해야 합니다. 대상 폴더를 다시 조회해 새 이름이 실제로 존재하는지, 원본 수와 결과 수가 맞는지, 충돌 때문에 남은 파일이 있는지 확인합니다. 일부 항목만 변경됐다면 성공한 파일과 실패한 파일을 나눠 보여 줍니다. 플러그인이나 Skill의 검사를 통과한 사실보다 실행 시점의 권한과 대상을 확인하는 기준은 AI 에이전트 스킬 보안: 검사 통과보다 실행 중 권한 확인이 중요한 이유에서 더 깊게 살펴볼 수 있습니다.

영구 삭제와 HTTPS 다운로드의 확인 기준

현재 File Manager Plugin의 삭제 기능은 초기 버전에서 영구 삭제로 작동합니다. 휴지통으로 이동하거나 플러그인 내부에서 실행 취소하는 단계가 없으므로 승인 전에 정확한 경로와 파일 유형, 파일 수를 보여 줘야 합니다. 폴더 삭제라면 그 안의 항목까지 영향을 받는지 확인해야 하며, “오래된 파일 삭제”처럼 범위가 넓은 요청은 먼저 후보 목록으로 바꿔야 합니다.

삭제를 시험할 때는 복사본으로 만든 테스트 파일을 사용하세요. 예를 들어 Download/AgentTest/delete-me.txt를 생성하고 내용을 확인한 뒤 해당 파일 하나만 삭제 대상으로 지정합니다. 승인 화면에서는 영구 삭제라는 결과와 복구 기능이 제공되지 않는다는 점이 보여야 합니다. 실행 후에는 같은 경로를 다시 조회해 파일이 실제로 사라졌는지 확인합니다.

중요한 파일에는 삭제보다 다른 경로로 이동하거나 백업을 만드는 준비 작업이 더 적합할 수 있습니다. 다만 이동이나 백업이 완료됐다는 응답만 믿고 원본을 지우면 안 됩니다. 새 위치에서 파일이 존재하고 필요한 경우 내용을 읽을 수 있는지 확인한 뒤 별도의 삭제 승인을 받아야 합니다. 현재 삭제 계약 자체에는 휴지통과 되돌리기가 없으므로 복구 계획은 실행 전에 마련해야 합니다.

다운로드 도구는 HTTPS 주소를 받아 외부 저장소 아래의 상대 경로에 파일을 기록합니다. INTERNET 권한은 네트워크에서 데이터를 가져오는 데 사용되고, 저장소 권한은 결과 파일을 대상 경로에 쓰는 데 사용됩니다. 사용자는 원본 주소의 도메인, 예상 파일 이름, 저장 폴더와 기존 파일 충돌 여부를 확인해야 합니다. HTTP 주소나 기기 내부의 임의 절대 경로를 다운로드 대상으로 다루는 방식이 아닙니다.

같은 이름의 파일이 이미 있을 때는 작업 전에 충돌 상태를 보여 주고 새 이름을 선택하거나 기존 파일을 유지할 수 있어야 합니다. 다운로드가 중간에 끊겼다면 파일이 완전한지 확인하지 않고 성공으로 표시해서는 안 됩니다. 완료 후에는 최종 상대 경로와 파일 크기, 가능하면 기대한 형식이나 해시를 검증합니다. 쓰기와 다운로드 결과를 관찰하는 단계가 있어야 네트워크 응답과 실제 저장 성공을 구분할 수 있습니다.

공식 검색부터 첫 안전 작업까지 설치 순서

File Manager Plugin 설치는 검색, 제안, 검증, 사용자 설치, 권한 설정, 도구 등록과 첫 시험 순으로 진행됩니다. 각 단계가 화면에 보이면 사용자는 검색 결과를 곧바로 설치된 기능으로 오해하지 않고 패키지 출처와 요청 권한을 확인할 수 있습니다. FoneClaw는 공식 메타데이터를 기준으로 플러그인을 찾고 설치 제안을 준비합니다.

1. 공식 검색: FoneClaw의 plugin_search로 File Manager를 찾습니다. 검색은 공식 메타데이터를 조회하며 APK를 설치하지 않습니다.
2. 설치 제안: plugin_request_install로 보이는 설치 제안을 만듭니다. Home 화면에서 플러그인 이름, 패키지, 버전, 최소 호스트와 권한을 확인합니다.
3. 패키지 검증: 현재 색인의 0.0.4, 버전 코드 4, ai.android.claw.plugin.device.filemanager, 예상 파일 식별값과 서명자를 설치 APK와 비교합니다.
4. 사용자 설치: 제안에 동의한 뒤 Android 설치 화면에서 패키지를 설치합니다. 검색이나 제안 도구만으로 설치가 자동 완료되지는 않습니다.
5. 권한 설정: 파일 작업이 필요할 때 모든 파일 접근을 검토하고 허용합니다. 네트워크 다운로드에는 인터넷 연결이 필요합니다.
6. 도구 등록: FoneClaw가 설치된 플러그인의 메타데이터를 확인하고 제공 도구를 등록했는지 상태 화면에서 확인합니다.
7. 첫 시험: 테스트 폴더의 목록을 가져오고 작은 텍스트 파일 하나를 제한된 크기로 읽습니다. 결과 경로와 내용을 확인한 뒤 생성이나 이름 변경으로 확장합니다.

첫 시험에서는 기존 사진, 문서와 다운로드 파일을 변경하지 않는 편이 좋습니다. Download/AgentTest 같은 새 폴더를 만들고 작은 텍스트 파일을 생성한 뒤 목록과 읽기 결과를 확인합니다. 다음으로 텍스트 쓰기와 단일 이름 변경을 시험합니다. 일괄 변경은 여러 테스트 파일을 준비하고 미리 보기와 previewToken 적용이 분리되는지 확인한 뒤 진행합니다.

설치 과정에서 버전 정보가 서로 다르게 보이면 공식 기계 판독 색인의 현재 패키지 항목을 기준으로 확인합니다. 현재 권위 항목은 0.0.4이며, 설명 문서에 남은 0.0.3 표기는 설치 APK의 최신 버전을 결정하는 값으로 사용하지 않습니다. FoneClaw 공식 GitHub 저장소에서는 호스트 구조와 공개 플러그인 문서를 함께 확인할 수 있습니다.

플러그인을 설치한 뒤에도 각 파일 작업은 FoneClaw의 관리 정책 안에서 진행됩니다. 상태 확인을 제외한 파일 도구에는 승인이 적용되고, 일괄 이름 변경 적용과 삭제는 파괴적 행동으로 구분됩니다. 사용자는 플러그인 설치 승인과 개별 파일 작업 승인을 별도로 결정합니다. 패키지를 신뢰한다는 판단이 외부 저장소의 모든 파일 변경에 대한 사전 동의가 되는 구조는 아닙니다.

파일 플러그인 신뢰와 복구 점검표

Android AI 파일 관리자 에이전트 플러그인은 설치 여부보다 작업 전후에 무엇을 보여 주는지로 평가해야 합니다. 별도 테스트 폴더를 만들고 목록, 검색, 제한된 텍스트 읽기, 생성, 쓰기, 단일 이름 변경, 일괄 미리 보기, 다운로드와 삭제를 차례로 시험하세요. 각 단계에서 입력 경로와 승인 내용, 관찰된 결과를 기록하면 모델 판단 문제와 플러그인 실행 문제를 분리할 수 있습니다.

• 출처 신뢰: 검색 결과가 공식 색인에서 왔는지, 설치 제안에 패키지 식별자와 0.0.4 버전, 최소 호스트 정보가 표시되는지 확인합니다.
• 패키지 검증: APK의 메타데이터, 기대한 서명자와 공식 색인의 파일 식별값이 일치하는지 봅니다.
• 권한 최소화: 모든 파일 접근과 인터넷 권한이 어떤 기능에 필요한지 확인하고 사용하지 않을 때 해제할 수 있는지 살펴봅니다.
• 경로 범위: 외부 저장소 기준의 상대 경로가 화면에 표시되고 요청한 폴더 밖의 파일이 후보에 포함되지 않는지 확인합니다.
• 읽기 제한: 텍스트 읽기에 maxBytes가 적용되고 필요한 부분보다 큰 데이터가 모델 입력으로 전달되지 않는지 봅니다.
• 생성 충돌: 새 파일 생성이 기존 파일을 덮어쓰지 않고 같은 이름이 있을 때 명확한 실패나 새 이름 선택을 제공하는지 확인합니다.
• 일괄 미리 보기: 모든 원본 이름과 새 이름, 충돌 가능성을 확인한 뒤 해당 previewToken으로만 적용되는지 살펴봅니다.
• 파괴적 승인: 영구 삭제와 일괄 변경 적용이 일반 조회와 구분되고 정확한 대상과 결과를 보여 주는지 확인합니다.
• 다운로드 검증: HTTPS 출처, 저장 상대 경로, 이름 충돌과 완료 후 실제 파일 크기 또는 식별값을 확인합니다.
• 관찰된 결과: 쓰기, 이름 변경, 삭제와 다운로드 뒤 대상 폴더를 다시 조회해 실제 상태를 검증합니다.
• 작업 기록: 사용한 플러그인 버전과 도구, 대상 경로, 승인한 사용자, 실행 시각, 성공·실패 결과가 연결되는지 봅니다.
• 복구 준비: 영구 삭제 전에 별도 백업이나 복사본을 만들고 복구 가능 여부를 실제로 확인합니다.
• 제거: 플러그인을 쓰지 않을 때 도구를 비활성화하고 APK를 제거한 뒤 모든 파일 접근 권한도 해제합니다.

감사 기록은 자연어 요청만 남기는 방식보다 구체적이어야 합니다. “파일을 정리해 달라고 요청함”만으로는 어떤 경로와 파일이 바뀌었는지 알 수 없습니다. 패키지 식별자, 플러그인 버전, 호출한 도구, 입력 경로, 미리 보기 토큰, 승인과 실제 결과를 연결하면 문제가 생겼을 때 작업 범위를 재구성할 수 있습니다. 도구별 승인과 기록 설계는 AI 에이전트 신원과 권한: 도구별 승인 제어와 감사 로그 설계에서 더 자세히 다룹니다.

실패한 작업은 성공한 항목과 미완료 항목을 분리해 보여 줘야 합니다. 일괄 이름 변경 중 일부가 충돌했다면 전체가 완료된 것처럼 표시하지 않고 다시 미리 볼 대상을 남깁니다. 다운로드 연결이 끊겼다면 부분 파일을 확인하고 새 이름으로 재시도할지 결정합니다. 삭제 결과가 불확실하다면 같은 명령을 반복하기 전에 원래 경로를 다시 조회합니다.

최종적으로 좋은 파일 에이전트는 넓은 권한을 가진 제품이 아니라 정확한 파일 범위를 이해하게 하는 제품입니다. FoneClaw에서는 설치 제안, 패키지 검증, Android 권한, 작업별 승인과 실제 결과 확인을 각각 보이는 단계로 유지합니다. 사용자가 경로와 변경안을 확인하고 파괴적 작업을 명시적으로 결정하며, 완료 후 실제 저장소 상태를 검증할 수 있을 때 File Manager Plugin은 반복적인 Android 파일 관리를 신뢰할 수 있는 작업으로 바꿉니다.