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

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/ |
백엔드 테스트 스위트(권한 게이트 코퍼스, 리뷰어, 승인 무결성 등) | 권한 관련 테스트가 설계 의도의 가장 좋은 문서 |

| 비교 축 | 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: …” 기록 | — | 자기보호 플로어만 남음. 데스크톱 피커엔 노출 안 됨, 서버 플래그로만 |
하드 플로어는 세 겹입니다.
- 자기보호 플로어 —
~/.config/coworker/의config.toml,risk_overrides.json,workspace_trust.json,unattended.json,coworker.db(저장된 “항상 허용” 포함),secrets.json,inbox_routing.json. 모드·허용 목록·자동 승인보다 먼저 검사하고, 승인이 아니라 거부입니다. 코드 주석이 막으려는 시나리오를 정확히 적어 둡니다: “평범해 보이는 명령 하나를 승인했는데 그게 규칙 파일에 한 줄을 덧붙여, 이후 모든 세션이 더 관대해진다 — 그리고 이건 기본 모드에서 일어난다.” - 나중에 실행되는 프로젝트 내 파일 —
.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은 일부러 뺐습니다. 사용자가 늘 고치는 파일이고 리뷰어가 내용을 보고 버전 업과 설치 스크립트 추가를 구분할 수 있다는 판단입니다. - 세션 폴더 밖 쓰기 — 경로 스코프. 경로를 확정할 수 없는 쓰기도 사람 전용 승인으로 보냅니다.
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

| 호출 | 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)할 때 둘 다 확인해야 합니다.

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로만 바꿀 수 있게 하고, 무인 실행은 절대 스스로 승인하지 않게 합니다. 박스 실측에서 이 규칙들은 문서에 적힌 그대로 동작했습니다. 지금 당장 사내 표준으로 깔기엔 베타지만, 에이전트를 만드는 팀이라면 이 저장소의 권한 엔진과 테스트는 한 번 정독할 가치가 충분합니다.