跳转到主要内容

​
Exec 工具

Run shell commands in the workspace. Supports foreground + background execution via process. If process is disallowed, exec runs synchronously and ignores yieldMs/background. Background sessions are scoped per agent; process only sees sessions from the same agent.

​
参数

  • command（必填）
  • workdir（默认为当前工作目录）
  • env（键值对覆盖）
  • yieldMs（默认 10000）：延迟后自动转入后台
  • background（布尔值）：立即转入后台
  • timeout（秒，默认 1800）：超时后终止
  • pty（布尔值）：在可用时使用伪终端运行（仅限 TTY 的 CLI、编程智能体、终端 UI）
  • host（sandbox | gateway | node）：执行位置
  • security（deny | allowlist | full）：gateway/node 的执行策略
  • ask（off | on-miss | always）：gateway/node 的审批提示
  • node（字符串）：host=node 时的节点 id/名称
  • elevated（布尔值）：请求提升模式（gateway 主机）；仅当 elevated 解析为 full 时才强制 security=full
注意事项：
  • host 默认为 sandbox。
  • 当沙箱隔离关闭时，elevated 会被忽略（exec 已在主机上运行）。
  • gateway/node 审批由 ~/.openclaw/exec-approvals.json 控制。
  • node 需要已配对的节点（配套应用或无头节点主机）。
  • 如果有多个可用节点，设置 exec.node 或 tools.exec.node 来选择一个。
  • 在非 Windows 主机上，exec 会使用已设置的 SHELL；如果 SHELL 是 fish，它会优先从 PATH 中选择 bash（或 sh）以避免 fish 不兼容的脚本，如果两者都不存在则回退到 SHELL。
  • 主机执行（gateway/node）会拒绝 env.PATH 和加载器覆盖（LD_*/DYLD_*），以防止二进制劫持或代码注入。
  • Important: sandboxing is off by default. 重要提示：沙箱隔离默认关闭。如果沙箱隔离关闭，host=sandbox 将直接在 Gateway 网关主机上运行（无容器）且不需要审批。如需审批，请使用 host=gateway 运行并配置 exec 审批（或启用沙箱隔离）。 To require approvals, run with host=gateway and configure exec approvals (or enable sandboxing).

​
配置

  • tools.exec.notifyOnExit（默认：true）：为 true 时，后台 exec 会话在退出时会入队系统事件并请求心跳。
  • tools.exec.approvalRunningNoticeMs（默认：10000）：当需要审批的 exec 运行时间超过此值时发出单次”运行中”通知（0 表示禁用）。
  • tools.exec.host（默认：sandbox）
  • tools.exec.security（默认：sandbox 为 deny，gateway + node 未设置时为 allowlist）
  • tools.exec.ask（默认：on-miss）
  • tools.exec.node（默认：未设置）
  • tools.exec.pathPrepend：exec 运行时添加到 PATH 前面的目录列表。
  • tools.exec.safeBins：仅限 stdin 的安全二进制文件，无需显式白名单条目即可运行。
示例： 
{
  tools: {
    exec: {
      pathPrepend: ["~/bin", "/opt/oss/bin"],
    },
  },
}

​
PATH 处理

  • host=gateway：将你的登录 shell PATH 合并到 exec 环境中。主机执行时会拒绝 env.PATH 覆盖。守护进程本身仍使用最小 PATH 运行： env.PATH overrides are rejected for host execution. The daemon itself still runs with a minimal PATH:
    • macOS：/opt/homebrew/bin、/usr/local/bin、/usr/bin、/bin
    • Linux：/usr/local/bin、/usr/bin、/bin
  • host=sandbox：在容器内运行 sh -lc（登录 shell），因此 /etc/profile 可能会重置 PATH。OpenClaw 在 profile 加载后通过内部环境变量将 env.PATH 添加到前面（无 shell 插值）；tools.exec.pathPrepend 在此也适用。 OpenClaw prepends env.PATH after profile sourcing via an internal env var (no shell interpolation); tools.exec.pathPrepend applies here too.
  • host=node：只有你传递的未被阻止的 env 覆盖会发送到节点。主机执行时会拒绝 env.PATH 覆盖。无头节点主机仅在 PATH 添加到节点主机 PATH 前面时才接受（不允许替换）。macOS 节点完全丢弃 PATH 覆盖。 env.PATH 覆盖设置在主机执行时会被拒绝，在 node 主机中会被忽略。 如果你在某个 node 上需要额外的 PATH 条目， 请配置 node 主机服务环境（systemd/launchd），或将工具安装到标准位置。
Per-agent node binding (use the agent list index in config): 
openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
控制 UI：Nodes 标签页包含一个小的”Exec 节点绑定”面板用于相同的设置。

​
会话覆盖（/exec）

使用 /exec 为 host、security、ask 和 node 设置每会话默认值。 不带参数发送 /exec 可显示当前值。 Send /exec with no arguments to show the current values. 示例： 
/exec host=gateway security=allowlist ask=on-miss node=mac-1

​
授权模型

/exec is only honored for authorized senders (channel allowlists/pairing plus commands.useAccessGroups). It updates session state only and does not write config. To hard-disable exec, deny it via tool policy (tools.deny: ["exec"] or per-agent). Host approvals still apply unless you explicitly set security=full and ask=off.

​
Exec 审批（配套应用/节点主机）

Sandboxed agents can require per-request approval before exec runs on the gateway or node host. See Exec approvals for the policy, allowlist, and UI flow. When approvals are required, the exec tool returns immediately with status: "approval-pending" and an approval id. Once approved (or denied / timed out), the Gateway emits system events (Exec finished / Exec denied). 当需要审批时，exec 工具会立即返回 status: "approval-pending" 和审批 id。一旦被批准（或拒绝/超时），Gateway 网关会发出系统事件（Exec finished / Exec denied）。如果命令在 tools.exec.approvalRunningNoticeMs 之后仍在运行，会发出单次 Exec running 通知。

​
白名单 + 安全二进制文件

Allowlist enforcement matches resolved binary paths only (no basename matches). When security=allowlist, shell commands are auto-allowed only if every pipeline segment is allowlisted or a safe bin. 在 allowlist 模式下，链式命令（;、&&、||）和重定向将被拒绝， 除非每个顶层片段都满足 allowlist 要求（包括 safe bins）。 重定向仍不受支持。

​
示例

前台： 
{ "tool": "exec", "command": "ls -la" }
后台 + 轮询： 
{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}
发送按键（tmux 风格）： 
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Enter"]}
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["C-c"]}
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Up","Up","Enter"]}
提交（仅发送 CR）： 
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
粘贴（默认带括号）： 
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

​
apply_patch（实验性）

apply_patch 是 exec 的子工具，用于结构化多文件编辑。 需显式启用： Enable it explicitly: 
{
  tools: {
    exec: {
      applyPatch: { enabled: true, allowModels: ["gpt-5.2"] },
    },
  },
}
注意事项：
  • 仅适用于 OpenAI/OpenAI Codex 模型。
  • 工具策略仍然适用；allow: ["exec"] 隐式允许 apply_patch。
  • 配置位于 tools.exec.applyPatch 下。
  • tools.exec.applyPatch.workspaceOnly 默认值为 true（仅限 workspace 内）。 仅当你有意让 apply_patch 在 workspace 目录之外进行写入/删除操作时，才将其设置为 false。