🌐 当 Claude Code、脚本工具或编辑器插件需要连接 Claude 中转站时，最容易被忽略的并不是模型名称，而是环境变量。很多“密钥无效”“仍然连接旧地址”“终端能用但编辑器不能用”的问题，都来自变量作用域、加载顺序或配置文件权限。

环境变量的价值在于：把密钥和接口地址从代码中抽离出来。这样既能降低泄露风险，也能让同一份程序在开发、测试和生产环境中切换不同入口，而不必修改业务逻辑。

🧭 一、环境变量究竟解决什么问题

假设一个 Python 文件直接写入密钥：

client = Anthropic(
    api_key="sk-real-key",
    base_url="https://api.example.com"
)

这段代码虽然能运行，却会带来三个隐患：

1. 源码上传仓库时可能连同密钥一起提交；
2. 多个项目共用一份代码时难以切换账号；
3. 测试环境和生产环境容易互相覆盖。

改为环境变量后，程序只负责读取：

import os

api_key = os.getenv("ANTHROPIC_AUTH_TOKEN")
base_url = os.getenv("ANTHROPIC_BASE_URL")
model = os.getenv("ANTHROPIC_MODEL")

配置与程序职责由此分离。开发者可以在不改代码的情况下更换中转入口、模型版本和超时策略。

🔑 二、建议准备的变量清单

不同客户端支持的字段可能不同，但一个清晰的基础配置通常包含：

{
  "ANTHROPIC_AUTH_TOKEN": "用于鉴权的 API Key",
  "ANTHROPIC_BASE_URL": "Claude 中转站接口根地址",
  "ANTHROPIC_MODEL": "默认模型名称",
  "ANTHROPIC_TIMEOUT": "请求超时时间",
  "ANTHROPIC_MAX_TOKENS": "单次最大输出长度"
}

真正部署时不要把解释文字写进变量值。可以使用如下格式：

ANTHROPIC_AUTH_TOKEN=sk-****************
ANTHROPIC_BASE_URL=https://api.example.com
ANTHROPIC_MODEL=claude-model-name
ANTHROPIC_TIMEOUT=60
ANTHROPIC_MAX_TOKENS=4096

其中 BASE_URL 必须使用控制台提供的真实接口地址。不要把官网首页、登录页或充值页当成 API 地址，也不要自行重复拼接 /v1。

🪟 三、Windows PowerShell 临时配置

临时变量只对当前 PowerShell 窗口有效，适合先做连通性测试：

$env:ANTHROPIC_AUTH_TOKEN="your-api-key"
$env:ANTHROPIC_BASE_URL="https://api.example.com"
$env:ANTHROPIC_MODEL="claude-model-name"
$env:ANTHROPIC_TIMEOUT="60"

检查是否写入成功：

echo $env:ANTHROPIC_AUTH_TOKEN
echo $env:ANTHROPIC_BASE_URL
echo $env:ANTHROPIC_MODEL

为了避免在屏幕上暴露完整密钥，可以只检查长度：

$env:ANTHROPIC_AUTH_TOKEN.Length

关闭当前窗口后，这些值会自动消失。测试失败时，这种方式不会污染系统配置，适合排查 URL、模型或 Key 是否正确。

🧱 四、Windows 持久化设置

需要长期使用时，可以写入当前用户环境：

[Environment]::SetEnvironmentVariable(
  "ANTHROPIC_AUTH_TOKEN",
  "your-api-key",
  "User"
)

[Environment]::SetEnvironmentVariable(
  "ANTHROPIC_BASE_URL",
  "https://api.example.com",
  "User"
)

[Environment]::SetEnvironmentVariable(
  "ANTHROPIC_MODEL",
  "claude-model-name",
  "User"
)

写入后应关闭并重新打开终端。已经启动的 VS Code、JetBrains IDE 或其他桌面应用不会自动读取新变量，也需要重新启动。

需要删除旧变量时：

[Environment]::SetEnvironmentVariable(
  "ANTHROPIC_BASE_URL",
  $null,
  "User"
)

🐧 五、macOS 与 Linux 配置方法

当前终端临时生效：

export ANTHROPIC_AUTH_TOKEN="your-api-key"
export ANTHROPIC_BASE_URL="https://api.example.com"
export ANTHROPIC_MODEL="claude-model-name"
export ANTHROPIC_TIMEOUT="60"

验证：

echo "$ANTHROPIC_BASE_URL"
echo "$ANTHROPIC_MODEL"

长期使用时，应根据 Shell 类型写入配置文件。

Zsh：

nano ~/.zshrc

Bash：

nano ~/.bashrc

追加：

export ANTHROPIC_AUTH_TOKEN="your-api-key"
export ANTHROPIC_BASE_URL="https://api.example.com"
export ANTHROPIC_MODEL="claude-model-name"
export ANTHROPIC_TIMEOUT="60"

保存后重新加载：

source ~/.zshrc

或：

source ~/.bashrc

📁 六、使用 .env 文件进行项目隔离

如果一台电脑上存在多个项目，全部写入系统环境会造成冲突。更好的方式是每个项目维护自己的 .env：

ANTHROPIC_AUTH_TOKEN=sk-****************
ANTHROPIC_BASE_URL=https://api.example.com
ANTHROPIC_MODEL=claude-model-name
APP_ENV=development

项目结构可以设计为：

my-claude-project/
├── src/
├── config/
├── .env
├── .env.example
├── .gitignore
└── README.md

.gitignore 必须包含：

.env
.env.*
!.env.example

.env.example 只保留字段名，不保留真实值：

ANTHROPIC_AUTH_TOKEN=
ANTHROPIC_BASE_URL=
ANTHROPIC_MODEL=

这样团队成员知道需要配置哪些字段，却不会接触他人的真实密钥。

🛡️ 七、权限与密钥保护

Linux/macOS 下可以限制 .env 访问权限：

chmod 600 .env

此外建议：

• 开发、测试、生产使用不同 Key；
• 不在截图中展示完整 Token；
• 不把 Key 写进 JSON 示例或前端代码；
• 定期轮换密钥；
• 发现泄露后立即停用，而不是只修改文件。

🚀 八、在项目中自然接入中转服务

完成本地环境准备后，可以在 kingflow 控制台查看接口入口、模型列表和密钥管理信息，官网为：

https://www.kingflow.ai/

更稳妥的接入顺序是：

{
  "step_1": "创建测试用途 API Key",
  "step_2": "复制控制台实际 Base URL",
  "step_3": "确认支持的模型名称",
  "step_4": "写入临时环境变量",
  "step_5": "发送最小请求",
  "step_6": "验证成功后再持久化"
}

不要一开始就把正式密钥写进所有机器。先用测试 Key 验证权限、流式响应和用量记录，可以显著降低排错成本。

🧪 九、最小连接测试

Python 示例：

import os
from anthropic import Anthropic

required = [
    "ANTHROPIC_AUTH_TOKEN",
    "ANTHROPIC_BASE_URL",
    "ANTHROPIC_MODEL"
]

missing = [name for name in required if not os.getenv(name)]
if missing:
    raise RuntimeError(f"缺少环境变量: {', '.join(missing)}")

client = Anthropic(
    api_key=os.environ["ANTHROPIC_AUTH_TOKEN"],
    base_url=os.environ["ANTHROPIC_BASE_URL"],
    timeout=float(os.getenv("ANTHROPIC_TIMEOUT", "60"))
)

response = client.messages.create(
    model=os.environ["ANTHROPIC_MODEL"],
    max_tokens=128,
    messages=[
        {"role": "user", "content": "请仅回复：环境变量配置成功"}
    ]
)

print(response.content[0].text)

这段代码先检查变量是否存在，再发起请求。相比直接等待接口报错，它能更快定位“变量未加载”问题。

🧯 十、常见故障排查

终端可以调用，IDE 不可以

原因通常是 IDE 在变量写入前已经启动。完全退出 IDE 后重新打开。

修改了 .env，程序仍读取旧值

确认应用是否自动加载 .env。Python 常用 python-dotenv，Node.js 可使用 dotenv。某些工具不会自动读取项目文件。

Base URL 显示正确，但请求 404

检查客户端是否自动添加路径。配置已经包含 /v1 时，再次自动拼接可能形成 /v1/v1/messages。

新终端仍然没有变量

确认编辑的是当前 Shell 对应文件：

echo $SHELL

Zsh 和 Bash 的配置文件并不相同。

✅ 十一、发布前自检表

{
  "secret_not_in_source": true,
  "env_loaded": true,
  "base_url_verified": true,
  "model_verified": true,
  "ide_restarted": true,
  "test_request_passed": true,
  "gitignore_checked": true,
  "production_key_isolated": true
}

🎯 总结

配置 Claude 中转站环境变量的关键，不是记住几条命令，而是明确变量的作用域、加载位置和安全边界。临时变量适合测试，用户级变量适合个人长期使用，项目级 .env 更适合团队隔离。

把密钥、地址和模型参数从源代码中分离后，项目会更安全，也更容易迁移和排错。真正可靠的配置，应当能够被验证、被替换，也能够在密钥泄露或入口变更时快速恢复。