거버넌스가 곧 아키텍처인 AI 동료: OpenWorker(andrewyng/openworker)의 위험 등급 5종·권한 모드·하드 플로어·리뷰어 서킷 브레이커 심층 해부 — 0.3.4 권한 엔진과 Harness SDK beta.4 박스 실측

한 줄 요약: andrewyng/openworker는 “데스크톱 AI 동료 앱”과 “에이전트 하네스 SDK”를 한 저장소에 담은 프로젝트인데, 코드를 열어 보면 진짜 핵심은 UI도 모델 연결도 아닌 권한 엔진입니다. 모든 도구 호출이 risk.classify() → PermissionEngine.evaluate()를 거치고, 어떤 모드에서도 낮출 수 없는 “하드 플로어”, 사람만 풀 수 있는 승인, 연속 거부 5회에서 멈추는 리뷰어 서킷 브레이커가 엔진 루프 안에 박혀 있습니다. 이 글은 그 설계를 소스 기준으로 해부하고, 박스에서 직접 설치해 권한 엔진·로컬 서버·TypeScript SDK를 실측한 결과를 그대로 정리합니다.

OpenWorker 구조: 모든 도구 호출이 PermissionEngine.evaluate()를 통과한다 (PIL로 직접 그린 다이어그램)
OpenWorker 구조: 모든 도구 호출이 PermissionEngine.evaluate()를 통과한다 (PIL로 직접 그린 다이어그램)

1. 지금 무엇이 공개돼 있나 — 버전·라이선스·숫자부터

숫자는 2026-11-16 17:00 KST 전후 GitHub API·npm·PyPI 조회 기준입니다. 버전이 여러 갈래라 헷갈리기 쉬우니 먼저 정리합니다.

항목 값 비고
저장소 andrewyng/openworker 2026-07-20 생성, aisuite 저장소에서 분리돼 나온 프로젝트
라이선스 MIT 루트 LICENSE, pyproject, npm 패키지 모두 MIT
스타 / 포크 약 19,362 / 2,760 열린 이슈+PR 411개. 이번 주 GitHub Trending Python 목록 진입
최신 GitHub 릴리스(앱) v0.3.1 2026-10-06 06:12 KST 게시. 이후 태그 없는 main 진행
main의 Python 패키지 버전 0.3.4 pyproject.toml 기준 (헤드리스 런타임 + CLI)
PyPI openworker 0.0.1 “Placeholder” — 이름만 선점. pip install openworker로는 아직 실체를 못 받음
Harness SDK (npm) @openworkerai/harness-sdk 0.1.0-beta.4 2026-11-13 05:28 KST 게시, Node ≥20, 플랫폼별 런타임 바이너리를 optionalDependencies로 끌어옴
App-building skill skills-v0.1.0-beta.2 2026-11-07 KST 릴리스, Claude Code/Codex용 빌더 스킬
최근 커밋 2026-11-14 09:34 KST 데스크톱·SDK 문서 PR 병합(#896, #898)

실무적으로 중요한 함의: 데스크톱 앱은 “오픈 베타 + 자동 업데이트”, SDK는 “API 변동 중이니 PR은 잠시 보류”라고 README가 스스로 밝히고 있습니다. 즉 제품으로 쓰기엔 베타, 설계 레퍼런스로 읽기엔 이미 충분히 두꺼운 상태입니다. 저장소 전체 파일은 2,600개 가까이, 백엔드 테스트 파일만 280여 개입니다.

2. 저장소 구조 — 한 저장소, 두 개의 엔진

가장 먼저 짚어야 할 설계 결정은 “엔진이 둘”이라는 점입니다. 데스크톱 앱은 Python 에이전트 엔진(coworker/)을 쓰고, 개발자용 Harness SDK는 별도의 Rust 엔진(harness/)을 씁니다. README도 이 둘이 분리돼 있다고 명시합니다.

디렉터리 내용 읽을 포인트
coworker/ Python 백엔드: 에이전트 엔진, 모델 프로바이더, 커넥터, MCP 클라이언트, 메모리, 자동화 risk.py(147줄) → permissions.py(1,846줄) → engine.py(4,369줄) 순서로 읽으면 거버넌스 흐름이 보임
harness/ Rust 워크스페이스(runtime, guardrails, telemetry, observability, store-postgres, git-broker 등) + TS SDK + 예제 워크스페이스 버전 0.1.0-beta.2, npm SDK는 beta.4
surfaces/gui/ React UI + Tauri 셸(서버 프로세스를 감독) 브라우저 개발 모드(Vite)와 tauri dev 둘 다 지원
stt/ 음성 입력용 Rust STT 사이드카 앱 기능이지 핵심 경로는 아님
packaging/ macOS DMG, Windows 빌드, 자동 업데이트 매니페스트, 개발 부트스트랩 Windows 빌드는 아직 코드 서명 전(SmartScreen 경고)
docs/ 설계 스펙과 결정 로그, OpenShell·macOS·Windows 샌드박스 문서 approval-guidance.md, openshell.md가 실무에 유용
skills/ openworker-harness-builder (코딩 에이전트용 SDK 빌더 스킬) npx @openworkerai/openworker-harness-builder --agent claude --project .
tests/ 백엔드 테스트 스위트(권한 게이트 코퍼스, 리뷰어, 승인 무결성 등) 권한 관련 테스트가 설계 의도의 가장 좋은 문서
데스크톱 앱의 Python 엔진과 Harness SDK의 Rust 엔진 — 한 저장소, 두 개의 엔진 (PIL 다이어그램)
데스크톱 앱의 Python 엔진과 Harness SDK의 Rust 엔진 — 한 저장소, 두 개의 엔진 (PIL 다이어그램)
비교 축 Desktop App 엔진 (Python) Harness SDK 엔진 (Rust)
대상 최종 사용자(리서치·문서·코드 리뷰·보안 점검) 자기 앱에 에이전트를 넣으려는 개발자
구동 방식 로컬 FastAPI 사이드카 + Tauri 셸이 감독 TS: 자식 프로세스로 관리 / Rust: 인프로세스 임베드
모델 계층 aisuite 기반, OpenAI·Anthropic·Gemini·OpenRouter·Bedrock·Ollama·LM Studio·llama.cpp·vLLM setModelProvider()로 앱이 직접 주입(예: Responses API 호환 엔드포인트)
UI 책임 저장소가 제공(React) 앱이 소유. SDK는 루프·도구 호출·승인·스트리밍·내구성 세션만
성숙도 오픈 베타, 자동 업데이트 0.1.0-beta, API 변동 중

트레이드오프는 명확합니다. 두 엔진을 두면 데스크톱 앱이 빠르게 기능을 실험하는 동안 SDK는 Rust로 안정된 계약을 다질 수 있지만, 같은 거버넌스 규칙을 두 언어로 유지해야 하는 비용이 생깁니다. 저장소에 harness/tests/python-contract.py, permission-reviewer-cases.json 같은 계약 테스트가 있는 이유가 여기 있습니다.

3. 핵심 설계 ①: 위험 등급(RiskClass)은 “이름”이 아니라 “선언된 속성”

coworker/risk.py는 예전에 권한 엔진 안에 하드코딩돼 있던 WRITE_TOOLS/SHELL_TOOL 이름 집합을 데이터로 끌어낸 모듈입니다. 모든 도구 호출의 “실효 위험도”를 다섯 등급 중 하나로 정합니다.

RiskClass 의미 예시 도구 엄격도
read 부작용 없음, 항상 허용 read_file 등 0
egress 네트워크로 나감 — 요청 자체가 데이터를 실어 나를 수 있음 web_fetch, web_search, browser_open_url, Apollo/Hunter 연락처 조회 1
external 머신 밖에 부작용(메시지 전송, SaaS 쓰기) 커넥터 카탈로그의 쓰기, 모든 서드파티 MCP 도구 2
write_local 워크스페이스 변경 — 경로 스코프 + 모드 게이트 write_file, replace_in_file, apply_patch, apply_unified_diff 3
exec 명령 실행 — 모드 게이트 run_shell 3

눈여겨볼 결정이 셋 있습니다.

  • web_search도 egress입니다. 목적지는 고정(설정한 검색 프로바이더)이지만 쿼리가 모델이 고른 자유 텍스트라 “같은 유출 채널”이라는 논리입니다. 연락처 보강(enrichment) 도구는 더 나쁜 경우로 봅니다 — 쿼리 자체가 동의하지 않은 제3자의 이름과 이메일이니까요.
  • 서드파티 MCP 도구는 무조건 external입니다(OPE-136). “MCP 도구의 효과는 낯선 사람의 주장일 뿐, 읽기 이름을 한 쓰기를 구분할 수 없다”는 이유입니다. 과거엔 mcp.json의 requires_approval: false 한 줄로 서버 전체가 read로 떨어져 승인 카드·Discuss 모드 거부·리뷰어·감사 기록을 한 번에 건너뛰었고, 지금은 그 플래그가 “카드만” 생략할 뿐 등급은 고정됩니다. 판정 키는 이름 접두사(mcp__)가 아니라 메타데이터의 category == "mcp"이고, 메타데이터 없는 이름만 접두사로 fail-closed 처리합니다.
  • 사용자 오버라이드는 조일 수만 있고 풀 수는 없습니다. 내장 write/exec/egress, 커넥터 쓰기, MCP 도구에 대해 엄격도가 낮은 오버라이드는 무시됩니다. write를 read로 내리면 경로 스코프와 read-only 게이트가 한꺼번에 꺼지기 때문입니다.
# risk.classify() 요지 (coworker/risk.py)
base = _BASE.get(name) or _catalog_floor(name) or _mcp_floor(name, metadata)
if overrides and (ov := overrides(name)):
    if base is None or STRICTNESS[ov] >= STRICTNESS[base]:
        return ov            # 조이는 방향만 허용
if base: return base
return EXTERNAL if metadata.requires_approval else READ

4. 핵심 설계 ②: 모드 7종과 “하드 플로어”

permissions.py의 Mode는 자율성의 상한(ceiling)을 정합니다. 이름 붙이는 방식 자체가 설계 의도를 드러냅니다 — 예전 auto를 bypass-approvals로 바꾼 이유는 “안전 장치를 끄는 행위”를 이름에 담고 Auto-approve와 헷갈리지 않게 하려는 것이고, “bypass-ALL”이 아닌 이유는 플로어가 여전히 남기 때문입니다.

모드 동작 리뷰어 모델 플로어
discuss 읽기 전용 대화, 편집·계획 워크플로 없음 — 모든 consequential 호출 거부
plan 읽기 전용 + 탐색 → propose_plan → 실행 계약 — discuss와 같은 게이트
interactive(기본) consequential 호출마다 승인 요청 — 유지
auto-approve 승인 카드가 뜨기 전 LLM 리뷰어가 먼저 판단, 확실한 것만 통과 “ask→allow”만 가능, “blocked→allow” 불가 유지
custom interactive + 설정의 auto_allow 도구 자동 허용 — 유지
bypass-approvals 일반 승인 전부 자동 허용(“full access”) — 워크스페이스 밖 쓰기·나중에 실행되는 파일 등은 그대로
dangerously-bypass-approvals 플로어까지 해제, 해제마다 “cleared by mode: …” 기록 — 자기보호 플로어만 남음. 데스크톱 피커엔 노출 안 됨, 서버 플래그로만

하드 플로어는 세 겹입니다.

  1. 자기보호 플로어 — ~/.config/coworker/의 config.toml, risk_overrides.json, workspace_trust.json, unattended.json, coworker.db(저장된 “항상 허용” 포함), secrets.json, inbox_routing.json. 모드·허용 목록·자동 승인보다 먼저 검사하고, 승인이 아니라 거부입니다. 코드 주석이 막으려는 시나리오를 정확히 적어 둡니다: “평범해 보이는 명령 하나를 승인했는데 그게 규칙 파일에 한 줄을 덧붙여, 이후 모든 세션이 더 관대해진다 — 그리고 이건 기본 모드에서 일어난다.”
  2. 나중에 실행되는 프로젝트 내 파일 — .git/hooks/, .github/workflows/, .gitlab-ci.yml, .vscode/tasks.json, .coworker/, setup.py, .envrc, .pre-commit-config.yaml, .husky/, .devcontainer/, 그리고 AGENTS.md(이후 모든 세션의 시스템 프롬프트로 읽히므로). 쓰기는 가능하지만 human_only=True 승인 — Auto-approve 리뷰어가 풀 수 없습니다. 반면 package.json/pyproject.toml은 일부러 뺐습니다. 사용자가 늘 고치는 파일이고 리뷰어가 내용을 보고 버전 업과 설치 스크립트 추가를 구분할 수 있다는 판단입니다.
  3. 세션 폴더 밖 쓰기 — 경로 스코프. 경로를 확정할 수 없는 쓰기도 사람 전용 승인으로 보냅니다.

5. 박스 실측 ①: 같은 호출, 모드별 판정

박스(Linux, Python 3.12.15)에서 main을 클론해 uv로 .[dev] 설치 후, 모델 키 없이 PermissionEngine.evaluate()를 직접 호출했습니다. 아래는 출력 그대로입니다(<ws>는 임시 워크스페이스).

git clone https://github.com/andrewyng/openworker && cd openworker
uv venv .venv -p 3.12 && uv pip install -p .venv/bin/python -e '.[dev]'
.venv/bin/python smoke_perm.py

== classify
read_file                -> read
write_file               -> write_local
run_shell                -> exec
web_fetch                -> egress
mcp__notion__search      -> external      # category="mcp", requires_approval=False여도
my_plugin_tool           -> external      # requires_approval=True 메타데이터
== override cannot loosen write_file: write_local
박스 실측: 같은 도구 호출에 대한 모드별 PermissionEngine 판정 결과 (openworker 0.3.4 소스 설치, 실제 출력 기반)
박스 실측: 같은 도구 호출에 대한 모드별 PermissionEngine 판정 결과 (openworker 0.3.4 소스 설치, 실제 출력 기반)
호출 discuss interactive bypass-approvals dangerously-bypass
read_file <ws>/a.md 허용 허용 허용 허용
write_file <ws>/brief.md 거부(read-only) 승인 요청 허용(full access) 허용
write_file /etc/passwd 거부 거부(not in a writable directory) 거부 허용 — “cleared by mode: write outside the session’s directories”
write_file <ws>/.git/hooks/pre-commit 거부 사람 전용 승인 사람 전용 승인 허용 — “cleared by mode: file that runs automatically later”
run_shell rm -rf build 거부 승인 요청 허용 허용
web_fetch https://example.com/?q=secret 거부 승인 요청 허용 허용
write_file ~/.config/coworker/config.toml 5개 모드(auto-approve 포함) 모두 거부 — “refusing to modify OpenWorker’s own settings”; echo x > …config.toml 셸 명령도 동일하게 거부

읽을 포인트: bypass-approvals에서도 /etc/passwd와 git hook은 멈춥니다. 이름이 “ALL”을 약속하지 않는 이유가 실측으로 확인됩니다. dangerously-bypass는 정말 다 풀리지만 “누가 어떤 플로어를 넘었는지”가 reason 문자열에 남습니다. 단, ls -la 같은 읽기성 명령도 interactive에선 승인 요청이었습니다 — 읽기 전용 명령 자동 허용은 세션 단위 session_readonly나 Auto-approve의 readonly_commands 티어(기본 off)를 켜야 하며, 판별기는 1,699줄짜리 보수적 분류기(coworker/readonly.py)입니다.

권한 관련 테스트 5개 파일도 돌렸습니다.

.venv/bin/python -m pytest -q tests/test_permissions_risk.py tests/test_risk_overrides.py \
  tests/test_permission_gate_corpus.py tests/test_decision_reviewer.py tests/test_approval_integrity.py
154 passed in 6.37s

(전체 스위트가 아니라 거버넌스 관련 5개 파일만입니다. pytest-asyncio의 loop scope 경고 1건 외 실패 없음.)

6. 핵심 설계 ③: Auto-approve 리뷰어와 서킷 브레이커

coworker/reviewer.py는 “두 번째 모델 호출”로 제안된 행동 하나가 사용자의 실제 요청에 비례하는지를 판단합니다. 불변식이 명확해서 그대로 옮길 가치가 있습니다.

불변식 내용 왜 중요한가
ask→allow만 게이트가 needs_user로 표시한 결정에만 호출. 하드 거부는 리뷰어에 도달조차 안 함 리뷰어가 뚫려도 플로어는 그대로
요청당 행동 1개 한 턴에 여러 호출이면 리뷰어 호출도 여러 개를 병렬로 판정이 엉뚱한 행동에 붙을 수 없음(재매칭 리스트 자체가 없음)
Fail closed 깨진 JSON, 미지의 verdict, 빈 응답, 타임아웃, 프로바이더 오류 → 모두 unsure → 사람이 결정 “파싱하다 실행되는” 경로가 없음
비신뢰 콘텐츠 차단 리뷰어 입력은 지침·알려진 세계(폴더·리모트)·사용자 본인 메시지·제안 행동뿐. 웹 페이지·메일 본문·파일 내용은 안 들어감 “공격자는 에이전트에게 말을 걸 수 있어도 판사에게는 못 건다”
출처 라벨 보드 할당·리드 에이전트 메시지·커넥터 이벤트는 사용자 승인이 아님을 프롬프트에 명시 멀티 에이전트 팀에서 권한 세탁 방지
서킷 브레이커 _REVIEWER_TRIP = 5 — 한 턴에서 연속 5회 거부되면 그 턴의 나머지는 사람에게 무한 재시도 루프 차단

서킷 브레이커 숫자에는 운영 이력이 붙어 있습니다. 처음엔 “누적 2회”였는데, 긴 에이전트 턴에서 리뷰어가 한 번 과하게 엄격했던 두 번 때문에 그 뒤 전부가 수동 승인으로 조용히 강등되는 일이 있었고(2026-08-24 소유자 판정), “연속 5회 + allow/unsure/ask_user 응답 시 리셋”으로 바뀌었습니다. 또한 리뷰어는 세션이 attended일 때만 쓰입니다. 자동화(스케줄 작업)는 attended를 설정하지 않으므로 리뷰어가 개입하지 않습니다 — 아래 attendance와 이어지는 부분입니다.

7. 핵심 설계 ④: “누가 대답하는가”를 모드와 분리한 Attendance

권한 모드가 “어디까지 해도 되나”라면, coworker/unattended.py의 attendance는 “에이전트가 물을 때 누가 답하나”입니다. 둘을 독립 축으로 둔 것이 이 프로젝트에서 가장 실무적인 결정이라고 봅니다.

값 상황 질문·승인 처리
attended 사람이 화면 앞에 있음 질문과 승인 카드가 인라인으로
inbox 지금은 아무도 안 봄 인라인 프롬프트가 Inbox에 주차되고 에이전트는 답이 올 때까지 정지(입력창 비활성)
auto 아무도 오지 않음 엔진이 고정 규칙으로 답하고 기록: 질문엔 “가장 덜 파괴적인 선택”, 폴더 요청은 거절+안내, 사람만 풀 수 있는 카드는 거부. 절대 행(hang)하지 않음

대신 답하는 문구도 “모델이 쓰지 않은 고정 텍스트”입니다. README의 “Unattended runs never self-approve”가 코드 수준에서 이렇게 구현됩니다. 슬랙에서 @OpenWorker를 멘션해 데스크톱에서 작업을 돌리는 기능, 아침 브리핑 같은 스케줄 작업이 이 축 위에서 안전하게 돌아가는 구조입니다.

8. 박스 실측 ②: 로컬 에이전트 서버와 토큰

README의 소스 실행 경로대로 헤드리스 서버를 띄웠습니다(UI 없이, 모델 키 없이).

.venv/bin/python -m coworker.server.run --cwd /tmp/owproj --port 18766
# Uvicorn running on http://127.0.0.1:18766
curl http://127.0.0.1:18766/v1/health                 # 200, 토큰 없이도 열림
{"status":"ok","default_workspace":"/tmp/owproj","model":"gpt-5.6-sol"}
curl http://127.0.0.1:18767/v1/inbox                  # 토큰 없음
{"error":"missing or invalid OpenWorker sidecar token"}   [401]
curl -H "X-OpenWorker-Token: $(cat ~/.config/coworker/sidecar-18766.token)" .../v1/inbox
{"items":[]}                                          [200]
.../v1/personas → cowork, code, cloud-posture, dep-audit, reviewer, security
  • 루프백(127.0.0.1)에만 바인딩되고, 실행마다 <state-dir>/sidecar-<port>.token을 만듭니다. 박스에서 이 파일 권한은 600이었습니다. 데스크톱 앱은 디스크에 쓰지 않는 인메모리 토큰을 씁니다.
  • 헬스 체크만 무인증이고 나머지 API는 401. 같은 머신의 다른 프로세스가 로컬 포트를 두드려 에이전트를 조종하는 공격면을 줄이는 방식입니다.
  • 첫 실행만으로 상태 디렉터리에 coworker.db, chat.db, journal.db, recordings.db, automation.db, teams.db 등 SQLite 파일이 생겼습니다. 감사 기록과 대화가 로컬에 쌓이는 “local-first” 구조를 그대로 보여 줍니다.
  • 기본 페르소나는 6종(cowork, code, cloud-posture, dep-audit, reviewer, security)이었고, README의 “Security coworkers ship first” 대로 보안 계열 전문 동료가 포함돼 있습니다.

9. 박스 실측 ③: Harness SDK 0.1.0-beta.4 수명주기

npm install @openworkerai/harness-sdk@0.1.0-beta.4
# added 2 packages — harness-sdk + harness-runtime-linux-x64
# node_modules 33M, 런타임 바이너리 bin/openworker-harness ≈ 33.5MB
node start.mjs   # Harness.start({sandbox:'off'}) → setModelProvider → createAgent → newSession → run → shutdown
단계 결과(실측) 해석
Harness.start() 59~82 ms(3회) Rust 바이너리를 자식 프로세스로 띄우는 비용이 작음
capabilities agent_runs, agent_teams, application_callbacks, attachments, builtin_tools, coding_processes 등 플래그 앱이 기능 협상을 런타임에 할 수 있음
setModelProvider(name ‘Dummy’, baseUrl http://127.0.0.1:9/v1) “Harness rejected the request” 거부 원인은 확정하지 못함(이름 또는 엔드포인트 정책). 공식 예제대로 OpenAI 설정으로 바꾸니 통과
session.run()(무효 키) status:"failed", providerError:{category:"authentication", retryable:false, httpStatus:401, code:"invalid_api_k…"} 예외를 던지지 않고 분류된 실패를 반환 — 재시도 판단을 앱이 코드로 할 수 있음
shutdown() 정상 finally 블록 패턴 권장(README 예제도 동일)

실제 모델 호출 결과(답변 품질, 도구 루프)는 유효한 키를 쓰지 않았으므로 이번 실측 범위 밖입니다. 하나 더: SDK 0.1.0-beta.4의 optionalDependencies는 런타임 0.1.0-beta.3을 가리킵니다. SDK와 런타임 버전이 1:1이 아니므로 고정(pin)할 때 둘 다 확인해야 합니다.

공식 저장소 이미지(docs/assets/how-it-works.png): 요청 → 로컬에서 동작하는 OpenWorker → 연결된 도구 → 결과물. 출처: andrewyng/openworker, MIT
공식 저장소 이미지(docs/assets/how-it-works.png): 요청 → 로컬에서 동작하는 OpenWorker → 연결된 도구 → 결과물. 출처: andrewyng/openworker, MIT

10. 비슷한 도구와 비교

OpenWorker는 “코딩 에이전트 CLI”와 “범용 데스크톱 에이전트”와 “에이전트 SDK” 사이 어딘가에 있습니다. 공개 문서 기준의 일반적인 비교이며, 각 도구 버전에 따라 세부는 다를 수 있습니다.

항목 OpenWorker Claude Code OpenAI Codex CLI block/goose OpenHands
주 형태 데스크톱 앱 + 하네스 SDK 터미널/IDE 코딩 에이전트 터미널 코딩 에이전트 데스크톱 + CLI 에이전트 웹 UI/헤드리스 코딩 에이전트
대상 작업 리서치·문서·코드 리뷰·보안·SaaS 연동 코딩 중심 코딩 중심 범용(확장으로) 코딩 중심
모델 BYO: 클라우드 + Ollama/LM Studio/llama.cpp/vLLM Anthropic 중심 OpenAI 중심(+호환 엔드포인트) 여러 프로바이더 여러 프로바이더
권한 모델 위험 등급 5종 × 모드, 하드 플로어, human_only, 오버라이드는 조이기만 권한 모드 + 허용/거부 규칙 승인 정책 + 샌드박스 모드 도구 권한 설정 컨테이너 샌드박스 중심
LLM 리뷰어 있음(fail-closed, 비신뢰 콘텐츠 차단, 연속 5회 브레이커) 별도 구성에 따라 별도 구성에 따라 — —
무인 실행 attended/inbox/auto 축 분리, 자기 승인 금지 헤드리스 모드 exec 모드 스케줄/레시피 헤드리스
샌드박스 NVIDIA OpenShell(컨테이너) / macOS 내장 / Windows 숨은 계정 OS 샌드박스 옵션 OS 샌드박스 — Docker
임베드용 SDK TS(npm) + Rust, 0.1 beta Agent SDK SDK — SDK
라이선스 MIT 상용 Apache-2.0 Apache-2.0 MIT(일부 예외)

거버넌스 설계만 놓고 본 강·약점입니다.

관점 강점 약점/비용
위험 분류 등급이 선언형 데이터, MCP는 fail-closed MCP 읽기 도구까지 external이라 승인 피로 ↑ (카드 생략 플래그로 완화)
플로어 자기보호가 모든 모드보다 먼저, 실측으로 확인 플로어 목록이 경로 문자열 기반 — 목록 밖의 “나중에 실행되는 파일”은 리뷰어·사람 판단에 의존
리뷰어 ask→allow만, 단일 행동, fail-closed 모델 호출이 추가되므로 비용·지연 증가. 판정은 “보증이 아니라 판단”(README 스스로 명시)
감사 모든 호출에 승인 출처(자동/사용자/거부+리뷰어 이유) 기록 로컬 SQLite — 조직 단위 중앙 수집은 SDK 쪽 telemetry/observability로 따로 구성해야
두 엔진 앱은 빠르게, SDK는 계약 중심으로 같은 규칙의 이중 구현, 문서상 SDK ≠ 앱 엔진이라는 혼동

11. 주의할 점과 한계

  • 설치 경로 혼동: PyPI openworker는 0.0.1 placeholder입니다. 헤드리스 런타임을 쓰려면 지금은 소스 설치(bash packaging/setup_dev_env.sh 또는 직접 venv)가 맞습니다.
  • Windows 빌드 미서명: SmartScreen 경고가 뜹니다. 사내 배포라면 서명 완료 전까지 정책 검토가 필요합니다.
  • Bypass 계열 모드는 신중히: dangerously-bypass-approvals는 저장소 스스로 “일회용 머신이나 컨테이너에서만”이라고 경고합니다. 실측에서도 /etc/passwd 쓰기가 허용으로 바뀌었습니다(기록은 남지만 막지는 않음).
  • 리뷰어는 판사이지 보증인이 아님: 리뷰어는 사용자 메시지와 제안 행동만 보므로, 행동의 내용(예: 파일 본문에 섞인 악성 코드)을 깊게 판단하는 장치가 아닙니다. 플로어·감사·샌드박스가 백스톱입니다.
  • OpenShell 경계: 샌드박스는 세션의 명령·파일 도구를 격리하지만, 에이전트 루프·모델 키·커넥터는 벽 밖에 있습니다. SDK 문서도 “앱 콜백은 앱 권한 그대로 실행된다”고 경고합니다 — 직접 만든 도구는 직접 스코프해야 합니다.
  • SDK API 변동: 0.1.0-beta 단계, PR 보류 요청 중. SDK·런타임 버전을 둘 다 고정하세요.
  • 승인 피로: interactive 기본값에선 ls -la도 묻습니다. readonly 티어·standing rule·도메인 허용 목록을 설계하지 않으면 사용자가 결국 bypass로 가게 됩니다.

12. 누가 도입하면 좋은가

상황 추천도 이유 / 시작점
에이전트 권한 설계를 참고하려는 플랫폼·보안 엔지니어 매우 높음 risk.py·permissions.py·reviewer.py·관련 테스트가 그 자체로 설계 문서. 내 제품 체크리스트로 옮기기 좋음
로컬 모델로 문서·리서치 업무를 자동화하려는 개인/소규모 팀 높음 데스크톱 앱 + Ollama/LM Studio, 키·대화가 로컬. 단 베타
자사 앱에 “승인 가능한 에이전트”를 넣으려는 제품팀 중간 Harness SDK는 승인·내구성 세션·스트리밍을 대신해 주지만 beta. PoC부터
규제 산업(감사 추적 필수) 중간 호출별 승인 출처 기록은 강점. 중앙 수집·보존 정책은 별도 설계
CLI 코딩 에이전트만 필요한 개발자 낮음 이미 쓰는 코딩 CLI가 더 가볍다. OpenWorker는 그보다 넓은 업무 범위를 노림

정리하면 OpenWorker의 가치는 “또 하나의 데스크톱 에이전트”보다 “에이전트가 스스로 권한을 키울 수 없게 만드는 구조”를 코드로 보여 준다는 데 있습니다. 자기보호 파일을 모든 모드보다 먼저 검사하고, 나중에 실행되는 파일은 사람만 승인하게 하고, 리뷰어는 ask를 allow로만 바꿀 수 있게 하고, 무인 실행은 절대 스스로 승인하지 않게 합니다. 박스 실측에서 이 규칙들은 문서에 적힌 그대로 동작했습니다. 지금 당장 사내 표준으로 깔기엔 베타지만, 에이전트를 만드는 팀이라면 이 저장소의 권한 엔진과 테스트는 한 번 정독할 가치가 충분합니다.

답글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다