docs: add Korean localization and KakaoWork channel docs

- Add KakaoWork channel documentation (docs/channels/kakao.md) - Add Korean getting started guide (docs/ko/start/getting-started.md) - Add Korean documentation index (docs/ko/index.md) This is the first step toward i18n support for Korean users. Addresses #2926 and #2794. Contributed-by: Hanish Keloth <hanishkeloth@users.noreply.github.com>
2026-01-28 15:45:37 +09:00 · 2026-01-28 15:45:37 +09:00 · ca7ab9a3c7
commit ca7ab9a3c7
parent 6044bf3637
3 changed files with 455 additions and 0 deletions
--- a/docs/channels/kakao.md
+++ b/docs/channels/kakao.md
@ -0,0 +1,187 @@
+---
+title: KakaoWork
+description: Connect Moltbot to KakaoWork for Korea-focused enterprise messaging
+---
+
+# KakaoWork
+
+Connect Moltbot to [KakaoWork](https://www.kakaowork.com/), Korea's leading enterprise messaging platform.
+
+<Note>
+KakaoWork is available as a third-party plugin. Install with:
+```bash
+moltbot plugins install @hanishkeloth/moltbot-kakao
+```
+</Note>
+
+## Features
+
+- Direct message conversations via KakaoWork Bot API
+- Reactive callback handling for button interactions
+- Multi-account configuration support
+- Pairing-based DM access control
+- Rate limit aware (200 req/min workspace limit)
+
+## Prerequisites
+
+1. KakaoWork workspace admin access
+2. Bot created in [KakaoWork Admin Console](https://admin.kakaowork.com)
+3. Bot App Key
+
+## Getting Your App Key
+
+1. Go to [KakaoWork Admin Console](https://admin.kakaowork.com)
+2. Navigate to **봇 관리** (Bot Management)
+3. Click **봇 추가** (Add Bot) or select existing bot
+4. Copy the **App Key** from bot settings
+
+## Installation
+
+```bash
+moltbot plugins install @hanishkeloth/moltbot-kakao
+```
+
+## Configuration
+
+### Using Environment Variable
+
+```bash
+export KAKAOWORK_APP_KEY="your-app-key-here"
+```
+
+### Using Config File
+
+Add to `~/.config/moltbot/config.jsonc`:
+
+```jsonc
+{
+  "channels": {
+    "kakao": {
+      "enabled": true,
+      "appKey": "your-app-key-here",
+      "dmPolicy": "pairing"
+    }
+  }
+}
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `appKey` | string | - | Bot App Key from KakaoWork admin |
+| `keyFile` | string | - | Path to file containing app key |
+| `callbackUrl` | string | - | HTTPS URL for reactive events |
+| `callbackPath` | string | - | Gateway HTTP path for callbacks |
+| `dmPolicy` | string | `"pairing"` | Access policy (see below) |
+| `allowFrom` | array | `[]` | User IDs allowed to DM the bot |
+| `proxy` | string | - | Proxy URL for API requests |
+
+## DM Policies
+
+| Policy | Description |
+|--------|-------------|
+| `pairing` | Users must pair with a code before chatting (default) |
+| `allowlist` | Only users in `allowFrom` list can chat |
+| `open` | Anyone in workspace can chat |
+| `disabled` | DMs are disabled |
+
+## Multi-Account Setup
+
+For multiple KakaoWork bots:
+
+```jsonc
+{
+  "channels": {
+    "kakao": {
+      "enabled": true,
+      "accounts": {
+        "support": {
+          "appKey": "SUPPORT_BOT_APP_KEY",
+          "dmPolicy": "open"
+        },
+        "internal": {
+          "appKey": "INTERNAL_BOT_APP_KEY",
+          "dmPolicy": "allowlist",
+          "allowFrom": ["12345", "67890"]
+        }
+      },
+      "defaultAccount": "support"
+    }
+  }
+}
+```
+
+## Callback URL (Reactive Events)
+
+To receive button interactions and modal submissions:
+
+1. Set up HTTPS endpoint (use ngrok for testing)
+2. Configure callback URL:
+
+```jsonc
+{
+  "channels": {
+    "kakao": {
+      "callbackUrl": "https://your-domain.com/kakao/callback",
+      "callbackPath": "/kakao/callback"
+    }
+  }
+}
+```
+
+3. Register the callback URL in KakaoWork Admin Console
+
+## Sending Messages
+
+```bash
+# Send to conversation ID
+moltbot message send --channel kakao --to 123456789 --message "Hello!"
+
+# Using the agent
+moltbot agent --message "Say hello" --channel kakao
+```
+
+## Pairing Flow
+
+When `dmPolicy: "pairing"` (default):
+
+1. User sends message to bot
+2. Bot replies with pairing code
+3. Admin approves: `moltbot pairing approve kakao <user-id>`
+4. User can now chat freely
+
+## Rate Limits
+
+KakaoWork enforces **200 requests per minute** at the workspace level. The plugin handles rate limiting automatically, but be aware when sending bulk messages.
+
+## Troubleshooting
+
+### "Invalid authentication" error
+- Check your App Key is correct
+- Verify bot is activated in KakaoWork Admin
+
+### Messages not sending
+- Ensure bot has permission to message the user
+- Check if rate limit (200/min) is exceeded
+- Verify conversation exists (use `conversations.open` first)
+
+### Callback not receiving events
+- Callback URL must be HTTPS
+- Check firewall allows incoming connections
+- Verify callback URL registered in KakaoWork Admin
+
+## API Reference
+
+This plugin uses the [KakaoWork Web API](https://docs.kakaoi.ai/kakao_work/webapireference/):
+
+- `bots.info` - Get bot information
+- `conversations.open` - Create/open DM conversations
+- `conversations.list` - List bot conversations
+- `messages.send` - Send messages
+
+## Links
+
+- [KakaoWork Developer Docs](https://docs.kakaoi.ai/kakao_work/)
+- [Plugin Repository](https://github.com/hanishkeloth/moltbot-kakao)
+- [npm Package](https://www.npmjs.com/package/@hanishkeloth/moltbot-kakao)
--- a/docs/ko/index.md
+++ b/docs/ko/index.md
@ -0,0 +1,37 @@
+---
+title: 한국어 문서
+description: Moltbot 한국어 문서
+---
+
+# Moltbot 한국어 문서
+
+Moltbot은 WhatsApp, Telegram, Discord, Slack, KakaoWork 등 다양한 채널에서 작동하는 개인 AI 어시스턴트입니다.
+
+## 시작하기
+
+- [시작하기 가이드](/ko/start/getting-started) - 설치부터 첫 메시지까지
+
+## 한국 사용자를 위한 채널
+
+| 채널 | 설명 | 설치 |
+|------|------|------|
+| [KakaoWork](/channels/kakao) | 카카오워크 기업 메시징 | `moltbot plugins install @hanishkeloth/moltbot-kakao` |
+| [LINE](/channels/line) | 라인 메시징 API | `moltbot plugins install @moltbot/line` |
+| [Telegram](/channels/telegram) | 텔레그램 봇 API | 기본 포함 |
+
+## 유용한 링크
+
+- [공식 웹사이트](https://molt.bot)
+- [영어 문서](https://docs.molt.bot)
+- [GitHub](https://github.com/moltbot/moltbot)
+- [Discord 커뮤니티](https://discord.gg/clawd)
+
+## 기여하기
+
+한국어 문서 개선에 기여하고 싶으시면:
+
+1. GitHub에서 저장소를 포크하세요
+2. `docs/ko/` 폴더에서 문서를 추가/수정하세요
+3. Pull Request를 제출하세요
+
+번역 문의: [GitHub Issues](https://github.com/moltbot/moltbot/issues)
--- a/docs/ko/start/getting-started.md
+++ b/docs/ko/start/getting-started.md
@ -0,0 +1,231 @@
+---
+summary: "초보자 가이드: 설치부터 첫 메시지까지 (설정 마법사, 인증, 채널, 페어링)"
+read_when:
+  - 처음 설치하는 경우
+  - 설치 → 온보딩 → 첫 메시지까지 가장 빠른 방법을 원하는 경우
+---
+
+# 시작하기
+
+목표: **설치**부터 **첫 번째 채팅**까지 가능한 빠르게 진행합니다.
+
+가장 빠른 채팅: Control UI를 열어보세요 (채널 설정 불필요). `moltbot dashboard`를 실행하고
+브라우저에서 채팅하거나, 게이트웨이 호스트에서 `http://127.0.0.1:18789/`를 열어보세요.
+문서: [Dashboard](/web/dashboard) 및 [Control UI](/web/control-ui).
+
+권장 방법: **CLI 온보딩 마법사** (`moltbot onboard`) 사용. 다음을 설정합니다:
+- 모델/인증 (OAuth 권장)
+- 게이트웨이 설정
+- 채널 (WhatsApp/Telegram/Discord/KakaoWork/...)
+- 페어링 기본값 (보안 DM)
+- 워크스페이스 부트스트랩 + 스킬
+- 선택적 백그라운드 서비스
+
+더 자세한 참조 페이지: [Wizard](/start/wizard), [Setup](/start/setup), [Pairing](/start/pairing), [Security](/gateway/security).
+
+## 0) 사전 요구사항
+
+- Node `>=22`
+- `pnpm` (선택사항; 소스에서 빌드하는 경우 권장)
+- **권장:** 웹 검색을 위한 Brave Search API 키.
+  `moltbot configure --section web` 실행 (`tools.web.search.apiKey` 저장).
+  [Web tools](/tools/web) 참조.
+
+macOS: 앱을 빌드하려면 Xcode / CLT를 설치하세요. CLI + 게이트웨이만 사용하려면 Node만 있으면 됩니다.
+Windows: **WSL2** (Ubuntu 권장) 사용. WSL2를 먼저 설치한 후 WSL 내에서 Linux 단계를 실행하세요. [Windows (WSL2)](/platforms/windows) 참조.
+
+## 1) CLI 설치 (권장)
+
+```bash
+curl -fsSL https://molt.bot/install.sh | bash
+```
+
+설치 옵션 (설치 방법, 비대화형, GitHub에서): [Install](/install).
+
+Windows (PowerShell):
+
+```powershell
+iwr -useb https://molt.bot/install.ps1 | iex
+```
+
+대안 (전역 설치):
+
+```bash
+npm install -g moltbot@latest
+```
+
+```bash
+pnpm add -g moltbot@latest
+```
+
+## 2) 온보딩 마법사 실행 (서비스 설치 포함)
+
+```bash
+moltbot onboard --install-daemon
+```
+
+선택 항목:
+- **로컬 vs 원격** 게이트웨이
+- **인증**: OpenAI Code (Codex) 구독 (OAuth) 또는 API 키. Anthropic의 경우 API 키를 권장합니다.
+- **제공자**: WhatsApp QR 로그인, Telegram/Discord 봇 토큰, KakaoWork 앱 키 등
+- **데몬**: 백그라운드 설치 (launchd/systemd; WSL2는 systemd 사용)
+  - **런타임**: Node (권장; WhatsApp/Telegram에 필요). Bun은 **권장하지 않음**.
+- **게이트웨이 토큰**: 마법사가 기본적으로 생성하고 `gateway.auth.token`에 저장합니다.
+
+마법사 문서: [Wizard](/start/wizard)
+
+### 인증: 저장 위치 (중요)
+
+- **권장 Anthropic 경로:** API 키 설정 (마법사가 서비스용으로 저장 가능).
+
+- OAuth 자격 증명 (레거시 가져오기): `~/.clawdbot/credentials/oauth.json`
+- 인증 프로필 (OAuth + API 키): `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`
+
+헤드리스/서버 팁: 일반 머신에서 먼저 OAuth를 수행한 후 `oauth.json`을 게이트웨이 호스트로 복사하세요.
+
+## 3) 게이트웨이 시작
+
+온보딩 중 서비스를 설치했다면, 게이트웨이가 이미 실행 중이어야 합니다:
+
+```bash
+moltbot gateway status
+```
+
+수동 실행 (포그라운드):
+
+```bash
+moltbot gateway --port 18789 --verbose
+```
+
+대시보드 (로컬 루프백): `http://127.0.0.1:18789/`
+토큰이 구성된 경우 Control UI 설정에 붙여넣으세요 (`connect.params.auth.token`으로 저장됨).
+
+⚠️ **Bun 경고 (WhatsApp + Telegram):** Bun은 이러한 채널에서 알려진 문제가 있습니다.
+WhatsApp 또는 Telegram을 사용하는 경우 **Node**로 게이트웨이를 실행하세요.
+
+## 3.5) 빠른 확인 (2분)
+
+```bash
+moltbot status
+moltbot health
+moltbot security audit --deep
+```
+
+## 4) 첫 번째 채팅 표면 페어링 + 연결
+
+### WhatsApp (QR 로그인)
+
+```bash
+moltbot channels login
+```
+
+WhatsApp → 설정 → 연결된 기기에서 스캔하세요.
+
+WhatsApp 문서: [WhatsApp](/channels/whatsapp)
+
+### Telegram / Discord / KakaoWork / 기타
+
+마법사가 토큰/설정을 작성할 수 있습니다. 수동 설정을 선호하는 경우:
+- Telegram: [Telegram](/channels/telegram)
+- Discord: [Discord](/channels/discord)
+- KakaoWork: [KakaoWork](/channels/kakao)
+
+**Telegram DM 팁:** 첫 번째 DM은 페어링 코드를 반환합니다. 승인하세요 (다음 단계 참조) 그렇지 않으면 봇이 응답하지 않습니다.
+
+## 5) DM 안전 (페어링 승인)
+
+기본 태세: 알 수 없는 DM은 짧은 코드를 받고 승인될 때까지 메시지가 처리되지 않습니다.
+첫 번째 DM에 응답이 없으면 페어링을 승인하세요:
+
+```bash
+moltbot pairing list whatsapp
+moltbot pairing approve whatsapp <code>
+```
+
+페어링 문서: [Pairing](/start/pairing)
+
+## 소스에서 (개발)
+
+Moltbot 자체를 해킹하려면 소스에서 실행하세요:
+
+```bash
+git clone https://github.com/moltbot/moltbot.git
+cd moltbot
+pnpm install
+pnpm ui:build # 첫 실행 시 UI 종속성 자동 설치
+pnpm build
+moltbot onboard --install-daemon
+```
+
+전역 설치가 없는 경우 이 저장소에서 `pnpm moltbot ...`를 통해 온보딩 단계를 실행하세요.
+
+게이트웨이 (이 저장소에서):
+
+```bash
+node moltbot.mjs gateway --port 18789 --verbose
+```
+
+## 7) 종단 간 확인
+
+새 터미널에서 테스트 메시지를 보내세요:
+
+```bash
+moltbot message send --target +15555550123 --message "Moltbot에서 보낸 안녕하세요"
+```
+
+`moltbot health`에서 "no auth configured"가 표시되면 마법사로 돌아가 OAuth/키 인증을 설정하세요 — 인증 없이는 에이전트가 응답할 수 없습니다.
+
+팁: `moltbot status --all`은 가장 좋은 붙여넣기 가능한 읽기 전용 디버그 보고서입니다.
+상태 프로브: `moltbot health` (또는 `moltbot status --deep`)는 실행 중인 게이트웨이에 상태 스냅샷을 요청합니다.
+
+## 다음 단계 (선택사항이지만 좋음)
+
+- macOS 메뉴 바 앱 + 음성 웨이크: [macOS app](/platforms/macos)
+- iOS/Android 노드 (Canvas/카메라/음성): [Nodes](/nodes)
+- 원격 액세스 (SSH 터널 / Tailscale Serve): [Remote access](/gateway/remote) 및 [Tailscale](/gateway/tailscale)
+- 상시 가동 / VPN 설정: [Remote access](/gateway/remote), [exe.dev](/platforms/exe-dev), [Hetzner](/platforms/hetzner), [macOS remote](/platforms/mac/remote)
+
+---
+
+## 한국 사용자를 위한 채널
+
+한국에서 Moltbot을 사용하는 경우 다음 채널을 권장합니다:
+
+### KakaoWork (카카오워크)
+
+기업용 메시징 플랫폼. 플러그인 설치:
+
+```bash
+moltbot plugins install @hanishkeloth/moltbot-kakao
+```
+
+설정:
+```jsonc
+{
+  "channels": {
+    "kakao": {
+      "enabled": true,
+      "appKey": "카카오워크_앱_키",
+      "dmPolicy": "pairing"
+    }
+  }
+}
+```
+
+문서: [KakaoWork](/channels/kakao)
+
+### LINE (라인)
+
+일본/대만/태국 시장을 위한 메시징 API:
+
+```bash
+moltbot plugins install @moltbot/line
+```
+
+문서: [LINE](/channels/line)
+
+### Telegram (텔레그램)
+
+한국에서도 인기 있는 메시징 앱:
+
+문서: [Telegram](/channels/telegram)