OpenWiki 설치: AI 에이전트용 코드베이스 문서 자동화 가이드

코딩 에이전트가 오래된 README만 읽으면 현재 코드 구조와 다른 답을 내놓기 쉽습니다. OpenWiki는 저장소를 읽어 에이전트용 위키를 만들고, 코드 변경 뒤에도 같은 문서를 갱신하는 CLI입니다.

이 글의 범위는 OpenWiki 코드 모드 설치와 첫 문서 생성까지입니다. Personal 모드와 외부 커넥터 설정은 다루지 않습니다.

1. 코드 모드가 만드는 파일

OpenWiki 코드 모드는 현재 저장소 안에 openwiki/ 문서 폴더를 만듭니다. 루트의 AGENTS.md와 CLAUDE.md에는 에이전트가 위키를 확인하도록 안내하는 관리 블록도 추가합니다. 기존 파일 전체를 덮지 않고 <!-- OPENWIKI:START -->와 <!-- OPENWIKI:END --> 사이만 갱신한다는 점이 눈에 띕니다.

생성 문서는 Google Open Knowledge Format v0.1을 따릅니다. 각 개념 문서는 Markdown 링크로 연결되고, 루트 index.md에는 okf_version: "0.1"이 기록됩니다.

저는 별도 검색 서버를 먼저 운영하기보다 저장소와 함께 리뷰할 수 있는 Markdown 문서를 시작점으로 삼는 쪽이 낫다고 봅니다. 문서 변경도 코드 PR에서 함께 확인할 수 있기 때문입니다.

2. npm으로 CLI 설치

Node.js와 npm이 준비된 터미널에서 아래 명령을 실행하시면 됩니다. Windows에서도 npm 또는 pnpm 설치를 권장합니다. Bun은 better-sqlite3를 직접 빌드할 수 있어 Visual Studio Build Tools가 추가로 필요할 수 있습니다.

npm install -g openwiki
openwiki --help

도구 설치만 확인하려면 openwiki --help 출력에서 --init, --update, --print 옵션을 찾아주시면 됩니다. 첫 실행은 프로젝트 루트에서 진행합니다.

cd <프로젝트_경로>
openwiki --init

초기 설정에서 inference provider, API 키, 모델을 고릅니다. 설정과 비밀 값은 로컬 ~/.openwiki/.env에 저장됩니다. OpenAI, OpenRouter, Gemini, Anthropic, AWS Bedrock과 OpenAI-compatible endpoint 등이 공식 지원 목록에 들어 있습니다.

3. 첫 문서 생성 확인

openwiki --init은 기본적으로 코드 모드로 실행됩니다. 완료 후 프로젝트 루트에서 openwiki/, AGENTS.md, CLAUDE.md를 확인합니다. 저장소별 문서 범위와 우선순위는 openwiki/INSTRUCTIONS.md에 적으면 됩니다. 이 파일은 일반 업데이트에서 자동으로 다시 쓰지 않습니다.

설치는 npm 또는 pnpm CLI로 진행합니다. v0.2.1 릴리스 커밋 기준 공식 문서가 제공하는 설치 명령과 생성 경로는 아래와 같습니다.

기존 자동화 도구를 컨테이너로 운영하는 흐름은 Docker Compose로 n8n 셀프 호스팅하기에서 확인할 수 있습니다. OpenWiki는 서버를 띄우는 방식이 아니라 프로젝트 로컬 CLI로 문서를 생성한다는 차이가 있습니다.

4. CI에서 문서 갱신

공식 예제는 GitHub Actions, GitLab CI, Bitbucket Pipelines를 제공합니다. GitHub Actions에서는 examples/openwiki-update.yml을 .github/workflows/openwiki-update.yml로 복사하고 provider와 모델 환경 변수를 CI secret에 넣습니다.

CI 명령은 초기화와 갱신을 나눌 필요가 없습니다. 문서가 아직 없어도 아래 명령이 첫 문서를 만들고, 이후 실행에서는 변경분을 갱신합니다.

openwiki code --update --print

예약 실행은 익명 reliability telemetry를 기본 전송합니다. 보내지 않으려면 CI 환경 변수에 OPENWIKI_TELEMETRY_DISABLED=1을 지정하시면 됩니다. 파일 내용, 저장소 이름, credential, prompt, 모델 출력은 telemetry 수집 항목이 아니라고 공식 문서에 명시돼 있습니다.

확인

openwiki code --update --print 실행 뒤 openwiki/index.md가 생기고 AGENTS.md 또는 CLAUDE.md에 OpenWiki 관리 블록이 보이면 코드 모드 문서 생성이 끝난 것입니다.