Kiro Crew 설정

선행 학습

Crew의 개념은 Kiro Crew, 설치·시작은 Kiro Crew 설치 및 시작에서 먼저 확인하세요.

설정이 사는 곳

항목	경로	설명
설정 파일	~/.kiro/crew/config.json	kirocrew config get/set/edit로 관리
자격 증명	~/.kiro/crew/.env	메신저 채널 토큰 등 (Slack: SLACK_APP_TOKEN, SLACK_BOT_TOKEN, KIROCREW_OWNER_ID)
데이터 홈	~/.kiro/crew/	설정·자격 증명·세션 이력·DB. 다른 Kiro 패밀리 앱과 ~/.kiro/ 베이스를 공유

Crew는 .kiro/를 별도 체계가 아니라 공유 베이스로 씁니다. ~/.kiro/crew/가 Crew 전용 데이터, 프로젝트의 .kiro/steering·.kiro/agents·mcp.json은 IDE·CLI와 그대로 공유됩니다. (관계 전체는 설치 및 시작 — 기존 .kiro/ 설정과의 관계 참고)

설정 읽기·쓰기

kirocrew config get dashboard.use_builtin_browser   # 값 조회
kirocrew config set dashboard.use_builtin_browser false  # 값 변경
kirocrew config edit                                 # 에디터로 직접 편집

환경 변수

변수	기본값	용도
KIROCREW_HOME	~/.kiro/crew	데이터 디렉터리(설정·자격 증명·DB)
KIROCREW_PORT	5476	게이트웨이/대시보드 리스닝 포트
KIROCREW_EMBED_MODEL_URL	CDN 기본값	임베딩 모델 다운로드 미러
KIROCREW_EMBED_MODEL_PATH	미설정	번들 모델 대신 로컬 GGUF 사용

• KIROCREW_PORT는 CLI 진입 시 검증되는 환경 변수이며 config 키가 아닙니다. CLI의 --port가 이를 덮어쓰며, --port auto는 OS가 할당하는 임시 포트에 바인딩합니다.
• dashboard.url config 키는 원격 URL을 광고할 뿐 포트를 바꾸지는 않습니다.
• 설치형 서비스에서는 포트가 설치 시 유닛에 구워집니다.

기본값이 opt-in인 주요 옵션

Crew는 민감하거나 외부로 데이터를 보내는 기능을 기본 비활성으로 둡니다. 명시적으로 켜야 동작합니다.

옵션	기본	설명
WakaTime 연동	off	켜면 코딩 활동 하트비트를 WakaTime으로 보내고 계정 통계를 읽음 (telemetry/wakatime 섹션)
Knowledge 자동 수집	off (신규 설치)	켜기 전에는 아무것도 수집하지 않음. 명시적으로 켜야 지식 라이브러리에 적재
dashboard.use_builtin_browser	true	데스크톱 앱에서 네이티브 브라우저 패널 경로 선택. 끄면 playwright-cli 경로로 라우팅 (→ Crew 브라우저)

✅ 프라이버시 기본값

외부 전송·자동 수집 계열은 끈 상태가 기본입니다. 데이터가 나가는 동작은 사용자가 의식적으로 켠 경우에만 일어나므로, 켤 때 그 범위를 먼저 확인하세요.

데이터 홈 마이그레이션 (업그레이드 시 주의)

과거 최상위 ~/.kirocrew/ 설치본은 첫 실행 시 ~/.kiro/crew/로 자동 마이그레이션됩니다. 업그레이드 전에 반드시 알아둘 점:

• 같은 상대 경로의 파일을 덮어쓰며, 롤백 복사본이나 덮어쓴 파일의 백업이 없습니다.
• 재다운로드 가능한 대용량 콘텐츠(models/, cache/)는 복사되지 않고 첫 시작 때 새 홈에서 재생성됩니다.
• 레거시 루트의 가상환경(venv, .venv, venvs)은 복사·삭제되지 않습니다(venv는 재배치 불가).
• KIROCREW_HOME을 설정하면 마이그레이션은 아예 건너뜁니다. 두 홈을 분리하고 싶다면 업그레이드 전에 설정하세요.

롤백은 없습니다. 되돌릴 수 있어야 한다면 먼저 백업하세요:

cp -a ~/.kirocrew ~/.kirocrew.manual-backup

버전별 설정 변화 추적

업그레이드 전에 바뀐 설정 전제를 확인하세요. 특히 설정에 영향을 주는 변화는:

• 0.3: Node.js 22가 최소 요건(24 LTS 권장). Telegram은 단일 계정 — 토큰을 telegram.bot_token으로 이전(계정 맵 미사용). kirocrew logout이 리프레시 토큰을 폐기해 모든 곳의 세션 종료. 터미널 출력의 자격 증명 스캔 제거(CJK·이모지 손상 방지). Knowledge 자동 수집이 opt-in으로 전환.
• 0.6: 세션별 harness(런타임) 선택 (Preview).

Crew 전체의 버전별 변화는 Kiro Crew 개요 — 버전별 변화 추적에 정리돼 있습니다. 1차 출처는 공식 changelog입니다: 0.3 · 0.6.

참고 링크

리소스	URL
공식 문서 — Configuration	kiro.dev/docs/crew/configuration/
소스 — 설치·설정 가이드	github.com/kirodotdev/KiroCrew — docs/guides/install.md

🚨 문제 해결

• 설정 변경이 반영되지 않음: kirocrew config get <키>로 실제 적용값을 확인하세요. 서비스형은 재시작이 필요할 수 있습니다.
• 메모리/지식 검색이 비어 있음: 임베딩 모델 URL 도달성과 ~/.kiro/crew/models/ 아래 GGUF 존재 여부를 확인하세요.
• 업그레이드 후 빈 상태로 시작: 데이터 홈 마이그레이션이 ~/.kirocrew → ~/.kiro/crew로 이동했는지 확인하세요. KIROCREW_HOME을 별도 지정했다면 그 경로를 봅니다.

이 문서의 공식 내용은 라이선스 준수를 위해 재구성·요약되었습니다. 정확한 원문은 위 참고 링크를 확인하세요.