> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokios.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Tokios exposes private local models through https://api.tokios.com using an outbound-only connector tunnel.
> Use 'connector' for the local tokios-connector process.
> Use 'deployment' for the public model name in the API model field.
> Use 'upstream model id' for the model served by Ollama, llama.cpp, vLLM, LM Studio, or another local backend.
> API keys use the prefix sk-tok-. Connector tokens use the prefix ct-tok-.

# 让编程代理帮你设置 Tokios

> 把自动化令牌和这个页面交给 Claude Code、Codex 或任何编程代理。它会配对连接器、发布模型、创建 API 密钥，并自动验证整个链路。

这个页面有 2 类读者。第一部分是写给你的。从[给代理的说明](#instructions-for-the-agent)开始的内容是为代理阅读和执行而编写的。

> [!NOTE]
>
> **如果你是代理：** 用 shell 而非浏览器工具获取本页的原始 markdown，这样命令和 JSON 格式可以原样送达：
>
> ```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
> curl -fsSL https://docs.tokios.com/guides/agent-setup.md
> ```
>
> 然后按照[给代理的说明](#instructions-for-the-agent)操作。本站每个页面都可以在 URL 后加 `.md` 获取 markdown 版本，整个站点内容也在 `https://docs.tokios.com/llms-full.txt` 中。

## 开始之前

**1. 创建自动化令牌**

在控制台中，打开 **[Settings](https://tokios.com/console/settings)**，然后选择 **Automation tokens**，再选择 **Create token**。使用 **Setup** 预设，过期时间设为 **1 hour**。复制令牌一次。参见[自动化令牌](/zh/setup/automation-tokens.md)。

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

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

**3. 将令牌放入 shell 变量**

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

**Windows PowerShell**

```powershell theme={"theme":{"light":"github-light","dark":"css-variables"}}
$env:TOKIOS_CONSOLE="https://tokios.com"
$env:TOKIOS_TOKEN="at-tok-YOUR_TOKEN"
claude
```

**Windows CMD**

```cmd theme={"theme":{"light":"github-light","dark":"css-variables"}}
set TOKIOS_CONSOLE=https://tokios.com
set TOKIOS_TOKEN=at-tok-YOUR_TOKEN
claude
```

**macOS & Linux**

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
export TOKIOS_CONSOLE=https://tokios.com
export TOKIOS_TOKEN=at-tok-YOUR_TOKEN
claude
```

**4. 向代理发送 1 条消息**

```text theme={"theme":{"light":"github-light","dark":"css-variables"}}
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** 中撤销令牌。

> [!NOTE]
>
> 编程代理拒绝将下载的脚本管道传入 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。连接器会自动检测这些。

### 规则

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

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

### 第 1 步：开始配对

首先列出现有连接器：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s "$TOKIOS_CONSOLE/account/connectors" -H "Authorization: Bearer $TOKIOS_TOKEN"
```

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

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s -X POST "$TOKIOS_CONSOLE/account/connectors/CONNECTOR_ID/claim-code" -H "Authorization: Bearer $TOKIOS_TOKEN"
```

否则创建一个：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s -X POST "$TOKIOS_CONSOLE/account/connectors" \
  -H "Authorization: Bearer $TOKIOS_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"gpu-box"}'
```

两者都返回：

```json theme={"theme":{"light":"github-light","dark":"css-variables"}}
{
  "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`）：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
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` 为例）：

```powershell theme={"theme":{"light":"github-light","dark":"css-variables"}}
$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 个实例），并按照[在启动时运行连接器](/zh/setup/connector-install.md#run-the-connector-at-boot)针对该平台操作。在 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 分钟：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -s "$TOKIOS_CONSOLE/account/connectors" -H "Authorization: Bearer $TOKIOS_TOKEN"
```

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

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
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 步：发布模型

检查工作区策略：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
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 个部署：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
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 密钥

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
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：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
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`。

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
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`。
* 验证结果：健康检查状态和聊天回复。
* 你跳过或无法完成的任何步骤及原因。

> **[自动化令牌](/zh/setup/automation-tokens.md)**
>
> 作用域、预设、过期时间，以及如何撤销或重新生成令牌。

> **[Claude Code](/zh/guides/claude-code.md)**
>
> 将 Claude Code 指向代理刚创建的密钥和模型。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.