skill-template/references/CONFIG.md

配置标准：.env 规范与首次落盘机制

解决"每个 skill 每次都要手动搞一堆环境变量、账号、地址"的痛点。统一约定：模板内置 .env.example，skill 首次运行自动落盘到用户数据目录，之后从那里读。

核心原则

1. .env.example 进仓库：带注释的全量默认配置，是配置项的"单一事实来源"。
2. 首次运行自动 copy：setup / doctor / 首次 run 时，把 .env.example 复制到 {CLAW_DATA_ROOT}/{user}/{slug}/.env（已存在则不覆盖，保护用户改过的值）。
3. 三级优先级读取：进程环境变量 > 数据目录/.env > .env.example 默认值。
4. 敏感信息绝不进 .env：密码/密钥/口令走 account-manager 的 secret-ref（见下"红线"）。

标准配置项

每个 skill 的 .env.example 至少包含这些（按需增减）：

# ── 运行模式（对应 adapter 四档，见 ADAPTER.md）──
OPENCLAW_TEST_TARGET=simulator_rpa     # mock | simulator_rpa | real_api | real_rpa

# ── 目标系统 ──
TARGET_BASE_URL=https://sandbox.jc2009.com   # 仿真/生产地址，可被进程环境变量覆盖

# ── 默认账号（仅非敏感标识；密码走 account-manager）──
DEFAULT_LOGIN_ID=04110001

# ── 浏览器 / RPA ──
OPENCLAW_BROWSER_HEADLESS=0            # 0=有头(默认) 1=无头(CI)
OPENCLAW_PLAYWRIGHT_STEALTH=1          # 1=开启反检测指纹(默认)

# ── 存证 ──
OPENCLAW_RECORD_VIDEO=1                # 1=录屏+字幕+背景音+MP4成片（RPA技能默认开，见 RPA.md）
OPENCLAW_ARTIFACTS_ON_FAILURE=1        # 1=失败截图(默认)

# ── 节流 / 超时 ──
STEP_DELAY_MIN=1.0                     # 步骤间随机等待下限(秒)
STEP_DELAY_MAX=5.0                     # 步骤间随机等待上限(秒)
HUMAN_WAIT_TIMEOUT=180                 # 滑块/验证码/2FA 等人工超时(秒)

🚫 红线：敏感信息不进 .env

.env 只放非敏感运行参数（模式、地址、开关、超时）。密码、密钥、动态口令、token——

• 走 account-manager 注册凭据，用 --secret-storage env --secret-ref XXX 引用；
• 真实值由宿主/用户通过环境变量注入，不落任何文件、不进 git。
• 参考 disburse-payroll-icbc/scripts/cli/cmd_setup.py：账号写入 account-manager，密码只登记 secret-ref（如 ICBC_SIM_PASSWORD）。

.gitignore 必须包含：

.env
*.env.local

配置读取层（模板提供）

模板会提供一个统一 config.py，约定行为：

config.get("TARGET_BASE_URL")              # 三级优先级解析
config.get_bool("OPENCLAW_BROWSER_HEADLESS")
config.get_float("STEP_DELAY_MIN", 1.0)
config.ensure_env_file()                   # 首次把 .env.example copy 到数据目录

• 启动时调一次 ensure_env_file() 完成落盘。
• 所有业务代码只通过 config.get* 读配置，不直接 os.environ，便于统一管理与测试覆盖。

引用方式

实现位于 jiangchang-platform-kit 的 jiangchang_skill_core.config；模板 vendor 拷贝在 scripts/jiangchang_skill_core/config.py：

from jiangchang_skill_core import config
from util.constants import SKILL_SLUG
from util.runtime_paths import get_skill_root
import os

example = os.path.join(get_skill_root(), ".env.example")
config.ensure_env_file(SKILL_SLUG, example)

headless = config.get_bool("OPENCLAW_BROWSER_HEADLESS")
target = config.get("TARGET_BASE_URL")
timeout = config.get_int("HUMAN_WAIT_TIMEOUT", 180)

doctor / setup 命令

每个 skill 应提供自检命令（参考 disburse 的 test_doctor）：

• python scripts/main.py doctor：检查浏览器是否安装、Profile/账号是否就绪、.env 是否已落盘、设备(手机)是否连接。
• python scripts/main.py setup：初始化演示账号、首次落盘 .env。

相关文档

• RPA.md — 三端 RPA 标准与各开关含义
• ADAPTER.md — OPENCLAW_TEST_TARGET 四档模式
• RUNTIME.md — CLAW_* 环境变量与数据目录约定