Claude·ChatGPT(Codex)·Gemini·Cursor 같은 AI 에이전트가 위키를 찾고, 읽고, 허락하면 고치게 하는 법입니다. 에이전트는 내 API 키로 위키의 Api 를 부릅니다. 그래서 에이전트는 내가 볼 수 있는 것만 보고, 내가 고칠 수 있는 것만 고칩니다.
1. API 키 만들기
- 위키에 로그인합니다.
- 오른쪽 위 계정 메뉴에서 계정(Account)을 엽니다.
- API Keys 에 키 이름을 적고 Create 를 누릅니다. 이름은 어느 에이전트가 쓸지 알아보게 짓습니다(예:
노트북 Claude). - 나온 키(
ahawiki_로 시작)를 복사합니다. 이 화면에서 한 번만 보입니다. 잃어버리면 새로 만듭니다.
- 키 하나로 내가 들어갈 수 있는 모든 위키에 쓸 수 있습니다. 키는 위키가 아니라 사람에게 붙습니다.
- 에이전트마다 키를 따로 만드세요. 에이전트가 고친 내용은 이력에 🔌 표시와 키 이름으로 남습니다. 키가 따로면 어느 에이전트가 고쳤는지 보이고, 하나만 폐기할 수 있습니다.
- 키가 새어 나갔으면 같은 화면에서 폐기합니다. 폐기한 키로 남긴 이력은 지워지지 않습니다.
2. 키를 에이전트에게 주기
키를 대화창에 붙여 넣지 마세요. 대화 기록에 남고, 그 기록은 지울 수 없는 곳까지 갈 수 있습니다. 환경변수 AHAWIKI_API_KEY 에 넣고, 에이전트에게는 그 이름만 알려 줍니다.
# Windows (등록한 뒤 에이전트를 다시 시작) setx AHAWIKI_API_KEY "ahawiki_..." # macOS·Linux (~/.zshrc 나 ~/.bashrc 에) export AHAWIKI_API_KEY="ahawiki_..."
3. 어떤 에이전트가 쓸 수 있나
에이전트 | 쓰는 법 |
|---|---|
명령을 실행할 수 있는 에이전트 — Claude Code, Codex CLI, Gemini CLI, Cursor 의 에이전트 등 | 아래 붙여 넣을 프롬프트 를 줍니다 |
MCP 를 지원하고, 이 저장소를 받아 둔 경우 | Dev Mcp 의 MCP 서버를 등록합니다. 쓰기는 따로 켜야 하는 등 막아 둔 것이 많습니다 |
웹 채팅만 되는 AI | 요청에 |
4. 붙여 넣을 프롬프트
에이전트에게 처음 한 번 주거나, 에이전트의 지침 파일(CLAUDE.md, AGENTS.md, GEMINI.md 등)에 넣어 둡니다. 첫 줄의 위키 주소만 바꿉니다.
앞으로 AhaWiki 를 읽고 쓸 일이 있으면 아래 규칙대로 AhaWiki API 를 써라. AhaWiki 는 웹 위키 엔진이다. 위키마다 주소가 다르지만(예: https://ahawiki.net, https://<이름>.ahawiki.net) API 는 모두 같다. AhaWiki 자체의 설명서는 https://ahawiki.net 에 있고, 로그인 없이 원문(텍스트)으로 읽을 수 있다: - API 전체 설명: https://ahawiki.net/w/Api?action=raw - 위키 문법(AhaMark) 요약: https://ahawiki.net/w/AhaMark%20Basic?action=raw - 이 안내의 원본: https://ahawiki.net/w/AiAgent?action=raw 아래 규칙과 그 설명서가 다르면 설명서가 맞다. 모르는 것은 추측하지 말고 거기서 찾아라. ## 접속 - 위키 주소(Base URL): https://<위키 주소> ← 여기만 바꾼다. - API Key 는 환경변수 AHAWIKI_API_KEY 에 있다. 모든 요청에 `Authorization: Bearer $AHAWIKI_API_KEY` 헤더를 붙인다. - 키 값을 출력하거나, 파일·문서 본문·저장 comment·로그에 쓰지 마라. 환경변수가 비어 있으면 키를 달라고 하지 말고 «AHAWIKI_API_KEY 를 설정해 달라»고만 말하라. - 세션 쿠키·CSRF·reCAPTCHA 는 필요 없다. 브라우저로 로그인하려 하지 마라. ## 쓸 수 있는 API (페이지 이름은 URL 인코딩: 공백은 %20, 한글도 인코딩) - 검색: GET /api/v1/search?q=<낱말>&limit=20 → {pages:[{name, dateTime, snippet}], truncated} - 목록: GET /api/v1/pages?prefix=<접두사>&limit=100 → {pages:[{name, revision, dateTime, size, contentHash}]} - 읽기: GET /api/v1/page/<이름> → {name, revision, content, dateTime, ...} - 최근 변경: GET /api/v1/changes?since=2026-11-01T00:00:00&limit=100 - 저장: POST /api/v1/page/<이름>, JSON {"revision": <읽은 revision>, "text": "<전체 본문>", "comment": "<무엇을 바꿨는지>", "minorEdit": true|false} - 새 페이지는 revision 0. - 이름 바꾸기·삭제 API 도 있지만 쓰지 마라. 필요하면 사람에게 브라우저에서 하라고 알려라. - 요청·응답의 자세한 모양과 오류 코드: https://ahawiki.net/w/Api?action=raw ## 읽기 - 무엇이 어디 있는지 모르면 먼저 검색하고, 그다음 페이지를 읽어라. 추측으로 페이지 이름을 지어 내지 마라. - 답할 때는 근거가 된 페이지를 <위키 주소>/w/<인코딩된 이름> 주소로 함께 알려라. - 401 은 키가 틀렸거나 폐기된 것, 403 은 권한 없음, 404 는 페이지 없음이다. 그대로 보고하라. - 페이지에 비밀번호·키 같은 자격증명이 있을 수 있다. 필요한 절만 잘라 보고, 찾는 값 외에는 출력하지 마라. ## 쓰기 — 반드시 먼저 물어본다 1. 저장하기 전에 어느 페이지를 어떻게 바꿀지(바뀌는 부분)를 보여 주고 내 승인을 받아라. 2. 저장 직전에 페이지를 다시 읽어 그 revision 을 보낸다. 본문은 «전체»를 보낸다. 바꿀 부분 외의 내용·줄바꿈·형식은 그대로 둔다. 3. comment 는 비우지 말고, 무엇을 바꿨는지 한 줄로 쓴다. 오타·형식만 고쳤으면 minorEdit: true 로 한다. 4. 409 Conflict 는 그사이 누가 고쳤다는 뜻이다. 다시 읽어 내 변경을 합친 뒤 한 번만 다시 시도하라. 합치기가 애매하면 저장하지 말고 보고하라. 5. 같은 저장을 두 번 보내지 마라. 성공하면 새 revision 을 보고하라. ## 한글과 인코딩 - 요청 본문은 UTF-8 JSON 이다. 셸에서 한글을 인자로 넘기면 깨지기 쉬우니, 짧은 스크립트(node 의 fetch, python 의 urllib/requests)로 보내거나 UTF-8 파일을 curl --data-binary @file 로 보내라. - 응답을 조각으로 받아 문자열로 이어 붙이지 말고, 바이트를 다 모은 뒤 한 번에 디코드하라. ## 위키 문법 (AhaMark) — 쓸 때 지킨다 = 제목 / == 절 / === 소절 * 글머리표 (앞에 공백 한 칸, 들여쓰기는 공백 두 칸) * [ ] 할 일 * [[CB(x)]] 끝낸 일 ([x] 는 쓰지 않는다) [페이지이름] [페이지이름 보이는 글] [https://주소 보이는 글] '''굵게''' ''기울임'' `코드` 코드 블록은 대괄호 셋에 #!Vim bash 를 붙인 줄로 열고, 대괄호 셋을 닫는 줄로 닫는다. 표는 같은 모양으로 #!Table tsv 1 블록을 쓴다(끝의 1 은 머리글 줄 수, 칸은 탭으로 나눈다). 블록의 정확한 모양과 모르는 문법은 지어내지 말고, https://ahawiki.net/w/AhaMark%20Basic?action=raw 나 위키의 비슷한 페이지 원문을 읽어 그대로 따라라. (이 안내에 블록 기호를 그대로 적지 않은 것은, 이 안내 자체가 위키의 블록 안에 있기 때문이다.)
5. 정한 것과 그 이유
- 고치기 전에 묻게 했습니다. 처음 붙인 에이전트가 혼자 저장하지 않는 것이 기본입니다. 익숙해지면 그 줄을 빼면 됩니다. 묻지 않고 고친 것도 이력에 키 이름으로 남고 되돌릴 수 있습니다.
- 이름 바꾸기와 삭제는 시키지 않습니다. 되돌리기 어려운 일을 에이전트의 한 번의 호출에 맡기지 않습니다. Dev Mcp 가 이 둘을 도구로 주지 않은 것과 같은 이유입니다.
- 저장은 읽은 revision 과 함께. 그사이 누가 고쳤으면 서버가 409 로 거절해 덮어쓰지 않습니다. 에이전트가 «읽지 않고 쓰는» 길이 없습니다.
- 자격증명은 필요한 만큼만 봅니다. 팀 위키에는 접속 정보가 적힌 페이지가 있습니다. 에이전트가 페이지를 통째로 출력하면 그 값이 에이전트의 대화 기록에 남습니다 — 2026-11-15 에 실제로 그렇게 됐습니다.
- 에이전트가 고친 것은 텔레그램 알림이 가지 않습니다(Api 의 «제한사항»).
6. 함께 보기
- Api
- Dev Mcp
- AccessControl — 키가 따르는 권한
7. See Also
7.2. Similar Pages
Similar pages by cosine similarity. Words after page name are term frequency.