Claude Code 环境怎么配：安装命令、代理与密钥放哪

终端里的编码助手 Claude Code：装哪条、密钥放哪、代理怎么接，全部给可复制命令。先统一说一次归属规则——下文凡标「推算」「经验判断」的句子是本文的推断，其余命令、变量名、报错原文都能在文末列出的官方页面里逐字找到。截至 2026-11-01 抓取官方页面时，官方仓库 README 已把 npm 安装标注为 deprecated（弃用），同时仓库挂着 154.1k star、25.5k fork；旧教程里那句 npm install -g @anthropic-ai/claude-code 已经不是官方推荐路径，这就是现在重看环境配置的理由。

三件事确认完再动手

1. 先能分辨 PowerShell 和 CMD：在 Windows 提示符里看有没有 PS 前缀——官方说法是 PowerShell 里显示 PS C:，CMD 里显示 C:。这一步决定你后面抄哪条命令，抄错会直接报错。
2. 有一条账号路径：官方 overview 写明多数运行面需要 Claude 订阅或 Anthropic Console 账号，而终端 CLI、VS Code、JetBrains 还支持第三方 provider。没订阅可以走 Console 的 API key，也可以走网关（下一节）。
3. Windows 用户装 Git for Windows：官方说明装了它 Claude Code 才会用 Bash 工具，没装就退到 PowerShell 当 shell 工具；WSL 不需要。确认方式：git --version 能打印版本号。

Node 不在这三条里。这是推算：官方 overview 与仓库 README 给出的全部安装命令中，没有一条把 Node 列为前置，只有那条已弃用的 npm 路径才和 Node 有关联——如果你机器上没有 Node，现在照本文装没有任何影响。

四条安装路径怎么选（还有一条已弃用）

官方推荐原生安装（native install），安装脚本本身不显示进度，下载完成后再开新窗口验证。四条受支持路径与一条已弃用路径的差别集中在「谁适合」和「会不会自动更新」上：

# macOS / Linux / WSL（官方推荐）
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

# Homebrew（两个 cask 二选一）
brew install --cask claude-code
brew install --cask claude-code@latest

# WinGet
winget install Anthropic.ClaudeCode

装完新开一个终端窗口，运行 claude --version。官方写明：安装程序结束后打印出版本号即为可用。之后进入项目目录启动：

cd your-project
claude

首跑会提示登录；如果你已经设了 ANTHROPIC_API_KEY 并在询问时同意使用，会跳过登录提示。经验判断：CI 里优先用原生脚本而不是 brew/winget，因为原生安装会后台自动更新，后两者不会，长时间跑的流水线容易停在旧版本上；反过来，需要锁版本的场景应该选 brew 的稳定 cask。IDE 那条路走扩展：扩展视图（macOS Cmd+Shift+X、Windows/Linux Ctrl+Shift+X）搜索 “Claude Code”，装完在命令面板（Cmd+Shift+P / Ctrl+Shift+P）输入 “Claude Code” 并选择 Open in New Tab。

密钥放哪：三种放置方式

「放哪」取决于你走哪条计费路径。官方认证文档列出的凭据类型包括 claude.ai 凭据、Claude API 凭据、Microsoft Foundry、Bedrock、Vertex、Anthropic profile 凭据与 Workload Identity Federation（工作负载身份联邦，即让云上的临时身份代替静态密钥）、以及 Claude Apps 网关会话 token。对应的三种放置方式：

1. 交互登录：首跑时按提示登录。官方说明 Claude Code 通过 /login 与 /logout 管理 .credentials.json，也就是登录态落在凭据文件里，不用手写密钥。
2. 环境变量：设 ANTHROPIC_API_KEY 后首跑会询问是否使用该 key，同意即跳过登录。适合临时会话和脚本。
3. apiKeyHelper 设置项：让 Claude Code 去跑一个 shell 脚本、拿脚本输出当 API key。官方提醒：如果脚本超过 10 秒才返回，提示条会显示耗时告警——密钥轮换用它，但脚本要快。

# macOS / Linux / WSL
export ANTHROPIC_API_KEY="sk-ant-..."
export CLAUDE_CONFIG_DIR="$HOME/.claude-team"
claude

# Windows PowerShell（只对当前窗口有效）
$env:ANTHROPIC_API_KEY = "sk-ant-..."
claude

CLAUDE_CONFIG_DIR 不是密钥本身，而是决定凭据文件放哪：设了它，.credentials.json 就留在该目录，macOS Keychain（钥匙串）条目也按该目录区分，因此两个不同 CLAUDE_CONFIG_DIR 的会话读到的是两套凭据。apiKeyHelper 是 Claude Code 的设置项，写在 .claude 目录下的设置文件里，目录结构见官方的 .claude 目录文档。经验判断：不要把 key 塞进项目里的 .env 再提交——项目级环境文件最容易被 git 带走，而上面三种方式都不会进仓库。

代理与网关怎么接

自建网关或中转时只动两个变量：ANTHROPIC_BASE_URL 决定请求发往哪个自定义端点，ANTHROPIC_AUTH_TOKEN 负责网关侧鉴权。官方网关文档给的 GitHub Actions 写法：

env:
  ANTHROPIC_BASE_URL: https://llm-gateway.example.com
  ANTHROPIC_AUTH_TOKEN: ${{ secrets.GATEWAY_API_KEY }}

steps:
  - uses: anthropics/claude-code-action@v1

本机终端把这两行换成本机写法即可（export 或 $env:）。网关侧有一个容易踩的口径：网关校验的是放进 Authorization 头的凭据，请求里 x-api-key 的那份副本会被忽略——所以网关文档要求把 key 同时以 ANTHROPIC_AUTH_TOKEN 的形式传过去。如果你用 Claude Code 只是走公共网络，这一节可以跳过；但只要碰上自建端点，就不要再同时改 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 之后猜哪个生效，按上表分工改一个就够。

国内网络下最常见的不是变量配错，而是安装这一步就拿不到脚本：官方把 403 和 syntax error near unexpected token '<' 并列写进安装故障处理入口。经验判断：后一种报错几乎总是因为管道拿到的是 HTML 错误页而不是安装脚本，bash 解析到 < 就炸。解法按官方路径来——回 overview 安装段落打开 Troubleshoot installation 对号入座，或直接换上表里的另一条安装路径（WinGet / Homebrew / apt）。

Node 与 Python：SDK 环境变量行为差在哪

如果你的环境配置发生在 Agent SDK（官方提供的编程接口，用代码启动 Claude Code 进程）里，Node 与 Python 两个 SDK 对同一段网关变量的处理方式不一样，这是最容易丢配置的一处：

// TypeScript：漏写 ...process.env，网关变量就全丢了
const result = query({
  prompt: "...",
  options: {
    env: {
      ...process.env,
      ANTHROPIC_BASE_URL: "https://llm-gateway.example.com",
    },
  },
});

# Python：合并语义，父进程变量会被带过去
options = ClaudeAgentOptions(
    env={"ANTHROPIC_AUTH_TOKEN": os.environ["GATEWAY_KEY"]}
)

同样的网关配置，Node 侧少写一行展开就整段失效，而 Python 侧看起来「少写却能跑」——两边的报错形态还完全不同，所以配完务必各自跑一次真实请求确认，别只看进程起来了。

四条真实报错与怎么确认配成了

以下四条报错原文都出自官方 overview 的安装段落：

1. claude: command not found 或 claude is not recognized —— 官方解释是安装目录还没进 PATH。第一步永远是开一个新终端窗口再跑 claude --version；仍找不到就按官方的 Fix your PATH 入口处理。
2. The token '&&' is not a valid statement separator —— 你在 PowerShell，不是 CMD。改用 PowerShell 那条 irm ... | iex。
3. 'irm' is not recognized as an internal or external command —— 你在 CMD，不是 PowerShell。改用 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd。
4. syntax error near unexpected token '<' 或 403 —— 走安装故障处理入口对号入座，或直接换另一条安装路径。

配成了的标志有三个，都能直接观察到：claude --version 打印出版本号；claude 首跑出现登录提示，或在你设了 ANTHROPIC_API_KEY 时询问是否使用该 key；如果配了 apiKeyHelper 且脚本超过 10 秒，提示条出现耗时告警（这说明 helper 被调用了，只是太慢）。

官方入口与文档索引

一个对用 Agent 找配置项特别有用的小入口：官方 overview 页写明可以抓取 /docs/llms.txt 拿到完整文档索引，先把这个文件喂给你的助手再问「某配置项在哪一页」，比逐页翻快得多。

• Claude Code 官方 overview（安装、运行面、登录）
• 官方仓库 anthropics/claude-code（README 的安装口径与弃用声明）
• 认证文档（凭据类型、CLAUDE_CONFIG_DIR、apiKeyHelper）
• LLM 网关接入文档（BASE_URL / AUTH_TOKEN 与两个 SDK 的 env 行为）
• 配置云环境（中文，云端会话的环境变量与网络访问级别）
• 文档索引 llms.txt 与 Changelog

参考来源

• Claude Code를 LLM 게이트웨이에 연결 – Claude Code Docs – anthropic_api_key 입력과 워크플로우 env 블록의 ANTHRO
• Autenticazione – Claude Code Docs – – Consentire un gateway LLM o proxy: elencate”customEn