35ba7cb5ba
- Source: setup/service.ts, runners.ts, agent-runner.ts error messages - Scripts: restart-stack.sh, run-migrations.ts → bun - Bootstrap: setup.sh check_node→check_bun, npm install→bun install - Docs: CLAUDE.md, README.md, all SKILL.md files - Tests: service.test.ts, restart-stack.test.ts expectations updated
92 lines
3.1 KiB
Markdown
92 lines
3.1 KiB
Markdown
---
|
|
name: debug
|
|
description: Debug EJClaw runtime issues on the current Discord-only, host-process architecture.
|
|
---
|
|
|
|
# EJClaw Debugging
|
|
|
|
현재 기준 EJClaw는 디스코드 전용이고, 에이전트는 컨테이너가 아니라 호스트 프로세스로 실행됩니다. 디버깅은 `채널`, `서비스`, `러너`, `DB 등록`, `자격 증명` 순서로 좁혀갑니다.
|
|
|
|
## 빠른 점검 순서
|
|
|
|
1. 타입과 테스트부터 확인
|
|
```bash
|
|
bun run typecheck
|
|
bun test
|
|
```
|
|
2. 서비스 상태 확인
|
|
```bash
|
|
bun run setup -- --step verify
|
|
```
|
|
3. 런타임 로그 확인
|
|
```bash
|
|
tail -f logs/ejclaw.log
|
|
tail -f logs/ejclaw.error.log
|
|
ls -t groups/*/logs/agent-*.log | head
|
|
```
|
|
4. 러너 빌드 확인
|
|
```bash
|
|
bun run build:runners
|
|
```
|
|
|
|
## 핵심 파일
|
|
|
|
- `src/index.ts` - 메시지 루프, 세션 명령, 라우팅
|
|
- `src/channels/discord.ts` - 디스코드 수신/송신, 멘션, 첨부파일, 음성 전사
|
|
- `src/agent-runner.ts` - 러너 실행, 환경 변수 전달, 워크디렉터리 처리
|
|
- `runners/agent-runner/src/index.ts` - Claude Code 러너
|
|
- `runners/codex-runner/src/index.ts` - Codex 러너
|
|
- `src/db.ts` - 등록 그룹, 세션, 스케줄 저장
|
|
- `setup/register.ts` - 디스코드 채널 등록
|
|
- `setup/verify.ts` - 설치 상태 검증
|
|
|
|
## 자주 보는 문제
|
|
|
|
### 봇이 아예 말이 없음
|
|
|
|
```bash
|
|
grep -n '^DISCORD_BOT_TOKEN=' .env
|
|
bun run setup -- --step verify
|
|
```
|
|
|
|
- `DISCORD_BOT_TOKEN`이 없으면 채널이 안 붙습니다.
|
|
- `REGISTERED_GROUPS=0`이면 채널 등록이 안 된 상태입니다.
|
|
- 메인 채널이 아니면 디스코드 멘션이나 트리거 조건을 먼저 확인합니다.
|
|
|
|
### 에이전트가 실행 직후 죽음
|
|
|
|
```bash
|
|
grep -nE '^(CLAUDE_CODE_OAUTH_TOKEN|ANTHROPIC_API_KEY|OPENAI_API_KEY|CODEX_OPENAI_API_KEY)=' .env
|
|
ls -t groups/*/logs/agent-*.log | head -3
|
|
```
|
|
|
|
- Claude 계열은 `CLAUDE_CODE_OAUTH_TOKEN` 또는 `ANTHROPIC_API_KEY`가 필요합니다.
|
|
- Codex 계열은 `OPENAI_API_KEY` 또는 `CODEX_OPENAI_API_KEY`가 필요합니다.
|
|
- 러너 로그에 인증 실패나 CLI 실행 오류가 바로 찍힙니다.
|
|
|
|
### 음성 전사가 안 됨
|
|
|
|
```bash
|
|
grep -nE '^(GROQ_API_KEY|OPENAI_API_KEY)=' .env
|
|
tail -f logs/ejclaw.log | grep -iE 'transcri|audio|whisper|groq'
|
|
```
|
|
|
|
- 기본 우선순위는 Groq Whisper, 없으면 OpenAI Whisper fallback입니다.
|
|
- 키가 없으면 디스코드 채널은 음성 첨부를 텍스트로 확장하지 못합니다.
|
|
|
|
### 등록은 되어 있는데 응답이 이상함
|
|
|
|
```bash
|
|
sqlite3 store/messages.db "select jid, folder, requires_trigger, is_main, agent_type from registered_groups;"
|
|
```
|
|
|
|
- `jid`는 `dc:<channel_id>` 형식이어야 합니다.
|
|
- `folder`는 `discord_main` 또는 `discord_<name>` 형태를 유지합니다.
|
|
- 세션 명령 문제면 `src/session-commands.ts`와 `src/index.ts` 호출부를 같이 봅니다.
|
|
|
|
## 원칙
|
|
|
|
- 채널 문제와 에이전트 문제를 섞지 말고 분리해서 봅니다.
|
|
- `.env`, DB 등록, 서비스, 러너 빌드 중 하나라도 틀리면 상위 증상이 비슷하게 보입니다.
|
|
- 컨테이너 전제 문서는 무시하고 `runners/*`와 `setup/*` 기준으로 확인합니다.
|