@spacebar_ai/moldclaw-core 2026.3.14 → 2026.3.16

package/dist/zod-schema.core-DN3RhEUG.d.ts

@@ -0,0 +1,173 @@
+import { z } from "zod";
+
+//#region src/config/zod-schema.core.d.ts
+declare const DmConfigSchema: z.ZodObject<{
+  historyLimit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+declare const GroupPolicySchema: z.ZodEnum<{
+  disabled: "disabled";
+  open: "open";
+  allowlist: "allowlist";
+}>;
+declare const DmPolicySchema: z.ZodEnum<{
+  disabled: "disabled";
+  open: "open";
+  allowlist: "allowlist";
+  pairing: "pairing";
+}>;
+declare const BlockStreamingCoalesceSchema: z.ZodObject<{
+  minChars: z.ZodOptional<z.ZodNumber>;
+  maxChars: z.ZodOptional<z.ZodNumber>;
+  idleMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+declare const ReplyRuntimeConfigSchemaShape: {
+  historyLimit: z.ZodOptional<z.ZodNumber>;
+  dmHistoryLimit: z.ZodOptional<z.ZodNumber>;
+  dms: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodObject<{
+    historyLimit: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strict>>>>;
+  textChunkLimit: z.ZodOptional<z.ZodNumber>;
+  chunkMode: z.ZodOptional<z.ZodEnum<{
+    length: "length";
+    newline: "newline";
+  }>>;
+  blockStreaming: z.ZodOptional<z.ZodBoolean>;
+  blockStreamingCoalesce: z.ZodOptional<z.ZodObject<{
+    minChars: z.ZodOptional<z.ZodNumber>;
+    maxChars: z.ZodOptional<z.ZodNumber>;
+    idleMs: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strict>>;
+  responsePrefix: z.ZodOptional<z.ZodString>;
+  mediaMaxMb: z.ZodOptional<z.ZodNumber>;
+};
+declare const MarkdownConfigSchema: z.ZodOptional<z.ZodObject<{
+  tables: z.ZodOptional<z.ZodEnum<{
+    off: "off";
+    bullets: "bullets";
+    code: "code";
+  }>>;
+}, z.core.$strict>>;
+declare const TtsProviderSchema: z.ZodString;
+declare const TtsModeSchema: z.ZodEnum<{
+  all: "all";
+  final: "final";
+}>;
+declare const TtsAutoSchema: z.ZodEnum<{
+  off: "off";
+  always: "always";
+  inbound: "inbound";
+  tagged: "tagged";
+}>;
+declare const TtsConfigSchema: z.ZodOptional<z.ZodObject<{
+  auto: z.ZodOptional<z.ZodEnum<{
+    off: "off";
+    always: "always";
+    inbound: "inbound";
+    tagged: "tagged";
+  }>>;
+  enabled: z.ZodOptional<z.ZodBoolean>;
+  mode: z.ZodOptional<z.ZodEnum<{
+    all: "all";
+    final: "final";
+  }>>;
+  provider: z.ZodOptional<z.ZodString>;
+  summaryModel: z.ZodOptional<z.ZodString>;
+  modelOverrides: z.ZodOptional<z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    allowText: z.ZodOptional<z.ZodBoolean>;
+    allowProvider: z.ZodOptional<z.ZodBoolean>;
+    allowVoice: z.ZodOptional<z.ZodBoolean>;
+    allowModelId: z.ZodOptional<z.ZodBoolean>;
+    allowVoiceSettings: z.ZodOptional<z.ZodBoolean>;
+    allowNormalization: z.ZodOptional<z.ZodBoolean>;
+    allowSeed: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strict>>;
+  elevenlabs: z.ZodOptional<z.ZodObject<{
+    apiKey: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+      source: z.ZodLiteral<"env">;
+      provider: z.ZodString;
+      id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+      source: z.ZodLiteral<"file">;
+      provider: z.ZodString;
+      id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+      source: z.ZodLiteral<"exec">;
+      provider: z.ZodString;
+      id: z.ZodString;
+    }, z.core.$strict>], "source">]>>;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    voiceId: z.ZodOptional<z.ZodString>;
+    modelId: z.ZodOptional<z.ZodString>;
+    seed: z.ZodOptional<z.ZodNumber>;
+    applyTextNormalization: z.ZodOptional<z.ZodEnum<{
+      off: "off";
+      auto: "auto";
+      on: "on";
+    }>>;
+    languageCode: z.ZodOptional<z.ZodString>;
+    voiceSettings: z.ZodOptional<z.ZodObject<{
+      stability: z.ZodOptional<z.ZodNumber>;
+      similarityBoost: z.ZodOptional<z.ZodNumber>;
+      style: z.ZodOptional<z.ZodNumber>;
+      useSpeakerBoost: z.ZodOptional<z.ZodBoolean>;
+      speed: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+  }, z.core.$strict>>;
+  openai: z.ZodOptional<z.ZodObject<{
+    apiKey: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+      source: z.ZodLiteral<"env">;
+      provider: z.ZodString;
+      id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+      source: z.ZodLiteral<"file">;
+      provider: z.ZodString;
+      id: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+      source: z.ZodLiteral<"exec">;
+      provider: z.ZodString;
+      id: z.ZodString;
+    }, z.core.$strict>], "source">]>>;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    voice: z.ZodOptional<z.ZodString>;
+    speed: z.ZodOptional<z.ZodNumber>;
+    instructions: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>>;
+  edge: z.ZodOptional<z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    voice: z.ZodOptional<z.ZodString>;
+    lang: z.ZodOptional<z.ZodString>;
+    outputFormat: z.ZodOptional<z.ZodString>;
+    pitch: z.ZodOptional<z.ZodString>;
+    rate: z.ZodOptional<z.ZodString>;
+    volume: z.ZodOptional<z.ZodString>;
+    saveSubtitles: z.ZodOptional<z.ZodBoolean>;
+    proxy: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strict>>;
+  microsoft: z.ZodOptional<z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    voice: z.ZodOptional<z.ZodString>;
+    lang: z.ZodOptional<z.ZodString>;
+    outputFormat: z.ZodOptional<z.ZodString>;
+    pitch: z.ZodOptional<z.ZodString>;
+    rate: z.ZodOptional<z.ZodString>;
+    volume: z.ZodOptional<z.ZodString>;
+    saveSubtitles: z.ZodOptional<z.ZodBoolean>;
+    proxy: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strict>>;
+  prefsPath: z.ZodOptional<z.ZodString>;
+  maxTextLength: z.ZodOptional<z.ZodNumber>;
+  timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>>;
+declare const requireOpenAllowFrom: (params: {
+  policy?: string;
+  allowFrom?: Array<string | number>;
+  ctx: z.RefinementCtx;
+  path: Array<string | number>;
+  message: string;
+}) => void;
+//#endregion
+export { MarkdownConfigSchema as a, TtsConfigSchema as c, requireOpenAllowFrom as d, GroupPolicySchema as i, TtsModeSchema as l, DmConfigSchema as n, ReplyRuntimeConfigSchemaShape as o, DmPolicySchema as r, TtsAutoSchema as s, BlockStreamingCoalesceSchema as t, TtsProviderSchema as u };

package/docs/SEC1.md

@@ -0,0 +1,523 @@
+# SEC-1: Secure Token Placeholder Protocol
+
+> **Version**: 1.0  
+> **Status**: Implemented  
+> **Last Updated**: 2026-03-22
+
+## 개요
+
+SEC-1은 moldClaw 설정 파일에서 민감한 정보(API 키, 토큰 등)를 안전하게 관리하기 위한 **플레이스홀더 프로토콜**입니다.
+
+### 핵심 개념
+
+설정 파일에 실제 시크릿 값을 저장하는 대신 `__SECURE__` 플레이스홀더를 사용하고, 실제 값은:
+
+- **OS Credential Store** (macOS Keychain, Windows Credential Manager, Linux Secret Service)
+- **환경변수**
+- **Tauri 앱의 보안 저장소**
+
+에서 런타임에 해석합니다.
+
+```yaml
+# ❌ 안전하지 않음 - 실제 키가 설정 파일에 노출
+discord:
+  token: "MTIzNDU2Nzg5MDEyMzQ1Njc4OQ.XXXXXX.XXXXXXXX"
+
+# ✅ SEC-1 방식 - 플레이스홀더 사용
+discord:
+  token: "__SECURE__"  # 또는 "__SECURE__DISCORD_TOKEN"
+```
+
+## 플레이스홀더 형식
+
+### 기본 형식
+
+```
+__SECURE__
+```
+
+가장 단순한 형태. 해당 필드의 실제 값이 외부에서 제공됨을 표시합니다.
+
+### 식별자 포함 형식
+
+```
+__SECURE__<IDENTIFIER>
+```
+
+어떤 시크릿을 참조하는지 명시적으로 표시합니다:
+
+```yaml
+providers:
+  openai:
+    apiKey: "__SECURE__OPENAI_API_KEY"
+  anthropic:
+    apiKey: "__SECURE__ANTHROPIC_API_KEY"
+```
+
+## 사용 방법
+
+### 1. Config 파일에 플레이스홀더 설정
+
+`moldclaw.yaml`:
+
+```yaml
+discord:
+  token: "__SECURE__"
+
+providers:
+  openai:
+    apiKey: "__SECURE__OPENAI_API_KEY"
+  anthropic:
+    apiKey: "__SECURE__ANTHROPIC_API_KEY"
+
+gateway:
+  token: "__SECURE__GATEWAY_TOKEN"
+```
+
+### 2. 환경변수로 실제 값 제공
+
+```bash
+# .env 파일 또는 시스템 환경변수
+export DISCORD_BOT_TOKEN="MTIzNDU2Nzg5MDEyMzQ1Njc4OQ.XXXXXX"
+export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"
+export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxx"
+export MOLDCLAW_GATEWAY_TOKEN="your-gateway-token"
+```
+
+### 3. 런타임 해석
+
+moldClaw가 시작될 때:
+
+1. Config 파일에서 `__SECURE__` 플레이스홀더 감지
+2. 해당 환경변수에서 실제 값 조회
+3. 플레이스홀더를 실제 값으로 대체
+
+## Tauri 앱과의 연동
+
+### 아키텍처
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    moldClaw Desktop App                  │
+│  ┌─────────────────────────────────────────────────┐    │
+│  │                   Tauri Frontend                 │    │
+│  │  ┌───────────┐    ┌──────────────────────────┐  │    │
+│  │  │  UI/React │◀──▶│  Tauri IPC Commands     │  │    │
+│  │  └───────────┘    └──────────┬───────────────┘  │    │
+│  └────────────────────────────│───────────────────┘    │
+│                               │                          │
+│  ┌────────────────────────────▼───────────────────┐    │
+│  │                  Tauri Backend (Rust)           │    │
+│  │  ┌────────────────────────────────────────┐    │    │
+│  │  │           Secure Storage Module         │    │    │
+│  │  │  ┌────────────┐    ┌───────────────┐   │    │    │
+│  │  │  │  keyring   │    │  SEC-1 API    │   │    │    │
+│  │  │  │   crate    │    │  Handlers     │   │    │    │
+│  │  │  └─────┬──────┘    └───────────────┘   │    │    │
+│  │  └────────│───────────────────────────────┘    │    │
+│  └───────────│────────────────────────────────────┘    │
+│              │                                          │
+└──────────────│──────────────────────────────────────────┘
+               │
+               ▼
+┌──────────────────────────────────────┐
+│       OS Credential Store            │
+│  ┌────────────┬───────────────────┐  │
+│  │   macOS    │  Keychain         │  │
+│  ├────────────┼───────────────────┤  │
+│  │  Windows   │  Credential Mgr   │  │
+│  ├────────────┼───────────────────┤  │
+│  │   Linux    │  Secret Service   │  │
+│  └────────────┴───────────────────┘  │
+└──────────────────────────────────────┘
+```
+
+### Tauri IPC 명령어
+
+Tauri 앱에서 SEC-1 지원을 위해 사용하는 IPC 명령어:
+
+```rust
+// Tauri 백엔드 (Rust)
+#[tauri::command]
+async fn sec1_store_secret(
+    identifier: String,
+    value: String,
+) -> Result<(), String> {
+    let entry = keyring::Entry::new("moldclaw", &identifier)?;
+    entry.set_password(&value)?;
+    Ok(())
+}
+
+#[tauri::command]
+async fn sec1_get_secret(identifier: String) -> Result<Option<String>, String> {
+    let entry = keyring::Entry::new("moldclaw", &identifier)?;
+    match entry.get_password() {
+        Ok(password) => Ok(Some(password)),
+        Err(keyring::Error::NoEntry) => Ok(None),
+        Err(e) => Err(e.to_string()),
+    }
+}
+
+#[tauri::command]
+async fn sec1_delete_secret(identifier: String) -> Result<(), String> {
+    let entry = keyring::Entry::new("moldclaw", &identifier)?;
+    entry.delete_credential()?;
+    Ok(())
+}
+
+#[tauri::command]
+async fn sec1_list_secrets() -> Result<Vec<String>, String> {
+    // 저장된 SEC-1 시크릿 식별자 목록 반환
+    // 구현은 앱별로 다름 (별도 메타데이터 저장 필요)
+}
+```
+
+### Frontend 연동 (React/TypeScript)
+
+```typescript
+import { invoke } from "@tauri-apps/api/core";
+
+// 시크릿 저장
+async function storeSecret(identifier: string, value: string): Promise<void> {
+  await invoke("sec1_store_secret", { identifier, value });
+}
+
+// 시크릿 조회
+async function getSecret(identifier: string): Promise<string | null> {
+  return await invoke("sec1_get_secret", { identifier });
+}
+
+// 시크릿 삭제
+async function deleteSecret(identifier: string): Promise<void> {
+  await invoke("sec1_delete_secret", { identifier });
+}
+
+// 설정 파일 생성 시 SEC-1 플레이스홀더 사용
+async function generateConfig(secrets: Record<string, string>): Promise<void> {
+  // 1. OS Credential Store에 시크릿 저장
+  for (const [id, value] of Object.entries(secrets)) {
+    await storeSecret(id, value);
+  }
+
+  // 2. Config 파일에는 플레이스홀더만 저장
+  const config = {
+    discord: {
+      token: "__SECURE__DISCORD_TOKEN",
+    },
+    providers: {
+      openai: {
+        apiKey: "__SECURE__OPENAI_API_KEY",
+      },
+    },
+  };
+
+  // 3. Config 파일 저장
+  await saveConfigFile(config);
+}
+```
+
+### 런타임 시크릿 주입
+
+Tauri 앱이 moldClaw Gateway를 시작할 때:
+
+```typescript
+import { Command } from "@tauri-apps/plugin-shell";
+import { invoke } from "@tauri-apps/api/core";
+
+async function startGateway(): Promise<void> {
+  // 1. SEC-1 플레이스홀더에 해당하는 시크릿 조회
+  const discordToken = await invoke<string>("sec1_get_secret", {
+    identifier: "DISCORD_TOKEN",
+  });
+  const openaiKey = await invoke<string>("sec1_get_secret", {
+    identifier: "OPENAI_API_KEY",
+  });
+
+  // 2. 환경변수로 주입하여 프로세스 시작
+  const command = Command.create("moldclaw", ["gateway"], {
+    env: {
+      DISCORD_BOT_TOKEN: discordToken ?? "",
+      OPENAI_API_KEY: openaiKey ?? "",
+    },
+  });
+
+  // 3. Gateway 프로세스 시작
+  await command.spawn();
+}
+```
+
+## 두 가지 SEC-1 유틸리티 모듈
+
+SEC-1에는 두 개의 별도 모듈이 있으며, 각각 다른 시나리오를 위해 설계되었습니다:
+
+### 모듈 비교
+
+| 모듈                  | 함수                    | 매칭 방식                    | 대소문자         | 용도                  |
+| --------------------- | ----------------------- | ---------------------------- | ---------------- | --------------------- |
+| `sec1-placeholder.ts` | `isSecurePlaceholder()` | Exact match (`__SECURE__`)   | Case-insensitive | Tauri 앱 마이그레이션 |
+| `sec1-utils.ts`       | `isSec1Placeholder()`   | Prefix match (`__SECURE__*`) | Case-sensitive   | CLI 확장 형식         |
+
+### `sec1-placeholder.ts` - Tauri 앱용
+
+- **사용 시나리오**: Tauri 데스크톱 앱에서 OS Credential Store로 마이그레이션할 때
+- **매칭 방식**: 값이 정확히 `__SECURE__`일 때만 매칭 (공백 trim 후)
+- **대소문자**: Case-insensitive (`__secure__`, `__SECURE__` 모두 매칭)
+- **예시**:
+  ```typescript
+  isSecurePlaceholder("__SECURE__"); // true
+  isSecurePlaceholder("__secure__"); // true
+  isSecurePlaceholder("__SECURE__DISCORD_TOKEN"); // false (exact match 아님)
+  ```
+
+### `sec1-utils.ts` - CLI 확장 형식용
+
+- **사용 시나리오**: CLI에서 어떤 환경변수를 참조하는지 명시적으로 지정할 때
+- **매칭 방식**: 값이 `__SECURE__`로 시작하면 매칭 (prefix match)
+- **대소문자**: Case-sensitive (정확히 `__SECURE__` 대문자만)
+- **예시**:
+  ```typescript
+  isSec1Placeholder("__SECURE__DISCORD_TOKEN"); // true
+  isSec1Placeholder("__SECURE__"); // true
+  isSec1Placeholder("__secure__DISCORD_TOKEN"); // false (대소문자 불일치)
+  ```
+
+### 권장 사용법
+
+- **Tauri 앱**: `sec1-placeholder.ts`의 함수들 사용
+- **CLI/환경변수 형식**: `sec1-utils.ts`의 함수들 사용
+- **설정 파일 작성 시**: 일관성을 위해 `__SECURE__` 대문자 사용 권장
+
+---
+
+## API 레퍼런스
+
+### `sec1-placeholder.ts`
+
+#### `SEC1_PLACEHOLDER`
+
+```typescript
+const SEC1_PLACEHOLDER = "__SECURE__";
+```
+
+기본 SEC-1 플레이스홀더 상수.
+
+#### `isSecurePlaceholder(value: unknown): boolean`
+
+값이 SEC-1 플레이스홀더인지 확인합니다.
+
+```typescript
+isSecurePlaceholder("__SECURE__"); // true
+isSecurePlaceholder("  __SECURE__  "); // true (trimmed)
+isSecurePlaceholder("sk-xxx"); // false
+isSecurePlaceholder(null); // false
+```
+
+#### `resolveSecurePlaceholder(configValue, envValue): string | undefined`
+
+SEC-1 플레이스홀더를 환경변수 값으로 해석합니다.
+
+```typescript
+// 플레이스홀더 → 환경변수로 대체
+resolveSecurePlaceholder("__SECURE__", "sk-real-key"); // "sk-real-key"
+
+// 실제 값 → 그대로 사용
+resolveSecurePlaceholder("sk-config-key", "sk-env-key"); // "sk-config-key"
+```
+
+#### `normalizeSecretValue(value: unknown): string | undefined`
+
+시크릿 값을 정규화합니다. SEC-1 플레이스홀더는 `undefined`로 반환합니다.
+
+```typescript
+normalizeSecretValue("sk-xxx"); // "sk-xxx"
+normalizeSecretValue("__SECURE__"); // undefined (플레이스홀더)
+normalizeSecretValue(""); // undefined
+```
+
+### `sec1-utils.ts`
+
+#### `SEC1_PREFIX`
+
+```typescript
+const SEC1_PREFIX = "__SECURE__";
+```
+
+SEC-1 플레이스홀더 접두사.
+
+#### `isSec1Placeholder(value: unknown): boolean`
+
+값이 SEC-1 플레이스홀더로 시작하는지 확인합니다.
+
+```typescript
+isSec1Placeholder("__SECURE__DISCORD_TOKEN"); // true
+isSec1Placeholder("__SECURE__"); // true
+isSec1Placeholder("sk-xxx"); // false
+```
+
+#### `extractSec1Identifier(value: string): string | null`
+
+SEC-1 플레이스홀더에서 식별자를 추출합니다.
+
+```typescript
+extractSec1Identifier("__SECURE__DISCORD_TOKEN"); // "DISCORD_TOKEN"
+extractSec1Identifier("__SECURE__"); // null
+extractSec1Identifier("sk-xxx"); // null
+```
+
+#### `createSec1Placeholder(identifier: string): string`
+
+식별자로 SEC-1 플레이스홀더를 생성합니다.
+
+```typescript
+createSec1Placeholder("DISCORD_TOKEN"); // "__SECURE__DISCORD_TOKEN"
+createSec1Placeholder("OPENAI_API_KEY"); // "__SECURE__OPENAI_API_KEY"
+```
+
+## 보안 고려사항
+
+### ✅ 장점
+
+1. **설정 파일 안전성**
+   - Git에 커밋해도 실제 시크릿 노출 없음
+   - 설정 파일 공유/백업 시 안전
+
+2. **OS 수준 보안**
+   - macOS Keychain: 암호화 저장, Touch ID/암호 보호
+   - Windows Credential Manager: DPAPI 암호화
+   - Linux Secret Service: GNOME Keyring 등 연동
+
+3. **프로세스 격리**
+   - 시크릿이 환경변수로 전달되므로 파일 시스템에 미노출
+   - 메모리에서만 존재
+
+### ⚠️ 주의사항
+
+1. **환경변수 노출**
+
+   ```bash
+   # 다른 프로세스가 환경변수 읽을 수 있음
+   ps eww  # 또는 /proc/<pid>/environ
+   ```
+
+   - 신뢰할 수 없는 프로세스와 함께 실행 시 주의
+
+2. **로그 필터링**
+
+   ```typescript
+   // 시크릿이 로그에 기록되지 않도록 주의
+   logger.info(`Token: ${token}`); // ❌ 위험!
+   logger.info("Token loaded successfully"); // ✅
+   ```
+
+3. **메모리 보안**
+   - 장시간 실행 시 메모리 덤프 주의
+   - 사용 후 민감 변수 클리어 권장
+
+### 🔒 권장 사항
+
+1. **SEC-1 플레이스홀더 활용**
+   - 모든 민감 정보에 `__SECURE__` 사용
+   - 설정 파일을 버전 관리에 포함 가능
+
+2. **환경변수 파일 보호**
+
+   ```bash
+   chmod 600 .env
+   echo ".env" >> .gitignore
+   ```
+
+3. **Tauri 앱 사용 권장**
+   - OS Credential Store 연동으로 최상의 보안
+   - 마스터 암호/생체 인증 활용
+
+## 예제
+
+### 완전한 Config 예시
+
+```yaml
+# moldclaw.yaml
+# SEC-1 플레이스홀더를 사용한 안전한 설정
+
+# Discord 봇 설정
+channels:
+  discord:
+    token: "__SECURE__DISCORD_TOKEN"
+
+# AI 모델 제공자
+providers:
+  openai:
+    apiKey: "__SECURE__OPENAI_API_KEY"
+  anthropic:
+    apiKey: "__SECURE__ANTHROPIC_API_KEY"
+  google:
+    apiKey: "__SECURE__GOOGLE_API_KEY"
+
+# Gateway 설정
+gateway:
+  token: "__SECURE__GATEWAY_TOKEN"
+
+# TTS 설정
+tts:
+  elevenlabs:
+    apiKey: "__SECURE__ELEVENLABS_API_KEY"
+
+# 웹 검색
+webSearch:
+  tavily:
+    apiKey: "__SECURE__TAVILY_API_KEY"
+```
+
+### 환경변수 파일 예시
+
+```bash
+# .env (이 파일은 .gitignore에 추가!)
+
+# Discord
+DISCORD_BOT_TOKEN=MTIzNDU2Nzg5MDEyMzQ1Njc4OQ.XXXXXX.XXXXXXXX
+
+# AI Providers
+OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+GOOGLE_API_KEY=AIzaxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Gateway
+MOLDCLAW_GATEWAY_TOKEN=your-secure-gateway-token
+
+# TTS
+ELEVENLABS_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Search
+TAVILY_API_KEY=tvly-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+## 문제 해결
+
+### 플레이스홀더가 해석되지 않음
+
+```bash
+# 환경변수가 설정되었는지 확인
+echo $DISCORD_BOT_TOKEN
+
+# .env 파일이 로드되는지 확인
+moldclaw config show
+```
+
+### Tauri 앱에서 시크릿 접근 불가
+
+```bash
+# OS Credential Store 상태 확인 (Linux)
+secret-tool search --all service moldclaw
+
+# macOS
+security find-generic-password -s moldclaw
+```
+
+### 토큰 형식 검증 오류
+
+SEC-1 플레이스홀더는 토큰 형식 검증을 건너뜁니다. 그러나 해석된 값은 여전히 유효한 토큰이어야 합니다.
+
+## 관련 문서
+
+- [Secrets Management](/docs/secrets/)
+- [Configuration Guide](/docs/start/configuration/)
+- [Tauri Integration](/docs/platforms/desktop/)