Tokios 连接器 JSON 配置文件参考说明

Tokios 连接器会从 JSON 配置文件中读取各项设置。您可通过 --config 参数指定配置文件路径，同时也可在启动时利用命令行参数覆盖任意设置。该连接器不会读取任何环境变量，且仅会向您在此处指定的上游模型发送请求，绝不会访问网关提供的其他 URL。

您所需的 ConnectorId 与 Token 参数均可在创建连接器时由 Tokios 控制台自动生成。其中令牌信息仅显示一次，请务必将其填入配置文件并妥善保存。

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

配置文件结构说明

最简配置仅需包含记载凭证信息的 Connector 区段以及一条本地上游模型定义即可。

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由控制台生成的连接器编号（例如 con_...），该编号用于向 Tokios 网关标识当前连接器身份。

string

必填

managed by pairingsecret — redacted in logs创建连接器时生成的专属令牌（例如 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" }
  }
}

本地服务器所使用的模型 ID 位于 Models / Routes[].Model 中 —— 即您直接向该服务器发送请求时所用的名称（例如 Ollama 中的 gemma4:e4b）。您需要在控制台中注册一个部署（例如 gemma-tunnel）作为公开 API 名称；客户端在 "model" 字段中发送的正是这个公开名称，网关会在通过隧道转发之前将其改写为上游 ID。详见模型路由。

上游配置字段说明

每个上游配置项 —— 无论是单独的 Upstream 还是 Upstreams 下的多个条目 —— 均包含以下设置：

string

必填

required您的模型服务器的基础 URL，务必包含 /v1 这一路径段，例如 http://127.0.0.1:11434/v1。连接器会在该地址后追加请求路径（/chat/completions）。您的服务器必须提供符合 OpenAI 规范的聊天补全 API。详情请参阅后端配置。

string[]

可选的主机限制设置。若留空（默认状态），连接器会直接信任 BaseUrl 中指定的主机名，本地与远程上游均无需额外配置。若填入具体值，则 BaseUrl 中的主机名必须存在于该列表中；如此设置后，若后续尝试将上游指向其他主机（BaseUrl），系统会在启动时直接报错，避免流量被悄悄转发至新主机以及对应的 ApiKey 地址。

string[]

连接器允许转发的请求路径列表。默认值为 ["/chat/completions"]。

若需访问局域网内其他设备上的模型，只需将 BaseUrl 指向对应地址即可，例如 http://192.168.1.50:11434/v1。无需任何额外启用设置：连接器仅会转发至自身配置文件中列出的主机，绝不会响应网关提供的其他 URL。旧版配置文件中可能仍包含 AllowLan 字段，但连接器会直接忽略该内容。

对远程上游服务进行身份验证

若需将请求转发至托管的、兼容 OpenAI 的服务商而非本地服务器，请将 BaseUrl 指向该服务商并提供相应的 API 密钥：

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

系统中并不存在 --log-level 标志。请通过下方的 Logging 区段或前文所述的 --Logging:LogLevel:Default=... 覆盖方式来调整详细程度。

日志记录

该连接器始终向控制台输出日志。您可通过顶层的 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 以及上游模型的相关详情。

string

启用此目录下的每日滚动日志功能（若目录不存在则自动创建）。留空（默认设置）即仅输出至控制台。此处需填写相对路径，该路径以连接器二进制文件所在位置为基准而非当前工作目录，如此即便双击启动连接器，日志文件也能准确生成。

integer

默认值:"14"

需保留的每日日志文件数量。

此操作将写入 logs/tokios-connector-YYYYMMDD.log 内容。

完整示例

macOS 系统
Linux 系统
Windows 系统

配置路径：~/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"
    }
  }
}

以后台服务形式运行

在开发阶段，直接在终端窗口中运行即可。若需长期运行，建议将连接器配置为系统服务，这样系统重启后它也会自动启动。

macOS 系统（使用 launchd 服务）
Linux 系统（使用 systemd 服务）
Windows 系统（服务模式）

在 ~/Library/LaunchAgents/com.tokios.connector.plist 位置创建一个 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

在 /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	路由配置指向了未知的上游模型 ID
E1502	无法连接至上游模型 — 请检查 `BaseUrl` 中是否包含 `/v1`

入门

模型

概念

参考

Tokios 连接器 JSON 配置文件参考说明

配置文件结构说明

`Connector` 参数详解

定义该连接器所提供的服务内容

上游配置字段说明

对远程上游服务进行身份验证

命令行参数

日志记录

完整示例

以后台服务形式运行

相关错误说明

​配置文件结构说明

​Connector 参数详解

​定义该连接器所提供的服务内容

​上游配置字段说明

​对远程上游服务进行身份验证

​命令行参数

​日志记录

​完整示例

​以后台服务形式运行

​相关错误说明

配置文件结构说明

`Connector` 参数详解

定义该连接器所提供的服务内容

上游配置字段说明

对远程上游服务进行身份验证

命令行参数

日志记录

完整示例

以后台服务形式运行

相关错误说明