TkForA 使用教程

本教程介绍如何将 TkForA（Token For Agent）配置到常见的智能体和 OpenAI 兼容客户端。示例中的地址和密钥均为占位符，请替换为 TkForA 控制台或管理员提供的实际值。

安全提示：不要把真实 API Key、带认证参数的分享链接、Cookie 或配置文件中的密钥提交到 Git 仓库、截图或公开工单中。

第一步、使用 CC Switch 快速配置多种智能体

1.1 下载 CC Switch

从 CC Switch Releases 下载与你的系统匹配的版本并完成安装。首次打开后，先确认应用列表已经更新。

适用场景：

快速配置 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 或 Hermes Agent。
不希望手动编辑 config.toml、settings.json 或 opencode.json。

1.2 添加 TkForA 配置

在 CC Switch 顶部选择目标应用类型。
新增或导入一个供应商配置，并将显示名称设置为 TkForA。
将服务地址替换为 TkForA 提供的地址，例如 https://your-tkfora-endpoint.example.com。
Claude Code 通常填写根地址；OpenAI 兼容客户端通常填写带 /v1 的地址。以客户端字段提示和 TkForA 实际接口说明为准。
填入 YOUR_API_KEY 形式的实际密钥，保存后启用该配置。

CC Switch 配置示例

第二步、Codex CLI、Codex App、VS Code、Cursor 与 Trae

这些客户端通常使用 OpenAI 兼容接口。若客户端提供了供应商表单，优先填写：

字段	示例	说明
Provider	`TkForA`	仅用于本地识别配置
Base URL	`https://your-tkfora-endpoint.example.com/v1`	按 TkForA 接口说明填写
API Key	`YOUR_API_KEY`	使用实际密钥，不要提交到仓库
Model	`YOUR_MODEL_NAME`	使用 TkForA 已开放的模型名

Codex CLI / Codex App

如果使用配置文件，先备份原文件，再按本机实际路径编辑：

# ~/.codex/config.toml
model_provider = "tkfora"
model = "YOUR_MODEL_NAME"

[model_providers.tkfora]
name = "TkForA"
base_url = "https://your-tkfora-endpoint.example.com/v1"
env_key = "TKFORA_API_KEY"

将密钥放入环境变量：

export TKFORA_API_KEY="YOUR_API_KEY"

Windows 用户可在 PowerShell 中使用：

$env:TKFORA_API_KEY = "YOUR_API_KEY"

VS Code、Cursor 与 Trae

在扩展或模型设置中选择 OpenAI 兼容供应商，填写 TkForA 的 Base URL、API Key 和模型名。若工具将 Base URL 自动追加 /chat/completions，只填写服务根地址；若要求完整 OpenAI 兼容根地址，则填写带 /v1 的地址。

Codex 配置示例

第三步、Claude Code

Claude Code 的配置方式取决于安装方式和版本。使用环境变量时，可以先设置 TkForA 的服务地址和密钥：

export ANTHROPIC_BASE_URL="https://your-tkfora-endpoint.example.com"
export ANTHROPIC_API_KEY="YOUR_API_KEY"

如果工具界面要求填写供应商配置：

供应商名称填写 TkForA。
Base URL 使用 TkForA 提供的 Claude 兼容根地址。
API Key 使用实际密钥。
模型填写 TkForA 已开放的 Claude 兼容模型名。
保存后重新启动终端或客户端，使环境变量生效。

也可以在 Claude Code 的设置文件中保存对应的 JSON 配置。不要把真实密钥硬编码到项目文件中，建议使用系统环境变量或本机密钥管理工具。

Claude Code 配置示例

第四步、OpenCode

在 OpenCode 中配置 TkForA 时，使用 OpenAI 兼容提供商：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "tkfora": {
      "name": "TkForA",
      "options": {
        "baseURL": "https://your-tkfora-endpoint.example.com/v1",
        "apiKey": "YOUR_API_KEY"
      },
      "models": {
        "YOUR_MODEL_NAME": {
          "name": "TkForA model"
        }
      }
    }
  }
}

实际配置字段可能随 OpenCode 版本变化。以当前版本的配置提示为准，并确认 Base URL、认证方式和模型名三者匹配。

第五步、Cherry、OpenClaw、Gemini CLI 及其他 OpenAI 兼容软件

Cherry 与其他桌面客户端

在服务商设置中新增 TkForA，选择 OpenAI 兼容协议，填写：

API 地址：TkForA 的兼容接口地址。
API Key：YOUR_API_KEY。
模型：YOUR_MODEL_NAME。
请求路径：如果客户端单独要求填写，通常为 /v1/chat/completions。

OpenClaw、Gemini CLI 及命令行工具

优先使用环境变量或工具提供的用户级配置文件。确认工具不会把密钥写入项目目录、日志或诊断报告。配置后先发送最小请求，再逐步启用流式输出、工具调用和更长上下文。

常见配置文件位置

Codex:       ~/.codex/config.toml
Claude Code: ~/.claude/settings.json
OpenCode:    ~/.config/opencode/opencode.json

Windows 下将 ~ 替换为当前用户目录。修改前建议复制一份备份，出现异常时可以恢复。

第六步、GPT Image API

如果 TkForA 账户已开通图像模型，可以使用 OpenAI 兼容的图像接口。请求示例仅展示结构：

curl "https://your-tkfora-endpoint.example.com/v1/images/generations" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "YOUR_IMAGE_MODEL",
    "prompt": "A simple test image",
    "size": "1024x1024"
  }'

图像 API 配置示例

如果返回模型不存在、权限不足或参数不支持，请先确认账户权限、模型名和接口版本，不要反复重试无效请求。

第七步、成功判断

按下面顺序验证：

客户端能读取到 TkForA 配置。
API Key 未过期，且没有多余空格或换行。
Base URL 没有重复的 /v1、/chat/completions 或 /images/generations。
选择的模型是 TkForA 当前开放的模型。
最小文本请求可以正常返回。
确认流式输出、工具调用或图像生成前，先记录请求时间和返回的 request_id。

最小文本请求成功后，再逐项打开高级能力。这样可以快速判断问题来自认证、地址、模型还是客户端功能。

第八步、常见问题

请求地址应该填根地址还是 `/v1`？

Claude 兼容客户端通常填写根地址；OpenAI 兼容客户端通常填写 /v1。如果客户端会自动拼接路径，避免重复填写路径。

为什么返回 401？

检查 API Key 是否正确、是否过期、是否包含引号或空格，并确认客户端实际使用的是 TkForA 配置而不是旧配置。

为什么返回 404？

通常是 Base URL 或模型路径不匹配。检查是否重复拼接 /v1，并确认客户端协议与 TkForA 开放的接口类型一致。

为什么返回 429？

表示请求频率、并发数或配额受到限制。降低并发、缩短上下文、等待后重试，并保留 request_id 便于定位。

为什么流式输出会中断？

先用非流式请求验证认证和模型，再检查网络代理、客户端超时设置和上下文大小。不要把一次中断直接判断为密钥失效。

为什么请求很慢或返回 5xx？

记录模型、时间、请求大小和 request_id，稍后使用相同配置发送一个小请求。若持续出现，联系 TkForA 支持并提供脱敏后的请求信息。

第九步、重新配置或恢复

如果配置出错，先关闭客户端并恢复备份，然后重新写入 TkForA 配置。

Codex：

Windows:   C:\\Users\\你的用户名\\.codex\\config.toml
macOS/Linux: ~/.codex/config.toml

Claude Code：

Windows:   C:\\Users\\你的用户名\\.claude\\settings.json
macOS/Linux: ~/.claude/settings.json

OpenCode：

Windows:   C:\\Users\\你的用户名\\.config\\opencode\\opencode.json
macOS/Linux: ~/.config/opencode/opencode.json

重新配置后，只做一次最小请求验证。确认正常后，再恢复其他插件、模型和高级参数。若密钥疑似泄露，应立即在 TkForA 控制台撤销并重新生成。

第一步、使用 CC Switch 快速配置多种智能体​

1.1 下载 CC Switch​

1.2 添加 TkForA 配置​

第二步、Codex CLI、Codex App、VS Code、Cursor 与 Trae​

Codex CLI / Codex App​

VS Code、Cursor 与 Trae​

第三步、Claude Code​

第四步、OpenCode​

第五步、Cherry、OpenClaw、Gemini CLI 及其他 OpenAI 兼容软件​

Cherry 与其他桌面客户端​

OpenClaw、Gemini CLI 及命令行工具​

常见配置文件位置​

第六步、GPT Image API​

第七步、成功判断​

第八步、常见问题​

请求地址应该填根地址还是 /v1？​

为什么返回 401？​

为什么返回 404？​

为什么返回 429？​

为什么流式输出会中断？​

为什么请求很慢或返回 5xx？​

第九步、重新配置或恢复​