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/. Rerunwednesdayai loginif you are logged out. - Agent sessions live in the SQL session database,
~/.openclaw/sessions.dbby default (plusbackups/and the legacy import archive under the state directory).
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.yamlpatchedDependenciesmust 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.tsapplies the same patch files in memory when each module loads. A new patch therefore also needs:- a
DEPENDENCY_PATCHESentry, whichsrc/infra/dependency-patches.test.tschecks againstpnpm-workspace.yaml; - an installed-tree scenario in
INSTALLED_PATCH_SCENARIOS, whichscripts/release-installed-package/installed-patches.e2e.test.tsruns against annpm install -gof the packed tarball.
- a
-
@sinclair/typeboxis pinned to an exact version as well. -
Never update the Carbon dependency (
@buape/carbon). -
Never use
npm linkorpnpm linkfor local installs. Build withnpm packand install the tarball globally. -
pnpm audit --prod --audit-level=highmust pass. Fix a high or critical advisory by bumping the direct dependency first, then with a scoped override inpnpm-workspace.yamloverrides(scoped by major or parent). Waive it inauditConfig.ignoreGhsasonly 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 thatwednesdayai plugins installruns for a managed plugin) never see thepnpm-workspace.yamloverrides. A cross-range override therefore also needs an npm path: a managed plugin mirrors it in its ownpackage.jsonoverrides(scripts/check-plugin-npm-overrides.test.tskeeps 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 withpnpm build && pnpm exec vitest run --config vitest.e2e.config.ts scripts/release-installed-package/npm-cross-range-overrides.e2e.test.ts.