# AI Coding Agent 與 Harness - GateLLM

> 把 Claude Code、Codex CLI、OpenClaw、Cline、Cursor、Zed、Goose、Aider 等 25+ coding agent 接入 GateLLM —— 每個 harness 的 base URL、設定落點與坑一頁說清。

規範連結: https://www.gatellm.io/zh-TW/coding-agents/

## AI Coding Agent 與 Harness
把 Claude Code、Codex CLI、OpenClaw、Cline、Cursor 等 25+ coding agent 按同樣的三步指到閘道器 —— 每條都給出確切的設定落點與關鍵設定項。
每個 AI coding agent 都從某個地方讀 base URL 與 API key —— 環境變數、設定檔案或設定面板。本頁列出每個 harness 從哪裡讀、說哪種協議、以及真正會絆倒人的那條坑。完整可複製的設定教程在文件網站。
## 閘道器模型該叫什麼名字
有些 harness 釘死了自己的模型 ID、原樣傳送。如果你的閘道器模型名不一樣，第一次呼叫就會 404。兩種對齊方式：
把閘道器模型名取成 harness 實際請求的 ID —— 零額外設定。
或用它的模型環境變數（如 ANTHROPIC_MODEL）指到你的閘道器名。
## 把任意 AI coding agent 指到閘道器
```
# 每個 agent 都只是「一個 base_url + 一把 access key」
export ANTHROPIC_BASE_URL="https://your-gateway.gatellm.io"   # Anthropic 系 agent：根（不帶 /v1）
export ANTHROPIC_API_KEY="<閘道器 access key>"

export OPENAI_API_BASE="https://your-gateway.gatellm.io/v1"   # OpenAI 相容 agent：帶 /v1
export OPENAI_API_KEY="<閘道器 access key>"

# Codex CLI（~/.codex/config.toml）走 Responses 協議
# [model_providers.gatellm]
# base_url = "https://your-gateway.gatellm.io/v1"
# wire_api = "responses"
```
### `Authorization: Bearer <key>`
- SDK / 框架: OpenAI · DashScope · 通用
- Bearer 字首大小寫不敏感

### `x-api-key: <key>`
- SDK / 框架: Anthropic SDK
- 也接受 Authorization

### `x-goog-api-key: <key>`
- SDK / 框架: Gemini SDK
- 也接受 Authorization

## Harness 相容矩陣

### 終端 agent
Claude Code、Codex CLI、Gemini CLI、OpenClaw、opencode、Crush、Droid、Goose、Aider、Qwen Code、OpenHands、Kimi Code、Plandex、SWE-agent、Grok Build、Mistral Vibe、MiMo Code、ForgeCode、Codebuff
| Harness | 協議 | 支援度 | 設定落點 | 關鍵設定項 | 文件 |
| --- | --- | --- | --- | --- | --- |
| Claude Code | Anthropic | 原生 | env vars | ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY, ANTHROPIC_MODEL | https://docs.gatellm.io/zh-CN/quickstart/claude-code-via-gateway |
| Codex CLI | OpenAI Responses | 原生 | ~/.codex/config.toml | base_url, env_key, wire_api | https://docs.gatellm.io/zh-CN/reference/clients-and-gateway-diffs |
| Gemini CLI | Gemini | 原生 | env vars | GOOGLE_GEMINI_BASE_URL, GEMINI_API_KEY | https://docs.gatellm.io/zh-CN/reference/clients-and-gateway-diffs |
| OpenClaw | OpenAI / Anthropic-compatible | OpenAI 相容 | openclaw.json | models.providers.<id>.baseUrl, models.providers.<id>.apiKey | https://docs.gatellm.io/zh-CN/quickstart/anthropic-interop |
| opencode | OpenAI-compatible | OpenAI 相容 | opencode.json | provider.<id>.options.baseURL | https://docs.gatellm.io/zh-CN/quickstart/openai-compatible |
| Crush | OpenAI / Anthropic-compatible | OpenAI 相容 | crush.json | providers.<id>.base_url, providers.<id>.type | https://docs.gatellm.io/zh-CN/quickstart/openai-compatible |
| Factory Droid | OpenAI / Anthropic-compatible | OpenAI 相容 | ~/.factory/settings.json | customModels[].baseUrl, customModels[].provider | https://docs.gatellm.io/zh-CN/quickstart/openai-compatible |
| Goose | OpenAI-compatible | OpenAI 相容 | env vars | OPENAI_HOST, OPENAI_BASE_PATH, OPENAI_API_KEY | https://docs.gatellm.io/zh-CN/quickstart/openai-compatible |
| Aider | OpenAI-compatible (LiteLLM) | OpenAI 相容 | env vars | OPENAI_API_BASE | https://docs.gatellm.io/zh-CN/quickstart/openai-compatible |
| Qwen Code | OpenAI-compatible | OpenAI 相容 | env vars | OPENAI_BASE_URL, OPENAI_API_KEY, OPENAI_MODEL | https://docs.gatellm.io/zh-CN/quickstart/openai-compatible |
| OpenHands | OpenAI-compatible (LiteLLM) | OpenAI 相容 | ~/.openhands/settings.json | base_url, model openai/ prefix | https://docs.gatellm.io/zh-CN/quickstart/openai-compatible |
| Kimi Code CLI | OpenAI / Anthropic | OpenAI 相容 | config.toml | providers | https://docs.gatellm.io/zh-CN/quickstart/openai-compatible |
| Plandex | OpenAI-compatible | OpenAI 相容 | custom models JSON | baseUrl | https://docs.gatellm.io/zh-CN/quickstart/openai-compatible |
| SWE-agent | OpenAI-compatible (LiteLLM) | OpenAI 相容 | env vars | OPENAI_BASE_URL | https://docs.gatellm.io/zh-CN/quickstart/openai-compatible |
| Grok Build | OpenAI-compatible | OpenAI 相容 | config.toml | custom models | https://docs.gatellm.io/zh-CN/quickstart/openai-compatible |
| Mistral Vibe | OpenAI-compatible | OpenAI 相容 | ~/.vibe/config.toml | providers | https://docs.gatellm.io/zh-CN/quickstart/openai-compatible |
| MiMo Code | OpenAI-compatible | OpenAI 相容 | /connect custom provider | base URL, API key | https://docs.gatellm.io/zh-CN/quickstart/openai-compatible |
| ForgeCode | OpenAI / Anthropic | OpenAI 相容 | setup wizard | base URL | https://docs.gatellm.io/zh-CN/quickstart/openai-compatible |
| Codebuff | OpenAI-compatible | OpenAI 相容 | settings | base URL, API key | https://docs.gatellm.io/zh-CN/quickstart/openai-compatible |

### IDE / 編輯器外掛
Cline、Roo Code、Kilo Code、Continue、Zed、Cursor、Windsurf、GitHub Copilot（BYOK）
| Harness | 協議 | 支援度 | 設定落點 | 關鍵設定項 | 文件 |
| --- | --- | --- | --- | --- | --- |
| Cline | OpenAI-compatible | OpenAI 相容 | Settings → OpenAI Compatible | Base URL, API Key, Model ID | https://docs.gatellm.io/zh-CN/quickstart/openai-compatible |
| Roo Code | OpenAI-compatible | OpenAI 相容 | Settings → OpenAI Compatible | Base URL, API Key, Model ID | https://docs.gatellm.io/zh-CN/quickstart/openai-compatible |
| Kilo Code | OpenAI-compatible | OpenAI 相容 | Settings → OpenAI Compatible | Base URL, API Key, Model ID | https://docs.gatellm.io/zh-CN/quickstart/openai-compatible |
| Continue | OpenAI-compatible | OpenAI 相容 | config.yaml | models[].apiBase | https://docs.gatellm.io/zh-CN/quickstart/openai-compatible |
| Zed | OpenAI-compatible | OpenAI 相容 | settings.json | language_models.openai_compatible.<id>.api_url | https://docs.gatellm.io/zh-CN/quickstart/openai-compatible |
| Cursor | OpenAI | 部分支援 | Settings → Models → Override OpenAI Base URL | Override OpenAI Base URL | https://docs.gatellm.io/zh-CN/quickstart/openai-compatible |
| Windsurf | OpenAI-compatible | OpenAI 相容 | Settings → Models → BYOK / custom | Base URL, API Key | https://docs.gatellm.io/zh-CN/quickstart/openai-compatible |
| GitHub Copilot (BYOK) | OpenAI-compatible | OpenAI 相容 | Manage Models → OpenAI-compatible | Base URL, API Key | https://docs.gatellm.io/zh-CN/quickstart/openai-compatible |

### 託管平台
Warp（僅 BYOK 金鑰）、Amazon Q Developer CLI、Devin —— 端點固定或不可改
| Harness | 協議 | 支援度 | 設定落點 | 關鍵設定項 | 文件 |
| --- | --- | --- | --- | --- | --- |
| Warp | OpenAI / Anthropic / Gemini (BYOK) | 部分支援 | Settings → BYOK | BYOK API keys | https://docs.gatellm.io/zh-CN/reference/supported-models-and-sdks |
| Amazon Q Developer CLI | MCP | 無自訂端點 | MCP server | — | https://docs.gatellm.io/zh-CN/reference/supported-models-and-sdks |
| Devin | — | 無自訂端點 | — | — | https://docs.gatellm.io/zh-CN/reference/supported-models-and-sdks |

## 接入坑
### harness 釘死了自己的模型 ID
Claude Code 傳送的是它自己設定的預設 ID（如 claude-opus-5 或 claude-sonnet-5），不是你的閘道器名。要麼把閘道器模型名取成 harness 實際請求的 ID，要麼用它的模型環境變數（如 ANTHROPIC_MODEL）指到你的閘道器名。名字不對 → 第一條訊息就 404 model_not_found。

### Anthropic 系 harness 要指根、不帶 /v1
Anthropic 風格客戶端的 base URL 要指向閘道器根（不帶 /v1）—— 客戶端自己拼 /v1/messages。這裡多寫一個 /v1 會讓路徑段疊一層。

### Codex 自訂 provider 需要 wire_api="responses"
Codex CLI 的 [model_providers.*] 設定塊要求 wire_api = "responses"。閘道器原生實現 /v1/responses —— 把 base_url 指過來、env_key 指向閘道器 access key 即可。

### LiteLLM 底座的 harness 要 openai/ 模型字首
Aider、OpenHands、SWE-agent 底層是 LiteLLM：把 OPENAI_API_BASE 設成閘道器，模型名帶 openai/ 字首（如 openai/閘道器模型名），LiteLLM 才按 OpenAI 相容端點路由。

### 預設走訂閱 OAuth，不是你的 key
Codex、Gemini CLI、Qwen Code 預設走廠商的 OAuth / 訂閱登入。要經閘道器必須顯式切到 API key 認證（同時設 key 與 base URL）—— 否則會直接繞過閘道器。

### IDE 按模型 ID 推斷工具 / 視覺能力
Cline / Roo / Kilo 等按模型名判斷工具呼叫與視覺能力。自訂閘道器名可能關掉函式呼叫 —— 工具呼叫失敗時，檢查客戶端的能力檢測規則，或把模型名取成它認識的家族名。

### 長推理會多出 :keep-alive 與 _gateway_warning
上游長推理期間閘道器會發 SSE 的 :keep-alive 註釋行（無害，跳過以 : 開頭的行即可）；中途斷流時會插入 _gateway_warning 欄位而不是直接報錯 —— 設計目標就是避免 Claude Code 這類 harness 因流錯誤中斷整段會話。

### Claude Code auto mode：決定那份安全裁決由誰應答
auto mode 下，Claude Code 在執行可能有危險的動作前，會等一份伺服器端裁決（請求體裡的 safeguards 欄位）。上游是官方 Anthropic 時，裁決在同一次請求裡由上游給出，閘道器原樣透通、不加干預。上游是忽略該欄位的第三方時，改由閘道器應答 —— 出廠預設（allow_all）放行全部動作，比不介入更寬鬆。要把某條上游上的這個判斷交回給它自己，就在該上游的 extra_config 裡寫 "anthropic_server_safeguards": "upstream"；控制台裡這項設定僅 admin 可改。

## 常見問題
### 能經 GateLLM 用 Claude Code 嗎？
能 —— 把 ANTHROPIC_BASE_URL 設為閘道器根（不帶 /v1）、ANTHROPIC_API_KEY 設為閘道器 access key。把閘道器模型名取成 Claude Code 請求的 ID（如 claude-opus-5 或 claude-sonnet-5），或用 ANTHROPIC_MODEL 對齊。
### 怎麼把 Codex CLI 指到閘道器？
在 ~/.codex/config.toml 裡加一個 [model_providers.<id>] 設定塊：base_url = "https://your-gateway.gatellm.io/v1"、env_key 指向你的 access key 環境變數、wire_api = "responses" —— 閘道器原生實現 /v1/responses。
### 哪些 coding agent 不能用自訂端點？
Devin、Amazon Q Developer CLI 這類託管平台不暴露自訂 base URL，無法經閘道器。Warp 支援 BYOK 金鑰但端點固定指向官方。其餘本頁列出的都能改 base URL。
### IDE 外掛（Cline / Roo / Kilo）能用嗎？
能 —— 在設定裡選「OpenAI Compatible」provider，貼上閘道器的 /v1 URL + access key + 模型名。注意能力檢測：有些按模型 ID 推斷工具呼叫能力。
### 為什麼模型名這麼關鍵？
harness 傳送的是固定模型 ID —— 它自己的預設值或你設定的名字。閘道器按這個精確字串路由，不匹配就是 404 model_not_found，不是能忽略的筆誤。
### LiteLLM 底座的 agent（Aider / OpenHands / SWE-agent）呢？
它們讀 OPENAI_API_BASE，模型名要帶 openai/ 字首，LiteLLM 才把閘道器當 OpenAI 相容端點路由。

## 相關頁面
- [首頁](https://www.gatellm.io/zh-TW/index.md)
- [定價](https://www.gatellm.io/zh-TW/pricing.md)
- [成本計算器](https://www.gatellm.io/zh-TW/calculator.md)
- [關於](https://www.gatellm.io/zh-TW/about.md)
- [預約示範](https://www.gatellm.io/zh-TW/demo.md)
- [常見問題](https://www.gatellm.io/zh-TW/faq.md)
- [比較 AI 閘道](https://www.gatellm.io/zh-TW/compare.md)
- [比較 LiteLLM](https://www.gatellm.io/zh-TW/compare/litellm.md)
- [比較 OpenRouter](https://www.gatellm.io/zh-TW/compare/openrouter.md)
- [比較 Alibaba Cloud AI Gateway](https://www.gatellm.io/zh-TW/compare/alibaba-cloud.md)
- [比較 Azure API Management](https://www.gatellm.io/zh-TW/compare/azure-apim.md)
- [比較 Apigee](https://www.gatellm.io/zh-TW/compare/apigee.md)
- [比較 Cloudflare AI Gateway](https://www.gatellm.io/zh-TW/compare/cloudflare.md)
- [比較 Kong AI Gateway](https://www.gatellm.io/zh-TW/compare/kong.md)
- [比較 Portkey](https://www.gatellm.io/zh-TW/compare/portkey.md)
- [LiteLLM vs Kong AI Gateway 比較](https://www.gatellm.io/zh-TW/compare/litellm-vs-kong.md)
- [LiteLLM vs OpenRouter 比較](https://www.gatellm.io/zh-TW/compare/litellm-vs-openrouter.md)
- [LiteLLM vs Portkey 比較](https://www.gatellm.io/zh-TW/compare/litellm-vs-portkey.md)
- [場景方案](https://www.gatellm.io/zh-TW/use-cases.md)
- [降低呼叫成本](https://www.gatellm.io/zh-TW/use-cases/reduce-cost.md)
- [達成高可用](https://www.gatellm.io/zh-TW/use-cases/high-availability.md)
- [多租戶隔離](https://www.gatellm.io/zh-TW/use-cases/multi-tenant.md)
- [合規與稽核](https://www.gatellm.io/zh-TW/use-cases/compliance-audit.md)
- [從症狀排障](https://www.gatellm.io/zh-TW/use-cases/troubleshooting.md)
- [混合多供應商模型堆疊](https://www.gatellm.io/zh-TW/use-cases/mixed-model-stack.md)
- [在 Office 內自架 AI](https://www.gatellm.io/zh-TW/use-cases/self-hosted-office-ai.md)
- [Token 用量可見性與歸因](https://www.gatellm.io/zh-TW/use-cases/token-ops.md)
- [Token FinOps: AI 支出分攤與管控](https://www.gatellm.io/zh-TW/use-cases/token-finops.md)
- [MCP 工具治理](https://www.gatellm.io/zh-TW/use-cases/mcp-tool-governance.md)
- [為所有模型統一加入網路搜尋](https://www.gatellm.io/zh-TW/use-cases/web-search-grounding.md)
- [多 Key 輪替與備援](https://www.gatellm.io/zh-TW/use-cases/multi-key-pooling.md)
- [限制接入的用戶端](https://www.gatellm.io/zh-TW/use-cases/client-admission-control.md)
- [強制模型使用政策](https://www.gatellm.io/zh-TW/use-cases/enforce-model-policy.md)
- [用戶端不暴露模型選擇](https://www.gatellm.io/zh-TW/use-cases/automatic-model-tiering.md)
- [一種協定,任何模型](https://www.gatellm.io/zh-TW/use-cases/one-protocol-any-model.md)
- [Office / Microsoft 365 增益集](https://www.gatellm.io/zh-TW/office-addin.md)
- [術語表](https://www.gatellm.io/zh-TW/glossary.md)
- [模型目錄](https://www.gatellm.io/zh-TW/models.md)
- [SDK 與框架整合](https://www.gatellm.io/zh-TW/integrations.md)
- [安全性與合規](https://www.gatellm.io/zh-TW/security.md)