docs: AI 연동 설정 문서 추가 (docs/ai-integration.md)

docs/ai-integration.md

@@ -0,0 +1,82 @@
+# AI 연동 설정
+
+## 글 작성 (Writer)
+
+### 우선순위 (Fallback 순서)
+1. **Claude Opus 4.6** (Primary) — cliproxy 프록시 경유
+2. **Gemini 2.5 Flash** (Fallback 1) — Google AI API 직접 호출
+3. **Groq llama-3.3-70b** (Fallback 2) — Groq API 직접 호출
+
+Primary가 실패하거나 빈 응답이면 자동으로 다음 순서로 전환됩니다.
+
+### 설정 파일
+`config/engine.json`
+
+```json
+"writing": {
+  "provider": "claude",
+  "fallback_chain": ["gemini", "groq"],
+  "options": {
+    "claude": {
+      "api_key_env": "ANTHROPIC_API_KEY",
+      "base_url": "http://192.168.0.17:8317/api/provider/claude",
+      "model": "claude-opus-4-6",
+      "max_tokens": 4096,
+      "temperature": 0.7
+    },
+    "gemini": {
+      "api_key_env": "GEMINI_API_KEY",
+      "model": "gemini-2.5-flash",
+      "max_tokens": 4096,
+      "temperature": 0.7
+    },
+    "groq": {
+      "api_key_env": "GROQ_API_KEY",
+      "model": "llama-3.3-70b-versatile",
+      "max_tokens": 4096,
+      "temperature": 0.7
+    }
+  }
+}
+```
+
+### 환경변수 (.env)
+
+| 변수명 | 설명 |
+|--------|------|
+| `ANTHROPIC_API_KEY` | cliproxy API 키 (`Jinie4eva!`) |
+| `ANTHROPIC_BASE_URL` | cliproxy 내부 URL (`http://192.168.0.17:8317/api/provider/claude`) |
+| `GEMINI_API_KEY` | Google AI API 키 |
+| `GROQ_API_KEY` | Groq API 키 |
+
+---
+
+## cliproxy 설정
+
+- **서비스**: NAS에서 Docker 컨테이너로 실행 (`CLIProxyAPI`)
+- **내부 포트**: `8317`
+- **외부 도메인**: `cliproxy.gru.farm`
+- **내부 접근 URL**: `http://192.168.0.17:8317`
+
+> **주의**: NAS 컨테이너에서 `cliproxy.gru.farm`(외부 도메인)으로 호출하면 헤어핀 NAT 문제로 401 오류가 발생합니다. 반드시 내부 IP(`192.168.0.17:8317`)로 연결해야 합니다.
+
+---
+
+## 텔레그램 대화 기능
+
+텔레그램에서 봇에게 말을 걸면 Claude Opus 4.6으로 응답합니다.
+Fallback 없이 Claude 단독 사용 (글 작성과 별개).
+
+- **모델**: `claude-opus-4-6`
+- **호출 경로**: `ANTHROPIC_BASE_URL` → cliproxy → Claude
+- **구현 위치**: `bots/scheduler.py` → `handle_message()`
+
+---
+
+## 구현 위치
+
+| 기능 | 파일 |
+|------|------|
+| Writer 클래스 (Claude/Gemini/Groq/Fallback) | `bots/engine_loader.py` |
+| 글 작성 호출 | `bots/scheduler.py` → `_call_openclaw()` |
+| 텔레그램 대화 | `bots/scheduler.py` → `handle_message()` |