# 설정

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

사전 요구 사항

Synapse SDK를 설정하기 전에 [설치 가이드](/ko/installation.md)를 완료하세요.

## 개요[​](#개요 "개요에 대한 직접 링크")

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`가 설정된 경우:

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

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

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

```

## 설정 방법[​](#설정-방법 "설정 방법에 대한 직접 링크")

### CLI 설정[​](#cli-설정 "CLI 설정에 대한 직접 링크")

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

#### 인증[​](#인증 "인증에 대한 직접 링크")

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

```bash
synapse login

```

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

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

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

#### 에이전트 선택[​](#에이전트-선택 "에이전트 선택에 대한 직접 링크")

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

```bash
synapse agent select

```

이 명령은:

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

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

#### 현재 설정 보기[​](#현재-설정-보기 "현재 설정 보기에 대한 직접 링크")

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

```bash
synapse agent show

```

#### 설정 초기화[​](#설정-초기화 "설정 초기화에 대한 직접 링크")

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

```bash
synapse agent clear

```

### 환경 변수[​](#환경-변수 "환경 변수에 대한 직접 링크")

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

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

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

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

```

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

```bash
SYNAPSE_ACCESS_TOKEN="your-token" synapse agent select

```

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

### 설정 파일[​](#설정-파일-1 "설정 파일에 대한 직접 링크")

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

## 설정 파일 레퍼런스[​](#설정-파일-레퍼런스 "설정 파일 레퍼런스에 대한 직접 링크")

### 자격 증명 파일[​](#자격-증명-파일 "자격 증명 파일에 대한 직접 링크")

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

**위치**: `~/.synapse/credentials`

**형식**:

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

```

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

### 에이전트 설정[​](#에이전트-설정 "에이전트 설정에 대한 직접 링크")

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

**위치**: `~/.synapse/config.json`

**스키마**:

```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-설정 "MCP 설정에 대한 직접 링크")

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

**위치**: `~/.synapse/config.yaml`

**스키마**:

```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-설정-초기화 "MCP 설정 초기화에 대한 직접 링크")

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

```bash
synapse mcp init

```

#### 다중 환경 관리[​](#다중-환경-관리 "다중 환경 관리에 대한 직접 링크")

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

```python
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     | 연결 실패                   |

#### 수동 연결 테스트[​](#수동-연결-테스트 "수동 연결 테스트에 대한 직접 링크")

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

```python
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)[​](#인증-실패-401 "인증 실패 (401)에 대한 직접 링크")

**증상**: "Invalid agent token" 오류

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

**해결 방법**:

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

### 접근 거부 (403)[​](#접근-거부-403 "접근 거부 (403)에 대한 직접 링크")

**증상**: "Access forbidden" 오류

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

**해결 방법**:

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

### 연결 타임아웃[​](#연결-타임아웃 "연결 타임아웃에 대한 직접 링크")

**증상**: "Connection timeout" 오류

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

**해결 방법**:

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

### 설정 파일 권한 거부[​](#설정-파일-권한-거부 "설정 파일 권한 거부에 대한 직접 링크")

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

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

**해결 방법**:

```bash
# 디렉토리 권한 수정
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 사용법](/ko/operations/cli-usage.md) - 전체 CLI 명령 레퍼런스
* [빠른 시작](/ko/quickstart.md) - Synapse SDK 시작하기
* [플러그인](/ko/plugins/index.md) - 플러그인 개발 가이드