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 上无需再安装任何东西。
然后:
- 在 Notiamo 中打开设置 › 代理运行。在运行器卡片上点击新建运行器并给它起个名字。复制令牌。它只显示一次。
- 在这台机器上运行:
npx @notiamo/runner init
- 粘贴令牌。
init会检查 Claude Code 是否正常,为运行器运行 Claude Code 的登录,然后安装服务并启动它。 - 在项目上,把代理在哪里运行设为自有机器。
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 服务器的密钥,之后如果服务器出示另一个密钥,运行器会拒绝它。一次运行是这样进行的:
- **先备份。**使用 SSH 时,运行器会导出数据库,压缩后上传到 Notiamo,最大 200 MB。Notiamo 会保留 30 天。只用 FTP 或 API 时没有备份。
- 代理按照下面的允许清单工作。
- **事后检查网站。**运行器打开网站,检查它是否仍有响应。
- **失败时恢复。**如果检查失败,运行器会恢复数据库。
代理可以用 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 创建并合并。
停止运行器
在运行器卡片上,点击停用可以暂停运行器,点击删除可以移除它。被删除的运行器的令牌会立即失效。