跳到主要内容

Exec

exec 是 MushroomAgent 最核心的运行时工具之一，用来在本地环境执行 shell 命令。它既可以同步返回结果，也可以把任务转成后台会话，再交给 process 管理。

功能说明​

  • 执行单次命令
  • 支持 workdir 和环境变量覆盖
  • 支持 timeout 和输出截断
  • 支持 background，长任务可立即转后台
  • 和 process 共用后台 session 模型

参数​

参数说明
command要执行的命令，必填
workdir工作目录，支持相对路径
envJSON 对象形式的环境变量覆盖
timeout超时秒数，默认取 tools.exec.default_timeout
max_output_chars最多返回多少字符
background设为 true 时立即转后台并返回 sessionId

执行模型​

  • 没有 shell 操作符时，运行时会直接把命令解析成 argv 执行。
  • 如果命令里包含管道、重定向、变量展开等 shell 语法，会退化为 /bin/sh -lc。
  • allowlist 默认按命令名或 basename 匹配。
  • privileged=false 时，命令不在白名单里会直接返回 capability_limited。

配置​

tools:
  exec:
    enabled: true
    cwd: /absolute/path/to/workspace
    cwd_root: /absolute/path/to/workspace
    allowlist:
      - curl
      - python3
      - ls
      - rg
      - cat
      - pwd
    privileged: false
    default_timeout: 1800
    max_output_chars: 200000

mushroom-agent init 生成的模板里，exec 默认就是启用的，而且会带上一组基础 allowlist。

示例​

前台执行：

{ "tool": "exec", "command": "rg TODO ." }

后台执行：

{ "tool": "exec", "command": "npm run dev", "background": true }

相关​