Investigate Re-implementation of Auto-Migration via OpenClaw Native Secrets System

[KHAEntertainment]

Background

The original automated migration system (clawvault openclaw migrate --apply) was deprecated and disabled because OpenClaw did not support ${ENV_VAR} placeholders in auth-profiles.json. Running --apply would replace plaintext keys with placeholder strings that OpenClaw treated as literal credential values, causing complete authentication failure.

This issue tracks investigating whether OpenClaw's native secrets management system (added since v0.2.0) now enables a safe, working auto-migration path — potentially via the exec source type that ClawVault already implements.

---

What Was Previously Attempted

v0.0.x / v0.1.0 migration approach (deprecated)

The clawvault openclaw migrate --apply command:

1. Scanned all ~/.openclaw/agents/<agentId>/agent/auth-profiles.json files
2. Extracted plaintext API keys and OAuth tokens
3. Stored them in the ClawVault keyring
4. Rewrote auth-profiles.json with ${ENV_VAR} placeholder strings:

   {
     "profiles": {
       "openai:default": {
         "type": "api_key",
         "key": "\${OPENCLAW_OPENAI_OPENAI_DEFAULT_KEY}"
       }
     }
   }

5. Expected OpenClaw to expand those placeholders at runtime

Why it failed

• OpenClaw did not expand ${ENV_VAR} in auth-profiles.json — it treated the placeholder string as the literal credential value
• Authentication failed silently because OpenClaw sent the placeholder string instead of the actual key
• OAuth tokens were especially brittle — they could be partially validated/parsed before env expansion occurred, causing unpredictable failures
• Multi-agent setups had multiple auth-profiles.json files — a failed migration could break all of them at once

---

What's Changed: OpenClaw Native Secrets System

OpenClaw now has a built-in secrets management system that is directly relevant to this investigation:

openclaw secrets configure (interactive)

openclaw secrets configure --agent main

Interactive wizard that scans plaintext secrets, maps them to SecretRefs, and optionally applies with preflight validation.

openclaw secrets apply (plan executor)

openclaw secrets apply --from /tmp/plan.json --dry-run
openclaw secrets apply --from /tmp/plan.json

• Validates all target paths before writing
• One-way scrub: replaces plaintext with refs
• Requires agentId for all auth-profiles.json targets
• Supports auth-profiles.api_key.key target type

SecretRef source: "exec" (critical for ClawVault)

{
  "source": "exec",
  "provider": "vault",
  "id": "providers/openai/apiKey"
}

keyRef/tokenRef in auth-profiles.json

From secrets-plan-contract.md:

Ref-only auth-profiles.json entries (keyRef/tokenRef) are included in runtime resolution and audit coverage.

secrets.providers exec config in openclaw.json

{
  "secrets": {
    "providers": {
      "clawvault": {
        "source": "exec",
        "command": ["/absolute/path/to/clawvault", "resolve"],
        "jsonOnly": true,
        "passEnv": ["PATH"]
      }
    }
  }
}

This is exactly the integration path ClawVault v0.2.0's exec-provider was built for.

---

Investigation Tasks

• Verify auth-profiles.json supports keyRef/tokenRef fields (exact schema)
• Verify source: "exec" works for auth-profiles.json refs (test with a known key)
• Identify which OpenClaw version introduced these features
• Assess OAuth token handling — confirm tokenRef works end-to-end
• Verify ClawVault's clawvault resolve produces the exact JSON format required

---

Proposed Re-implementation Plan (conditional on investigation)

Phase 1: Generate OpenClaw-compatible plan files

Replace ${ENV_VAR} rewriting with plan file generation:

1. Run clawvault openclaw migrate --verbose as dry-run (existing)
2. Generate a plan.json compatible with openclaw secrets apply
3. Guide user to run openclaw secrets apply
4. ClawVault acts as the exec backend; OpenClaw handles the auth-profiles.json writes

Phase 2: clawvault openclaw setup command

Auto-configure secrets.providers.clawvault in openclaw.json so users don't have to edit it manually.

Phase 3: Deprecate old --apply path

Once Phase 1 is validated, mark clawvault openclaw migrate --apply as superseded by openclaw secrets configure + ClawVault exec provider workflow.

---

Priority

Medium — existing workaround works but is not migration-friendly for new users with existing plaintext auth-profiles.json setups.

[traycerai]

Warning

Insufficient credits. Please purchase more credits or upgrade your plan to continue using Traycer.

[KHAEntertainment]

Added notes from Deepwiki -

Potential to use CLI Commands to inject new provider/model configurations instead of directly editing config files.

Also note that the TUI gives end users the ability to switch a plaintext provider to ENV or Secrets Vault via Clawvault directly via the setup wizard.

---

Yes, you can add a new provider/model via the CLI without going through the entire setup wizard. OpenClaw provides several non-interactive approaches:

Non-interactive onboarding

Use openclaw onboard --non-interactive with custom provider flags:

openclaw onboard --non-interactive \
  --auth-choice custom-api-key \
  --custom-base-url "https://llm.example.com/v1" \
  --custom-model-id "foo-large" \
  --custom-api-key "$CUSTOM_API_KEY" \
  --secret-input-mode plaintext \
  --custom-compatibility openai
``` [1](#0-0) 

For Ollama:
```bash
openclaw onboard --non-interactive \
  --auth-choice ollama \
  --custom-base-url "http://ollama-host:11434" \
  --custom-model-id "qwen3.5:27b" \
  --accept-risk
``` [2](#0-1) 

## Direct model commands

Set models directly without onboarding:
```bash
openclaw models set <provider/model>
openclaw models list
openclaw models status
``` [3](#0-2) 

## Direct config editing

Edit configuration directly:
```bash
openclaw config set models.providers.custom-provider.baseUrl "https://api.example.com/v1"
openclaw config set models.providers.custom-provider.apiKey "your-key"
openclaw config set agents.defaults.model.primary "custom-provider/model-name"
``` [4](#0-3) 

## Provider authentication

For providers requiring OAuth or special auth:
```bash
openclaw models auth login --provider <provider-id>
openclaw models auth paste-token --provider anthropic
``` [5](#0-4) 

## Notes

- Custom providers support OpenAI-compatible and Anthropic-compatible endpoints
- Use `--secret-input-mode ref` to store API keys as environment references instead of plaintext
- Provider configuration is written to `models.json` under the agent directory
- Non-interactive mode requires all necessary flags or environment variables to be set [6](#0-5) 

Wiki pages you might want to explore:
- [Getting Started (openclaw/openclaw)](/wiki/openclaw/openclaw#1.1)
- [Glossary (openclaw/openclaw)](/wiki/openclaw/openclaw#10)

### Citations

**File:** docs/cli/onboard.md (L32-42)
```markdown
Non-interactive custom provider:

```bash
openclaw onboard --non-interactive \
  --auth-choice custom-api-key \
  --custom-base-url "https://llm.example.com/v1" \
  --custom-model-id "foo-large" \
  --custom-api-key "$CUSTOM_API_KEY" \
  --secret-input-mode plaintext \
  --custom-compatibility openai

**File:** docs/cli/onboard.md (L46-54)
```markdown
Non-interactive Ollama:

```bash
openclaw onboard --non-interactive \
  --auth-choice ollama \
  --custom-base-url "http://ollama-host:11434" \
  --custom-model-id "qwen3.5:27b" \
  --accept-risk

**File:** docs/concepts/models.md (L118-122)
```markdown
```bash
openclaw models list
openclaw models status
openclaw models set <provider/model>
openclaw models set-image <provider/model>

File: docs/cli/index.md (L394-399)

- `config get <path>`: print a config value (dot/bracket path).
- `config set <path> <value>`: set a value (JSON5 or raw string).
- `config unset <path>`: remove a value.
- `config file`: print the active config file path.
- `config validate`: validate the current config against the schema without starting the gateway.
- `config validate --json`: emit machine-readable JSON output.

File: src/commands/models/auth.ts (L345-355)

export async function modelsAuthLoginCommand(opts: LoginOptions, runtime: RuntimeEnv) {
  if (!process.stdin.isTTY) {
    throw new Error("models auth login requires an interactive TTY.");
  }

  const config = await loadValidConfigOrThrow();
  const defaultAgentId = resolveDefaultAgentId(config);
  const agentDir = resolveAgentDir(config, defaultAgentId);
  const workspaceDir =
    resolveAgentWorkspaceDir(config, defaultAgentId) ?? resolveDefaultAgentWorkspaceDir();
  const requestedProviderId = normalizeProviderId(String(opts.provider ?? ""));

File: docs/start/wizard-cli-reference.md (L190-204)

  <Accordion title="Custom provider">
    Works with OpenAI-compatible and Anthropic-compatible endpoints.

    Interactive onboarding supports the same API key storage choices as other provider API key flows:
    - **Paste API key now** (plaintext)
    - **Use secret reference** (env ref or configured provider ref, with preflight validation)

    Non-interactive flags:
    - `--auth-choice custom-api-key`
    - `--custom-base-url`
    - `--custom-model-id`
    - `--custom-api-key` (optional; falls back to `CUSTOM_API_KEY`)
    - `--custom-provider-id` (optional)
    - `--custom-compatibility <openai|anthropic>` (optional; default `openai`)