设置执行器

执行器是开源的 vps-agent CLI 安装在您自己的计算机或 VPS 上。它向 SprintFlint 注册，轮询 自动播放 作业，在配置的工作树或克隆目录中运行编码工具（默认为 Claude Code），并创建拉取请求。执行器不会自行合并；由您审查并合并。

先决条件

在注册运行器之前在主机上安装这些：

• Node.js 18+ - 运行器是通过 npm 安装的 Node CLI
• git - 重用本地签出（工作树）或克隆存储库，然后推送分支
• GitHub CLI (gh) - 打开拉取请求
• Claude Code (claude) - 默认编码工具需要；如果您仅运行以下工具，则可跳过： noop 马具

安装

使用 npm 全局安装 CLI：

npm install -g vps-agent

验证它在您的 PATH 中：

vps-agent --version

注册

注册会将执行器关联到您的 SprintFlint 组织。有两种模式。

Token模式（推荐）

从 SprintFlint 中的运行器设置页面生成注册令牌，然后使用它进行注册：

vps-agent register \
  --token <token> \
  --api-url https://sprintflint.com

打开 执行器 在 SprintFlint 中创建执行器，并复制其注册令牌。该令牌用于识别执行器并验证其身份；请妥善保密。

组织 ID 模式

如果您希望在注册时为执行器命名，请使用您的组织 ID 进行注册：

vps-agent register \
  --org-id <id> \
  --name <name>

启动执行器

开始在前台轮询作业：

vps-agent start

要保持其在后台运行（对于 VPS 或长期主机），请使用守护程序模式：

vps-agent start --daemon

启动后，执行器会发送心跳并显示为 在线 在SprintFlint。它现在会为您的组织挑选自动播放作业。

状态、日志和停止

重复使用本地结账

默认情况下，运行程序将存储库克隆到新的作业目录中。这很慢并且会错过本地秘密（例如 Rails master.key）。在项目编辑页面上配置项目路径 - 或此运行器上的路径覆盖 - 并且作业负载告诉运行器使用 git worktree add 相反，从那个结帐处。

剩余的工作树添加/删除行为是在 vps-agent。这个 Rails 应用程序发送 source_mode, project_path, worktree_base, 和 use_worktree 在每一个 next_job / job assignment.

编码工具选择

的 马具 是执行器调用来实现工单的编码工具。设置 harness 配置键：

• claude - 默认值；针对克隆的存储库驱动 Anthropic 的 Claude Code CLI。需要 claude CLI 已安装并经过身份验证。
• noop - 试运行：克隆存储库并创建空 PR，不修改代码。在启用实际编码工具前，用它验证连接、Git 身份验证和 PR 流程。

权限模式

的 permission_mode 配置项控制编码工具无需确认即可执行哪些操作：

• acceptEdits - 自动接受文件编辑；无人值守自动播放的合理默认设置
• bypassPermissions - 根本没有权限提示就运行；仅在您完全信任和隔离的主机上使用
• plan - 让编码工具规划修改而不写入代码；可用于预览 Autoplay 将执行的操作

Git认证

执行器使用主机自身的 git 和 gh 用于克隆存储库、推送分支并打开 PR 的 CLI 凭据。启动代理之前在主机上进行一次身份验证：

gh auth login

vps-agent doctor 验证这一点，并且代理拒绝启动，如果 gh 未经过身份验证。 SprintFlint 从不处理您的 GitHub 凭证。

故障排除

开始于 doctor

vps-agent doctor 检查常见故障点并报告错误：

vps-agent doctor

• 确认节点 18+， git, gh, 和 claude 已安装并位于 PATH 上
• 确认执行器已注册并且可以访问 SprintFlint API
• 确认 git 和 gh 在主机上进行身份验证

跑者离线展示

• 运行 vps-agent status 在主机上确认其正在运行
• 确保出站 HTTPS 到 sprintflint.com 没有被阻止
• 重新检查注册令牌；重新生成它 执行器 如果需要的话

作业排队但从未运行

• 确认至少有一个执行器已启动并在线（vps-agent start)
• 跟踪日志 vps-agent logs -f 当您开始自动播放时
• 验证项目有 GitHub一体化 和配置的存储库

PR未开通

• 检查一下 gh 已安装并经过身份验证（gh auth status)
• 确认运行程序可以推送到存储库
• 尝试一下 noop 编码工具，以判断问题出在编码工具还是 Git/PR 流程

下一步

• 自动播放 - 作业如何排队和端到端运行
• GitHub 集成 - 连接存储库并将 PR 链接到工单
• API参考 - 工单评论与整合