跳到主要內容ATP Token

把任何 coding agent 接上 ATP

本頁內容

任何會說 Anthropic 或 OpenAI wire format 的 agent 都能跑在專案（project）金鑰上。真正要填的只有三個值：Gateway 的 base URL、一把 atp- 開頭的金鑰，以及該專案已啟用的模型 ID。這一頁涵蓋我們完整記錄的兩個 agent（Claude Code 與 Codex CLI）、其他工具共用的通用規則，以及三個套用通用規則會壞掉的工具。

貼給你的 agent#

多數人不會自己一格一格填，而是直接叫 agent 去接。下面這段就是為了整段複製而寫的，把 <你的工具名> 換成你要接的工具即可。

Read https://atptoken.ai/docs/agents.md and follow it to connect my <your tool> to ATP Token.
My key is in the ATP_API_KEY environment variable.
First call GET https://api.atptoken.ai/v1/models to see which models are available,
then pick one from that list and configure it.

指令維持英文、指向英文版頁面，是因為那份純 markdown 是給機器讀的正規來源；你要改成中文照樣可以。

每一頁都有純 markdown 版本

任何文件網址後面加上 .md，就會拿到這一頁的 markdown 原始碼——沒有頁面外框、不需要剖析 HTML。上面那段指令要 agent 讀的就是它。

第一步永遠是 GET /v1/models#

碰任何設定檔之前，先列出這把金鑰實際能呼叫哪些模型。agent 最常見的失敗，就是自己猜一個模型名。

Shell
curl https://api.atptoken.ai/v1/models \
  -H "Authorization: Bearer $ATP_API_KEY"

回傳裡的每一個 id，這把金鑰都能用。清單上沒有的模型，代表它沒有在該金鑰所屬的專案啟用，呼叫下去會拿到 403——請先到主控台的「資源」開啟，再跑一次上面的請求，把 id 原樣抄過去。

設定你的 agent#

Claude Code#

設定 base URL（不用加 /v1——Claude Code 會自己補上 /v1/messages），並把金鑰當成 auth token 送出。清掉 ANTHROPIC_API_KEY，避免它蓋過去。

export ANTHROPIC_BASE_URL="https://api.atptoken.ai"
export ANTHROPIC_AUTH_TOKEN="atp-..."
export ANTHROPIC_API_KEY=""
export ANTHROPIC_MODEL="claude-sonnet-4-6"   # any model from GET /v1/models
claude

或把相同的值寫進 ~/.claude/settings.json 的 env 區塊：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.atptoken.ai",
    "ANTHROPIC_AUTH_TOKEN": "atp-...",
    "ANTHROPIC_API_KEY": ""
  },
  "model": "claude-sonnet-4-6"
}

Codex CLI#

在 ~/.codex/config.toml 把 Gateway 加成自訂的 OpenAI-compatible 供應商（base URL 要包含 /v1），再 export env_key 指定的那把金鑰。

# ~/.codex/config.toml
model = "gpt-5.4"            # any model from GET /v1/models
model_provider = "atp"

[model_providers.atp]
name = "ATP"
base_url = "https://api.atptoken.ai/v1"
env_key = "ATP_API_KEY"
wire_api = "chat"
export ATP_API_KEY="atp-..."
codex

兩個工具都用 Authorization: Bearer atp-… 驗證。模型必須在該金鑰所屬專案已啟用，否則 Gateway 回傳 403。

Hermes Agent#

Hermes 把密鑰放在 ~/.hermes/.env，其餘設定放 ~/.hermes/config.yaml。把 Gateway 加成一個具名供應商：

# ~/.hermes/config.yaml
providers:
  atp:
    api: https://api.atptoken.ai/v1
    key_env: ATP_API_KEY
    transport: chat_completions
    default_model: <model from GET /v1/models>
# ~/.hermes/.env
ATP_API_KEY=atp-...

discover_models 預設開啟，所以 hermes model 會直接從 GET /v1/models 讀型錄，不用自己列模型。想改走 Anthropic 格式就把 transport 換成 anthropic_messages。

有兩件事要留意。Hermes 同時還接受舊版的 custom_providers: 清單，跟新的 providers: 並存時，模型選單與實際執行可能讀到不同來源——只留 providers: 就好。另外 ${VAR} 代換失敗不會報錯，變數名打錯只會留下原字串加一則警告，很難查。

OpenClaw#

OpenClaw 的設定在 ~/.openclaw/openclaw.json（JSON5 格式）。把 Gateway 註冊成一個供應商，再把 agent 的預設模型指過去：

{
  models: {
    mode: "merge",
    providers: {
      atp: {
        baseUrl: "https://api.atptoken.ai/v1",
        apiKey: "${ATP_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "<model from GET /v1/models>", contextWindow: 128000, maxTokens: 32000 },
        ],
      },
    },
  },
  agents: { defaults: { model: { primary: "atp/<model-id>" } } },
}

有三個地方會咬人。OpenClaw 直接拒絕純 HTTP，網址一定要是 https。模型清單要手動列——它不會去打 GET /v1/models，沒列到的 id 就是選不到。還有 baseUrl 同時是網路信任邊界，只有那個完全相符的 scheme://host:port 會被放行，所以打錯字的症狀是「請求被擋」而不是「網址錯誤」。

其他 agent 的通用規則#

只要工具有「OpenAI compatible」這一類的供應商，要填的幾乎都是同樣三個值：

  • Base URL——填 https://api.atptoken.ai/v1。要含 /v1，但不要接 /chat/completions，路徑由工具自己補。
  • API 金鑰——那把 atp-… 開頭的專案金鑰。
  • Model——GET /v1/models 回傳的其中一個 id。
工具設定位置欄位或變數Base URL
ClineVS Code 設定介面 → API 供應商選 OpenAI CompatibleBase URL / API 金鑰 / Model含 /v1
Roo CodeVS Code 設定面板 → API 供應商選 OpenAI CompatibleBase URL / API 金鑰 / Model含 /v1
Continue.dev~/.continue/config.yamlprovider: openai 加上 apiBase含 /v1
OpenCodeopencode.json 或 ~/.config/opencode/opencode.jsonoptions.baseURL（npm 套件用 @ai-sdk/openai-compatible）含 /v1
Aider環境變數OPENAI_API_BASE 加上 OPENAI_API_KEY含 /v1

有三件事特別常踩：

  • Aider——model 要寫成 openai/<model-id>。少了這個前綴，請求會被路由到錯的供應商。
  • Cline 與 Roo Code——context window 與 max output tokens 必須自己手動填。留白的話工具會套預設值，token 帳就算錯了。
  • OpenCode——模型清單要自己列（models）。它不會去讀 GET /v1/models，沒列之前模型選單是空的。

欄位名稱與選單位置會隨版本改動，這張表只是起點，實際以你的工具版本為準。

Cline 請選 OpenAI Compatible

本頁的 Cline 設定使用 OpenAI Compatible 供應商；請依上表填入 base URL，不要直接套用到 Anthropic 供應商設定。

Agent Skills 一行安裝#

Skills 是 markdown 格式的操作手冊，讓 agent 在動手寫程式之前，先知道 ATP 的驗證方式、模型查詢、媒體任務與錯誤處理。

Shell
# Codex
curl -fsSL https://atptoken.ai/skills/install.sh | sh -s -- codex

# Claude Code
curl -fsSL https://atptoken.ai/skills/install.sh | sh -s -- claude

# Install for both
curl -fsSL https://atptoken.ai/skills/install.sh | sh -s -- both
ATP Agent Skills

七個官方 Skills 的內容、安裝方式，以及怎麼確認裝到哪裡了。

疑難排解#

  • 403——模型沒有在該金鑰所屬的專案啟用。到主控台的「資源」開啟即可。這是最常見的失敗。
  • 404——/v1 加錯位置。有些工具會把 host 與路徑分成兩個欄位填，這時 /v1 要放在路徑那一邊，不要放進 host。對照上面表格裡你那個工具的那一列。
  • 工具說找不到這個模型——多數工具需要你手動列出模型 ID，它們不會自己去讀 GET /v1/models。
  • Roo Code 專屬——Roo 只支援 native tool calling，沒有 XML 自動備援（fallback），所以挑的模型必須完整支援 function calling。

下一步

下一頁代理技能
這頁有幫助嗎？