<!-- source: https://deepwiki.com/openclaw/openclaw/7-security -->

# Security

- .agents/skills/crabbox/SKILL.md
- .agents/skills/openclaw-testing/SKILL.md
- .crabbox.yaml
- .github/actions/ensure-base-commit/action.yml
- .github/actions/setup-node-env/action.yml
- .github/actions/setup-pnpm-store-cache/action.yml
- .github/actions/setup-pnpm-store-cache/ensure-node.sh
- .github/workflows/ci-build-artifacts-testbox.yml
- .github/workflows/ci-check-testbox.yml
- .github/workflows/ci.yml
- .github/workflows/crabbox-hydrate.yml
- .github/workflows/openclaw-cross-os-release-checks-reusable.yml
- .github/workflows/windows-blacksmith-testbox.yml
- AGENTS.md
- CONTRIBUTING.md
- docs/ci.md
- docs/cli/update.md
- docs/gateway/security/index.md
- docs/gateway/security/shrinkwrap.md
- docs/install/development-channels.md
- docs/install/index.md
- docs/install/installer.md
- docs/install/updating.md
- docs/plugins/dependency-resolution.md
- docs/reference/full-release-validation.md
- docs/reference/release-performance-sweep.md
- extensions/acpx/package.json
- extensions/codex/package.json
- extensions/tlon/package.json
- qa/scenarios/memory/thread-memory-isolation.md
- scripts/AGENTS.md
- scripts/ci-run-timings.mjs
- scripts/crabbox-wrapper.mjs
- scripts/install-cli.sh
- scripts/install.ps1
- scripts/install.sh
- scripts/lib/ci-node-test-plan.mjs
- scripts/lib/docker-build.sh
- scripts/lib/plugin-npm-package-manifest.mjs
- src/agents/tools/image-tool.providers.live.test.ts
- src/cli/update-cli.test.ts
- src/cli/update-cli/update-command.ts
- src/infra/install-source-utils.test.ts
- src/infra/install-source-utils.ts
- src/infra/npm-install-env.test.ts
- src/infra/npm-install-env.ts
- src/infra/safe-package-install.test.ts
- src/infra/update-channels.test.ts
- src/infra/update-channels.ts
- src/infra/update-global.test.ts
- src/infra/update-global.ts
- src/infra/update-runner.test.ts
- src/infra/update-runner.ts
- src/scripts/test-live-media.test.ts
- test/plugin-npm-package-manifest.test.ts
- test/scripts/ci-node-test-plan.test.ts
- test/scripts/ci-run-timings.test.ts
- test/scripts/ci-workflow-guards.test.ts
- test/scripts/crabbox-wrapper.test.ts
- test/scripts/install-cli.test.ts
- test/scripts/install-ps1.test.ts
- test/scripts/install-sh.test.ts
- test/scripts/openclaw-cross-os-release-workflow.test.ts
- test/scripts/package-acceptance-workflow.test.ts
- test/scripts/setup-pnpm-store-cache-ensure-node.test.ts
- test/vitest/vitest.unit-support.config.ts

This page provides a high-level overview of OpenClaw's security model and implementation. It introduces the core trust assumptions underpinning OpenClaw's design, describes the defense-in-depth audit system, sandboxing mechanisms, and secret management approach.

## Trust Model and Scope

OpenClaw operates under a **personal assistant trust model**. This means a single trusted operator is expected per gateway instance. The key assumptions include:

- Trusted Host and Configuration : The OpenClaw host environment and its configuration files (e.g., openclaw.json ) must be controlled and trusted. Anyone able to modify this state is considered a trusted operator.
- Trusted Gateway Authentication : Callers authenticated to the Gateway API (via token, password, or device pairing) are trusted operators. OpenClaw supports multiple auth modes, including token and password .
- No Multi-Tenant Hostile Isolation : Running a single Gateway for multiple mutually untrusted or adversarial users is unsupported. If such isolation is required, separate Gateway instances must be used.
- Node Pairing Trust : Node commands and remote access are restricted until explicit node pairing is approved, moving beyond simple device-token possession.

The trust boundary centers on the personal assistant operator who controls the Gateway and its associated agents. OpenClaw uses `doctor` checks to ensure these boundaries are not inadvertently weakened by ambiguous configurations.

### Trust Boundary Concept

```

```

**Sources:**
[AGENTS.md4-5](https://github.com/openclaw/openclaw/blob/fbdf5937/AGENTS.md?plain=1#L4-L5); [src/cli/update-cli/update-command.ts27-28](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L27-L28); [src/cli/update-cli/update-command.ts109-110](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L109-L110)

## Security Audit System

OpenClaw features an automated security audit and health system integrated into the `doctor` command suite. This system performs comprehensive runtime environment checks to uncover security issues or misconfigurations [src/cli/update-cli/update-command.ts15-16](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L15-L16)

The audit system detects common risks such as:

- Unauthenticated Gateway Exposure : Checks if gateway authentication is ambiguous or unset src/cli/update-cli/update-command.ts 117-118
- Risky Tool Policies : Identifies when sensitive commands (like exec or /diagnostics ) lack proper owner restrictions src/cli/update-cli/update-command.ts 101-102
- Supply Chain Integrity : Validates that critical packages and bundled plugins haven't drifted from their expected manifests src/cli/update-cli/update-command.ts 118-119
- Dependency Guarding : Automated GitHub workflows enforce strict review requirements for dependency changes and lockfile integrity test/scripts/package-acceptance-workflow.test.ts 88-91

The `doctor` command provides auto-repair capabilities to correct permissions and tighten policy laxities automatically [src/cli/update-cli/update-command.ts15-16](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L15-L16)

### Architecture Diagram: Security Audit & Validation

```

```

For details, see [Security Audit System](/openclaw/openclaw/7.2-security-audit-system).

**Sources:**
[src/cli/update-cli/update-command.ts15-16](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L15-L16); [src/cli/update-cli/update-command.ts23-28](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L23-L28); [src/cli/update-cli/update-command.ts65-69](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L65-L69); [scripts/install.sh155-160](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/install.sh#L155-L160); [test/scripts/package-acceptance-workflow.test.ts5-13](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/package-acceptance-workflow.test.ts#L5-L13)

## Sandboxing & Isolation

OpenClaw employs layered sandboxing and isolation mechanisms to reduce risks from executing arbitrary tools and network requests:

- Docker Sandboxing : Tools can be executed inside Docker containers. Configuration logic ensures that only safe paths are accessible and that dangerous flags are validated.
- OpenShell/Crabbox Isolation : Supports remote validation and execution via the Crabbox wrapper, providing an isolated environment for broad tests and package validation .agents/skills/crabbox/SKILL.md 8-10
- Installer Hardening : The install.sh script uses non-interactive wrappers for system package managers to prevent terminal hijacking during setup test/scripts/install-sh.test.ts 116-123
- Execution Approvals : Sensitive operations, particularly those involving the shell or global updates, are gated by user confirmation src/cli/update-cli/update-command.ts 7
- Runtime Guards : Strict Node.js version checks and environment normalization prevent execution in unsupported or insecure runtimes src/cli/update-cli/update-command.ts 57

### Code Entity Space: Execution Protection Flow

```

```

For details, see [Sandboxing & Isolation](/openclaw/openclaw/7.3-sandboxing-and-isolation).

**Sources:**
[src/cli/update-cli/update-command.ts7](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L7-L7); [src/cli/update-cli/update-command.ts23-24](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L23-L24); [src/cli/update-cli/update-command.ts57](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L57-L57); [src/cli/update-cli/update-command.ts87](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L87-L87); [src/cli/update-cli/update-command.ts102](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L102-L102)

## Secret Management

OpenClaw integrates a unified system for credentials and secrets to minimize exposure:

- SecretRef System : Abstracts credential references using the SecretRef type. This allows configuration to point to environment variables or external providers without embedding plain-text secrets in openclaw.json .
- Environment Resolution : Secrets are resolved at runtime using environment variable substitution, keeping keys out of persistent configuration files src/cli/update-cli/update-command.ts 29
- Credential Safety : Standing orders for agents explicitly prohibit printing or leaking secrets during execution AGENTS.md 17
- Auth Profile Encryption : Provider-specific credentials (like OpenAI or Anthropic keys) are managed via auth profiles, which can be resolved through the SecretRef hierarchy.

For details, see [Secret Management](/openclaw/openclaw/7.4-secret-management).

**Sources:**
[AGENTS.md17](https://github.com/openclaw/openclaw/blob/fbdf5937/AGENTS.md?plain=1#L17-L17); [src/cli/update-cli/update-command.ts29](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L29-L29); [src/cli/update-cli/update-command.ts155-157](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L155-L157)

## Summary and Next Steps

OpenClaw's security is grounded in the **single trusted operator boundary**. Its defense-in-depth approach combines:

- Strict Configuration Validation : Ensuring the Gateway and Agents are not misconfigured via doctor src/cli/update-cli/update-command.ts 15-16
- Installer Safety : Using non-interactive shell patterns and checksum verification for bootstrapped binaries scripts/install.sh 100-108 ; scripts/install.sh 221-224
- Supply Chain Security : Auditing dependencies and build artifacts through automated CI gates test/scripts/package-acceptance-workflow.test.ts 88-91
- Isolated Validation : Leveraging Crabbox for remote, ephemeral execution environments .agents/skills/crabbox/SKILL.md 12-17

Continue your exploration with these detailed child pages:

- Security Model & Trust Boundaries - Detailed threat model and scope.
- Security Audit System - Documentation of the audit/doctor CLI and findings.
- Sandboxing & Isolation - Deep dive into Docker, Crabbox, and SSRF guards.
- Secret Management - Coverage of the SecretRef system and credential storage.

# Bridging Natural Language and Code: Trust Boundary to Core Code Entities

This diagram relates the natural language concepts of OpenClaw's trust model components to specific code entities implementing those components:

```

```

**Sources:**
[src/cli/update-cli/update-command.ts16-17](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L16-L17); [src/cli/update-cli/update-command.ts27-29](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/update-cli/update-command.ts#L27-L29); [scripts/install.sh2-5](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/install.sh#L2-L5); [scripts/crabbox-wrapper.mjs25-29](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/crabbox-wrapper.mjs#L25-L29); [.github/workflows/ci.yml39-44](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/ci.yml#L39-L44)
