0-环境配置
环境配置
目录
1.1 登录与认证
安装 Claude Code 后终端运行 claude，首次启动开浏览器登录。浏览器够不到本地回调服务器（WSL2、SSH、容器常见）时，按 c 复制登录 URL，或把浏览器显示的 login code 粘贴回终端。
可认证的账户类型：
| 类型 | 说明 |
|---|---|
| Claude Pro / Max | claude.ai 订阅账户登录 |
| Teams / Enterprise | 团队管理员邀请的 claude.ai 账户；Enterprise 加 SSO、域捕获、RBAC、合规 API、managed policy |
| Claude Console | API 计费，Console 凭证登录（需先被邀请） |
| 云提供商 | Amazon Bedrock / Google Vertex AI / Microsoft Foundry，设环境变量即可，无需浏览器登录 |
/logout 登出并重新认证。
团队认证可选：Claude for Teams/Enterprise（推荐）、Console、Bedrock、Vertex、Foundry。
1.2 认证优先级
多份凭证同时存在时，Claude Code 按此顺序选一个（高 → 低）：
| 优先级 | 凭证 | 用途 |
|---|---|---|
| 1 | 云提供商凭证 | CLAUDE_CODE_USE_BEDROCK/_VERTEX/_FOUNDRY 任一设置时 |
| 2 | ANTHROPIC_AUTH_TOKEN | 作 Authorization: Bearer 头。用于 LLM 网关/代理（bearer 认证而非 Anthropic API key） |
| 3 | ANTHROPIC_API_KEY | 作 X-Api-Key 头。直接 Anthropic API 访问。交互模式问一次并记忆（/config 的「Use custom API key」切换）；非交互 -p 模式总用 |
| 4 | apiKeyHelper 脚本输出 | 动态/轮换凭证（如 vault 短期 token） |
| 5 | CLAUDE_CODE_OAUTH_TOKEN | claude setup-token 生成的长期 OAuth（CI 用） |
| 6 | /login 的订阅 OAuth | Pro/Max/Team/Enterprise 默认 |
坑： 有订阅但设了 ANTHROPIC_API_KEY，key 批准后优先，可能导致禁用/过期 org 认证失败。unset ANTHROPIC_API_KEY 回退订阅，/status 确认当前生效方式。
Claude Code on the Web 始终用订阅凭证；沙箱环境里 ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN 不覆盖它。
1.3 凭证管理
存储位置：
| 平台 | 位置 |
|---|---|
| macOS | 加密 Keychain |
| Linux | ~/.claude/.credentials.json（mode 0600） |
| Windows | %USERPROFILE%\.claude\.credentials.json（继承用户目录 ACL，默认限本账户） |
设 CLAUDE_CONFIG_DIR 时，.credentials.json 改到该目录下。由 /login、/logout 管理。
自定义 API 端点用 ANTHROPIC_BASE_URL（不写凭证文件）。
apiKeyHelper（动态凭证）：
- settings 中配置，指向返回 API key 的 shell 脚本。
- 默认调用时机：启动后 5 分钟，或收到 HTTP 401。
CLAUDE_CODE_API_KEY_HELPER_TTL_MS自定义刷新间隔。 - 返回超过 10 秒时，提示栏显示已耗时警告（脚本慢应优化）。
- 仅 terminal CLI 生效；Claude Desktop 和云会话用 OAuth，不调用
apiKeyHelper，也不读 API key 环境变量。
1.4 长期 Token（CI/脚本）
浏览器登录不可用的环境（CI、脚本），用 claude setup-token 生成一年期 OAuth token：
bash
claude setup-token # 走 OAuth 授权，打印 token 到终端（不存盘）
export CLAUDE_CODE_OAUTH_TOKEN=your-token
约束：
- 需 Pro/Max/Team/Enterprise 订阅。
- 仅限 inference，不能建立 Remote Control 会话。
--bare模式不读此 token——用ANTHROPIC_API_KEY或apiKeyHelper替代。
自 2026-06-15 起，订阅计划上的 Agent SDK 和
claude -p用量从新的月度 Agent SDK credit 扣除，与交互用量额度分开。