fix: hard guard for settings.json env conflicts#80
Merged
Conversation
Detect when settings.json's env field contains keys that would silently override ccc's provider env (Claude Code's settings.json env overrides the process env passed via syscall.Exec, empirically verified). Refuse to launch claude — and refuse to run validate — when such conflicts are present, instead of silently stripping the keys. A key is considered conflicting if it: - starts with ANTHROPIC_ or CLAUDE_, OR - collides with any key defined in base/provider env. The error message lists offending keys (without values, to avoid leaking secrets) and points the user at the fix: remove from settings.json's env and move provider configuration to ccc.json. ccc never modifies the user's settings.json — the user is the only one who can resolve the conflict. BREAKING CHANGE: previously, ANTHROPIC_*/CLAUDE_* keys and managed keys in settings.json env were silently filtered out when writing the merged settings. Now they cause a hard error and refuse to start claude until the user removes them.
Replace the previous 'silent strip' description in README/README-CN and docs/settings-merge-strategy.md with the new hard-guard behavior: ccc never modifies settings.json's env, and aborts with a clear error listing offending keys (no values) and the fix path. Also commit docs/discuss-20260519-env-priority.md — the empirical investigation log behind the decision (three controlled isolated-env tests verifying that Claude Code's settings.json env strictly overrides the process env passed via syscall.Exec).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
背景
实测验证（claude 2.1.144，隔离环境三组对照实验，详见 `docs/discuss-20260519-env-priority.md`）确认：
Claude Code 中 `~/.claude/settings.json` 的 `env` 字段严格覆盖 claude 进程继承的 OS 环境变量。
ccc 通过 `syscall.Exec` 把 provider env 作为进程环境变量传给 claude（`internal/cli/exec.go`），其优先级低于 settings.json 的 env。因此只要 settings.json 的 `env` 里残留 `ANTHROPIC_`/`CLAUDE_` 或与 provider/base 同名的 key，就会覆盖 ccc 传入的 provider 配置，导致切换 provider 静默失效。
当前 main（#76 `FilterUserEnvForSettings`）的做法是静默剥离这些 key 后继续运行——会丢失用户手动配置且无任何提示。
改动
ccc 不再尝试自动剥离/迁移/修改用户 settings.json。检测到冲突就直接报错并中止，无交互、无 y/N，交互与非交互行为一致。`ccc validate` 同样做检测。
冲突判据：
报错文本只列 key，不列 value（避免 AUTH_TOKEN 打到终端/CI 日志），并打印 settings.json / ccc.json 路径与修复指引。
文件
破坏性变化
原本"settings.json 有 `ANTHROPIC_*` → 静默剥离后照常启动"，现在变为"报错中止，要求用户先清理 settings.json"。
修复方法：从 `
/.claude/settings.json` 的 `env` 中删除冲突 key，并把 provider 相关配置改到 `/.claude/ccc.json` 的 `providers..env`。验证
不在本次范围