让编程代理帮你设置 Tokios

这个页面有 2 类读者。第一部分是写给你的。从给代理的说明开始的内容是为代理阅读和执行而编写的。

如果你是代理： 用 shell 而非浏览器工具获取本页的原始 markdown，这样命令和 JSON 格式可以原样送达：

curl -fsSL https://docs.tokios.com/guides/agent-setup.md

然后按照给代理的说明操作。本站每个页面都可以在 URL 后加 .md 获取 markdown 版本，整个站点内容也在 https://docs.tokios.com/llms-full.txt 中。

开始之前

创建自动化令牌

在控制台中，打开 Settings，然后选择 Automation tokens，再选择 Create token。使用 Setup 预设，过期时间设为 1 hour。复制令牌一次。参见自动化令牌。

在运行模型的机器上启动代理

代理需要在那台机器上运行连接器安装命令。确保 Ollama、LM Studio、llama.cpp 或 vLLM 已在该机器上的默认端口运行。

将令牌放入 shell 变量

设置变量，然后从同一个 shell 启动代理，这样密钥不会进入对话。

Windows PowerShell
Windows CMD
macOS & Linux

$env:TOKIOS_CONSOLE="https://tokios.com"
$env:TOKIOS_TOKEN="at-tok-YOUR_TOKEN"
claude

set TOKIOS_CONSOLE=https://tokios.com
set TOKIOS_TOKEN=at-tok-YOUR_TOKEN
claude

export TOKIOS_CONSOLE=https://tokios.com
export TOKIOS_TOKEN=at-tok-YOUR_TOKEN
claude

向代理发送 1 条消息

Read https://docs.tokios.com/guides/agent-setup and follow it. The console base URL is in the TOKIOS_CONSOLE variable and the automation token is in TOKIOS_TOKEN. Never print the token. My model server is Ollama on this machine. When you are done, give me the final report described on that page.

将 Ollama 替换为你的后端。对于 Codex，同样的消息也适用。如果你希望代理安装服务，可以加上 “Make the connector start at boot.”；否则它只会告诉你连接器在重启后不会自动运行。

运行过程中，关注 Connectors 标签页：一台待配对的设备会出现，然后变为活跃状态并显示已宣布的模型。代理创建的行会带有 via token 徽章。代理完成后，在 Settings 中撤销令牌。

编程代理拒绝将下载的脚本管道传入 shell，因此代理不会使用一键安装命令。它通过网关下载连接器二进制文件，验证校验和，然后自行启动。如果你的代理停下来询问被阻止的安装命令，请将它指回这个页面。

给代理的说明

你正在无人值守地设置 Tokios 工作区：配对本机上的连接器，发布本地模型，为编程客户端创建 API 密钥，并验证整个链路。你通过工作区的管理 API 使用 1 个凭据（即自动化令牌）来操作。

你已有的信息

TOKIOS_CONSOLE：控制台基础 URL，通常为 https://tokios.com。下面的每个调用都是 TOKIOS_CONSOLE + /account/...。
TOKIOS_TOKEN：自动化令牌，at-tok-…。在每个请求中以 Authorization: Bearer <token> 发送。它具有 Setup 作用域，即将过期。
本机回环地址上已有一个模型服务器在运行：Ollama 在端口 11434，LM Studio 在 1234，llama.cpp 在 8080，或 vLLM 在 8000。连接器会自动检测这些。

规则

绝对不要在任何地方打印、记录或写入令牌， 除 Authorization 头外。每次都从 shell 变量读取：bash 中用 $TOKIOS_TOKEN，PowerShell 中用 $env:TOKIOS_TOKEN，cmd 中用 %TOKIOS_TOKEN%。你在第 5 步创建的 API 密钥不同：在最终报告中将它交给用户。
令牌仅在 TOKIOS_CONSOLE/account/* 上有效。不要用它尝试 /admin、/auth、/v1 或 /portal。
先查询再创建。 重用同名的待配对连接器和同名的部署。不要因为重试失败就创建第二个 API 密钥。创建是普通 POST 请求，不是幂等的。
错误为 JSON 格式：{"error":{"message":"…","type":"…","scope":"…"}}。
- 401：令牌无效、已过期或已撤销。停止并报告。
- 403 带 scope：令牌缺少该作用域。停止并报告缺少哪个作用域。
- 403 “only available from the console”：该操作仅限登录用户。不要尝试绕过。
- 409（批准时）：重新读取连接器行，按第 3 步所述重试。
- 429：等待 60 秒后重试。
不要更改密码、显示或共享密钥、触碰请求日志或创建其他令牌。你无法做到，也不得尝试。
报告每一步的结果。如果某步失败或跳过，如实说明。

示例使用 bash。在 Windows cmd 中，用双引号包裹 URL 和 JSON，并转义内部引号，例如 -d "{\"name\":\"gpu-box\"}"。

第 1 步：开始配对

首先列出现有连接器：

curl -s "$TOKIOS_CONSOLE/account/connectors" -H "Authorization: Bearer $TOKIOS_TOKEN"

如果已有你打算使用的名称的行显示 "status":"pending_pair"，用新的配对码重用它：

curl -s -X POST "$TOKIOS_CONSOLE/account/connectors/CONNECTOR_ID/claim-code" -H "Authorization: Bearer $TOKIOS_TOKEN"

否则创建一个：

curl -s -X POST "$TOKIOS_CONSOLE/account/connectors" \
  -H "Authorization: Bearer $TOKIOS_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"gpu-box"}'

两者都返回：

{
  "connector_id": "con_…",
  "claim_code": "TKS-XXXX-XXXX",
  "claim_code_expires_at": "2026-…",
  "server_url": "wss://…/connector/connect",
  "install_oneliner": {
    "macos": "curl -fsSL https://tokios.com/downloads/install/macos | sh -s -- --code TKS-XXXX-XXXX",
    "linux": "curl -fsSL https://tokios.com/downloads/install/linux | sh -s -- --code TKS-XXXX-XXXX",
    "windows": "irm https://tokios.com/downloads/install/windows | iex; tokios-install -Code 'TKS-XXXX-XXXX'"
  }
}

配对码有效期为 15 分钟。保留 claim_code 和 server_url；忽略 install_oneliner（它将脚本管道传入 shell，你不能这样做——见第 2 步）。此响应中没有连接器令牌，以后也不会有：连接器在批准后通过隧道接收自己的凭据。

第 2 步：在本机上安装连接器并以分离方式启动

代理安全规则拒绝将下载的脚本管道传入 shell（curl … | sh、irm … | iex），下载脚本并运行本质上是同一回事。两者都不要做，也不要请求用户批准。使用路径 A。它不执行任何下载的脚本：你通过网关的重定向下载连接器二进制文件本身，根据发布版的 SHA256SUMS 验证它，然后用第 1 步的配对码和 server_url 在后台启动它。 路径 A（使用此路径）：下载二进制文件，验证，运行。 选择适合本机的资源：linux/x64 → tokios-connector-linux-x64，linux/arm64 → tokios-connector-linux-arm64，macos/arm64 → tokios-connector-osx-arm64，windows/x64 → tokios-connector-win-x64.exe，windows/arm64 → tokios-connector-win-arm64.exe。 Linux 和 macOS（以 linux/x64 为例；macOS 上使用 shasum -a 256 代替 sha256sum）：

mkdir -p ~/.tokios/connector && cd ~/.tokios/connector
curl -fsSL -o tokios-connector "$TOKIOS_CONSOLE/downloads/connector/linux/x64"
curl -fsSL -o SHA256SUMS https://github.com/tokiosAI/tokios-connector/releases/latest/download/SHA256SUMS
expected=$(grep -E '\*?tokios-connector-linux-x64$' SHA256SUMS | awk '{print $1}')
actual=$(sha256sum tokios-connector | awk '{print $1}')
[ -n "$expected" ] && [ "$expected" = "$actual" ] || { echo "checksum mismatch"; exit 1; }
chmod +x tokios-connector
nohup ./tokios-connector TKS-XXXX-XXXX --Connector:ServerUrl "SERVER_URL" > tokios-connector-stdout.log 2>&1 < /dev/null &
echo $! > tokios-connector.pid

Windows，使用 PowerShell（以 windows/x64 为例）：

$dir = Join-Path $env:LOCALAPPDATA 'Tokios\connector'
New-Item -ItemType Directory -Force -Path $dir | Out-Null
Set-Location $dir
Invoke-WebRequest "$env:TOKIOS_CONSOLE/downloads/connector/windows/x64" -OutFile tokios-connector.exe
Invoke-WebRequest https://github.com/tokiosAI/tokios-connector/releases/latest/download/SHA256SUMS -OutFile SHA256SUMS
$expected = (((Get-Content SHA256SUMS) -match 'tokios-connector-win-x64\.exe$') -split '\s+')[0].ToLower()
$actual = (Get-FileHash tokios-connector.exe -Algorithm SHA256).Hash.ToLower()
if (-not $expected -or $expected -ne $actual) { throw "checksum mismatch" }
$p = Start-Process -FilePath .\tokios-connector.exe -ArgumentList 'TKS-XXXX-XXXX','--Connector:ServerUrl','SERVER_URL' -WorkingDirectory $dir -WindowStyle Hidden -RedirectStandardOutput tokios-connector-stdout.log -RedirectStandardError tokios-connector-stderr.log -PassThru
Set-Content tokios-connector.pid $p.Id

将 TKS-XXXX-XXXX 替换为第 1 步的 claim_code，将 SERVER_URL 替换为 server_url。连接器拨出，出示配对码，等待批准，然后将配置写入二进制文件旁边。如果机器已安装 tokios-connector，跳过下载，直接以相同方式运行该二进制文件。 路径 B（仅在用户要求使用安装程序时）： 安装程序执行相同的下载和校验和步骤，并添加 --detach 标志。它是为用户粘贴而设计的。如果你被要求使用它，先下载到文件，运行前阅读保存的文件，并在报告中说明。绝不要管道传入。连接器的输出在 tokios-connector-stdout.log 中，pid 在 tokios-connector.pid 中，位于上面的目录。稍后用 kill $(cat tokios-connector.pid) 或 Stop-Process -Id (Get-Content tokios-connector.pid) 停止它。 持久化。 分离的进程在重启后不会保留。除非用户消息要求你使连接器在启动时运行，否则不要安装服务；否则在最终报告中说明并提供此选项。如果你被要求：先完成第 3 步到第 6 步，然后停止分离的进程（kill $(cat tokios-connector.pid)；连接器每个目录只允许 1 个实例），并按照在启动时运行连接器针对该平台操作。在 Linux 上，这是一个 systemd 用户单元，其 ExecStart 为 %h/.tokios/connector/tokios-connector --config %h/.tokios/connector/tokios-connector.json，使用 systemctl --user enable --now tokios-connector 启用，加上 loginctl enable-linger "$USER" 使其无需登录即可启动。配对信息保存在 tokios-connector.json 中，因此服务无需新的配对码即可重连。

第 3 步：等待设备出现，然后批准

每 3 秒轮询一次，最长 2 分钟：

curl -s "$TOKIOS_CONSOLE/account/connectors" -H "Authorization: Bearer $TOKIOS_TOKEN"

找到你的 connector_id。当行显示 "claimPending": true 时，它还带有 "sessionId": "sess_…" 和 "machineName"。确认机器名是本机，然后用该 session id 批准：

curl -s -X POST "$TOKIOS_CONSOLE/account/connectors/CONNECTOR_ID/approve" \
  -H "Authorization: Bearer $TOKIOS_TOKEN" -H "Content-Type: application/json" \
  -d '{"session_id":"sess_…"}'

成功返回 {"status":"approved"}。遇到 409 时，设备以新的 session id 重新连接、尚未连接或配对码已过期。重新读取该行。如果配对码已过期，按第 1 步请求新的配对码并用它重启连接器。否则用当前的 sessionId 重新批准。继续轮询，直到行显示 "status":"active"、"online":true 和非空的 "announcedModels"。最多等待 60 秒：连接器在批准后检测本地模型。如果 announcedModels 持续为空，说明检测到的回环端口上没有模型服务器在运行。报告此情况并停止。

第 4 步：发布模型

检查工作区策略：

curl -s "$TOKIOS_CONSOLE/account/auto-publish" -H "Authorization: Bearer $TOKIOS_TOKEN"

如果返回 {"auto_publish": true}，每个已宣布的模型会自动为你发布。轮询 GET $TOKIOS_CONSOLE/account/models 直到已宣布的名称作为 id 值出现。报告时注意准确表述。“已发布”意味着模型在此工作区中有了部署：拥有此工作区 API 密钥且模型作用域覆盖它的人可以通过 API 主机调用它，其他人则无法访问。没有密钥就无法访问任何东西。这发生在连接器批准后宣布模型后的几秒钟内，公共名称就是上游模型 ID（例如 gemma4:e4b）。自动发布还会重新发布你删除的模型（如果连接器再次宣布它），所以如果用户只想暴露部分检测到的模型，请用 POST $TOKIOS_CONSOLE/account/deployments/DEPLOYMENT_ID/disable 暂停其他模型，并说明自动发布已开启。暂停的模型会保持暂停状态。不要删除它们：删除需要 models:reroute 作用域，而 Setup 预设不包含该作用域，并且自动发布会再次发布被删除的模型。
如果返回 false，先列出 GET $TOKIOS_CONSOLE/account/deployments，然后为每个需要可调用的模型创建 1 个部署：

curl -s -X POST "$TOKIOS_CONSOLE/account/deployments" \
  -H "Authorization: Bearer $TOKIOS_TOKEN" -H "Content-Type: application/json" \
  -d '{"public_name":"gemma4:e4b","upstream_model":"gemma4:e4b","connector_id":"con_…"}'

public_name 是客户端在 model 字段中发送的值。upstream_model 必须是 announcedModels 中的 1 个。返回 409 表示名称已存在；保持原样。

第 5 步：创建 API 密钥

curl -s -X POST "$TOKIOS_CONSOLE/account/keys" \
  -H "Authorization: Bearer $TOKIOS_TOKEN" -H "Content-Type: application/json" \
  -d '{"display_name":"laptop 2026-10-16","model_patterns":["gemma4:e4b"]}'

响应：{"id":"key_…","secret":"sk-tok-…","retrievable":true}。secret 只显示一次。保留它用于报告。将 model_patterns 限制为你发布的模型；仅在用户要求所有模型时才省略。

第 6 步：验证

运行健康检查，一个通过隧道的 1 个 token 的 ping：

curl -s -X POST "$TOKIOS_CONSOLE/account/models/healthcheck" \
  -H "Authorization: Bearer $TOKIOS_TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"gemma4:e4b"}'

期望 "status":"ok" 和 latency_ms。然后用 API 密钥（不是令牌）进行 1 次实际调用。客户端基础 URL 是 https://api.tokios.com；用 GET $TOKIOS_CONSOLE/account/connection 确认，它返回 base_url。

curl -s -X POST "https://api.tokios.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-tok-…" -H "Content-Type: application/json" \
  -d '{"model":"gemma4:e4b","messages":[{"role":"user","content":"Say hello in five words."}],"max_tokens":32}'

第 7 步：最终报告

向用户提供：

连接器：名称、id、状态、机器名。
已发布的模型：公共名称，以及是自动发布创建的还是你手动创建的。提醒用户这些模型可由工作区 API 密钥的持有者调用，而非公众。
连接器是否在重启后存活：“不会，它以分离方式运行”，除非你安装了服务，此时说明是哪个服务。
API 密钥：其 id 和 sk-tok- 密钥。这是你要交出的 1 个密钥。
客户端配置，来自 GET $TOKIOS_CONSOLE/account/connection：
- Claude Code：ANTHROPIC_BASE_URL=<base_url>、ANTHROPIC_API_KEY=<sk-tok-…>，以及用 --model 传递的模型名称。
- Codex：OPENAI_BASE_URL=<base_url>/v1、wire_api=responses、disable_response_storage=true。
验证结果：健康检查状态和聊天回复。
你跳过或无法完成的任何步骤及原因。

自动化令牌

作用域、预设、过期时间，以及如何撤销或重新生成令牌。

Claude Code

将 Claude Code 指向代理刚创建的密钥和模型。

硬件与适配

服务与连接运行时

连接客户端或应用

对比

让编程代理帮你设置 Tokios

开始之前

给代理的说明

你已有的信息

规则

第 1 步：开始配对

第 2 步：在本机上安装连接器并以分离方式启动

第 3 步：等待设备出现，然后批准

第 4 步：发布模型

第 5 步：创建 API 密钥

第 6 步：验证

第 7 步：最终报告

自动化令牌

Claude Code

​开始之前

​给代理的说明

​你已有的信息

​规则

​第 1 步：开始配对

​第 2 步：在本机上安装连接器并以分离方式启动

​第 3 步：等待设备出现，然后批准

​第 4 步：发布模型

​第 5 步：创建 API 密钥

​第 6 步：验证

​第 7 步：最终报告

自动化令牌

Claude Code

开始之前

给代理的说明

你已有的信息

规则

第 1 步：开始配对

第 2 步：在本机上安装连接器并以分离方式启动

第 3 步：等待设备出现，然后批准

第 4 步：发布模型

第 5 步：创建 API 密钥

第 6 步：验证

第 7 步：最终报告