OpenWiki Windows 초보자 가이드

Summary

OpenWiki는 코드베이스를 분석해 코딩 에이전트가 읽을 수 있는 openwiki/ 문서를 만들고, 코드 변경에 맞춰 계속 갱신하는 TypeScript CLI입니다.

빠른 시작

저장소: langchain-ai/openwiki

MIT license 13.1k stars 901 forks

핵심 사항은 다음과 같습니다.

• Node.js 22 이상이 필요합니다.
• Windows에서는 npm 또는 pnpm 전역 설치가 권장됩니다.
• openwiki --init은 현재 저장소용 문서를 초기 생성합니다.
• 첫 실행에서 추론 제공자, API 키, 모델을 설정합니다.
• 자격 증명은 사용자 프로필 아래 ~/.openwiki/.env에 저장됩니다.

PowerShell에서 다음 순서로 시작합니다. 먼저 문서화하려는 코드 저장소를 현재 작업 폴더로 열어 두어야 합니다.

npm install -g openwiki
openwiki --help
openwiki --init

WARNING

npm install -g openwiki는 인터넷에서 패키지를 내려받아 전역으로 설치합니다. 패키지 이름과 출처를 확인한 뒤 실행하세요. 관리자 권한이 필요하다는 설명은 원본에서 확인되지 않았습니다.

저장소 소개

OpenWiki는 코드베이스 또는 개인 지식 자료를 로컬 위키로 정리하는 명령줄 도구입니다. 이 가이드는 기본값인 코드 모드에 집중합니다.

OpenWiki 원본 README의 CLI 실행 화면입니다. 이미지를 누르면 GitHub의 원본 파일을 엽니다.

구분	설명
코드 모드	현재 코드 저장소를 분석하고 openwiki/에 문서를 만듭니다.
개인 모드	설정된 자료를 바탕으로 ~/.openwiki/wiki에 개인 위키를 만듭니다.
패키지 버전	0.2.3
실행 파일	openwiki → ./dist/cli.js
라이선스	MIT
구현 형태	TypeScript 기반 Node.js CLI

인자 없이 실행하는 openwiki, openwiki --init, openwiki --update는 코드 모드로 동작합니다. 개인 모드에는 openwiki personal 형식을 사용합니다.

생성 문서는 Google Open Knowledge Format(OKF) v0.1과 호환됩니다. 일반 개념 문서는 YAML 메타데이터와 Markdown 링크를 사용하며, 루트 index.md에는 okf_version: "0.1"이 선언됩니다.

Windows 사전 준비

필수 조건은 다음과 같습니다.

항목	요구 사항
운영체제	Windows에서 npm 또는 pnpm 사용 권장
Node.js	22 이상
패키지 관리자	npm 또는 pnpm
추론 서비스	지원되는 제공자와 해당 인증 정보
작업 위치	문서화할 저장소의 현재 작업 폴더

Node.js 및 npm 버전 확인 명령은 제공된 원본에서 확인되지 않았습니다. Node.js 설치 방법도 원본에서 확인되지 않았으므로 공식 Node.js 배포 경로에서 22 이상을 준비하세요.

지원 제공자로는 OpenAI, OpenRouter, Anthropic, Gemini, Gemini Enterprise, AWS Bedrock, OpenAI 호환 서비스 등이 명시되어 있습니다. 첫 실행 기본 제공자는 OpenAI이며 기본 모델은 gpt-5.6-terra입니다. 실제 이용 가능 여부와 비용은 각 제공자에서 별도로 확인해야 합니다.

TIP

처음에는 연결하려는 추론 제공자 하나만 정하고 해당 서비스의 인증 정보와 과금 정책을 먼저 확인하세요. LangSmith 키는 선택 사항입니다.

WARNING

Bun의 bun install -g openwiki 경로는 better-sqlite3를 직접 컴파일할 수 있습니다. 이 경우 Visual Studio Build Tools와 Desktop development with C++ 워크로드가 필요합니다. Windows 초보자는 원본이 권장하는 npm 또는 pnpm 경로를 우선 사용하는 편이 단순합니다.

설치와 실행

npm으로 설치

npm install -g openwiki

pnpm을 이미 사용한다면 다음 명령도 원본에서 확인됩니다.

pnpm add -g openwiki

둘 중 하나만 선택하면 됩니다.

도움말 확인

openwiki --help

코드 저장소 문서 초기화

문서화할 저장소를 현재 작업 폴더로 연 다음 실행합니다.

openwiki --init

첫 대화형 실행에서는 다음 항목을 설정합니다.

1. 추론 제공자
2. 제공자 API 키 또는 지원되는 로그인 방식
3. 사용할 LLM 모델
4. 선택 사항인 LangSmith API 키

설정과 비밀 값은 로컬의 ~/.openwiki/.env에 저장됩니다.

WARNING

API 키는 비밀번호처럼 취급하세요. 화면 공유, 커밋, 이슈 또는 로그에 키를 붙여 넣지 마세요. ~/.openwiki/.env 파일을 Git에 추가해서도 안 됩니다.

초기화 후 문서를 다시 갱신할 때는 다음 명령을 사용합니다.

openwiki --update

대화형 코드 모드는 다음과 같이 시작합니다.

openwiki

한 번 실행하고 종료하면서 최종 출력만 표시하는 예시는 다음과 같습니다.

openwiki -p "Summarize what you can do"

첫 성공 확인

설치 직후 가장 낮은 위험으로 확인할 수 있는 명령은 다음과 같습니다.

openwiki --help

도움말이 표시되면 전역 실행 파일을 찾을 수 있는 상태입니다. 그다음 openwiki --init을 완료하고 다음 결과를 확인합니다.

• 현재 저장소에 openwiki/ 문서 폴더가 생성되었는지 확인합니다.
• 저장소 루트에 AGENTS.md와 CLAUDE.md가 생성 또는 갱신되었는지 확인합니다.
• 기존 파일이 있었다면 OpenWiki가 관리하는 <!-- OPENWIKI:START -->부터 <!-- OPENWIKI:END --> 블록만 변경했는지 살펴봅니다.
• 저장소별 지침 파일 openwiki/INSTRUCTIONS.md가 있다면 일반 실행에서 임의로 다시 쓰이지 않았는지 확인합니다.

성공한 갱신 기록은 openwiki/.last-update.json에 저장된다고 제공된 빠른 시작 문서에 설명되어 있습니다.

TIP

생성 결과를 바로 신뢰하지 말고 실제 소스 코드와 대조하세요. OpenWiki 문서는 AI가 생성하므로 누락이나 잘못된 해석이 있을 수 있습니다.

핵심 구조

경로	역할
README.md	설치, 사용법, 제공자와 커넥터 개요
package.json	Node.js 요구 버전, 실행 파일, 스크립트와 의존성
src/cli.tsx	Ink 기반 화면과 실행 수명주기
src/commands.ts	CLI 명령과 옵션 파싱
src/agent/index.ts	모델 생성, 에이전트 실행, 메타데이터 기록
src/agent/prompt.ts	문서 생성 지시와 관리 블록 규칙
src/agent/docs-only-backend.ts	문서 쓰기 범위를 제한하는 백엔드
src/code-mode.ts	코드 모드 설정과 저장소 보조 파일 관리
src/env.ts	~/.openwiki/.env 저장과 자격 증명 진단
src/credentials.tsx	제공자, 키, 모델의 대화형 설정
src/connectors/	로컬 자료 수집용 커넥터 구현
src/ingestion.ts	설정된 자료의 수집 실행 조정
openwiki/	생성된 저장소 문서
examples/	GitHub, GitLab, Bitbucket 자동 갱신 예시

openwiki/는 애플리케이션 소스가 아니라 생성 문서로 취급해야 합니다.

동작 흐름

코드 모드의 확인된 흐름을 단순화하면 다음과 같습니다.

sequenceDiagram
  actor User as 사용자
  participant CLI as OpenWiki CLI
  participant Repo as 코드 저장소
  participant LLM as 추론 모델
  participant Wiki as openwiki 문서

  User->>CLI: openwiki --init 또는 --update
  alt 최초 실행
    CLI-->>User: 제공자, API 키, 모델 설정 요청
    User->>CLI: 설정 저장
  end
  CLI->>Repo: 코드와 기존 문서 조사
  CLI->>LLM: 저장소 맥락과 문서 생성 요청
  LLM-->>CLI: 문서 초안 반환
  CLI->>Wiki: 문서 생성 또는 갱신
  CLI->>Repo: AGENTS.md와 CLAUDE.md 연결 유지
  CLI-->>User: 갱신 결과와 메타데이터 보고

Mermaid 다이어그램은 기본적으로 생성될 수 있습니다. OpenWiki는 생성 후 문법을 검사하고, 실패한 다이어그램을 설명이 붙은 일반 text 블록으로 바꿉니다. 이후 --update 실행에서 복구를 시도합니다. mermaid와 jsdom 설치는 더 정밀한 검사용 선택 사항이며 필수 설치는 아닙니다.

개인 모드에서는 커넥터가 원시 자료와 매니페스트를 ~/.openwiki/connectors/<connector>/raw/에 저장한 뒤 ~/.openwiki/wiki/로 합성합니다. 이 흐름은 코드 모드의 첫 시작에는 필요하지 않습니다.

안전 주의사항

WARNING

~/.openwiki/.env에는 API 키와 OAuth 토큰이 저장될 수 있습니다. 특히 ChatGPT 로그인 방식의 refresh token은 비밀번호처럼 보호해야 합니다.

WARNING

openwiki auth slack, openwiki auth gmail, openwiki auth x, openwiki auth notion은 브라우저 OAuth를 시작하고 반환된 토큰을 로컬에 저장합니다. 코드 모드만 시험하는 단계에서는 커넥터 인증을 실행할 필요가 없습니다.

WARNING

openwiki ngrok start는 Slack OAuth용 임의의 공개 HTTPS 전달 주소를 만듭니다. 외부 네트워크에 콜백 경로를 노출하므로 목적과 접근 범위를 이해하기 전에는 실행하지 마세요.

• 커넥터 설정 파일에는 비밀 값 자체가 아니라 환경 변수 이름만 기록해야 합니다.
• OpenAI 호환 대체 URL은 API 키와 요청 내용을 다른 서버로 전달할 수 있습니다. 신뢰하는 서버만 사용하세요.
• AWS Bedrock 자격 증명은 필요한 최소 권한만 부여해야 합니다. 구체적인 Windows 보관 절차는 원본에서 확인되지 않았습니다.
• GitHub Actions 예시는 저장소 내용 쓰기와 Pull Request 쓰기 권한을 사용하며 제공자 비밀 값이 필요합니다. 처음부터 자동화하지 말고 로컬 결과를 검토한 후 도입하세요.
• 예약 또는 CI 실행은 기본적으로 익명 신뢰성 텔레메트리를 전송합니다. 로컬 실행도 텔레메트리가 기본 활성화되어 있습니다. PowerShell에서 일시적으로 끄는 정확한 명령은 원본에서 확인되지 않았습니다. 영구 설정으로 ~/.openwiki/.env에 OPENWIKI_TELEMETRY_DISABLED=1을 추가하는 방법은 README에 명시되어 있습니다.
• MIT 라이선스는 소프트웨어를 보증 없이 제공합니다. 생성 문서의 정확성과 적용 결과는 사용자가 검토해야 합니다.

다음 단계

기본 실행에 성공했다면 다음 순서가 적절합니다.

1. openwiki/의 생성 문서를 실제 코드와 대조합니다.
2. 저장소 문서의 범위와 우선순위를 openwiki/INSTRUCTIONS.md에 정리합니다.
3. 변경 후 openwiki --update로 문서를 갱신합니다.
4. 필요할 때만 개인 모드와 커넥터를 조사합니다.
5. 반복 갱신이 안정된 뒤 GitHub Actions 예시 도입을 검토합니다.

CI에서는 openwiki code --update --print를 사용하며, 기존 문서가 없어도 필요한 제공자와 모델 환경 변수가 있으면 초기 문서를 만들 수 있다고 README에 명시되어 있습니다. 다만 워크플로는 저장소 쓰기 권한, 제공자 비밀 값, 텔레메트리 설정을 함께 검토해야 합니다.

참고한 원본

GitHub 원본 저장소