Pilot Shell License 系统完整指南：激活、7天试用与机器绑定一次讲透-平芜编程栈

Pilot Shell License 系统完整指南：激活、7天试用与机器绑定一次讲透

【免费下载链接】pilot-shellProfessional context and harness engineering for Claude Code and OpenAI Codex. Build production-grade software with spec-driven development, TDD, persistent memory, quality gates, code intelligence, human oversight, and end-to-end verification.项目地址: https://gitcode.com/GitHub_Trending/cl/pilot-shell

Pilot Shell 是一款面向 Claude Code 与 OpenAI Codex 的上下文工程与开发规范增强工具（AI coding harness）。它的 License 系统决定了你的解锁层级：7 天免费试用（Trial）、Solo 单人订阅、Team 团队订阅，并内置机器绑定与失效恢复机制。本文基于仓库源码与官方文档，带你快速看懂激活、试用与机器绑定的完整原理。

🔑 只需记住三条命令：pilot trial --start（领试用）、pilot activate <key>（激活订阅）、pilot status（查状态），其余细节看下文。

一、Pilot Shell License 系统是什么：三种访问层级一图看懂

Pilot Shell 的 License 共三种层级，安装时自动检测当前机器处于哪一种：

层级	价格	适用对象	核心权益
🆓 Trial（试用）	免费	任何新机器	完整功能 7 天，每台机器仅限一次
🔵 Solo	$14/月	1 名开发者	规则/钩子/LSP/MCP、Pilot 工作流、持久记忆、浏览器控制台、跨机器技能同步
🟣 Team	$35/席位/月	多人团队	Solo 全部 + 扩展共享、项目记忆共享、内置技能定制、席位管理、优先支持

💡 所有订阅方案均可在多台个人设备上使用——一份订阅，全设备通行，无需为每台电脑单独付费。

二、免费试用指南：如何领取 7 天 Trial 并查看剩余天数

试用是 Pilot Shell License 系统对新用户最友好的入口，两台核心命令如下：

pilot trial --check # 检查本机是否还有试用资格 pilot trial --start # 启动试用（每台机器一次）

关键规则，源码里写得很明确：

机器绑定：试用记录与本机绑定，trial --start在用过一次的机器上会返回trial_already_used错误，无法重置；
自动流程：安装器会自动完成「检查资格 → 启动试用 → 显示剩余天数」，成功后你会看到7-day free trial activated — X days remaining；
剩余天数可见：试用天数实时显示在终端 statusline（状态栏）和 Console 控制台中，到期前一目了然。

试用与激活的完整安装期流程见 installer/cli.py 中的_handle_license_flow函数。

三、许可证激活步骤：pilot 命令速查表

所有 License 操作都集中在pilot二进制（位于~/.pilot/bin/pilot），官方命令清单如下（摘自 docs/docusaurus/docs/features/cli.md）：

命令	作用
`pilot activate <key>`	在本机激活 License Key
`pilot deactivate`	解除本机与 License 的绑定
`pilot status [--json]`	查看当前 License 状态与层级
`pilot trial --check / --start`	检查试用资格 / 启动试用
`pilot portal [--no-browser]`	打开客户门户：席位、发票、支付方式、找回 Key

两个值得注意的细节：

安装期最多重试 3 次：若 License 无效，安装器会提示输入 Key，每次输入都会调用pilot activate <key> --json在线校验（见 installer/cli.py），3 次失败后才放弃并给出订阅入口；
门户 ≠ 登录：pilot portal使用结账时的邮箱登录，License Key 本身不能打开账单——因此队友机器上的 Key 无法访问你的支付信息，这是刻意设计的安全边界。

四、机器绑定原理：~/.pilot 下的授权文件与运行时校验

Pilot Shell License 系统采用「本地文件 + 远程校验缓存」双层机器绑定，核心文件都在~/.pilot/目录下（该目录在所有 Claude 配置间共享）：

文件	作用
`~/.pilot/.license`	本机授权文件，是 Pilot 各钩子能否执行的第一道门
`~/.pilot/.license-access.json`	「访问中断」标记，出现后所有付费钩子立即静默停跑
`pilot verify --json`	会话级校验，带24 小时 TTL 缓存，正常路径零网络延迟

具体机制在两份钩子源码中一目了然：

钩子门控pilot/hooks/run_if_licensed.py：每个 Pilot 钩子执行前先检查.license是否存在、.license-access.json是否出现。有效则通过os.execv替换为真实钩子继续跑；无效则直接跳过，不产生任何副作用。
会话校验pilot/hooks/license_check.py：作为SessionStart钩子，在每次会话开始时调用pilot verify --json复核状态（走 24h 缓存，不拖慢启动）。

这套设计的巧妙之处：校验状态存在本地，校验逻辑却是「先跑再核对」，既保证响应速度，又让失效能被及时感知。

五、License 失效会怎样：不阻塞的降级设计与恢复方法

⚠️ 这是新手最关心的问题：License 失效后，Pilot Shell不会锁死你的终端。官方采用 fail-open（故障放行）设计：

Claude Code 与 Codex 本身保持可用，只是 Pilot 托管的规则、工作流、质量钩子、Console 与状态栏指标被暂停；
statusline 变为一条平静的恢复提示，Console 只打开License 恢复屏，提示激活新 Key；
pilot activate、pilot status、pilot portal、版本更新与安全卸载器始终可用——不想继续用 Pilot？随时可以干净卸载，不会带走你的 AI 编码代理和用户数据；
输入一个新的有效 Key 即可立刻恢复全部功能。

会话级通知区分四种失效状态（见 pilot/hooks/license_check.py）：deactivated（被停用）、trial_expired（试用结束）、validation_required（无法在线验证）、invalid（无有效授权）。

六、多台设备与团队订阅：License Key 找回与席位管理

换电脑/重装系统：在新机器执行pilot activate <your-license-key>重新绑定即可，同一 Key 可在多台个人设备上先后激活；
忘记 Key：pilot portal打开客户门户，用结账邮箱登录即可找回 License Key、查看发票、增删团队席位（门户能力见 installer 文档与pilot portal说明）；
团队扩容：Team 层级在门户中集中管理席位，新成员拿到自己的 Key 后在各自机器上pilot activate即可，扩展与项目记忆通过仓库共享。

七、常见 License 错误速查表

现象 / 错误	含义	解决方法
`trial_already_used`	本机已用过试用	购买订阅，或换机器试用
`Trial has expired`	7 天试用结束	输入 License Key 激活
`deactivated`	访问被远程停用	联系支持或激活新 Key
`validation_required`	Key 无法在线验证（常因断网）	联网后等待缓存刷新
`expired`（订阅）	Solo/Team 订阅到期	在门户续费后自动恢复

结语：为什么这套 License 设计值得参考

Pilot Shell License 系统的精髓可以概括为三点：试用机器绑定防白嫖（每台机器一次）、运行时校验零延迟（本地文件 + 24h 缓存）、失效体验不粗暴（降级提示而非锁死）。如果你正在为自己的 AI 工具设计授权体系，installer/cli.py、pilot/hooks/run_if_licensed.py 与 pilot/hooks/license_check.py 是三个最值得精读的文件。