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" }
  }
}

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

必填

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` 参数详解

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

上游配置字段说明

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

命令行参数

日志记录

完整示例

以后台服务形式运行

相关错误说明