📌 《从零给 QQ 挂一个 AI 机器人》系列 · 第 2 篇（共 2 篇）

作者：AVA
环境：AstrBot 4.28.2 + NapCat（Docker 双容器）

⚠️ 提醒：这篇讲的是给机器人开权限，本质上是让大模型能执行命令、读写文件。第 5 节的安全边界请一定看完再动手，配置写错等于把服务器交出去。

上一回说到哪

第 1 篇里机器人已经能聊天了。但聊了两天就会发现一个问题：

它只会说话，不会干活。

我想要的场景很具体：扔一个链接给它，让它自己下载下来存着；需要的时候再让它把文件发回给我。也就是——给它一个工作区。

先别急着写插件

第一反应是「写个插件吧」。但去翻 AstrBot 文档会发现一件事：

从 v4.14 起，官方内置了「电脑能力」（computer use）。

开启之后，大模型会自动获得一整套工具 + 一个按会话隔离的工作区目录，下载、读写、跑脚本全都覆盖。根本不用自己写插件——自己写反而要处理沙箱、路径、权限这些麻烦事。

配置项就一个开关，三档：

档位	含义
none	关闭（默认值）
local	在当前容器里执行，工作区是容器内一个普通目录
sandbox	在独立沙箱里执行，隔离更强，但要多一份部署成本

我们选 local——够用，且不用额外折腾。

配置

改 data/cmd_config.json，或者直接走 WebUI（配置 → AI → 能力 → 使用电脑能力）：

"admins_id": ["<你的QQ号>"],

"provider_settings": {
  "computer_use_runtime": "local",
  "computer_use_require_admin": true     // ← 千万别关
}

⚠️ 版本差异是个大坑：网上能搜到的文章里常出现 computer_use_local_permissions / filesystem_scope 这两个键，在 4.28.2 上压根不存在（那是 4.29+ 才加的）。照抄会直接报配置错误。以你实际装的版本为准，别信博客。

另外注意 admins_id 里填的是裸 QQ 号字符串（["123456"] 这种），不用加前缀。

改完重启 AstrBot，日志里会出现：

[aiocqhttp.aiocqhttp_platform_adapter:107]: aiocqhttp(OneBot v11) 适配器已连接。

工作区长什么样

开启后会自动创建，路径规则是按会话隔离：

/AstrBot/data/workspaces/<会话ID>/

私聊会话的 ID 形如 default_FriendMessage_<QQ号>——每个私聊的人一份自己的目录，互不干扰。宿主机上对应 ./astrbot/data/workspaces/（走 data 那个挂载，天然持久化，容器重建也不丢）。

在 local 档下，模型拿到的工具是这些：

astrbot_execute_shell        astrbot_shell_session
astrbot_execute_python       astrbot_file_read_tool
astrbot_file_write_tool      astrbot_file_edit_tool
astrbot_grep_tool            send_message_to_user

⭐ 最大的坑：两个容器，看不见彼此的文件

配完之后「下载」是能用了——毕竟 astrbot_execute_shell 跑个 curl 就行。

但「发回给我」发不出去。

原因很反直觉：真正去读磁盘、把文件上传给 QQ 的执行者是 NapCat 容器，不是 AstrBot。而 NapCat 的容器里根本没有 /AstrBot/data 这个路径——那是 AstrBot 容器里的目录。文件在 AstrBot 眼里好好的，在 NapCat 眼里就是「不存在」。

报错通常是找不到文件之类的，很容易误判成「路径写错了」，然后在 AstrBot 里反复改路径——改到天亮也没用，因为错的是容器边界。

解法：给 NapCat 加一条最小挂载

  napcat:
    volumes:
      # ...原有的几行...
      - ./astrbot/data/workspaces:/AstrBot/data/workspaces   # ← 加这条

这样两边看到的是同一份真实文件，模型传过去的 /AstrBot/data/workspaces/... 就能被 NapCat 读到了。

⚠️ 务必只挂工作区这一个子目录。 别图省事把整个 ./astrbot/data 挂进 NapCat——那里面有 cmd_config.json，存着你的大模型 API key，还有各种凭据。挂进去等于把这些也一起暴露给了另一个容器，没有任何必要。

一个反直觉的事实：astrbot_download_file 不是下载器

工具列表里有个名字特别像「下载文件」的工具，很容易让人以为「直接让它调这个下载链接就行了」。

不是。 那个工具是 sandbox 档专用的，干的事是「把沙箱里的文件取回宿主机」，跟 URL 无关。

在 local 档下想让机器人下载一个链接，就是让模型自己用 shell 跑 curl（或者用 Python 的 requests）。别去找什么「下载工具」，没有。

实测过程

给机器人发一句：

帮我把 https://www.baidu.com/robots.txt 下载到工作区

日志里能看到它自己决定调工具：

[runners.tool_loop_agent_runner:1127]: Agent 使用工具: ['astrbot_execute_shell']
[runners.tool_loop_agent_runner:1183]: 使用工具：astrbot_execute_shell，
                                      参数：{'command': 'cd /AstrBot/data/workspaces/... && curl ...'}

然后在服务器上核实文件（⚠️ 这一步别省）：

ls -la /opt/qqbot/astrbot/data/workspaces/<会话ID>/
# -rw-r--r-- 1 root root 2814 robots.txt

接着发「把工作区里的 robots.txt 发给我」，日志里是：

Agent 使用工具: ['send_message_to_user']
参数：{'messages': [{'type': 'plain', 'text': '给你，...'},
                    {'type': 'file', 'path': '/AstrBot/data/workspaces/.../robots.txt'}]}
Tool `send_message_to_user` Result: Message sent to session ...

QQ 里收到文件，闭环。

顺手记一个教训

大模型报的路径不能信。

它会很自信地告诉你「文件搁在 /AstrBot/data/workspaces/xxx/robots.txt，2814 字节」——这个数字和路径有可能是编的。这次是核了两遍全对上了，但只要你在做这类工具调用，去服务器 ls / stat 一遍永远是最便宜的一步。

🔴 安全边界（必读）

开了这个能力，等于把服务器的一部分交给了大模型。几条必须知道：

① 只有管理员能用，别关那行配置

computer_use_require_admin: true 会拦掉所有非管理员——否则任何能私聊到你机器人的陌生人，都能在你服务器上跑命令。源码里的判定就是简单比对 admins_id，填的是裸 QQ 号。

② local 档没有路径限制

这是最需要注意的一条：在 4.28.2 上，local 档等于把整个容器文件系统敞开，没有「只能读写工作区」这种限制（4.29+ 才有 filesystem_scope）。也就是说，模型理论上能读到容器里的任意文件，包括 cmd_config.json——里面有你的大模型 API key。

目前它靠「只有你能触发」这一层兜着。但结论是：你自己的号 = 对机器人的最高权限，别在跟它的聊天里让它去翻配置文件。

③ 开了联网 + 执行，天然有 SSRF 面

框架层没有内网地址拦截，模型可以请求内网地址、甚至云厂商的元数据端点。同样靠「只有管理员能触发」兜着——所以第 ① 条是地基。

④ 下载没有体积上限

没有配额。云服务器磁盘通常不大，别让它拉大文件把盘塞满。

⑤ 触发方式两种，都是它自己决定

你发指令和它自己判断该调用工具，走的是同一条链路。也就是说——它什么时候去读文件、读哪个文件，是模型自己决定的，你只能通过「说什么」来影响它。

最后

这套东西配完之后，机器人从「会聊天的玩具」变成了「能干活的助手」。回过头看，最难的地方不是配置项，而是两个认识：

1. 先查官方有没有内置——省掉一个插件的工作量
2. 遇到「文件找不到」，先想容器边界——而不是反复改路径

补充 ①：（自己起个小标题）

🔲 留给你写：你原本想让机器人干什么活？第一句实际发过去的是什么？（写不出来整节删掉）

补充 ②：（自己起个小标题）

🔲 留给你写：看了安全边界那节，你的感受，或者你打算怎么收紧它。

---

📖 本系列共 2 篇 · 本篇完结

代码与环境基于 AstrBot 4.28.2 实测，有问题欢迎评论区交流。