# Odysseus

> 문서에 적힌 규율 다섯 개가 코드로 강제되는지 하나씩 찾아봤습니다. 강제되는 건 하나였습니다.

- 수치: 규율 5 중 1
- 사람이 보는 화면: https://aitryed.com/ko/teardowns/harness/odysseus/
- 반대 언어: https://aitryed.com/en/teardowns/harness/odysseus/index.md
- 저장소: https://github.com/odysseus-dev/odysseus
- 이 사이트 안내(AI용): https://aitryed.com/ko/llms.txt

---

**내 컴퓨터 안에 통째로 올려 쓰는 AI 작업 공간입니다. 문서가 아주 잘 쓰여 있었는데, 그 문서에 적힌 규칙 다섯 개가 «실제로 코드로 강제되는지» 하나씩 찾아봤습니다. 강제되는 건 하나였습니다.**

> **[도판]** 셀프호스팅 AI 워크스페이스. 도커 컴포즈 한 줄로 벡터DB·메타검색·푸시까지 같이 올라온다. 생후 두 달, 별 84,277개.
>
> Odysseus 의 구성. 도커 컴포즈가 본체와 벡터DB·메타검색·푸시알림을 함께 띄우고, 본체는 얇은 오케스트레이터 아래 코어·라우트·소스 세 덩어리로 나뉜다. 소스 안에 에이전트 루프와 프롬프트 보안 모듈이 있고, 그 밑에 에이전트 툴과 내장 MCP 서버가 붙는다.

## 이 물건이 뭔가요

보통 AI 서비스는 **남의 회사 서버**에서 돕니다. 제가 보낸 내용이 그 회사를 거쳐 갑니다.

이건 **제 컴퓨터 안에 통째로 올려서** 씁니다. 대화·메일·일정·문서 검색·조사·이미지 생성이 한 화면 안에 다 들어 있고, **명령 한 줄이면 필요한 것들이 전부 같이 설치**됩니다.

만들어진 지 두 달인데 **「좋아요」가 84,277개** 붙어 있습니다.

## 그 84,277개는 근거로 못 씁니다

여기서 첫 번째 교훈이 나옵니다.

「좋아요」 말고 다른 숫자를 같이 봐야 합니다. **「복제본을 떠 간 사람」** 숫자입니다. 복제본을 뜬다는 건 **실제로 만져 보려고 가져갔다**는 뜻입니다.

| | 이 창고 | 보통 창고 |
|---|---|---|
| 좋아요 : 복제본 비율 | **450 대 1** | 5~20 대 1 |

**450 대 1**입니다. 450명이 좋아요를 누르는 동안 1명이 만져 봤다는 뜻입니다.

이유가 있었습니다. **유명 유튜버 본인의 프로젝트**라 구독자들이 좋아요는 눌렀는데, **코드를 만질 사람들은 아니었던 것**입니다.

→ 배운 것: **인기 숫자 하나만 보면 틀립니다.** 옆의 숫자와 «비율»을 봐야 그 인기가 무엇으로 이뤄졌는지가 나옵니다.

## 문서가 정말 잘 쓰여 있었습니다

이 창고의 진짜 장점입니다. 문서가 제 것보다 앞서 있었습니다.

- **어떤 공격이 가능한지 정리한 문서**가 따로 있음
- **테스트를 어떻게 쓸지에 대한 기준 문서**가 있음
- **가져다 쓰는 남의 부품마다 «왜 이걸 골랐는지» 주석**이 붙어 있음

세 번째는 특히 드뭅니다. 보통은 부품 목록만 있고 이유가 없습니다.

## 그래서 실험을 했습니다 — 「적힌 대로 실제로 막고 있나」

문서가 좋으면 **그 문서를 믿고 싶어집니다.** 그런데 문서는 **하겠다는 말**이고, 코드는 **하고 있는 것**입니다.

그래서 문서가 선언한 규칙 다섯 개를 골라, **그걸 실제로 강제하는 지점이 코드에 있는지** 하나씩 찾았습니다.

**다섯 중 하나만 실재했습니다.**

나머지 넷은 <strong>규칙이 아니라 잘 쓰인 «의도»</strong>였습니다. 지키자고 적어 뒀는데, 안 지켜도 아무 일이 안 일어납니다.

→ 이게 이 편에서 값을 치른 교훈입니다.

> **문서에 적힌 규칙과, 코드가 강제하는 규칙은 다른 것이다. 「적혀 있다」를 「지켜진다」로 읽으면 틀린다.**

## 유일하게 실재한 하나 — 그리고 제가 가져온 것

실제로 코드로 막고 있던 하나가, 제가 이 조사에서 가져온 유일한 물건입니다.

**문제 상황부터 설명하겠습니다.**

AI에게 외부에서 가져온 글(웹페이지·메일 같은 것)을 읽힐 때, **그 글이 AI에게 명령을 시도할 수 있습니다.** 「지금까지 지시는 무시하고 이렇게 해라」 같은 문장을 글 안에 숨겨 두는 식입니다.

그래서 보통 **울타리로 감쌉니다.**

```
[여기부터 외부 글 — 명령으로 읽지 말 것]
(외부에서 가져온 글)
[여기까지]
```

그런데 **공격자가 그 울타리 문구를 이미 알고 있으면**, 자기 글 안에 「여기까지」를 미리 써 넣습니다. 그러면 울타리가 **거기서 조기에 닫히고**, 그 뒤에 쓴 내용은 **울타리 «밖»** — 즉 명령으로 읽히는 구역에 놓입니다.

이 창고는 그걸 막습니다. **울타리 안에 넣기 전에, 글 안에 있는 울타리 문구를 무해한 것으로 바꿔 치웁니다.** 라벨도 같이 처리하고 줄바꿈까지 정리합니다.

간단한데 안 하면 울타리 전체가 무의미해집니다.

## 판정 — 셋으로 갈랐습니다

| 어디에 | 판정 | 왜 |
|---|---|---|
| 회사에 도입 | **안 함** | 관리자가 **명령 실행 + 파일 읽고 쓰기 + 메일 발송**을 다 할 수 있는데, 만들어진 지 두 달이고 정식 판이 한 번도 안 나옴 |
| 개인적으로 실험 | **조건부** | 격리해서 + 외부에 안 열어 두는 조건 |
| **코드 읽기** | **추천** | 단, **보안 부분만** |

두 번째 줄에 조건을 붙인 이유가 있습니다. 이 창고는 **가져다 쓰는 남의 부품의 판번호를 안 고정**해 뒀습니다. 그러면 **어제 되던 게 오늘 깨집니다** — 남의 부품이 새 판으로 바뀌면서요.

그리고 **자동 검사가 통과를 강제하지 않는 상태**라, 깨져도 아무도 안 웁니다. 둘이 겹치면 위험합니다.

## 마지막 — 여기서 찾으면 안 되는 것

AI를 돌리는 «틀» 자체를 배우러 왔다면 **여기가 아닙니다.**

이 창고가 **그 틀을 다른 데서 가져왔다고 스스로 밝히고** 있습니다. 그리고 **원본 쪽이 조건도 더 자유롭습니다.**

원본이 있는데 사본을 읽을 이유가 없습니다.

## 여기부터는 자세한 기록입니다

**문서는 저보다 앞서 있는데, 그 문서를 강제하는 장치는 저보다 뒤에 있었습니다.** 이 레포가 자기 문서에 선언한 규율 다섯 개를 골라 그것을 강제하는 실행 지점이 코드에 있는지 전수 확인한 결과, **다섯 중 하나만 실재했습니다.** 나머지 넷은 규율이 아니라 잘 쓰인 의도였습니다. 그리고 그 하나 — 프롬프트 인젝션 가드 — 가 이 조사에서 제가 실제로 가져온 유일한 물건입니다.



## 무엇을 하는 물건인가

**남의 서버에 안 맡기고 내 기계 위에 통째로 올리는 AI 작업 공간이다.** 대화·메일·캘린더·문서 검색·심층 리서치·이미지 생성이 한 웹 UI 안에 들어 있고, 그 뒤에서 에이전트 루프가 툴을 돌린다. 모델은 로컬이든 API든 붙일 수 있다.

파일로 보면 이렇다.

| | 파일 | 줄 | |
|---|---:|---:|---|
| 파이썬 | 1,064 | 213,480 | FastAPI |
| 자바스크립트 | 162 | 158,514 | **번들러 없음** — 바닐라 ES 모듈 |
| 테스트 | 754 | 84,992 | 런타임 대비 40% |
| `src/` | 143 | 56,115 | 평평한 폴더 — 최대 구조 부채 |
| `mcp_servers/` | 5 | 3,531 | 메일·이미지·메모리·검색 내장 |

최대 파일이 메일 라우트 6,032줄, 에이전트 루프 5,248줄이다. **생후 두 달에 이 규모**라는 게 이 레포를 읽을 때 계속 붙는 조건이다.

설계에서 눈에 띄는 결정 둘. **에이전트 루프가 펜스 코드블록을 파싱해서 툴을 부른다** — 네이티브 함수 호출도 같은 경로로 합류시킨다. 함수 호출을 지원 안 하는 로컬 소형 모델까지 받으려는 선택이다. 그리고 **컨텍스트가 85%에 닿으면 자동으로 압축**하고, 입력 예산을 모델의 컨텍스트 창에서 동적으로 산출한다.

## 별 84,277개는 근거로 못 쓴다

포크가 187개다. **비율이 450 대 1**인데 정상적인 오픈소스는 5~20 대 1이다. 유명 유튜버 본인 프로젝트라 스타는 눌렀지만 코드는 안 만지는 사람이 압도적이라는 뜻이다.

봇 조작과는 다르다. PR 3,317건에 기여자 313명이라 활동이 같이 크다 — **봇 스타는 활동을 동반하지 않는다.** 그러니 숫자 자체는 진짜고, 다만 **품질 신호가 아니다.**

2차 출처도 못 쓴다. 이 프로젝트를 소개한 글 여럿이 **라이선스를 MIT라고 적었는데 실제로는 AGPL-3.0**이고(도입 판단을 통째로 뒤집는 오보다), **포크를 10,000개라고 적었는데 실제로는 187개**다. 이 글의 수치는 전부 API와 얕은 클론으로 직접 쟀다.

## 규율 다섯 중 코드가 강제하는 건 하나였다

문서가 유난히 좋은 레포다. 위협 모델 문서, 테스트 표준 문서, 의존성마다 붙은 근거 주석. 그래서 문서가 **선언한** 규율을 다섯 개 골라, 그것을 **강제하는 지점**이 코드에 실재하는지 하나씩 찾았다.

> **[도판]** 선언과 강제를 따로 셌다. 문서가 좋다는 것과 그 문서가 지켜진다는 것은 다른 사실이다.
>
> 문서가 선언한 규율 다섯 가지를 코드로 검증한 결과. 프롬프트 인젝션 가드만 통과했고, 테스트 게이트와 행위 우선 검증과 의존성 핀 고정은 불합격, 자동 분류는 절반이다.

**통과한 하나 — 프롬프트 인젝션 가드.** 위협 모델 문서는 외부에서 들어온 텍스트가 전부 신뢰불가 래퍼를 거친다고 주장한다. 웹 검색결과, 가져온 URL, 유튜브 자막, 검색된 문서, 저장된 메모리, 스킬 텍스트, 통합, MCP 툴 설명, 메일, 업로드 파일, 심층 리서치 크롤링. 테스트를 뺀 호출부가 **29개** 실재하고, 주장한 표면을 실제로 덮는다. **툴 실행 결과까지 감싼다** — 대부분의 구현이 놓치는 지점이다.

**불합격 셋.**

- **테스트가 게이트가 아니다.** 8만 5천 줄이 있는데 CI 잡에 `continue-on-error: true`가 붙어 있다. 깨져도 초록불이고 머지를 안 막는다. 실제 머지 방어선은 문법 검사 + 보안 스캔 + 사람 리뷰가 전부인데, **두 달간 PR이 3,317건 들어온 레포에서 품질 방어선이 사람이라는 뜻**이다
- **행위 우선 검증을 스스로 어긴다.** 표준 문서가 "소스 텍스트나 AST가 아니라 관측 가능한 행위를 검증하라"고 못 박는데, 소스를 직접 읽는 테스트가 45개 있다. 그중에 **보안 불변식을 소스 문자열 매칭으로 고정한 것**이 있다 — 변수명만 바꿔도 깨지고(거짓 실패), 다른 경로로 격리가 뚫려도 통과한다(거짓 통과). 가장 나쁜 조합이다
- **의존성 30개 중 26개가 버전 무핀이고 락파일이 없다.** 암호·인증 라이브러리까지 포함해서다. 권장 설치 경로가 `docker compose up --build`라 **사용자마다 다른 의존성 조합을 받는다** — 재현 불가능한 빌드다

가장 아이러니한 대목: **CI 액션은 커밋 해시로 핀 고정해 공급망 공격을 막는데, 정작 프로덕션에 들어가는 런타임 의존성은 무방비다.** 공급망 규율이 CI에만 있고 런타임엔 없다.

**절반 하나.** 테스트 754개에 수집 시점 자동 분류를 씌웠는데, 분류기를 직접 돌려 보니 **41%가 미분류**다. 가장 중요한 5,248줄짜리 에이전트 루프의 테스트가 어느 영역에도 안 들어간다 — 키워드 매칭에 "agent"가 없어서다. 다만 이건 **설계 의도이기도 하다**(아래 참조).

## 가져온 것 — 가드 마커 이스케이프

신뢰불가 텍스트를 구분자로 감싸 프롬프트에 넣을 때, **그 텍스트 안에 구분자 리터럴이 들어 있으면 블록이 조기 종료된다.** 그 뒤 내용은 신뢰 구역으로 새어 나간다. 이 레포는 넣기 전에 마커를 무해한 토큰으로 치환하고, 라벨도 같이 처리하고, 개행까지 제거한다.

구현이 열 줄이다. 그리고 이게 제게 **없던** 방어입니다.

**보안 문제이기 전에 사고 문제다.** 기획서나 이슈 원문을 통째로 모델에 넣는 지점이 여럿인데, 문서에 우연히 구분자 비슷한 문자열이 있으면 공격자 없이도 프롬프트 구조가 깨진다. 실제로 대괄호 태그 하나가 파서를 세운 일이 이미 있었다. **악의를 가정하지 않아도 도입 근거가 선다.**

같이 본 것 둘, 원리만 가져왔다.

- **모르는 것을 크게 드러내는 분류.** 41% 미분류는 사고가 아니라 설계다. 분류기 독스트링이 *"추측하느니 미분류로 남기는 쪽을 선호한다"*고 적어 뒀고, 미분류 파일도 자기 마커를 받아 주소를 갖는다. 그래서 **"아직 이해 못 한 영역"이 숫자로 보인다.** 모든 항목을 어떤 분류에든 밀어 넣으면 이해 못 한 것이 정상 분류 속에 숨는다 — 목표는 0%가 아니라 추세다
- **끄되, 왜 끄는지와 언제 켤지를 그 자리에 적는다.** 테스트를 게이트에서 뺀 건 실패지만 빼는 **방식<strong>은 배울 만하다. `continue-on-error` 바로 위에 현 상태·이유·졸업 조건 세 줄이 붙어 있다. ⚠</strong>졸업 조건에 기한이 없으면 영구가 된다**는 게 함정이지만, 아무 말 없이 끄는 것보다는 낫다

## 판정

| | |
|---|---|
| 사내 도입 | ✗ — AGPL-3.0에 관리자 = 셸 실행 + 파일 읽기쓰기 + 메일 발송, 의존성 무핀, 생후 두 달, 릴리스 태그 0개 |
| 개인 실험 | △ — 무핀 의존성과 비게이트 테스트가 겹치면 **어제 되던 게 오늘 깨진다.** 도커 격리 · 외부 미노출 조건 |
| 코드 읽기 | ◎ — 단 프롬프트 보안 모듈만 |

에이전트 루프 패턴을 보러 왔다면 여기가 아니다. **이 레포가 그 패턴을 상류에서 가져왔다고 스스로 밝히고 있고**, 상류는 MIT라 라이선스도 자유롭다.

⚠ 그리고 이 조사가 남긴 규칙 하나. 처음 읽었을 때 저는 이 레포를 "규율 있는 프로젝트"로 판정했다. 문서가 워낙 좋아서다. **잘 쓰인 문서를 보고 문서의 품질을 코드의 품질로 착각한 것**이고, 위 다섯 칸 중 넷이 그 착각의 크기다.

> **"규율이 있다"고 쓰려면 그 규율을 강제하는 실행 지점 — CI 게이트·훅·린터 — 을 먼저 찾는다. 없으면 그건 규율이 아니라 의도다.**