플러그인 권한
다섯 가지 권한, 권한이 없을 때 플러그인이 보는 것, 그리고 WebAssembly 플러그인이 프로그램과 전혀 다른 이유.
플러그인이 할 수 있는 일은 agentty-plugin.json에 미리 선언하고 설치 전에 이용자에게 보여 줍니다. 권한 없이 호출하면 -32001 오류로 실패합니다.
다섯 가지 권한#
| 권한 | 이용자에게 표시되는 문구 | 메서드 |
|---|---|---|
net.request | 지정한 주소로 HTTP 요청을 보냅니다 | net/fetch |
prompt.inject | 에이전트 세션 시작·프롬프트 전송 | prompt/inject |
terminal.write | 터미널에 입력하고 Enter까지 | terminal/send |
session.read | Agentty에 열린 AI 세션의 대화를 읽습니다 | session/get |
workspace.read | 열린 워크스페이스·탭·폴더와 에이전트 상태를 봅니다 | workspace/list, host/revealPath, pane/status |
mcp.tools | Agentty의 AI 에이전트에 제공하는 도구로 응답합니다 (MCP) | tools/call |
terminal.proxy | 새 터미널을 플러그인의 프록시로 연결합니다 (API 버전 6 필요) | terminal/setProxy |
플러그인 자신의 저장소와 패널에는 권한이 필요 없습니다. storage/get·storage/set·storage/keys는 플러그인 자기 폴더(<데이터 폴더>/plugin-data/<id>/storage.json, 0600으로 생성)를 쓰며 키 64개, 총 1MB까지입니다. WebAssembly 플러그인에는 자기 파일이 없어서 무언가를 기억하려면 이것을 써야 합니다.
net.request를 session.read나 workspace.read와 함께 가진 플러그인은 여러분의 작업을 읽어 어딘가로 보낼 수 있습니다. 둘 다 요청하는 플러그인은 설명에 그 이유를 분명히 적어야 합니다. 적지 않은 플러그인은 마켓플레이스가 거부합니다.
두 종류의 플러그인#
가장 중요한 구분이고, 플러그인 페이지의 정보 → 실행 방식에 표시됩니다.
wasm | Agentty가 모듈을 직접 실행합니다. 파일도, 소켓도, 환경 변수도, 프로세스도 없습니다. 어떻게 작성했든 프로토콜이 허용한 것만 건드립니다. |
node, python, executable | 이용자 권한으로 실행되는 프로그램입니다. 이용자가 실행하는 다른 프로그램과 같은 파일·네트워크 접근 권한을 가집니다. 위 권한은 프로토콜로 하는 동작만 막을 뿐 프로그램 자체는 전혀 막지 못합니다. |
그래서 권한 목록의 의미가 둘 사이에서 달라집니다. WebAssembly 플러그인에서는 그 플러그인이 할 수 있는 일의 전부입니다. 프로그램에서는 Agentty를 통해 할 수 있는 일의 전부일 뿐입니다. 파일은 원래부터 직접 열 수 있었으니까요.
프로그램 플러그인은 제작자를 신뢰할 때만 설치하세요. 마켓플레이스가 소스가 공개된 WebAssembly 모듈만 다루는 것도 이 때문입니다.
권한이 없을 때 플러그인이 보는 것#
컨텍스트는 선언한 권한에 따라 걸러집니다. workspace.read가 없으면 폴더와 제목 필드가 제거되고, session.read가 없으면 세션 id가 제거됩니다. 남는 것은 id, kind, tool, status, running, 언어입니다. 어느 페인이 포커스됐고 작업 중인지는 알 수 있지만, 어디서 무엇을 하는지는 알 수 없습니다.
{
"pane": { "id": 12, "kind": "claude", "tool": "claude", "status": "working", "running": true },
"language": "ko"
}프롬프트가 어디로 가고, 누가 골랐는가#
다이얼로그는 경계가 아닙니다. 이 점은 분명히 해 둘 필요가 있습니다. prompt.inject가 있으면 플러그인은 묻지 않고 자기 에이전트 세션을 열어 텍스트를 보낼 수 있습니다. 일부러 그렇게 만들었습니다. AgentOS는 자기가 시작한 세션으로 단계를 진행하는 것이 일의 전부인데, 다이얼로그를 거쳐서는 그 일을 할 수 없습니다.
플러그인이 선택을 이용자에게 넘길 수도 있습니다. target: "ask"로 호출하면 **보낼 곳…**이 열립니다. 이용자가 텍스트를 보고 에이전트와 목적지를 고르며 보내기를 누르기 전에는 아무 일도 일어나지 않습니다. 그 외의 target — newTab, newWorkspace, active, pane, workspace — 은 모두 이 다이얼로그를 건너뜁니다. 그러니 외부에서 온 것을 받아 동작하는 플러그인은 항상 ask를 써야 합니다. 링크로 실행된 플러그인은 제약을 받습니다. newTab 및 newWorkspace에 Claude Code 또는 Codex (또는 에이전트를 주지 않으면 Claude Code)라면 바로 열리되 Enter는 누르지 않습니다. 다른 경우는 모두 **보낼 곳…**을 거치고 역시 Enter는 누르지 않습니다.
두 호출은 Enter에서 갈리고, 그 차이가 terminal.write의 전부입니다.
injectPrompt는 터미널에서 Enter를 대신 누르지 않습니다. 텍스트를 입력해 두고 이용자에게 맡깁니다.sendToTerminal은 다른 물건이고, Enter를 누릅니다. 셸이라면 그 명령이 실행됩니다.
링크는 신뢰하지 않습니다#
agentty:// 링크는 웹페이지를 포함해 어디서든 올 수 있습니다. 링크가 한 번이라도 닿은 플러그인은 실행되는 내내 이렇게 동작합니다.
prompt/inject의 target이newTab또는newWorkspace이고 Claude Code 또는 Codex (또는 에이전트 없음, Claude Code로 기본 설정)라면 새 에이전트 탭이나 워크스페이스가 바로 열립니다. 텍스트는 프롬프트에 입력되지만 Enter는 누르지 않습니다. 이렇게 바로 열리는 탭은 몇 초에 하나뿐입니다. 링크를 연달아 여는 페이지도 탭 하나만 얻고 나머지는 **보낼 곳…**에서 차례를 기다립니다. 다른 모든 경우 — 이미 열린 터미널(active,pane,workspace),split,own, 셸/터미널 에이전트, target 없음 — 는 **보낼 곳…**을 거쳐 Enter를 누르지 않습니다.terminal/send는 텍스트를 Enter를 누르지 않고 입력합니다 (submit은 false로 강제됩니다). Claude Code나 Codex 터미널에만 입력하고 셸에는 입력하지 않습니다. 셸 명령줄에 남은 글은 이용자가 다음에 치는 명령과 함께 실행될 수 있기 때문입니다. 입력만으로는 아무것도 실행되지 않습니다. 텍스트는 제어 문자를 뺀 채 붙여넣어지고 줄바꿈은 bracketed paste로 감싸이거나 공백으로 바뀝니다. 입력할 수 있는 곳도 전과 같습니다(이용자가 방금 그 플러그인을 쓴 직후, 또는 플러그인이 연 터미널).- Enter를 이용자에게 맡긴 경우 양쪽 호출 모두
submitted: false로 응답합니다.
브라우저는 계속 거부됩니다 (-32001). 링크가 닿은 플러그인이 Agentty 밖에서 할 수 있는 일은 host/openUrl 하나뿐이고, 그것도 한 번에 주소 하나입니다. 링크가 연 패널에서 클릭했다고 해서 플러그인이 입력한 것을 실행해도 된다고 동의한 것은 아닙니다. 기다린 것도 마찬가지입니다. 푸는 것은 플러그인 재시작뿐입니다.
Agentty는 좋은 주소와 나쁜 주소를 가려내지 못하므로 그 부분은 작성자의 몫입니다. 링크가 건넨 것은 낯선 사람이 준 텍스트로 여기고 거기서 받은 주소를 확인 없이 열지 마세요.
링크를 처리하는 플러그인이라면 모든 파라미터를 검증하세요. Cosmica 플러그인은 Cosmica 노트 폴더 안의 .md 파일만 열고, 폴더 밖 경로는 거부합니다.
net.request로 할 수 있는 일#
net/fetch는 플러그인이 네트워크에 닿는 유일한 방법이고, Agentty가 범위를 제한합니다.
| 메서드 | http·https에서 GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS |
| 헤더 | 최대 32개. Host, Content-Length, Transfer-Encoding, Connection, Upgrade, Expect는 불가, 줄바꿈이 든 것도 불가 |
| 요청 본문 | 1MB |
| 응답 | 4MB까지 보관 (truncated가 더 왔는지 알려 줍니다) |
| 타임아웃 | 기본 15초, 최대 60초 |
| 동시 요청 | 플러그인당 4개 |
요청에는 여러분의 것이 아무것도 실리지 않습니다. 쿠키도, 저장된 자격 증명도 없고 플러그인이 직접 넣은 것만 갑니다. 호출마다 URL을 가린 채 플러그인 로그에 기록됩니다.
리다이렉트는 3번까지 따라가고 그 주소도 처음 요청과 똑같이 검사합니다. http나 https여야 하고, 링크로컬이나 메타데이터 주소가 아니어야 합니다. 그러지 않으면 서버가 302 Location: http://169.254.169.254/…로 응답해 검사를 우회할 수 있습니다. Authorization이나 Cookie 헤더는 다른 호스트로 넘어가지 않고, 리다이렉트된 POST·PUT·PATCH는 응답이 307이나 308이 아닌 한 본문 없는 GET이 됩니다.
레이트 리밋과 폭주 방지#
Agentty는 실수든 아니든 잘못 동작하는 플러그인으로부터 자신을 보호합니다.
| 제한 | 동작 |
|---|---|
| 패널 다시 그리기 | 최소 50ms 간격 |
| 알림 | 최소 700ms 간격. 초과분은 정상 응답 후 폐기. 메시지는 300자에서 잘립니다 |
| URL 열기 | 최소 700ms 간격. host/openUrl도 알림과 같은 방식으로 제한됩니다 |
| 메시지 | 초당 240건을 넘으면 폭주로 간주해 플러그인 중단 |
| UI 트리 | 요소 2,000개, 깊이 12단계, 문자열당 20,000자. choice의 옵션과 리스트 항목의 버튼도 각각 요소로 셉니다 |
| 줄 길이 | stdout·stderr 각 16MB |
| WebAssembly | 모듈 64MB, 메모리 64MB, 메시지당 16MB, 하나를 처리하는 동안 메시지 256개 — send와 log를 합쳐서 |
AI 에이전트의 도구 (MCP)#
플러그인은 Agentty에서 실행되는 AI 에이전트(Claude Code, Codex)에 도구를 제공할 수 있습니다. Agentty에 들어 있는 MCP 서버(agentty-plugins MCP 서버)를 거칩니다. 권한이 있고 contributes.tools에 도구를 나열한 플러그인이 하나 이상 켜져 있으면 에이전트에 이 서버가 자동으로 붙습니다.
플러그인은 권한과 도구를 함께 선언해야 합니다. 권한만 있고 도구가 없거나, 도구만 있고 권한이 없으면 매니페스트 오류입니다. mcp.tools 권한은 API 버전 5를 요구합니다.
mcp.tools를 선언하지 않은 플러그인은 MCP를 지원하지 않으므로 에이전트에게 보이지 않습니다. 그 플러그인의 페이지는 "MCP 연결 — 지원하지 않음"이라고 표시합니다.
mcp.tools를 선언한 플러그인의 권한 탭에는 "MCP 연결 허용" 스위치가 있으며, 기본값은 ON입니다. 이용자가 OFF로 끄면 에이전트는 더 이상 그 플러그인의 도구를 나열하거나 호출할 수 없습니다.
플러그인당 최대 32개의 도구를 제공할 수 있습니다. 도구 name은 1–48자이며 소문자, 숫자, 밑줄을 쓸 수 있고 문자로 시작해야 합니다. 각 호출은 120초 후 시간 초과됩니다. 인수와 에이전트에 전달되는 텍스트에는 크기 제한이 있으니 프로토콜 상세를 보세요.
플러그인의 응답은 에이전트의 컨텍스트에 들어가므로 다른 도구 출력처럼 다루세요. 각 호출은 로그(로그 탭)에 기록되며 호출한 페인이 표시됩니다.
터미널 프록시#
플러그인은 이용자가 여는 터미널과 AI 세션이 자기가 이 컴퓨터(127.0.0.1)에서 실행하는 프록시를 거치게 해 달라고 요청할 수 있습니다. 그러면 플러그인은 그 터미널이 어떤 호스트에 닿는지, 얼마나 보내는지 볼 수 있습니다. 이용자에게는 새 터미널을 자체 프록시로 연결로 표시됩니다. 이미 열린 터미널은 바뀌지 않고 플러그인을 멈추면 프록시도 끝납니다. 주소는 Agentty가 포트 번호로 만들기 때문에 플러그인이 터미널을 다른 곳으로 보낼 수 없습니다. 프록시는 한 번에 한 플러그인만 쓸 수 있습니다.
요청한 권한에 값하는 플러그인 만들기#
- 쓰는 권한만 요청하세요. 모든 권한이 이용자에게 표시되며, 쓰지 않는 권한은 신뢰만 깎아먹습니다.
- 자격 증명을 읽거나 보내지 마세요. 다른 앱의 설정을 읽는다면 필요한 필드만 가져오세요. Cosmica 플러그인은
notes.path와 포트만 읽습니다. - 데이터는 플러그인 자신의 저장소에 두세요. 다른 앱이 읽는 파일은 조심해서 만들고, 이용자의 파일을 요청 없이 덮어쓰지 마세요.
127.0.0.1하고만 통신하세요. 이용자가 직접 다른 곳을 설정한 경우가 아니라면요.- 입력 전에
pane.status를 확인하세요.working,permission,question상태는 방해하면 안 됩니다. - 외부에서 온 것은 무엇이든 검증하세요. 링크든 파일이든 서버 응답이든 그대로 믿고 동작하지 마세요.
남의 플러그인을 설치하기 전에#
- 카드의 권한을 읽으세요. 노트 플러그인이
terminal.write를 요구한다면 그 이유가 설명돼 있어야 합니다. - 실행 방식을 확인하세요. WebAssembly 모듈은 프로그램보다 훨씬 작은 신뢰만 요구합니다.
- 소스를 읽을 수 있는 플러그인을 선호하세요. 카드의 링크가 대개 저장소를 가리킵니다.
- 설치 후 로그를 보면 플러그인이 실제로 무엇을 하는지 확인할 수 있습니다.
- 비활성화는 즉시 적용되고, 삭제는 플러그인을 제거합니다. 데이터 폴더는 직접 지울 때까지 남습니다.