Free Claude Code 免费配置迁移指南：一次看懂 schema-1 env 文件原子迁移

Free Claude Code 免费配置迁移指南一次看懂 schema-1 env 文件原子迁移【免费下载链接】free-claude-codeUse Claude Code, Codex, Pi, and OpenCode and more for free (1.3B free tokens) from your terminal, app, IDE, or phone like OpenClaw (voice supported ToS friendly)项目地址: https://gitcode.com/GitHub_Trending/fr/free-claude-codeFree Claude Code免费 Claude Code 使用方案让你免费在终端、App、IDE 或手机上调用 Claude Code、Codex、OpenCode 等 AI 编程工具累计 1.3B 免费 tokens。随着版本迭代早期散落在多个目录的环境变量配置需要统一收敛。本文详解它的schema-1 env 文件原子迁移机制如何把旧配置一次性、安全地合并进唯一的托管文件~/.fcc/.env做到幂等、原子、多进程安全全程无需手动操作。一、为什么需要「一次性」配置迁移 早期版本里Free Claude Code 的配置可能分散在好几个地方而且变量命名也在不断演进。这带来三个痛点来源分散老用户可能在~/.free-claude-code/.env、~/.config/free-claude-code/.env甚至代码仓库根目录放过了.env。命名过期像HF_TOKEN、ENABLE_MODEL_THINKING、OPENCODE_PROXY这类旧变量名已被新名取代。怕写坏配置里存着 API Key一旦迁移中途崩溃不能留下「半截文件」。为此项目引入了托管 env 文件schema 版本标记原子写入的组合拳让迁移只发生一次、且绝不破坏旧数据。核心逻辑集中在 env_migrations.py对外暴露的主入口是consolidate_managed_config。二、迁移的三个来源路径迁移第一步是找到基准配置文件。优先级如下托管文件优先若~/.fcc/.env已存在直接以它为基准说明大概率已迁移过。旧目录回退否则按顺序探测 paths.py 里的旧路径~/.free-claude-code/.env~/.config/free-claude-code/.env仓库根目录的.env仅当校验确认是 Free Claude Code 代码库时才采纳见 env_files.py显式覆盖额外读取环境变量FCC_ENV_FILE指向的文件叠加其中的「已知」变量。 关键原则已存在托管文件时不再合并旧目录避免用过期值覆盖你手动改过的配置。迁移只吸收「被识别」的变量recognized_env_keys()无关的键例如UNRELATED_SECRET会被直接忽略旧文件本身也保持原样、绝不被改动。三、schema-1 标记迁移只发生一次幂等托管文件头部会写入一个版本标记FCC_CONFIG_SCHEMA1这个1就是schema-1。它的判断逻辑非常讲究写在consolidate_managed_config场景行为标记 1已是最新直接跳过返回changedFalse不重写标记为空 / 无标记执行一次迁移并写入1标记 99旧文件里偷写的不信任按未迁移处理标记是更高版本如2fail closed抛出unsupported schema拒绝运行「只信任托管文件里的 schema 标记、且遇到更新版本就拒绝」的设计保证了迁移天然幂等——重复执行不会产生任何字节变化。对应测试见 test_env_migrations.py 的「byte_for_byte 幂等」与「newer schema fails closed」。四、原子写入临时文件 os.replace写坏也不怕 ️这是「原子迁移」真正落地的一环实现在atomic_write_managed_config先用render_managed_config把配置渲染成规范文本含# Managed by Free Claude Code.头注释、schema 标记、按字母排序的变量。写入临时文件.env.pid.tmp并flushfsync落盘。在 POSIX 下chmod 0o600仅属主可读写保护 API Key。用os.replace(tmp, target)原子替换目标文件——要么完整替换、要么完全没变不存在中间态。finally中清理残留临时文件。一旦替换失败如磁盘错误原文件原封不动测试test_atomic_replace_failure_preserves_original专门验证了这一点。渲染后的文件长这样示意结构# Managed by Free Claude Code. # Edit settings in /admin when possible. FCC_CONFIG_SCHEMA1 # Configured settings MODEL... # Preserved unrecognized settings CUSTOM...未识别的自定义变量会被保留在Preserved unrecognized settings区块避免误删用户手写内容。五、跨进程锁多开终端也不会写花配置 如果同时打开好几个终端谁负责迁移答案是——加锁。resolve_settings_snapshot在调用迁移前会先通过InterprocessFileLock抢占~/.fcc/config.lock超时 10 秒迁移完成后立即释放。测试test_concurrent_loaders_produce_one_valid_managed_file用 8 个线程并发触发加载最终断言只生成一份合法文件且目录下没有任何*.tmp残留。这就保证了「多进程安全」。六、到底迁移了哪些变量所有变量级迁移规则集中在ENV_MIGRATIONS元组覆盖三类场景env_migrations.py旧变量新变量值转换HF_TOKENHUGGINGFACE_API_KEY原样ENABLE_MODEL_THINKINGREASONING_POLICYtrue→clientfalse→offENABLE_FABLE/OPUS/SONNET/HAIKU_THINKINGREASONING_FABLE等空→inherittrue→clientfalse→offOPENCODE_PROXYOPENCODE_ZEN_PROXY原样FCC_SMOKE_MODEL_OPENCODEFCC_SMOKE_MODEL_OPENCODE_ZEN前缀opencode/→opencode_zen/MODEL/MODEL_FABLE等同名模型引用前缀opencode/→opencode_zen/两个细节值得一提新旧同存时新值胜出例如同时有HF_TOKEN和HUGGINGFACE_API_KEY保留新变量、丢弃旧变量测试。一次性物化鉴权开关迁移会按 token 是否存在推导并写入PROXY_AUTH_ENABLEDtrue/false但进程环境变量里临时设置的开关不会被持久化test_process_auth_flag_is_not_persisted。七、迁移完成后去哪里看/admin 管理页 托管文件~/.fcc/.env不必手改——项目提供内置的/admin 管理页可视化查看与编辑各 Provider 的配置状态。注意页面底部会显示~/.fcc/.env路径正是迁移产出的那份文件。管理页的写回同样走原子写入见 admin/persistence.py 的target_values_with_updates每次都会重新打上FCC_CONFIG_SCHEMA1标记。八、常见疑问 FAQQ迁移会动我的旧.env吗A不会。旧文件只读、绝不修改只把「已知变量」拷贝进托管文件。Q我已经手动改过~/.fcc/.env升级会覆盖吗A不会。只要文件里已有FCC_CONFIG_SCHEMA1迁移直接跳过没有 schema 标记才会做一次性收敛且收敛时以托管文件本身为基准不再吞并旧目录。Q为什么 API Key 更安全了A托管文件强制chmod 0o600仅属主可读写并在原子写入前落盘、失败时保留原文件杜绝半截文件泄露或损坏密钥。Q遇到更高版本 schema 会怎样Afail closed——直接报错拒绝运行提示当前版本只支持1避免用旧版本误写新格式。小结Free Claude Code 的 env 迁移 schema-1 标记幂等 原子写入不写坏 跨进程锁多开安全 变量级规则无感升级。你只需升级配置会安静、安全地归位到~/.fcc/.env。【免费下载链接】free-claude-codeUse Claude Code, Codex, Pi, and OpenCode and more for free (1.3B free tokens) from your terminal, app, IDE, or phone like OpenClaw (voice supported ToS friendly)项目地址: https://gitcode.com/GitHub_Trending/fr/free-claude-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考