@spacebar_ai/moldclaw-core 2026.3.14 → 2026.3.16

package/docs/SEC1_IMPLEMENTATION/CHANNELS_REPORT.md

@@ -0,0 +1,173 @@
+# SEC-1 Channels Implementation Report
+
+## 개요
+
+SEC-1 (Secure Token Placeholder Protocol)을 모든 채널(Discord, Telegram, Slack 등)의 토큰 처리에 적용하였습니다.
+
+## SEC-1 스펙
+
+- **형식**: `__SECURE__<identifier>`
+- **예시**: `__SECURE__DISCORD_TOKEN`, `__SECURE__TELEGRAM_BOT_TOKEN`
+- **목적**: 시크릿이 외부에서 관리되며 런타임에 실제 값으로 대체됨을 표시
+
+## 수정된 파일
+
+### 1. SEC-1 유틸리티 (신규)
+
+**파일**: `src/secrets/sec1-utils.ts`
+
+SEC-1 관련 핵심 유틸리티 함수들을 제공합니다:
+
+```typescript
+// SEC-1 플레이스홀더 접두사
+export const SEC1_PREFIX = "__SECURE__";
+
+// SEC-1 플레이스홀더 여부 확인
+export function isSec1Placeholder(value: unknown): boolean;
+
+// SEC-1 플레이스홀더에서 식별자 추출
+export function extractSec1Identifier(value: string): string | null;
+
+// SEC-1 플레이스홀더 생성
+export function createSec1Placeholder(identifier: string): string;
+
+// SEC-1 필터링이 적용된 시크릿 문자열 정규화
+export function normalizeSecretStringValueSec1(value: unknown): string;
+
+// SEC-1 제외 구성된 시크릿 입력 값 확인
+export function hasConfiguredSecretInputValueSec1(value: unknown): boolean;
+```
+
+### 2. 채널 시크릿 수집기
+
+**파일**: `src/secrets/runtime-config-collectors-channels.ts`
+
+#### 변경 사항:
+
+- `isSec1Placeholder` 함수 import 추가
+- `normalizeSecretStringValue()`: SEC-1 플레이스홀더를 빈 문자열로 처리 (수집 대상에서 제외)
+- `hasConfiguredSecretInputValue()`: SEC-1 플레이스홀더를 "구성됨"으로 인식 (런타임 해석 대상)
+
+```typescript
+// SEC-1 플레이스홀더는 런타임에 해석될 유효한 구성으로 인식
+if (typeof value === "string" && isSec1Placeholder(value.trim())) {
+  return true;
+}
+```
+
+### 3. 토큰 검증 헬퍼
+
+**파일**: `src/channels/plugins/setup-wizard-helpers.ts`
+
+#### 변경 사항:
+
+- `isSec1Placeholder` 함수 import 추가
+- `validateTokenFormat()`: SEC-1 플레이스홀더는 형식 검증을 건너뜀
+
+```typescript
+// SEC-1: __SECURE__ 플레이스홀더는 형식 검증 없이 허용
+// 런타임에 실제 시크릿 값으로 해석됨
+if (isSec1Placeholder(trimmed)) {
+  return { valid: true };
+}
+```
+
+## 테스트
+
+### 신규 테스트 파일
+
+**파일**: `src/secrets/sec1-utils.test.ts`
+
+SEC-1 유틸리티 함수들에 대한 포괄적인 테스트:
+
+- `SEC1_PREFIX` 상수 검증
+- `isSec1Placeholder()` 다양한 입력에 대한 테스트
+- `extractSec1Identifier()` 식별자 추출 테스트
+- `createSec1Placeholder()` 플레이스홀더 생성 테스트
+- `normalizeSecretStringValueSec1()` 정규화 테스트
+- `hasConfiguredSecretInputValueSec1()` 구성 확인 테스트
+
+### 기존 테스트 확장
+
+**파일**: `src/channels/plugins/setup-wizard-helpers.test.ts`
+
+`validateTokenFormat` 및 `createTokenValidator`에 SEC-1 지원 테스트 추가:
+
+- SEC-1 플레이스홀더가 모든 채널 타입에서 유효하게 처리됨
+- 공백이 포함된 SEC-1 플레이스홀더 처리
+- 빈 토큰 거부 확인
+- 형식 오류 검증
+
+## 테스트 결과
+
+```
+✓ src/secrets/sec1-utils.test.ts (15 tests) 6ms
+✓ src/channels/plugins/setup-wizard-helpers.test.ts (66 tests) 22ms
+✓ src/secrets/runtime.test.ts (60 tests) 89ms
+
+Test Files: 3 passed
+Tests: 141 passed
+```
+
+## 동작 방식
+
+### 1. 설정 시 (Setup Wizard)
+
+사용자가 `__SECURE__DISCORD_TOKEN`과 같은 값을 입력하면:
+
+- `validateTokenFormat()`이 SEC-1 플레이스홀더를 인식
+- 형식 검증을 건너뛰고 유효하다고 판단
+- 설정 파일에 그대로 저장
+
+### 2. 시크릿 수집 시 (Runtime Config Collection)
+
+시크릿 수집 단계에서:
+
+- `normalizeSecretStringValue()`가 SEC-1 플레이스홀더를 빈 문자열로 반환
+- 이로 인해 해당 값은 "실제 값이 설정됨" 카운트에서 제외
+- 그러나 `hasConfiguredSecretInputValue()`는 SEC-1 플레이스홀더를 "구성됨"으로 인식
+- 런타임에 시크릿 해석 시스템이 실제 값을 주입
+
+### 3. 런타임 시
+
+- SEC-1 플레이스홀더는 시크릿 해석 시스템에 의해 실제 값으로 대체
+- 대체된 실제 값은 채널 연결에 사용됨
+
+## 지원 채널
+
+SEC-1은 다음 채널들의 토큰/시크릿에 적용됩니다:
+
+- **Discord**: `token`, `pluralkit.token`
+- **Telegram**: `botToken`, `webhookSecret`
+- **Slack**: `botToken`, `userToken`, `appToken`, `signingSecret`
+- **WhatsApp**: (시크릿 수집기를 통해 지원)
+- 기타 모든 채널의 시크릿 필드
+
+## 사용 예시
+
+```yaml
+# moldclaw.yaml
+channels:
+  discord:
+    enabled: true
+    token: __SECURE__DISCORD_BOT_TOKEN
+
+  telegram:
+    enabled: true
+    botToken: __SECURE__TELEGRAM_BOT_TOKEN
+
+  slack:
+    enabled: true
+    botToken: __SECURE__SLACK_BOT_TOKEN
+    appToken: __SECURE__SLACK_APP_TOKEN
+```
+
+## 주의사항
+
+1. SEC-1 플레이스홀더는 실제 시크릿 값이 아니며, 반드시 런타임에 해석되어야 합니다.
+2. 시크릿 해석 시스템(예: 환경 변수, 시크릿 매니저)이 올바르게 구성되어야 합니다.
+3. SEC-1 식별자는 해석 시스템에서 인식할 수 있는 형식이어야 합니다.
+
+## 완료 일시
+
+2026-03-22 01:45 KST

package/docs/SEC1_IMPLEMENTATION/CORE_UTIL_REPORT.md

@@ -0,0 +1,139 @@
+# SEC-1 Core Utility Report
+
+## 개요
+
+SEC-1 플레이스홀더 처리를 위한 핵심 유틸리티 모듈 구현 완료.
+
+## 구현 파일
+
+| 파일                                   | 설명                 |
+| -------------------------------------- | -------------------- |
+| `src/secrets/sec1-placeholder.ts`      | SEC-1 핵심 유틸리티  |
+| `src/secrets/sec1-placeholder.test.ts` | 테스트 (30개 케이스) |
+
+## API 요약
+
+### 상수
+
+```typescript
+export const SEC1_PLACEHOLDER = "__SECURE__";
+```
+
+### 함수
+
+| 함수                                                    | 설명                               |
+| ------------------------------------------------------- | ---------------------------------- |
+| `isSecurePlaceholder(value)`                            | 값이 SEC-1 플레이스홀더인지 확인   |
+| `resolveSecurePlaceholder(configValue, envValue)`       | 플레이스홀더를 환경변수로 대체     |
+| `normalizeSecretValue(value)`                           | 토큰 값 정규화 (SEC-1 필터링 포함) |
+| `inspectSecretValue(value)`                             | 플레이스홀더 여부와 정규화 값 반환 |
+| `resolveSecretWithPriority(config, override, fallback)` | 우선순위 기반 시크릿 해석          |
+
+## 사용 예시
+
+### 기본 플레이스홀더 검사
+
+```typescript
+import { isSecurePlaceholder, SEC1_PLACEHOLDER } from "./sec1-placeholder.js";
+
+// Config에서 읽은 값 검사
+if (isSecurePlaceholder(configValue)) {
+  // Credential Store에서 실제 값 조회 필요
+}
+```
+
+### 플레이스홀더 해석
+
+```typescript
+import { resolveSecurePlaceholder } from "./sec1-placeholder.js";
+
+// Tauri 앱에서: Config 값이 __SECURE__ 면 환경변수로 대체
+const token = resolveSecurePlaceholder(
+  config.apiKey, // "__SECURE__" 또는 실제 값
+  process.env.API_KEY, // OS credential store에서 주입된 값
+);
+```
+
+### 우선순위 기반 해석
+
+```typescript
+import { resolveSecretWithPriority } from "./sec1-placeholder.js";
+
+// 우선순위: CLI arg > Config > 환경변수
+const token = resolveSecretWithPriority(
+  config.apiKey, // Config 값
+  args.apiKey, // CLI 오버라이드 (최우선)
+  process.env.API_KEY, // 환경변수 폴백
+);
+```
+
+### 값 정규화
+
+```typescript
+import { normalizeSecretValue } from "./sec1-placeholder.js";
+
+// SEC-1 플레이스홀더, 빈 문자열, 비문자열 → undefined
+// 유효한 문자열 → trimmed 값
+const normalized = normalizeSecretValue(rawValue);
+```
+
+## 테스트 결과
+
+```
+✓ src/secrets/sec1-placeholder.test.ts (30 tests) 8ms
+
+ Test Files  1 passed (1)
+      Tests  30 passed (30)
+```
+
+### 테스트 커버리지
+
+- `SEC1_PLACEHOLDER` 상수 검증
+- `isSecurePlaceholder`: 정확한 매칭, whitespace 처리, 부분 매칭 거부, 비문자열 처리
+- `resolveSecurePlaceholder`: 플레이스홀더 대체, 실제 값 유지, undefined 처리
+- `normalizeSecretValue`: trimming, 플레이스홀더 필터링, 빈 값 처리
+- `inspectSecretValue`: 복합 정보 반환
+- `resolveSecretWithPriority`: 우선순위 로직
+- 통합 시나리오: Tauri 앱, 레거시 config, 다중 폴백
+
+## 설계 결정
+
+### SEC-1 플레이스홀더 값
+
+`__SECURE__` 선택 이유:
+
+- 실제 API 키와 충돌 가능성 0
+- 명확한 의미 전달
+- 대소문자 일관성 (대문자만)
+
+### Whitespace 처리
+
+플레이스홀더 검사 시 trim 적용:
+
+- `"  __SECURE__  "` → 플레이스홀더로 인식
+- YAML/JSON 파싱 후 trailing whitespace 처리
+
+### undefined vs null
+
+- 입력: null도 undefined처럼 처리
+- 출력: 항상 `string | undefined` 반환 (null 사용 안 함)
+
+## 의존성
+
+```typescript
+import { isNonEmptyString } from "./shared.js";
+```
+
+기존 `shared.ts`의 유틸리티 재사용으로 코드 중복 방지.
+
+## 완료 상태
+
+- [x] `sec1-placeholder.ts` 구현
+- [x] `sec1-placeholder.test.ts` 테스트 (30개 케이스)
+- [x] 모든 테스트 통과
+- [x] JSDoc 문서화
+- [x] 사용 예시 포함
+
+---
+
+_Generated: 2026-03-22_

package/docs/SEC1_IMPLEMENTATION/DOCS_REPORT.md

@@ -0,0 +1,134 @@
+# SEC-1 Documentation Report
+
+> **Generated**: 2026-03-22 01:42 KST  
+> **Task**: sec1-docs  
+> **Status**: ✅ Complete
+
+## 문서화 완료 항목
+
+### 1. README.md 업데이트 ✅
+
+**파일**: `/home/sanghyuck/workspace/moldclaw-core/README.md`
+
+**추가된 내용**:
+
+- SEC-1 Quick Start 섹션
+- 플레이스홀더 사용 예시
+- 환경변수 설정 예시
+- 주요 장점 요약
+- 관련 문서 링크
+
+### 2. SEC1.md 가이드 생성 ✅
+
+**파일**: `/home/sanghyuck/workspace/moldclaw-core/docs/SEC1.md`
+
+**포함 내용**:
+
+| 섹션              | 설명                                             |
+| ----------------- | ------------------------------------------------ |
+| 개요              | SEC-1 프로토콜의 핵심 개념 및 목적               |
+| 플레이스홀더 형식 | `__SECURE__` 및 `__SECURE__<ID>` 형식 설명       |
+| 사용 방법         | Config 설정, 환경변수, 런타임 해석 가이드        |
+| Tauri 앱 연동     | 아키텍처 다이어그램, IPC 명령어, Frontend 코드   |
+| API 레퍼런스      | `sec1-placeholder.ts`, `sec1-utils.ts` 함수 문서 |
+| 보안 고려사항     | 장점, 주의사항, 권장 사항                        |
+| 예제              | 완전한 Config 및 .env 예시                       |
+| 문제 해결         | FAQ 및 디버깅 가이드                             |
+
+## 구현 코드 분석
+
+### 발견된 SEC-1 관련 파일
+
+```
+/home/sanghyuck/workspace/moldclaw-core/src/secrets/
+├── sec1-placeholder.ts  (5,681 bytes)
+└── sec1-utils.ts        (3,046 bytes)
+```
+
+### 주요 API
+
+#### `sec1-placeholder.ts`
+
+| 함수                          | 용도                        |
+| ----------------------------- | --------------------------- |
+| `SEC1_PLACEHOLDER`            | `"__SECURE__"` 상수         |
+| `isSecurePlaceholder()`       | 플레이스홀더 여부 확인      |
+| `resolveSecurePlaceholder()`  | 환경변수로 해석             |
+| `normalizeSecretValue()`      | 시크릿 값 정규화            |
+| `inspectSecretValue()`        | 플레이스홀더 여부와 값 반환 |
+| `resolveSecretWithPriority()` | 우선순위 기반 해석          |
+
+#### `sec1-utils.ts`
+
+| 함수                                  | 용도                  |
+| ------------------------------------- | --------------------- |
+| `SEC1_PREFIX`                         | `"__SECURE__"` 접두사 |
+| `isSec1Placeholder()`                 | SEC-1 접두사 확인     |
+| `extractSec1Identifier()`             | 식별자 추출           |
+| `createSec1Placeholder()`             | 플레이스홀더 생성     |
+| `normalizeSecretStringValueSec1()`    | SEC-1 고려 정규화     |
+| `hasConfiguredSecretInputValueSec1()` | 실제 값 설정 여부     |
+
+## Config 예시
+
+### 플레이스홀더 사용
+
+```yaml
+# moldclaw.yaml - SEC-1 플레이스홀더 사용
+channels:
+  discord:
+    token: "__SECURE__"
+
+providers:
+  openai:
+    apiKey: "__SECURE__OPENAI_API_KEY"
+  anthropic:
+    apiKey: "__SECURE__ANTHROPIC_API_KEY"
+
+gateway:
+  token: "__SECURE__GATEWAY_TOKEN"
+```
+
+### 환경변수 설정
+
+```bash
+# .env
+DISCORD_BOT_TOKEN=MTIzNDU2Nzg5MDEyMzQ1Njc4OQ.XXXXXX.XXXXXXXX
+OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+MOLDCLAW_GATEWAY_TOKEN=your-secure-gateway-token
+```
+
+## 보안 고려사항 요약
+
+### 장점 ✅
+
+1. **설정 파일 안전성** - Git 커밋 시 시크릿 미노출
+2. **OS 수준 보안** - Keychain/Credential Manager 암호화
+3. **프로세스 격리** - 메모리에서만 시크릿 존재
+
+### 주의사항 ⚠️
+
+1. **환경변수 노출** - `ps eww` 등으로 조회 가능
+2. **로그 필터링** - 시크릿 로그 출력 방지 필요
+3. **메모리 보안** - 장시간 실행 시 메모리 덤프 주의
+
+## 산출물
+
+| 파일                                      | 상태        | 설명                |
+| ----------------------------------------- | ----------- | ------------------- |
+| `README.md`                               | ✅ 업데이트 | SEC-1 섹션 추가     |
+| `docs/SEC1.md`                            | ✅ 신규     | 포괄적 SEC-1 가이드 |
+| `docs/SEC1_IMPLEMENTATION/DOCS_REPORT.md` | ✅ 신규     | 본 리포트           |
+
+## 후속 작업 제안
+
+1. **테스트 문서화**: `sec1-placeholder.test.ts` 및 `sec1-utils.test.ts` 테스트 케이스 문서화
+2. **Tauri 앱 예제**: 실제 Tauri 앱 통합 샘플 코드 추가
+3. **마이그레이션 가이드**: 기존 설정에서 SEC-1로 마이그레이션하는 단계별 가이드
+4. **CLI 명령어**: `moldclaw secrets` 관련 CLI 문서 추가
+
+---
+
+**작성자**: OpenClaw Agent (sec1-docs)  
+**검토 상태**: Pending main agent review

package/docs/SEC1_IMPLEMENTATION/ENV_MAP_DRAFT.md

@@ -0,0 +1,148 @@
+# SEC-1 환경변수 매핑 초안
+
+> `secure-marker-env-map.ts` 구현을 위한 참고 자료
+
+## 채널 토큰 매핑
+
+| Config 경로                             | 환경변수                     | 비고                                  |
+| --------------------------------------- | ---------------------------- | ------------------------------------- |
+| `channels.discord.token`                | `DISCORD_BOT_TOKEN`          |                                       |
+| `channels.discord.accounts.*.token`     | `DISCORD_BOT_TOKEN`          | 또는 `DISCORD_BOT_TOKEN_{ACCOUNT_ID}` |
+| `channels.discord.pluralkit.token`      | `PLURALKIT_TOKEN`            |                                       |
+| `channels.telegram.botToken`            | `TELEGRAM_BOT_TOKEN`         |                                       |
+| `channels.telegram.accounts.*.botToken` | `TELEGRAM_BOT_TOKEN`         |                                       |
+| `channels.telegram.webhookSecret`       | `TELEGRAM_WEBHOOK_SECRET`    |                                       |
+| `channels.slack.botToken`               | `SLACK_BOT_TOKEN`            |                                       |
+| `channels.slack.appToken`               | `SLACK_APP_TOKEN`            |                                       |
+| `channels.slack.userToken`              | `SLACK_USER_TOKEN`           |                                       |
+| `channels.slack.signingSecret`          | `SLACK_SIGNING_SECRET`       |                                       |
+| `channels.matrix.password`              | `MATRIX_PASSWORD`            |                                       |
+| `channels.matrix.accessToken`           | `MATRIX_ACCESS_TOKEN`        |                                       |
+| `channels.mattermost.botToken`          | `MATTERMOST_TOKEN`           |                                       |
+| `channels.irc.password`                 | `IRC_PASSWORD`               |                                       |
+| `channels.irc.nickserv.password`        | `IRC_NICKSERV_PASSWORD`      |                                       |
+| `channels.bluebubbles.password`         | `BLUEBUBBLES_PASSWORD`       |                                       |
+| `channels.msteams.appPassword`          | `MSTEAMS_APP_PASSWORD`       |                                       |
+| `channels.feishu.appSecret`             | `FEISHU_APP_SECRET`          |                                       |
+| `channels.feishu.encryptKey`            | `FEISHU_ENCRYPT_KEY`         |                                       |
+| `channels.feishu.verificationToken`     | `FEISHU_VERIFICATION_TOKEN`  |                                       |
+| `channels.googlechat.serviceAccount`    | `GOOGLECHAT_SERVICE_ACCOUNT` | JSON 문자열                           |
+| `channels.nextcloud-talk.botSecret`     | `NEXTCLOUD_BOT_SECRET`       |                                       |
+| `channels.nextcloud-talk.apiPassword`   | `NEXTCLOUD_API_PASSWORD`     |                                       |
+| `channels.zalo.botToken`                | `ZALO_BOT_TOKEN`             |                                       |
+| `channels.zalo.webhookSecret`           | `ZALO_WEBHOOK_SECRET`        |                                       |
+
+## Gateway 시크릿 매핑
+
+| Config 경로               | 환경변수                           |
+| ------------------------- | ---------------------------------- |
+| `gateway.auth.token`      | `MOLDCLAW_GATEWAY_AUTH_TOKEN`      |
+| `gateway.auth.password`   | `MOLDCLAW_GATEWAY_AUTH_PASSWORD`   |
+| `gateway.remote.token`    | `MOLDCLAW_GATEWAY_REMOTE_TOKEN`    |
+| `gateway.remote.password` | `MOLDCLAW_GATEWAY_REMOTE_PASSWORD` |
+
+## Model Provider API Key 매핑
+
+| Config 경로                            | 환경변수                   | 비고      |
+| -------------------------------------- | -------------------------- | --------- |
+| `models.providers.openai.apiKey`       | `OPENAI_API_KEY`           |           |
+| `models.providers.anthropic.apiKey`    | `ANTHROPIC_API_KEY`        |           |
+| `models.providers.google.apiKey`       | `GOOGLE_API_KEY`           |           |
+| `models.providers.groq.apiKey`         | `GROQ_API_KEY`             |           |
+| `models.providers.deepseek.apiKey`     | `DEEPSEEK_API_KEY`         |           |
+| `models.providers.perplexity.apiKey`   | `PERPLEXITY_API_KEY`       |           |
+| `models.providers.fireworks.apiKey`    | `FIREWORKS_API_KEY`        |           |
+| `models.providers.together.apiKey`     | `TOGETHER_API_KEY`         |           |
+| `models.providers.mistral.apiKey`      | `MISTRAL_API_KEY`          |           |
+| `models.providers.cohere.apiKey`       | `COHERE_API_KEY`           |           |
+| `models.providers.azure-openai.apiKey` | `AZURE_OPENAI_API_KEY`     |           |
+| `models.providers.*.apiKey`            | `{PROVIDER_UPPER}_API_KEY` | 동적 생성 |
+
+## TTS/STT API Key 매핑
+
+| Config 경로                                    | 환경변수             |
+| ---------------------------------------------- | -------------------- |
+| `messages.tts.elevenlabs.apiKey`               | `ELEVENLABS_API_KEY` |
+| `messages.tts.openai.apiKey`                   | `OPENAI_API_KEY`     |
+| `channels.discord.voice.tts.elevenlabs.apiKey` | `ELEVENLABS_API_KEY` |
+| `channels.discord.voice.tts.openai.apiKey`     | `OPENAI_API_KEY`     |
+
+## Tools API Key 매핑
+
+| Config 경로                          | 환경변수             |
+| ------------------------------------ | -------------------- |
+| `tools.web.search.apiKey`            | `WEB_SEARCH_API_KEY` |
+| `tools.web.search.gemini.apiKey`     | `GOOGLE_API_KEY`     |
+| `tools.web.search.perplexity.apiKey` | `PERPLEXITY_API_KEY` |
+| `tools.web.fetch.firecrawl.apiKey`   | `FIRECRAWL_API_KEY`  |
+
+## 기타 시크릿 매핑
+
+| Config 경로                                | 환경변수                      |
+| ------------------------------------------ | ----------------------------- |
+| `talk.apiKey`                              | `MOLDCLAW_TALK_API_KEY`       |
+| `cron.webhookToken`                        | `MOLDCLAW_CRON_WEBHOOK_TOKEN` |
+| `skills.entries.*.apiKey`                  | `{SKILL_UPPER}_API_KEY`       |
+| `agents.defaults.sandbox.ssh.identityData` | `MOLDCLAW_SSH_IDENTITY`       |
+
+---
+
+## 구현 시 고려사항
+
+### 1. Provider 환경변수 매핑 로직
+
+```typescript
+function resolveProviderEnvVar(providerId: string): string {
+  // 알려진 provider 매핑
+  const KNOWN_PROVIDERS: Record<string, string> = {
+    openai: "OPENAI_API_KEY",
+    anthropic: "ANTHROPIC_API_KEY",
+    google: "GOOGLE_API_KEY",
+    "azure-openai": "AZURE_OPENAI_API_KEY",
+    // ...
+  };
+
+  if (KNOWN_PROVIDERS[providerId]) {
+    return KNOWN_PROVIDERS[providerId];
+  }
+
+  // 동적 생성: my-custom-provider → MY_CUSTOM_PROVIDER_API_KEY
+  return `${providerId.toUpperCase().replace(/-/g, "_")}_API_KEY`;
+}
+```
+
+### 2. Account ID 처리
+
+```typescript
+// channels.discord.accounts.work.token → DISCORD_TOKEN 또는 DISCORD_TOKEN_WORK
+function resolveAccountEnvVar(baseName: string, accountId: string | undefined): string {
+  if (!accountId || accountId === "default") {
+    return baseName;
+  }
+  // 우선 account-specific 환경변수 시도, fallback으로 기본 환경변수
+  return `${baseName}_${accountId.toUpperCase()}`;
+}
+```
+
+### 3. Fallback 전략
+
+```typescript
+function resolveEnvValue(envVarName: string, fallbackEnvVarName?: string): string | undefined {
+  const value = process.env[envVarName];
+  if (value) return value;
+
+  if (fallbackEnvVarName) {
+    return process.env[fallbackEnvVarName];
+  }
+
+  return undefined;
+}
+```
+
+---
+
+## 참조
+
+- `src/secrets/provider-env-vars.ts`: 기존 provider 환경변수 정의
+- `src/channels/config-presence.ts`: 채널별 환경변수 prefix
+- `src/plugins/bundled-provider-auth-env-vars.ts`: 번들 provider 환경변수