Notiamo 可以针对项目中未处理的评论和任务启动 AI 代理。代理负责做出修改,由你团队中的一个人批准。运行可以在 Notiamo 的服务器上进行,也可以在你自己的电脑上进行。本页讲的是第二种方式:运行器,一个安装在你机器上的小程序。它是给代理机构团队用的。

运行器是什么

运行器等待你的组织在 Notiamo 中排队的代理运行。对每次运行,它会克隆仓库(或连接到 WordPress 网站),用这次运行的指令启动 Claude Code,把代理的操作发送给 Notiamo,并在结束时汇报。

  • **它不持有任何 Claude 凭据。**它启动机器上已有的 claude 程序。运行器的会话使用自己的配置文件夹,因此与你自己的会话互不干扰。登录本身属于 Claude Code,由 Claude Code 保管。
  • **它不是 Notiamo 里的 Claude 登录。**Notiamo 从不查看或使用你的 Claude 账号。运行器只是在你的机器上,为你自己的工作运行你自己的 Claude Code。

安装

你需要:

  • Node.js 22 或更高版本;
  • Claude Code 2.1.314 或更新版本;
  • git 2.31 或更新版本;
  • 在 Linux 和 WSL2 上:bubblewrap 和 socat(Debian 或 Ubuntu:sudo apt install bubblewrap socat)。在 macOS 上无需再安装任何东西。

然后:

  1. 在 Notiamo 中打开设置 › 代理运行。在运行器卡片上点击新建运行器并给它起个名字。复制令牌。它只显示一次。
  2. 在这台机器上运行:
npx @notiamo/runner init
  1. 粘贴令牌。init 会检查 Claude Code 是否正常,为运行器运行 Claude Code 的登录,然后安装服务并启动它。
  2. 在项目上,把代理在哪里运行设为自有机器。

init 结束时,运行器已经在运行。登录或重启之后,它会自动再次启动。

命令

命令 作用
npx @notiamo/runner init 设置运行器:令牌、Claude Code 登录、安装并启动服务。
npx @notiamo/runner@latest update 把运行器升级到最新版本。令牌、名称和登录保持不变。
npx @notiamo/runner status 说明服务是否已安装并在运行,并显示最后一行日志。
npx @notiamo/runner logs 显示日志的最后 50 行。
npx @notiamo/runner stop 停止服务,直到下次登录或开机。
npx @notiamo/runner uninstall 移除服务。运行器的文件夹保留。
npx @notiamo/runner env <projectId> 创建或显示这台机器提供给某个项目运行的 env 文件。
npx @notiamo/runner start 在前台运行。服务运行的就是这个命令,你很少需要用到。

在 macOS 上,服务是 launchd 代理 com.notiamo.runner;在 Windows 上是计划任务“Notiamo runner”;在 Linux 上是 systemd 用户单元 notiamo-runner。

一台机器上的两个运行器

npx @notiamo/runner init --profile staging 会设置第二个独立的运行器。它有自己的文件夹(~/.notiamo-runner/profiles/staging)和自己的服务。该运行器的每条命令都要加上 --profile staging。配置名称由字母、数字和连字符组成,长度为 1 到 32 个字符。

代理能碰什么,不能碰什么

每次运行都有自己的 Claude Code 设置文件。有三道限制让代理待在自己的范围内。

**文件工具只在运行文件夹内。**Claude 自己的文件工具(读取、编辑、写入、搜索)会拒绝运行文件夹之外的一切。任何需要请求权限的调用都会被拒绝,因为没有人在场回答。

**shell 命令在操作系统的沙箱中运行。**在 macOS(Seatbelt)以及 Linux 或 WSL2(bubblewrap 和 socat)上,代理在 shell 中运行的每条命令都受到限制。如果沙箱无法启动,运行就不会开始。

**机器上的任何凭据都到不了代理。**Claude Code 只会得到一小份环境变量列表(PATH、HOME、USER、LOGNAME、SHELL、LANG、LC_ALL、LC_CTYPE、TERM、TMPDIR、TZ、XDG_*、代理和证书设置),外加这次运行自己的变量。它永远得不到 SSH_AUTH_SOCK、GH_TOKEN、GITHUB_TOKEN、NPM_TOKEN、AWS_* 或 ANTHROPIC_*。代理的 git 看不到任何全局或系统 git 配置。

shell 沙箱允许和拒绝的内容:

  • **禁止读取:**其他项目的文件夹(包括同时进行的其他运行)、运行器自己的文件,以及你的凭据文件和文件夹(SSH 密钥、云服务登录、软件包仓库登录、git 凭据)。
  • **允许写入:**仅限运行文件夹和它旁边该项目的软件包缓存文件夹。这次运行的 .git/hooks 和 .git/config 是只读的。
  • 允许联网:GitHub、npm、Notiamo、WordPress 网站(对于 WordPress 运行),以及你在运行器卡片的代理可访问的额外主机中添加的主机。其他一律被拒绝。

代理从不推送,也不持有任何凭据。代理工作完成后,由运行器自己推送这次运行的分支。

运行结束时,运行器会停止代理留下的所有进程,例如开发服务器。

macOS 上的钥匙串

macOS 的沙箱并没有完全封住钥匙串。因此,不要在运行运行器的那个用户的钥匙串里保存任何 GitHub 登录(init 发现时会提醒你)。最安全的做法是使用一个有自己钥匙串的专用 macOS 用户。

Windows

普通的 Windows 没有 shell 沙箱。这样,评论里的文字就可能让一次运行以你的身份执行任何命令。请在 WSL2 中运行运行器。在普通的 Windows 上,除非你在运行器的 config.json 中加入 "allowUnsandboxed": true,否则运行器不会启动;只在没有存放其他东西的机器上这样做。

同时进行多个运行

在运行器卡片上设置同时运行数:1 到 3。每次运行都会用到你的 Claude 套餐,所以请把数量控制在套餐承受得了的范围内。同一个项目绝不会同时运行两次:同一项目上的第二次运行要等第一次结束。

同时进行的每次运行都有自己的槽位文件夹。一次运行的沙箱读不到其他槽位。

为某一个客户准备的运行器

创建运行器时,你可以在运行范围中把它限制在一个工作区。这样它只接这个客户的运行。要在客户的电脑上设置:在那里安装 Claude Code,运行 npx @notiamo/runner init,然后粘贴运行器的令牌。运行的费用由那台电脑上的 Claude 登录承担,所以请用应当付费的账号登录。

准备命令和测试命令

刚克隆下来的仓库没有安装任何软件包。请告诉代理如何安装,以及如何测试。打开项目的代理设置,填写准备命令和测试命令,各一行。

  • 代理在第一次修改之前运行一次准备命令。例如:pnpm install --frozen-lockfile。
  • 代理在每次提交之前运行测试命令。没通过的修改会被修好或撤销。例如:pnpm typecheck && pnpm lint。
  • 这两条命令由代理自己运行,与它的其他命令在同一个沙箱中。软件包仓库必须在允许的主机之列。GitHub 和 registry.npmjs.org 默认就在其中。其他任何仓库(PyPI、crates.io、私有仓库)都要在运行器卡片的代理可访问的额外主机中添加。
  • 每个项目在它的克隆旁边都有一个软件包缓存文件夹。npm、pnpm、Yarn、Corepack、Bun、pip、uv 和 Composer 把缓存放在那里,因为沙箱封闭了你主目录里的常用位置。该文件夹在项目的多次运行之间保留,并随克隆一起消失。普通 Windows 上没有这个文件夹。
  • 让测试命令保持轻量。需要 Docker 的测试无法运行。需要数据库的测试,只有在项目的 env 文件指向一个你一直开着的数据库时才能运行(见下文)。

代理以“Notiamo agent”的名义提交,每个条目一行简明的说明。运行器会关闭 Claude Code 的“Co-Authored-By”尾注和“Generated with”行,所以仓库里不会出现 AI 共同作者。

为你自己的项目准备的环境

GitHub 项目上的一次运行只会得到一份干净的克隆,别无其他。对于你自己的软件项目,测试可能还需要数据库、文件存储、邮件捕获工具和一个 .env。运行器所在的机器用一个普通文件把它们提供给某个项目的运行:

npx @notiamo/runner env <projectId>

<projectId> 是 Notiamo 中项目页面地址的最后一部分。这条命令会创建 ~/.notiamo-runner/env/<projectId>.env,只有你能读取,并打印出路径。每行写一个 KEY=VALUE。该项目的下一次运行会在它的 shell 中得到这些变量,代理只被告知变量名,从不告知变量值。删除这个文件就能撤走它们。这个文件永远不会离开这台机器:Notiamo 并不知道它的存在。

有了这个文件,在 macOS 上这次运行的 shell 还可以访问 127.0.0.1 上的服务:你的 Postgres、文件存储、开发服务器。这些服务由你保持运行;代理无法启动它们,Docker 也在它够不到的地方。在 Linux 上,沙箱有自己的网络,所以那里的 127.0.0.1 不是这台机器的:请把服务绑定到机器的网络地址,并把该主机添加到代理可访问的额外主机中。

规则:

  • **只用开发和测试用的值。**代理会运行 shell 命令,能读到每一个变量。绝不要放生产环境的密钥,绝不要放你在别处使用的密码。
  • PATH、HOME、代理和证书变量、NODE_OPTIONS、NODE_TLS_REJECT_UNAUTHORIZED、NOTIAMO_*、GIT_*、CLAUDE_* 和 ANTHROPIC_* 会被忽略,日志里会说明。这个文件可以改变代理的命令所看到的内容,但改变不了 Claude Code 与 Anthropic 和 Notiamo 的通信方式。
  • 6 个字符或更长的值,在 Notiamo 收到的记录中会被遮盖为 [secret]。较短的值(1、true)则不会。
  • 当一个运行器上的多个项目通过各自的 env 文件共用一个数据库时,请把同时运行数保持为 1。两次同时进行的运行会在同一个数据库上运行测试。

WordPress 网站

连接设置在项目的网站访问卡片上:一个应用密码,还可以选择 SSH 或 FTP。运行器在第一次连接时记住 SSH 服务器的密钥,之后如果服务器出示另一个密钥,运行器会拒绝它。一次运行是这样进行的:

  1. **先备份。**使用 SSH 时,运行器会导出数据库,压缩后上传到 Notiamo,最大 200 MB。Notiamo 会保留 30 天。只用 FTP 或 API 时没有备份。
  2. 代理按照下面的允许清单工作。
  3. **事后检查网站。**运行器打开网站,检查它是否仍有响应。
  4. **失败时恢复。**如果检查失败,运行器会恢复数据库。

代理可以用 wp-cli 运行的命令,按分组列出(在项目上设置):

  • 内容:post *、term *、menu *、media import、option get、option update。
  • 数据库:search-replace(只能给出旧文本和新文本;它绝不会触碰用户表和选项表)、cache flush、rewrite flush、transient delete。
  • 插件和主题:plugin 和 theme 的 list、activate、deactivate、update。
  • 信息:core version、site list、db size。
  • **文件:**没有 wp-cli 命令;代理使用它的文件工具。文件工具可以写入样式、脚本和服务器不会执行的其他文件。
  • PHP 文件(默认关闭):文件工具也可以写入 PHP。PHP 文件是在你的服务器上运行的代码,而 WordPress 运行没有审批步骤:更改会立即生效。只有当你信任所有能写评论的人时,才为该网站打开它。
  • 绝不允许,除非你选择“允许所有操作”:eval、eval-file、shell、user *、db query|import|reset|drop|export、plugin install、theme install、core update|download。

什么存在哪里

所有内容都在 ~/.notiamo-runner 中。

路径 存放的内容
config.json Notiamo 的地址、运行器的名称和运行器令牌。只有你能读取。
claude/ 运行器的 Claude Code 配置文件夹:它的登录和会话。
projects/ 你的项目的工作副本,每个槽位中每个项目一个文件夹。超过运行器卡片上设定的天数没有使用的项目会被删除;下次运行会重新克隆。
git/ 运行器自己保存的仓库副本。代理既不能读取也不能写入这个文件夹。
env/ 你创建的 env 文件,每个项目一个。
runs/ 每个进行中的运行的 Claude Code 设置。不含密钥。运行结束时删除。
runner.log 运行器做过的事,不含密钥。
state.json 进行中的运行的 id。重启之后,每一个都会向 Notiamo 报告为失败。

一次运行的密钥(WordPress 密码、这次运行自己的令牌)随运行从 Notiamo 发来,只保存在内存中。代理以环境变量的形式得到它们,绝不通过文件。代理输出的内容在上传记录之前,会先清除其中的这些密钥。

运行器从不使用机器上的 git 凭据。每次运行都会从 Notiamo 得到一个 GitHub 令牌,有效期一小时,且只对这次运行的仓库有效。运行器把它保存在内存中,用于自己的 fetch 和 push。拉取请求由 Notiamo 创建并合并。

停止运行器

在运行器卡片上,点击停用可以暂停运行器,点击删除可以移除它。被删除的运行器的令牌会立即失效。