第一次使用 AI 智能体Your first AI coding agent

先认识三个概念Learn three basics first

注册、验证、充值、保存 KeyRegister, verify, add credit, and save your key

选择适合您的客户端Choose the right client

画面为步骤示意，按钮名称可能随软件版本略有变化。Illustrations are representative; labels may change between app versions.

选择可用的 Model IDChoose an available Model ID

Model ID 是软件识别模型的准确名称，必须从下表复制，不能凭显示名称猜测。

A Model ID is the exact name software uses. Copy it from the live list below instead of guessing from a display name.

Codex

Mac：从打开“终端”开始Mac: start by opening Terminal

mkdir -p ~/.codex
touch ~/.codex/config.toml
cp ~/.codex/config.toml ~/.codex/config.toml.backup
open -a TextEdit ~/.codex/config.toml

read -s "APIGATE_API_KEY?Paste your ats_ key: "
export APIGATE_API_KEY
launchctl setenv APIGATE_API_KEY "$APIGATE_API_KEY"

model = "gpt-5.4-mini"
model_provider = "apigate"

[model_providers.apigate]
name = "APIGate"
base_url = "https://api.apigate.biz/v1"
env_key = "APIGATE_API_KEY"
wire_api = "responses"
requires_openai_auth = false

如果只测试命令行，可在同一个终端执行：codex exec "Reply only: APIGATE_OK"。注销或重新启动 Mac 后，需要重新设置环境变量。请使用上述 config.toml 测试；单独另存为 apigate.config.toml 不会自动创建 profile。

CLI-only test: codex exec "Reply only: APIGATE_OK". Set the environment variable again after logging out of macOS. Use the config.toml above for the test; a separately named file is not automatically a profile.

下一步：在同一个终端执行 codex exec --skip-git-repo-check "只回复：APIGATE_OK"。如果终端提示 Not inside a trusted directory，这是因为当前不在受信任的 Git 项目目录；保留上面的 --skip-git-repo-check 即可完成一次测试，不是 Key 错误。注销或重新启动 Mac 后，需要重新设置环境变量。

Next, in the same terminal run codex exec --skip-git-repo-check "Reply only: APIGATE_OK". If Codex says Not inside a trusted directory, you are outside a trusted Git project; keep --skip-git-repo-check for this one-shot test. It is not a key error. Set the environment variable again after logging out or restarting macOS.

Windows：从打开 PowerShell 开始Windows: start by opening PowerShell

New-Item -ItemType Directory -Force "$HOME\.codex" | Out-Null
if (-not (Test-Path "$HOME\.codex\config.toml")) { New-Item -ItemType File "$HOME\.codex\config.toml" | Out-Null }
Copy-Item "$HOME\.codex\config.toml" "$HOME\.codex\config.toml.backup" -Force
notepad "$HOME\.codex\config.toml"

Windows 先使用 Codex CLI。用户级配置位于 $HOME\.codex\config.toml；不要放到项目里的 .codex\config.toml，因为自定义模型供应商设置只从用户级配置读取。桌面界面若没有“自定义供应商”入口，也不要把 Key 填进普通 ChatGPT 登录框。

On Windows, begin with the Codex CLI and use the user-level $HOME\.codex\config.toml. Do not put provider settings in a project-local config.

$secure = Read-Host "Paste your ats_ key" -AsSecureString
$ptr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure)
$env:APIGATE_API_KEY = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($ptr)
[Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ptr)
codex exec "Reply only: APIGATE_OK"

Claude Code

read -s "APIGATE_KEY?Paste your ats_ key: "
export ANTHROPIC_AUTH_TOKEN="$APIGATE_KEY"
unset APIGATE_KEY
export ANTHROPIC_BASE_URL="https://api.apigate.biz"
claude -p --model claude-haiku-4-5 "Reply only: APIGATE_OK"

Windows PowerShell

Windows用户不要执行上面的read/export命令，请复制下面整段到PowerShell。看到APIGATE_OK后，使用同一个PowerShell窗口运行claude --model claude-sonnet-4-6。不要先执行/login。

Windows users must use the PowerShell block below instead of the read/export commands. After APIGATE_OK, run claude --model claude-sonnet-4-6 in the same window. Do not run /login first.

$secure = Read-Host "Paste your ats_ key" -AsSecureString
$ptr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secure)
$env:ANTHROPIC_AUTH_TOKEN = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($ptr)
[Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ptr)
Remove-Item Env:ANTHROPIC_API_KEY -ErrorAction SilentlyContinue
$env:ANTHROPIC_BASE_URL = "https://api.apigate.biz"
claude -p --model claude-haiku-4-5 "Reply only: APIGATE_OK"

这些变量只对当前终端窗口有效，关闭后Key不会写进配置文件。Claude Code的提示缓存会按官方缓存倍率计费，并显示在APIGate用量记录中。

These variables apply only to the current Terminal window, so the key is not written to a config file. Claude Code prompt caching is billed using the official cache multipliers and recorded in APIGate usage.

OpenClaw

{
  models: {
    mode: "merge",
    providers: {
      apigate: {
        baseUrl: "https://api.apigate.biz/v1",
        apiKey: "${APIGATE_API_KEY}",
        api: "openai-completions",
        models: [{
          id: "gpt-5.4-mini",
          name: "GPT-5.4 mini via APIGate",
          reasoning: true,
          input: ["text", "image"],
          contextWindow: 400000,
          maxTokens: 128000
        }]
      }
    }
  },
  agents: {
    defaults: {
      model: { primary: "apigate/gpt-5.4-mini" }
    }
  }
}

read -s "APIGATE_API_KEY?Paste your ats_ key: "
export APIGATE_API_KEY
openclaw config validate
openclaw doctor
openclaw gateway restart
openclaw agent --local --message "Reply only: APIGATE_OK"

通用API与最小测试Generic API and minimum test

如果您使用Python、JavaScript、Cherry Studio或其他支持自定义OpenAI地址的软件，Base URL使用https://api.apigate.biz/v1，Key使用您的ats_ Key。

For Python, JavaScript, Cherry Studio, or any client supporting a custom OpenAI endpoint, use https://api.apigate.biz/v1 as the Base URL and your ats_ key.

curl https://api.apigate.biz/v1/chat/completions \
  -H "Authorization: Bearer ats_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.4-nano","messages":[{"role":"user","content":"Reply only: APIGATE_OK"}]}'

iPhone、iPad 与 AndroidiPhone, iPad, and Android

接入后：完成一次可核对的验收

保存并重新打开客户端 → 回复 APIGATE_OK → 在练习文件夹读取一份无敏感资料的文本 → 核对工具结果及 APIGate 控制台同一时间、对应 Key／模型的调用记录。

模型自报身份不能证明线路正确；CLI 成功不能代替桌面端测试。

常见问题与排错Common problems and fixes