# 원격 제어 및 킬스위치

> 인터넷에 공개된 자료와 커뮤니티 토론을 바탕으로 정리된 Claude Code v2.1.88 분석 보고서.

## 개요

Claude Code는 공식 관리자(및 기업 관리자)가 원격 구성을 통해 클라이언트의 특정 동작을 관리하고 업데이트하여 시스템 보안 및 기업 규정 준수를 보장할 수 있는 원격 관리 메커니즘을 구현하고 있습니다.

## 1. 원격 관리 설정

### 구조

자격이 있는 모든 세션은 다음에서 설정을 가져온다:
```
GET /api/claude_code/settings
```

출처: `src/services/remoteManagedSettings/index.ts:105-107`

### 폴링 동작

```typescript
// src/services/remoteManagedSettings/index.ts:52-54
const SETTINGS_TIMEOUT_MS = 10000
const DEFAULT_MAX_RETRIES = 5
const POLLING_INTERVAL_MS = 60 * 60 * 1000 // 1시간
```

설정은 1시간마다 폴링되며, 실패 시 최대 5회 재시도한다.

### 대상 자격

- Console 사용자 (API 키): 전원 대상
- OAuth 사용자: Enterprise/C4E 및 Team 구독자만 해당

### 수락 강제 다이얼로그

원격 설정에 "위험한" 변경이 포함되면 차단 다이얼로그가 표시된다:

```typescript
// src/services/remoteManagedSettings/securityCheck.tsx:67-73
export function handleSecurityCheckResult(result: SecurityCheckResult): boolean {
  if (result === 'rejected') {
    gracefulShutdownSync(1)  // 종료 코드 1로 종료
    return false
  }
  return true
}
```

원격 설정을 거부하면 애플리케이션이 **강제 종료된다**. 선택지는 원격 설정 수락 또는 Claude Code 종료뿐이다.

### 장애 시 동작

원격 서버 접근이 불가능하면 디스크 캐시 설정을 사용한다:

```typescript
// src/services/remoteManagedSettings/index.ts:433-436
if (cachedSettings) {
  logForDebugging('Remote settings: Using stale cache after fetch failure')
  setSessionCache(cachedSettings)
  return cachedSettings
}
```

원격 설정이 한 번 적용되면, 서버 장애 시에도 캐시가 유지된다.

## 2. Feature Flag 킬스위치

GrowthBook feature flag를 통해 여러 기능을 원격 비활성화할 수 있다:

### 권한 우회 킬스위치

```typescript
// src/utils/permissions/bypassPermissionsKillswitch.ts
// Statsig 게이트를 확인하여 권한 우회를 비활성화
```

사용자 동의 없이 권한 우회 기능을 비활성화할 수 있다.

### Auto 모드 서킷 브레이커

```typescript
// src/utils/permissions/autoModeState.ts
// autoModeCircuitBroken 상태로 auto 모드 재진입을 차단
```

Auto 모드를 원격으로 비활성화할 수 있다.

### Fast 모드 킬스위치

```typescript
// src/utils/fastMode.ts
// /api/claude_code_penguin_mode 에서 조회
// 특정 사용자의 fast 모드를 영구 비활성화 가능
```

### 분석 싱크 킬스위치

```typescript
// src/services/analytics/sinkKillswitch.ts:4
const SINK_KILLSWITCH_CONFIG_NAME = 'tengu_frond_boric'
```

모든 분석 출력을 원격으로 중단할 수 있다.

### Agent Teams 킬스위치

```typescript
// src/utils/agentSwarmsEnabled.ts
// 환경 변수와 GrowthBook 게이트 'tengu_amber_flint' 모두 필요
```

### 음성 모드 킬스위치

```typescript
// src/voice/voiceModeEnabled.ts:21
// 'tengu_amber_quartz_disabled' — 음성 모드 긴급 차단
```

## 3. 모델 오버라이드 시스템

카나리 테스트를 수행하거나 예상치 못한 온라인 상황에 대응하기 위해 시스템은 내부 직원과 같은 특정 그룹에 대해 모델 버전을 동적으로 전환하는 것을 지원합니다:

```typescript
// src/utils/model/antModels.ts:32-33
// @[MODEL LAUNCH]: tengu_ant_model_override에 새 ant 전용 모델 업데이트
// @[MODEL LAUNCH]: 코드네임을 scripts/excluded-strings.txt에 추가
```

`tengu_ant_model_override` GrowthBook flag로 가능한 작업:
- 기본 모델 설정
- 기본 노력 수준 설정
- 시스템 프롬프트에 내용 추가
- 커스텀 모델 별칭 정의

## 4. Penguin 모드

Fast 모드 상태는 전용 엔드포인트에서 조회한다:

```typescript
// src/utils/fastMode.ts
// GET /api/claude_code_penguin_mode
// API가 비활성화를 응답하면 해당 사용자에게 영구 비활성화
```

Fast 모드 가용성을 제어하는 feature flag:
- `tengu_penguins_off`
- `tengu_marble_sandcastle`

## 요약

| 메커니즘 | 범위 | 사용자 동의 |
|----------|------|------------|
| 원격 관리 설정 | Enterprise/Team | 수락 또는 종료 |
| GrowthBook feature flag | 전체 사용자 | 없음 |
| 킬스위치 | 전체 사용자 | 없음 |
| 모델 오버라이드 | 내부 (ant) | 없음 |
| Fast 모드 제어 | 전체 사용자 | 없음 |

원격 제어 인프라는 광범위합니다. 기업 관리자는 사용자가 재정의할 수 없는 정책을 강제할 수 있으며, 시스템은 중대한 문제를 해결하기 위해 기능 플래그(feature flags)를 통해 모든 사용자의 동작을 원격으로 변경할 수 있습니다.