zh use computer

使用电脑能力

电脑能力（Computer Use）决定 Agent 是否可以在 AstrBot 运行环境中执行代码、访问文件、调用 Shell。

模式选择

在 WebUI 中进入：

• 配置 -> 普通配置 -> 使用电脑能力

核心配置项是 Computer Use Runtime：

• none：不启用电脑能力，不给 Agent 挂载 Shell、Python、文件系统等工具。
• local：在 AstrBot 所在机器上执行，适合需要访问本机文件、命令行工具或本地依赖的场景。
• sandbox：在隔离沙盒中执行，适合希望降低本机风险、或让多用户使用自动化能力的场景。

Local 模式

local 模式会把电脑能力挂载到 AstrBot 所在的主机环境。Agent 可以调用本机 Shell、本机 Python，以及本机文件系统工具。

这意味着 Agent 的能力边界接近 AstrBot 进程本身：它能访问什么，取决于 AstrBot 进程的系统权限、运行用户、工作目录和操作系统限制。

Workspace

在 local 模式下，AstrBot 会为每个会话准备一个 workspace：

data/workspaces/{normalized_umo}

其中 {normalized_umo} 来自当前会话的 unified_msg_origin，并会将不适合文件名的字符替换为 _。

本地文件工具的相对路径会解析到这个 workspace 下。例如：

notes/todo.txt

会被解析为：

data/workspaces/{normalized_umo}/notes/todo.txt

本地 Shell 工具执行时，也会把当前工作目录设置为这个 workspace。

Note

本地 Python 工具会调用 AstrBot 当前 Python 环境执行代码。编写会读写文件的 Python 代码时，建议使用明确的绝对路径，或先通过文件工具在 workspace 中准备文件。

本地工具

local 模式主要提供以下工具：

• Shell：执行本机 shell 命令。Windows 下使用 cmd.exe 语义，Linux/macOS 下使用类 Unix shell 语义。
• Python：使用 AstrBot 当前 Python 环境执行 Python 代码。
• 文件读取：读取 workspace 或允许路径中的文本、图片、表格等文件。
• 文件写入：写入 UTF-8 文本文件；相对路径默认落在当前 workspace。
• 文件编辑：按精确字符串替换文件内容。
• Grep 搜索：使用 ripgrep 能力搜索文件内容。

local 模式不会挂载沙盒上传/下载工具，也不会提供浏览器自动化工具。浏览器能力属于沙盒运行时，需要使用支持 browser capability 的沙盒 profile。

本地 Shell 内置了基础危险命令拦截，例如 rm -rf、sudo、shutdown、reboot、kill -9 等。但这不是完整安全沙箱，不能把它当作安全边界。

权限模型

电脑能力还有一个独立开关：

• 需要 AstrBot 管理员权限

默认情况下这个开关是开启的。

开启后：

• 管理员可以使用 local 模式下的 Shell、Python、文件读取、文件写入、文件编辑和 Grep 搜索。
• 非管理员不能使用 Shell 和 Python。
• 非管理员只能在受限目录内使用文件读取、写入、编辑和搜索。

非管理员在 local 模式下允许访问的目录包括：

• data/skills
• 当前会话的 data/workspaces/{normalized_umo}
• AstrBot 的临时目录
• 系统临时目录中的 .astrbot

关闭“需要 AstrBot 管理员权限”后，普通用户在电脑能力工具上的行为会接近管理员。除非你非常清楚风险，否则不建议关闭。

管理员 ID 可在：

• 配置 -> 其他配置 -> 管理员 ID

中配置。用户可通过 /sid 获取自己的 ID。

Sandbox 模式

sandbox 模式会把执行动作放到隔离环境中，而不是直接在 AstrBot 主机上运行。

在沙盒中，Agent 仍然可以使用 Shell、Python、文件系统工具；如果所选沙盒 profile 支持 browser capability，还会挂载浏览器自动化工具。

使用 Shipyard Neo 时，沙盒 workspace 根目录通常是：

/workspace

文件工具一般应传入相对路径，例如：

result.txt

而不是：

/workspace/result.txt

沙盒部署、profile、TTL、数据持久化、浏览器能力等内容请参考：Agent 沙盒环境。

Note

即使在 sandbox 模式下，“需要 AstrBot 管理员权限”仍会影响 Shell、Python、浏览器、上传下载等工具的调用权限。具体权限取决于你的配置。

Skills

Skills 是给 Agent 使用的“任务说明书”，通常存放在 data/skills 下，每个 Skill 都包含一个 SKILL.md。

电脑能力和 Skills 的关系可以理解为：

• Skills 告诉 Agent 应该怎么做。
• 电脑能力决定 Agent 能不能执行这些步骤。

例如，一个 Skill 可能要求 Agent 读取文件、运行脚本、生成报告。如果 Computer Use Runtime 是 none，Agent 可以看到 Skill 的说明，但无法真正调用 Shell 或 Python 完成执行。

在 local 模式下，Agent 会读取本地 Skills。 在 sandbox 模式下，AstrBot 会尝试把本地 Skills 同步到沙盒中，让 Agent 在沙盒内按 Skill 指令执行。

更多内容请参考：技能 Skills。