macOS 命令行防睡眠工具，使用系统自带的 caffeinate。中文菜单、后台运行、定时、绑定 PID，以及 Codex / Claude 快捷启动。兼容 macOS 自带 Bash 3.2，无需 Homebrew、Python 或管理员权限。
从 Releases 下载 awake-macos.zip。
解压 ZIP，打开终端，输入 bash （末尾有空格），把 install.sh 拖入终端，然后按回车。也可以进入解压目录执行：
bash install.sh也可以从源码安装：
git clone https://github.com/leenlbma/awake-macos.git
cd awake-macos
bash install.sh安装会将 awake、Awake.command、awake-uninstall 放到 ~/bin，并在 ~/.zshrc 添加带标记的 PATH 配置。已有配置会先备份；重复安装会更新工具，不会重复追加 PATH 段，也不会自动启动防睡眠。遇到同名的非本工具文件会中止，不会覆盖。
新开终端后输入 awake。当前窗口也可以执行 source ~/.zshrc，或直接运行 "$HOME/bin/awake"。如使用自定义 ZDOTDIR 或其他 shell，请自行在实际配置文件中加入 ~/bin。
也可不安装：在解压目录执行 ./awake，或双击 Awake.command。双击入口优先启动同目录的 awake，其次启动 ~/bin/awake。macOS 若要求确认文件来源，请按系统提示通过“右键 → 打开”或系统设置允许这个你已核对来源的脚本；不要全局关闭系统保护。若解压软件丢失执行权限，可执行 chmod +x awake Awake.command install.sh uninstall.sh。
| 命令 | 效果 |
|---|---|
awake |
中文交互菜单；退出菜单后，后台任务继续 |
awake on |
使用 caffeinate -i 阻止空闲系统睡眠，允许息屏 |
awake screen |
使用 caffeinate -di 同时阻止空闲系统睡眠和显示器睡眠 |
awake 8h / awake 2h / awake 30m |
到时自动释放防睡眠，允许息屏 |
awake pid 12345 |
使用 -i -w 12345，目标进程退出后释放 |
awake run python3 agent.py |
执行程序，程序结束时释放；保留参数和退出码 |
awake codex / awake claude |
在防睡眠保护下启动已安装的 CLI，也可追加参数 |
awake status |
显示本工具状态、所有可见的 caffeinate 进程和 pmset -g assertions |
awake stop |
只停止本工具的一个后台任务 |
awake stop-all |
显示影响范围，输入 STOP-ALL 后停止列表中有权限操作的 caffeinate |
awake help |
查看帮助 |
最常用的操作：
awake 8h
# 然后按 Control + Command + Q 锁屏
# 提前结束防睡眠：
awake stop时长支持正整数加小写 s / m / h，最长 365 天；不接受 0h、负数、小数、前导零或 1h30m。例如一小时半可写 awake 90m。
后台模式（on、screen、定时、pid）同一用户只保留一个任务。重复启动同一模式不会产生额外进程，也不会重置定时；要重新计时或切换模式，请先 awake stop。不同用户分别管理自己的状态。
awake run、awake codex、awake claude 是独立的前台任务，可以和后台模式同时存在；awake stop 不停止它们。请保留对应终端，按程序自身退出方式或通常使用的 Control+C 结束。关闭终端可能结束前台 Agent；锁屏不会关闭终端。绑定 PID 只保护目标进程存在期间，不会重启 Agent，也不会跟踪其退出后留下的子进程。
命令行参数按原样传递，不使用 eval。别名和 shell 函数不是可执行程序；管道、重定向或多条命令需要显式运行 shell：
awake run /bin/zsh -l -c 'python3 agent.py | tee agent.log'
awake run /path/to/program '带空格的参数'菜单中的“执行命令”会明确按 zsh 命令行语法处理输入。Codex / Claude 需提前安装并位于 PATH；工具不会安装这些 CLI 或替你登录。
- 锁屏：限制访问桌面，现有进程仍可运行。使用 Control + Command + Q。
- 息屏：显示器关闭，系统仍可运行。
awake on和定时模式允许息屏。 - 系统睡眠：CPU 和多数本地任务会暂停；
-i阻止因空闲进入这种状态。 - 合盖：MacBook 通常会进入睡眠；本工具不能可靠绕过合盖行为。长任务建议保持开盖、接电、通风。Apple 支持的外接显示器合盖模式取决于机型、供电和外设条件，不能仅依靠本工具。
本工具不修改 pmset 永久设置，不主动锁屏，不阻止用户主动选择“睡眠”、关机或重启，也无法保证低电量、系统更新、断网时任务继续。屏幕常亮更耗电。锁屏后，依赖解锁桌面、鼠标或屏幕识别的自动化仍可能不可用；防睡眠只保证相应电源断言，不保证 Agent 本身成功。
如果 Codex / Claude 程序一直停留在交互提示符，程序尚未退出，awake run 的防睡眠就仍然有效。其他应用也可能持有电源断言；停止 Awake 后是否立即睡眠由系统设置和所有现存断言共同决定。
状态位于 ~/Library/Application Support/Awake/background.pid，目录仅当前用户可访问。文件记录 PID、启动时间和 caffeinate 命令行，读取时不会执行其内容。停止前会核对进程身份，避免简单 PID 文件过期后误停其他进程；僵尸进程或失效记录会在下一次状态、启动或停止操作时清理。重启后不自动恢复防睡眠。
后台进程使用 nohup 并关闭终端输入输出，退出启动它的终端后仍可运行。并发操作通过 macOS 自带 shlock 串行处理；失效锁可自动恢复。若状态记录被手动删除或损坏，工具会放弃认领原进程，以避免误杀；请通过 awake status 核对，再选择明确确认的 awake stop-all。
stop-all 会影响其他程序启动的 caffeinate，也可能取消正在运行的 Agent 的防睡眠保护，因此必须在交互终端确认。它只处理确认前列出的进程，并再次核对身份；其他用户的进程可能无法停止，会报告失败，不自动提权，也不会停止使用其他方式持有的电源断言。它不是停止 Agent 的命令。
设置 NO_COLOR=1 可关闭颜色；重定向输出时自动关闭颜色。
"$HOME/bin/awake-uninstall"
# 或在原始解压目录中：
bash uninstall.sh卸载会停止本工具管理的后台任务，移除本工具安装的文件和标记范围内的 PATH 段。不会停止其他 caffeinate 或前台 Agent。修改配置前会创建备份；空状态目录会被移除，其他文件和备份会保留。当前终端已加载的 PATH 不受影响，新终端使用更新后的配置。
awake：主程序。install.sh/uninstall.sh：安装与卸载。Awake.command：Finder 双击入口。README.md：本说明。TESTING.md：实际验证结果与范围。
采用 MIT 许可证，允许使用、修改、分发及商业使用，请保留版权和许可证声明。
欢迎提交 Issue 或 Pull Request。开发和测试方法见 CONTRIBUTING.md；GitHub Actions 会在 macOS 上运行集成测试。
作者：Leen Ma（署名 LeenMa）。小红书：motor，GitHub：leenlbma，均为同一人。联系：leenlbma@gmail.com。
Author: Leen Ma (also written LeenMa). Xiaohongshu: motor. GitHub: leenlbma. All the same person. Contact: leenlbma@gmail.com.