Tokios 커넥터 JSON 설정 참조 안내

Tokios 커넥터는 JSON 설정 파일에서 각종 설정을 읽어들입니다. --config 매개변수를 통해 해당 파일을 지정할 수 있으며, 시작 시 명령줄 플래그를 사용해 특정 설정을 재정의할 수도 있습니다. 이 커넥터는 환경 변수를 전혀 참조하지 않으며, 사용자가 여기서 지정한 업스트림 모델 ID들로만 요청을 전달합니다. 게이트웨이에서 제공하는 URL로는 절대 요청을 보내지 않습니다.

커넥터를 생성할 때 Tokios 콘솔에서 ConnectorId 및 Token API 키가 발급됩니다. 이 토큰은 단 한 번만 표시되므로 반드시 설정 파일에 붙여넣은 뒤 안전한 곳에 보관해두어야 합니다.

Precedence:CLI flags›TOKIOS_* env vars›tokios-connector.json›defaults

설정 파일에 관한 설명

최소한의 설정만으로도 Connector 섹션에 인증 정보와 하나의 로컬 업스트림 모델 ID를 기재할 수 있습니다.

tokios-connector.json

{
  "Connector": {
    "ConnectorId": "con_your_connector_id",
    "Token": "ct-your-connector-token",
    "Models": ["gemma4:e4b"],
    "Upstream": {
      "BaseUrl": "http://127.0.0.1:11434/v1"
    }
  }
}

해당 설정 파일을 지정하여 커넥터를 실행하면 됩니다.

tokios-connector --config tokios-connector.json

`Connector` 필드에 관한 설명

string

필수

managed by pairingrestart required콘솔에서 확인할 수 있는 커넥터의 ID입니다(예: con_...). 이 값은 Tokios 게이트웨이에서 해당 커넥터를 식별하는 기준이 됩니다.

string

필수

managed by pairingsecret — redacted in logs커넥터 생성 시 발급되는 API 키입니다(예: ct-...). 이 값은 귀하의 테넌트와 연결되어 있으며 콘솔에 단 한 번만 표시됩니다.

string

커넥터가 접속할 wss:// 게이트웨이 엔드포인트입니다. 기본값은 호스팅된 Tokios 게이트웨이이므로 보통은 이 값을 지정하지 않아도 됩니다. (자체 호스팅 배포 환경에서는 wss://your-server/connector/connect와 같은 자체 서버 주소를 입력해야 합니다.)

integer

기본값:"8"

커넥터가 한 번에 전달할 수 있는 진행 중인 요청의 최대 개수입니다. 이 한도를 초과하는 요청들은 503 connector_busy 오류와 함께 거부되며, 슬롯이 비워질 때까지 처리되지 않습니다.

커넥터가 어떤 서비스를 제공하는지 정의합니다.

두 가지 형태 중 하나만 선택하세요. 둘 다 지정할 경우 오류가 발생합니다. 단일 업스트림 — 하나의 로컬 서버가 하나 이상의 업스트림 모델 ID를 처리하는 경우입니다.

tokios-connector.json

"Connector": {
  "ConnectorId": "con_...",
  "Token": "ct-...",
  "Models": ["gemma4:e4b"],
  "Upstream": { "BaseUrl": "http://127.0.0.1:11434/v1" }
}

다중 업스트림 — 서로 다른 모델 ID를 각기 다른 로컬 서버로 라우팅하는 경우입니다.

tokios-connector.json

"Connector": {
  "ConnectorId": "con_...",
  "Token": "ct-...",
  "Routes": [
    { "Model": "gemma4:e4b",    "UpstreamId": "ollama" },
    { "Model": "qwen2.5-coder", "UpstreamId": "lmstudio" }
  ],
  "Upstreams": {
    "ollama":   { "BaseUrl": "http://127.0.0.1:11434/v1" },
    "lmstudio": { "BaseUrl": "http://127.0.0.1:1234/v1" }
  }
}

The ids in Models / Routes[].Model are the model ids your local server uses — what you’d send it directly (e.g. gemma4:e4b in Ollama). You expose one under a public API name (e.g. gemma-tunnel) by registering a deployment in the console; that public name is what clients send in the "model" field, and the gateway rewrites it to the upstream id before forwarding it down the tunnel. See Model Routing.

업스트림 관련 설정 항목들입니다.

각 업스트림 — 즉 단일 Upstream 또는 Upstreams 아래에 명시된 항목들 — 은 다음 설정을 받아들입니다.

string

필수

requiredThe base URL of your model server, including the /v1 segment — e.g. http://127.0.0.1:11434/v1. The connector appends the request path (/chat/completions) to it. Your server must expose an OpenAI-compatible Chat Completions API. See Backends.

string[]

선택 사항인 호스트 제한 설정입니다. 비워두면(기본값) 커넥터는 BaseUrl에 명시된 호스트를 그대로 신뢰합니다. 로컬 및 원격 업스트림 모두 별도 설정이 필요하지 않습니다. 값을 입력하면 BaseUrl에 명시된 호스트가 반드시 목록에 포함되어야 합니다. 그렇지 않으면 이후 BaseUrl에서 다른 호스트로 변경하려 할 때 시작 시 오류가 발생하며, 업스트림의 ApiKey 설정도 새 호스트로 자동 전송되지 않습니다.

string[]

커넥터가 전달할 수 있는 요청 경로들입니다. 기본값은 ["/chat/completions"]입니다.

네트워크 내 다른 기기에 있는 모델에 접근하려면 BaseUrl에 해당 주소를 입력하면 됩니다(예: http://192.168.1.50:11434/v1). 별도 활성화 설정은 필요하지 않습니다. 커넥터는 자체 설정 파일에 명시된 호스트로만 요청을 전달하며, 게이트웨이에서 제공한 URL로는 전달하지 않습니다. 이전 설정 파일에는 AllowLan이 포함되어 있을 수 있으나 커넥터는 이를 무시합니다.

원격 업스트림에 인증하기

로컬 서버 대신 호스팅된 OpenAI 호환 제공업체로 요청을 전달하려면 BaseUrl을 해당 제공업체 주소로 지정하고 업스트림 모델 ID에 필요한 인증 정보를 입력하세요.

string

업스트림 요청에 포함되는 키 값입니다.

string

기본값:"Authorization"

키가 전송되는 헤더명입니다. Anthropic 스타일 제공업체에는 x-api-key을, Azure OpenAI에는 api-key을 사용하세요.

string

기본값:"Bearer "

키 앞에 붙는 접두사입니다. 원시 키 방식을 사용할 경우(예: x-api-key, api-key) 빈 문자열로 설정하세요.

object

모든 업스트림 요청에 추가되는 고정 헤더들입니다.

object

업스트림 URL에 추가되는 고정 쿼리 문자열 매개변수입니다(예: Azure OpenAI의 api-version).

명령줄 플래그 목록

플래그 명칭	각 플래그의 설명 내용
`--config <path>`	설정 파일 경로입니다. 상대 경로일 경우 현재 디렉터리부터 상위 디렉터리 순으로, 그다음 바이너리 파일 위치에서도 검색합니다. 생략 시 커넥터는 `appsettings.json`을 찾게 됩니다. 지정된 경로에 파일이 없으면 오류가 발생합니다.
`--version`	커넥터 버전 정보를 출력하고 종료합니다. 별칭으로는 `--ver`, `-v`이 있습니다.

어떤 설정 값이든 전체 키 경로를 사용해 명령줄에서도 재정의할 수 있습니다.

tokios-connector --config tokios-connector.json --Logging:LogLevel:Default=Debug

There is no --log-level flag. Set verbosity through the Logging section (below) or the --Logging:LogLevel:Default=... override shown above.

로깅

커넥터는 항상 콘솔에 로그를 기록합니다. 상세도를 조절하고 매일 새로운 로그 파일을 생성하려면 최상위 수준의 Logging 섹션을 활용하세요. 이 섹션은 Connector 섹션과 동급입니다.

tokios-connector.json

{
  "Logging": {
    "LogLevel": { "Default": "Information" },
    "Directory": "logs",
    "RetainedDays": 7
  },
  "Connector": {
    "ConnectorId": "con_...",
    "Token": "ct-...",
    "Models": ["gemma4:e4b"],
    "Upstream": { "BaseUrl": "http://127.0.0.1:11434/v1" }
  }
}

string

기본값:"Information"

상세도 수준은 Trace, Debug, Information, Warning, 혹은 Error 중에서 선택할 수 있습니다. 문제 해결 시에는 Debug으로 설정해 각 요청별 라우팅 정보와 cid, 업스트림 모델 ID에 관한 상세 내용까지 기록하도록 하세요.

string

지정된 디렉터리에 매일 새로운 로그 파일을 생성하도록 설정할 수 있습니다. 디렉터리가 없으면 자동으로 생성됩니다. 값을 비워두면(기본값) 콘솔에만 로그가 출력됩니다. 상대적 경로는 작업 디렉터리가 아닌 커넥터 실행 파일 위치를 기준으로 해석되므로, 더블클릭으로 커넥터를 실행하더라도 로그가 예측 가능한 위치에 저장됩니다.

integer

기본값:"14"

보관할 일별 로그 파일의 개수를 지정합니다.

이 설정은 logs/tokios-connector-YYYYMMDD.log 값을 기록하게 됩니다.

전체 예시

macOS
Linux
윈도우

설정 경로: ~/Library/Application Support/tokios/tokios-connector.json

{
  "Connector": {
    "ConnectorId": "<generated-during-pairing>",
    "Token": "<generated-during-pairing>",
    "Models": ["gemma4:e4b"],
    "Upstream": {
      "BaseUrl": "http://127.0.0.1:11434/v1"
    }
  }
}

설정 파일 경로: /etc/tokios/tokios-connector.json

{
  "Connector": {
    "ConnectorId": "<generated-during-pairing>",
    "Token": "<generated-during-pairing>",
    "Models": ["gemma4:e4b"],
    "Upstream": {
      "BaseUrl": "http://127.0.0.1:11434/v1"
    }
  }
}

설정 파일 경로: %APPDATA%\tokios\tokios-connector.json

{
  "Connector": {
    "ConnectorId": "<generated-during-pairing>",
    "Token": "<generated-during-pairing>",
    "Models": ["gemma4:e4b"],
    "Upstream": {
      "BaseUrl": "http://127.0.0.1:11434/v1"
    }
  }
}

백그라운드 서비스로 실행하기

개발 목적으로는 터미널 창에서 실행해도 무방합니다. 하지만 항상 작동해야 하는 환경에서는 커넥터를 시스템 서비스로 실행하여 재부팅 시에도 자동으로 시작되도록 설정하는 것이 좋습니다.

맥OS (launchd)
리눅스 (systemd)
윈도우 (서비스)

Create a plist file at ~/Library/LaunchAgents/com.tokios.connector.plist:

~/Library/LaunchAgents/com.tokios.connector.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.tokios.connector</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/tokios-connector</string>
    <string>--config</string>
    <string>/etc/tokios/tokios-connector.json</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/var/log/tokios-connector.log</string>
  <key>StandardErrorPath</key>
  <string>/var/log/tokios-connector.log</string>
</dict>
</plist>

서비스를 로드하고 시작하려면 다음 명령을 사용하세요:

launchctl load ~/Library/LaunchAgents/com.tokios.connector.plist
launchctl start com.tokios.connector

Create a unit file at /etc/systemd/system/tokios-connector.service:

/etc/systemd/system/tokios-connector.service

[Unit]
Description=Tokios Connector
After=network.target

[Service]
ExecStart=/usr/local/bin/tokios-connector --config /etc/tokios/tokios-connector.json
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

서비스를 활성화하고 시작하려면 다음 명령을 사용하세요:

sudo systemctl daemon-reload
sudo systemctl enable tokios-connector
sudo systemctl start tokios-connector

On Windows, use NSSM (Non-Sucking Service Manager) or Task Scheduler to run the connector as a background service.NSSM 활용 방법:

nssm install TokiosConnector "C:\Program Files\Tokios\tokios-connector.exe"
nssm set TokiosConnector AppParameters "--config C:\ProgramData\Tokios\tokios-connector.json"
nssm set TokiosConnector Start SERVICE_AUTO_START
nssm start TokiosConnector

작업 스케줄러 활용 방법:새 작업을 생성한 뒤 트리거를 At startup으로 설정하고, 실행할 프로그램 경로를 tokios-connector.exe으로 지정한 후 --config <path>을 인수로 입력하세요. 또한 Run whether user is logged on or not 옵션을 활성화하면 백그라운드에서 계속 작동하게 됩니다.

코드	의미
E1401	유효하지 않거나 취소된 커넥터 토큰
E1404	알 수 없는 업스트림 모델을 가리키는 경로
E1502	Upstream unreachable — check `BaseUrl` includes `/v1`

시작하기

모델

개념

참고

Tokios 커넥터 JSON 설정 참조 안내

설정 파일에 관한 설명

`Connector` 필드에 관한 설명

커넥터가 어떤 서비스를 제공하는지 정의합니다.

업스트림 관련 설정 항목들입니다.

원격 업스트림에 인증하기

명령줄 플래그 목록

로깅

전체 예시

백그라운드 서비스로 실행하기

관련 오류

​설정 파일에 관한 설명

​Connector 필드에 관한 설명

​커넥터가 어떤 서비스를 제공하는지 정의합니다.

​업스트림 관련 설정 항목들입니다.

​원격 업스트림에 인증하기

​명령줄 플래그 목록

​로깅

​전체 예시

​백그라운드 서비스로 실행하기

​관련 오류

설정 파일에 관한 설명

`Connector` 필드에 관한 설명

커넥터가 어떤 서비스를 제공하는지 정의합니다.

업스트림 관련 설정 항목들입니다.

원격 업스트림에 인증하기

명령줄 플래그 목록

로깅

전체 예시

백그라운드 서비스로 실행하기

관련 오류