运行环境是 Agent 工作的机器。Agent 团队靠共享运行环境 24 小时推进工作。接入共享运行环境需要管理员权限；成员接入自己的运行环境，见 接入个人运行环境。
准备一台机器
| 准备什么 | 要求 |
|---|---|
| 系统 | macOS 或 Linux；Windows 要在 WSL 的 Ubuntu 里运行 |
| 基础软件 | Node.js 24 或更高版本，Git。项目用 NocoBase 应用模板时还要 pnpm，用 Node.js 自带的 corepack 启用：corepack enable |
| 编码工具 | 用官方方式安装并登录，例如 Claude Code 和 Codex。用运行执行机的那个系统用户登录。建议准备两家厂商的工具，评审才能交给另一家厂商的模型 |
| 代码托管平台的命令行 | Agent 用它开 PR：GitHub 用 gh，GitLab 用 glab，Gitee 用 gitee |
| 浏览器 | Agent 改了界面，要在真实运行的应用里截图，附在交付报告里。运行环境上要能运行 Chromium，Linux 上连同它的系统依赖一起安装，例如 npx playwright install --with-deps chromium |
| 网络 | 能访问 Studio 的地址；编码工具能访问各自的模型服务 |
Agent 在这台机器上以运行执行机的系统用户的身份工作，能读写这个用户能访问的一切，包括 SSH 密钥和其他凭证。请用专用的系统用户、容器或虚拟机，不要和 Studio 本身装在同一个用户下。
添加运行环境
- 打开「Agent 管理 › 运行环境」，点「添加运行环境」。
- 「使用范围」选「共享」：可以执行所有用户发起的任务，并会收到发起人的变量和密钥。
- 「编码工具」勾选这台机器上要用的工具。只有勾选的工具的工作会派到这里。
- 「最大并发数」是这台机器同时运行的工作数，默认 3，按机器的资源和模型额度设置。订阅会话数较少的工具，可以在「高级：按编码工具限制」里单独设上限。
- 点「生成安装命令」，选择这台机器的系统。
工具和并发数，之后都可以在运行环境的详情里修改。
命令中带有一次性凭证，用于添加一个「共享」运行环境。只能使用一次。几秒钟后，运行环境会出现在列表中。
在机器上安装
安装有两种方式，任选一种。
提示词。 把对话框里的完整提示词复制给这台机器上的编码工具，例如 Claude Code。它会检查 Node.js 和编码工具，运行注册命令，把执行机装成后台服务，处理 PATH、代理和 npm 权限这些常见问题，最后告诉你还要亲自完成哪些登录或网络设置。
手动安装。 用准备运行 Agent 的系统用户，在这台机器上运行对话框里的命令，例如：
curl -fsSL https://studio.example.com/main/api/agents/dist/installScript | sh -s -- --runner --server https://studio.example.com/main --token <一次性凭证>命令从你的 Studio 下载执行机 nocobase-runner 和命令行 nb-studio，注册执行机，并设置为登录后自动启动。机器上已经装过 nocobase-runner 的，改用对话框里的 nocobase-runner register 命令注册。
Windows。 先在 PowerShell 里运行 wsl --install，重启 Windows；再打开 Ubuntu，运行 Linux 的命令。Node.js 和编码工具都装在 WSL 的 Ubuntu 里。WSL 访问不了外网时，开启 WSL 的镜像网络。
提示词和命令里带有一次性凭证，只能用一次，有效期在对话框里写明，通常只有几分钟。过期了就重新生成。提示词只交给这台机器上的编码工具，不要转发给别人。
确认接入成功
几秒钟后，运行环境出现在列表里，显示「在线」和它正在运行的工作数，例如「在线 0/3」，并列出勾选的每个编码工具的状态：
| 状态 | 意思 | 怎么办 |
|---|---|---|
| 已登录 | 可以接活 | 不用处理 |
| 需要登录 | 装了，但还没有登录 | 在这台机器上，用运行执行机的系统用户登录这个工具，再在详情里点「重新检测」 |
| 未安装 | 没有找到这个工具 | 安装它；已经装了还显示未安装，见下文常见问题 |
完成的标志运行环境显示在线，要用的编码工具显示「已登录」。这时「Agent 管理 › Agent」里会出现常用模型的 Agent，其余模型可以从「添加 Agent」添加，接着 启用 Agent。
管理运行环境
在列表里点一个运行环境，打开它的详情：
- 常规：名称、最大并发数、使用范围。
- 工具：每个编码工具是否启用、状态、额度和同时运行的上限。关闭的工具，工作不会派到这里。
- 本机策略：机器的主人在那台机器上限定它接哪些工作，Studio 里只能查看。
- 本机提供的变量：那台机器能提供给运行的变量，只显示名字，值留在机器上，用
nocobase-runner env set NAME设置。 - 工作目录和运行记录：这台机器上的任务目录，以及它执行过的运行。
执行机在没有 Agent 运行时会自动升级。要立即升级，在那台机器上运行 nocobase-runner update。
不再使用一台运行环境时，先吊销它的凭证：执行机在下一次请求时停止，它手上的工作退回队列。吊销后可以删除，历史运行记录会保留。要重新接入，再添加一次。
常见问题
运行环境显示离线。 执行机 150 秒没有联系 Studio，就显示离线，它手上的工作回到队列，由其他运行环境接手。在那台机器上运行 nocobase-runner status，确认执行机在运行，并且这台机器能访问 Studio 的地址。
工具已经装好，还是显示未安装。 后台服务的 PATH 里没有这个工具。在能运行 which claude 或 which codex 的终端里，重新运行 nocobase-runner service install，再重启服务。
下载执行机时失败。 需要代理时，为下载和后台服务都配置代理。npm 全局安装权限不足时，用当前用户自己的安装目录或 Node 版本管理器，不要用 sudo npm install。