Computer Use

Computer Use 让 AI 能够在你的电脑上执行命令和运行脚本。这是一个强大的功能，可以让 AI 帮你完成编译代码、运行测试、安装依赖等操作。

Computer Use 能做什么？

启用后，AI 可以：

• 💻 执行 Shell 命令 — 运行 git status、cargo build、npm install 等
• 🐍 运行 Python 脚本 — 执行 Python 代码进行数据处理或计算
• 🔧 自动化操作 — 帮你完成重复性的命令行操作

运行模式

Computer Use 提供三种运行模式，在安全性和灵活性之间给你选择：

模式	说明	适合场景
关闭	不启用 Computer Use	纯聊天场景
AIO 沙盒 ⭐	命令在 AIO Sandbox Docker 容器中运行，与宿主机完全隔离	✅ 日常使用推荐
本地模式	命令直接在你的系统上运行，权限等同于 Ruri 进程	需要完全系统访问时

AIO 沙盒模式（推荐）

AIO 沙盒模式通过 AIO Sandbox 服务在隔离的 Docker 容器中执行命令，提供最强的安全隔离：

• 🔒 命令在隔离的容器中执行，与宿主机完全隔离
• 📦 AI 可以使用沙盒专用工具：8 种工具覆盖 Shell 执行、文件读写编辑、目录浏览、文件查找和内容搜索（详见下方）
• 🌐 沙盒端点可配置，支持远程沙盒实例
• 🛡️ 宿主机文件系统和系统命令不可直接访问

如果选择 AIO 沙盒模式但未配置端点，Ruri 会回退到基本的本地文件工具并记录一条警告日志。

要使用 AIO 沙盒，你需要先部署 AIO Sandbox 服务，然后在 Ruri 中配置沙盒端点。

AIO 沙盒工具一览

AIO 沙盒模式提供了 8 个专用工具，让 AI 能够在隔离容器中完成丰富的文件操作和命令执行：

工具	标识	说明	参数
Shell	shell	在沙盒容器中执行 Shell 命令，支持可选超时	command（必填）— 要执行的命令；timeout（可选）— 超时秒数（默认 30）
读取文件	read_file	从沙盒中读取文件内容	path（必填）— 文件路径
写入文件	write_file	向沙盒中的文件写入内容	path（必填）— 文件路径；content（必填）— 写入内容
创建文件	create_file	创建新文件（文件已存在则失败；自动创建父目录）	path（必填）— 文件路径；content（必填）— 文件内容
编辑文件	edit_file	精确查找并替换文件中的文本（使用 old_text/new_text 进行精准编辑）	path（必填）— 文件路径；old_text（必填）— 要查找的文本；new_text（必填）— 替换后的文本
浏览目录	list_directory	列出目录内容，显示文件信息（大小、类型），默认路径 /home/gem	path（可选）— 目录路径（默认 /home/gem）
查找文件	find_files	按 glob 模式查找文件（如 **/*.py、src/**/*.rs）	path（必填）— 搜索目录；glob（必填）— 文件名匹配模式
搜索文件内容	search_in_file	使用正则表达式在文件中搜索，返回匹配内容及行号	path（必填）— 文件路径；regex（必填）— 正则表达式

各工具详细说明

Shell — 在沙盒的 Docker 容器中执行任意 Shell 命令。执行结果包含标准输出、退出码和执行状态。命令超时后仍可能有部分输出返回。Shell 会话通过 session_id 管理，可以保持会话上下文。

读取文件 — 读取沙盒中指定路径的文件内容，适合查看配置、脚本、日志等。

写入文件 — 将内容写入沙盒中指定路径的文件，会覆盖已有文件的内容。如果需要在已有文件不存在时创建文件，也可以使用此工具。

创建文件 — 在指定路径创建一个新文件并写入内容。与写入文件不同，如果文件已存在则会报错，避免意外覆盖。父目录不存在时会自动创建。

编辑文件 — 对文件进行精确的文本替换，需提供 old_text（要查找的文本）和 new_text（替换后的文本）。old_text 必须与文件中的内容完全匹配（包括空格和缩进）。如果未找到或找到多处匹配，则会报错。适合做精准的代码修改，而不是重写整个文件。

浏览目录 — 列出指定目录下的所有条目，展示文件/目录图标（📁/📄）、名称和文件大小，并在末尾汇总总条目数、目录数和文件数。如果不指定路径，默认浏览 /home/gem 目录。

查找文件 — 使用 glob 模式在指定目录下查找文件。支持标准 glob 语法，如 **/*.py（递归查找所有 Python 文件）、src/**/*.rs（仅在 src 目录下递归查找 Rust 文件）等。

搜索文件内容 — 在指定文件内使用正则表达式搜索，返回匹配的文本内容及对应的行号。适合在代码中查找特定函数、变量或模式。

重试与错误处理

AIO 沙盒客户端内置了自动重试机制，确保在沙盒服务暂时不可用时仍能可靠执行：

• 自动指数退避重试 — 当请求遇到临时服务器错误（HTTP 502 / 503 / 504）时，客户端会自动重试，最多重试 3 次
• 指数退避间隔 — 重试间隔按指数增长：第 1 次重试等待 1 秒，第 2 次等待 2 秒，第 3 次等待 4 秒
• 仅重试临时错误 — 客户端错误（4xx）和其他非临时错误不会触发重试，会立即返回错误
• 描述性错误消息 — 临时错误包含详细的提示信息，提醒检查沙盒容器是否运行以及端点是否可达

例如，当沙盒服务正在重启时，客户端会自动重试请求，无需人工干预。如果所有重试均失败，会返回包含诊断信息的错误消息，帮助定位问题。

警告

本地模式下 AI 拥有你系统上 Ruri 进程的全部权限。仅在受信任的环境中使用，建议优先使用 AIO 沙盒模式。

启用 Computer Use

通过 Web UI

1. 进入 设置 页面
2. 找到 Computer Use 部分
3. 开启功能
4. 选择运行模式：
   • 关闭 — 不启用 Computer Use
   • AIO 沙盒 — 隔离 Docker 容器（推荐）
   • 本地 — 完全系统访问
5. 如果选择了 AIO 沙盒，配置 沙盒端点（如 http://localhost:8080）
6. 设置工作区目录（AI 在此目录下操作）
7. 保存

提示

首次使用建议选择 AIO 沙盒模式，它能在大多数场景下满足需求，同时保护你的系统安全。

AIO 沙盒配置

AIO 沙盒通过 HTTP API 与远程沙盒服务通信，配置非常简单：

配置项	说明	默认值
端点	AIO Sandbox 服务 URL	http://localhost:8080

提示

你可以在同一台机器或远程服务器上部署 AIO Sandbox 服务。在团队环境中，共享沙盒实例可以让多个用户安全地运行命令，而不影响宿主机系统。

什么时候需要 Computer Use？

✅ 建议开启的场景

• "帮我运行一下项目的测试" — AI 可以执行测试命令并分析结果
• "安装这个项目的依赖" — AI 可以运行 npm install、pip install 等
• "帮我编译看看有没有错误" — AI 可以运行编译命令并解读错误信息
• "查看 git 仓库状态" — AI 可以运行 git 命令帮你管理代码
• "用 Python 处理一下这个数据" — AI 可以编写和运行 Python 脚本

❌ 不需要开启的场景

• 只是和 AI 聊天问答
• 只需要 AI 读写文件（文件工具默认可用）
• 只需要 AI 搜索代码（搜索工具默认可用）
• 在不信任的环境中使用 Ruri

工作区说明

工作区定义了 AI 操作的范围：

• 工作目录 — AI 执行命令的默认路径
• 允许的路径 — AI 可以访问的目录范围

通过合理设置工作区，你可以让 AI 只在你允许的目录下操作，提高安全性。

安全建议

1. 🛡️ 优先使用沙盒模式 — 对大多数任务来说已经足够
2. 📂 限制工作区范围 — 只给 AI 它需要的目录访问权限
3. 👀 留意 AI 的操作 — 聊天中会显示 AI 执行的所有命令，注意查看
4. 🚫 不确定就不开 — 如果你不需要 AI 执行命令，保持 Computer Use 关闭即可

信息

AI 每次执行命令时，你都可以在聊天界面中看到具体的命令内容。如果发现异常，可以使用 /stop 指令立即中断。