SpoonOS 설정 가이드: 환경 변수부터 API 키까지 완벽 정리

네오 블록체인·2025년 11월 27일

SpoonOS를 설치했다면 이제 설정을 통해 프레임워크를 사용할 준비를 해야 합니다. SpoonOS는 환경 변수 우선(env-first) 접근 방식을 채택하여 간단하고 유연한 설정을 제공합니다. 이 가이드는 처음 설정하는 개발자부터 고급 사용자까지 모든 수준의 사용자를 위한 완벽한 설정 가이드입니다.

SpoonOS 설정 철학

SpoonOS는 환경 변수 우선(env-first) 접근 방식을 채택했습니다. 이는 다음과 같은 이점을 제공합니다:

✅ 단순성: 복잡한 설정 파일 없이 환경 변수만으로 모든 설정 가능
✅ 보안: 민감한 정보를 코드에 하드코딩하지 않음
✅ 유연성: 환경별(개발/스테이징/프로덕션)로 다른 설정 쉽게 적용
✅ 표준 준수: 12-Factor App 방법론을 따름

핵심 Python SDK는 환경 변수(.env 파일 포함)만 읽습니다. config.json 파일은 spoon-cli 워크플로우에서만 사용되며, CLI가 해당 파일을 읽어 환경 변수로 내보낸 후 에이전트를 시작합니다.

설정 우선순위

SpoonOS는 런타임에 다음 순서로 설정을 로드합니다 (나중에 로드된 값이 우선):

SDK 내장 기본값: 프레임워크에 하드코딩된 기본 설정
환경 변수: .env 파일 또는 셸 환경 변수
CLI에서 내보낸 값: spoon-cli가 config.json에서 읽어 환경 변수로 내보낸 값 (CLI 사용 시에만)

💡 중요: 같은 변수가 여러 곳에 정의되어 있으면, 위 순서에서 나중에 로드된 값이 이전 값을 덮어씁니다. 예를 들어, 환경 변수에 설정한 값이 SDK 기본값보다 우선합니다.

환경 변수 설정

.env 파일 생성

프로젝트 루트 디렉토리에 .env 파일을 생성하여 모든 설정을 관리하는 것이 가장 편리합니다.

프로젝트 구조 예시:

my-spoonos-project/
├── .env                 # 환경 변수 설정 파일
├── .gitignore          # .env 파일을 Git에서 제외
├── main.py
└── requirements.txt

기본 .env 템플릿

다음은 SpoonOS를 시작하기 위한 기본 .env 파일 템플릿입니다:

# ============================================
# LLM Provider API Keys (최소 하나는 필수)
# ============================================

# Google Gemini (빠른 시작 권장)
GEMINI_API_KEY=your_gemini_key_here

# OpenAI
OPENAI_API_KEY=your_openai_key_here

# Anthropic Claude
ANTHROPIC_API_KEY=your_anthropic_key_here

# DeepSeek
DEEPSEEK_API_KEY=your_deepseek_key_here

# OpenRouter
OPENROUTER_API_KEY=your_openrouter_key_here

# ============================================
# 기본 LLM 설정 (선택사항)
# ============================================

# 기본 LLM 프로바이더 선택
# 옵션: gemini, openai, anthropic, deepseek, openrouter
DEFAULT_LLM_PROVIDER=gemini

# 기본 모델 선택
DEFAULT_MODEL=gemini-2.5-pro

# Gemini 최대 토큰 수 (권장: 20000)
GEMINI_MAX_TOKENS=20000

# ============================================
# Web3 설정 (온체인 도구 사용 시에만 필요)
# ============================================

# Web3 프로바이더 URL (Infura, Alchemy 등)
WEB3_PROVIDER_URL=https://mainnet.infura.io/v3/your_project_id

# 프라이빗 키 (주의: 절대 공개 저장소에 커밋하지 마세요!)
PRIVATE_KEY=your_private_key_here

환경 변수 상세 설명

LLM 프로바이더 API 키

SpoonOS는 여러 LLM 프로바이더를 지원합니다. 최소 하나의 API 키는 필수입니다:

변수명	프로바이더	필수 여부	비고
`GEMINI_API_KEY`	Google Gemini	권장	빠른 시작에 가장 적합
`OPENAI_API_KEY`	OpenAI	선택	GPT 모델 사용 시
`ANTHROPIC_API_KEY`	Anthropic	선택	Claude 모델 사용 시
`DEEPSEEK_API_KEY`	DeepSeek	선택	DeepSeek 모델 사용 시
`OPENROUTER_API_KEY`	OpenRouter	선택	여러 모델 통합 접근 시

기본 LLM 설정

프로바이더를 명시하지 않으면 다음 설정이 사용됩니다:

DEFAULT_LLM_PROVIDER: 기본으로 사용할 LLM 프로바이더
DEFAULT_MODEL: 기본으로 사용할 모델명
GEMINI_MAX_TOKENS: Gemini의 최대 컨텍스트 길이 (기본값: 20000)

Web3 설정

블록체인 상호작용이 필요한 경우에만 설정합니다:

WEB3_PROVIDER_URL: Ethereum 노드 RPC 엔드포인트
- Infura: https://mainnet.infura.io/v3/YOUR_PROJECT_ID
- Alchemy: https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY
- 자체 노드: http://localhost:8545
PRIVATE_KEY: 트랜잭션 서명에 사용할 프라이빗 키
- ⚠️ 보안 주의: 절대 공개 저장소에 커밋하지 마세요!

.env 파일 로드 방법

Python에서 .env 파일을 자동으로 로드하려면 python-dotenv 패키지를 사용할 수 있습니다:

pip install python-dotenv

from dotenv import load_dotenv
import os

# .env 파일 로드
load_dotenv()

# 환경 변수 읽기
api_key = os.getenv('GEMINI_API_KEY')

SpoonOS는 내부적으로 .env 파일을 자동으로 로드하므로 별도 설정이 필요 없습니다.

API 키 발급 및 설정

Google Gemini (권장)

Gemini는 빠른 시작에 가장 적합한 선택입니다. 무료 할당량이 넉넉하고 설정이 간단합니다.

1단계: API 키 발급

Google AI Studio에 접속
Google 계정으로 로그인
"Create API Key" 버튼 클릭
프로젝트 선택 또는 새 프로젝트 생성
생성된 API 키 복사

2단계: .env 파일에 추가

GEMINI_API_KEY=AIzaSy...your_actual_key_here

비용 정보:

무료 할당량: 월 15 RPM (Requests Per Minute), 1,500 RPD (Requests Per Day)
유료 플랜: 사용량에 따라 과금

OpenAI

OpenAI의 GPT 모델을 사용하려면 API 키가 필요합니다.

1단계: API 키 발급

OpenAI Platform에 접속
계정 생성 또는 로그인
"Create new secret key" 클릭
키 이름 지정 (선택사항)
생성된 키 복사 (⚠️ 한 번만 표시되므로 안전하게 보관)

2단계: .env 파일에 추가

OPENAI_API_KEY=sk-proj-...your_actual_key_here

비용 정보:

GPT-4: 입력 $0.03/1K 토큰, 출력 $0.06/1K 토큰
GPT-3.5-turbo: 입력 $0.50/1M 토큰, 출력 $1.50/1M 토큰
무료 크레딧 제공 (신규 계정)

Anthropic Claude

Anthropic의 Claude 모델을 사용하려면 API 키가 필요합니다.

1단계: API 키 발급

Anthropic Console에 접속
계정 생성 또는 로그인
"Create Key" 클릭
키 이름 지정
생성된 키 복사

2단계: .env 파일에 추가

ANTHROPIC_API_KEY=sk-ant-...your_actual_key_here

비용 정보:

Claude 3 Opus: 입력 $15/1M 토큰, 출력 $75/1M 토큰
Claude 3 Sonnet: 입력 $3/1M 토큰, 출력 $15/1M 토큰
Claude 3 Haiku: 입력 $0.25/1M 토큰, 출력 $1.25/1M 토큰

DeepSeek

DeepSeek은 저렴한 비용으로 고성능 모델을 제공합니다.

1단계: API 키 발급

DeepSeek Platform에 접속
계정 생성 또는 로그인
API 키 섹션에서 새 키 생성
생성된 키 복사

2단계: .env 파일에 추가

DEEPSEEK_API_KEY=sk-...your_actual_key_here

비용 정보:

매우 저렴한 가격대
무료 티어 제공

OpenRouter

OpenRouter는 여러 LLM 프로바이더를 통합하여 접근할 수 있게 해줍니다.

1단계: API 키 발급

OpenRouter에 접속
계정 생성 또는 로그인
"Keys" 섹션에서 새 키 생성
생성된 키 복사

2단계: .env 파일에 추가

OPENROUTER_API_KEY=sk-or-...your_actual_key_here

비용 정보:

각 모델별로 다른 가격
통합 결제 시스템

CLI 설정 파일

spoon-cli를 사용하는 경우, CLI 전용 설정을 config.json 파일에서 관리할 수 있습니다.

config.json 구조

{
    "llm": {
        "provider": "gemini",
        "model": "gemini-2.5-pro",
        "maxTokens": 20000
    },
    "web3": {
        "providerUrl": "https://mainnet.infura.io/v3/your_project_id",
        "privateKey": "your_private_key_here"
    },
    "agents": {
        "defaultTimeout": 300,
        "maxRetries": 3
    }
}

CLI 설정 동작 방식

spoon-cli가 config.json 파일을 읽습니다
설정 값들을 환경 변수로 내보냅니다
SDK는 환경 변수에서 설정을 읽습니다

⚠️ 중요: Python SDK는 config.json을 직접 읽지 않습니다. CLI를 통해서만 사용됩니다.

자세한 스키마와 명령어는 docs/cli/configuration.md를 참고하세요.

보안 모범 사례

API 키와 프라이빗 키는 민감한 정보이므로 안전하게 관리해야 합니다.

1. .env 파일을 Git에서 제외

.gitignore 파일에 반드시 추가하세요:

# .gitignore
.env
.env.local
.env.*.local
*.key

2. 환경 변수 검증

# .env 파일에 민감한 정보가 있는지 확인
grep -E "(API_KEY|PRIVATE_KEY|PASSWORD|SECRET)" .env

3. 프로덕션 환경 설정

프로덕션에서는 환경 변수를 직접 설정하거나 시크릿 관리 서비스를 사용하세요:

Docker 사용 시:

# Dockerfile
ENV GEMINI_API_KEY=${GEMINI_API_KEY}

Kubernetes 사용 시:

# secret.yaml
apiVersion: v1
kind: Secret
metadata:
    name: spoonos-secrets
data:
    gemini-api-key: <base64-encoded-key>

클라우드 서비스:

AWS: AWS Secrets Manager 또는 Parameter Store
Google Cloud: Secret Manager
Azure: Key Vault

4. API 키 권한 제한

가능한 한 최소 권한 원칙을 따르세요:

읽기 전용 키 사용 (가능한 경우)
특정 IP에서만 접근 허용
사용량 제한 설정
정기적으로 키 로테이션

5. 프라이빗 키 관리

블록체인 프라이빗 키는 특히 주의해야 합니다:

⚠️ 절대 공개 저장소에 커밋하지 마세요
하드웨어 지갑 사용 고려
멀티시그 지갑 사용
테스트넷과 메인넷 키 분리

설정 검증

설치 후 설정이 올바르게 되었는지 확인하는 것이 중요합니다.

기본 검증 명령어

python -c "from spoon_ai.utils.config_manager import ConfigManager; print('✅ Configuration loaded successfully')"

성공하면 다음과 같은 메시지가 표시됩니다:

✅ Configuration loaded successfully

상세 검증 스크립트

더 자세한 검증을 원한다면 다음 스크립트를 사용할 수 있습니다:

# verify_config.py
import os
from dotenv import load_dotenv

load_dotenv()

def verify_config():
    """설정 검증 및 상태 출력"""
    print("🔍 SpoonOS 설정 검증 중...\n")

    # LLM API 키 확인
    llm_providers = {
        'Gemini': 'GEMINI_API_KEY',
        'OpenAI': 'OPENAI_API_KEY',
        'Anthropic': 'ANTHROPIC_API_KEY',
        'DeepSeek': 'DEEPSEEK_API_KEY',
        'OpenRouter': 'OPENROUTER_API_KEY'
    }

    configured_providers = []
    for provider, key_name in llm_providers.items():
        key = os.getenv(key_name)
        if key:
            configured_providers.append(provider)
            print(f"✅ {provider}: 설정됨")
        else:
            print(f"❌ {provider}: 설정되지 않음")

    if not configured_providers:
        print("\n⚠️  경고: LLM API 키가 하나도 설정되지 않았습니다!")
        print("   최소 하나의 API 키를 설정해주세요.")
    else:
        print(f"\n✅ {len(configured_providers)}개의 LLM 프로바이더가 설정되었습니다.")

    # 기본 설정 확인
    default_provider = os.getenv('DEFAULT_LLM_PROVIDER', '없음')
    default_model = os.getenv('DEFAULT_MODEL', '없음')

    print(f"\n📋 기본 설정:")
    print(f"   프로바이더: {default_provider}")
    print(f"   모델: {default_model}")

    # Web3 설정 확인
    web3_provider = os.getenv('WEB3_PROVIDER_URL')
    private_key = os.getenv('PRIVATE_KEY')

    if web3_provider or private_key:
        print(f"\n⛓️  Web3 설정:")
        if web3_provider:
            print(f"   ✅ 프로바이더 URL: 설정됨")
        else:
            print(f"   ❌ 프로바이더 URL: 설정되지 않음")

        if private_key:
            print(f"   ✅ 프라이빗 키: 설정됨")
        else:
            print(f"   ❌ 프라이빗 키: 설정되지 않음")

    print("\n✅ 검증 완료!")

if __name__ == '__main__':
    verify_config()

실행 방법:

python verify_config.py

자동 검증

SpoonOS 프레임워크는 초기화 시 자동으로 설정을 검증하고, 문제가 발견되면 명확한 오류 메시지를 제공합니다:

from spoon_ai import SpoonOS

try:
    framework = SpoonOS()
    print("✅ 프레임워크 초기화 성공!")
except ValueError as e:
    print(f"❌ 설정 오류: {e}")
    print("   .env 파일을 확인하거나 API 키를 설정해주세요.")

문제 해결

일반적인 문제와 해결 방법

1. API 키를 찾을 수 없음

오류 메시지:

ValueError: No LLM API key found. Please set at least one API key.

해결 방법:

.env 파일이 프로젝트 루트에 있는지 확인
환경 변수 이름이 정확한지 확인 (대소문자 구분)
.env 파일에 따옴표 없이 값만 입력했는지 확인

# 잘못된 예
GEMINI_API_KEY="your_key_here"  # 따옴표 제거

# 올바른 예
GEMINI_API_KEY=your_key_here

2. 환경 변수가 로드되지 않음

문제: Python 스크립트에서 환경 변수를 읽을 수 없음

해결 방법:

# python-dotenv가 설치되어 있는지 확인
pip install python-dotenv

# 명시적으로 로드
from dotenv import load_dotenv
load_dotenv()  # .env 파일 로드

# 또는 절대 경로 지정
load_dotenv('/path/to/your/.env')

3. API 키 형식 오류

문제: API 키가 올바른 형식이 아님

해결 방법:

각 프로바이더의 API 키는 특정 접두사를 가집니다:

Gemini: AIza...
OpenAI: sk-proj-... 또는 sk-...
Anthropic: sk-ant-...
DeepSeek: sk-...
OpenRouter: sk-or-...

키가 올바른 형식인지 확인하고, 필요하면 새로 발급받으세요.

4. Web3 프로바이더 연결 실패

문제: 블록체인 노드에 연결할 수 없음

해결 방법:

# 프로바이더 URL 확인
echo $WEB3_PROVIDER_URL

# 연결 테스트
curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  $WEB3_PROVIDER_URL

5. 프라이빗 키 형식 오류

문제: 프라이빗 키가 올바르지 않음

해결 방법:

Ethereum 프라이빗 키는:

0x 접두사 포함 또는 제외 가능
64자리 16진수 (32바이트)
예: 0x1234...abcd 또는 1234...abcd

# 프라이빗 키 검증 예시
import re

def validate_private_key(key):
    # 0x 제거
    key = key.replace('0x', '')
    # 64자리 16진수인지 확인
    return len(key) == 64 and re.match(r'^[0-9a-fA-F]+$', key)

디버깅 팁

환경 변수 확인

# 현재 로드된 환경 변수 확인
python -c "import os; [print(f'{k}={v[:10]}...') for k, v in os.environ.items() if 'API' in k or 'KEY' in k]"

.env 파일 위치 확인

from pathlib import Path
print(f"현재 작업 디렉토리: {Path.cwd()}")
print(f".env 파일 존재: {(Path.cwd() / '.env').exists()}")

로깅 활성화

import logging
logging.basicConfig(level=logging.DEBUG)
# 이제 상세한 로그를 볼 수 있습니다

다음 단계

설정이 완료되었다면 이제 SpoonOS를 본격적으로 사용할 준비가 되었습니다!

SpoonOS 설치 가이드: Python AI 에이전트 프레임워크 시작하기

다음 포스트

SpoonOS 설정 가이드: 환경 변수부터 API 키까지 완벽 정리

목차

SpoonOS 설정 철학

설정 우선순위

환경 변수 설정

.env 파일 생성

기본 .env 템플릿

환경 변수 상세 설명

LLM 프로바이더 API 키

기본 LLM 설정

Web3 설정

.env 파일 로드 방법

API 키 발급 및 설정

Google Gemini (권장)

OpenAI

Anthropic Claude

DeepSeek

OpenRouter

CLI 설정 파일

config.json 구조

CLI 설정 동작 방식

보안 모범 사례

1. .env 파일을 Git에서 제외

2. 환경 변수 검증

3. 프로덕션 환경 설정

4. API 키 권한 제한

5. 프라이빗 키 관리

설정 검증

기본 검증 명령어

상세 검증 스크립트

자동 검증

문제 해결

일반적인 문제와 해결 방법

1. API 키를 찾을 수 없음

2. 환경 변수가 로드되지 않음

3. API 키 형식 오류

4. Web3 프로바이더 연결 실패

5. 프라이빗 키 형식 오류

디버깅 팁

다음 단계

추천 학습 경로

SpoonOS 설치 가이드: Python AI 에이전트 프레임워크 시작하기

[SpoonOS] 에이전트(Agents)

0개의 댓글