Before, a Claude run that hit the account usage limit closed the open paired task as claude_usage_limit, posted the reset time and consumed the user's messages, so the work was lost and had to be re-requested. Now the room is paused instead: - The failed turn is released without touching the paired task (no failure count, no status change, no follow-up) and the queue keeps the human messages unconsumed, so the same turn can run again. - The room is recorded in router_state `claude_usage_pause` with the reset time (error text, else cached usage API reset, else a 10 min retry). A banner time that just passed is read as "now", not tomorrow. - While the limit lasts, paused rooms run nothing and any other room's Claude turn pauses that room without spawning a run (the limit is account-wide). A stop request still goes through and drops the room from the resume list. - The scheduler tick clears the pause 1 min after the reset, posts a resume notice and re-queues the rooms; the pending turn or the kept messages then run again. The state survives restarts. Safety refusals keep closing the task as before. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
6.7 KiB
설정
EJClaw의 설정 기준은 .env 하나입니다.
프로젝트 루트의 ../.env.example를 기본 예시로 보고, 이 문서는 현재 런타임에서 의미가 있는 키만 추려 설명합니다.
기본 원칙
- Discord 토큰은 role-fixed canonical 키만 사용합니다
- reviewer 기본 provider는
claude-code - owner 기본 provider는
codex - room-level override는 provider 단위(
claudeModel,codexModel)만 지원합니다 - Claude와 Codex는 각각 계정 1개로 동작합니다 (계정 로테이션 없음)
Discord 봇
DISCORD_OWNER_BOT_TOKEN=
DISCORD_REVIEWER_BOT_TOKEN=
DISCORD_ARBITER_BOT_TOKEN=
예전 service-based alias는 더 이상 허용되지 않습니다.
역할 / 모델 설정
# 역할별 provider
OWNER_AGENT_TYPE=codex
REVIEWER_AGENT_TYPE=claude-code
ARBITER_AGENT_TYPE=codex
# provider 기본 모델
# 공식 Claude API 모델 ID입니다.
CLAUDE_MODEL=claude-opus-5-5
CLAUDE_EFFORT=high
CLAUDE_THINKING=adaptive
CODEX_MODEL=gpt-5.5
CODEX_EFFORT=xhigh
# 역할별 override
OWNER_MODEL=gpt-5.5
OWNER_EFFORT=xhigh
REVIEWER_MODEL=claude-opus-5-5
REVIEWER_EFFORT=high
ARBITER_MODEL=gpt-5.5
ARBITER_EFFORT=xhigh
설명:
- reviewer / arbiter provider는 전역
REVIEWER_AGENT_TYPE/ARBITER_AGENT_TYPE이 기본값이고, 방마다src/db.ts의assignRoom(jid, { name, reviewerAgentType, arbiterAgentType })를 관리 셸에서 호출해 덮어쓸 수 있습니다 (에이전트용assign_room도구는 제거됨) - 역할별
*_MODEL은 해당 역할의 provider에 맞춰 주입됩니다.codex역할에는 Codex 모델을,claude-code역할에는 Claude 모델을 넣어야 합니다. - 예를 들어
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는 비활성 상태입니다
인증
# Claude Code OAuth
CLAUDE_CODE_OAUTH_TOKEN=
CLAUDE_CREDENTIALS_PATH=
# Claude host env (선택)
ANTHROPIC_API_KEY=
ANTHROPIC_AUTH_TOKEN=
ANTHROPIC_BASE_URL=
설명:
CLAUDE_CODE_OAUTH_TOKEN: runner에 주입하는 Claude 토큰. 예전CLAUDE_CODE_OAUTH_TOKENS(쉼표 구분)가 남아 있으면 첫 번째 값만 씁니다CLAUDE_CREDENTIALS_PATH: 이 서비스의 Claude OAuth credentials 파일.CLAUDE_TOKEN_REFRESH_USE_CREDENTIALS=true면 만료 전에 자동 갱신하고 새 토큰을.env에도 기록합니다- Claude가 사용 한도에 도달하면 다른 provider로 넘기지 않고 그 방의 작업을 일시정지합니다. 방에
Claude 사용 한도에 도달해서 이 방의 작업을 일시정지했습니다. 21:40에 사용량이 초기화되면 자동으로 이어서 진행합니다.처럼 재개 시각을 보내고, paired task와 처리하던 메시지는 그대로 둡니다. 한도가 남아 있는 동안 다른 방의 Claude turn도 실행하지 않고 일시정지합니다. 초기화 시각 1분 뒤 스케줄러가 방들을 다시 큐에 넣어 같은 turn을 이어서 실행합니다. 재개 시각을 모르면 10분 뒤에 다시 시도합니다. 일시정지 상태는router_state.claude_usage_pause에 저장되어 재시작 후에도 유지되며, 일시정지 중 "중단"을 보내면 그 방은 재개하지 않습니다
Codex 쪽은 OAuth 세션 파일 기준으로 동작합니다. ~/.codex-accounts/0/auth.json을 쓰고, 없으면 ~/.codex/auth.json을 씁니다. Codex 실행은 계정 잠금으로 한 번에 하나만 돌고, 잠겨 있으면 최대 15분 기다립니다. OPENAI_API_KEY를 Codex child process에 넘겨서 빌링하는 구조는 사용하지 않습니다.
음성 전사
GROQ_API_KEY=
- 기본은 Groq Whisper(
whisper-large-v3-turbo) GROQ_API_KEY가 없고OPENAI_API_KEY가 있으면 OpenAI Whisper(whisper-1)로 자동 대체됩니다(src/channels/discord.ts)
운영 / 배포 관련 설정
ASSISTANT_NAME=claude
STATUS_CHANNEL_ID=
MAX_CONCURRENT_AGENTS=5
Discord 이미지 첨부 allowlist
EJCLAW_ATTACHMENT_ALLOWED_DIRS=~/Pictures/Screenshots,~/Downloads/ejclaw-images
-
콤마 또는 플랫폼 path delimiter(Linux는
:)로 여러 폴더를 지정합니다. -
기본 허용 폴더는
data/attachments와 Codexgenerated_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/**전체보다 자주 쓰는 스크린샷/이미지 출력 폴더만 추가하는 것을 권장합니다. -
ASSISTANT_NAME은 owner trigger 기본 이름을 만듭니다 -
paired room에서도 사용자 진입점은 owner가 기준입니다
-
status dashboard는 선택 설정입니다
-
/compact·/clear·/stop세션 명령과SESSION_COMMAND_ALLOWED_SENDERS는 제거됐습니다. 남아 있는 값은 무시됩니다. 작업 중단은 방에 "그만"·"멈춰"·"stop" 같은 짧은 메시지를 보내면 됩니다(README "작업 중단" 참고)
디버깅 경로
| 항목 | 경로 / 명령 |
|---|---|
| DB | store/messages.db |
| 서비스 로그 | journalctl --user -u ejclaw -f |
| room 로그 | groups/{folder}/logs/ |
| owner/reviewer 세션 | data/sessions/{folder}* |
| owner worktree | data/workspaces/{folder}/owner |
| Claude 플랫폼 프롬프트 | prompts/claude-platform.md |
| reviewer 프롬프트 | prompts/claude-paired-room.md |
| arbiter 프롬프트 | prompts/arbiter-paired-room.md |
| Codex 플랫폼 프롬프트 | prompts/codex-platform.md |
| 글로벌 메모리 | groups/global/CLAUDE.md |
문서와 실제 코드의 우선순위
문서보다 실제 동작이 우선입니다. 동작 기준을 확인할 때는 아래를 먼저 봅니다.
.env.examplesrc/config/load-config.tssrc/agent-runner-environment.tssrc/paired-execution-context.ts