Provider Agent 是什么
token-provider-agent 是一个常驻运行的命令行程序，负责把你的机器接入平台、维持在线、接收任务并调用本地模型执行推理。
网页控制台负责创建 API Key、查看节点、活动记录和收入。而真正让你的机器成为 Provider 节点的，是这个 Agent。
准备工作
开始之前，确认以下条件已就绪：
- 一台能长期运行的机器
- 已安装并可访问的本地推理框架；默认使用 LM Studio，也支持 vLLM / SGLang / oMLX / llama.cpp / Ollama
- 默认 LM Studio 模式下，确认本地服务已启动并暴露 OpenAI-compatible
/v1/models和/v1/chat/completions - 一个 Provider API Key（下一节介绍如何获取）
- 平台提供的
token-provider-agent二进制文件
设备建议
选择模型时优先看 GPU 可用显存。以下是单卡常见配置建议；不同推理框架、量化精度、上下文长度和系统占用都会影响实际可加载规模，正式启动前仍以本地推理框架的加载结果和 Agent 预检为准。
| GPU 可用显存 | 常见 GPU 示例 | 推荐模型 |
|---|---|---|
| <= 12 GB | 入门级或较老的消费级 GPU | 不推荐 |
| >=16 GB | GeForce RTX 4060 Ti 16GB 版、RTX 5060 Ti 16GB 版、RTX 4070 Ti SUPER、RTX 4080、RTX 4080 SUPER、RTX 5070 Ti、RTX 5080 | qwen3.5:9b |
| >=24 GB | GeForce RTX 3090、RTX 4090、RTX 4090 D、RTX 5090 D v2 | gemma4:26b |
| >=32 GB | GeForce RTX 5090、RTX 5090 D（非 v2 的 32GB 版本） | qwen3.6:35b |
| >=96 GB | NVIDIA RTX PRO 6000 Blackwell | qwen3.5:122b |
软件下载
请前往 程序下载 下载天池 Token 相关程序。
普通 Provider 用户优先下载“天池 Token 桌面版”。桌面版提供图形化入口，支持 Provider 节点启动，更适合本地桌面和工作站日常运行。
只有在需要长期守护、脚本化部署、服务器部署或无桌面环境运行时，再下载“天池 Token 供应：命令行版”。如果选择命令行版，后续示例统一用 ./token-provider-agent 代替实际可执行文件。
本地推理框架也可以从下载页的“第三方程序”列表进入安装页面。默认推荐先使用 LM Studio；专业节点再根据机器和吞吐需求选择 vLLM / SGLang / oMLX / llama.cpp / Ollama。
第一步：获取 Provider API Key
登录网页控制台，进入 Provider 的「API 密钥」页面，创建一条新的 Provider API Key。
创建后页面会直接显示密钥内容（stp-...）。请立即保存，离开页面后无法再次查看。
建议每台机器使用独立的密钥，方便后续排查节点状态、活动记录和收入归属。
第二步：确认推理框架和模型可用
Provider Agent 启动时会检查指定模型是否在推理框架中可用。默认推理框架是 LM Studio，启动前确认三件事：
- 已从 LM Studio 下载页 安装 LM Studio
- 已在 LM Studio 中下载并加载目标模型
- Developer 页面里的本地 API Server 已启动，默认地址是
http://127.0.0.1:1234
--model 参数仍然使用平台侧模型代码，例如 qwen3.5:9b。控制台的 Token 供应示例会同时展示“模型名称”和“模型 ID”：模型名称通常用于搜索、下载或启动本地推理框架；模型 ID 是本地 OpenAI-compatible /v1/models 返回、Provider Agent 预检和真实请求使用的标识。
LM Studio 的安装、下载模型和验证方式见 LM Studio 本地模型准备。
如果你使用 vLLM / SGLang / oMLX / llama.cpp 等 OpenAI-compatible 推理框架，同样确认服务已暴露 /v1/models 和 /v1/chat/completions，并准备好对应的推理框架地址和推理框架 API Key。Agent 会根据 --api-format 在启动预检时从平台 /platform/v1/models 的 runtime_model_options 选择默认模型 ID；如果你在控制台选择了另一个模型 ID，请通过 --runtime-model-id 或 PROVIDER_AGENT_RUNTIME_MODEL_ID 显式传入。
如果你已经有 Ollama 环境，也可以继续使用 --api-format ollama。Ollama 模式下需要先用 ollama pull <model_name> 下载目标模型，并通过 ollama ls 确认本地可见。
不同推理框架的安装、模型名准备、256K 上下文配置和可用性检查方式，见：
第三步：运行启动前检查
正式启动前，先跑一次预检：
./token-provider-agent preflight start --model qwen3.5:9b预检只做检查，不会启动服务。当前会确认：
- 推理框架是否可访问
- 指定模型是否在推理框架中存在
预检失败时，常见原因：
- 推理框架未启动或地址不正确
- 模型 ID 拼写错误，或本地
/v1/models返回的 ID 与控制台展示不一致 - Ollama 模型未拉取到本地，或 OpenAI-compatible 服务未暴露预检解析出的上游模型
- 平台模型目录没有为当前
--model和--api-format提供runtime_model_options
非 Ollama 推理框架可以在预检时显式带上推理框架地址和框架类型：
./token-provider-agent preflight start --model gemma4:26b --base-url http://127.0.0.1:8000 --api-format omlx --runtime-model-id gemma-4-26b-a4b-it-4bit如果上游服务需要鉴权，预检和启动时都要同时传入 --runtime-api-key，或设置 PROVIDER_AGENT_RUNTIME_API_KEY。
第四步：启动 Provider Agent
核心启动命令：
./token-provider-agent start --api-key stp-... --model qwen3.5:9b主要参数：
| 参数 | 说明 |
|---|---|
--api-key | 网页控制台创建的 Provider API Key |
--model | 平台侧模型代码；Ollama 模式下通常直接等于本地模型名 |
启动成功后，进程会常驻运行，持续完成以下工作：
- 注册或恢复节点
- 上报模型和节点状态
- 发送心跳保持在线
- 接收并执行推理任务
所以它是一个常驻服务，不是一次性命令。
更多启动参数
如果需要自定义连接地址或调优参数，还可以使用：
| 参数 | 说明 | 默认值 |
|---|---|---|
--node-name | 这台机器在平台上的显示名称 | 当前主机名 |
--base-url | 本地推理框架地址；ollama 走原生 /api，其它框架走 OpenAI-compatible /v1 | http://127.0.0.1:1234 |
--api-format | 推理框架选择，可选 lmstudio / vllm / sglang / omlx / llama.cpp / ollama，大小写不敏感 | lmstudio |
--runtime-model-id | 可选：本地推理框架实际使用的模型 ID；不填时按平台目录默认选择 | 未设置 |
--runtime-api-key | 非 Ollama 推理框架下的 API Key，会作为 Authorization: Bearer 传给 /v1/... | 未设置 |
--provider-base-url | 控制面地址 | https://provider.skypool.xyz |
--relay-ws-url | Relay WebSocket 地址 | wss://a.skypool.xyz |
--state-path | 本地状态文件路径，用于保存节点会话状态 | /tmp/provider-agent-state.json |
--log-level | 日志级别 | info |
--p2p-enabled | 启用 P2P 直连；也可显式传入 true / false | false |
--max-p2p-connections | 最大 P2P 连接数 | 8 |
--max-total-concurrency | 最大并发任务数 | 1 |
--prefill-progress-interval-ms | 首个真实输出前的 prefill 进度刷新间隔（毫秒） | 15000 |
--ollama-base-url 仍被兼容，但已经废弃；新配置统一使用 --base-url。
这些启动参数也可以通过环境变量传入：
| CLI 参数 | 环境变量 |
|---|---|
--api-key | PROVIDER_AGENT_API_KEY |
--model | PROVIDER_AGENT_MODEL_CODE |
--node-name | PROVIDER_AGENT_NODE_NAME |
--base-url | PROVIDER_AGENT_BASE_URL |
--api-format | PROVIDER_AGENT_API_FORMAT |
--runtime-model-id | PROVIDER_AGENT_RUNTIME_MODEL_ID |
--runtime-api-key | PROVIDER_AGENT_RUNTIME_API_KEY |
--provider-base-url | PROVIDER_AGENT_PROVIDER_BASE_URL |
--relay-ws-url | PROVIDER_AGENT_RELAY_WS_URL |
--state-path | PROVIDER_AGENT_STATE_PATH |
--log-level | PROVIDER_AGENT_LOG_LEVEL |
--p2p-enabled | PROVIDER_AGENT_P2P_ENABLED |
--max-p2p-connections | PROVIDER_AGENT_MAX_P2P_CONNECTIONS |
--max-total-concurrency | PROVIDER_AGENT_MAX_TOTAL_CONCURRENCY |
--prefill-progress-interval-ms | PROVIDER_PREFILL_PROGRESS_INTERVAL_MS |
布尔参数支持 1、true、yes、on 表示开启，支持 0、false、no、off 表示关闭。完整命令列表可通过 --help 查看。
OpenAI-compatible 推理框架示例
当你的上游服务兼容 OpenAI Chat Completions API 时，选择对应的 --api-format 后启动即可。下面以默认推荐的 LM Studio 为例：
./token-provider-agent start --api-key stp-... --model gemma4:26b --base-url http://127.0.0.1:1234 --api-format lmstudio --runtime-model-id google/gemma-4-26b-a4b --runtime-api-key runtime-...如果上游服务不需要鉴权，可以省略 --runtime-api-key。如果没有选择其它模型 ID，也可以省略 --runtime-model-id，Agent 会在预检阶段按平台模型目录默认项解析，并用本地 /v1/models 验证它可以被调用。
第五步：确认节点正常工作
可以从三个方面确认。
Agent 进程状态
如果 start 运行后没有立刻退出，说明基础启动已通过。
网页控制台节点列表
进入 Provider 的「节点列表」页面，确认能看到：
- 你的节点名称
- 节点状态
- 最近心跳时间
如果心跳时间持续刷新，说明 Agent 在线运行正常。
活动记录和收入
当请求开始进入后，在「活动记录」和「收入」页面可以看到实际的请求处理情况。如果活动记录已出现请求且 Agent 稳定运行，主流程已接通。
常用命令
查看帮助
./token-provider-agent --help查看节点状态
./token-provider-agent status --json确认当前节点状态和生命周期快照。
查看本地模型
./token-provider-agent models --json确认 Agent 当前能看到哪些本地模型。
导出诊断信息
./token-provider-agent diagnose --json排查推理框架、连接或本地状态问题时最有用。
查看 P2P 状态
./token-provider-agent p2p status --json排查直连或传输能力时使用。
停止
./token-provider-agent stop如果 Agent 在前台运行，也可以直接 Ctrl+C 停止。
常见问题
启动时提示缺少 model code
启动命令缺少 --model 参数，补上后重新执行：
./token-provider-agent start --api-key stp-... --model qwen3.5:9b预检失败，找不到模型
指定的模型在推理框架中不可用。依次检查：
- 推理框架已启动
- 模型 ID 拼写正确，且能在本地
/v1/models中看到 - Ollama 模型已拉取到本地，或 OpenAI-compatible
/v1/models能返回预检解析出的上游模型 - 平台
/platform/v1/models中当前平台模型的runtime_model_options包含所选--api-format和模型 ID
可以用 ./token-provider-agent models --json 查看 Agent 当前能识别的模型列表。
节点没出现在网页控制台
按顺序检查：
- Agent 进程是否直接退出了
- API Key 是否正确
- 节点名是否成功传入
status和diagnose输出中是否有明显错误
如果 Agent 启动成功但节点列表为空，通常是接入链路中某一步未完成。
Agent 在运行，但一直没有请求
不要立刻怀疑模型执行有问题，优先检查：
- 节点是否在线
- 心跳是否持续更新
- 模型是否已成功上报
- 当前是否有流量分配到你的节点
网页控制台的「节点列表」「活动记录」「收入」是最直接的三个观察入口。
API Key 泄露了怎么办
- 在网页控制台删除旧的 Provider API Key
- 创建一条新密钥
- 用新密钥重新启动 Agent
不要继续使用已怀疑泄露的密钥。
最小上手流程
按以下顺序操作，即可完成最基础的接入：
- 在网页控制台创建 Provider API Key
- 准备好
token-provider-agent二进制文件 - 确认本地推理框架和目标模型可用
- 运行
./token-provider-agent preflight start --model qwen3.5:9b - 运行
./token-provider-agent start --api-key stp-... --model qwen3.5:9b - 在网页控制台查看「节点列表」
- 查看「活动记录」和「收入」