> ## Documentation Index
> Fetch the complete documentation index at: https://datagen.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Harness

> 選擇驅動 Agent 的執行環境、鎖定確切版本，並把模型呼叫導向 Anthropic 相容的閘道

**Harness**（介面顯示為「執行框架」）是一組可重複使用的預設，定義*驅動 Agent 的方式*：Agent 執行環境及其確切版本、選填的 Anthropic 相容 LLM 供應商，以及進階執行設定。設定一次後，就能在任何 Agent、知識庫建構器、App 建構器或資料建構器上選用。

沒有 Harness 時，一切都以內建的 **Claude Agent SDK** 搭配原生 Anthropic 執行。以下情況請建立 Harness：

* **鎖定執行環境版本**，讓映像檔更新永遠不會改變 Agent 的行為。
* **把模型呼叫導向你自己的閘道** -- LLM proxy、自架模型伺服器，或其他供應商的 Anthropic 相容端點。
* **調整執行環境** -- 壓縮（compaction）、思考預算、逾時設定。

## 開啟 Harness

在左側欄開啟 **更多** 選單，選擇 **執行框架**。每張卡片會摘要該預設，例如
`sdk@0.3.204 · gateway.example.com · my-model · 2 項進階設定`，或
`內建 SDK · 原生 Anthropic`。

管理員與建構者可以建立、編輯和刪除 Harness。所有成員都可以檢視。

***

## 執行環境：Claude Agent SDK vs Codex

| 執行環境 | 狀態 |
| - | - |
| **Claude Agent SDK** | 可用，且為預設。Agent 在沙盒中以 Anthropic 的 Claude Agent SDK（`@anthropic-ai/claude-agent-sdk`）執行。 |
| **Codex** | 在 **執行環境** 選單中標示為 **即將推出**，目前還無法選取或綁定。 |

Harness 建立後就無法更改執行環境；若要切換，請建立新的 Harness。

***

## 建立 Harness

<Steps>
  <Step title="開啟對話框">
    點選 **新增執行框架**。
  </Step>

  <Step title="名稱與執行環境">
    輸入 **名稱**（在工作區內不可重複，例如 `gateway-prod`）與選填的 **描述**。**執行環境** 保持 **Claude Agent SDK**。
  </Step>

  <Step title="鎖定版本（選填）">
    輸入確切的 **版本**，或留空使用內建預設。
  </Step>

  <Step title="指向閘道（選填）">
    填寫 **LLM 供應商** 欄位，把模型呼叫導向 Anthropic 相容端點。
  </Step>

  <Step title="新增進階設定（選填）">
    使用 **+ 新增設定…** 調整執行環境。
  </Step>

  <Step title="建立">
    點選 **建立**，然後在你的 Agent 上選用這個 Harness。
  </Step>
</Steps>

### 版本鎖定

| 欄位 | 用途 |
| - | - |
| **版本** | Claude Agent SDK 的確切版本，例如 `0.3.204`。留空則使用沙盒映像檔內建的 SDK（最快）。 |

* 只接受確切版本 -- 不接受 `latest` 之類的標籤，也不接受 `^0.3` 之類的範圍。浮動標籤會讓鎖定失去意義。
* 若鎖定的版本與內建版本不同，會在執行開始時於沙盒內安裝，因此會增加啟動時間。
* 當你的 Agent 已在某版本上驗證過，或你的閘道需要特定的傳輸行為時，請鎖定版本。

***

## LLM 供應商（Anthropic 相容閘道）

**Claude base URL** 留空即使用原生 Anthropic，其他供應商欄位會維持停用。填入後，所有模型呼叫都會送往你的端點。

| 欄位 | 沙盒中設定的環境變數 | 用途 |
| - | - | - |
| **Claude base URL** | `ANTHROPIC_BASE_URL` | Anthropic 相容端點（`http://` 或 `https://`），例如 `https://gateway.example.com/anthropic`。 |
| **驗證權杖密鑰** | `ANTHROPIC_AUTH_TOKEN` 與 `ANTHROPIC_API_KEY` | 存放供應商金鑰的工作區密鑰**名稱**。它的值會取代你的 Anthropic 金鑰送到閘道。選擇 **不使用密鑰（使用預設驗證）** 則沿用既有的 `ANTHROPIC_API_KEY`。 |
| **供應商模型** | `ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` | 供應商提供的模型 ID，例如 `my-model`。 |
| **供應商小型模型** | `ANTHROPIC_DEFAULT_HAIKU_MODEL`、`ANTHROPIC_SMALL_FAST_MODEL`、`CLAUDE_CODE_SUBAGENT_MODEL` | 用於快速、背景與子代理（subagent）呼叫的模型。留空則使用 **供應商模型**。 |

### 驗證權杖密鑰如何運作

**驗證權杖密鑰** 只儲存*名稱*，永遠不會儲存金鑰本身：

<Steps>
  <Step title="把供應商金鑰存成工作區密鑰">
    在工作區設定 -> **密鑰** 新增閘道的金鑰，例如名稱為 `gateway_api_key`。選擇器會列出工作區的密鑰。
  </Step>

  <Step title="在 Harness 上選取">
    在 **驗證權杖密鑰** 選取它。儲存時會檢查該名稱是否存在於工作區密鑰，或工作區 Default [連線保險庫](/zh/foundation/vault) 的密鑰插槽中；找不到的名稱會被拒絕。
  </Step>

  <Step title="執行時">
    DataGen 會先在本次執行的連線保險庫所提供的密鑰中查找該名稱（不分大小寫，連字號視同底線），再到工作區密鑰中查找。其值會同時匯出為 `ANTHROPIC_AUTH_TOKEN`（以 Bearer 權杖送出）與 `ANTHROPIC_API_KEY`（以 `x-api-key` 送出），因此接受任一種標頭的閘道都能運作，而你真正的 Anthropic 金鑰永遠不會送到自訂網址。
  </Step>
</Steps>

<Warning>
  選擇 **不使用密鑰（使用預設驗證）** 時，連線保險庫或工作區密鑰中既有的 `ANTHROPIC_API_KEY` 會被送到自訂 base URL。只要閘道不是由你營運，或它不預期收到你的 Anthropic 金鑰，就請選擇驗證權杖密鑰。設定自訂 base URL 時，Claude 訂閱的 OAuth 權杖一律會被移除。
</Warning>

### 模型優先順序

設定 **供應商模型** 後，綁定此 Harness 的每個 Agent 都會以它執行。Agent 的 **預設模型** 與任何自動化設定的模型都會被忽略，Agent 設定畫面也會顯示提示，說明此 Agent 一律使用哪個模型。若要讓各 Agent 的預設模型生效，請將 **供應商模型** 留空。

***

## 進階設定

**+ 新增設定…** 提供一份執行設定允許清單。每一項都會以同名環境變數注入沙盒；只接受以下鍵值。

| 設定 | 類型 | 預設 |
| - | - | - |
| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` -- 觸發自動壓縮的上下文視窗大小 | tokens，10,000 - 2,000,000 | 模型完整視窗 |
| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` -- 觸發自動壓縮的視窗百分比 | 1 - 100 | 約 70 |
| `MAX_THINKING_TOKENS` -- 延伸思考預算 | tokens，0 - 200,000 | 模型預設 |
| `CLAUDE_CODE_EFFORT_LEVEL` -- 推理強度 | `low`、`medium`、`high`、`xhigh` | 模型預設 |
| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` -- 每次回應的最大輸出 tokens | tokens，1,000 - 128,000 | 模型預設 |
| `API_TIMEOUT_MS` -- API 請求的 HTTP 逾時 | ms，1,000 - 3,600,000 | 600000 |
| `BASH_DEFAULT_TIMEOUT_MS` -- Bash 指令預設逾時 | ms，1,000 - 3,600,000 | 120000 |
| `BASH_MAX_TIMEOUT_MS` -- Bash 逾時上限 | ms，1,000 - 3,600,000 | 600000 |
| `MCP_TIMEOUT` -- MCP 伺服器啟動逾時 | ms，1,000 - 600,000 | 30000 |
| `MCP_TOOL_TIMEOUT` -- 單次 MCP 工具呼叫逾時 | ms，1,000 - 3,600,000 | 30000 - 60000 |
| `BASH_MAX_OUTPUT_LENGTH` -- Bash 輸出截斷前的長度 | 字元，1,000 - 10,000,000 | 約 100000 |
| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` -- 從子程序環境中移除 Anthropic / 雲端憑證 | 開 / 關 | 關 |
| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` -- 停用自動記憶 | 開 / 關 | 關 |
| `CLAUDE_CODE_DISABLE_ATTACHMENTS` -- 停用附件處理 | 開 / 關 | 關 |
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` -- 停用遙測與更新檢查 | 開 / 關 | 關 |

<Tip>
  轉譯到 OpenAI 風格後端（例如 vLLM）的閘道，可能會拒絕推理強度值 `high`。遇到這類閘道，請把 `CLAUDE_CODE_EFFORT_LEVEL` 設為 `medium`。
</Tip>

***

## 在哪裡選用 Harness

| 位置 | 設定 | 保持預設時 |
| - | - | - |
| **Agent** | **執行框架與模型** 卡片 -> **執行框架**，再點 **儲存** | **預設（內建 SDK、原生 Anthropic）** |
| **知識庫建構器** | 知識庫設定 -> **執行框架** | **預設（內建 SDK、原生 Anthropic）** |
| **App 建構器** | App 建構器 -> **執行環境**（建構器對話所使用的執行環境與模型） | **工作區預設** |
| **資料建構器** | 資料 -> **建構器設定** -> **執行框架** | 內建 SDK、原生 Anthropic |

***

## 常見問題

<AccordionGroup>
  <Accordion title="Agent 忽略了自己的預設模型">
    Harness 設定了 **供應商模型**。請在 Harness 上清除它，或把這些 Agent 綁定到其他 Harness。
  </Accordion>

  <Accordion title="閘道對某個模型回傳 404">
    有些供應商無法對應 Claude 的模型名稱。請同時設定 **供應商模型** 與 **供應商小型模型**，讓每個模型插槽（包含子代理與快速背景呼叫）都使用供應商提供的模型。
  </Accordion>

  <Accordion title="儲存時出現找不到密鑰名稱的錯誤">
    **驗證權杖密鑰** 必須在儲存前已存在於工作區密鑰，或 Default 連線保險庫的密鑰中。請先建立，再選取。
  </Accordion>

  <Accordion title="清除 base URL">
    清除 **Claude base URL** 也會一併清除驗證權杖密鑰與兩個模型欄位，讓 Harness 乾淨地回到原生 Anthropic。
  </Accordion>

  <Accordion title="刪除 Harness">
    綁定它的 Agent 會改用內建預設（內建 SDK、原生 Anthropic）。
  </Accordion>
</AccordionGroup>

## 下一步

<CardGroup cols={2}>
  <Card title="資料總覽" icon="database" href="/zh/data/overview">
    連接資料庫並發布 Agent 可查詢的分析資料。
  </Card>

  <Card title="建立 Agent" icon="robot" href="/zh/agents/build">
    在 Agent 上組合連線保險庫、沙箱環境與 Harness。
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.