文档

OpenRoutine 的一切都由两个纯文本文件驱动：一个你拥有的 Markdown 任务文件，和一个 写明哪些文件要运行、智能体是什么的 config.toml。

• 安装
• 最初五分钟
• 任务文件
• 配置
• CLI 参考
• REST API
• 部署
• 概念

安装

仅支持 macOS 和 Linux，明确不支持 Windows。Homebrew、PyPI、npm 装的都是同一个 预编译二进制文件——只有 cargo 这两条路需要 Rust 工具链。

brew tap soulmachine/tap https://github.com/soulmachine/openroutine
brew trust --formula soulmachine/tap/openroutine
brew install openroutine     # 预编译二进制，不需要 Rust
pip install openroutine      # 或从 PyPI 安装——同一个二进制，打包成 wheel
npm install -g openroutine   # 或从 npm 安装
cargo install openroutine    # 或从 crates.io 源码编译

brew tap 这行要带上仓库地址，因为这个仓库本身就是 tap，而不是另建一个 homebrew-* 仓库；Homebrew 6 还要求先信任第三方 formula 才会加载它。

openroutine init             # 写入配置，打印一个示例任务
openroutine add hello.md     # 注册一个任务文件
openroutine list             # 查看哪些任务会运行
openroutine serve            # 在前台运行调度器
openroutine install          # 或注册为开机服务，无需 sudo

init 写入 ~/.config/openroutine/config.toml，并打印一个可以 照抄的示例任务。把它以 Markdown 存到任何地方，再用 openroutine add 注册即可。没有其他需要配置的东西。

最初五分钟

openroutine init 打印的内容（原样为英文），以及接下来该做什么。

Wrote config …/config.toml

A task is one markdown file. A starter, to save as hello.md:

---
name: hello
description: Say hello, nightly
cron: "0 9 * * *"
---

Say hello, then stop. This is a sample task — edit it freely.

Try:  openroutine add hello.md          # register it
      openroutine list                  # what would run
      openroutine run hello --dry-run   # what it would do
      openroutine serve                 # start the scheduler

Nothing fires until a daemon is running. `openroutine install`
registers one with your service manager, without sudo.

run --dry-run 是最先值得一试的命令。它渲染出完全解析后的执行计划 — 命令行、环境变量、工作目录、接下来的触发时刻 — 而不启动任何东西。它是一次读取， 不是一次运行；什么都不会被记录。

任务文件

任务就是单个 Markdown 文件，用 openroutine add 注册。frontmatter 是元数据， 正文是提示词，这个文件就是任务的完整定义。任务的 id 从 frontmatter 的 name 推导而来，在整台机器上唯一 — 重命名或移动文件不改变任何东西； 而把 name: 改成会推导出不同 id 的内容，就是创建了一个新任务。

---
name: hello
description: Say hello, nightly
cron: "0 9 * * *"
---

Say hello, then stop. This is a sample task — edit or delete it.

frontmatter 键

时长接受 30s、5m、2h、 1d，或裸写的秒数。

正文就是提示词 — 对智能体无话可说的任务会被拒绝。

既没有 cron 也没有 at 的任务是一次性任务 — 守护进程接手后它立刻运行一次，然后显示为已完成。编辑文件后，它会在下一次 openroutine reload 时重新上膛：已完成的任务不会再运行，所以它无法 自己注意到这次编辑。

任务在运行时重新读取自己的文件。一次运行开始的那一刻 — 无论按调度、 被手动触发，还是补跑 — 任务会检查自己文件的 mtime，mtime 变了再查内容摘要；如果定义 变了，运行的就是新定义。所以你刚改好的提示词就是实际执行的那一个。没有任何监视， 也没有任何轮询：没有定时器，没有文件监听，不碰其他任务的文件，也不重读配置。

其余一切都靠重载（reload）。守护进程在启动时，以及 openroutine reload 或 POST /v1/reload 要求时，重新读取配置和 每个已注册的文件；add 和 remove 会自己请求一次。重载是让一次 编辑出现在 list、status 和 Web 界面里的方式，也是一个不会再 运行的任务能注意到编辑的唯一途径 — 已完成的一次性任务只在重载时重新上膛， disabled: true 的任务也无法自己打开自己，因为两者都不再运行。

在触发时刻，一个已经变得无法应答这个时点的定义会撤回它，而不是运行它： 不再能解析的、现在写着 disabled: true 的、以及改了名字的，都会跳过这次 运行并等待一次重载，因为身份变更属于注册表层面的事。cron 时点即使已不在新调度里也照常 运行 — 它在被安排时是正当到期的 — 而 at: 在到点之前被改动过的一次性任务 会被跳过，并在新写的时刻重新上膛。每一种都记录为一次跳过，原因是 definition-changed。

on_failure 和 tz 在 v1 模式中已声明，但尚未生效。 OpenRoutine 会点名警告它们，而不是称之为未知键，因为一个静默无效的键是最糟的结果。

配置

由人拥有、可手工编辑，位于 ~/.config/openroutine/config.toml。 以下是 openroutine init 写入的内容（注释原样为英文）：

# openroutine — https://openroutine.dev

# The agent a task gets when it names none.
default_agent = "claude"

# The task files to schedule. `openroutine add` appends here.
tasks = []

# An agent is a command template. {prompt} is substituted as a
# single argument; without it, the prompt arrives on stdin.
[agents.claude]
cmd = "claude -p {prompt}"

[agents.codex]
cmd = "codex exec {prompt}"

配置键

运行状态 — 上次运行时间、当时安排的时点、记录的跳过、暂停开关 — 由机器拥有，存放在 你仓库之外的一个 scheduled-tasks.json 里。删掉它，丢的是运行历史， 不是任务。

CLI 参考

openroutine --help 可看到同一份列表。全局的 --config <PATH> 可在任何命令上覆盖 XDG 配置路径。

REST API

守护进程监听 127.0.0.1:7373，由 openroutine token 输出的 Bearer 令牌保护。

curl -X POST http://127.0.0.1:7373/v1/tasks/todo-digest/fire \
  -H "Authorization: Bearer $(openroutine token)" \
  -d '{"text": "Sentry alert SEN-4521 fired in prod."}'

可选的 text 以“调用方提供的上下文”标注后送达智能体，而不是作为指令 — 任何能访问端点的一方都能发送 text，因此 text 必须无法重新定义任务本身。

端点

部署

要让守护进程在一台你不守着的机器上无人值守地运行 — 桌下的 Mac mini、一台家用服务器 — 把它注册到系统的服务管理器。

cargo install --path .        # 安装到一个稳定路径；见下文
openroutine init              # 配置；打印一个示例任务
openroutine add hello.md      # 用一个任务验证它能工作
openroutine install           # 注册到 launchd/systemd，无需 sudo
openroutine status            # daemon: running (pid …)

install 记录的是执行注册的那个二进制的路径，所以要用安装后的副本运行它， 而不是 target/release/openroutine — 一次 cargo clean 不应该能 拆掉你的调度器。它写入的是按用户的服务，从不要求 sudo。openroutine install --print 精确显示它会写什么、会运行什么，而不实际写入。

你的智能体必须在登录 shell 的 PATH 上

守护进程通过登录 shell 运行每个智能体，所以一次运行拿到的 PATH、shim 和 API 密钥与你的终端相同。登录 shell 不等于交互式 shell： zsh 读 .zshenv 和 .zprofile 但不读 .zshrc；bash 读 .bash_profile 但不读 .bashrc。 所以一个只靠 .zshrc 放上 PATH 的智能体 — 装在 ~/.local/bin 里的是最常见的情况 — 你手工测试时找得到，launchd 启动守护进程后就不见了：

zsh:1: command not found: claude

openroutine list 会在你踩坑之前发出警告。它按服务管理器的方式采样登录 shell — PATH 以守护进程继承的裸 /usr/bin:/bin:/usr/sbin:/sbin 起步，绝不用你终端恰好有的 PATH — 所以它替守护进程回答，而不是替你回答：

warning: "claude" is on your PATH here but not under a service manager, so
scheduled Runs will fail; move its PATH export into your login profile

修复方式：把 PATH 导出移进 .zprofile（顺带把 SSH 和 cron 会话也修好了），或者用绝对路径指名智能体：

[agents.claude]
cmd = "/Users/you/.local/bin/claude -p {prompt}"

按守护进程将来看到它的方式验证 — 一个不继承你终端任何环境的登录 shell：

env -i HOME="$HOME" SHELL=/bin/zsh PATH=/usr/bin:/bin /bin/zsh -lc 'command -v claude'

macOS

install 向 ~/Library/LaunchAgents/ 写入一个 LaunchAgent，所以守护进程在登录时启动，而不是开机时；它挂掉后 launchd 会重启它。在无人值守的机器上，请搭配自动登录（系统设置 → 用户与群组 → 自动登录为），这要求关闭 FileVault。

自动登录不只是为了让守护进程启动。智能体 CLI 把凭据保存在你的登录钥匙串里， 而钥匙串靠图形界面登录来解锁 — 没有它就启动的服务会发现钥匙串锁着，智能体报告自己 未登录。这也是 install 不写 root LaunchDaemon 的原因：在任何人登录之前 启动，恰恰是智能体无法认证的状态，LaunchDaemon 买到的那一件事正是弄坏它的那一件事。 这笔交换反过来也成立，而且是真实的代价：自动登录加上关闭 FileVault，意味着物理接触 就是一个已登录的桌面。

顺手把机器调成不会睡过自己的调度：

sudo pmset -c sleep 0 displaysleep 0 disksleep 0  # 永不休眠
sudo pmset -c autorestart 1 womp 1                # 断电恢复后自动回来
launchctl print gui/$(id -u)/dev.openroutine.daemon | grep state

Linux

install 写入一个 systemd 用户单元并启用 lingering，所以守护进程在开机时 启动、无需登录会话 — 唯一一个“无需登录”不带星号成立的平台。

systemctl --user status dev.openroutine.daemon
journalctl --user -u dev.openroutine.daemon -f

确认它扛得住

openroutine run <task>   # 一次真实的端到端运行
openroutine logs <task>  # 智能体实际打印了什么

直接杀掉守护进程是公平的测试：服务管理器应当在几秒内以新 pid 把它带回来。 openroutine uninstall 注销它，你的配置、状态和任务原样保留。

概念

CLI、界面和文档共用的词汇表。这里的精确是有意为之 — 其中多数词都有一个含义 微妙不同的近义词。术语本身保留 CLI 与界面实际使用的英文原词。