created by Aha00aAha00a at 2026-11-15
last modified by Aha00aAha00a at 2026-11-15
revision: 3

AiAgent

Claude·ChatGPT(Codex)·Gemini·Cursor 같은 AI 에이전트가 위키를 찾고, 읽고, 허락하면 고치게 하는 법입니다. 에이전트는 내 API 키로 위키의 Api 를 부릅니다. 그래서 에이전트는 내가 볼 수 있는 것만 보고, 내가 고칠 수 있는 것만 고칩니다.

문서

읽는 사람

담는 것

이 문서

에이전트를 붙이려는 사용자

키 만들기, 에이전트에게 주는 법, 붙여 넣을 프롬프트

API 를 직접 부르는 도구와 그 개발자

주소, 요청·응답 모양, 오류 코드

이 저장소로 작업하는 개발자

MCP 서버를 왜 그렇게 만들었는지

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

요청에 Authorization 헤더를 붙일 수 없어 쓸 수 없습니다

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. 함께 보기

7. See Also

7.2. Similar Pages

Similar pages by cosine similarity. Words after page name are term frequency.

  • 62.83% Api api(28:86), key(7:33), ahawiki(16:13), revision(8:16), 페이지(4:20), page(2:21), v1(5:16), name(3:17), aha(8:10), net(8:10)
  • 55.41% Dev Mcp api(28:10), ahawiki(16:13), mcp(7:13), 에이전트가(10:3), revision(8:3), key(7:3), 위키(7:3), aha(8:1), 같은(6:3), v1(5:3)
  • 53.84% Dev Api api(28:150), key(7:85), page(2:34), aha(8:19), wiki(4:22), v1(5:20), get(4:15), name(3:16), 않는다(1:18), ahawiki(16:1)
  • 42.65% Dev ApiControllers api(28:34), 에이전트가(10:1), key(7:3), 같은(6:4), 있습니다(5:5), 페이지(4:6), revision(8:1), 위키(7:2), dev(4:5), wiki(4:5)
  • 34.60% Dev ApiResponse api(28:42), json(2:42), ahawiki(16:4), revision(8:10), get(4:10), aha(8:5), 같은(6:7), page(2:10), wiki(4:7), v1(5:5)
  • 33.77% Dev Page page(2:89), api(28:23), wiki(4:43), 페이지(4:40), revision(8:27), 같은(6:27), 다시(4:20), name(3:21), aha(8:15), 페이지를(5:17)
  • 32.12% Setup api(28:10), ahawiki(16:21), net(8:19), wiki(4:13), aha(8:8), 같은(6:7), 있는(5:6), page(2:9), captcha(1:10), 위키(7:3)
  • 31.01% MacroInclude api(28:3), aha(8:12), ahawiki(16:3), wiki(4:12), 위키(7:7), net(8:3), 같은(6:5), 있는(5:6), revision(8:1), raw(5:4)

7.3. Adjacent Pages

≤ 32
all
1.0x
1.0x
80
-120
ON
0/0
0/0
0.00
0
0 / 0
1.00x