rohanprichard/claude-overnight · 上手攻略

仓库：rohanprichard/claude-overnight
链接：https://github.com/rohanprichard/claude-overnight
分类：AI Agent 工具 · 效率神器
作者：Tom
更新：2026-09-26

§1 是什么

claude-overnight 是一个让 Claude Code 夜间自动运行排队任务的工具。白天用 /queue 把研究问题丢进队列，深夜当 Claude Code 配额刷新后，overnight 自动批量执行，早起收获一叠 Markdown 研究报告。

本质是配额感知的定时调度器：它不仅看时间，还实时检查你的 5 小时每日窗口和周配额余额，在确认有可用额度时才启动任务队列，避免白跑一场或透支配额。

核心场景：把 Claude Code 的碎片闲置配额变成夜间自动化研究机器。

§2 解决什么问题

Claude Code 有每周配额上限（Pro 5 小时/周），很多人每天用不满，结果周末一看——配额悄悄过期，一分钟都没留下。overnight 把这部分浪费的配额利用起来：

白天排队问题，夜间自动跑
配额紧张时自动暂停，不透支
醒来直接读 Markdown 报告，不需要盯着跑

对于程序员还有一个进阶用法：对代码仓库排队实际工作（加功能、修 Bug、跑测试），用 git worktree 隔离，不碰主分支。

§3 快速安装

前置要求

macOS 或 Linux
Python 3.11+
Claude Code CLI（Pro 或 Max 订阅）
uv 包管理器（推荐）或 pipx

安装步骤

# 推荐用 uv 安装（单命令，无需配置环境）
uv tool install claude-overnight

# 或用 pipx
# pipx install claude-overnight

# 安装调度器 + 注册 /queue 等 slash 命令
overnight install

overnight install 做两件事： 1. 注册调度器：macOS 注册 launchd agent，Linux 注册 systemd user timer，每 30 分钟检查一次是否在夜间窗口且配额有余 2. 安装 slash 命令：把 /queue、/followup、/status 注入 ~/.claude/commands/，在 Claude Code 内直接使用

验证安装

overnight status   # 查看当前 5h / 周配额使用情况
overnight list    # 查看队列（刚装完应该为空）

§4 核心用法

白天：排队研究问题

# 从任意终端添加问题
overnight add "how do sqlite WAL checkpoints actually work?"

# 在 Claude Code 内部用 slash 命令（更自然）
# 在任意 Claude Code 会话中输入：
/queue what are the tradeoffs of CRDTs vs OT for a collab editor?

查看与管理队列

overnight list           # 列出所有排队任务
overnight status         # 当前 5h 窗口 + 周配额使用情况
overnight add --after 2026-09-28 "research this before the meeting"  # 定时到指定日期

夜间：自动运行

凌晨 3:00 左右，配额刷新，窗口开启，overnight 触发：

💤 3:00 am — 配额刷新，夜间窗口开启，批量任务开始运行

每个任务以 headless 模式执行（claude -p），工具限制为仅网络搜索（研究任务）或全工具（代码任务，需在信任仓库中）。

早晨：收获结果

# 查看当天所有结果
overnight results

# 查看特定报告
overnight results <id>     # 用任务 ID 指定某篇报告
overnight results 1        # 查看第一篇

# 打开 HTML 摘要页面（包含所有报告，内联渲染）
overnight open

# 继续某个任务的会话（进入 Claude Code 对话，延续当时的上下文）
overnight resume <id>

# 对已完成任务追加追问，下次窗口继续运行
overnight followup <id> "now compare against Yjs specifically"

调试与测试

# 预览本次会实际执行什么（不真正运行）
overnight run --dry-run

# 立即强制运行（忽略夜间窗口和配额检查）
overnight run --force

# 重试失败任务
overnight retry

# 也重试崩溃后卡住的任务
overnight retry --stuck

进阶：代码仓库任务

# 先信任一个仓库（一次性）
overnight trust ~/code/myapp

# 对信任的仓库排队编程任务
overnight add --repo ~/code/myapp \
  "add a dark mode toggle to settings; follow the existing theme pattern and run the tests"

# 也可以在 Claude Code 会话里直接 /queue
# （进入仓库目录后 /queue 自动捕获当前仓库路径）

代码任务在独立的 git worktree（专门分支）上运行，主分支和 working tree 完全不受影响：

# 早上审阅 diff
git diff main..overnight/add-a-dark-mode-toggle-3f9c2a

⚠️ 代码任务使用 bypassPermissions 模式（v0.6+ 修复），意味着任务可以在仓库里执行任意 shell 命令，包括运行测试。只对你信任的仓库使用 overnight trust。

§5 典型适用场景

场景	怎么用 overnight
睡前研究问题	白天 /queue 5 个问题，醒来收获 5 篇结构化报告
技术调研	对比方案调研、竞品分析、技术选型评估
睡前写代码	用 trust + /queue 对项目加功能，第二天 merge diff
定时研究任务	`overnight add --after <date>`，指定日期自动触发
长篇代码审查	队列里放多个审查问题，按优先级排队，夜间完成
论文/文档撰写辅助	把相关问题拆解成子问题，批量研究，早起整合

§6 坑与注意

⚠️ 配额感知不等于配额增加：overnight 不会给你更多配额，只是确保在有配额时才跑。如果每天用满 5 小时，overnight 无用武之地。
⚠️ 调度延迟：overnight install 注册的是每 30 分钟检查一次，不是精确到点的定时器。凌晨窗口开启后最多等 30 分钟才触发。
⚠️ 工作邮箱通知：overnight 使用工作邮箱发送调度失败等系统通知，默认读取系统邮件发件配置（macOS mail 命令），无邮件配置时通知可能静默失败。
⚠️ macOS 睡眠：如果 Mac 凌晨进入睡眠状态，launchd 定时器可能不触发（取决于系统电源管理设置）。建议 Mac 在夜间保持电源接入+不休眠。
⚠️ 研究任务工具限制：研究任务只允许网络搜索，不支持文件操作或本地命令。如果需要读本地代码，用代码任务模式并先 overnight trust。
⚠️ v0.6 以下版本：repo_job_timeout_minutes 默认为 45 分钟，如果仓库较大或测试较慢，可以调整此参数避免超时。
⚠️ 升级：uv tool install --upgrade claude-overnight，无需重新运行 install，配置文件不变。

§7 与同类对比

工具	定位	优势	劣势
claude-overnight	Claude Code 配额感知调度	配额外剩余利用、配额保护、worktree 隔离	仅支持 Claude Code（需 Pro/Max）、非通用调度
Cron + Claude Code	通用定时触发	任意时间触发	不感知配额，可能在无额时白跑
OpenAI Assistants API	云端 Agent 批量运行	通用性强	无本地配额概念
AutoGPT / AgentGPT	全自动 Agent 平台	独立运行	贵、本地控制力弱
Loom / Zapier 等	自动化工作流	生态丰富	非 LLM 原生

overnight 的核心差异化：专门为 Claude Code 配额碎片设计的调度器，配额感知是它独有的护城河。

§8 一句话推荐结论

如果你订阅了 Claude Code Pro/Max，但每天用不满 5 小时——claude-overnight 把这些碎片化的闲置配额变成一台夜间研究机器，起床就能读报告，代码还能直接 merge 进分支。