Provider Agent 是什么
token-provider-agent 是一个常驻运行的命令行程序，负责把你的机器接入平台、维持在线、接收任务并调用本地模型执行推理。
网页控制台负责创建 API Key、查看节点、活动记录和收入。而真正让你的机器成为 Provider 节点的，是这个 Agent。
准备工作
开始之前，确认以下条件已就绪：
- 一台能长期运行的机器
- 已安装并可访问的 Ollama
- 至少一个已拉取到本地的模型
- 一个 Provider API Key（下一节介绍如何获取）
- 平台提供的
token-provider-agent二进制文件
二进制文件按平台命名：
| 平台 | 文件名 |
|---|---|
| macOS (Apple Silicon) | token-provider-agent-darwin-arm64 |
| macOS (Intel) | token-provider-agent-darwin-x64 |
| Linux (x64) | token-provider-agent-linux-x64 |
| Linux (ARM) | token-provider-agent-linux-arm64 |
| Windows | token-provider-agent-win32-x64.exe |
以下示例统一用 ./token-provider-agent 代替，执行时替换为你的实际文件名。
第一步：获取 Provider API Key
登录网页控制台，进入 Provider 的「API 密钥」页面，创建一条新的 Provider API Key。
创建后页面会直接显示密钥内容（stp-...）。请立即保存，离开页面后无法再次查看。
建议每台机器使用独立的密钥，方便后续排查节点状态、活动记录和收入归属。
第二步：确认本地模型可用
Provider Agent 启动时会检查指定模型是否在本地可用。启动前只需要确认三件事：
- 已从 Ollama 下载页 安装 Ollama
- 已用
ollama pull <model_name>下载目标模型 ollama ls能看到该模型
模型名要和后续 --model 参数一致。例如下载 qwen3.5:9b 后，启动时也使用 --model qwen3.5:9b。
Ollama 的安装、下载模型和验证方式见 Ollama 本地模型准备。
第三步：运行启动前检查
正式启动前，先跑一次预检：
./token-provider-agent preflight start --model qwen3.5:9b
预检只做检查，不会启动服务。当前会确认：
- Ollama 是否可访问
- 指定模型是否在本地存在
预检失败时，常见原因：
- Ollama 未启动
- 模型名拼写错误
- 模型未拉取到本地
第四步：启动 Provider Agent
核心启动命令：
./token-provider-agent start --api-key stp-... --model qwen3.5:9b
主要参数：
| 参数 | 说明 |
|---|---|
--api-key | 网页控制台创建的 Provider API Key |
--model | 本地已准备好的模型名 |
启动成功后，进程会常驻运行，持续完成以下工作：
- 注册或恢复节点
- 上报模型和节点状态
- 发送心跳保持在线
- 接收并执行推理任务
所以它是一个常驻服务，不是一次性命令。
更多启动参数
如果需要自定义连接地址或调优参数，还可以使用：
| 参数 | 说明 | 默认值 |
|---|---|---|
--node-name | 这台机器在平台上的显示名称 | 当前主机名 |
--ollama-base-url | Ollama 地址 | http://127.0.0.1:11434 |
--provider-base-url | 控制面地址 | https://provider.skypool.xyz |
--relay-ws-url | Relay WebSocket 地址 | wss://a.skypool.xyz |
--state-path | 本地状态文件路径，用于保存节点会话状态 | /tmp/provider-agent-state.json |
--heartbeat-interval-ms | 心跳间隔（毫秒），必须是 15000 到 60000 之间的整数 | 30000 |
--log-level | 日志级别 | info |
--p2p-enabled | 启用 P2P 直连；也可显式传入 true / false | false |
--max-p2p-connections | 最大 P2P 连接数 | 8 |
--max-total-concurrency | 最大并发任务数 | 2 |
这些启动参数也可以通过环境变量传入：
| CLI 参数 | 环境变量 |
|---|---|
--api-key | PROVIDER_AGENT_API_KEY |
--model | PROVIDER_AGENT_MODEL_CODE |
--node-name | PROVIDER_AGENT_NODE_NAME |
--ollama-base-url | PROVIDER_AGENT_OLLAMA_BASE_URL |
--provider-base-url | PROVIDER_AGENT_PROVIDER_BASE_URL |
--relay-ws-url | PROVIDER_AGENT_RELAY_WS_URL |
--state-path | PROVIDER_AGENT_STATE_PATH |
--heartbeat-interval-ms | PROVIDER_AGENT_HEARTBEAT_INTERVAL_MS |
--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 |
布尔参数支持 1、true、yes、on 表示开启，支持 0、false、no、off 表示关闭。完整命令列表可通过 --help 查看。
第五步：确认节点正常工作
可以从三个方面确认。
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
前台运行时也可以直接 Ctrl+C 停止。
常见问题
启动时提示缺少 model code
启动命令缺少 --model 参数，补上后重新执行：
./token-provider-agent start --api-key stp-... --model qwen3.5:9b
预检失败，找不到模型
指定的模型在本地 Ollama 中不可用。依次检查：
- Ollama 已启动
- 模型名拼写正确
- 模型已拉取到本地
可以用 ./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二进制文件 - 确认本地 Ollama 和目标模型可用
- 运行
./token-provider-agent preflight start --model qwen3.5:9b - 运行
./token-provider-agent start --api-key stp-... --model qwen3.5:9b - 在网页控制台查看「节点列表」
- 查看「活动记录」和「收入」