---
outline: [2, 3]
head:
  - - meta
    - name: description
      content: 使用 OneGateway API Keys 接入 Claude Code、Codex 和其他常用工具，配置网关地址、密钥与模型，并验证调用记录。
---

# 接入常用工具

Claude Code、Codex 和其他支持自定义模型服务地址的工具，可以通过 OneGateway 调用模型。先在 [API Keys](/user/tokens) 创建密钥并复制 **API 地址**，再从[可用模型](/user/models)复制目标模型 ID。建议为每个工具分别创建密钥，便于查看用量和调整限制。

## 接入前准备

确认密钥已启用、未过期、额度充足，且可用模型范围包含目标模型。工具需要的接口和模型能力也必须得到供应商支持。

| 工具 | 使用的接口 | 地址示例 |
| --- | --- | --- |
| Claude Code | Anthropic Messages | `https://your-api-endpoint`，客户端追加 `/v1/messages` |
| Codex | OpenAI Responses | `https://your-api-endpoint/v1`，客户端追加 `/responses` |
| 支持 OpenAI 格式的聊天工具 | 通常为 Chat Completions，以工具要求为准 | `https://your-api-endpoint/v1` |

示例中的 `your-api-endpoint`、`sk-xxxxxxxx` 和模型 ID 都需要替换。实际地址以控制台提供的 **API 地址** 为准；部署在子路径时保留该路径，不要重复添加 `/v1`。

## Claude Code

先按 [Claude Code 官方说明](https://code.claude.com/docs/en/overview)安装客户端。以下配置适用于终端中的 Claude Code。

### 配置地址与密钥

在将要启动 Claude Code 的终端中设置环境变量。`ANTHROPIC_BASE_URL` 填网关基础地址，`ANTHROPIC_AUTH_TOKEN` 填 OneGateway 发放的密钥，客户端会通过 Bearer 认证发送它。配置方式见 [Claude Code 网关接入文档](https://code.claude.com/docs/en/llm-gateway-connect)。

::: code-group

```bash [macOS / Linux]
export ANTHROPIC_BASE_URL='https://your-api-endpoint'
export ANTHROPIC_AUTH_TOKEN='sk-xxxxxxxx'
claude --model 'your-claude-model-id'
```

```powershell [Windows PowerShell]
$env:ANTHROPIC_BASE_URL = 'https://your-api-endpoint'
$env:ANTHROPIC_AUTH_TOKEN = 'sk-xxxxxxxx'
claude --model 'your-claude-model-id'
```

:::

`your-claude-model-id` 应替换为可用模型中的 ID，并选择支持 Anthropic Messages 和工具调用的模型。已有 `ANTHROPIC_API_KEY` 或其他网关配置时，先核对它们是否与本次配置冲突。

环境变量仅对当前终端及从它启动的程序生效。需要长期使用时，可将配置合并到个人的 `~/.claude/settings.json` 的 `env` 中；已有设置需保留。

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-api-endpoint",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxx"
  }
}
```

保存真实密钥的配置应放在个人目录，避免提交到项目仓库。

### 验证调用

在客户端中运行 `/status`，确认 Anthropic base URL 和凭据来源，然后发起一个简单请求，例如“介绍当前目录的结构”。在 OneGateway [日志](/user/usage)中核对密钥、模型、供应商和用量。

如果连接失败，先检查基础地址是否重复包含 `/v1`，再核对密钥和模型 ID。仅在网页中看到模型，不能证明该模型已满足 Claude Code 的工具调用要求。

## Codex

先按 [Codex 官方快速开始](https://developers.openai.com/codex/quickstart/)安装客户端。以下使用自定义模型供应商配置连接 OneGateway，配置字段依据 [OpenAI 官方网关接入文档](https://learn.chatgpt.com/docs/enterprise/connect-to-a-gateway)。

### 配置模型供应商

将以下内容合并到个人的 `~/.codex/config.toml`；Windows 对应 `%USERPROFILE%\.codex\config.toml`。顶层的 `model` 和 `model_provider` 放在第一个表头之前，避免被 TOML 解释为表内字段。

```toml
model = "your-codex-model-id"
model_provider = "onegateway"

[model_providers.onegateway]
name = "OneGateway"
base_url = "https://your-api-endpoint/v1"
wire_api = "responses"
env_key = "ONEGATEWAY_API_KEY"
supports_websockets = false
```

`your-codex-model-id` 替换为网关可用模型中支持 Responses 和工具调用的模型 ID。`supports_websockets = false` 使用 HTTP 流式连接；完整字段说明见 [Codex 配置参考](https://learn.chatgpt.com/docs/config-file/config-reference)。

在启动 Codex 的终端中设置密钥：

::: code-group

```bash [macOS / Linux]
export ONEGATEWAY_API_KEY='sk-xxxxxxxx'
codex
```

```powershell [Windows PowerShell]
$env:ONEGATEWAY_API_KEY = 'sk-xxxxxxxx'
codex
```

:::

密钥由 `env_key` 指定的环境变量读取。使用这种自定义供应商配置时，应确认启动 Codex 的终端已设置该变量。

### 验证调用

启动后确认使用的模型与供应商，再提交一个简单请求。在 OneGateway [日志](/user/usage)中确认请求经过网关，使用了预期的 API Key 和模型。

如果返回接口不存在，核对地址和网关对 `/v1/responses` 的支持；如果提示模型不存在或无权限，核对模型 ID、密钥限制和供应商分组定价。

## 其他聊天工具

在工具的模型服务设置中选择支持自定义地址的 OpenAI 或 Anthropic 接口，填写 OneGateway API 地址和密钥，手工添加或选择可用模型 ID。以 OpenAI Chat Completions 为例，Base URL 通常为 `https://your-api-endpoint/v1`。

先发送一句简短提问，再到日志中验证结果。地址、密钥和模型确认可用后，再开启图片输入、工具调用等功能；功能支持取决于选定模型与接口。

## 常见接入问题

| 现象 | 检查方向 |
| --- | --- |
| 404 或路径不存在 | Base URL、客户端自动追加的路径、是否重复添加 `/v1` |
| 401 或密钥无效 | 凭据是否完整、环境变量是否传入启动进程、密钥是否启用 |
| 模型不存在或无权限 | 模型 ID、密钥可用模型范围、供应商状态与分组定价 |
| 工具启动后仍连接原服务 | 个人配置是否被其他配置覆盖，客户端是否从设置环境变量的终端启动 |
| 普通聊天可用，工具调用失败 | 模型及上游接口是否支持工具调用和工具要求的协议 |

更多排查见[常见问题](/guide/faq#troubleshooting-order)。