Skip to main content

Secure development

This guide covers the practices contributors follow while writing code. For reporting a vulnerability, the trust model and operator hardening, see the Security section of the docs site.

Secrets and placeholders

  • Never commit real phone numbers, API tokens, videos, or live config values. Use obviously fake placeholders.
  • Docs content must be generic. Do not include personal device names, hostnames, or paths. Use placeholders such as user@gateway-host.
  • Read the security policy before any security triage or advisory work.

Local credential files

  • Web provider credentials live in ~/.openclaw/credentials/. Rerun wednesdayai login if you are logged out.
  • Agent sessions live in the SQL session database, ~/.openclaw/sessions.db by default (plus backups/ and the legacy import archive under the state directory).
Never copy these into the repository, a fixture, or a log entry.

Security scanning

The primary gate is a blocking pre-push gitleaks scan. git push runs git-hooks/pre-push, which scans every commit that is not yet on any remote with scripts/pre-push/secrets-scan.sh (config in .gitleaks.toml, shared with the weekly backstop below; it disables the entropy-only generic-api-key rule to keep the blocking gate on provider-specific rules). Leaks block the push; for a confirmed false positive, add its Fingerprint to .gitleaksignore. Install gitleaks with brew install gitleaks (or a release binary); without it the push goes ahead with a warning. OPENCLAW_SKIP_PREPUSH=1 skips the pre-push hook for WIP pushes. See the Local hooks section of Testing policy. As a backstop for skipped hooks (--no-verify, OPENCLAW_SKIP_PREPUSH=1), the Deterministic Security workflow runs a weekly full-repo gitleaks and Semgrep scan (Tuesday 04:17 UTC, plus on-demand workflow_dispatch). As an optional extra check you can still run detect-secrets locally; it is no longer run by any active automation. The baseline is .secrets.baseline (configuration in .detect-secrets.cfg):

Dependency policy

  • Dependencies listed in pnpm-workspace.yaml patchedDependencies must use exact versions (no ^ or ~). Patching a dependency requires explicit approval.
  • pnpm applies those patches only to pnpm installs. For npm-installed gateways, src/infra/dependency-patches.ts applies the same patch files in memory when each module loads. A new patch therefore also needs:
    • a DEPENDENCY_PATCHES entry, which src/infra/dependency-patches.test.ts checks against pnpm-workspace.yaml;
    • an installed-tree scenario in INSTALLED_PATCH_SCENARIOS, which scripts/release-installed-package/installed-patches.e2e.test.ts runs against an npm install -g of the packed tarball.
    See ADR 2085.
  • @sinclair/typebox is pinned to an exact version as well.
  • Never update the Carbon dependency (@buape/carbon).
  • Never use npm link or pnpm link for local installs. Build with npm pack and install the tarball globally.
  • pnpm audit --prod --audit-level=high must pass. Fix a high or critical advisory by bumping the direct dependency first, then with a scoped override in pnpm-workspace.yaml overrides (scoped by major or parent). Waive it in auditConfig.ignoreGhsas only when no fix exists or the fix is blocked. Every waiver needs an entry in ADR 0249 with reachability evidence and an exit issue.
  • npm installs (npm install -g wednesdayai, and the npm install that wednesdayai plugins install runs for a managed plugin) never see the pnpm-workspace.yaml overrides. A cross-range override therefore also needs an npm path: a managed plugin mirrors it in its own package.json overrides (scripts/check-plugin-npm-overrides.test.ts keeps the values equal), and a root dependency needs a runtime fix or an npm-install waiver in ADR 0249. Prove it against the packed tarball with pnpm build && pnpm exec vitest run --config vitest.e2e.config.ts scripts/release-installed-package/npm-cross-range-overrides.e2e.test.ts.