능력을 다 켜 두면 에이전트가 위험해진다 — OpenClaw가 Skills 메뉴로 능력을 골라 켜는 방법

오픈소스 개인 AI 어시스턴트 OpenClaw를 집 서버에 올려 쓰면서 설정 화면을 들여다봤다. 그중 "Skills(스킬)" 메뉴가 눈에 들어왔다. 스킬은 1Password·Trello 같은 외부 도구를 감싼 능력 묶음이다 — 에이전트에게 "이런 일을 이렇게 할 수 있다"고 가르치는 설명서에 가깝다. 그런데 이런 능력을 무한정 켜 두면 어떻게 될까? 이 글은 "필요한 스킬만 골라 켜고, 각 스킬이 요구하는 바이너리·API 키를 점검·관리하는 화면"이 왜 필요했는지, OpenClaw가 그걸 어떤 구조로 풀었는지를 따라간다.

배경 — 스킬은 에이전트에게 "능력을 가르치는 설명서"다

OpenClaw에서 스킬(skill)은 마크다운으로 쓴 지시문 파일이다. 각 스킬은 SKILL.md 파일 하나를 담은 폴더로 존재하고, 그 안에는 YAML 프론트매터(파일 맨 위의 메타데이터 블록)와 본문이 들어간다. 본문은 "사용자가 이미지를 만들어 달라고 하면 image_generate 도구를 써라" 같은 식으로, 에이전트가 언제·어떻게 도구를 쓸지를 알려 준다. 스킬은 외부 CLI/도구(예: 1Password CLI, Trello)를 감싼 능력 묶음인 셈이다.

다이어그램 설명. 이 그림은 사용자의 요청 한 줄이 스킬을 거쳐 실제 외부 도구 실행으로 이어지는 경로를 보여준다. 사용자가 "비밀번호를 꺼내 달라"고 하면 에이전트가 어떤 능력을 써야 할지 판단하고, 그에 맞는 스킬 지시문을 참고한다. 핵심은 스킬이 단독으로 동작하지 않는다는 점이다 — 그 아래로 요구 바이너리(여기서는 1Password 명령줄 도구 op)와 요구 환경변수(인증 토큰)가 갖춰져야 비로소 외부 도구를 실행할 수 있다. 흔한 오해가 "스킬을 설치하면 바로 쓸 수 있다"는 가정인데, OpenClaw에서 스킬은 설명서일 뿐이고 실행에 필요한 도구·키는 별개로 충족돼야 한다. 그래서 단순히 "스킬이 있다/없다"가 아니라 "쓸 수 있다/없다"를 판단하는 화면이 필요해진다.

핵심 문제 — 능력을 다 켜 두면 토큰 낭비와 보안 위험이 동시에 커진다

가장 단순한 발상은 "설치된 스킬을 전부 켜 두고 에이전트가 알아서 쓰게 하자"다. 능력이 많을수록 좋아 보인다. 하지만 이 단순 모델에서 실제로 터지는 문제가 셋 있다.

다이어그램 설명. 이 그림은 "전부 켜기" 방식이 갈라지는 세 가지 실패를 보여준다. 첫째, OpenClaw는 활성화된 스킬마다 이름·설명·경로를 압축한 블록을 시스템 프롬프트(매 요청 앞에 붙는 지시문)에 끼워 넣는데, 그 비용이 정해져 있다 — 문서 공식에 따르면 기본 195자에 스킬당 약 97자 + 이름·설명·경로 길이만큼 늘고, 대략 4글자가 1토큰이니 스킬 하나가 필드 길이 전에 이미 약 24토큰을 차지한다 — 이 24토큰은 XML 골격만 친 하한이고, 여기에 실제 이름·설명·경로 길이가 더해지므로 설명이 긴 스킬은 한 개가 100토큰을 훌쩍 넘기도 한다(그래서 문서도 "설명을 짧게 유지하라"고 권한다). 안 쓸 스킬까지 켜 두면 매 요청 이 비용을 그냥 태운다. 둘째, 커뮤니티에서 받은 제3자 스킬은 신뢰할 수 없는 외부 코드로 다뤄야 한다 — 읽지도 않고 켜면 의도치 않은 동작이 일어날 수 있다. 셋째, 요구 바이너리나 API 키가 없는데도 스킬이 켜져 있으면, 에이전트는 쓸 수 없는 도구를 호출하려다 실패한다. 놓치기 쉬운 함정은 세 문제가 같은 뿌리라는 점이다 — "능력은 많을수록 좋다"는 직관이 토큰·보안·신뢰성 셋을 동시에 갉아먹는다. 그래서 필요한 스킬만 골라 켜고 요구사항을 점검하는 통제 화면이 가치를 갖는다.

해결 방법 — 레지스트리 + 요구사항 게이트 + 비밀 주입

OpenClaw는 이 문제를 세 축으로 나눠 푼다. (1) 스킬을 여러 위치에서 우선순위대로 불러오는 레지스트리, (2) 켤 자격이 되는지 거르는 요구사항 게이트, (3) 켜진 스킬에만 비밀(API 키·환경변수)을 그 순간에만 넣어 주는 비밀 주입. Skills 메뉴는 이 세 가지의 상태를 한 화면에서 보여주고 조작하는 창이다. 하나씩 본다.

레지스트리 — 같은 이름이면 높은 위치가 이긴다

스킬은 한 곳이 아니라 여러 위치에 흩어져 산다 — 작업공간 폴더, 에이전트별 폴더, 머신 공용 폴더, 설치본에 딸려 온 기본 스킬(bundled skill) 등이다. OpenClaw는 이들을 우선순위가 정해진 순서로 불러오고, 같은 이름의 스킬이 여러 위치에 있으면 가장 높은 위치의 것만 채택한다.

다이어그램 설명. 이 그림은 스킬을 불러오는 여섯 위치의 우선순위를 위에서 아래로 보여준다. 여기서 <작업공간>은 "workspace"라는 고정 폴더가 아니라 에이전트가 도는 작업 디렉토리를 가리키는 자리표시자다 — 에이전트마다 자기 작업공간이 따로 있어 그 값이 달라진다(반면 3·4순위의 ~/.agents·~/.openclaw는 홈 기준 고정 경로다). 맨 위가 작업공간 스킬이고 맨 아래가 추가 폴더·플러그인 스킬인데, 같은 이름의 스킬이 두 곳에 있으면 더 위쪽 위치의 것이 아래쪽을 덮어쓴다. 이렇게 층을 둔 이유는 명확하다 — 설치본에 동봉된 기본 스킬을 직접 고치지 않고도, 같은 이름의 스킬을 작업공간에 두는 것만으로 안전하게 재정의(override)할 수 있기 때문이다. 마치 시스템 기본 설정 위에 사용자 설정을 얹는 방식과 같은 발상이다. 놓치기 쉬운 점은 폴더 경로가 이름을 만들지 않는다는 것이다 — 스킬의 이름과 슬래시 명령은 프론트매터의 name 필드(없으면 폴더명)에서 오고, 중간 폴더 구조는 정리용일 뿐이다. 그래서 같은 이름을 두 위치에 두면 의도치 않게 한쪽이 가려질 수 있다.

요구사항 게이트 — "쓸 수 있는 스킬"만 통과시킨다

레지스트리로 불러온 스킬이 모두 켜지는 건 아니다. OpenClaw는 불러오는 시점에 각 스킬의 metadata.openclaw(프론트매터 안의 한 줄 JSON 메타데이터)에 적힌 요구사항을 검사해 거른다. 이게 요구사항 게이트(gate, 통과 조건을 거는 관문)다. 요구사항이 하나도 없는 스킬은 명시적으로 끄지 않는 한 항상 통과한다.

다이어그램 설명. 이 그림은 스킬 하나가 활성화되기까지 거치는 판단의 연쇄를 보여준다. 위에서부터 읽으면 된다 — 먼저 "무조건 포함" 플래그가 켜져 있으면 나머지 검사를 모두 건너뛰고 바로 통과한다. 그게 아니면 운영체제 필터, 요구 바이너리(예: 1Password 스킬의 op 명령이 PATH에 있는가), 요구 환경변수·설정값(예: API 키가 채워져 있는가)을 차례로 검사하고, 하나라도 어긋나면 그 자리에서 제외한다. 이 패턴의 핵심은 "능력이 있다"와 "능력을 쓸 준비가 됐다"를 분리한다는 점이다 — 준비가 안되어 있는 스킬은 애초에 에이전트의 시야에서 빠지므로, 에이전트가 못 쓸 도구를 헛되이 시도하는 사고(앞서 본 세 번째 문제)가 원천 차단된다. Skills 메뉴의 on/off 토글과 "설치" 버튼은 바로 이 게이트의 두 입력 — 활성화 여부와 요구 바이너리 충족 — 을 사용자가 직접 손보는 손잡이다.

비밀 주입 — 켜진 스킬에만, 그 순간에만

스킬이 외부 도구를 쓰려면 API 키나 토큰이 필요할 때가 많다. OpenClaw는 이 비밀을 ~/.openclaw/openclaw.json의 skills.entries 항목에 적어 두고, 에이전트가 한 번 응답하는 동안에만 프로세스 환경변수에 넣었다가 끝나면 되돌린다. Skills 메뉴의 "API 키 관리"가 바로 이 항목을 다루는 화면이다.

# ~/.openclaw/openclaw.json 의 skills.entries — 스킬별 켜기/끄기 + 키
{
  "skills": {
    "entries": {
      "image-lab": {
        "enabled": true,                       # 이 스킬을 켤지 (false면 번들·설치돼 있어도 끔)
        "apiKey": { "source": "env", "id": "GEMINI_API_KEY" },  # primaryEnv에 연결되는 키
        "env": { "GEMINI_API_KEY": "키값" }     # 이미 환경에 없을 때만 주입
      },
      "sag": { "enabled": false }              # 끈 스킬 — 게이트 통과해도 제외
    }
  }
}

코드 설명. 이 발췌는 사용자가 Skills 메뉴에서 토글·키를 손보면 실제로 어떤 설정이 바뀌는지를 보여준다. 각 스킬 항목에는 enabled(켜기/끄기), apiKey(요구 환경변수에 연결할 키), env(주입할 환경변수)가 들어간다. 핵심 설계는 두 가지다. 첫째, enabled: false는 번들·설치된 스킬이라도 강제로 끄므로, 사용자가 "능력은 있지만 지금은 안 쓴다"를 명시할 수 있다. 둘째, env는 이미 환경에 그 변수가 없을 때만 주입한다 — 운영체제 레벨에서 설정한 값을 덮어쓰지 않는다는 안전 규칙이다. 놓치기 쉬운 함정은 비밀의 주입 범위다 — 이 키들은 호스트 프로세스에, 그것도 해당 응답 한 턴 동안만 들어간다. 격리된 컨테이너 안으로는 들어가지 않으므로, 샌드박스에서 도는 에이전트에 키를 넘기려면 별도 통로가 필요하다. 그래서 비밀을 프롬프트나 로그에 직접 적지 않는 게 권장된다.

설치와 업데이트 — ClawHub 레지스트리에서

새 스킬은 ClawHub(공개 스킬 레지스트리)에서 설치한다. Skills 메뉴의 "설치·업데이트"가 이 명령들을 감싼 버튼이다. 그리고 설치 직전에 보안 검증을 거친다 — 받은 코드가 신뢰할 수 있는지부터 확인한다.

다이어그램 설명. 이 그림은 새 스킬이 설치되기까지의 관문을 위에서 아래로 보여준다. 먼저 레지스트리에서 스킬을 고를 때 VirusTotal·정적 분석 같은 보안 스캔 결과가 미리 노출되고, 설치를 누르면 ClawHub가 그 스킬의 신뢰 봉투(trust envelope — 출처·버전·서명을 묶어 진위를 보증하는 검증 데이터)를 확인한다. 검증이 실패하면 명령이 비정상 종료되어 설치가 막힌다. 통과해도 운영자가 별도 설치 정책을 걸어 뒀다면 그 정책이 한 번 더 거른다 — 그리고 이 정책은 결정을 못 내리면 닫는 쪽(fail closed, 실패 시 권한을 열지 않고 차단)으로 동작한다. 이렇게 겹겹이 거른 뒤에야 작업공간 폴더에 설치되고, 그래도 마지막 단계는 사람이다 — 문서는 제3자 스킬을 "신뢰할 수 없는 외부 코드"로 보고 켜기 전에 읽으라고 못 박는다. 이 다단계 게이트의 가치는 앞서 본 두 번째 문제(읽지 않은 외부 코드의 위험)를 설치 단계에서부터 줄인다는 데 있다. 업데이트는 ClawHub로 설치한 스킬만 자동 추적되고, Git이나 로컬 폴더에서 가져온 스킬은 다시 설치해야 갱신된다는 점은 놓치기 쉽다.

결과 — 무엇이 좋아졌나

레지스트리·요구사항 게이트·비밀 주입을 한 화면으로 모은 Skills 메뉴 덕분에, 앞서 본 세 문제가 이렇게 정리된다.

이전 (능력 전부 켜기)	이후 (Skills 메뉴로 골라 켜기)
안 쓸 스킬도 매 요청 토큰 비용 발생	필요한 스킬만 on → 시스템 프롬프트에서 빠져 비용 절감
읽지 않은 외부 코드를 그냥 켜는 위험	설치 시 신뢰 봉투·보안 스캔·운영자 정책 다단계 검증
요구 바이너리·키 없는 스킬을 헛되이 호출	게이트가 미충족 스킬을 시야에서 제외 → 헛호출 차단
비밀 키가 어디까지 노출되는지 불명확	호스트 프로세스에, 응답 한 턴 동안만 주입 후 복원

정리하면, OpenClaw의 Skills 메뉴는 "에이전트가 가질 수 있는 능력"과 "지금 실제로 쓸 능력"을 사람이 갈라 통제하는 손잡이다. 능력을 무한정 켜 두는 대신, 필요한 스킬만 켜고 각 스킬의 요구사항(바이너리·키)을 한눈에 점검하니 토큰·보안·신뢰성이 동시에 정리된다. 화려한 도구 개수보다 이렇게 "능력을 의도적으로 좁히는 통제면"이 사실 자율 에이전트의 안전을 떠받치는 토대다 — 켤 수 있는 모든 능력을 다 켠 에이전트는 강력해 보이지만, 실은 통제되지 않은 에이전트에 더 가깝기 때문이다.

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.