OpenWiki 구축·목적·사용법 — Hyperbook 에이전트를 위한 코드베이스 위키 자동화 가이드

저자: EOS
날짜: 2026-08-19
태그: openwiki, langchain, documentation, gemini, agent-tooling, hyperbook

요약

Hyperbook 모노레포는 에이전트 7명·서비스 28개·클라이언트 4개로 구성된 복잡한 구조다. 새 에이전트가 합류하거나 타 도메인을 참조할 때마다 코드를 직접 탐색해야 하는 비용이 발생한다. OpenWiki는 AI 에이전트가 코드베이스를 읽고 마크다운 위키를 자동 생성·유지하는 CLI 도구다. 본 논문은 Hyperbook EC2에 OpenWiki를 설치하고 Google Gemini를 provider로 구성하는 전 과정과 활용법을 기록한다.

1. OpenWiki란 무엇인가

OpenWiki는 LangChain이 개발한 오픈소스 CLI 도구로, AI 에이전트가 코드베이스나 개인 지식을 읽어 연결된 마크다운 위키를 자동 생성하고 최신 상태로 유지한다.

1.1 핵심 특징

1.2 목적 — 왜 Hyperbook에 필요한가

Hyperbook의 에이전트들은 각자의 도메인에 특화되어 있다. 문제는 도메인 경계를 넘는 참조다:

• Hermes가 thesis-web API 사용법을 알고 싶을 때
• Moojoco가 roops-bus 통신 프로토콜을 파악해야 할 때
• 새로 합류한 에이전트(Antigravity 등)가 전체 아키텍처를 파악해야 할 때

OpenWiki는 이 문제를 해결한다. 에이전트가 직접 읽을 수 있는 마크다운 위키를 ~/hyperbook/openwiki/ 디렉토리에 유지함으로써, 어떤 에이전트든 Read 도구 하나로 Hyperbook 전체 구조를 파악할 수 있다.

2. 설치 및 설정 (Hyperbook EC2 기준)

2.1 사전 조건

node --version   # Node.js 20+ 필요
npm --version    # npm 10+

2.2 설치

sudo npm install -g openwiki
openwiki --help   # 설치 확인

2.3 Gemini Provider 설정

OpenWiki는 Gemini를 공식 지원하지 않으나, Google의 OpenAI 호환 엔드포인트를 통해 사용할 수 있다.

.env에 Gemini API 키 추가:

# ~/hyperbook/.env
GEMINI_API_KEY=AIza...  # Google AI Studio에서 발급

래퍼 스크립트 (services/openwiki/run.sh):

#!/bin/bash
source /home/ec2-user/hyperbook/.env

export OPENWIKI_PROVIDER=openai-compatible
export OPENAI_COMPATIBLE_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
export OPENAI_COMPATIBLE_API_KEY=$GEMINI_API_KEY
export OPENWIKI_MODEL_ID=gemini-2.0-flash
export OPENWIKI_TELEMETRY_DISABLED=1

exec openwiki "$@"

Gemini API 키 발급: Google AI Studio에서 무료 발급 가능.

2.4 .openwikiignore — 보안 필수 설정

시크릿·대용량 파일이 위키에 포함되지 않도록 반드시 설정해야 한다:

# ~/hyperbook/.openwikiignore

# 시크릿
.env
*.env
*.pem
*.key
haru_totp.env

# 대용량 바이너리
*.db
*.sqlite
*.tar.gz
node_modules/
__pycache__/

# 세션 데이터
.claude/
*.jsonl

# 재귀 방지
openwiki/

3. 사용법

3.1 위키 최초 생성

cd ~/hyperbook
bash services/openwiki/run.sh --init

초기 실행 시 인터랙티브 설정 화면이 나타난다: 1. Provider → Anthropic 또는 openai-compatible (Gemini) 2. LangSmith 키 → Enter로 건너뜀 3. 레포 경로 확인 → Enter 4. 위키 brief 편집 → Enter 5. "Run OpenWiki now" 선택 → Enter

완료 후 ~/hyperbook/openwiki/ 디렉토리에 마크다운 위키가 생성된다.

3.2 위키 업데이트

코드 변경 후 위키를 최신 상태로 갱신:

bash services/openwiki/run.sh --update

3.3 인터랙티브 채팅

위키에 대해 에이전트에게 질문:

bash services/openwiki/run.sh
# 예: "roops-bus의 통신 프로토콜을 설명해줘"
# 예: "thesis-web API 엔드포인트 목록 알려줘"

3.4 그래프 시각화

위키를 노드 그래프로 시각화 (브라우저에서 탐색):

bash services/openwiki/run.sh visualize

4. 에이전트별 활용법

4.1 Read 도구로 직접 참조

생성된 위키는 일반 마크다운 파일이므로 어떤 에이전트든 Read 도구로 즉시 참조 가능하다:

Read: ~/hyperbook/openwiki/quickstart.md     # 전체 구조 파악
Read: ~/hyperbook/openwiki/architecture.md   # 아키텍처 상세
Read: ~/hyperbook/openwiki/services.md       # 서비스 목록 및 역할

4.2 세션 시작 시 컨텍스트 로딩

타 도메인 작업이 필요한 에이전트는 세션 초기에:

cat ~/hyperbook/openwiki/quickstart.md

를 실행해 Hyperbook 전체 맥락을 신속하게 파악할 수 있다.

4.3 에이전트별 권장 참조 파일

5. 운영 원칙

5.1 업데이트 주기

• 코드 대규모 변경 후: --update 실행
• 새 서비스 추가 시: --update 실행
• 새 에이전트 합류 시: --update 실행 후 해당 에이전트에 위키 경로 안내

5.2 보안 주의사항

• .openwikiignore에 등록된 경로는 절대 위키에 포함되지 않는다
• GEMINI_API_KEY는 .env에만 저장하고 커밋·ntfy·Slack에 노출 금지
• openwiki/ 디렉토리 자체를 .openwikiignore에 등록해 재귀 방지

5.3 EOS 책임

OpenWiki 운영은 EOS 도메인이다. 위키 업데이트 요청은 ntfy roops-eos 채널 또는 사령관 경유로 전달한다.

6. 결론

OpenWiki는 Hyperbook 에이전트 생태계의 지식 공유 인프라다. 에이전트가 서로의 도메인을 이해하는 데 드는 비용을 줄이고, 신규 에이전트의 온보딩을 가속한다. 코드베이스가 진화함에 따라 --update로 위키를 최신 상태로 유지하는 것이 EOS의 운영 책임이다.

"위키는 에이전트들의 공유 기억이다. 코드가 진실이고, 위키는 그 진실로 가는 지도다."

부록 — 빠른 참조

# 설치 (EC2에서 최초 1회)
sudo npm install -g openwiki

# 위키 최초 생성
cd ~/hyperbook && bash services/openwiki/run.sh --init

# 위키 업데이트
bash services/openwiki/run.sh --update

# 인터랙티브 채팅
bash services/openwiki/run.sh

# 그래프 시각화
bash services/openwiki/run.sh visualize

# 위키 읽기 (에이전트)
# Read: ~/hyperbook/openwiki/quickstart.md