Files
EJClaw/docs/configuration.md
Codex ce4547daa6 feat: replace session commands with a natural-language stop
Remove the /compact, /clear and /stop session commands. They were gated
to the main room or SESSION_COMMAND_ALLOWED_SENDERS, neither of which
exists in this deployment, so nobody could use them. The agent-runner
/compact passthrough goes with them.

Instead, a short human message whose whole intent is "stop" (그만, 멈춰,
중단해, 하지 마, 취소, stop, cancel, ...; see src/stop-intent.ts) stops the
room when it has something to stop: a running or queued run, an open
paired task, or unprocessed human messages before it. The message loop
then
- advances the room cursors past the stop message (memory + router_state)
- completes the open paired task as user_stopped, cancels its open turns
  and drops its execution lease
- closes stdin with a user-stop reason and kills the agent through the
  existing GroupQueue.closeStdin/killProcess
- replies "진행 중이던 작업을 중단했습니다." once
When nothing is running the message is handled as a normal message.

The user-stop close reason is treated like a human interruption, so the
killed paired turn releases its lease without counting a failure and
queues no follow-up, and the turn controller does not post the generic
failure text on top of the stop reply.

advanceLastAgentCursor no longer moves a cursor backwards, so a run that
finishes after the stop cannot rewind the cursor and re-dispatch the
stop message (the respawn seen when an agent was only killed).

Stale SESSION_COMMAND_* keys in .env are now ignored instead of failing
startup.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 19:26:10 +09:00

141 lines
5.5 KiB
Markdown

# 설정
EJClaw의 설정 기준은 `.env` 하나입니다.
프로젝트 루트의 [`../.env.example`](../.env.example)를 기본 예시로 보고, 이 문서는 현재 런타임에서 의미가 있는 키만 추려 설명합니다.
## 기본 원칙
- Discord 토큰은 role-fixed canonical 키만 사용합니다
- reviewer 기본 provider는 `claude-code`
- owner 기본 provider는 `codex`
- room-level override는 provider 단위(`claudeModel`, `codexModel`)만 지원합니다
- `CLAUDE_CODE_OAUTH_TOKENS`가 canonical이고, `CLAUDE_CODE_OAUTH_TOKEN`은 legacy fallback입니다
## Discord 봇
```bash
DISCORD_OWNER_BOT_TOKEN=
DISCORD_REVIEWER_BOT_TOKEN=
DISCORD_ARBITER_BOT_TOKEN=
```
예전 service-based alias는 더 이상 허용되지 않습니다.
## 역할 / 모델 설정
```bash
# 역할별 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
OWNER_FALLBACK_ENABLED=true
REVIEWER_MODEL=claude-opus-5-5
REVIEWER_EFFORT=high
REVIEWER_FALLBACK_ENABLED=true
ARBITER_MODEL=gpt-5.5
ARBITER_EFFORT=xhigh
ARBITER_FALLBACK_ENABLED=true
```
설명:
- 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-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는 비활성 상태입니다
## 인증
```bash
# Claude Code OAuth
CLAUDE_CODE_OAUTH_TOKENS=
CLAUDE_CODE_OAUTH_TOKEN=
# Claude host env (선택)
ANTHROPIC_API_KEY=
ANTHROPIC_AUTH_TOKEN=
ANTHROPIC_BASE_URL=
```
설명:
- `CLAUDE_CODE_OAUTH_TOKENS`: canonical, 쉼표 구분
- `CLAUDE_CODE_OAUTH_TOKEN`: 단일 토큰 legacy fallback
- 실제 runner에는 현재 선택된 Claude 토큰 하나만 주입됩니다
Codex 쪽은 현재 **OAuth 세션 파일** 기준으로 동작합니다. `OPENAI_API_KEY`를 Codex child process에 넘겨서 빌링하는 구조는 사용하지 않습니다.
## 음성 전사
```bash
GROQ_API_KEY=
```
- 기본은 Groq Whisper(`whisper-large-v3-turbo`)
- `GROQ_API_KEY`가 없고 `OPENAI_API_KEY`가 있으면 OpenAI Whisper(`whisper-1`)로 자동 대체됩니다(`src/channels/discord.ts`)
## 운영 / 배포 관련 설정
```bash
ASSISTANT_NAME=claude
STATUS_CHANNEL_ID=
MAX_CONCURRENT_AGENTS=5
```
## Discord 이미지 첨부 allowlist
```bash
EJCLAW_ATTACHMENT_ALLOWED_DIRS=~/Pictures/Screenshots,~/Downloads/ejclaw-images
```
- 콤마 또는 플랫폼 path delimiter(Linux는 `:`)로 여러 폴더를 지정합니다.
- 기본 허용 폴더는 `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/**` 전체보다 자주 쓰는 스크린샷/이미지 출력 폴더만 추가하는 것을 권장합니다.
- `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` |
## 문서와 실제 코드의 우선순위
문서보다 실제 동작이 우선입니다. 동작 기준을 확인할 때는 아래를 먼저 봅니다.
1. `.env.example`
2. `src/config/load-config.ts`
3. `src/agent-runner-environment.ts`
4. `src/paired-execution-context.ts`