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 dotkc and make sure it can decrypt on the OpenClaw host:

dotkc status

2) Install this plugin (local dev link):

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

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

3) Enable the plugin + opt-in tools:

{
  plugins: {
    entries: {
      dotkc: {
        enabled: true,
        config: {
          dotkcBin: "dotkc",
          specFile: "./dotkc.spec",
          allowUnsafe: false
        }
      }
    }
  },
  tools: { allow: ["dotkc"] }
}

Recommended install: openclaw plugins install dotkc-openclaw@0.1.0

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.

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.

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

Roadmap

• Stronger leakage detection: fail closed if plaintext-looking env lines appear
• Safe execution tool: run only via spec allowlist + command allowlist (return only exit code + stderr summary)
• Tests (golden JSON parsing + failure modes)
• Optional: publish to npm