# OpenClaw 외부 문서 보관소

OpenClaw 워크스페이스에서 참조하는 외부 공급사·서비스·플랫폼 공식 문서를 모아두는 곳. 모든 에이전트(클로·레이·골디·코디)가 공유하는 단일 진실 공급원.

## 운영 원칙

- **하위 폴더 만들지 않는다.** 모든 문서는 `docs/` 직속에 둔다. 분류는 이 README.md 의 카탈로그로.
- **새 문서 추가 시 이 README.md 의 "카탈로그" 섹션에 한 줄 등록.** 제목·용도·관련 에이전트·관련 코드 위치.
- **외부에서 받은 PDF/문서를 그대로 보관.** 가공·요약본은 별도 메모리 파일로 정리하고, 원본은 그대로.
- **버전 갱신 시 파일명에 날짜 suffix 또는 그대로 덮어쓰기.** 큰 변화면 옛 버전을 `archive/` 같은 폴더 대신 `이름_YYYY-MM-DD.pdf` 처럼 명시.

## 카탈로그

### `키움 REST API 문서.pdf`

- **공급사:** 키움증권
- **용도:** 키움 OpenAPI(REST) 명세서. TR_ID 별 endpoint URL, request body·response field, 예시.
- **버전:** 2026-09-10 사이트 다운로드본 (870쪽, API 347개 = OAuth 2 + 국내주식 210 + 미국주식 135). 직전본은 2026-05-07(528쪽·207개, 국내+OAuth만)
- **관련 에이전트:** 레이(stock) — 매매·조회 모든 키움 호출의 단일 진실 공급원
- **관련 코드:** (실제 호출 TR)
  - `scripts/kiwoom_client.py` — 조회 공용 클라이언트 (ka10001/ka10004/ka10023/ka10059/ka10075/ka10080/ka10081/ka10095/ka10099/ka10170/ka90009/kt00001/kt00004/kt00007/kt00015/kt00016/kt00018)
  - `scripts/orders/kiwoom_order.py` — 매수/매도·정정·취소 (kt10000/kt10001/kt10002/kt10003), `orders/datasource.py` 호가(ka10004), `orders/guards.py`·`orders/handler.py`·`orders/fill_watcher.py` (ka10075/ka10099/kt00007)
  - `scripts/realtime_hub.py` — WebSocket 실시간 (0B 주식체결 / 1h VI발동·해제)
  - `scripts/investment_principal.py` (kt00015/kt00016/kt00018), `scripts/surge_monitor.py`·`scripts/trailing_monitor.py`, `sim/` (ka10023/ka10059/ka10081/ka90009)
- **관련 메모리:**
  - 코디: `~/.claude/projects/-Users-snowoyh--openclaw/memory/reference_kiwoom_endpoints.md`, `reference_kiwoom_doc_freshness_check.md`(최신성 대조법)
  - 레이: `agents/stock/workspace/memory/orders_module.md`, `2026-05-07-kiwoom-api-audit.md`
- **새 TR 추가 절차:**
  1. PDF 목차에서 TR_ID 페이지 번호 확인
  2. 해당 페이지에서 "URL" 필드 확인 → endpoint 결정 (`acnt`/`stkinfo`/`mrkcond`/`ordr`/`chart`/`rkinfo`)
  3. 응답 필드명 그대로 매핑 (suffix 패턴 추측 금지 — 2026-05-07 ka10004 사고)
  4. 가격·수량 필드는 `+/-` 부호 가능 — `abs()` 처리 검토
- **최신성 확인:** 문서 안에 개정일자가 없다(jsPDF 클라이언트 생성물). 사이트 가이드 페이지를 GET으로 긁어 대조하는 절차는 코디 메모리 `reference_kiwoom_doc_freshness_check.md` 참조. 공식 PDF/JSON 다운로드 버튼은 WAF 차단이라 자동화 불가 — 갱신은 관리자님이 브라우저에서 직접
- **마지막 검증:** 2026-09-10 — 사이트 목록 347개 ↔ PDF 수록 347개 전수 일치, 우리가 쓰는 21개 TR + 실시간 0B·1h 필드 대조 완료(구본 대비 변경은 kt00015 선택 파라미터 `qry_sort_tp` 추가 1건뿐)

## 변경 이력

- 2026-05-07 — `docs/` 폴더 신규, 키움 REST API PDF 입주
- 2026-09-10 — 키움 REST API PDF 갱신(2026-05-07 → 2026-09-10). 미국주식 135개 신규 수록, 국내 6개 추가·`ka10009` 삭제, `kt00015` 에 `qry_sort_tp` 추가. 기존 호출부 영향 없음