내장 도구

내장 도구 (src/tools/*) 각 도구는 선택 사항입니다 — 키가 없으면 해당 기능이 조용히 비활성화됩니다.

web_search / web_extract 백엔드

web_search 와 web_extract 는 같은 백엔드를 공유합니다. 모델은 제공자를 고를 수 없습니다. 사용 가능한 첫 번째를 씁니다: 1. Tavily — TAVILY_API_KEY. 최우선. 2. Firecrawl — FIRECRAWL_API_KEY. Tavily 를 쓸 수 없을 때만. 3. Exa — 로컬 EXA_API_KEY, 또는 로그인한 Minara 세션 (플랫폼 exaPassthrough). Tavily 와 Firecrawl 이 모두 없을 때만. 체인 폴스루는 없습니다. DuckDuckGo / Google / Brave / Anthropic 네이티브 경로와 HTML 페치 추출도 없습니다. 빈 결과와 HTTP 오류는 선택된 백엔드에 남습니다. JS 로 막힌 페이지는 browser_navigate / browser_snapshot 으로 갑니다. 고급 필터(Exa category, Firecrawl sources/tbs, Tavily topic/depth)는 활성 백엔드의 도구 스키마에만 나타납니다.

`EXA_API_KEY`

Exa 웹 검색 및 추출 (Tavily 와 Firecrawl 다음).

제어 대상: Tavily 와 Firecrawl 을 모두 쓸 수 없을 때의 web_search / web_extract 백엔드입니다. 로컬 키가 있으면 직접 사용하고(플랫폼 패스스루보다 우선), 없으면 로그인한 Minara 세션이 플랫폼 exaPassthrough 로 Exa 를 실행합니다. Exa 는 뉴럴 검색 인덱스이며 검색 결과에 하이라이트가 붙습니다. 추출은 /contents(깨끗한 페이지 텍스트)입니다. 실패해도 다른 백엔드로 넘어가지 않습니다.
사용처: src/tools/web-backends.ts (src/app.ts의 createWebTools() 경유).
설정 시점: Minara 로그인 없이 로컬에서 Exa 를 쓰고 싶을 때 설정합니다.
미설정 시: Tavily 키가 있으면 Tavily, 없으면 Firecrawl, 없으면 로그인해 있을 때 Exa 입니다. 셋 다 없으면 도구가 숨겨집니다.
형식: https://dashboard.exa.ai/api-keys 에서 발급받은 Exa API 키.
설정 위치: 설정 → API 키

`FIRECRAWL_API_KEY`

Firecrawl 검색 + 추출 (Tavily 다음).

제어 대상: Tavily 를 쓸 수 없을 때 web_search / web_extract 백엔드입니다. /search 는 제목/URL, /scrape 는 깔끔한 markdown(onlyMainContent: true)을 반환합니다.
사용처: src/tools/web-backends.ts (src/app.ts의 createWebTools() 경유).
설정 시점: Tavily 없이 검색과 고품질 전체 페이지 추출을 함께 쓰려는 경우입니다.
미설정 시: Firecrawl 을 건너뛰고, 로컬 Exa 키가 있거나 로그인해 있으면 Exa 를 사용합니다.
Free tier: 월 500 크레딧. 형식: https://www.firecrawl.dev/app/api-keys 에서 발급받은 Firecrawl API 키.
설정 위치: 설정 → API 키

`TAVILY_API_KEY`

Tavily 웹 검색 및 추출 (최우선순위).

제어 대상: web_search 와 web_extract 의 기본 백엔드입니다. 실패해도 Firecrawl 이나 Exa 로 넘어가지 않습니다.
사용처: src/tools/web-backends.ts (src/app.ts의 createWebTools() 경유).
설정 시점: Tavily 를 웹 리서치 백엔드로 쓰려는 경우입니다.
미설정 시: Firecrawl 키가 있으면 Firecrawl, 없으면 Exa(로컬 키 또는 로그인 패스스루)입니다. 셋 다 없으면 web_search 와 web_extract 는 숨겨진 채로 남습니다. DuckDuckGo 폴백은 없습니다.
형식: https://tavily.com 에서 발급받은 Tavily API 키.
설정 위치: 설정 → API 키

`GOAL_MAX_TURNS`

검토를 위해 일시 중지하기 전, 상시 /goal이 자동으로 이어서 진행할 수 있는 최대 턴 수입니다(REPL goal 모드).

미설정 시 기본값: 20
형식: 양의 정수
설정 위치: 설정 → 환경설정 (schema 키)

`POSITION_MEMORY_ENABLED`

포지션/세션 인식 메모리 주입입니다. 활성화되면 자산이 관련된 각 채팅 턴(메시지 내 티커, 또는 사용자의 최근 현물 상위 심볼 중 하나)에서 해당 자산에 대해 저장된 메모리를 최대 5개까지 휘발성 프롬프트 tail에 주입합니다 — 조언성 질문에는 과거 견해와 매매 노트를, 펀더멘털성 질문에는 사용자의 분석 선호와 습관을 주입합니다. 결정론적이며 로컬에서 동작합니다(키워드 인텐트 라우팅 + SQLite 조회, 추가 LLM 호출 없음). 트레이딩 시그널은 trading-summary 재빌드로 갱신되는 사전 구축된 현물 상위 심볼 아티팩트에서 가져옵니다. memory/position-memory.ts를 통해 app.ts에서 사용됩니다(positionMemoryProvider). preferences 매니저를 통해 실시간으로 읽으므로 전환하면 다음 턴부터 적용됩니다.

미설정 시 기본값: off
형식: 활성화하려면 1/true/yes/on
설정 위치: 설정 → 환경설정 (schema 키)

`OPENAI_API_KEY`

OpenAI 플랫폼 키, 다목적.

제어 대상: (1) research.knowledge_base 스킬 — text-embedding-3-* 임베딩을 Qdrant에 기록합니다. (2) src/tools/audio.ts의 오디오 TTS. (3) 선택적 LLM provider(옵트인) — OpenAI OAuth 경로와는 구별됩니다. 이 env만 설정한다고 OpenAI가 LLM provider로 자동 선택되지는 않습니다. LLM 경로를 활성화하려면 minara auth login openai --api-key $OPENAI_API_KEY를 실행하며, 이는 openaiApiKey 프로필 슬롯에 기록합니다.
사용처: src/skills/builtin/research/knowledge-base.ts, src/tools/audio.ts, src/llm/openai-api-key.ts.
미설정 시: research KB 기록은 건너뛰고, TTS는 사용할 수 없으며, LLM은 다른 provider를 사용합니다.
형식: https://platform.openai.com 에서 발급받은 sk-....
설정 위치: LLM 공급자 자격 증명 (설정 → 공급자 및 모델)

`OPENAI_BASE_URL`

OpenAI API base URL의 선택적 재정의.

제어 대상: OpenAI api-key LLM 클라이언트 + 도구가 호출하는 대상입니다.
기본값: https://api.openai.com/v1
설정 시점: Azure OpenAI 호환 게이트웨이나 동일한 wire 형태를 갖는 기업 프록시를 대상으로 하는 경우입니다.
미설정 시: 공식 OpenAI 엔드포인트가 사용됩니다.
설정 위치: 사용자 대상 설정 아님

`OPENAI_ORG_ID`

선택적 OpenAI organization 헤더.

제어 대상: 모든 LLM 호출에 OpenAI-Organization으로 전송됩니다.
설정 시점: OpenAI 계정에 여러 조직이 있고 특정 조직으로 청구를 라우팅하려는 경우입니다.
미설정 시: API 키에 연결된 기본 조직이 사용됩니다.
설정 위치: 사용자 대상 설정 아님

`FAL_KEY` / `FAL_QUEUE_URL`

Fal.ai 이미지/미디어 provider.

제어 대상: image_generate, video_generate 및 실시간 이미지/동영상 모델 카탈로그를 위한 Fal.ai 인증입니다.
사용처: src/media/* 및 미디어 생성 도구.
설정 시점: API 키 인증을 사용할 때 설정합니다. 또는 설정 > 제공업체 및 모델 > 이미지 및 동영상에서 Fal.ai로 로그인할 수 있습니다.
미설정 시: 미디어 생성을 사용하려면 Fal.ai 로그인이 필요합니다.
형식: FAL_KEY는 https://fal.ai 에서 발급받은 불투명 문자열입니다. FAL_QUEUE_URL은 큐 엔드포인트의 선택적 재정의입니다(절대 URL이며, 프라이빗 Fal.ai 배포를 사용하는 경우에만 설정).
설정 위치: 설정 → API 키 (FAL_KEY)
설정 위치: 사용자 대상 설정 아님 (FAL_QUEUE_URL)

메시징 게이트웨이

send_message 도구, 워크플로 트리거, 오토파일럿 리포트가 사용하는 아웃바운드 알림 대상입니다. 여러 제공자를 동시에 구성할 수 있으며, LLM 이 provider 인자로 호출마다 하나를 선택하고 MESSAGING_DEFAULT_PROVIDER 로 폴백합니다. minara auth messaging add <provider> 사용을 권장합니다 — 마법사가 자격 증명을 ~/.minara/credentials.json (messaging 슬롯) 에 저장하며 이 파일은 건드리지 않습니다.

`MESSAGING_DEFAULT_PROVIDER`

호출자가 provider 인자를 생략했을 때 send_message가 사용하는 기본 provider입니다.

제어 대상: 명시적 provider 없이 이루어진 agent-loop / workflow / autopilot의 send_message 호출이 이 id로 라우팅됩니다.
사용처: src/app.ts(게이트웨이 맵 구성), src/tools/messaging.ts(핸들러 디스패치).
설정 시점: 둘 이상의 provider를 구성했고 특정 하나를 기본값으로 지정하려는 경우입니다(예: 개인 알림은 telegram, 팀 알림은 slack — 그리고 기본값으로 telegram을 원하는 경우).
미설정 시: 가장 먼저 구성된 provider가 선택됩니다(삽입 순서는 src/messaging/providers.ts의 MESSAGING_PROVIDERS를 따름 — telegram → discord → slack → whatsapp → signal → email → home_assistant).
형식: provider id — telegram, discord, slack, whatsapp, signal, email, home_assistant 중 하나입니다. 대소문자를 구분하지 않습니다.
설정 위치: 사용자 대상 설정 아님

`MESSAGING_MAX_ATTACHMENT_BYTES`

send_message({attachments: [...]}) 호출의 첨부파일당 크기 상한입니다.

제어 대상: 각 첨부파일이 해당 provider API로 업로드되기 전에 resolver가 샌드박스 파일 크기를 확인하고, 크기가 이 값을 초과하면 명확한 오류와 함께 거부합니다. 제한 없는 LLM 제어 경로가 대용량 파일로 SMTP 릴레이 / Discord / Telegram을 DOS 공격하는 것을 방지합니다.
사용처: src/messaging/attachment-resolver.ts.
설정 시점: 운영자가 50 MB 기본값을 더 엄격하게 조이려는 경우입니다(예: Slack 무료 등급의 1 GB 저장 용량 할당량, 또는 1분을 초과하는 오디오 차단).
미설정 시: 기본값은 52 428 800 바이트(50 MB)입니다. Provider API는 각자 최대치를 독립적으로 적용합니다 — 이 상한은 Minara 측 한도이며, provider는 자사 API가 너무 크다고 판단하는 파일을 여전히 거부할 수 있습니다.
형식: 10진 정수(바이트)입니다. 0 이하 값은 무시됩니다.
설정 위치: 사용자 대상 설정 아님

`TELEGRAM_BOT_TOKEN` / `TELEGRAM_CHAT_ID`

아웃바운드 Telegram 메시징.

제어 대상: send_message 도구가 Bot API를 통해 지정된 채팅에 게시합니다. 워크플로 알림 및 경고 출력에 사용됩니다. Telegram은 현재 스트리밍 편집 지원이 기본 내장된 유일한 provider입니다(게이트웨이의 streamDefaultIntervalMs 참조).
사용처: src/messaging/telegram.ts.
설정 시점: 에이전트(또는 워크플로 트리거)가 Telegram 채널이나 DM으로 경고를 푸시하기를 원하는 경우입니다.
미설정 시: send_message는 다른 전송 수단에는 계속 작동하지만 Telegram 경로는 명확한 구성 오류를 반환합니다.
형식: TELEGRAM_BOT_TOKEN은 @BotFather에서 발급받은 123456:ABC-DEF... 문자열입니다. TELEGRAM_CHAT_ID는 숫자 채팅 id입니다(채널/그룹은 음수, DM은 양수).
설정 위치: 설정 → 메시징

`TELEGRAM_RICH_TEXT`

아웃바운드 응답을 Telegram 리치 텍스트로 렌더링합니다.

제어 대상: 활성화되면(기본값), markdown 응답이 Telegram HTML로 렌더링되며(굵게, 제목, 표, 코드 블록, 작업 목록), Telegram이 마크업을 거부하면 MarkdownV2 → 일반 텍스트로 폴백합니다. 스트리밍 편집은 완전히 닫힌 구성 요소만 flush하므로 사용자가 절반만 렌더링된 서식을 보는 일이 없습니다.
사용처: src/messaging/telegram.ts.
설정 시점: 에이전트의 텍스트를 서식 없이 그대로 보내려면 false(또는 0/no/off)로 설정합니다.
미설정 시: 리치 텍스트가 켜집니다.
설정 위치: 설정 → 환경설정 (schema 키)

`SLACK_BOT_TOKEN` / `SLACK_CHANNEL_ID`

아웃바운드 Slack.

제어 대상: provider: "slack"가 요청되면(또는 slack이 기본값일 때) send_message 도구가 Slack으로 라우팅됩니다. 아웃바운드는 공유되는 Vercel Chat SDK Slack 어댑터가 처리합니다: SLACK_BOT_TOKEN이 전송과 post+edit 스트리밍을 담당하고, SLACK_CHANNEL_ID가 기본 대상 채널입니다. 아래의 SLACK_APP_TOKEN과 함께 사용해 Socket Mode 인바운드 스트림을 엽니다.
사용처: src/messaging/chatsdk/adapters/slack.ts.
설정 시점: 팀 / 업무 알림 및 Slack 양방향 채팅에 설정합니다.
미설정 시: send_message의 Slack 경로를 사용할 수 없습니다. 다른 provider는 계속 작동합니다.
형식: SLACK_BOT_TOKEN은 xoxb-로 시작합니다. SLACK_CHANNEL_ID는 C... 채널 id입니다(#name이 아님).
설정 위치: 설정 → 메시징

`SLACK_APP_TOKEN`

Socket Mode 인바운드용 앱 레벨 토큰(xapp-…).

제어 대상: 클라이언트 아웃바운드 Slack 인바운드 데몬(Socket Mode)을 활성화합니다. 이 값이 설정되면 에이전트가 Slack으로 WebSocket을 열어 Events API 메시지를 수신합니다 — 공개 Request URL / webhook 서버가 필요 없으므로, 공개 IP가 없는 머신에서도 양방향 채팅이 작동합니다. SLACK_BOT_TOKEN과 함께 사용합니다(응답 전송에 사용됨).
사용처: src/messaging/inbound/slack-daemon.ts.
설정 시점: 공개 webhook을 노출하지 않고 Slack 양방향 채팅을 원하는 경우입니다(예: 노트북에서 실행 / NAT 뒤). Slack 앱 설정의 "Socket Mode" / "App-Level Tokens"에서 connections:write 스코프로 생성합니다.
미설정 시: Slack 인바운드가 webhook 경로로 폴백합니다(공개 Request URL + SLACK_SIGNING_SECRET 필요).
형식: xapp-1-....
설정 위치: 설정 → 메시징

`DISCORD_BOT_TOKEN` / `DISCORD_CHANNEL_ID`

아웃바운드 Discord.

제어 대상: provider: "discord"가 요청되면(또는 discord가 기본값일 때) send_message 도구가 Discord로 라우팅됩니다. PATCH /channels/{id}/messages/{id}를 통한 스트리밍 편집을 1000ms 스로틀로 지원합니다(Discord 레이트 리밋 = 채널당 5/5초).
사용처: src/messaging/discord.ts.
설정 시점: 커뮤니티 서버 알림, Discord 중심 팀.
미설정 시: send_message의 Discord 경로를 사용할 수 없습니다.
형식: DISCORD_BOT_TOKEN은 Developer Portal 앱 페이지에서 발급받은 불투명 bot 시크릿입니다. DISCORD_CHANNEL_ID는 숫자 채널 snowflake입니다. bot은 Send Messages + Manage Messages 권한으로 서버 + 채널에 초대되어 있어야 합니다(Manage Messages는 스트리밍 편집에 의존하는 경우에만 필요).
설정 위치: 설정 → 메시징

`HASS_URL` / `HASS_TOKEN` / `HASS_NOTIFY_SERVICE`

Home Assistant 알림.

제어 대상: provider: "home_assistant"가 요청되면 send_message 도구가 Home Assistant의 알림 플랫폼으로 라우팅됩니다. 스트리밍을 지원하지 않으며(notify.*는 fire-and-forget), 헬퍼가 마무리 시점에 단일 전송으로 폴백합니다.
사용처: src/messaging/home_assistant.ts.
설정 시점: 매매 경고를 휴대폰 푸시 / Alexa TTS / 기타 Home Assistant 매개 엔드포인트로 푸시하려는 경우입니다.
미설정 시: send_message의 Home Assistant 경로를 사용할 수 없습니다.
형식: HASS_URL은 전체 base URL입니다(https://hass.example:8123, 끝에 슬래시 없음). HASS_TOKEN은 HA 프로필에서 발급받은 장기 액세스 토큰입니다. HASS_NOTIFY_SERVICE는 notify 서비스 id입니다(mobile_app_pixel, alexa_tts. 앞의 notify.는 선택 사항이며 어댑터가 제거함).
설정 위치: 설정 → 메시징

`SMTP_HOST` / `SMTP_PORT` / `SMTP_USER` / `SMTP_PASSWORD` / `EMAIL_FROM` / `EMAIL_TO`

아웃바운드 이메일(SMTP).

제어 대상: provider: "email"가 요청되면 send_message 도구가 이메일로 라우팅됩니다. 제목은 메시지의 첫 줄에서 추론합니다(≤ 120자, 단일 줄) — 그렇지 않으면 "Minara alert"로 폴백합니다. 스트리밍 편집을 지원하지 않습니다.
사용처: src/messaging/email.ts(MIT 라이선스 nodemailer를 래핑).
설정 시점: 규정 준수 / 아카이빙 채널, 또는 대상 수신자가 채팅 플랫폼 중 하나를 사용하지 않는 경우입니다.
미설정 시: send_message의 이메일 경로를 사용할 수 없습니다. 다른 provider는 계속 작동합니다.
형식: SMTP_HOST는 릴레이 호스트명입니다. SMTP_PORT는 STARTTLS의 경우 587, SSL의 경우 465입니다(어댑터가 포트로 TLS 모드를 선택함 — port === 465일 때만 secure: true). SMTP_USER / SMTP_PASSWORD는 자격 증명입니다(Gmail은 앱 전용 비밀번호 사용). EMAIL_FROM은 From 헤더 주소입니다. EMAIL_TO는 기본 수신자입니다(channel을 통해 메시지별로 재정의 가능).
설정 위치: 설정 → 메시징

`GOOGLE_OAUTH_CLIENT_ID` / `GOOGLE_OAUTH_CLIENT_SECRET`

"Email (Gmail)" 원클릭 연결을 구동하는 운영자 제공 Google OAuth 클라이언트입니다(provider id email-gmail).

제어 대상: Settings → Messaging의 Connect-Gmail 버튼을 활성화합니다. 그러면 에이전트가 좁은 gmail.send 스코프를 사용하여 Gmail API를 통해 알림을 전송합니다(메일을 읽지 않음).
사용처: src/gateway/api.ts(OAuth 초기화) + src/messaging/gmail.ts.
설정 시점: Gmail 커넥터를 제공하려는 경우입니다. Google Cloud 콘솔에서 OAuth 클라이언트를 생성하고(유형 "Desktop app", loopback redirect), ID + 시크릿을 여기 또는 Email (Gmail) 패널에 직접 붙여넣습니다. 우선순위는 다른 모든 메시징 자격 증명과 동일합니다: export된 env 변수가 우선하며, 그 외에는 UI에 저장된 값이 사용됩니다.
설정되지 않은 경우(그리고 UI에도 입력되지 않은 경우): Connect-Gmail 버튼이 비활성화됩니다. 다른 provider는 계속 작동합니다.
preferences-schema-coverage: SKIP — 메시징 provider 자격 증명은 Preferences 스키마가 아니라 Settings → Messaging에서 관리됩니다(SMTP_* / TELEGRAM_*와 동일).
설정 위치: 설정 → 메시징

`GMAIL_REFRESH_TOKEN` / `GMAIL_SENDER_EMAIL` / `GMAIL_TO`

Gmail 연결 상태입니다. GMAIL_REFRESH_TOKEN과 GMAIL_SENDER_EMAIL은 Connect-Gmail 플로에서 기록됩니다(직접 설정할 필요 없음). GMAIL_TO는 선택적 수신자 재정의입니다 — 비워 두면 연결된 받은편지함 자체로 알림을 푸시합니다(push-to-self). preferences-schema-coverage: SKIP — 위의 GOOGLE_OAUTH_CLIENT_ID 참조.

설정 위치: 설정 → 메시징

`WHATSAPP_ACCESS_TOKEN` / `WHATSAPP_PHONE_NUMBER_ID` / `WHATSAPP_RECIPIENT`

Meta Cloud API를 통한 아웃바운드 WhatsApp.

제어 대상: provider: "whatsapp"가 요청되면 send_message 도구가 WhatsApp으로 라우팅됩니다. 스트리밍 편집을 지원하지 않습니다(Meta의 편집 API는 15분 윈도우 + 엄격한 레이트 리밋이 있어 LLM 토큰 스트리밍에 적합하지 않음).
사용처: src/messaging/whatsapp.ts.
설정 시점: WhatsApp Business API 액세스가 있는 Meta Business 앱을 프로비저닝했고 WhatsApp을 통해 알림을 전달해야 하는 경우입니다.
미설정 시: send_message의 whatsapp 경로를 사용할 수 없습니다.
형식: WHATSAPP_ACCESS_TOKEN은 Meta Developer Portal 또는 Business System User가 발급한 길고 불투명한 Bearer 토큰입니다(보통 EAA...로 시작). WHATSAPP_PHONE_NUMBER_ID는 등록된 비즈니스 전화번호의 숫자 id입니다. WHATSAPP_RECIPIENT은 E.164 형식의 기본 수신자입니다(+12025551234) — send_message의 channel 인자가 호출별로 이를 재정의합니다.
Note: 수신자는 활성화된 24시간 고객 서비스 윈도우가 있거나 사전 승인된 템플릿 메시지를 받아야 합니다 — 이는 우리가 아니라 Meta의 정책 제약입니다. 일반 텍스트 메시지는 사용자가 지난 24시간 이내에 해당 비즈니스에 메시지를 보낸 경우에만 작동합니다.
설정 위치: 설정 → 메시징

`SIGNAL_CLI_NUMBER` / `SIGNAL_RECIPIENT` / `SIGNAL_CLI_BINARY`

아웃바운드 Signal.

제어 대상: provider: "signal"가 요청되면 send_message 도구가 Signal로 라우팅됩니다. 다른 모든 provider와 달리 Signal에는 HTTP API가 없어 — Minara가 로컬에서 signal-cli로 셸 아웃합니다(MIT 라이선스, https://github.com/AsamK/signal-cli). 스트리밍 편집을 지원하지 않습니다(Signal 프로토콜은 편집을 허용하지 않음).
사용처: src/messaging/signal.ts.
설정 시점: 프라이버시 중심 경고를 Signal 수신자에게 보내려 하고 호스트에 signal-cli 도구가 있는 경우입니다.
미설정 시: send_message의 signal 경로를 사용할 수 없습니다.
Runtime dependency: signal-cli가 설치되어 있고 PATH에 있어야 합니다 (macOS: brew install signal-cli; Debian: 업스트림 저장소 참조). 처음 사용하기 전에 발신 번호를 등록합니다: signal-cli -u +15555550100 register 그런 다음 휴대폰으로 도착하는 SMS 코드를 입력합니다. 앱 부팅 시 바이너리가 없으면 signal provider는 조용히 건너뛰며 — 다른 provider는 계속 작동합니다.
형식: SIGNAL_CLI_NUMBER와 SIGNAL_RECIPIENT는 모두 E.164 형식이어야 합니다(앞에 +, 국가 코드, 총 8-15자리 숫자, 공백이나 대시 없음 — 예: +12025551234). 어댑터는 생성 시점과 매 send() 호출마다 정규식을 검증하며, 수신자 앞에 --를 두는 고정 argv 레이아웃을 사용하여 앞 대시 플래그 주입을 차단합니다. SIGNAL_CLI_BINARY는 바이너리 경로의 선택적 재정의입니다 — 기본값은 signal-cli에 대한 PATH 조회입니다.
CLAUDE.md §4a Bucket B 예외: 이 모듈은 서브프로세스를 생성하지만 shell: false로 argv 형식을 사용하며, LLM 입력이 argv에 도달하지 않습니다 — 메시지 본문은 별도의 -m 슬롯을 통해 전달되고, 수신자는 기록되기 전에 정규식으로 검증됩니다.
설정 위치: 설정 → 메시징

인바운드 메시징 웹훅 (선택 사항, kill-switch 적용)

인바운드 리스너는 자동으로 시작되지 않습니다 — 호출자가 직접 InboundServer 를 인스턴스화합니다 (src/messaging/inbound/server.ts 참조). 활성화되면 Telegram, Discord, Slack 에서 오는 서명된 웹훅을 수신하고 정규화된 InboundMessage 이벤트를 등록된 단일 핸들러로 디스패치합니다. WhatsApp + Signal 인바운드는 이 PR 에서 연결되지 않았습니다 (WhatsApp 은 인증서 교환 핸드셰이크가 필요하고, Signal 은 signal-cli 데몬 JSON-RPC 소켓을 사용합니다 — 둘 다 별도 PR 로 다룰 가치가 있습니다).

`TELEGRAM_WEBHOOK_SECRET`

Telegram이 X-Telegram-Bot-Api-Secret-Token 헤더로 되돌려 보내는 공유 시크릿입니다. setWebhook의 secret_token 파라미터와 동시에 설정합니다.

제어 대상: 이 헤더가 없거나 일치하지 않는 요청은 핸들러가 실행되기 전에 401을 반환합니다.
미설정 시: /webhooks/telegram 경로가 404를 반환합니다 — 인바운드 서버는 Telegram 인바운드가 구성되지 않은 것처럼 동작합니다.
형식: 불투명 문자열, 1–256자(Telegram 자체 제약).
설정 위치: 사용자 대상 설정 아님

`SLACK_SIGNING_SECRET`

Slack 앱 서명 시크릿(bot token이 아님).

제어 대상: Slack이 공개한 방식에 따라 v0:{timestamp}:{body}에 대한 HMAC-SHA256을 사용하는 webhook 서명 검증입니다.
미설정 시: /webhooks/slack이 404를 반환합니다.
형식: Basic Information → App Credentials에서 발급받은 불투명 16진 문자열.
설정 위치: 설정 → 메시징

`DISCORD_PUBLIC_KEY` / `DISCORD_APPLICATION_ID`

Discord 앱 식별 정보.

제어 대상: Vercel Chat SDK Discord 어댑터의 생성자는 (Gateway 모드에서도) 애플리케이션 공개 키를 요구하므로, 어댑터를 빌드하려면 DISCORD_BOT_TOKEN과 함께 DISCORD_PUBLIC_KEY를 설정해야 합니다. DISCORD_APPLICATION_ID는 선택 사항으로, 슬래시 명령 등록을 위해 앱을 식별합니다.
미설정 시: Discord는 미구성으로 처리됩니다(공개 키 없이는 어댑터를 빌드할 수 없음).
형식: DISCORD_PUBLIC_KEY는 64자 소문자 16진(원시 32바이트 Ed25519 공개 키). DISCORD_APPLICATION_ID는 숫자 앱 id입니다.
설정 위치: 설정 → 메시징

`WHATSAPP_APP_SECRET` / `WHATSAPP_VERIFY_TOKEN`

WhatsApp Cloud API 인바운드 webhook(Meta).

제어 대상: - WHATSAPP_APP_SECRET는 X-Hub-Signature-256을 통해 모든 POST에 서명합니다 (원시 본문에 대한 HMAC-SHA256). 잘못된 서명 → 401. - WHATSAPP_VERIFY_TOKEN은 운영자가 Meta 대시보드에 webhook URL을 등록할 때 일회성 GET 핸드셰이크에서 되돌려 보내지는 Meta hub.verify_token입니다.
미설정 시: - WHATSAPP_APP_SECRET 누락 → /webhooks/whatsapp POST = 404. - WHATSAPP_VERIFY_TOKEN 누락 → /webhooks/whatsapp GET = 404.
형식: 불투명 문자열입니다. 앱 시크릿은 Meta 앱 대시보드에서 발급받은 16진값이고, verify token은 사용자가 구성한 값입니다.
설정 위치: 설정 → 메시징

PR2: 아시아 IM 플랫폼 (Lark / WeCom / DingTalk / WeChat OA / QQ / LINE)

각 블록은 src/messaging/inbound/specs/<id>.ts 가 필요로 하는 아웃바운드 자격 증명과 인바운드 웹훅 시크릿을 모두 설정합니다. 어느 블록이든 비워 두면 해당 제공자의 아웃바운드 + 인바운드가 모두 비활성화됩니다. 라우트는 404 를 반환하고 게이트웨이는 라이브 맵에서 제외됩니다.

`LARK_APP_ID` / `LARK_APP_SECRET` / `LARK_DEFAULT_CHAT_ID` / `LARK_VERIFICATION_TOKEN` / `LARK_ENCRYPT_KEY` / `LARK_DOMAIN`

Lark / Feishu — LARK_*. 테넌트 토큰 아웃바운드 + 서명/암호화된 webhook 이벤트.

제어 대상: 아웃바운드 Lark IM 메시징. agent-loop를 위한 인바운드 webhook 이벤트(im.message.receive_v1).
사용처: src/messaging/lark.ts + src/messaging/inbound/specs/lark.ts.
형식: LARK_APP_ID — Lark 개발자 콘솔의 cli_xxxxx. LARK_APP_SECRET — 같은 콘솔의 불투명 시크릿. LARK_DEFAULT_CHAT_ID — 기본 oc_xxxxx 채팅 id. LARK_VERIFICATION_TOKEN — Event Subscription 검증 토큰. LARK_ENCRYPT_KEY — 선택적 Event Subscription 암호화 키입니다. 설정되면 인바운드 POST 본문이 SHA256(encrypt_key) 기반 AES-256-CBC로 암호화되어 도착합니다. 평문 모드는 비워 둡니다. LARK_DOMAIN — open.feishu.cn(기본값, 중국 본토) 또는 open.larksuite.com(국제).
설정 위치: 설정 → 메시징

`WECOM_CORP_ID` / `WECOM_AGENT_ID` / `WECOM_SECRET` / `WECOM_DEFAULT_TOUSER` / `WECOM_CALLBACK_TOKEN` / `WECOM_CALLBACK_AES_KEY`

WeCom (企业微信) 자체 구축 애플리케이션.

제어 대상: WeCom 사용자 / 부서로의 아웃바운드 + 서명된 AES 암호화 콜백 인바운드입니다. WeCom은 두 서피스 모두 WeChat OA와 동일한 레거시 SHA1+AES 봉투를 통해 라우팅합니다.
사용처: src/messaging/wecom.ts + src/messaging/inbound/specs/wecom.ts.
형식: WECOM_CORP_ID — "我的企业" 페이지의 corp ID. WECOM_AGENT_ID — 애플리케이션 agent ID(숫자). WECOM_SECRET — 애플리케이션 시크릿. WECOM_DEFAULT_TOUSER — 기본 수신자(전체 에이전트는 @all). WECOM_CALLBACK_TOKEN — "接收消息" 콜백 구성의 Token. WECOM_CALLBACK_AES_KEY — 같은 페이지의 43자 EncodingAESKey.
설정 위치: 설정 → 메시징

`DINGTALK_WEBHOOK_URL` / `DINGTALK_WEBHOOK_SECRET`

DingTalk (钉钉) 커스텀 그룹 로봇 — HMAC 서명을 포함한 아웃바운드 webhook.

제어 대상: 로봇의 webhook URL을 통한 DingTalk 그룹으로의 아웃바운드입니다(DingTalk 사양에 따라 timestamp + secret으로 서명). 인바운드는 DingTalk이 다시 POST하는 outgoing-message webhook을 수신합니다.
사용처: src/messaging/dingtalk.ts + src/messaging/inbound/specs/dingtalk.ts.
형식: DINGTALK_WEBHOOK_URL — https://oapi.dingtalk.com/robot/send?access_token=… URL. DINGTALK_WEBHOOK_SECRET — "签名" 모드의 SECxxxx 서명 시크릿.
설정 위치: 설정 → 메시징

`DINGTALK_STREAM_APP_KEY` / `DINGTALK_STREAM_APP_SECRET`

Stream Mode 인바운드.

제어 대상: 클라이언트 아웃바운드 DingTalk Stream Mode 데몬을 활성화합니다. 둘 다 설정되면 에이전트가 게이트웨이 WebSocket을 열어 그 위로 bot 메시지를 수신합니다 — 공개 콜백 URL이 필요 없으므로 공개 IP가 없는 머신에서도 양방향 채팅이 작동합니다. 위의 로봇 webhook과 구별됩니다: Stream Mode는 조직 앱(AppKey / AppSecret)으로 인증하며, 응답은 여전히 로봇 webhook을 통해 나갑니다.
사용처: src/messaging/inbound/dingtalk-daemon.ts.
설정 시점: 공개 콜백을 노출하지 않고 DingTalk 양방향 채팅을 원하는 경우입니다. AppKey / AppSecret은 DingTalk 개발자 콘솔의 앱 "凭证与基础信息" 페이지에서 찾을 수 있습니다.
미설정 시: DingTalk 인바운드가 outgoing-webhook 경로로 폴백합니다(공개 콜백 URL 필요).
형식: DingTalk 개발자 콘솔에서 발급받은 불투명 문자열.
설정 위치: 설정 → 메시징

`WECHAT_OA_APP_ID` / `WECHAT_OA_APP_SECRET` / `WECHAT_OA_TOKEN` / `WECHAT_OA_AES_KEY` / `WECHAT_OA_DEFAULT_OPENID`

WeChat OA (公众号) 고객 서비스 메시징.

제어 대상: 아웃바운드 고객 서비스 메시지입니다(사용자의 48시간 상호작용 윈도우 내에 있어야 하며 — 그 윈도우를 벗어나면 플랫폼이 errcode 45015를 반환함). 인바운드: 서명 + AES 암호화된 메시지 이벤트.
사용처: src/messaging/wechat_oa.ts + src/messaging/inbound/specs/wechat_oa.ts.
형식: WECHAT_OA_APP_ID / WECHAT_OA_APP_SECRET — OA AppID + AppSecret. WECHAT_OA_TOKEN — 公众平台 → 设置 → 服务器配置의 서버 구성 Token. WECHAT_OA_AES_KEY — 같은 페이지의 43자 EncodingAESKey. WECHAT_OA_DEFAULT_OPENID — 기본 수신자 openid.
설정 위치: 설정 → 메시징

`QQ_BOT_APP_ID` / `QQ_BOT_APP_SECRET` / `QQ_BOT_TOKEN` / `QQ_BOT_DEFAULT_CHANNEL_ID`

QQ Bot v2 (Official Bot OpenAPI).

RATE LIMIT WARNING: 공식 봇은 봇당 월 4개의 능동 메시지로만
제한되며, 하루 200개의 능동 DM, 그리고 채널당 하루 20개의
능동 서브 채널 메시지로 제한됩니다. 대부분의 상호작용은
사용자가 시작한 메시지 이후 ≤5초 이내의 수동 응답을 사용해야 하며,
능동 푸시는 중요한 경고용으로 예약되어 있습니다.
사용처: src/messaging/qq.ts + src/messaging/inbound/specs/qq.ts.
형식: QQ_BOT_APP_ID — bot AppID(숫자). QQ_BOT_APP_SECRET — bot Secret(아웃바운드 인증과 인바운드 Ed25519 서명 검증의 시드로 모두 사용됨). QQ_BOT_TOKEN — bot token(레거시 필드, 호환성을 위해 유지). QQ_BOT_DEFAULT_CHANNEL_ID — 기본 대상. 형식 <kind>:<id> 여기서 kind는 c2c | group | channel | dm. 접미사 없는 id는 기본적으로 channel:이 됩니다.
설정 위치: 설정 → 메시징

`LINE_CHANNEL_ACCESS_TOKEN` / `LINE_CHANNEL_SECRET` / `LINE_DEFAULT_USER_ID`

LINE Messaging API.

제어 대상: 아웃바운드 LINE 푸시 메시지(유료 종량제)와 서명된 인바운드 webhook 이벤트입니다. Reply token(무료)은 아직 연결되지 않아 — 모든 아웃바운드가 종량제 push API를 거칩니다.
사용처: src/messaging/line.ts + src/messaging/inbound/specs/line.ts.
형식: LINE_CHANNEL_ACCESS_TOKEN — LINE Developers의 장기 bearer. LINE_CHANNEL_SECRET — 인바운드에서 X-Line-Signature를 검증하는 데 사용되는 채널 시크릿(HMAC-SHA256, base64). LINE_DEFAULT_USER_ID — 기본 수신자 userId / groupId / roomId.
설정 위치: 설정 → 메시징

PR3: 서구권 IM + 페더레이션 (Mattermost / Teams / Google Chat / BlueBubbles / Matrix)

`MATTERMOST_URL` / `MATTERMOST_BOT_TOKEN` / `MATTERMOST_DEFAULT_CHANNEL_ID` / `MATTERMOST_OUTGOING_WEBHOOK_TOKEN`

Mattermost — bot-token 아웃바운드 + outgoing-webhook 인바운드.

CAVEAT: Mattermost의 outgoing-webhook 기능은 오직 PUBLIC 채널에서만,
그리고 webhook에 구성된 TRIGGER WORD에 대해서만 작동합니다.
프라이빗 채널과 DM에는 WebSocket bot 경로가 필요합니다(향후 PR).
사용처: src/messaging/mattermost.ts + src/messaging/inbound/specs/mattermost.ts.
형식: MATTERMOST_URL — Mattermost 서버 URL(끝에 슬래시 없음). MATTERMOST_BOT_TOKEN — bot 계정의 personal access token. MATTERMOST_DEFAULT_CHANNEL_ID — 기본 대상 채널. MATTERMOST_OUTGOING_WEBHOOK_TOKEN — outgoing-webhook 본문의 token 필드와 비교되는 토큰(상수 시간).
설정 위치: 설정 → 메시징

`TEAMS_BOT_APP_ID` / `TEAMS_BOT_APP_PASSWORD` / `TEAMS_BOT_TENANT_ID` / `TEAMS_DEFAULT_CONVERSATION_ID` / `TEAMS_DEFAULT_SERVICE_URL`

Microsoft Teams — JWT 검증 인바운드를 갖춘 Bot Framework.

인바운드 JWT 검증은 다음에서 JWKS를 동적으로 가져옵니다:
https://login.botframework.com/v1/.well-known/openidconfiguration —
JWKS URL을 어디에도 하드코딩하지 마십시오. Microsoft가 이를 로테이션합니다.
사용처: src/messaging/teams.ts + src/messaging/inbound/specs/teams.ts.
형식: TEAMS_BOT_APP_ID — bot의 Microsoft App ID GUID. TEAMS_BOT_APP_PASSWORD — bot의 Microsoft App 비밀번호. TEAMS_BOT_TENANT_ID — 멀티테넌트는 common, 싱글테넌트는 GUID. TEAMS_DEFAULT_CONVERSATION_ID — 푸시할 기본 대화. TEAMS_DEFAULT_SERVICE_URL — 기본 Bot Framework serviceUrl (일반적으로 https://smba.trafficmanager.net/teams). 프로덕션 코드는 이를 인바운드 activity에서 학습하여 대화별로 유지해야 합니다. 이 env 변수는 부트스트랩 폴백입니다.
설정 위치: 설정 → 메시징

`GOOGLE_CHAT_CREDENTIALS` / `GOOGLE_CHAT_USE_ADC` / `GOOGLE_CHAT_PROJECT_NUMBER` / `GOOGLE_CHAT_DEFAULT_SPACE_ID`

Google Chat — Vercel Chat SDK 어댑터(서비스 계정 또는 ADC; webhook 인바운드).

제어 대상: 아웃바운드와 인바운드 모두 공유되는 Vercel Chat SDK Google Chat 어댑터가 처리합니다. 인바운드는 Google 서명 webhook / Pub/Sub 푸시이며, InboundServer가 /webhooks/google_chat 을 chat.webhooks.google_chat 으로 전달합니다 (MESSAGING_INBOUND_ENABLED=1 필요).
사용처: src/messaging/chatsdk/adapters/google_chat.ts.
형식: GOOGLE_CHAT_CREDENTIALS — 서비스 계정 자격 증명 JSON(또는 키 파일 경로)입니다. CLAUDE.md §4: 경로는 반드시 data / 샌드박스 트리 안에 있어야 하며, 운영자의 통제를 벗어난 경로를 참조하지 마십시오. GOOGLE_CHAT_USE_ADC — true 로 설정하면 애플리케이션 기본 자격 증명(ADC)을 사용합니다. GOOGLE_CHAT_DEFAULT_SPACE_ID — 기본 space 리소스 이름 (예: spaces/AAAA1234567).
설정 위치: 설정 → 메시징

`BLUEBUBBLES_SERVER_URL` / `BLUEBUBBLES_PASSWORD` / `BLUEBUBBLES_DEFAULT_CHAT_GUID`

BlueBubbles — 자체 호스팅 서버를 통한 iMessage 브리지.

운영자가 원하는 iMessage 계정에 로그인 상태를 유지하는 Mac에서
BlueBubbles 서버를 실행해야 합니다. 인증은
단일 공유 비밀번호이며 — 순수 상수 시간 비교, HMAC 없음.
사용처: src/messaging/bluebubbles.ts + src/messaging/inbound/specs/bluebubbles.ts.
형식: BLUEBUBBLES_SERVER_URL — BlueBubbles 서버의 공개 URL (일반적으로 ngrok / cloudflared 같은 터널). BLUEBUBBLES_PASSWORD — 서버 비밀번호(?guid= 쿼리와 일치). BLUEBUBBLES_DEFAULT_CHAT_GUID — 기본 채팅 GUID (예: iMessage;-;+15551234567).
설정 위치: 설정 → 메시징

`MATRIX_HOMESERVER` / `MATRIX_ACCESS_TOKEN` / `MATRIX_USER_ID` / `MATRIX_DEFAULT_ROOM_ID`

Matrix — 페더레이션 client-server API입니다. 인바운드는 MESSAGING_MATRIX_INBOUND로 게이팅되는 long-poll 데몬으로 실행됩니다(HTTP webhook 없음).

사용처: src/messaging/matrix.ts + src/messaging/inbound/matrix-daemon.ts.
형식: MATRIX_HOMESERVER — homeserver URL(예: https://matrix.org). MATRIX_ACCESS_TOKEN — 장기 액세스 토큰입니다. Bearer 헤더를 사용하고, 사용 중단된 ?access_token= 쿼리 형식은 사용하지 마십시오. MATRIX_USER_ID — bot 사용자(예: @bot:example.org). /sync에서 self-loop를 필터링하는 데 사용됩니다. MATRIX_DEFAULT_ROOM_ID — 기본 room id(예: !abc:example.org).
Caveats: 이 게이트웨이는 종단 간 암호화(E2EE)
room을 지원하지 않습니다. 평문 room만 데몬이 소비할 m.room.message
이벤트를 방출합니다.
설정 위치: 설정 → 메시징

`MESSAGING_MATRIX_INBOUND`

Matrix /sync 데몬의 kill-switch.

제어 대상: 설정되면 앱 부팅 시 Matrix room 메시지를 agent-loop 브리지로 방출하는 long-poll 리스너를 시작합니다.
사용처: src/app.ts의 provider 레지스트리 inboundDaemon 열거를 통한 src/messaging/inbound/matrix-daemon.ts.
형식: 1/true/yes/on(대소문자 구분 없음).
설정 위치: 설정 → 환경설정 (schema 키)

`MESSAGING_TELEGRAM_POLLING` / `MESSAGING_DISCORD_GATEWAY` / `MESSAGING_SLACK_SOCKET` / `MESSAGING_MATTERMOST_WS` / `MESSAGING_QQ_WS` / `MESSAGING_DINGTALK_STREAM` / `MESSAGING_LARK_WS`

클라이언트 아웃바운드 인바운드 데몬 — 재정의 스위치.

이 플랫폼들은 webhook(플랫폼이 공개 URL로 IN 연결)과
클라이언트 아웃바운드 데몬(에이전트가 OUT 연결하여 긴
연결 / 폴을 유지) 둘 다 지원합니다. 데몬은 공개 IP가 없는
개인 머신에서도 양방향 채팅이 작동하게 해줍니다 — 터널 없이,
제3자 없이.
기본적으로 각 데몬은 플랫폼의 아웃바운드 자격 증명이 구성되어
있고 해당 플랫폼에 공개 webhook이 연결되지 않은 경우
(즉, webhook 서명 시크릿이 설정되지 않았거나 MESSAGING_INBOUND_ENABLED가
꺼진 경우) 자동으로 시작됩니다. 플랫폼에 webhook을 구성하면 webhook
인바운드를 유지합니다. 이 스위치들은 그 자동 결정을 명시적으로
재정의하며 3-상태입니다: - 미설정 / 빈 값 → auto(위의 기본값) - 1/true/yes/on → 데몬을 강제로 ON - 0/false/no/off → 데몬을 강제로 OFF(webhook 전용 유지) MESSAGING_TELEGRAM_POLLING — Telegram getUpdates long-poll (src/messaging/inbound/telegram-daemon.ts). Webhook 신호: TELEGRAM_WEBHOOK_SECRET. MESSAGING_DISCORD_GATEWAY — Discord Gateway WebSocket. Interactions webhook이 처리할 수 없는 일반 채널 / DM 메시지도 전달합니다 (src/messaging/inbound/discord-daemon.ts). Discord 개발자 포털에서 권한이 필요한 "Message Content" 인텐트를 활성화해야 합니다. Webhook 신호: DISCORD_APPLICATION_PUBLIC_KEY. MESSAGING_SLACK_SOCKET — Slack Socket Mode. SLACK_APP_TOKEN이 필요합니다 (src/messaging/inbound/slack-daemon.ts). Webhook 신호: SLACK_SIGNING_SECRET. MESSAGING_MATTERMOST_WS — Mattermost v4 WebSocket bot. outgoing-webhook 경로가 도달할 수 없는 DM / 프라이빗 채널에도 도달합니다 (src/messaging/inbound/mattermost-daemon.ts). Webhook 신호: MATTERMOST_OUTGOING_WEBHOOK_TOKEN. MESSAGING_QQ_WS — QQ v2 gateway WebSocket (src/messaging/inbound/qq-daemon.ts). webhook 전용 신호가 없으므로 (QQ의 webhook은 아웃바운드 QQ_BOT_APP_SECRET을 재사용함), QQ가 구성되면 언제나 gateway 데몬이 선호됩니다. 대신 webhook을 사용하려면 MESSAGING_QQ_WS=0으로 설정합니다. MESSAGING_DINGTALK_STREAM — DingTalk Stream Mode. DINGTALK_STREAM_APP_KEY / _SECRET이 필요합니다 (src/messaging/inbound/dingtalk-daemon.ts). DINGTALK_WEBHOOK_SECRET은 webhook 인바운드가 아니라 아웃바운드 전송에 서명하므로 데몬을 억제하지 않습니다. webhook을 사용하려면 MESSAGING_DINGTALK_STREAM=0으로 설정합니다. MESSAGING_LARK_WS — 공식 SDK를 통한 Lark / Feishu 롱 커넥션 (src/messaging/inbound/lark-daemon.ts). Webhook 신호: LARK_VERIFICATION_TOKEN.
설정 위치: 사용자 대상 설정 아님

`MESSAGING_INBOUND_TRANSCRIBE`

인바운드 메시지의 음성 메시지 전사를 활성화합니다. OPENAI_API_KEY가 필요합니다.

제어 대상: 1/true/yes/on으로 설정되면 인바운드 음성 첨부파일이 다운로드되어 OpenAI Whisper로 전사되고, 전사 결과가 InboundMessage.text에 채워집니다. 원본 오디오는 attachments에 유지되므로 다운스트림 소비자가 재생할 수 있습니다.
사용처: src/messaging/inbound/transcribe.ts(후속 작업에서 인바운드 메시지 정규화기로부터 호출됨).
미설정 시: 음성 첨부파일이 빈 text로 도착하며, 원하는 라우팅은 호출자가 책임집니다.
형식: 1/true/yes/on(대소문자 구분 없음).
설정 위치: 설정 → 환경설정 (schema 키)

`MESSAGING_VOICE_REPLY`

스트리밍 텍스트에 더해, 인바운드 음성 노트에 음성 응답 첨부파일로 답변합니다.

제어 대상: 에이전트의 텍스트 응답이 마무리되면, 응답이 오디오로 합성되어 동일한 채널/스레드로 음성(또는 기능에 따라 audio/file) 첨부파일로 다시 전송됩니다. 인바운드 메시지 자체에 전사된 음성 첨부파일이 포함된 경우에만 실행됩니다. TTS 실패는 텍스트 응답을 절대 중단시키지 않습니다.
사용처: voice-delivery 헬퍼를 통한 src/messaging/inbound/agent-bridge.ts. 구성된 음성 provider(ELEVENLABS_API_KEY 또는 OPENAI_API_KEY)가 필요합니다.
형식: 1/true/yes/on(대소문자 구분 없음).
설정 위치: 설정 → 환경설정 (schema 키)

`ELEVENLABS_API_KEY`

ElevenLabs 음성 플랫폼 키.

제어 대상: 게이트웨이 /v1/voice/* 엔드포인트, 웹 소리내어 읽기, 메시징 음성 응답 전반에서 음성 합성(TTS, eleven_turbo_v2_5)과 전사(STT, Scribe)에 선호되는 provider입니다. 설정되면 음성에 대해 OpenAI보다 ElevenLabs가 자동 선택됩니다(더 낮은 지연). OpenAI는 폴백으로 남으며, OGG/Opus 음성 노트(Telegram)를 생성할 수 있는 유일한 provider입니다.
사용처: src/voice/resolve.ts.
미설정 시: 음성이 OPENAI_API_KEY로 폴백합니다. 그것도 설정되지 않으면 음성 기능을 사용할 수 없습니다(명확한 오류, 크래시 없음).
형식: https://elevenlabs.io 에서 발급받은 sk_....
설정 위치: 사용자 대상 설정 아님

`VOICE_COMPOSER_STT_PROVIDER` / `VOICE_COMPOSER_STT_MODEL` / `VOICE_CONVERSATION_STT_PROVIDER` / `VOICE_CONVERSATION_STT_MODEL` / `VOICE_FILE_STT_PROVIDER` / `VOICE_FILE_STT_MODEL` / `VOICE_REPLY_TTS_PROVIDER` / `VOICE_REPLY_TTS_MODEL`

시나리오별 음성 Provider 및 모델.

제어 대상: 입력창 받아쓰기, 핸즈프리 대화, 전체 오디오 파일/메시지, Agent 음성 답변을 각각 설정합니다. Provider 값은 auto, openai, elevenlabs입니다.
Defaults: 입력창/대화 기본값은 auto + gpt-live-transcribe, 파일/메시지는 auto + gpt-transcribe, 답변은 auto + Provider 권장 TTS 모델입니다.
Compatibility: VOICE_STT_PROVIDER/MODEL은 파일 시나리오, VOICE_TTS_PROVIDER/MODEL은 답변 시나리오의 호환 별칭입니다. 시나리오별 변수가 우선합니다.
사용처: src/voice/resolve.ts 및 /v1/voice/* Gateway 라우트.
설정 위치: 설정 → 환경설정 (schema 키)

`VOICE_TTS_PROVIDER`

음성 합성 벤더를 고정합니다.

제어 대상: TTS에 한해 자동 선택(ElevenLabs 우선, OpenAI 폴백)을 재정의합니다.
사용처: src/voice/resolve.ts(런타임 preference voice.ttsProvider).
형식: auto | elevenlabs | openai. 기본값: auto.
설정 위치: 설정 → 환경설정 (schema 키)

`VOICE_TTS_VOICE`

응답을 소리내어 읽을 때 사용되는 voice id.

제어 대상: PRIMARY TTS provider에 네이티브 voice id로 전달됩니다(ElevenLabs voice id, 또는 alloy 같은 OpenAI voice 이름). 폴백 provider는 각자의 기본 voice를 사용합니다.
사용처: src/voice/resolve.ts(런타임 preference voice.ttsVoice).
미설정 시: 프로젝트 기본 voice / OpenAI "alloy".
설정 위치: 설정 → 환경설정 (schema 키)

`VOICE_TTS_MODEL`

primary provider의 TTS 모델 id.

제어 대상: ElevenLabs 모델(Settings -> Voice models에서 선택되는 기본값이기도 함), 그리고 OpenAI가 primary일 때의 OpenAI 모델입니다. ElevenLabs 선택지: eleven_v3(가장 사람다움, 기본값), eleven_multilingual_v2, eleven_turbo_v2_5, eleven_flash_v2_5.
사용처: src/voice/settings.ts(ElevenLabs 기반) + src/voice/resolve.ts(OpenAI, 런타임 preference voice.ttsModel).
미설정 시: eleven_v3(ElevenLabs) / gpt-4o-mini-tts(OpenAI).
설정 위치: 설정 → 환경설정 (schema 키)

`VOICE_TTS_STABILITY` / `VOICE_TTS_SIMILARITY_BOOST` / `VOICE_TTS_STYLE` / `VOICE_TTS_SPEAKER_BOOST` / `VOICE_TTS_SPEED` / `VOICE_TTS_FAST_FIRST`

음성 전달 기본값(ElevenLabs voice_settings)입니다. 각각 BASE를 설정하며, Settings -> Voice models 슬라이더가 사용자별로 그 위에 재정의합니다.

사용처: src/voice/settings.ts. VOICE_TTS_STABILITY 0..1 — 낮을수록 생동감, 높을수록 안정적(기본값 0.6) VOICE_TTS_SIMILARITY_BOOST 0..1 — 음색에 대한 충실도(기본값 0.8) VOICE_TTS_STYLE 0..1 — 표현력 / 개성(기본값 0.45) VOICE_TTS_SPEAKER_BOOST 1/0 — 명료도 부스트(기본값 켜짐) VOICE_TTS_SPEED 0.7..1.2 — 재생 속도(기본값 0.9) VOICE_TTS_FAST_FIRST 1/0 — 각 응답의 첫 문장을 가장 빠른 모델로 읽어 음성이 더 빨리 시작되도록 함 (기본값 켜짐)
설정 위치: 사용자 대상 설정 아님

`VOICE_STT_PROVIDER`

음성-텍스트 변환 벤더를 고정합니다.

사용처: src/voice/resolve.ts(런타임 preference voice.sttProvider).
형식: auto | elevenlabs | openai. 기본값: auto.
설정 위치: 설정 → 환경설정 (schema 키)

`VOICE_FFMPEG_PATH`

음성 트랜스코드를 위한 선택적 ffmpeg 바이너리.

제어 대상: AMR 음성 형식(WeCom, 내장 전사가 없는 WeChat OA)은 STT 전에 ffmpeg를 거치며, WeCom 음성 응답은 mp3 → AMR로 트랜스코드합니다. 설정되지 않으면 PATH에서 "ffmpeg"를 조회하며, 둘 다 확인되지 않으면 해당 트랜스코드는 건너뛰고 영향을 받는 플랫폼은 우아하게 성능이 저하됩니다.
사용처: src/messaging/audio-transcode.ts.
설정 위치: 사용자 대상 설정 아님

`VOICE_STT_MODEL`

primary provider의 STT 모델 id.

사용처: src/voice/resolve.ts(런타임 preference voice.sttModel).
미설정 시: scribe_v1(ElevenLabs) / gpt-4o-mini-transcribe(OpenAI).
설정 위치: 설정 → 환경설정 (schema 키)

`TWITTERAPI_API_KEY`

서드파티 Twitter/X 스크래핑 provider.

제어 대상: twitterapi.io 스크래퍼를 통해 트윗, 프로필, 검색 결과를 읽습니다(레이트 리밋 있음, OAuth 불필요).
사용처: src/tools/providers/twitterapi.ts. requires_env를 통해 research.social.twitter 스킬을 게이팅합니다.
설정 시점: 개발자 앱을 소유하지 않고 research.social 스킬이 실시간 Twitter 데이터를 가져오기를 원하는 경우입니다.
미설정 시: research.social.twitter가 스킬 카탈로그에서 숨겨집니다.
형식: https://twitterapi.io 에서 발급받은 불투명 API 키.
X_API_BEARER_TOKEN(공식 X API)과는 구별됩니다 — 이것은
서드파티 스크래퍼로 가고, 다른 하나는 api.x.com/2에 직접
연결됩니다. 둘 중 하나 또는 둘 다 설정할 수 있습니다.
설정 위치: 설정 → API 키

`X_API_BEARER_TOKEN`

X (Twitter) 공식 API bearer 토큰.

제어 대상: api.x.com/2에 대한 읽기 전용 app-only 액세스입니다(검색, 조회, 타임라인).
사용처: src/tools/providers/x-api.ts. requires_env를 통해 내장 x.api 스킬을 게이팅합니다.
설정 시점: https://developer.x.com 에 개발자 앱을 소유하고 있으며, 에이전트가 twitterapi.io 스크래퍼 대신(또는 이에 더해) 공식 API에 연결하기를 원하는 경우입니다.
미설정 시: x.api 스킬이 카탈로그에서 숨겨집니다.
형식: console.x.com에서 발급받은 Bearer 토큰 — 길고 불투명한 문자열.
설정 위치: 설정 → API 키

`GLASSNODE_API_KEY`

Glassnode 온체인 분석.

제어 대상: 온체인 지표 엔드포인트입니다(SOPR, MVRV, realised cap, flows 등).
사용처: src/tools/providers/glassnode.ts. requires_env를 통해 research.onchain.glassnode 스킬을 게이팅합니다.
설정 시점: Glassnode 구독이 있고 에이전트가 온체인 지표를 직접 인용하기를 원하는 경우입니다.
미설정 시: glassnode 스킬이 카탈로그에서 숨겨집니다.
형식: https://glassnode.com 에서 발급받은 불투명 API 키.
설정 위치: 설정 → API 키

`QDRANT_URL` / `QDRANT_API_KEY`

research KB용 벡터 데이터베이스.

제어 대상: (1) research.knowledge_base 스킬 — 에이전트가 터미널에서 curl로 운영자가 큐레이션한 Qdrant 컬렉션(news, projects, people, docs)을 쿼리하도록 가르칩니다. (2) kb_search 도구 — 동일한 Qdrant 쿼리 경로를 감싼 최상위 래퍼로, institution 모드 분석가(news / fundamentals / sentiment)가 web_search로 폴백하기 전에 사용합니다.
사용처: src/skills/builtin/research-knowledge-base.ts(스킬)와 src/tools/kb-search.ts(institution 모드 도구). 둘 다 QDRANT_URL 존재 여부로 게이팅되며, kb_search는 구성된 임베딩 provider(EMBEDDING_PROVIDER + EMBEDDING_API_KEY)도 필요합니다.
설정 시점: 오픈 웹 검색이 반환하는 것보다 더 신선하거나 좁은 news + project 사실을 위해, 에이전트가 기존 v1로 채워진 Qdrant 인스턴스를 쿼리하기를 원하는 경우입니다.
미설정 시: knowledge_base 스킬이 카탈로그에서 숨겨지고 kb_search 도구가 등록되지 않습니다. Institution 분석가는 기존 web_search 로 폴백합니다(동작 변화 없음).
형식: QDRANT_URL은 절대 URL입니다(https://xxx.qdrant.io). QDRANT_API_KEY는 선택 사항입니다 — 배포에 인증이 필요한 경우에만 설정합니다(Qdrant Cloud는 필요하고, 로컬 docker는 대개 필요 없음).
설정 위치: 사용자 대상 설정 아님 (QDRANT_URL)
설정 위치: 설정 → API 키 (QDRANT_API_KEY)

`KB_EMBEDDING_PROVIDER` / `KB_EMBEDDING_API_KEY` / `KB_EMBEDDING_MODEL` / `KB_EMBEDDING_DIM`

kb_search 전용 KB 특화 Embedder 재정의입니다.

제어 대상: kb_search 쿼리 문자열을 Qdrant에 게시하기 전에 임베딩하는 데 사용되는 embedder입니다. 이 embedder는 Qdrant 컬렉션을 원래 채운 것과 반드시 일치해야 하며 — 차원이 일치하지 않으면 매 호출마다 Qdrant가 400을 반환합니다.
설정 시점: kb_search Qdrant 인스턴스가 메모리에 사용하는 것(EMBEDDING_PROVIDER / EMBEDDING_MODEL)과 다른 embedder로 채워진 경우에만 사용합니다. 일반적인 경우: v1 Qdrant는 OpenAI text-embedding-3-small(1536d)로 채워졌지만 메모리에는 voyage-3(1024d)를 사용하는 경우.
미설정 시: kb_search가 공유 embedder(EMBEDDING_PROVIDER + EMBEDDING_API_KEY + EMBEDDING_MODEL + EMBEDDING_DIM)로 폴백합니다. 메모리와 KB가 동일한 모델을 공유하면 재정의가 필요 없습니다.
형식: 위의 EMBEDDING_* 계열과 동일한 허용 값입니다. KB_EMBEDDING_API_KEY는 설정되지 않으면 EMBEDDING_API_KEY로 기본 설정됩니다(따라서 OpenAI 사용자는 provider + model 재정의만 설정하면 됨).
설정 위치: 사용자 대상 설정 아님 (KB_EMBEDDING_PROVIDER, KB_EMBEDDING_MODEL, KB_EMBEDDING_DIM)
설정 위치: 설정 → API 키 (KB_EMBEDDING_API_KEY)

`E2B_API_KEY`

Kernel 클라우드 브라우저 코디네이터(https://e2b.dev).

제어 대상: 워크벤치가 Kernel 클라우드 Chromium(코디네이터 샌드박스)을 시작하게 합니다. KERNEL_API_KEY와 함께 씁니다. 이 키는 셸·파일·execute_code를 게이트웨이 호스트에서 옮기지 않습니다.
사용처: 워크벤치 클라우드 브라우저 런타임(Kernel bootstrap)이 사용. 호출 시 해석(Settings → API Keys에 추가한 키는 재시작 없이 적용).
설정 시점: Desktop/CLI에서 로컬 브라우저 대신 Kernel Live View를 쓸 때. Hosted Web Browser 코디네이터에도 필요합니다.
미설정 시: 클라우드 브라우저 placement를 쓸 수 없고, 호스트가 허용하면 Desktop/CLI는 로컬 브라우저로 유지.
형식: https://e2b.dev 대시보드의 opaque 키.
Safety: bash를 위해 공유 org 키를 per-user hosted agent에 넣지 마세요. 셸은 게이트웨이 VM에 남습니다.
설정 위치: 설정 → API 키

`KERNEL_API_KEY`

KERNEL_API_KEY, Web Browser 워크벤치용 관리형 Chromium.

제어 대상: Web Browser 워크벤치가 사용하는 Kernel 클라우드 Chromium 세션을 생성합니다. 같은 세션이 임베디드 Live View와 Agent 브라우저 도구용 CDP 엔드포인트를 제공합니다.
사용처: 워크벤치 클라우드 브라우저 런타임에서 사용합니다. 호출 시점에 해석되므로 Settings > API Keys에 저장한 키는 재시작 없이 적용됩니다.
설정 시점: Web 사용자에게 대화형 원격 브라우저가 필요할 때 설정합니다. kernel-browser 코디네이터를 위해 E2B_API_KEY도 필요합니다.
미설정 시: Web Browser는 Kernel 공식 키 문서와 대시보드 링크가 있는 설정 화면을 표시합니다. Desktop 네이티브 Browser는 계속 사용할 수 있습니다.
형식: https://dashboard.onkernel.com 에서 생성한 불투명 API 키입니다.
설정 위치: 설정 → API 키

`WORKBENCH_E2B_SESSION_IDLE_SECONDS`

Web 클라우드 리소스 일시중지 유예 시간.

제어 대상: 마지막 Web 클라이언트가 Chat 또는 Institution 세션을 떠난 뒤 Gateway가 해당 세션의 클라우드 Browser를 일시중지하기까지 기다리는 시간입니다. 일시중지는 타임아웃까지 Kernel 세션을 유지합니다. 게이트웨이의 shell에는 영향이 없습니다.
사용처: Preferences computer.cloudSessionIdleSeconds → Gateway 워크벤치 클라우드 리소스 리퍼가 사용합니다. Desktop 네이티브 Browser와 Computer 세션은 이 설정을 사용하지 않습니다.
미설정 시 기본값: 60초(1분).
설정 시점: 느린 세션 전환에도 클라우드 상태를 유지하려면 늘리고, 더 빨리 일시중지하려면 줄이세요. Settings → Preferences를 우선하고 env는 덮어쓰기입니다. 유예 시간 내에 돌아오면 보류된 일시중지가 취소됩니다.
형식: 0부터 3600까지의 유한한 초 단위 숫자입니다. 잘못된 값이나 음수는 기본값 60초를 사용합니다. Terminal에는 영향이 없습니다.
설정 위치: 설정 → 환경설정 (schema 키)

`MINARA_HOST_KIND`

Gateway 호스트 분류 재정의.

제어 대상: Browser/Computer 백엔드 선택에 사용할 호스트 종류를 강제합니다: desktop | local-cli | hosted-e2b | web-remote.
사용처: src/computer/host.ts(currentHostKind)가 사용합니다. 배치, capability, Chromium 실행 정책, 사설 URL 규칙이 이 분류를 읽습니다.
미설정 시 기본값: 미설정 시 MINARA_DESKTOP_PID / computer bridge / CDP, E2B_SANDBOX_ID 또는 CREDENTIALS_DEK+/data, 그다음 GATEWAY_HOST로 추론하며, 아니면 local-cli입니다.
설정 시점: 테스트와 운영 진단 전용입니다. 프로덕션 Desktop과 hosted-e2b는 자동 신호에 의존하세요.
형식: 값은 desktop, local-cli, hosted-e2b, web-remote 중 하나입니다.
설정 위치: 사용자 대상 설정 아님

`MINARA_COMPUTER_BACKEND`

세션 런타임 고정(local / cloud / docker).

제어 대상: 세션 런타임(브라우저, 셸, 파일)을 local / cloud / docker로 고정하거나 auto(Desktop 로컬 우선)로 둡니다. 셸과 파일은 docker를 고정하지 않는 한 게이트웨이 프로세스를 따릅니다. cloud는 Kernel 클라우드 브라우저만 고릅니다. GUI 컴퓨터 사용은 Desktop만. hosted에서는 bash가 agent VM에서, 브라우저는 cloud로 돕니다.
사용처: Preferences computer.backend → src/computer/backends.ts(readSessionBackendOverride)와 세션 런타임 placement(SessionRuntimeStore 경유)가 사용합니다.
미설정 시 기본값: 미설정 시 자동: hosted → 로컬 셸 + 클라우드 브라우저; Desktop은 네이티브 브리지가 있으면 로컬 우선(클라우드 키가 있어도); 브리지 없는 Desktop은 E2B_API_KEY + KERNEL_API_KEY가 있으면 브라우저는 cloud, 없으면 local; local-cli는 항상 local(키는 명시적 Cloud 브라우저 고정만 가능하게 함). auto는 docker를 고르지 않습니다 — docker를 명시하세요.
설정 시점: Settings → Preferences → 세션 런타임을 권장. cloud는 Kernel 브라우저 강제(셸은 이 호스트); docker는 로컬 컨테이너(MINARA_DOCKER_SANDBOX_IMAGE 필요); local은 Desktop 브리지 강제(없으면 명확히 실패).
형식: auto, local, cloud, 또는 docker. 비움 / 미설정 = auto.
설정 위치: 설정 → 환경설정 (schema 키)

`MINARA_DOCKER_SANDBOX_IMAGE`

Docker 실행 백엔드 이미지.

제어 대상: 점착 docker 실행 백엔드(같은 컨테이너의 셸 + 파일 + execute_code)용 컨테이너 이미지. Preferences computer.backend=docker(또는 MINARA_COMPUTER_BACKEND=docker)로 선택 — 호출별 environment 오버라이드는 없습니다. 강화: 패키지 관리자에 필요한 최소를 제외한 capability 제거, no-new-privileges, PID 제한, 크기 제한 /tmp; 호스트 bind 마운트 없음, 호스트 env 전달 없음. 채팅 세션당 컨테이너 하나, 호출 간 재사용, 15분 유휴 후 제거.
사용처: src/tools/_execution/docker-environment.ts, src/app.ts의 ExecutionRouter 경유. 호출 시 해석.
설정 시점: 다른 클라우드 VM 없이 신뢰할 수 없는 코드에 강한 로컬 격리를 원할 때. 실행 중인 Docker(또는 Podman) 데몬 필요; CLI는 PATH와 일반적인 Docker Desktop 위치에서 찾습니다.
미설정 시: docker 백엔드를 쓸 수 없음; code/shell은 게이트웨이 호스트에서 실행.
형식: 필요한 언어 런타임이 있는 pull 가능한 이미지 참조, 예: python:3.12-slim 또는 node:22-slim.
Safety: 로컬 격리와 같은 자세 — 컨테이너가 보안 경계이며 environment_provision_credentials로 명시적으로 프로비저닝하지 않는 한 호스트 자격 증명을 갖지 않습니다. docker는 Preferences computer.backend=docker 고정으로만 선택(호출별 오버라이드 없음).
설정 위치: 사용자 대상 설정 아님

`MINARA_GITHUB_APP_CLIENT_ID`

Coding GitHub 로그인을 위한 공개 클라이언트 ID.

제어 대상: 구조화된 HTTPS Git 및 Pull Request용 GitHub App 디바이스 플로 자격 증명 Provider를 활성화합니다.
사용처: Desktop 릴리스 CI가 product-config.json에 포함하고 Desktop이 공개 값을 src/app/bootstrap.ts에 전달해 CodingGitService를 연결합니다. Shell 또는 프로젝트 .env 값은 개발용 재정의로 유지됩니다.
설정 시점: 디바이스 플로와 검토된 저장소 권한이 있는 Minara GitHub App을 등록한 경우 설정합니다.
미설정 시: 설정하지 않으면 GitHub 연결에 운영자 구성이 필요하며 로컬 SSH는 독립적으로 유지됩니다.
형식: 선택적인 제품 GitHub App client id(예: Iv1.example). client secret이 아닙니다.
설정 위치: 사용자 대상 설정 아님

`MINARA_FILTERED_SSH_AGENT`

Desktop 내부 SSH 권한 표시자.

제어 대상: SSH_AUTH_SOCK이 Desktop에서 관리하는 필터링 엔드포인트이며 소유자가 선택한 identity만 노출함을 표시합니다.
사용처: 로컬 SSH 자격 증명 Provider를 연결할 때 src/gateway/api.ts에서 읽습니다.
설정 시점: 수동으로 설정하지 않습니다. 필터링 SSH agent 프록시가 실행 중일 때만 Minara Desktop이 주입합니다.
미설정 시: 설정하지 않으면 제한되지 않은 환경 SSH agent를 신뢰하지 않고 로컬 SSH 자격 증명 Provider는 사용할 수 없습니다.
형식: 내부 값은 1이며 다른 값은 설정되지 않은 것으로 처리됩니다.
설정 위치: 사용자 대상 설정 아님

`MINARA_CLOUD_CREDENTIAL_FILES`

docker 실행 컨테이너에 프로비저닝되는 자격 증명 파일 — 운영자 선언, 업로드 전용.

제어 대상: environment_provision_credentials가 클라우드 VM에 업로드하는 파일 집합으로, 그곳에서 실행되는 코드가 인증할 수 있도록 합니다. 에이전트는 경로를 선택할 수 없으며 — 오직 이 config만 선택할 수 있습니다. 각 항목은 data 디렉터리 INSIDE의 파일을 절대 VM 대상 경로에 매핑합니다. 로컬 경로는 MINARA_DATA_DIR 기준 상대 경로여야 하며, 절대 경로, .. 순회, data 디렉터리를 벗어나는 심볼릭 링크는 파싱 시점에 항목별로 거부됩니다. 프로비저닝된 VM 경로는 업로드 전용입니다: environment_pull_file은 이를 다시 읽기를 거부하며, 파일 내용은 모델 컨텍스트에 절대 들어가지 않습니다.
사용처: src/tools/environment-files.ts를 통한 src/tools/_execution/credential-provision.ts.
설정 시점: 클라우드 VM에서 실행하는 코드가 API 키 파일 / 토큰 파일을 필요로 하는 경우입니다. 읽기 전용이고 영향 범위가 작은 자격 증명을 선호하십시오 — VM은 전체 네트워크 egress를 가집니다. 지갑 키나 자금 이동 자격 증명을 여기에 절대 선언하지 마십시오.
미설정 시: environment_provision_credentials가 파일이 없다고 보고하며, 클라우드 실행은 자격 증명이 없습니다(기본 태세).
형식: {"local": "<relative path>", "remote": "/abs/vm/path"} 형식의 JSON 배열입니다. 예: [{"local":"cloud-creds/market.json","remote":"/root/.creds/market.json"}]
설정 위치: 사용자 대상 설정 아님

목차