Start here: dotkc manual + best practices → dotkc.hczhang.com

dotkc OpenClaw Plugin (L2)

Typed OpenClaw tools for dotkc so agents can use secrets workflows through a constrained interface.

Goal: let OpenClaw use secrets without printing them (avoid secrets entering model transcripts).

Quick start

1) Install this plugin (dotkc is bundled):

# from npm (recommended)
openclaw plugins install dotkc-openclaw@0.1.4
openclaw gateway restart

# or local dev link
openclaw plugins install -l /path/to/dotkc-openclaw
openclaw gateway restart

2) Verify dotkc can decrypt on the OpenClaw host (dotkc is bundled, but still needs vault + key on disk):

dotkc status

3) Enable the plugin + opt-in tools:

{
  plugins: {
    entries: {
      dotkc: {
        enabled: true,
        config: {
          // dotkcBin: "dotkc", // optional override (default uses bundled dotkc)
          dotkcBin: "",
          specFile: "./dotkc.spec",
          allowUnsafe: false,
          commandAllowlist: ["node", "pnpm"]
        }
      }
    }
  },
  tools: { allow: ["dotkc"] }
}

Recommended install: openclaw plugins install dotkc-openclaw@0.1.4

What problem this solves

OpenClaw agents often need credentials (API keys, tokens) to run local tools. The unsafe default is to fetch a secret and print it, which can:

• land in the model transcript/context
• leak into logs or debugging output
• get pasted into chat accidentally

This plugin promotes the safer pattern:

1. Keep an allowlist file in the repo (dotkc.spec, no values)
2. Let dotkc resolve values at runtime
3. Prefer inspect redaction and env injection (values are not printed)

Tools exposed to the agent

dotkc_status (required)

Runs:

dotkc status --openclaw

Returns the OpenClaw JSON envelope from dotkc (paths + decrypt capability).

dotkc_doctor (optional)

Runs:

dotkc doctor --openclaw

Returns diagnostics and suggested fixes.

dotkc_inspect (optional)

Runs (default):

dotkc run --spec-file ./dotkc.spec --openclaw

Intended for redacted sanity checks.

dotkc_run (optional)

Runs a real command with secrets injected, but returns only safe summaries (tails) back to the model.

It spawns:

dotkc run --spec-file ./dotkc.spec -- <cmd> [args...]

Guardrails:

• No-leak is enforced by the plugin (it sets DOTKC_NO_LEAK=1 for dotkc subprocesses)
• Requires plugin config commandAllowlist[]
• Rejects unsafe specFile / cwd paths (relative only; no traversal)
• Fail-closed leak detection before returning any output

Important: by default this plugin does not enable unsafe/raw values.

How it works

• The plugin runs in-process with the OpenClaw Gateway.
• Each tool spawns dotkc as a subprocess and expects a single --openclaw JSON object on stdout.
• The tool surface is intentionally small (no “return raw secret values” API).

Security model / guardrails

• dotkc_inspect is designed for redacted output.
• The plugin also applies defensive redaction: it redacts obvious value-bearing fields (env, value, token, apiKey, etc.) unless you explicitly enable allowUnsafe.
• allowUnsafe is for debugging on a trusted machine only.
• Do not build agent workflows that call dotkc get (it prints raw values).

Threat model: if a secret is printed, it can enter model transcripts and/or be sent to the model provider. Design workflows so secrets are injected into child processes, not displayed.

No-leak default: this plugin enforces DOTKC_NO_LEAK=1 when spawning dotkc, so you do not need to set it in the Gateway environment.

Troubleshooting

“dotkc not found”

Set dotkcBin to an absolute path, or ensure dotkc is on PATH for the Gateway service.

“failed to parse dotkc –openclaw JSON”

Run the underlying command on the host:

dotkc status --openclaw

Ensure nothing else writes to stdout (no banners, no extra logs).

Vault/key problems

dotkc doctor --openclaw

Check:

• vault exists (synced ciphertext)
• key exists (local file)
• dotkc can decrypt

Links

• dotkc manual: dotkc.hczhang.com
• OpenClaw plugin docs: docs.openclaw.ai/tools/plugin
• OpenClaw agent tools guide: docs.openclaw.ai/plugins/agent-tools

Security hardening

This plugin is designed to be fail-closed.

• It applies defensive redaction (field-based).
• It also runs leak detection and will refuse to return tool output if it suspects plaintext secrets.

Roadmap

• Tests (golden JSON parsing + failure modes)
• Optional: publish to npm