Selig
4c966a3ad2
6 custom skills (assign-task, dispatch-webhook, daily-briefing, task-capture, qmd-brain, tts-voice) with technical documentation. Compatible with Claude Code, OpenClaw, Codex CLI, and OpenCode.
87 lines
9.7 KiB
JSON
Executable File
87 lines
9.7 KiB
JSON
Executable File
{
|
|
"title": "Exec tool",
|
|
"content": "Run shell commands in the workspace. Supports foreground + background execution via `process`.\nIf `process` is disallowed, `exec` runs synchronously and ignores `yieldMs`/`background`.\nBackground sessions are scoped per agent; `process` only sees sessions from the same agent.\n\n* `command` (required)\n* `workdir` (defaults to cwd)\n* `env` (key/value overrides)\n* `yieldMs` (default 10000): auto-background after delay\n* `background` (bool): background immediately\n* `timeout` (seconds, default 1800): kill on expiry\n* `pty` (bool): run in a pseudo-terminal when available (TTY-only CLIs, coding agents, terminal UIs)\n* `host` (`sandbox | gateway | node`): where to execute\n* `security` (`deny | allowlist | full`): enforcement mode for `gateway`/`node`\n* `ask` (`off | on-miss | always`): approval prompts for `gateway`/`node`\n* `node` (string): node id/name for `host=node`\n* `elevated` (bool): request elevated mode (gateway host); `security=full` is only forced when elevated resolves to `full`\n\n* `host` defaults to `sandbox`.\n* `elevated` is ignored when sandboxing is off (exec already runs on the host).\n* `gateway`/`node` approvals are controlled by `~/.openclaw/exec-approvals.json`.\n* `node` requires a paired node (companion app or headless node host).\n* If multiple nodes are available, set `exec.node` or `tools.exec.node` to select one.\n* On non-Windows hosts, exec uses `SHELL` when set; if `SHELL` is `fish`, it prefers `bash` (or `sh`)\n from `PATH` to avoid fish-incompatible scripts, then falls back to `SHELL` if neither exists.\n* Host execution (`gateway`/`node`) rejects `env.PATH` and loader overrides (`LD_*`/`DYLD_*`) to\n prevent binary hijacking or injected code.\n* Important: sandboxing is **off by default**. If sandboxing is off, `host=sandbox` runs directly on\n the gateway host (no container) and **does not require approvals**. To require approvals, run with\n `host=gateway` and configure exec approvals (or enable sandboxing).\n\n* `tools.exec.notifyOnExit` (default: true): when true, backgrounded exec sessions enqueue a system event and request a heartbeat on exit.\n* `tools.exec.approvalRunningNoticeMs` (default: 10000): emit a single “running” notice when an approval-gated exec runs longer than this (0 disables).\n* `tools.exec.host` (default: `sandbox`)\n* `tools.exec.security` (default: `deny` for sandbox, `allowlist` for gateway + node when unset)\n* `tools.exec.ask` (default: `on-miss`)\n* `tools.exec.node` (default: unset)\n* `tools.exec.pathPrepend`: list of directories to prepend to `PATH` for exec runs.\n* `tools.exec.safeBins`: stdin-only safe binaries that can run without explicit allowlist entries.\n\n* `host=gateway`: merges your login-shell `PATH` into the exec environment. `env.PATH` overrides are\n rejected for host execution. The daemon itself still runs with a minimal `PATH`:\n * macOS: `/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`, `/bin`\n * Linux: `/usr/local/bin`, `/usr/bin`, `/bin`\n* `host=sandbox`: runs `sh -lc` (login shell) inside the container, so `/etc/profile` may reset `PATH`.\n OpenClaw prepends `env.PATH` after profile sourcing via an internal env var (no shell interpolation);\n `tools.exec.pathPrepend` applies here too.\n* `host=node`: only non-blocked env overrides you pass are sent to the node. `env.PATH` overrides are\n rejected for host execution. Headless node hosts accept `PATH` only when it prepends the node host\n PATH (no replacement). macOS nodes drop `PATH` overrides entirely.\n\nPer-agent node binding (use the agent list index in config):\n\nControl UI: the Nodes tab includes a small “Exec node binding” panel for the same settings.\n\n## Session overrides (`/exec`)\n\nUse `/exec` to set **per-session** defaults for `host`, `security`, `ask`, and `node`.\nSend `/exec` with no arguments to show the current values.\n\n## Authorization model\n\n`/exec` is only honored for **authorized senders** (channel allowlists/pairing plus `commands.useAccessGroups`).\nIt updates **session state only** and does not write config. To hard-disable exec, deny it via tool\npolicy (`tools.deny: [\"exec\"]` or per-agent). Host approvals still apply unless you explicitly set\n`security=full` and `ask=off`.\n\n## Exec approvals (companion app / node host)\n\nSandboxed agents can require per-request approval before `exec` runs on the gateway or node host.\nSee [Exec approvals](/tools/exec-approvals) for the policy, allowlist, and UI flow.\n\nWhen approvals are required, the exec tool returns immediately with\n`status: \"approval-pending\"` and an approval id. Once approved (or denied / timed out),\nthe Gateway emits system events (`Exec finished` / `Exec denied`). If the command is still\nrunning after `tools.exec.approvalRunningNoticeMs`, a single `Exec running` notice is emitted.\n\n## Allowlist + safe bins\n\nAllowlist enforcement matches **resolved binary paths only** (no basename matches). When\n`security=allowlist`, shell commands are auto-allowed only if every pipeline segment is\nallowlisted or a safe bin. Chaining (`;`, `&&`, `||`) and redirections are rejected in\nallowlist mode.\n\nSend keys (tmux-style):\n\nSubmit (send CR only):\n\nPaste (bracketed by default):\n\n## apply\\_patch (experimental)\n\n`apply_patch` is a subtool of `exec` for structured multi-file edits.\nEnable it explicitly:\n\n* Only available for OpenAI/OpenAI Codex models.\n* Tool policy still applies; `allow: [\"exec\"]` implicitly allows `apply_patch`.\n* Config lives under `tools.exec.applyPatch`.",
|
|
"code_samples": [
|
|
{
|
|
"code": "### PATH handling\n\n* `host=gateway`: merges your login-shell `PATH` into the exec environment. `env.PATH` overrides are\n rejected for host execution. The daemon itself still runs with a minimal `PATH`:\n * macOS: `/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`, `/bin`\n * Linux: `/usr/local/bin`, `/usr/bin`, `/bin`\n* `host=sandbox`: runs `sh -lc` (login shell) inside the container, so `/etc/profile` may reset `PATH`.\n OpenClaw prepends `env.PATH` after profile sourcing via an internal env var (no shell interpolation);\n `tools.exec.pathPrepend` applies here too.\n* `host=node`: only non-blocked env overrides you pass are sent to the node. `env.PATH` overrides are\n rejected for host execution. Headless node hosts accept `PATH` only when it prepends the node host\n PATH (no replacement). macOS nodes drop `PATH` overrides entirely.\n\nPer-agent node binding (use the agent list index in config):",
|
|
"language": "unknown"
|
|
},
|
|
{
|
|
"code": "Control UI: the Nodes tab includes a small “Exec node binding” panel for the same settings.\n\n## Session overrides (`/exec`)\n\nUse `/exec` to set **per-session** defaults for `host`, `security`, `ask`, and `node`.\nSend `/exec` with no arguments to show the current values.\n\nExample:",
|
|
"language": "unknown"
|
|
},
|
|
{
|
|
"code": "## Authorization model\n\n`/exec` is only honored for **authorized senders** (channel allowlists/pairing plus `commands.useAccessGroups`).\nIt updates **session state only** and does not write config. To hard-disable exec, deny it via tool\npolicy (`tools.deny: [\"exec\"]` or per-agent). Host approvals still apply unless you explicitly set\n`security=full` and `ask=off`.\n\n## Exec approvals (companion app / node host)\n\nSandboxed agents can require per-request approval before `exec` runs on the gateway or node host.\nSee [Exec approvals](/tools/exec-approvals) for the policy, allowlist, and UI flow.\n\nWhen approvals are required, the exec tool returns immediately with\n`status: \"approval-pending\"` and an approval id. Once approved (or denied / timed out),\nthe Gateway emits system events (`Exec finished` / `Exec denied`). If the command is still\nrunning after `tools.exec.approvalRunningNoticeMs`, a single `Exec running` notice is emitted.\n\n## Allowlist + safe bins\n\nAllowlist enforcement matches **resolved binary paths only** (no basename matches). When\n`security=allowlist`, shell commands are auto-allowed only if every pipeline segment is\nallowlisted or a safe bin. Chaining (`;`, `&&`, `||`) and redirections are rejected in\nallowlist mode.\n\n## Examples\n\nForeground:",
|
|
"language": "unknown"
|
|
},
|
|
{
|
|
"code": "Background + poll:",
|
|
"language": "unknown"
|
|
},
|
|
{
|
|
"code": "Send keys (tmux-style):",
|
|
"language": "unknown"
|
|
},
|
|
{
|
|
"code": "Submit (send CR only):",
|
|
"language": "unknown"
|
|
},
|
|
{
|
|
"code": "Paste (bracketed by default):",
|
|
"language": "unknown"
|
|
},
|
|
{
|
|
"code": "## apply\\_patch (experimental)\n\n`apply_patch` is a subtool of `exec` for structured multi-file edits.\nEnable it explicitly:",
|
|
"language": "unknown"
|
|
}
|
|
],
|
|
"headings": [
|
|
{
|
|
"level": "h2",
|
|
"text": "Parameters",
|
|
"id": "parameters"
|
|
},
|
|
{
|
|
"level": "h2",
|
|
"text": "Config",
|
|
"id": "config"
|
|
},
|
|
{
|
|
"level": "h3",
|
|
"text": "PATH handling",
|
|
"id": "path-handling"
|
|
},
|
|
{
|
|
"level": "h2",
|
|
"text": "Session overrides (`/exec`)",
|
|
"id": "session-overrides-(`/exec`)"
|
|
},
|
|
{
|
|
"level": "h2",
|
|
"text": "Authorization model",
|
|
"id": "authorization-model"
|
|
},
|
|
{
|
|
"level": "h2",
|
|
"text": "Exec approvals (companion app / node host)",
|
|
"id": "exec-approvals-(companion-app-/-node-host)"
|
|
},
|
|
{
|
|
"level": "h2",
|
|
"text": "Allowlist + safe bins",
|
|
"id": "allowlist-+-safe-bins"
|
|
},
|
|
{
|
|
"level": "h2",
|
|
"text": "Examples",
|
|
"id": "examples"
|
|
},
|
|
{
|
|
"level": "h2",
|
|
"text": "apply\\_patch (experimental)",
|
|
"id": "apply\\_patch-(experimental)"
|
|
}
|
|
],
|
|
"url": "llms-txt#exec-tool",
|
|
"links": []
|
|
} |