diff --git a/.claude/skills/customize/SKILL.md b/.claude/skills/customize/SKILL.md index e034f4a..cc7668e 100644 --- a/.claude/skills/customize/SKILL.md +++ b/.claude/skills/customize/SKILL.md @@ -59,7 +59,7 @@ description: Customize Discord-only EJClaw behavior, routing, integrations, prom ```bash bun run typecheck -bun test +bun run test ``` 러너나 실행 경로를 건드렸으면 추가로 확인합니다. diff --git a/.claude/skills/debug/SKILL.md b/.claude/skills/debug/SKILL.md index 382f3d5..e3992eb 100644 --- a/.claude/skills/debug/SKILL.md +++ b/.claude/skills/debug/SKILL.md @@ -12,7 +12,7 @@ description: Debug EJClaw runtime issues on the current Discord-only, host-proce 1. 타입과 테스트부터 확인 ```bash bun run typecheck - bun test + bun run test ``` 2. 서비스 상태 확인 ```bash @@ -20,8 +20,7 @@ description: Debug EJClaw runtime issues on the current Discord-only, host-proce ``` 3. 런타임 로그 확인 ```bash - tail -f logs/ejclaw.log - tail -f logs/ejclaw.error.log + journalctl --user -u ejclaw -f ls -t groups/*/logs/agent-*.log | head ``` 4. 러너 빌드 확인 @@ -45,12 +44,12 @@ description: Debug EJClaw runtime issues on the current Discord-only, host-proce ### 봇이 아예 말이 없음 ```bash -grep -n '^DISCORD_BOT_TOKEN=' .env +grep -nE '^DISCORD_(OWNER|REVIEWER|ARBITER)_BOT_TOKEN=' .env bun run setup -- --step verify ``` -- `DISCORD_BOT_TOKEN`이 없으면 채널이 안 붙습니다. -- `REGISTERED_GROUPS=0`이면 채널 등록이 안 된 상태입니다. +- `DISCORD_OWNER_BOT_TOKEN` / `DISCORD_REVIEWER_BOT_TOKEN` / `DISCORD_ARBITER_BOT_TOKEN`이 없으면 채널이 안 붙습니다. 구 이름(`DISCORD_BOT_TOKEN` 등)이 남아 있으면 시작 시 오류로 종료됩니다. +- `ASSIGNED_ROOMS=0`이면 채널 등록이 안 된 상태입니다. - 메인 채널이 아니면 디스코드 멘션이나 트리거 조건을 먼저 확인합니다. ### 에이전트가 실행 직후 죽음 @@ -61,14 +60,14 @@ ls -t groups/*/logs/agent-*.log | head -3 ``` - Claude 계열은 `CLAUDE_CODE_OAUTH_TOKEN` 또는 `ANTHROPIC_API_KEY`가 필요합니다. -- Codex 계열은 `OPENAI_API_KEY` 또는 `CODEX_OPENAI_API_KEY`가 필요합니다. +- Codex는 API 키가 아니라 OAuth 인증 파일(`~/.codex-accounts/0/auth.json`)을 씁니다. 만료됐으면 `CODEX_HOME=$HOME/.codex-accounts/0 ./node_modules/.bin/codex login --device-auth`로 다시 로그인합니다. 실패 원인은 `paired_turn_attempts.last_error`에서 확인합니다. - 러너 로그에 인증 실패나 CLI 실행 오류가 바로 찍힙니다. ### 음성 전사가 안 됨 ```bash grep -nE '^(GROQ_API_KEY|OPENAI_API_KEY)=' .env -tail -f logs/ejclaw.log | grep -iE 'transcri|audio|whisper|groq' +journalctl --user -u ejclaw -f | grep -iE 'transcri|audio|whisper|groq' ``` - 기본 우선순위는 Groq Whisper, 없으면 OpenAI Whisper fallback입니다. @@ -77,10 +76,10 @@ tail -f logs/ejclaw.log | grep -iE 'transcri|audio|whisper|groq' ### 등록은 되어 있는데 응답이 이상함 ```bash -sqlite3 store/messages.db "select jid, folder, requires_trigger, is_main, agent_type from registered_groups;" +bun -e "import {Database} from 'bun:sqlite'; const db=new Database('store/messages.db',{readonly:true}); console.table(db.query('select chat_jid, folder, room_mode, requires_trigger, is_main, owner_agent_type, work_dir from room_settings').all())" ``` -- `jid`는 `dc:` 형식이어야 합니다. +- `chat_jid`는 `dc:` 형식이어야 합니다. tribunal 방인데 `work_dir`가 비어 있으면 첫 턴에 자동 복구됩니다. - `folder`는 `discord_main` 또는 `discord_` 형태를 유지합니다. - 세션 명령 문제면 `src/session-commands.ts`와 `src/index.ts` 호출부를 같이 봅니다. diff --git a/.claude/skills/setup/SKILL.md b/.claude/skills/setup/SKILL.md index 5428a92..4facaf2 100644 --- a/.claude/skills/setup/SKILL.md +++ b/.claude/skills/setup/SKILL.md @@ -10,7 +10,7 @@ description: Run initial EJClaw setup for the unified single-service Discord arc EJClaw는 현재 **단일 서비스**로 동작합니다: - **ejclaw** — 통합 런타임 서비스 -Claude가 기본 봇으로 동작하고, Codex는 별도 서비스가 아니라 필요 시 내부 러너/역할 라우팅으로 사용됩니다. +owner 역할의 코드 기본값은 Codex(`OWNER_AGENT_TYPE`, reviewer 기본값은 Claude Code)이며, `.env`에서 바꿀 수 있습니다(현재 운영 배포는 owner=claude-code, reviewer=codex, arbiter=claude-code). Codex는 별도 서비스가 아니라 같은 `ejclaw` 서비스 안에서 내부 러너/역할 라우팅으로 실행됩니다. ## 1. 부트스트랩 @@ -18,7 +18,7 @@ Claude가 기본 봇으로 동작하고, Codex는 별도 서비스가 아니라 bash setup.sh ``` -- Node 20 이상과 의존성이 준비되어야 합니다. +- Bun 1.3 이상과 의존성이 준비되어야 합니다(`setup.sh`가 Bun을 확인합니다). - 실패하면 `logs/setup.log`를 먼저 봅니다. ## 2. 현재 상태 확인 @@ -40,7 +40,10 @@ bun run setup -- --step environment `.env`에 최소한 아래 값이 있어야 합니다. ```bash -DISCORD_BOT_TOKEN=... # Claude 봇 토큰 +DISCORD_OWNER_BOT_TOKEN=... # owner 봇 토큰 +DISCORD_REVIEWER_BOT_TOKEN=... # reviewer 봇 토큰 +DISCORD_ARBITER_BOT_TOKEN=... # arbiter 봇 토큰 +# 구 이름(DISCORD_BOT_TOKEN 등)은 더 이상 지원되지 않으며, 남아 있으면 시작 시 오류로 종료됩니다 CLAUDE_CODE_OAUTH_TOKEN=... # 또는 ANTHROPIC_API_KEY=... ASSISTANT_NAME=claude # 트리거 이름 (@claude) ``` @@ -58,7 +61,12 @@ Codex 관련 선택 설정은 **별도 서비스 파일이 아니라 같은 `.en # 같은 .env 또는 서비스 Environment=에 추가 가능 CODEX_MODEL=gpt-5.5 CODEX_EFFORT=xhigh -OPENAI_API_KEY=... +``` + +Codex는 API 키가 아니라 OAuth로만 인증합니다(러너가 `OPENAI_API_KEY`를 일부러 제거함). 로그인: + +```bash +CODEX_HOME=$HOME/.codex-accounts/0 ./node_modules/.bin/codex login --device-auth ``` ### 선택 환경 변수 @@ -101,9 +109,7 @@ bun run setup -- --step register -- \ --jid dc:123456789012345678 \ --name "My Server #general" \ --folder discord_main \ - --trigger @claude \ - --is-main \ - --no-trigger-required + --is-main ``` 보조 채널 예시: @@ -112,8 +118,7 @@ bun run setup -- --step register -- \ bun run setup -- --step register -- \ --jid dc:123456789012345678 \ --name "My Server #ops" \ - --folder discord_ops \ - --trigger @claude + --folder discord_ops ``` ## 6. 서비스 시작 @@ -156,8 +161,8 @@ bun run setup -- --step verify ## 빠른 문제 해결 -- 빌드 문제: `bun run typecheck`, `bun test`, `bun run build:runners` -- Claude 서비스 문제: `logs/ejclaw.error.log` 또는 `journalctl --user -u ejclaw -f` -- Codex 실행 문제: 같은 `ejclaw` 서비스 로그에서 `CODEX_MODEL`, `CODEX_EFFORT`, `OPENAI_API_KEY` 설정을 같이 확인 -- 디스코드 연결 문제: `.env`의 `DISCORD_BOT_TOKEN`과 등록된 `dc:*` JID 확인 -- 응답 문제: `tail -f logs/ejclaw.log` +- 빌드 문제: `bun run typecheck`, `bun run test`, `bun run build:runners` +- Claude 서비스 문제: `journalctl --user -u ejclaw -f` +- Codex 실행 문제: 같은 `ejclaw` 서비스 로그와 `CODEX_MODEL`, `CODEX_EFFORT`, Codex 인증 파일(`~/.codex-accounts/0/auth.json`)을 확인 +- 디스코드 연결 문제: `.env`의 `DISCORD_OWNER_BOT_TOKEN` / `DISCORD_REVIEWER_BOT_TOKEN` / `DISCORD_ARBITER_BOT_TOKEN`과 등록된 `dc:*` JID 확인 +- 응답 문제: `journalctl --user -u ejclaw -f` diff --git a/.env.example b/.env.example index 19c98a3..c409bed 100644 --- a/.env.example +++ b/.env.example @@ -24,7 +24,7 @@ GROQ_API_KEY= # Voice transcription (Groq Whisper, free: ASSISTANT_NAME=claude # Trigger name (@claude) # --- Claude model --- -CLAUDE_MODEL=claude-opus-4-8 # Claude model +CLAUDE_MODEL=claude-opus-5-5 # Claude model CLAUDE_EFFORT=high # Claude effort level CLAUDE_THINKING=adaptive # Claude thinking mode @@ -82,7 +82,7 @@ STATUS_CHANNEL_ID= # Discord channel ID for live status updat # OWNER_EFFORT=xhigh # Owner effort override # OWNER_FALLBACK_ENABLED=true # Fall back to codex on Claude failure (default: true) # -# REVIEWER_MODEL=claude-opus-4-8 # Reviewer model override +# REVIEWER_MODEL=claude-opus-5-5 # Reviewer model override # REVIEWER_EFFORT=high # Reviewer effort override # REVIEWER_FALLBACK_ENABLED=true # Fall back to codex on Claude failure (default: true) # diff --git a/CHANGELOG.md b/CHANGELOG.md index de05c85..3211006 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,23 @@ 이 문서는 EJClaw의 주요 변경 사항을 기록합니다. +## [Unreleased] + +### Changed + +- 기본 Claude 모델을 Claude Opus 5.5(`claude-opus-5-5`)로 상향. Opus 5.5는 Claude Code CLI 2.1.280 이상이 필요해 `@anthropic-ai/claude-agent-sdk`를 0.3.153 → 0.3.286(번들 CLI 2.1.286)으로 올림 (8b68885) +- `@openai/codex`를 0.133.0 → 0.159.3으로 상향. 구버전이 매 실행마다 내던 `failed to decode models response: unknown variant max` 오류와 로그 폭주가 사라지고, 단순 리뷰 턴이 49초 → 5초로 단축됨 (a7f2e02) + +### Fixed + +- Codex 계정이 1개일 때 두 방이 동시에 Codex를 쓰면 두 번째 실행이 "Codex rotation pool unavailable"로 즉시 실패하고 리뷰가 조용히 생략되던 문제 수정. 잠금이 다른 실행에 잡혀 있으면 최대 15분 기다림 (30ba510) +- 이미 턴 소유권을 잃은 실행의 5초 진행 표시 타이머가 멈추지 않아, 실제로 작업 중인 방의 진행 메시지가 멈춘 것처럼 보이던 문제 수정 (69ae334) +- `work_dir`가 비어 있는 tribunal 방에서 실행 컨텍스트가 만들어지지 않아 작업 리비전이 얼고 10분 안의 후속 메시지가 버려지던 문제 수정. 자동 복구 경로가 동작하도록 함 (c7a8a43) + +### Docs + +- README / `docs/configuration.md` / `docs/architecture.md` / setup·debug 스킬을 현재 동작에 맞게 정리: 현재 SDK·모델 버전, room별 reviewer/arbiter override, 제거된 `registered_groups`, 더 이상 지원되지 않는 `DISCORD_BOT_TOKEN`, Codex OAuth 로그인, journald 로그 위치, `bun run test` + ## [0.2.3] - 2026-04-22 ### Added diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8a358a5..b3b0eff 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,7 +12,7 @@ A [skill](https://code.claude.com/docs/en/skills) is a markdown file in `.claude A PR that contributes a skill should not modify any source files. -Your skill should contain the **instructions** Claude follows to add the feature—not pre-built code. See `/add-telegram` for a good example. +Your skill should contain the **instructions** Claude follows to add the feature—not pre-built code. See `.claude/skills/setup/SKILL.md` for the format. ### Why? diff --git a/README.md b/README.md index 80a7134..c7b0921 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # EJClaw ![Version](https://img.shields.io/badge/version-0.2.3-blue) -![Claude Agent SDK](https://img.shields.io/badge/Claude_Agent_SDK-0.2.126-blueviolet) -![Codex SDK](https://img.shields.io/badge/Codex_SDK-0.133.0-green) +![Claude Agent SDK](https://img.shields.io/badge/Claude_Agent_SDK-0.3.286-blueviolet) +![Codex SDK](https://img.shields.io/badge/Codex_SDK-0.159.3-green) ![Bun](https://img.shields.io/badge/Bun-1.3+-f9f1e1?logo=bun&logoColor=black) ![Discord](https://img.shields.io/badge/Discord-Tribunal-5865F2?logo=discord&logoColor=white) @@ -52,8 +52,8 @@ GitHub `main` 베이스 위에 운영 중 검증된 변경을 현재 코드 구 | 역할 | 현재 기본값 | 설명 | | --- | --- | --- | | Owner | room별 `owner_agent_type` (기본 Codex) | 사용자 요청 처리, 코드 작성, 최종 응답 | -| Reviewer | 전역 `REVIEWER_AGENT_TYPE` (기본 Claude Code) | owner 결과 비판적 리뷰, 회귀 검증 | -| Arbiter | 전역 `ARBITER_AGENT_TYPE` (옵션) | owner/reviewer 교착 시 판정 | +| Reviewer | 전역 `REVIEWER_AGENT_TYPE` (기본 Claude Code), room별 `reviewer_agent_type`로 override 가능 | owner 결과 비판적 리뷰, 회귀 검증 | +| Arbiter | 전역 `ARBITER_AGENT_TYPE` (옵션), room별 `arbiter_agent_type`로 override 가능 | owner/reviewer 교착 시 판정 | ```text 사용자 메시지 @@ -80,7 +80,7 @@ MoA가 켜져 있으면 arbiter가 판정하기 전에 Kimi, GLM 같은 외부 - `room_role_overrides`: owner / reviewer / arbiter 역할별 override - `paired_projects`: canonical project root - `paired_workspaces`: 실제 owner / reviewer 실행 workspace -- `registered_groups`: 완전히 제거되지는 않았지만, canonical source가 아니라 compatibility/read-model 성격으로 남아 있는 레이어 +- `registered_groups`: 제거됨. 구버전 DB를 옮길 때 `setup/legacy-room-registrations.ts`가 입력으로만 읽음 운영적으로는: @@ -132,8 +132,8 @@ Discord ──► SQLite (WAL) ──► GroupQueue ──┬──► Owner (ho 현재 runner 번들 기준 버전: -- Claude Agent SDK: `@anthropic-ai/claude-agent-sdk@0.2.126` -- Codex SDK/CLI: `@openai/codex@0.133.0` +- Claude Agent SDK: `@anthropic-ai/claude-agent-sdk@0.3.286` (번들 Claude Code CLI 2.1.286 — Claude Opus 5.5는 CLI 2.1.280 이상 필요) +- Codex SDK/CLI: `@openai/codex@0.159.3` ### 설치 @@ -178,6 +178,8 @@ bun run deploy 3. `migrate-room-registrations` 실행 4. `systemctl --user restart ejclaw` +주의: 운영 유닛은 `bun src/index.ts`로 src를 직접 실행하므로 루트 `dist/` 빌드는 서비스에 영향이 없습니다(runner의 `dist/`는 경로로 실행되므로 `bun run build:runners`가 필요). 또 에이전트 턴 안에서 `systemctl --user restart`를 직접 실행하면 에이전트 자신이 함께 종료되므로, 턴 안에서는 `systemd-run --user --collect … systemctl --user restart ejclaw.service`처럼 분리 실행해야 합니다. + ## 개발 ```bash @@ -192,7 +194,7 @@ bun run check - [docs/architecture.md](docs/architecture.md) — 데이터 모델, 실행 흐름, 주요 파일 - [docs/configuration.md](docs/configuration.md) — `.env` 키와 디버깅 경로 -- [docs/legacy-compat-removal-spec.md](docs/legacy-compat-removal-spec.md) — 남아 있는 레거시 제거 계획 +- [docs/legacy-compat-removal-spec.md](docs/legacy-compat-removal-spec.md) — 레거시 제거 설계 문서(주요 결정은 반영 완료, 이력 참고용) - [CHANGELOG.md](CHANGELOG.md) — 릴리즈 이력 ## 라이선스 diff --git a/docs/architecture.md b/docs/architecture.md index e8917bf..5598cb4 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -24,13 +24,12 @@ EJClaw는 단일 `ejclaw` 서비스가 세 Discord 봇과 paired runtime을 함 | `paired_projects` | canonical project root (`canonical_work_dir`) | | `paired_tasks` | paired runtime의 상태 머신 | | `paired_workspaces` | owner / reviewer의 실제 실행 workspace 경로 | -| `registered_groups` | compatibility / materialized read-model 성격의 잔존 레이어 | 현재 기준에서 중요한 점: - room 설정의 기준은 `room_settings` - reviewer / arbiter는 room의 공개 진입점이 아니라 내부 역할 -- `registered_groups`는 제거 진행 대상이지만 아직 완전히 사라진 것은 아님 +- `registered_groups` 테이블은 제거됨(구버전 DB 이전 시 `setup/legacy-room-registrations.ts`가 입력으로만 읽음) ## 실행 흐름 @@ -64,8 +63,8 @@ Discord ──► SQLite (WAL) ──► GroupQueue ──┬──► Owner (ho | 역할 | 기본 선택 | 설명 | | --- | --- | --- | | owner | room별 `owner_agent_type` (기본 Codex) | 사용자 요청 처리, 코드 작성, 최종 응답 | -| reviewer | 전역 `REVIEWER_AGENT_TYPE` (기본 Claude Code) | owner 결과 검토, 회귀 검증 | -| arbiter | 전역 `ARBITER_AGENT_TYPE` (옵션) | owner / reviewer 교착 시 판정 | +| reviewer | 전역 `REVIEWER_AGENT_TYPE` (기본 Claude Code), room별 `reviewer_agent_type` override | owner 결과 검토, 회귀 검증 | +| arbiter | 전역 `ARBITER_AGENT_TYPE` (옵션), room별 `arbiter_agent_type` override | owner / reviewer 교착 시 판정 | 역할별 model / effort는 전역 env(`OWNER_*`, `REVIEWER_*`, `ARBITER_*`)로 정하고, room-level `agentConfig`는 provider별(`claudeModel`, `codexModel`) override만 제공합니다. @@ -98,7 +97,7 @@ Discord ──► SQLite (WAL) ──► GroupQueue ──┬──► Owner (ho - test - build - reviewer / arbiter가 직접 로컬 빌드를 못 돌려도, host verification 경로로 `typecheck`, `test`, `build`를 수행할 수 있음 -- startup precondition은 전용 오류로 올리고, `RestartPreventExitStatus=78`로 crash loop를 막음 +- startup precondition은 전용 오류로 올리고, setup이 생성하는 유닛은 `RestartPreventExitStatus=78`로 crash loop를 막음(현재 운영 호스트의 `ejclaw.service`는 수동 작성 유닛으로 `bun src/index.ts`를 실행하며 이 줄이 없고, 로그는 journald로 감) - deploy는 `migrate-room-registrations`를 선행한 뒤 service restart를 수행 ## 주요 파일 diff --git a/docs/configuration.md b/docs/configuration.md index de2a1ea..9dafcf7 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -31,7 +31,7 @@ ARBITER_AGENT_TYPE=codex # provider 기본 모델 # 공식 Claude API 모델 ID입니다. -CLAUDE_MODEL=claude-opus-4-8 +CLAUDE_MODEL=claude-opus-5-5 CLAUDE_EFFORT=high CLAUDE_THINKING=adaptive CODEX_MODEL=gpt-5.5 @@ -42,7 +42,7 @@ OWNER_MODEL=gpt-5.5 OWNER_EFFORT=xhigh OWNER_FALLBACK_ENABLED=true -REVIEWER_MODEL=claude-opus-4-8 +REVIEWER_MODEL=claude-opus-5-5 REVIEWER_EFFORT=high REVIEWER_FALLBACK_ENABLED=true @@ -53,10 +53,10 @@ ARBITER_FALLBACK_ENABLED=true 설명: -- reviewer / arbiter provider 선택은 **전역 설정** +- reviewer / arbiter provider는 전역 `REVIEWER_AGENT_TYPE` / `ARBITER_AGENT_TYPE`이 기본값이고, 방마다 `assign_room`의 `reviewer_agent_type` / `arbiter_agent_type`으로 덮어쓸 수 있습니다 - 역할별 `*_MODEL`은 해당 역할의 provider에 맞춰 주입됩니다. `codex` 역할에는 Codex 모델을, `claude-code` 역할에는 Claude 모델을 넣어야 합니다. -- 예를 들어 `ARBITER_AGENT_TYPE=claude-code`로 바꾸면 그때 `ARBITER_MODEL=claude-opus-4-8`을 사용할 수 있습니다. -- 특정 방에서만 reviewer를 Codex로 고르는 기능은 없음 +- 예를 들어 `ARBITER_AGENT_TYPE=claude-code`로 바꾸면 그때 `ARBITER_MODEL=claude-opus-5-5`를 사용할 수 있습니다. +- 모델 ID는 추측하지 말고 `GET https://api.anthropic.com/v1/models`로 확인하세요(`claude-opus-5-0` 같은 표기는 존재하지 않음). 새 모델은 더 높은 Claude Code CLI 버전을 요구할 수 있으므로(예: Opus 5.5는 CLI 2.1.280 이상), `.env`를 바꾸기 전에 runner SDK로 실제 호출해 보고 적용하세요. Opus/Sonnet 5.x는 `CLAUDE_THINKING=adaptive`만 지원합니다. - room-level `agentConfig`의 `claudeModel`, `codexModel`은 역할별이 아니라 provider별 override - `ARBITER_AGENT_TYPE`은 옵션이며, 설정하지 않으면 arbiter는 비활성 상태입니다 @@ -87,8 +87,8 @@ Codex 쪽은 현재 **OAuth 세션 파일** 기준으로 동작합니다. `OPENA GROQ_API_KEY= ``` -- 기본은 Groq Whisper -- 필요 시 OpenAI Whisper fallback을 별도 확장할 수 있지만, 현재 README / 문서 기준 최소 키는 `GROQ_API_KEY`입니다 +- 기본은 Groq Whisper(`whisper-large-v3-turbo`) +- `GROQ_API_KEY`가 없고 `OPENAI_API_KEY`가 있으면 OpenAI Whisper(`whisper-1`)로 자동 대체됩니다(`src/channels/discord.ts`) ## MoA @@ -128,7 +128,8 @@ EJCLAW_ATTACHMENT_ALLOWED_DIRS=~/Pictures/Screenshots,~/Downloads/ejclaw-images ``` - 콤마 또는 플랫폼 path delimiter(Linux는 `:`)로 여러 폴더를 지정합니다. -- 지정한 폴더 하위의 PNG/JPEG/GIF/WebP/BMP만 Discord 첨부 후보가 됩니다. +- 기본 허용 폴더는 `data/attachments`와 Codex `generated_images`이며, 이 설정은 그 외 폴더를 추가합니다. +- 첨부 가능 형식: PNG/JPEG/GIF/WebP/BMP, MP4/MOV/WebM, MP3/WAV/OGG/M4A/FLAC, PDF, ZIP, TXT/Markdown/CSV/JSON (SVG 불가). 파일당 최대 8MB. - `realpath`, 이미지 signature, size cap 검증은 그대로 적용됩니다. - `/home/**` 전체보다 자주 쓰는 스크린샷/이미지 출력 폴더만 추가하는 것을 권장합니다. diff --git a/docs/legacy-compat-removal-spec.md b/docs/legacy-compat-removal-spec.md index 4554bef..4b02120 100644 --- a/docs/legacy-compat-removal-spec.md +++ b/docs/legacy-compat-removal-spec.md @@ -1,6 +1,6 @@ # EJClaw 레거시 호환 제거 및 구조 정리 Spec -- 상태: Draft +- 상태: 구현 완료 · 이력 참고용 (주요 결정은 921c241 "finish legacy room cleanup"에서 반영: `registered_groups` 테이블 제거, 구 env 별칭은 시작 시 오류로 거부) - 대상: 코어 개발자 / 리팩토링 담당자 - 기준일: 2026-04-09 - 기준: 저장소 정적 분석 결과 diff --git a/groups/global/CLAUDE.md b/groups/global/CLAUDE.md index e3da019..dd8e9b9 100644 --- a/groups/global/CLAUDE.md +++ b/groups/global/CLAUDE.md @@ -10,7 +10,8 @@ Do not store platform-wide operating rules here. Those now live in `prompts/clau This host has an NVIDIA GPU available for compute: - GPU: NVIDIA GeForce RTX 5050 (GB207, Blackwell), 8GB VRAM, compute capability 12.0 (sm_120) -- Driver 595.71.05, CUDA runtime 13.2; `libcuda.so` present so GPU compute is usable +- Driver 595.x (open kernel module), CUDA runtime 13.2; `libcuda.so` present so GPU compute is usable +- Driver packages auto-update via apt. After an update the userspace libs move ahead of the still-loaded kernel module, and `nvidia-smi` fails with `Failed to initialize NVML: Driver/library version mismatch` until the host reboots. CUDA compute through `/home/claude/gpu-venv` keeps working in that state (verified 2026-10-01: libs 595.91, module 595.84, `torch.cuda.is_available()` True). Treat that `nvidia-smi` error as "reboot pending", not "GPU broken". - Ready-to-use PyTorch (CUDA 12.8 / Blackwell-capable) venv at `/home/claude/gpu-venv` — run with `/home/claude/gpu-venv/bin/python`. `torch.cuda.is_available()` is True. - For CUDA C compilation, `nvcc` is not installed; install the CUDA Toolkit only if a task needs it. @@ -24,15 +25,15 @@ Behavioral rule: when a task could meaningfully benefit from the GPU (ML inferen ## Host RAM / disk safety (tmpfs rule) -`/tmp` (7.2G) and `/dev/shm` (13G) are RAM-backed tmpfs. Anything large written there consumes RAM, not disk. +`/tmp` (16G) and `/dev/shm` (16G) are RAM-backed tmpfs. Anything large written there consumes RAM, not disk. - 2026-06-11 incident: MeloTTS Korean-TTS venv (~2.4GB) was installed into `/tmp/melo311` (tmpfs), eating RAM and risking OOM. Fixed by moving it to disk at `/home/claude/jarvis-tts/melo311` and updating 43 script shebangs. - Recurrence guards (in place, defence-in-depth): 1. `~/.bashrc` exports `TMPDIR=$HOME/.tmp`, `UV_CACHE_DIR=$HOME/.cache/uv`, `PIP_CACHE_DIR=$HOME/.cache/pip` (all ext4 disk), above the interactive-shell guard so non-interactive agent shells inherit it. 2. The `ejclaw.service` user unit (`~/.config/systemd/user/ejclaw.service`) sets the same three `Environment=` vars, so every child process (agent runners, install/build steps that never source `.bashrc`) inherits disk temp at the systemd root. Applied via `daemon-reload`; takes full effect on the next `ejclaw.service` restart. Do NOT restart it from inside a live agent turn (the agent is its descendant). - 3. Scheduled watchdog (cron `*/30`) alerts the group only if `/tmp` or `/dev/shm` > 3GB, available RAM < 4GB, or disk free < 10GB, and auto-deletes `$HOME/.tmp` files older than 3 days. This catches an explicit `/tmp/...` write that bypasses `TMPDIR`. + 3. Watchdog `/home/claude/tmpfs-ram-watchdog.sh` (user crontab `*/30`) posts once per episode to the EJClaw #상태 channel when `/tmp` or `/dev/shm` usage > 3GB or MemAvailable < 4GB, re-arms after recovery, and deletes `$HOME/.tmp` files older than 3 days. Token-free (Discord REST with the owner bot token, no agent run); log `/home/claude/tmpfs-ram-watchdog.log`, latches under `~/.tmpfs-ram-watchdog/`. Test with `DRYRUN=1 TMPFS_MAX_MB=100 /home/claude/tmpfs-ram-watchdog.sh`. This catches an explicit `/tmp/...` write that bypasses `TMPDIR`. (The original watchdog had silently disappeared; restored 2026-10-01.) Disk space is watched separately by `/home/claude/disk85-alert.sh` (cron `*/10`, @everyone alert at ≥85% root usage). - Rule: NEVER install venvs, models, datasets, or any multi-GB artefact into `/tmp` or `/dev/shm`. Use disk paths under `$HOME` (e.g. `/home/claude/jarvis-tts`). If a tool ignores `TMPDIR`, pass an explicit disk path. EJClaw runs directly via `bun` under the user systemd unit (no Docker/compose in use here). -- As of 2026-06-11 the root filesystem was expanded: `/` (ext4) is now 353G total with ~214G free (37% used); earlier it was 156G/84%. RAM is 30GB total, usually ~25GB free. Adding RAM is not the real fix for tmpfs blowups; keeping big artefacts on disk is. Disk is no longer tight, but the watchdog still warns if free drops below 10GB. +- Root filesystem `/` (ext4) is 506G total, ~221G free (55% used) as of 2026-10-01 (it was 156G in early June, then 353G). RAM is 30GB as seen by the guest (Proxmox shows 32GiB and counts guest page cache as "used", so its ~85% figure is misleading — judge by `free -h` → `available`). Adding RAM is not the real fix for tmpfs blowups; keeping big artefacts on disk is. - The two TTS scratch scripts (`/home/claude/jarvis-tts/gen_melo.py`, `gen_xtts.py`) now route output to disk and hard-refuse any `/tmp` or `/dev/shm` write path via a `disk_path()` guard. - 2026-07-26 OOM incident + `MemoryHigh` change: the `ejclaw.service` base unit set `MemoryHigh=3G` (soft cgroup cap; `MemoryMax` unset). An agent-launched GPU/diffusers job in the `anyway2` channel (`gen_banner.py`, ~2.9GB RSS on its own) ran INSIDE the bot's cgroup, pushed total past 3G, and `systemd-oomd` oom-killed `ejclaw.service` ~6× in a row (systemd auto-restarted each time → restart loop; the banner also never finished). Fix: raised the soft cap to `MemoryHigh=16G` via a documented drop-in `~/.config/systemd/user/ejclaw.service.d/10-memory-high.conf` (applied with `daemon-reload`, no restart needed for a cgroup-property change). Rationale: host has 30G, KAclaw is capped at 3G and other services ~2G, so 16G leaves ~11G+cache headroom while still capping runaways; `MemoryMax` stays infinity so a burst is throttled, not hard-killed. The base unit still reads 3G — the drop-in overrides it (`systemctl --user cat ejclaw` shows both). Cleaner long-term alternative (not done): keep the bot cap tight and launch heavy GPU jobs OUTSIDE the bot cgroup via `systemd-run --user --scope`. @@ -57,7 +58,10 @@ Schema: `credentials..{type, host, token, note, added_at}`. Currently stored: - `git.tkrmagid.kr` — Gitea personal access token. Use via `Authorization: token ` header, or embed in HTTPS URL as `https://:@git.tkrmagid.kr/...`. For `git clone/push`, prefer the URL form or `git -c http.extraHeader="Authorization: token " clone ...`. Do not paste the raw token into chat replies. - `sudo` — local sudo password for the `claude` user on this host. Use via `echo "$PW" | sudo -S ` (read the password from `credentials.sudo.password` with the Read tool, then pipe). Do not paste the raw password into chat replies. -- `discord.com/bot/testbot` — Discord test bot (테스트봇, client/app ID `1538122882528321536`), stored 2026-08-15 for use across all chats. Read the token from `credentials["discord.com/bot/testbot"].token` in secrets.json with the Read tool (token is NOT written here). Use as `Authorization: Bot ` against `https://discord.com/api/v10`, or as the bot token for a discord.js/gateway login. Do not paste the raw token into chat replies. Token was chat-exposed on save; if used for anything sensitive/long-term, rotate it in the Discord Developer Portal first. Re-ask the user if Discord returns 401., edit `secrets.json` and append a new entry under `credentials`; update this list with the host and intended use. +- `discord.com/bot/testbot` — Discord test bot (테스트봇, client/app ID `1538122882528321536`), stored 2026-08-15 for use across all chats. Read the token from `credentials["discord.com/bot/testbot"].token` in secrets.json with the Read tool (token is NOT written here). Use as `Authorization: Bot ` against `https://discord.com/api/v10`, or as the bot token for a discord.js/gateway login. Do not paste the raw token into chat replies. Token was chat-exposed on save; if used for anything sensitive/long-term, rotate it in the Discord Developer Portal first. Re-ask the user if Discord returns 401. +- Other entries (each has its own `note` with usage rules — read it before use): `docker5.ssh` (root password fallback for .5; prefer key auth), `kis.koreainvestment` + `dart.fss.or.kr` (stock-adviser APIs), `huggingface.co` (read token), `anthropic.api` (stock-adviser API key with a monthly budget cap; also usable to list models via `GET /v1/models`), `tossinvest.com` (IP-allowlisted), `washing_machine_app.keystore`, `api.smartthings.com`, `discord.com/oauth/virtual-stock-site-bot`, `youtube.oauth/music_bot_v2`, and per-repo GitHub PATs `github.com/Kacarong/{style-ai-site,flight-tracker,stock-adviser,virtual-stock-site-bot,cgv-macro}` (use only via ephemeral push URLs, never persist in `.git/config`). + +To add a credential: edit `secrets.json`, append a new entry under `credentials`, and add the key + intended use to this list. Never paste raw secret values into chat or into this file. ## User communication preferences @@ -65,7 +69,7 @@ Currently stored: ## Room mode policy -All rooms default to `tribunal` (paired) mode. Owner runs the work, reviewer/arbiter (claude-code) verifies. New rooms registered via `bun setup/index.ts --step register` are also `tribunal` by default. +All rooms default to `tribunal` (paired) mode. Owner (claude-code) runs the work, the reviewer (codex, `REVIEWER_AGENT_TYPE=codex`) verifies, and the arbiter (claude-code) breaks deadlocks. New rooms registered via `bun setup/index.ts --step register` are `tribunal` by default and get their paired workspace (`work_dir`) provisioned at registration. A room that ends up tribunal with `work_dir = NULL` (e.g. created through another path) is now self-healed on its first turn (fix c7a8a43, 2026-09-19); before that fix such rooms silently dropped follow-up messages. If the user in a channel says any of these — "클로드 사용하지 말자", "paired 모드 끄자", "리뷰어 끄자", "이 방은 single 로 바꿔줘" — switch that channel back to `single` mode. Use: @@ -150,6 +154,119 @@ Fix (mirrors the Claude per-service isolation above): EJClaw now uses a dedicate then open the printed `https://auth.openai.com/codex/device` URL and enter the one-time code. A plain `codex login` writes to `~/.codex` and will NOT update the account EJClaw uses. Account: ChatGPT `account_id 7e40ecd8-461b-49bd-bbe4-cdc6c7dc68cf`. - Verify: `cd /home/claude/EJClaw && bun -e 'import {initCodexTokenRotation,getActiveCodexAuthPath} from "./src/codex-token-rotation.ts"; initCodexTokenRotation(); console.log(getActiveCodexAuthPath())'` → should print `/home/claude/.codex-accounts/0/auth.json`. +## EJClaw / KAclaw model + runtime versions (updated 2026-10-01) + +Current state: +- EJClaw: `CLAUDE_MODEL=claude-opus-5-5` (Claude Opus 5.5), `CLAUDE_EFFORT=high`, `CLAUDE_THINKING=adaptive`. Runner SDK `@anthropic-ai/claude-agent-sdk` 0.3.286 → bundled Claude Code CLI 2.1.286 (pinned in `runners/agent-runner/package.json`). Reviewer: Codex `gpt-5.5` via `@openai/codex` 0.159.3 (pinned in `runners/codex-runner/package.json`). `.env` backup before the 5.5 switch: `/home/claude/ejclaw-env-backup-20261001-140746`. +- KAclaw: `CLAUDE_MODEL=claude-opus-5` (account hjj100411, Pro). Not upgraded to 5.5 — it likely needs the same SDK bump first. + +Model upgrade checklist (both incidents below were caused by skipping it): +1. Get the exact model ID from the models API, never by guessing from the marketing name: `curl -s https://api.anthropic.com/v1/models -H "x-api-key: " -H "anthropic-version: 2023-06-01"`. Valid 5.x IDs as of 2026-10-01: `claude-opus-5-5`, `claude-sonnet-5-5`, `claude-opus-5`, `claude-sonnet-5`, `claude-fable-5-1`, `claude-fable-5`. Writing `5.0` as `claude-opus-5-0` is invalid — that typo broke every KAclaw channel 2026-09-17 → 09-21. +2. Before editing `.env`, run a real query through the service's own SDK + bundled binary + credentials (`query({model, pathToClaudeCodeExecutable: /node_modules/@anthropic-ai/claude-agent-sdk-linux-x64/claude})` with `CLAUDE_CREDENTIALS_PATH` exported). Newer models can require a newer Claude Code CLI: Opus 5.5 is rejected by CLI 2.1.153 with `400 ... version 2.1.280 or newer is required`, so the SDK had to be bumped first. +3. Opus/Sonnet 5.x support only `adaptive` thinking — keep `CLAUDE_THINKING=adaptive` (`enabled` + budget fails on 5.x). +4. Apply with the detached `systemd-run … systemctl --user restart` form and verify the new PID + zero `does not support this model` / `issue with the selected model` log lines. + +Gotchas found 2026-10-01: +- **Stale nested `node_modules` can shadow the lockfile version.** `runners/codex-runner/node_modules/@openai/codex` held an untracked 0.124.0 copy from 2026-04-26, so the reviewer kept running 0.124 no matter what the pin said (that old CLI failed every run with `failed to decode models response: unknown variant max` and dumped the whole models payload into the journal). It was removed (backup `/home/claude/.tmp/stale-codex-backup/`). After any runner dependency bump, verify what the runner really loads: `cd runners/codex-runner/dist && bun -e "const p=Bun.resolveSync('@openai/codex/package.json', process.cwd()+'/index.js'); console.log(p, require(p).version)"` — it must be the root `node_modules` path. +- **One Codex account = one Codex run at a time.** The per-account auth lease is exclusive (protects refresh-token rotation). Two rooms needing Codex at once used to fail the second run instantly ("Codex rotation pool unavailable") and close the task as `reviewer_codex_unavailable` — the review was silently skipped (3× on 2026-09-28). Since fix 30ba510 the second run waits up to 15 min for the lease; a dead/rate-limited pool still fails fast. Adding a second Codex account under `~/.codex-accounts/1/` would remove the waiting. +- The service runs `bun src/index.ts`, so root `dist/` staleness does not matter; runner `dist/` (spawned by path) does — rebuild with `bun run build:runners` after runner changes. + +EJClaw fixes 2026-09-19 → 10-01 (details in each commit message): +- c7a8a43 — tribunal room with `work_dir = NULL` self-heals instead of freezing its task revision and dropping follow-ups for 10 min. +- 69ae334 — superseded run's 5s progress ticker is stopped when it loses the turn attempt (room no longer looks frozen). +- 8b68885 — claude-agent-sdk 0.3.153 → 0.3.286 for Opus 5.5. +- 30ba510 — wait for a busy Codex lease instead of skipping the review. +- a7f2e02 — @openai/codex 0.133 → 0.159.3 (+ stale 0.124 nested copy removed); simple reviewer turn 49s → 5s, 0 app-server errors. + +## Windows CI 러너 / .9 중첩 가상화 (2026-09-23) — 모든 프로젝트 공용 + +`.9` 안에서 Windows VM 을 돌려 Windows 전용 경로를 자동 검증할 수 있다. +LiveSub 에서 처음 구축했지만 **어느 프로젝트든 그대로 재사용**하면 된다. + +### 중첩 가상화 — 된다 (실측) + +`.9` 는 Proxmox 위의 QEMU/KVM VM 이지만 중첩 가상화가 켜져 있다. +`/dev/kvm` 존재, `kvm_intel nested=Y`, `qemu -enable-kvm` → `kvm support: enabled`. + +- 설치해 둔 것: `qemu-system-x86`, `ovmf`, `swtpm`, `swtpm-tools`, `xorriso` +- **`claude` 계정을 `kvm` 그룹에 넣었다.** `/dev/kvm` 이 `root:kvm 0660` 이라 + 없으면 `Could not access KVM kernel module: Permission denied` 로 죽는다. + usermod 는 재로그인해야 적용되므로 그 전에는 `sg kvm -c '...'` 로 감싼다. +- **중첩 GPU 패스스루는 불가능하다.** IOMMU 그룹 0개, 커널 cmdline 에 iommu + 옵션 없음. GPU 검증은 `.9`(리눅스)에서 직접 해야 한다. + +### 자원 한계 — CPU 는 절대 늘리지 말 것 (실측 근거) + +물리 호스트는 **i7-11700 (8코어/16스레드), RAM 62.6GB** 다. Proxmox(`192.168.10.2`) +에는 SSH 키가 없어 접근 못 하지만, `.5` LXC 를 통해 호스트 스펙을 읽을 수 있다. +`/proc/meminfo` 는 lxcfs 가 컨테이너 한도로 가리므로 +**`/sys/devices/system/node/node0/meminfo`** 를 읽어야 진짜 값이 나온다. + +`.9` 의 vCPU 를 늘리면 `.5` 의 운영 컨테이너 19개가 느려진다. `.5` 응답 실측: + +``` +.9 한가할 때 616~628ms 기준 +.9 가 4코어 사용 657~678ms +7% <- VM 100% 인 정상 상황 +.9 가 8코어 전부 1487~1491ms +140% <- 이 상태를 만들면 안 된다 +``` + +그래서 VM 은 **vCPU 4 / RAM 8GB / 디스크 80GB** 로 띄우고, 최악을 막으려면 +`CPUQuota=400%` + `CPUWeight=50` 을 건다. CI 작업은 코어 4개에서 포화하므로 +더 줘도 빨라지지 않는다 (파이프라인 2코어 13초 / 4코어 10초 / 8코어 11초). + +### ⚠️ VM 은 반드시 `systemd-run --user --scope` 로 띄울 것 + +에이전트 턴에서 그냥 `qemu` 를 실행하면 VM 이 **봇의 cgroup 안에서** 돈다. +`ejclaw.service` 는 `MemoryHigh=16G` 이고 8GB VM 이 그 안에 들어가면 상한을 +쳐서 봇이 OOM 으로 죽는다 (2026-07-26 에 실제로 6회 연속 OOM 전례 있음). + +```bash +systemd-run --user --scope -p MemoryMax=10G -p CPUQuota=400% -p CPUWeight=50 \ + --unit win-ci qemu-system-x86_64 -enable-kvm -m 8192 ... +``` + +`app.slice` 의 형제 scope 로 빠지는 것을 실측 확인했다. + +### ISO 출처 (라이선스 키 불필요) + +- **Windows 11 Enterprise LTSC 2024 평가판** (90일, 키 없이 설치·사용) + `https://go.microsoft.com/fwlink/p/?linkid=2289029` → 4.8GB + 파일명 `26100.1742...CLIENT_LTSC_EVAL_x64FRE_en-us.iso` (빌드 26100 = 24H2) + LTSC 라 Store·소비자 앱이 없어 CI 러너로 오히려 유리하다. + 90일 후에는 `slmgr /rearm` 으로 최대 3회 연장하거나 VM 을 다시 만든다. +- **virtio-win** (virtio 드라이버) + `https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/stable-virtio/virtio-win.iso` → 0.9GB +- 다운로드 속도 약 12.5MB/s → 둘 합쳐 약 8분. +- 사용자 지시: **설치 끝나면 ISO 는 지워서 디스크를 회수할 것.** + +### VM 구성 시 빠뜨리면 조용히 실패하는 것들 + +- `-device virtio-vga,max_outputs=2` — 화면 2개. 기본 `-vga std` 는 1개라 + **모니터 선택 기능을 검증할 수 없다.** 게스트에 virtio-gpu 드라이버 필요. +- 오디오 장치를 안 붙이면 WASAPI 장치 열거가 0개로 실패한다. +- **자동 로그온 필수.** 러너를 서비스로 돌리면 데스크톱 세션이 없어 GUI + 테스트와 스크린샷이 전부 실패한다. 자동 로그온 + 로그온 시 예약 작업. +- Windows 11 은 TPM 2.0 + SecureBoot 필요 → `swtpm` + `OVMF_CODE_4M.secboot.fd`. + +### Gitea Actions 러너 + +- 라벨 형식 `[:]`, schema 기본값 `host`. +- **라벨이 안 맞아도 작업이 실패하지 않고 기본 ubuntu 컨테이너에서 돈다.** + Windows 검증이 조용히 리눅스에서 도는 착각이 생기므로 워크플로 첫 단계에서 + `RUNNER_OS` 를 확인해 막을 것. +- `shell: bash` 를 쓰지 말 것. Git for Windows 를 깔아도 `bash.exe` 는 기본 + PATH 에 없다 (`Git\cmd` 만 등록). `pwsh`(PowerShell 7) 를 쓰고 winget 으로 + `Microsoft.PowerShell` 을 설치해야 한다. +- GPU 러너를 여러 프로젝트가 공유하면 **`capacity: 1`** 을 반드시 확인한다. + 워크플로 `concurrency` 는 같은 저장소 안에서만 막아준다. + +### .9 재부팅 시 확인 (2026-09-23 기준) + +`linger=yes` 이고 아래 유저 서비스가 전부 `enabled` 라 재부팅 후 자동 복구된다. +ejclaw, kaclaw, geoglobe-web/tunnel, unifi-site/tunnel, exvideo-tunnel, +wsai-voice, xmas-counter, vncserver, filter-chain. 시스템 쪽은 docker, +containerd, ollama 가 enabled. 재부팅 전에 이 목록을 다시 확인할 것. + ## .5 Docker host + remote docker context (2026-07-21) A second LAN machine runs Docker workloads; any Claude channel on .9 can drive it.