Token Safety Checker

Scan openclaw.json for plaintext secrets and migrate them to environment variables via SecretRef.
All operations run locally. Secret values are never passed as CLI arguments, never logged, and never appear in agent context.

Script

Single entry point: INLINECODE1

CODEBLOCK0

How secrets are protected

Risk	Mitigation
Secret values in `scan` output	INLINECODE3 returns paths + lengths only — never values
Secret values in CLI args

migrate reads values from disk internally — never via --values arg | | Secret values in dry-run output | Masked as export VAR="***" | | Secret values in agent context | findings JSON only contains path, env_var, length — safe to pass through SKILL | | Secret values in logs | No logging of values at any point |

Workflow

1. Scan

CODEBLOCK1

Output (safe to use in agent context — no secret values):
CODEBLOCK2

Exit 0 = clean → report and stop. Exit 1 = findings → continue. Exit 2 = config not found.

2. Show findings to user and confirm

Present the findings table (path | env_var | length). Allow renaming env vars. Do not proceed without explicit confirmation.

3. Dry-run

CODEBLOCK3

Show output to user. The script re-reads config from disk to verify findings are still current. Confirm before proceeding.

4. Migrate

CODEBLOCK4

The script:

1. Re-scans config from disk to confirm findings are still plaintext
Backs up openclaw.json → INLINECODE13
Reads secret values internally from disk (not from CLI args)
Appends env exports to shell profile (skips duplicates, masks values in output)
Replaces plaintext values with SecretRef in INLINECODE14

5. Source profile + restart gateway

⚠️ Check how the gateway is managed:

Shell-launched (most local setups):
CODEBLOCK5

systemd: Add vars to EnvironmentFile= in the unit — sourcing a shell profile won't work.

Docker: Pass via -e or environment: in compose.

6. Verify

CODEBLOCK6

7. Rollback

CODEBLOCK7

SecretRef format

CODEBLOCK8

INLINECODE18 is recommended for most setups. For higher-security environments, prefer file or exec.

Token 安全检查器

扫描 openclaw.json 中的明文密钥，并通过 SecretRef 将其迁移到环境变量中。
所有操作均在本地运行。密钥值不会作为 CLI 参数传递，不会被记录，也不会出现在代理上下文中。

脚本

单一入口点：scripts/safeclaw.py

python3 safeclaw.py scan [--config PATH]
python3 safeclaw.py migrate [--findings JSON] [--config PATH] [--profile PATH] [--dry-run] [--restore]

密钥保护方式

风险	缓解措施
scan 输出中的密钥值	scan 仅返回路径 + 长度 — 绝不返回实际值
CLI 参数中的密钥值

工作流程

1. 扫描

bash
python3 /scripts/safeclaw.py scan [--config ~/.openclaw/openclaw.json]

输出（可在代理上下文中安全使用 — 不含密钥值）：
json
{
findings: [
{ path: channels.discord.token, envvar: OPENCLAWDISCORD_TOKEN, length: 72 }
],
shell: { name: zsh, profile: ~/.zshrc, source_cmd: source ~/.zshrc }
}

退出码 0 = 干净 → 报告并停止。退出码 1 = 发现结果 → 继续。退出码 2 = 未找到配置文件。

2. 向用户展示发现结果并确认

展示发现结果表格（path | env_var | length）。允许重命名环境变量。未经明确确认不得继续。

3. 试运行

bash
python3 /scripts/safeclaw.py migrate \
--findings <步骤 1 中的发现结果 JSON> \
--dry-run

向用户展示输出。脚本会从磁盘重新读取配置以确认发现结果仍然有效。继续前需确认。

4. 迁移

bash
python3 /scripts/safeclaw.py migrate \
--findings <步骤 1 中的发现结果 JSON>

脚本将：

1. 重新扫描磁盘上的配置，确认发现结果仍为明文
备份 openclaw.json → openclaw.json.bak
从磁盘内部读取密钥值（而非从 CLI 参数）
追加环境变量导出到 shell 配置文件（跳过重复项，输出中掩码显示值）
替换 openclaw.json 中的明文值为 SecretRef

5. 加载配置文件 + 重启网关

⚠️ 检查网关的管理方式：

Shell 启动（大多数本地设置）：
bash
source
openclaw gateway restart

systemd： 在单元中将变量添加到 EnvironmentFile= — 加载 shell 配置文件无效。

Docker： 通过 -e 或 compose 中的 environment: 传递。

6. 验证

bash
python3 /scripts/safeclaw.py scan # 退出码 0 = 干净
openclaw gateway status

7. 回滚

bash
python3 /scripts/safeclaw.py migrate --restore

SecretRef 格式

json
{ source: env, provider: default, id: MYENVVAR }
{ source: file, provider: default, id: /path/to/secret.txt }
{ source: exec, provider: default, id: command --prints --secret }

对于大多数设置，推荐使用 env。对于更高安全性的环境，建议使用 file 或 exec。

token-safety-checker令牌安全检查