설정

환경과 사용 사례에 맞게 Synapse SDK를 설정하세요.

사전 요구 사항

Synapse SDK를 설정하기 전에 설치 가이드를 완료하세요.

개요

Synapse SDK는 다양한 워크플로우에 맞는 여러 설정 방법을 제공합니다. 모든 설정 파일은 ~/.synapse/에 보안 권한(0o600)으로 저장됩니다.

한눈에 보기

방법	적합한 용도	명령/파일
CLI	대화형 설정, 최초 설정	synapse login, synapse agent select
환경 변수	CI/CD 파이프라인, 컨테이너	SYNAPSE_HOST, SYNAPSE_ACCESS_TOKEN
설정 파일	영구 설정, 다중 환경	~/.synapse/credentials, config.json, config.yaml

설정 파일

파일	형식	용도
~/.synapse/credentials	Text	백엔드 인증 (호스트, 액세스 토큰)
~/.synapse/config.json	JSON	에이전트 설정 (ID, URL, 토큰)
~/.synapse/config.yaml	YAML	MCP 다중 환경 설정

설정 우선순위

SDK는 다음 순서(높은 우선순위에서 낮은 순서)로 설정 값을 결정합니다:

예시:

환경 변수와 ~/.synapse/credentials 모두에 SYNAPSE_HOST가 설정된 경우:

# 환경 변수
export SYNAPSE_HOST="https://env.synapse.sh"

# 자격 증명 파일: SYNAPSE_HOST=https://file.synapse.sh

# 결과: SDK는 https://env.synapse.sh를 사용 (환경 변수가 우선)

설정 방법

CLI 설정

CLI는 대화형 설정 명령을 제공합니다.

인증

synapse login을 실행하여 Synapse 백엔드에 인증하세요:

synapse login

다음을 입력하라는 메시지가 표시됩니다:

• Host: 백엔드 API URL (기본값: https://api.synapse.sh)
• Access Token: Synapse API 토큰

자격 증명은 ~/.synapse/credentials에 저장됩니다.

에이전트 선택

대화형 인터페이스를 사용하여 에이전트를 선택하세요:

synapse agent select

이 명령은:

1. 백엔드에서 사용 가능한 에이전트를 가져옵니다
2. 에이전트를 테이블 형식으로 표시합니다
3. ID로 에이전트를 선택하라는 메시지를 표시합니다
4. 자동으로 연결을 테스트합니다
5. ~/.synapse/config.json에 설정을 저장합니다

참고: 연결 테스트는 설정을 구성할 때만 실행되며 CLI 시작 시에는 실행되지 않습니다.

현재 설정 보기

현재 에이전트 설정을 표시합니다:

synapse agent show

설정 초기화

저장된 에이전트 설정을 제거합니다:

synapse agent clear

환경 변수

환경 변수는 설정 파일보다 우선합니다.

변수	설명	기본값
SYNAPSE_HOST	백엔드 API URL	https://api.synapse.sh
SYNAPSE_ACCESS_TOKEN	API 액세스 토큰	None

쉘에서 환경 변수를 설정하세요:

export SYNAPSE_HOST="https://api.synapse.sh"
export SYNAPSE_ACCESS_TOKEN="your-token-here"

또는 인라인으로 사용하세요:

SYNAPSE_ACCESS_TOKEN="your-token" synapse agent select

팁: CI/CD 파이프라인에서는 파일에 자격 증명을 저장하지 않도록 환경 변수를 사용하세요.

설정 파일

설정 파일은 영구적인 설정 저장소를 제공합니다.

설정 파일 레퍼런스

자격 증명 파일

자격 증명 파일은 백엔드 인증 정보를 저장합니다.

위치: ~/.synapse/credentials

형식:

SYNAPSE_HOST=https://api.synapse.sh
SYNAPSE_ACCESS_TOKEN=your-access-token-here

경고: 이 파일에는 민감한 자격 증명이 포함되어 있습니다. 제한적인 권한을 설정하세요 (chmod 600 ~/.synapse/credentials).

에이전트 설정

에이전트 설정은 선택한 에이전트의 세부 정보를 저장합니다.

위치: ~/.synapse/config.json

스키마:

{
  "agent": {
    "id": 123,
    "name": "My Development Agent",
    "url": "https://agent.synapse.sh",
    "token": "your-agent-token"
  }
}

필드:

필드	타입	필수	설명
agent.id	int	Yes	고유 에이전트 식별자
agent.name	string	No	사람이 읽을 수 있는 에이전트 이름
agent.url	string	No	에이전트 API 엔드포인트 URL
agent.token	string	No	에이전트 인증 토큰

MCP 설정

MCP(Model Context Protocol) 설정은 다중 환경을 지원합니다.

위치: ~/.synapse/config.yaml

스키마:

default_environment: development

environments:
  development:
    backend_url: https://api.synapse.sh
    access_token: your-dev-token
    tenant: dev-tenant
    agent_id: 123
    agent_name: Dev Agent
    agent_url: https://dev-agent.synapse.sh
    agent_token: dev-agent-token
    plugin_paths:
      - ./plugins
      - ~/my-plugins

  production:
    backend_url: https://api.synapse.sh
    access_token: your-prod-token
    tenant: prod-tenant
    agent_id: 456
    agent_name: Prod Agent
    agent_url: https://prod-agent.synapse.sh
    agent_token: prod-agent-token
    plugin_paths:
      - /opt/synapse/plugins

환경 필드:

필드	타입	설명
backend_url	string	백엔드 API URL
access_token	string	백엔드 액세스 토큰
tenant	string	테넌트 식별자
agent_id	int	에이전트 ID
agent_name	string	에이전트 표시 이름
agent_url	string	에이전트 엔드포인트 URL
agent_token	string	에이전트 인증 토큰
plugin_paths	list[string]	플러그인 검색 디렉토리

MCP 설정 초기화

예제 값으로 새 MCP 설정 파일을 생성합니다:

synapse mcp init

다중 환경 관리

프로그래밍 방식으로 환경을 전환하세요:

from synapse_sdk.mcp.config import ConfigManager

config = ConfigManager()

# 활성 환경 조회
env = config.get_active_environment()
print(f"Active: {env.backend_url}")

# 환경 전환
config.set_active_environment("production")

참고: 각 환경은 별도의 백엔드 및 에이전트 설정을 유지하여 개발 환경과 프로덕션 환경 간 원활한 전환이 가능합니다.

문제 해결

연결 테스트

SDK는 /health/ 엔드포인트를 사용하여 에이전트 연결을 테스트합니다.

에이전트를 설정하면 CLI가 자동으로 연결을 테스트합니다:

상태 코드	결과
200	연결 성공
401	유효하지 않은 에이전트 토큰
403	접근 거부
Timeout	연결 타임아웃 (>5초)
Error	연결 실패

수동 연결 테스트

프로그래밍 방식으로 에이전트 연결을 테스트하세요:

from synapse_sdk.cli.agent.select import check_agent_connection

result = check_agent_connection(
    url="https://agent.synapse.sh",
    token="your-agent-token",
    timeout=5
)

if result.success:
    print(f"Connected: {result.message}")
else:
    print(f"Failed: {result.message}")

인증 실패 (401)

증상: "Invalid agent token" 오류

원인: 액세스 토큰 또는 에이전트 토큰이 올바르지 않거나 만료되었습니다.

해결 방법:

1. 토큰이 올바른지 확인하세요
2. synapse login으로 재인증하세요
3. synapse agent select로 에이전트를 다시 선택하세요

접근 거부 (403)

증상: "Access forbidden" 오류

원인: 토큰은 유효하지만 권한이 부족합니다.

해결 방법:

1. 테넌트 설정을 확인하세요
2. 에이전트가 계정에서 접근 가능한지 확인하세요
3. 관리자에게 권한을 요청하세요

연결 타임아웃

증상: "Connection timeout" 오류

원인: 에이전트에 접근할 수 없거나 응답이 느립니다.

해결 방법:

1. 에이전트 URL이 올바른지 확인하세요
2. 네트워크 연결 상태를 확인하세요
3. 에이전트 서비스가 실행 중인지 확인하세요
4. 방화벽 설정을 확인하세요

설정 파일 권한 거부

증상: 설정 파일을 읽거나 쓸 때 "Permission denied" 오류

원인: ~/.synapse/ 디렉토리 또는 파일의 권한이 잘못되었습니다.

해결 방법:

# 디렉토리 권한 수정
chmod 700 ~/.synapse

# 파일 권한 수정
chmod 600 ~/.synapse/credentials
chmod 600 ~/.synapse/config.json
chmod 600 ~/.synapse/config.yaml

환경 변수가 적용되지 않음

증상: 환경 변수 설정이 무시됨

원인: 변수 이름이 잘못되었거나 export되지 않았습니다.

해결 방법:

1. 변수 이름이 정확히 일치하는지 확인하세요 (SYNAPSE_HOST, SYNAPSE_ACCESS_TOKEN)
2. 변수가 export되었는지 확인하세요: export SYNAPSE_ACCESS_TOKEN="token"
3. 변수 값에 오타가 없는지 확인하세요

관련 문서

• CLI 사용법 - 전체 CLI 명령 레퍼런스
• 빠른 시작 - Synapse SDK 시작하기
• 플러그인 - 플러그인 개발 가이드