langchain-ai/openwiki

스스로 유지보수되는 위키. 에이전트를 위해 만들어졌고, 인간이 탐색한다.

OpenWiki는 코드베이스 또는 개인 지식을 위한 위키를 작성하고 유지보수하는 CLI입니다. 에이전트가 소스를 읽고, 사용자가 소유하는 연결된 Markdown 위키를 종합하여, 모든 변경 사항에 대해 최신 상태를 유지합니다. 에이전트가 메모리로 읽을 수 있도록 설계되었으며, 인간이 탐색할 수 있는 대화형 시각화 도구(interactive visualizer)를 제공합니다.

OpenWiki가 제공하는 것:

• 에이전트가 작성한 문서 — Deep Agents 문서화 에이전트가 생성하여 정확성을 유지합니다.
• 두 가지 모드: 저장소용 code 위키 또는 개인 지식용 personal 위키.
• 13개 모델 제공자(provider) 기본 지원 — OpenAI, Anthropic부터 Bedrock, Gemini, 그리고 모든 OpenAI 호환 게이트웨이까지.
• Codex 및 Claude Code용 코딩 에이전트 통합 — 호스트의 모델과 저장소 도구를 사용합니다.
• Grounded Claims — 중요한 사실을 버전이 있는 소스 증거(versioned source evidence)에 연결하고, 증거가 변경되면 이를 표면화합니다.
• 9가지 기본 제공 커넥터 — Custom MCP, Notion, Slack, Gmail, X, Web Search, Hacker News, LangSmith, 로컬 git 저장소용.
• 대화형 시각화 도구 — 모든 위키를 실시간으로 탐색 가능한 노드 그래프로 변환합니다.
• 자동 업데이트 — GitHub Actions, GitLab CI 또는 Bitbucket Pipelines를 통해.
• Open Knowledge Format(OKF v0.2) 출력 — 검증된 Mermaid 다이어그램 포함.

🎉 새로운 기능

• Grounded Claims: 코드 위키의 중요한 사실에는 이제 버전이 있는 소스 증거가 포함됩니다. 해당 증거가 변경되거나 사라지면 OpenWiki는 어떤 명제를 확인·재작성·폐기해야 하는지 정확히 알 수 있습니다.
• OpenWiki 통합: Codex 또는 Claude Code 내부에서 OpenWiki를 직접 실행합니다. 코딩 에이전트의 인증된 모델과 기본 저장소 도구를 사용하면서 OpenWiki가 문서 수명주기를 관리합니다.
• OKF v0.2: 모든 위키는 결정적 생성 출처(deterministic generation provenance)와 검증된 신뢰 및 수명주기 메타데이터를 갖춘 휴대용 Open Knowledge Format 번들입니다.
• 배포 가능한 시각화 도구: 대화형 그래프와 Markdown 리더를 GitHub Pages, MkDocs 또는 모든 정적 호스트에 배포할 수 있는 정적 사이트로 내보낼 수 있습니다.

빠른 시작

CLI 설치(Node.js 22 이상):

npm install -g openwiki

현재 저장소에 대한 위키를 생성합니다. 첫 실행 시 제공자(provider), 키, 모델을 선택하는 과정을 안내한 다음 openwiki/에 문서를 작성합니다:

openwiki --init

openwiki --init을 다시 실행하면 기존에 생성된 저장소 위키와 Claims를 완전히 새로운 생성 결과로 대체합니다. OpenWiki는 사용자가 작성한 openwiki/INSTRUCTIONS.md 브리프를 보존하며, 생성이 실패하거나 취소되면 이전 위키를 복원합니다.

위키가 변경될 때마다 문서 PR을 여는 예약 CI 작업을 추가하여 자동으로 최신 상태를 유지하세요:

• GitHub Actions: openwiki-update.yml을 .github/workflows/openwiki-update.yml로 복사합니다.
• GitLab CI: openwiki-update.gitlab-ci.yml을 .gitlab-ci.yml로 복사하거나 파이프라인에 포함합니다.
• Bitbucket Pipelines: openwiki-update.bitbucket-pipelines.yml을 bitbucket-pipelines.yml로 복사한 다음 openwiki-update 파이프라인을 예약합니다.

[!NOTE]

Windows에서는 Node.js 패키지 매니저(npm install -g openwiki 또는 pnpm add -g openwiki)로 설치하세요. bun으로 설치하면 better-sqlite3 네이티브 의존성을 컴파일하는 방식으로 대체될 수 있는데, 이 경우 C++ 데스크톱 개발 워크로드(Desktop development with C++)가 포함된 Visual Studio Build Tools가 필요합니다.

코딩 에이전트 통합

OpenWiki는 자체 모델을 실행하는 대신 기존 코딩 에이전트 내부에서 실행될 수 있습니다. 코딩 에이전트가 저장소를 조사하고 문서를 계획·작성하며, 유용할 때 기본 도구와 하위 에이전트(subagent)를 사용합니다. OpenWiki는 저장소를 준비하고 실행을 제약하며 인덱스, 출처(provenance), 설정 파일, 메타데이터를 결정적으로 확정하는 MCP 수명주기를 제공합니다.

코딩 에이전트용 통합을 설치합니다(하나 선택):

openwiki integrations install codex
openwiki integrations install claude

지원 대상은 Codex와 Claude Code입니다. 둘 다 기본적으로 사용자 수준으로 설치되므로 한 번 설치하면 모든 Git 저장소에서 사용할 수 있습니다. 프로젝트 경로는 해당 Git 저장소 루트로 확인됩니다. 설치 후 코딩 에이전트를 다시 시작하고 저장소를 연 다음 다음과 같이 요청하세요:

Initialize this repository's OpenWiki from the current source and tests.

기존 위키가 있다면 다음과 같이 요청하세요:

Update this repository's OpenWiki for changes since its last successful run.

호스트 기반 실행은 현재 개인 브레인(personal brain)이 아닌 저장소 코드 위키만 지원합니다. 코딩 에이전트의 인증된 모델 세션을 사용하므로 OpenWiki 제공자 자격 증명은 필요하지 않습니다. OpenWiki는 여전히 결정적 설정과 최종화를 담당하고, 코딩 에이전트는 조사, 계획, 사실 기반 작성, 의미론적 검토를 담당합니다.

외부 코딩 에이전트 통합은 현재 저장소 소스와 테스트만 사용합니다. LangSmith를 포함한 커넥터 기반 컨텍스트는 아직 지원되지 않습니다.

이 통합은 수명주기 시작/종료(bookends)와 Grounded Claims 검사 및 해결 기능을 제공합니다. Codex 또는 Claude가 기본 저장소 도구로 Markdown을 작성하는 동안 OpenWiki는 사실 페이지 뒤에 있는 증거 기반 명제를 검증하고 저장합니다.

openwiki integrations list로 사용자 수준 설치 상태를 확인하거나 openwiki integrations uninstall 로 통합을 안전하게 제거할 수 있습니다. 저장소 범위 상태를 보려면 list, install, uninstall에 --project [path]를 추가하세요.

다른 코딩 에이전트를 추가하는 기여자는 "Adding a coding-agent integration" 문서를 따라야 합니다.

Grounded Claims

OpenWiki는 사실 페이지 뒤에 있는 중요한 명제를 추적하여 코드 위키가 스스로 수정되도록 만듭니다. 단순히 Markdown 파일이 마지막으로 생성된 시점만 추적하는 것이 아닙니다. Claims는 미래 에이전트가 의존하는 진실(동작, 책임, 아키텍처, 데이터 흐름, 불변 조건, 실패 의미론, 구성, 보안 경계)을 다룹니다. 각 Claim은 repo://src/server.ts#L40-L82와 같은 정확한 저장소 증거를 가리키며, Claim이 수립될 당시 OpenWiki가 관찰한 증거 버전도 포함합니다.

업데이트 전에 OpenWiki는 해당 증거 버전을 확인합니다. 소스 줄이 변경되거나 사라지면 영향을 받는 Claim은 stale(오래됨) 또는 unresolved(미해결) 상태가 됩니다. 이 부채는 관련 페이지를 읽을 때까지 조용히 남아 있다가, 에이전트가 이를 검사하고 명제를 확인·수정·철회할 수 있습니다. Markdown은 깨끗하게 유지되며 구조화된 Claim 상태는 openwiki/.claims/ 아래에 함께 저장됩니다.

Grounded Claims는 현재 저장소 코드 위키와 저장소 증거에만 적용됩니다. LangSmith 전용 관찰을 포함한 커넥터 파생 사실은 Claim 대상이 아닙니다.

두 가지 모드

OpenWiki는 두 가지 모드 중 하나로 실행됩니다. 인자 없는 openwiki, openwiki --init, openwiki --update는 기본적으로 code 모드입니다. 개인 브레인을 사용하려면 personal 위치 인자(또는 --mode personal)를 추가하세요.

기본적으로 CLI는 실행 후에도 계속 열려 있어 후속 메시지를 보낼 수 있습니다. 일회성 비대화형 실행으로 최종 출력을 출력하고 종료하려면 -p / --print를 추가하세요. --init과 --update는 대화형 터미널에서 성공 시 자동으로 종료되므로 동일한 명령을 일회성 또는 대화형으로 사용할 수 있습니다.

로컬 상태 디렉터리

OpenWiki는 기본적으로 로컬 자격 증명, 개인 위키, 커넥터 데이터, 대화 기록, 스킬(skills)을 ~/.openwiki 아래에 저장합니다. 마운트된 컨테이너 볼륨과 같은 다른 쓰기 가능한 디렉터리를 사용하려면 OpenWiki를 시작하기 전에 OPENWIKICONFIGDIR을 설정하세요:

OPENWIKI_CONFIG_DIR=/data/openwiki openwiki personal --init

이 재정의는 별도의 상태 디렉터리를 선택합니다. OpenWiki는 기존 ~/.openwiki 디렉터리를 이동하거나 삭제하지 않습니다. 보존하려는 상태는 직접 복사하고, OpenWiki가 현재 사용자에 대해 권한을 제한하므로 변수를 전용 디렉터리로 지정하세요.

위키 탐색

모든 위키를 실시간 나란히 보이는 Markdown 리더가 있는 대화형 노드 그래프로 변환합니다:

openwiki visualize

이 명령은 ./openwiki을 로컬 루프백 주소(127.0.0.1, 네트워크에 노출되지 않음)로 서빙하고 브라우저에서 그래프를 엽니다. 서버가 실행되는 동안 위키 파일 편집은 자동으로 반영됩니다. 다른 디렉터리를 시각화하려면 경로를, 포트를 선택하려면 --port (충돌 시 포트가 증가하며 기본값은 4321)를, 브라우저를 열지 않으려면 --no-open을 전달하세요:

openwiki visualize openwiki --port 4400 --no-open

생성된 문서 옆에 시각화 도구를 게시하려면 서버를 시작하는 대신 정적 디렉터리로 내보내세요:

openwiki visualize openwiki --export docs/openwiki-visualizer

내보내기에는 index.html, client.js, client-lib.js, styles.css, graph.json이 포함됩니다. 클라이언트는 같은 디렉터리의 그래프 파일을 읽으며 라이브 리로드를 사용하지 않으므로 GitHub Pages, MkDocs 또는 다른 정적 호스트에서 호스팅할 수 있습니다. --export는 --port 또는 --no-open과 함께 사용할 수 없습니다.

[!NOTE]

페이지는 그래프, Markdown, 다이어그램 라이브러리를 공개 CDN에서 로드하므로 로컬 및 정적 뷰어 모두 인터넷 연결이 필요합니다.

소스 연결

personal 모드에서 OpenWiki는 이미 사용 중인 도구에서 지식을 수집하여 로컬 위키로 종합합니다. 첫 실행 온보딩에서는 Custom MCP, 로컬 git 저장소, Notion, Gmail, X/Twitter, Web Search, Hacker News 설정을 제공합니다. Slack도 OAuth 앱과 HTTPS 콜백을 구성하면 사용할 수 있습니다.

수집 실행 중에 결정적 커넥터 도구는 원시 데이터와 매니페스트를 ~/.openwiki/connectors//raw/ 아래에 작성한 다음, 소스별 에이전트 실행이 ~/.openwiki/wiki/ 아래에 위키를 종합합니다. 동일한 커넥터를 두 번 이상 구성할 수 있습니다(예: AI 연구용 Web Search 소스 하나와 NBA 뉴스용 소스 하나). OpenWiki는 이를 web-search-1, web-search-2와 같은 별도 인스턴스로 저장합니다.

openwiki auth notion        # 제공자에 대한 로컬 브라우저 OAuth 흐름 실행
openwiki ingest all         # 구성된 모든 소스 실행
openwiki ingest web-search  # 하나의 커넥터 소스 실행

커넥터 세부 정보 및 OAuth

• git-repo는 구성된 로컬 저장소 경로를 읽고 간결한 매니페스트를 작성합니다.
• custom-mcp는 구성된 모든 HTTP 또는 stdio MCP 서버에 연결하며 명시적으로 안전한 읽기 전용 도구만 허용합니다.
• x는 홈 타임라인, 사용자 게시물, 멘션, 북마크, 리스트 게시물에 대해 OAuth 사용자 컨텍스트 자격 증명으로 X API를 직접 사용합니다.
• notion은 호스팅된 Notion MCP 서버를 대상으로 하므로 토큰을 붙여넣는 대신 Notion OAuth로 인증합니다.
• google은 OAuth 사용자 자격 증명으로 Gmail API를 직접 사용하여 최근 메일을 가져옵니다.
• slack은 OAuth 사용자 및 봇 토큰으로 Slack Web API를 사용하여 범위가 지정된 대화와 검색 결과를 수집합니다.
• web-search는 LangChain을 통해 Tavily를 사용하며 TAVILYAPIKEY가 필요합니다.
• hackernews는 공개 Hacker News 피드와 검색 API를 사용하며 자격 증명이 필요 없습니다.

openwiki auth 는 로컬 브라우저 OAuth 흐름을 실행하고, 반환된 토큰을 ~/.openwiki/.env에 저장하며, 가능한 경우 커넥터 구성을 만들고 MCP 기반 제공자의 MCP 도구를 발견합니다. Slack과 Gmail은 해당 파일에 앱 클라이언트 자격 증명이 이미 설정되어 있어야 합니다. Notion은 호스팅 MCP에 동적 클라이언트 등록을 사용하고, X는 PKCE와 함께 OAuth 2.0을 사용합니다. openwiki auth configure 와 openwiki auth tools 는 고급 재시도 명령입니다.

커넥터 비밀값은 환경 변수 이름으로 참조되며 ~/.openwiki/.env에 저장됩니다. 커넥터 구성 파일에는 원시 비밀값이 절대 포함되지 않습니다.

Slack OAuth 터널. openwiki ngrok start는 무작위 HTTPS 전달 URL로 ngrok 터널을 시작하고, ngrok의 로컬 검사 API를 읽고, /callback을 추가하고, OPENWIKIHTTPSOAUTHREDIRECTURI를 자동으로 저장합니다. 출력된 콜백 URL을 Slack에 등록하세요.