它到底是什么

claude self-hosted-runner 是官方 CLI reference 中记录的子命令，用于启动一个运行程序（runner）进程，把本机或容器注册到 self-hosted environment（自托管环境），从而在用户自有基础设施上托管 Claude Code 云会话（cloud sessions）。它是标准 claude 二进制文件自带的能力，要求 Claude Code v2.1.224 或更高版本；更早版本无法识别 self-hosted-runner 子命令，会直接回落成打印通用的 claude --help。

该功能面向 Team 和 Enterprise 计划的组织，目前处于公开 beta 阶段，默认关闭，需要组织的 Owner 在 claude.ai 的 Cloud environments 管理页开启「Allow self-hosted environments」；启用 ZDR（零数据保留）的组织无法使用该功能。

用法 / 语法

claude self-hosted-runner <setup|doctor|orchestrator>

不带子命令、直接携带启动参数时，用于真正跑起一个 runner 进程：

claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>'

已确认的 flag：

检查主机是否就绪：

claude self-hosted-runner --help

就绪的主机会打印出 runner 的 usage 文本（包含 --environment-secret-file 等 flag）；版本低于 v2.1.224 时，这条命令只会打印通用的 claude --help。

Shell 集成 / 自动化

Runner 进程设计为会在其活跃会话全部结束后自行退出（这是既定行为，参见 Runner lifecycle）。生产部署需要把它放在会在进程退出后自动重启的 orchestrator/supervisor 之下（文档给出了 Kubernetes 和 Docker Compose 的部署方案）。

向已经在自托管环境中运行的云会话发送后续消息，用的是同一 claude CLI 但不同的命令（不属于 self-hosted-runner 子命令树），可在任意已 claude auth login 的机器上执行：

claude -p "your message" --cloud <session-id>

成功时打印 Sent to cloud session. 及会话 ID、查看链接。

运行约束 / 限制

经典使用场景

• 首次搭建：在准备作为 runner 的主机上执行 claude self-hosted-runner setup，走完引导流程，得到一个可轮询任务的 runner 和 ./runner-setup/CHEAT-SHEET.md 速查表。
• 手动/脚本化部署：不具备交互式会话的主机（如容器镜像构建阶段）改走手动路径——写入 secret 文件、指定 --base-dir 后直接启动 runner 进程，交给 systemd/Kubernetes/Compose 等编排系统管理重启。
• 故障诊断：runner 部署后行为异常（如一直显示 "No runners deployed"、认证失败）时运行 claude self-hosted-runner doctor 排查。
• 弹性伸缩场景：不想长期占用固定数量的 runner 主机时，用 claude self-hosted-runner orchestrator 搭配自定义 spawn-runner hook，实现"有排队会话才拉起 runner、会话结束就回收"的按需模式。

常见坑

• 版本过旧（< v2.1.224）时，claude self-hosted-runner setup 不会报错提示版本不符，而是直接把这行命令文本当作 prompt 启动一个普通 Claude 会话，容易让人误以为命令生效了；应先用 claude self-hosted-runner --help 确认能打印出 runner 的 usage 文本（含 --environment-secret-file），而不是通用帮助。
• 不指定 --base-dir 时默认落到 /workspace，如果该目录不存在或不可写、又没有以 root 启动，runner 会在启动阶段直接报错退出（提示相关目录名），而不是注册失败后重试。
• environment secret 被轮换/吊销后，持有旧 secret 的 runner 会在下一次带认证的轮询请求中失败并退出，日志输出 poll auth failed；需要依赖 orchestrator 用新 secret 重启它，手动启动的 runner 不会自愈。
• 想在 Windows 上跑 runner 会直接不受支持，必须改用 Linux 容器。

来源

• CLI reference - Claude Docs
• Self-hosted environments quickstart - Claude Code Docs
• Deploy self-hosted environments to production - Claude Code Docs
• Customize sessions in self-hosted environments - Claude Code Docs
• Self-hosted environments for Claude Code - Claude Blog