runpod

Runpod（路由器）

Runpod 技能的入口。此技能本身不执行任何操作，只负责选择正确的路径并移交任务。对于多步骤任务或资源配置任务，请先查看已完成示例，让相应示例选择路径；否则，请继续阅读匹配技能的 SKILL.md。

路径

路径	用途
runpod-mcp	通过结构化工具调用管理基础设施（Pod、端点、作业、模板、卷、注册表、目录、账单）——适用于本次会话已连接 Runpod MCP 工具的情况。根据任务转交给相应的流程技能（发现、生命周期 CRUD、无服务器部署、Pod 部署、Pod 诊断、端点运维、成本审计）。
runpodctl	通过终端/CI/脚本管理同一基础设施，包括浏览/部署 Hub、文件传输（send/receive）、SSH 密钥、doctor 设置和模型缓存。
flash	编写在 Runpod 无服务器环境中运行的 Python——@remote/@Endpoint 函数、flash dev 热重载、flash deploy。以代码为先，不用于基础设施管理。
companion-clis	前置资源：下载模型（hf）、构建/推送镜像（docker）、管理仓库/发行版（gh）、通过 S3 将数据传输到网络卷（aws）。
runpod-usage	操作前了解 Runpod 的工作方式——Pod 与无服务器、构建容器、存储、GPU 选择、注意事项。仅提供知识。
runpod-templates	官方预构建 Pod 模板（ComfyUI、PyTorch、……）：是否有适用于此工作负载的模板，以及其镜像包含哪些内容——端口、路径、自动启动、就绪状态、首次启动时缺少的内容。作为参考和路由中心；通过 runpod-mcp/runpodctl 部署。
runpod-build-template	根据请求、本地代码或 GitHub 创建或改进模板项目：提供有文档说明的 Dockerfile、应用专属文件，以及 Pod/队列/负载均衡部署交接。
runpod-migrate	将现有代码从 GraphQL API 或 REST v1 迁移到 REST v2——盘点哪些部分使用哪个版本、重写调用位置、标记破坏性变更。会修改用户代码；不管理基础设施。

这些技能只是快照；工具才是事实依据

下方每条路径封装的内容都有各自的发布周期，更新速度也比此仓库快。因此，请使用这些技能进行路由，但能力和语法以当前工具为准：

路径	直接查询
runpodctl	runpodctl --help、runpodctl <resource> <action> --help、runpodctl version。如需了解错误形式，可故意运行错误命令并查看 JSON
runpod-mcp	客户端的工具列表（Claude Code 中的 /mcp）——每个工具都附带自己的参数说明
flash	flash --help，以及 deploy/dev 的输出
companion-clis	相应 CLI 自带的 --help（hf、gh、docker、aws）
runpod-templates	runpodctl template list --type official、template get <id>（其 readme 是权威信息）
REST v2	实时规范：https://api.runpod.io/v2/openapi.json

未经确认，绝不要告诉用户某个工具做不到某事。 能力缺失是此处最可能过时的说法，也是读者最没有理由再次核实的内容——它已经过时两次（runpodctl v2.9.0 添加了 serverless health，v2.10.0 添加了 pod logs/serverless logs）。如果某项限制仍然存在，请注明适用的版本，而不要说“无法”。

首次运行 — 更新工具，然后检查身份验证

**每项任务的第一条命令之前都要更新。**旧版本保留了后续版本修复或移除的标志。v2.12.0 之前的 runpodctl 接受 pod create --stop-after / --terminate-after，但后端从未执行这些标志，因此 Pod 会在截止时间之后继续计费。更新你即将使用的每个工具：

runpodctl update && runpodctl version   # runpodctl
flash update                            # flash

MCP 无需任何操作：托管服务始终是最新版本，而使用 npx @runpod/mcp-server@latest 启动的本地安装会获取最新版本。 在任务剩余时间内使用相同的版本。

使用 runpod-build-template 编写文件无需云凭据。只有在操作实际使用控制平面或其他需要身份验证的服务时，才检查身份验证。

基础设施任务（Pod、端点、作业、卷）需要可用的控制平面 — Runpod MCP 或 runpodctl。不要等到任务进行中才发现一切都没配置好：先检查；如果尚未配置，请帮助用户完成设置，而不是勉强采用不完整的备用方案。

检查（凭据解析顺序：RUNPOD_API_KEY 环境变量 → .env → ~/.runpod/config.toml）：

runpodctl user            # succeeds ⇒ a key is set and valid

此外，在 Claude Code 中，/mcp 应显示 runpod 已连接。

**规则：先获取密钥 — 不要默认使用 MCP OAuth。**原因：一个 RUNPOD_API_KEY 即可解锁所有工具 — 它可为 runpodctl + flash + 托管 MCP 进行身份验证（使用 --header "Authorization: Bearer $RUNPOD_API_KEY"）。MCP 的“使用 Runpod 登录”OAuth 只为 MCP 本身进行身份验证 — CLI 仍然无法使用，因此任何仅支持 CLI 的任务（send/receive、SSH、doctor、模型缓存/Model Repository、CPU 端点）都会受阻。⚠️ **仅使用 OAuth 属于半配置状态。**如果尚未配置，请停止并按以下顺序获取密钥：

1. flash login — 通过浏览器 OAuth 登录，并将真实密钥保存到 ~/.runpod/config.toml（runpodctl
   • flash 会读取该文件；可将其复用于 MCP Bearer）。一步完成，解锁所有工具。仅限人工操作。
2. export RUNPOD_API_KEY=…（https://console.runpod.io/user/settings）— 同样可以完整解锁； 最适合无头 Agent。
3. 仅使用 MCP OAuth（/mcp → 登录）— 最后手段，仅用于 MCP 任务；CLI 仍未通过身份验证。

**然后：**如果某种方式已经可用，就使用它 — 但如果 只有 MCP 通过 OAuth 登录，仍需在执行任何仅支持 CLI 的步骤前获取密钥。缺少 CLI？curl -sSL https://cli.runpod.net | bash（runpodctl）· uv tool install runpod-flash（flash）· npx @runpod/mcp-server@latest add（MCP）。完整设置说明： runpod-usage/reference/getting-started.md。

如何路由

0. 是否已有适用的示例？ 对于单次调用以外的任何任务，选择执行路径之前，请先查看黄金路径索引——匹配的路径已经列出了执行路径、标志、顺序和陷阱，因此路由时只需阅读，无须重新推导。符合以下任意条件时，请查看：

• 任务需要多个资源（镜像 + 模板 + 端点、Pod + 卷、多区域，……）或多个执行路径
• 任务会创建计费资源，或用户的请求类似于*"让 X 运行起来 / 部署好 / 正常工作"*
• 涉及存储、网络、自动扩缩、流式处理或调试实时资源——这些领域的难点往往就在于不明显的操作顺序
• 你正准备为此编写多步骤计划

对于单次读取或单次 CRUD 调用（“列出我的 Pod”“停止 Pod X”“有哪些 GPU 可用”），跳过第 0 步，直接选择执行路径。选择工作流时，匹配的黄金路径优先于此路由器的执行路径表。其中的命令并不能证明某项能力只能通过 CLI 使用：请根据当前可用的工具和下方的能力矩阵选择执行路径，同时保留路径中的操作顺序和验证步骤。

如果用户明确要求创建或优化 Dockerfile / 模板项目，请先匹配path 26，而不是通用部署示例；GP26 是编写规范，包含本地检查，并非经过实时验证的部署流程。已有的预构建产物不能替代用户要求交付的内容。

1. 概念性问题，或尚未做出的设计选择（无服务器还是 Pod？选哪种 GPU？将模型打包进去还是挂载卷？）→ 先阅读 runpod-usage，再继续作答。
2. 编写或改进模板项目 / Dockerfile，包括转换本地代码或 GitHub 仓库，或准备 Hub 列表文件 → runpod-build-template。它会将构建 / 推送机制和基础设施工作交由现有的执行路径处理。 将现有镜像注册为可复用模板（“根据我的镜像创建模板”），以及浏览 / 部署现有 Hub 列表，请使用下方的基础设施执行路径；注册无需新建 Dockerfile。
3. 在 Pod 上运行常见工作负载，或修复模板 Pod（“运行 ComfyUI / PyTorch 开发环境”、无法启动、缺少模型）→ runpod-templates——制定任何安装计划之前，先检查是否有官方预构建版本，并让它负责路由修复操作。
4. 使用 Runpod 的代码优先工作流，在 Runpod GPU 上编写 / 迭代 / 发布自己的代码 → flash。
5. 生成交付产物（下载模型、构建并推送镜像、创建仓库发布版本、将数据同步到卷）→ companion-clis。
6. 在 Runpod API 版本之间迁移现有代码——“帮我们迁移到 REST v2”“这个仓库使用的是哪个 Runpod API？”“升级会有什么影响？”→ runpod-migrate。（调用 API 来执行某项操作是不同的任务；请使用下方的基础设施执行路径。）
7. 管理基础设施（创建 / 列出 / 更新 / 删除 Pod、端点、模板、卷；列出 GPU / 数据中心；运行无服务器作业；计费）：
   • 仅 CLI 支持的能力——send/receive、SSH 密钥、doctor、模型缓存 → runpodctl。
   • 否则，如果此会话中已连接 Runpod MCP 工具（可用 create-pod、list-endpoints 等工具）→ runpod-mcp。
   • 否则（仅有 shell 的 Agent，没有 MCP）→ runpodctl。

runpod-mcp 与 runpodctl（功能重叠）

两者都驱动同一个 Runpod API，因此在基础设施的增删改查上有重叠。选择时，先看功能，再看环境：

• 对于简单、结构化的操作，MCP 更方便——例如读取和基本增删改查——前提是已连接 MCP 工具（参数有类型，无需处理 Shell 引号）。
• 当操作需要 MCP 不具备的功能时，就改用 runpodctl——即使 MCP 已连接也是如此；对于只能使用 Shell 的 Agent，或用户需要可复现的命令时，runpodctl 也是唯一选择。

功能对照表（按操作选择首选方式）：

操作	首选方式	原因
列出或获取任何内容；启动、停止、重启或删除 Pod；对端点、模板、卷、注册表进行简单增删改查；目录；账单	如果已连接，优先使用 runpod-mcp，否则使用 runpodctl	简单的结构化操作——MCP 参数有类型，使用方便
创建简单 Pod（一个镜像 + 一种 GPU）	如果已连接，优先使用 runpod-mcp，否则使用 runpodctl	两者都支持
基于模板创建 Pod，或创建 CPU Pod	如果已连接，优先使用 runpod-mcp，否则使用 runpodctl	MCP 的 create-pod 支持 templateId（仅限 v2）和 computeType: "CPU"
创建带有多个 GPU 优先选项的 Pod，或同时使用模板 + CPU创建 Pod	runpodctl	MCP 只能指定一种 GPU 类型，且不接受为 CPU Pod 部署模板
浏览或部署现有的 Hub 条目	如果已连接且提供所需操作，优先使用 runpod-mcp，否则使用 runpodctl	检查当前可用的工具；Hub 本身并不是改用 CLI 的理由
文件传输（send/receive）、SSH 密钥/信息、doctor 设置、模型缓存	runpodctl	MCP 没有对应工具
调用无服务器作业（run/runsync/状态/流式传输）	如果已连接，优先使用 runpod-mcp，否则使用 runpodctl	两种方式现在都支持一流的作业命令（runpodctl serverless run/status/health，v2.9.0+）；MCP 参数有类型，且只有 MCP 会流式传输作业的增量输出（stream-job）
读取 Pod 或 Worker 日志	两者皆可——如果已连接，优先使用 runpod-mcp，否则使用 runpodctl	两种方式都能读取：MCP 的 stream-pod-logs/stream-worker-logs 会返回解析后的帧；runpodctl 的 pod logs/serverless logs 会输出 JSON 行，并支持 --follow（v2.10.0+）

经验法则：简单操作默认使用 MCP；一旦操作需要 MCP 未提供的标志或功能，就交给 runpodctl。

部署工作负载（黄金循环）

对于任何“在 Runpod 上运行 ”的任务，请遵循 runpod-usage/reference/development-loop.md 中的开发循环：决定使用 Pod 还是无服务器 → 配置资源 → 设置环境（仅限从零开始时）→ 验证 → 交付 → 控制成本并拆除资源。这些规则在该循环中适用：

• 优先使用预构建模板 / Hub worker，而不是从零开始构建镜像 — 除非用户明确要求自定义模板项目或 Dockerfile； 官方 Pod 模板已编入索引 runpod-templates。
• 交付前，使用来自 Pod / 端点外部的真实请求验证工作负载 — “Running” / “ready” 状态并不意味着服务已正常运行。
• 默认使用 Secure Cloud。 Community Cloud 主机是经批准的供应商；Secure Cloud 主机是数据中心级服务商，因此通常更稳定。只有用户明确要求时才 部署到 Community。（runpodctl pod create 已 默认使用 --cloud-type SECURE；不要覆盖该设置。）
• 缓存还是网络卷，是延迟方面的选择，而不是成本方面的选择。 下载时间永远 不计费，但缓存未命中时，Runpod 会一直等待模型下载完成后才启动 worker —— 作业会停留在队列中，端点看起来处于空闲状态。对延迟敏感 → 预先将模型加载到 网络卷；否则，缓存是更省钱的默认选择。缓存容量按机器计算，因此请在用户自己的 端点上分别计时，而不是引用某个阈值。参见 runpodctl/reference/model-caching.md。
• 每次创建 GPU 时都要固定 CUDA 最低版本 — 在 runpodctl 中使用 --min-cuda-version 12.8，在 REST v2 和 MCP 中使用 gpu.minCudaVersion: "12.8"（仅 CUDA-13 镜像使用 13.0）。不设置此项时，创建操作会接受任意主机 CUDA 版本， 现代镜像可能会部署到 CUDA 版本过旧、无法运行它的主机上，表现为容器启动时 退出，或悄然改用 CPU 运行： gpu-selection.md。

它分为两个子循环：

• 通过 URL 访问的服务（Ollama、ComfyUI、开发环境）→ runpod-usage/reference/pod-workflows.md （创建时配置端口 + 环境变量 + 卷，通过 SSH-exec 安装，绑定 0.0.0.0，轮询 代理 URL）。在 runpodctl 通道中执行。
• 可缩容至零的请求 / 响应 API（Whisper、推理）→ runpod-usage/reference/endpoint-workflows.md （Hub worker、flash 或自定义镜像；调用 /run / /runsync；轮询作业状态）。

示例操作流程（黄金路径）

这是路由的第 0 步，不是附录。近两打端到端场景（几乎都已在真实账户上实测验证）收录于 ./golden-paths/README.md，其中包含可直接复制的真实命令和 实测输出——每个场景还附有「注意事项」和「费用与清理」章节，因为这些内容重新摸索起来代价不小。

将任务与下方某一行匹配，并在规划或调用任何内容之前先打开对应路径。 即使只是部分匹配，也值得打开：即便模型、GPU 或区域不同，最接近的路径中的操作顺序和注意事项通常仍适用。只有在这里找不到相近路径时，才转到上方的各泳道表格。

想要……	黄金路径
在 Pod 上通过 URL 运行服务器（Ollama/ComfyUI）	01，02
部署无服务器模型端点（Hub / flash / 自定义镜像）	03，05
提供 HuggingFace 模型服务，无需将模型烘焙进镜像或使用卷（主机缓存）	20 — 模型缓存（--model-reference）
调用可直接使用的托管模型（无需部署）	11 — 公共端点
微调后提供结果模型服务	04，08
交互式开发环境（SSH / VS Code）	06
移动数据：Pod → 卷 → 无服务器	07
当 flash 不够用时使用自定义无服务器方案（双模式镜像开发循环）	09
根据代码、仓库或应用需求创建或改进完整的模板项目	26 — 项目编写
为目标构建最小镜像（Pod 与无服务器队列）	22（Pod），23（队列）；概念说明见 building-images
决定哪些内容烘焙进镜像，哪些内容挂载到网络卷	25 — 烘焙还是挂载
选择网络卷的存储层级（标准型还是高性能型）	21 — 存储层级
高可用性 / 多区域无服务器方案（多卷 + 数据同步）	10，19（3 区域）
增量式流式输出（/stream）	12
调整自动扩缩容 / 提高每个工作进程的吞吐量	13（自动扩缩容），18（并发）
负载均衡 / HTTP 服务器或 WebSocket 工作进程	14（负载均衡），17（WebSocket）
收到作业完成通知（推送，而非轮询）	16 — Webhook
检查运行状况 / 调试故障端点	15 — 监控与调试

多泳道任务

操作顺序始终是理解 → 生成构件 → 管理基础设施 → 验证， 因为基础设施只能引用已存在的构件。每一步都应在同一泳道中完成，并在凭证边界处切换泳道。

示例——“将 openai/gpt-oss-20b 部署到无服务器端点”：

1. runpod-usage — 无服务器还是 Pod、20B 模型对应的 GPU 层级、烘焙还是挂载还是缓存。
2. companion-clis — hf download …、docker build --platform=linux/amd64 …、docker push。
3. runpod-mcp 或 runpodctl — 创建引用该镜像和 GPU 池的端点。
4. 同一基础设施泳道 — 调用端点 / 检查状态以进行验证。

身份验证

一切都只需一个密钥：RUNPOD_API_KEY（https://console.runpod.io/user/settings）。 每种方式都只是让该密钥可供使用——runpodctl doctor、flash login、MCP stdio 环境变量，或 MCP 托管版「使用 Runpod 登录」（OAuth，密钥不会存储在磁盘上）。 配套 CLI 使用各自的凭据（HuggingFace 令牌、GitHub 身份验证、 Docker Hub PAT、供 aws 使用的 Runpod S3 密钥）——不要将 RUNPOD_API_KEY 用于 这些凭据。