# 설정 파일 레퍼런스

## 위치

기본 경로:
- `~/.habraid/data/config.json`

하위 호환 / 명시 실행 경로:
- `HABRAID_CONFIG=/path/to/config.json`
- `WIKI_ENGINE_CONFIG=/path/to/config.json`
- 레거시 fallback: `~/.habraid/config.json`, `~/.config/habraid/config.json`

## 스키마

```typescript
interface WikiEngineConfig {
  vault: {
    path: string;
    git_remote?: string;
    branch: string;
  };
  db: {
    path: string;
  };
  mempalace: {
    enabled: boolean;
    path: string;
  };
  llm: {
    mode: "host" | "standalone";
    preferences?: {
      priority?: "fast" | "balanced" | "smart";
    };
    fallback?: {
      provider: "openai" | "zai" | "glm" | "ollama";
      model: string;
      api_url: string;
      api_key_env: string;
      max_tokens: number;
    };

    // legacy compatibility fields
    provider: string;
    model: string;
    api_url: string;
    api_key_env: string;
    max_tokens: number;
  };
  sync: {
    timezone: string;
  };
}
```

## 권장 기본값

```json
{
  "vault": {
    "path": "~/wiki",
    "branch": "main"
  },
  "db": {
    "path": "~/.habraid/data/habraid.db"
  },
  "mempalace": {
    "enabled": true,
    "path": ""
  },
  "llm": {
    "mode": "host",
    "preferences": {
      "priority": "balanced"
    },
    "fallback": {
      "provider": "zai",
      "model": "glm-5.1",
      "api_url": "https://api.example.com/v1",
      "api_key_env": "GLM_API_KEY",
      "max_tokens": 4096
    },
    "provider": "zai",
    "model": "glm-5.1",
    "api_url": "https://api.example.com/v1",
    "api_key_env": "GLM_API_KEY",
    "max_tokens": 4096
  },
  "sync": {
    "timezone": "Asia/Seoul"
  }
}
```

## 동작 원칙

### `llm.mode = "host"`
- host(Hermes/OpenClaw/Codex CLI)가 가능하면 추론을 담당
- host bridge가 unavailable이면 `llm.fallback` 사용
- `hw_status` / sync state에 마지막 route/provider/model이 기록될 수 있음

### `llm.mode = "standalone"`
- habraid가 직접 backend 호출
- legacy config(`provider/model/api_url/api_key_env`)는 fallback 정보를 제공한다.
- `mode`를 명시하지 않은 기존 config도 기본적으로 host-first로 해석되고, legacy llm 필드는 fallback/runtime metadata로 유지된다.

## 레거시 설정 예시

다음 형태도 계속 읽을 수 있다.

```json
{
  "llm": {
    "provider": "zai",
    "model": "glm-5.1",
    "api_url": "https://api.example.com/v1",
    "api_key_env": "GLM_API_KEY",
    "max_tokens": 4096
  }
}
```

이 경우 내부 normalize 시 standalone-compatible runtime config로 변환된다.

## 설정 파일 로드 순서

1. explicit path (`loadConfig(path)` 또는 CLI `--config`)
2. `WIKI_ENGINE_CONFIG`
3. `HABRAID_CONFIG`
4. `~/.habraid/data/config.json`
5. legacy fallback (`~/.habraid/config.json`, `~/.config/habraid/config.json`)
6. built-in defaults

## API 키

`.env` 검색 경로:
- `~/.hermes/.env`
- `~/.openclaw/.env`
- `./.env`

예시:

```bash
GLM_API_KEY=***
OPENAI_API_KEY=***
OPENROUTER_API_KEY=***
```

실제 사용하는 키는 선택된 standalone backend 또는 fallback의 `api_key_env`를 따른다.