Cowork 환경변수로 외부 API 안전하게 연결하기

한 줄 요약

텔레그램 봇 토큰, 고객 DB 경로, OAuth 시크릿 같은 민감값은 절대 Skill·CLAUDE.md·코드에 직접 쓰지 마세요. 대신 Cowork 환경변수에 저장하고 env: 참조로 가져옵니다.

왜 환경변수가 필요한가

나쁜 예 — 직접 박힌 토큰

# SKILL.md 안에 또는 Python 블록에 직접
TELEGRAM_TOKEN = "123456:ABCdefGHIjklMNOpqr"  # 실제 봇 토큰
requests.post(f"https://api.telegram.org/bot{TELEGRAM_TOKEN}/sendMessage", ...)

무엇이 잘못됐나?

스킬을 동료에게 공유하면 내 토큰도 같이 공유됨
토큰이 바뀌면 모든 스킬을 수정해야 함
유출 시 누구의 토큰인지, 어디까지 퍼졌는지 추적 불가
감사·컴플라이언스 위반 (특히 금융·공공)

좋은 예 — 환경변수 참조

import os
token = os.environ["TELEGRAM_BOT_TOKEN"]
requests.post(f"https://api.telegram.org/bot{token}/sendMessage", ...)

또는 스킬 본문에서:

## 입력
- TELEGRAM_BOT_TOKEN: env:TELEGRAM_BOT_TOKEN  (환경변수에서 읽음)
- TELEGRAM_CHAT_ID: env:TELEGRAM_CHAT_ID

좋은 점:

스킬을 공유해도 토큰은 각자의 Cowork 환경변수 값을 씀
토큰 갱신은 Cowork 설정 한 곳만 바꾸면 끝
유출 발생 시 누구의 계정인지 감사 로그로 추적
자격증명이 스킬 파일에 없으므로 Git·스크린샷·공유 폴더 경유 유출 리스크 제거

Cowork 환경변수 기본 흐름

flowchart LR
  A[관리자] --> B[Cowork 설정]
  B --> C["환경변수 추가
KEY=VALUE"]
  C --> D[팀 공유 범위 선택]
  D --> S["스킬 실행 시
env:KEY 로 접근"]
  S --> E["외부 API
텔레그램/국세청/Drive"]

환경변수 네이밍 규칙

규칙	예시
대문자 + 밑줄	`TELEGRAM_BOT_TOKEN` (O) / `telegramToken` (X)
용도 접두사	`TELEGRAM_`, `OPENAI_`, `CLIENT_DB_*`
동사가 아닌 명사	`SMTP_HOST` (O) / `GET_SMTP` (X)
환경 구분	`DEV_`, `PROD_` — 개발·운영을 섞지 않기
접근 범위	팀 공유 vs 개인 전용을 반드시 구분

권장 템플릿

# 외부 서비스 자격증명
TELEGRAM_BOT_TOKEN=...
TELEGRAM_CHAT_ID=...
NOTION_API_KEY=...
SLACK_WEBHOOK_URL=...

# 내부 경로
CLIENT_DB_PATH=/cowork/data/clients.xlsx
FAQ_PATH=/cowork/docs/faq.md
TEMPLATE_DIR=/cowork/templates

# 설정
LOG_LEVEL=info
TIMEZONE=Asia/Seoul

공유 범위 전략

범위	적합한 값	예시
개인 전용	개인 계정 토큰·개인 OAuth	내 Gmail 연동, 내 Notion 토큰
팀 공유	팀 공통 서비스	부서 텔레그램 봇, 팀 공용 Notion 페이지
전사 공유	회사 공용 자원	회사 이메일 SMTP, 전사 공용 DB

원칙: 필요한 최소 범위로만 공유. 전사 공용이 팀 공용보다 "더 좋다"가 아닙니다. 범위가 넓을수록 사고 시 영향이 큽니다.

실수 회피 체크리스트

토큰을 채팅(카카오톡·Slack)에 붙여넣지 않기 — 채팅 기록이 증거로 남음
스크린샷을 찍을 때 Cowork 설정 화면은 마스킹
개발용·운영용 환경변수를 이름으로 구분 (DEV_*, PROD_*)
퇴사자 발생 시 개인 토큰 기반 환경변수는 즉시 교체
3개월 주기로 미사용 환경변수 정리
감사 로그에서 "누가 언제 이 환경변수에 접근했나" 주기적 확인 (Enterprise 플랜)

외부 API 연동 자주 쓰는 설정

텔레그램 봇

TELEGRAM_BOT_TOKEN=123456:ABCdef...
TELEGRAM_CHAT_ID=-100123456789  # 그룹이면 음수, 개인은 양수

봇 생성: @BotFather 에게 /newbot → 토큰 받음. 그룹에 초대 후 getUpdates API 로 chat_id 확인.

OpenWeatherMap / 환율 API

OPENWEATHER_API_KEY=...
EXCHANGE_API_KEY=...

무료 tier 로도 일 1000회 정도는 충분. Track B 일일 브리핑에 적합.

Notion

NOTION_API_KEY=secret_...
NOTION_WORKSPACE_ID=...

Notion 커넥터를 쓰면 API 키 대신 OAuth로 자동 관리되므로 더 안전. 단 설정이 약간 더 복잡.

내부 공유 파일 경로

CLIENT_DB_PATH=/cowork/shared/tax-firm/clients.xlsx

파일 자체는 Cowork 공유 폴더에, 경로만 환경변수로. 파일이 이동해도 환경변수만 수정.

자주 묻는 질문

Q. Desktop(Pro 플랜)에서는 환경변수 기능이 없나요?

A. Desktop 은 OS 환경변수를 읽을 수 있지만, Cowork 의 팀 공유 기능은 없습니다. 개인 작업에는 로컬 .env 파일로 대체할 수 있지만, 팀 배포는 Team 플랜(Cowork) 필수입니다.

Q. 이미 스킬에 토큰을 박아 공유해버렸어요.

A. 즉시 (1) 해당 토큰 발급원에서 무효화/회전, (2) 스킬에서 토큰 제거하고 env: 참조로 교체, (3) 공유받은 동료에게 삭제 요청. Git 으로 커밋까지 했다면 히스토리 정리도 필요합니다.

Q. 환경변수 이름을 잊어버렸어요. 확인하는 법?

A. Cowork 설정 페이지에서 이름은 보이지만 값은 마스킹됩니다. 값이 기억나지 않으면 발급원에서 다시 발급받아 교체하는 게 정답입니다. 마스킹된 값을 강제로 노출하는 기능은 제공되지 않으며 그게 정상입니다.

Q. 환경변수가 너무 많아지면 관리가 복잡해져요.

A. 네이밍 접두사(TELEGRAM_*, CLIENT_DB_*)로 그룹화하고, 3개월마다 "미사용 변수 정리" 를 루틴으로 돌리세요. 스킬에서 참조하는 변수 목록을 스킬 프런트매터에 env_used: [...] 로 명시하면 관리 도구로 역인덱스 가능.

다음 읽을거리

변경 이력

v1 (2026-04-11): 최초 작성 — Claude@IGM Cohort 1 교재용