Claude Code

Claude Code 是 Anthropic 推出的终端编程工具。通过配置 API 地址、API Key 和模型 ID，可以让 Claude Code 使用 AGTCloud 的 Anthropic Messages 兼容入口。

本教程只介绍 Claude Code CLI。不同模型对工具调用、扩展思考和实验功能的支持范围可能不同，请选择当前 API Key 可见且支持 Anthropic Messages 的模型。

准备工作

开始前，请确认你已经：

准备好终端环境和 Git；
注册并登录 AGTCloud；
在 API Keys 页面创建令牌；
从模型广场找到当前令牌可用的 Anthropic 协议模型 ID。

安装 Claude Code

选择与你的操作系统对应的安装方式。原生安装脚本会自动更新；Homebrew 和 WinGet 安装需要通过各自的包管理器手动更新。

curl -fsSL https://claude.ai/install.sh | bash

安装完成后，重新打开终端并检查版本：

claude --version
claude doctor

claude doctor 会检查安装状态和配置文件。如果终端提示找不到 claude，请重新打开终端，并确认安装目录已经加入 PATH。

配置 AGTCloud

Claude Code 会向 ANTHROPIC_BASE_URL 指定的地址发送请求。这里只填写 AGTCloud API Origin，不要在末尾追加 /v1，因为 Claude Code 会自行请求 /v1/messages。

临时配置

以下配置只在当前终端会话中生效。请将 your-api-key 和 MODEL_ID 替换为自己的令牌和模型 ID。

unset ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_BASE_URL="https://api.agtcloud.cn"
export ANTHROPIC_API_KEY="your-api-key"
export ANTHROPIC_MODEL="MODEL_ID"

环境变量	作用
`ANTHROPIC_BASE_URL`	将 Claude Code 请求指向本页显示的 AGTCloud API 地址
`ANTHROPIC_API_KEY`	通过 `X-Api-Key` Header 发送 AGTCloud API Key
`ANTHROPIC_MODEL`	指定本次会话默认使用的模型 ID

清除冲突的认证变量

如果系统中已经配置 ANTHROPIC_AUTH_TOKEN，Claude Code 会将其作为 Bearer Token 使用，可能覆盖 ANTHROPIC_API_KEY。使用本教程配置前，请先清除该变量。

持久配置

希望每次打开终端都自动生效时，可以把相同配置写入 shell 配置文件或 Windows 用户环境变量。API Key 会以明文形式保存在本机，请只在个人受信设备上使用这种方式。

编辑 ~/.zshrc 并加入：

export ANTHROPIC_BASE_URL="https://api.agtcloud.cn"
export ANTHROPIC_API_KEY="your-api-key"
export ANTHROPIC_MODEL="MODEL_ID"

保存后加载配置：

source ~/.zshrc

cd /path/to/your/project

启动 Claude Code

claude

如果首次启动提示是否使用环境变量中的 API Key，请按终端提示确认。

检查当前配置

在 Claude Code 中执行：

/status

确认认证来源为 API Key，并检查 Base URL 是否为本页显示的 AGTCloud API 地址。Base URL 不应包含重复的 /v1。

发起只读测试

在包含 README.md 的测试项目中输入：

请读取 README.md，并用三点概括这个项目的用途。不要修改任何文件。

能够正常返回内容，且 AGTCloud 控制台中出现对应调用记录，说明基础连接已经建立。

完成配置检查后，可以发送一个简单问题，确认模型能够正常响应。

常见问题

现象	优先检查	处理方式
找不到 `claude` 命令	安装结果和 `PATH`	重新打开终端，运行 `claude doctor`，必要时重新执行官方安装命令
启动后仍要求登录	API Key 是否在启动 Claude Code 的同一终端中生效	检查 `ANTHROPIC_API_KEY`，重新打开终端后再次启动
API Key 没有生效	是否同时设置了 `ANTHROPIC_AUTH_TOKEN`	清除冲突变量，通过 `/status` 核对认证来源
返回 `401`	API Key、环境变量和令牌状态	重新复制有效 API Key，并通过 `/status` 确认认证来源
返回 `403`	令牌权限、模型权限和账户状态	在控制台检查令牌及模型可用范围
返回 `404`	Base URL 和模型 ID	Base URL 只填写 `https://api.agtcloud.cn`，不要追加 `/v1`；重新复制模型 ID
找不到或无法使用模型	当前 API Key 可见模型和协议支持	选择支持 Anthropic Messages 的模型，并通过 `ANTHROPIC_MODEL` 指定完整 ID
部分工具或高级功能不可用	模型能力和网关兼容情况	先使用基础对话验证；高级能力以所选模型和当前适配结果为准

遇到无法定位的问题时，请记录请求时间、模型 ID、HTTP 状态和脱敏错误信息，然后查看错误与排障。不要提交完整 API Key。

安全建议

为 Claude Code 单独创建 API Key，便于管理权限和停用凭证。
不要把真实 Key 写入代码、仓库、截图、日志或共享脚本。
在共享设备或团队环境中，优先使用操作系统凭证管理或组织统一的密钥分发方案。
API Key 疑似泄露时，应立即在控制台禁用或删除，并创建新的 Key。

下一步可以继续阅读 API Key、Base URL 与认证和 Anthropic Messages。