---
title: 設定參考
url: https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configuration-reference
description: 了解自行託管的 Claude Managed Agents 伺服器的設定存放位置，並查閱每項設定的鍵、環境變數、預設值與用途。
---
若要申請自行託管的 Claude Managed Agents 存取權，請聯絡您的 Anthropic 客戶團隊。
本頁說明自行託管的 Claude Managed Agents 伺服器的設定存放位置，並列出這些設定。若要設定某項功能，請參閱[單一登入](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configure)、[代理身分與憑證](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/agent-identity)和[推論提供者](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/inference-provider)。
## 設定的存放位置
伺服器從一個 YAML 檔案讀取其設定，並從其環境讀取其憑證。
* **Docker Compose：** 該檔案是解壓縮後封存檔中位於 `docker-compose.yml` 旁的 `compose.config.yaml`。編輯該檔案，然後從該目錄執行 `docker compose restart cma-server`。
* **Kubernetes：** 該檔案是伺服器 Helm chart 的 `server.config` 值。在您的 values 檔案中編輯它，執行 `helm upgrade`，然後使用 `kubectl -n cma-server rollout restart deployment -l anthropic.com/role=server` 重新啟動伺服器。請參閱[在 Kubernetes 上部署](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/kubernetes)。
如果伺服器拒絕自行託管頁面中所示的某項設定，請[升級伺服器](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/upgrade)。封存檔頂層的 `cma-server.example.yaml` 為常用的鍵加上了註解。
憑證絕不會放在該檔案中。伺服器會從環境變數，或從您的雲端附加至主機的身分讀取憑證。
### 將憑證傳遞給 Compose 堆疊
在 Compose 堆疊中，伺服器容器只會接收 `docker-compose.yml` 中 `cma-server` 服務之 `environment:` 清單內的變數。若要傳遞其他變數：
1. 將其名稱加入該清單，並在 `.env` 中設定其值。
2. 如果憑證是檔案，請將該檔案放在 `docker-compose.yml` 旁，並在 `docker-compose.yml` 的 `x-server-mounts` 清單中加入一行，例如 `- ./gcp-key.json:/etc/cma-server/gcp-key.json:ro`。第一個冒號之後的路徑是該檔案在容器內的路徑。請在 `.env` 中使用該路徑作為變數的值，或作為指定該檔案之設定的值。
3. 執行 `docker compose up -d`。重新啟動不會重新讀取 `.env`。
升級會取代 `docker-compose.yml`，因此請在啟動新版本的堆疊之前，於新版本的檔案中重複這些編輯。
## 如何閱讀表格
每項設定在[設定檔](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configuration-reference#where-settings-go)中都有一個鍵，而大多數設定也有對應的環境變數。環境變數會覆寫設定檔，而設定檔會覆寫預設值。如果設定檔含有未知的鍵，伺服器將不會啟動，且錯誤訊息會指出該鍵的位置。
* **鍵：** 鍵中的每個點代表檔案中的一層巢狀結構。例如，`server.addr` 是 `server` 區段中的 `addr` 鍵。
* **變數：** 變數的名稱是 `CMA_` 加上大寫的鍵，並以兩個底線取代每個點。
* **僅限檔案：** 該設定沒有對應的變數。
* **僅限環境變數：** 如果該設定出現在設定檔中，伺服器將無法啟動。
* **僅限 `bedrock` 及類似標籤：** 該設定僅適用於該提供者、儲存區或密鑰管理器。如果您在使用其他提供者、儲存區或密鑰管理器時設定了它，伺服器將無法啟動。
* **清單：** 清單在設定檔中是 YAML 清單，在變數中則是以逗號分隔的字串。
* **時間長度：** 時間長度是帶有單位的數字，例如 `30s`、`5m` 或 `1h`。
* **整數：** 整數是純數字，不含正負號、前導零或底線。
啟動時，伺服器會記錄您所設定的設定以及大多數預設值，並註明每個值的來源，例如 `server.addr=0.0.0.0:8400 (file)`。對於機密值，伺服器會記錄 `***` 來取代，但伺服器自行產生的伺服器 API 金鑰除外。
## 伺服器與記錄
| 設定
環境變數 | 預設值 | 說明 |
| --------------------------------------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `server.addr`
`CMA_SERVER__ADDR` | `127.0.0.1:8400` | 伺服器監聽的位址。 |
| `server.api_key`
`CMA_SERVER__API_KEY` | 無 | [伺服器 API 金鑰](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted#the-three-credentials)。搭配 `store.backend: postgres` 時為必填，除非 `auth.refuse_server_api_key` 為 `true`。搭配 `memory` 時，如果您未設定，伺服器會產生一個金鑰，並在啟動時記錄它。 |
| `server.id_marker`
`CMA_SERVER__ID_MARKER` | `local` | 伺服器建立的每個 ID 中，接在前綴之後的內容。`local` 會產生 `sesn_local_01…`，而 `none` 會產生 `sesn_01…`，與託管服務相同。 |
| `server.shutdown_delay`
`CMA_SERVER__SHUTDOWN_DELAY` | `0s` | 收到停止訊號後，伺服器在其就緒探測回應 `not_ready` 期間持續提供服務的時間。最大值為 `5m`。 |
| `server.max_connections`
`CMA_SERVER__MAX_CONNECTIONS` | `0` | 伺服器在 `server.addr` 上同時保持開啟的最大連線數。`0` 表示沒有限制。達到上限時，新連線會等待，直到另一個連線關閉或其用戶端放棄。事件串流、worker 輪詢和健康狀態探測都會計入。在 Kubernetes 上，kubelet 會重新啟動探測等待過久的 pod。 |
| `logging.format`
`CMA_LOGGING__FORMAT` | `text` | 記錄格式，`text` 或 `json`。 |
| `logging.level`
`CMA_LOGGING__LEVEL` | `info` | 伺服器記錄的最低層級。可用值為 `debug`、`info`、`warn` 和 `error`。 |
| `logging.errors`
`CMA_LOGGING__ERRORS` | `false` | 記錄中是否包含 `4xx` 和 `5xx` 回應的錯誤訊息。訊息可能會引用用戶端傳送的值。 |
| `health.check_interval`
`CMA_HEALTH__CHECK_INTERVAL` | `60s` | 伺服器為就緒探測檢查其推論憑證的頻率。最小值為 `5s`。 |
| `health.upstream_affects_readiness`
`CMA_HEALTH__UPSTREAM_AFFECTS_READINESS` | `true` | 當推論提供者拒絕伺服器的憑證時，就緒探測是否回應 `503`。 |
## 資料庫
本表中除了 `store.backend` 之外的每項設定，僅在搭配 `store.backend: postgres` 時適用。
| 設定
環境變數 | 預設值 | 說明 |
| --------------------------------------------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `store.backend`
`CMA_STORE__BACKEND` | `memory` | 伺服器儲存資料的位置。可用值為 `memory`（重新啟動後會清除）和 `postgres`。 |
| `store.database_url`
`CMA_STORE__DATABASE_URL` | 無 | PostgreSQL 連線字串。搭配 `postgres` 時為必填。 |
| `store.control_database_url`
`CMA_STORE__CONTROL_DATABASE_URL` | `store.database_url` 的值 | 伺服器自身維護連線（例如其心跳）所用的連線字串。 |
| `store.listen_database_url`
`CMA_STORE__LISTEN_DATABASE_URL` | `store.database_url` 的值 | 伺服器用來監聽通知的那一條連線所用的連線字串。交易模式下的連線集區器無法承載該連線。 |
| `store.migrate_database_url`
`CMA_STORE__MIGRATE_DATABASE_URL` | `store.database_url` 的值 | 伺服器的 `migrate` 命令所使用的連線字串。交易模式下的連線集區器無法承載該連線。 |
| `store.pool_max_conns`
`CMA_STORE__POOL_MAX_CONNS` | `24` | 單一伺服器的連線集區最多開啟的資料庫連線數。最小值為 `4`。 |
| `store.event_poll_interval`
`CMA_STORE__EVENT_POLL_INTERVAL` | `25ms` | 每台伺服器向資料庫查詢其用戶端正在串流之工作階段中最新事件的頻率。由另一台伺服器記錄的事件，最多約等待此時間長度即會送達串流。 |
| `store.credentials_encryption_key`
`CMA_STORE__CREDENTIALS_ENCRYPTION_KEY`
僅限環境變數 | 無 | 用於加密資料庫中所儲存憑證的金鑰，格式為 base64 編碼的 32 個隨機位元組。Docker Compose 和 Kubernetes 安裝會設定此值。若未設定，伺服器將無法啟動，除非 `store.allow_unencrypted_credentials` 為 `true`。 |
| `store.allow_unencrypted_credentials`
`CMA_STORE__ALLOW_UNENCRYPTED_CREDENTIALS` | `false` | 伺服器是否可以在沒有 `store.credentials_encryption_key` 的情況下啟動。沒有該金鑰時，伺服器會以純文字將憑證儲存在資料庫中。如果 `git.allowed_hostnames` 列出了主機，或您使用 Docker Compose 或伺服器 Helm chart 進行安裝，`true` 將沒有作用。 |
| `store.credentials_encryption_keys_retiring`
`CMA_STORE__CREDENTIALS_ENCRYPTION_KEYS_RETIRING`
僅限環境變數 | 無 | 在金鑰輪替期間，伺服器仍可用來解密的先前加密金鑰。此設定需要 `store.credentials_encryption_key`。 |
## 推論提供者
若要設定提供者，請參閱[推論提供者](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/inference-provider)。
| 設定
環境變數 | 預設值 | 說明 |
| -------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inference.provider`
`CMA_INFERENCE__PROVIDER` | `anthropic` | 伺服器傳送模型呼叫的目的地。可用值為 `anthropic`、`bedrock`、`vertex`、`foundry` 和 `gateway`。 |
| `inference.headers`
僅限檔案 | 無 | 伺服器加入每個模型呼叫的請求標頭，格式為標頭名稱對應值的映射。請為每個值加上引號。對於 YAML 不會讀取為文字的未加引號值（例如 `true` 或 `0042`），伺服器會拒絕啟動。搭配 `gateway` 時，值也可以是 `{ from: request_id }` 或 `{ from: session_id }`。 |
| `inference.model_fallback`
`CMA_INFERENCE__MODEL_FALLBACK` | `true` | 僅限 `anthropic`。模型呼叫是否要求[伺服器端備援](https://platform.claude.com/docs/zh-TW/build-with-claude/refusals-and-fallback#server-side-fallback)。這些呼叫會攜帶 `fallbacks` 欄位和標頭 `anthropic-beta: server-side-fallback-2026-07-01`。您在 `ANTHROPIC_BASE_URL` 中指定的代理伺服器可能會拒絕該欄位或標頭。如果它以 `400` 或 `422` 回應，伺服器會在不含它們的情況下重新傳送該呼叫。 |
| `inference.metadata.user_id`
`CMA_INFERENCE__METADATA__USER_ID` | 無 | 僅限 `anthropic` 和 `foundry`，或搭配 `format: anthropic-messages` 的 `gateway`。伺服器在每個模型呼叫中以 `metadata.user_id` 傳送的單一識別碼。啟動記錄會印出此值。若未設定此項，伺服器會傳送標籤 `cma-server`。您無法關閉 `metadata.user_id`。如果提供者或代理伺服器拒絕它，每個模型呼叫都會失敗。請參閱[哪些內容會離開您的網路](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-data-and-access#what-leaves-your-network)。 |
### 雲端提供者
| 設定
環境變數 | 預設值 | 說明 |
| -------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `inference.region`
`CMA_INFERENCE__REGION` | 無 | 僅限 `bedrock` 和 `vertex`。AWS 區域，或 Google Cloud’s Agent Platform 中的位置。搭配 `vertex` 時為必填。若未設定，`bedrock` 會使用 AWS SDK 預設鏈找到的區域。 |
| `inference.project_id`
`CMA_INFERENCE__PROJECT_ID` | 無 | 僅限 `vertex`。發出呼叫所在的 Google Cloud 專案。除非 Google 憑證已指定專案，否則為必填。 |
| `inference.api`
`CMA_INFERENCE__API` | `invoke_model` | 僅限 `bedrock`。承載呼叫的 Amazon Bedrock API，`invoke_model` 或 `messages`。`messages` 是 [Claude in Amazon Bedrock (`bedrock-mantle`)](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-in-amazon-bedrock) 所描述的端點。搭配此值時，伺服器的 AWS 角色需要 `bedrock-mantle:CreateInference`，以取代 `bedrock:InvokeModel` 和 `bedrock:InvokeModelWithResponseStream`。 |
| `inference.list_models`
`CMA_INFERENCE__LIST_MODELS` | `true` | 僅限 `bedrock`。伺服器是否讀取 Amazon Bedrock 的 Claude 模型清單。有了這些清單，代理便可使用在您伺服器版本發布之後推出的模型。 |
| `inference.model_id_prefix`
`CMA_INFERENCE__MODEL_ID_PREFIX` | `us.anthropic.` | 僅限 `bedrock`。伺服器加在每個模型 ID 前面的文字。搭配 `inference.api: messages` 時，預設值為 `anthropic.`。 |
| `inference.model_id_overrides`
僅限檔案 | 無 | 僅限 `bedrock`、`vertex` 和 `foundry`。模型 ID 對應提供者所預期之確切 ID 的映射。搭配 `foundry` 時，該 ID 是部署名稱。 |
| `inference.foundry.resource`
`CMA_INFERENCE__FOUNDRY__RESOURCE` | 無 | 僅限 `foundry`。Foundry 資源的名稱。請設定此項或 `inference.foundry.base_url`，但不要同時設定兩者。 |
| `inference.foundry.base_url`
`CMA_INFERENCE__FOUNDRY__BASE_URL` | 無 | 僅限 `foundry`。根據預設，呼叫會傳送至 `https://.services.ai.azure.com/anthropic`。若要透過其他位址（例如代理伺服器）存取該資源，請改為在此設定該 URL。該 URL 以 `/anthropic` 結尾。 |
### 模型閘道
這些設定僅在搭配 `inference.provider: gateway` 時適用。請參閱[模型閘道](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/inference-provider#model-gateway)。
| 設定
環境變數 | 預設值 | 說明 |
| ----------------------------------------------------------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inference.gateway.url`
`CMA_INFERENCE__GATEWAY__URL` | 無 | 必填。接收模型呼叫的 URL。搭配 `bedrock-invoke` 和 `vertex-raw-predict` 時，`{model}` 標示模型 ID 的位置。搭配 `vertex-raw-predict` 時，URL 必須以 `/{model}:rawPredict` 結尾。 |
| `inference.gateway.format`
`CMA_INFERENCE__GATEWAY__FORMAT` | 無 | 必填。閘道接受的請求格式：`bedrock-invoke`、`anthropic-messages` 或 `vertex-raw-predict`。 |
| `inference.gateway.model_map`
僅限檔案 | 無 | 必填。將代理可指定的每個模型 ID 對應到閘道所預期之 ID 的映射。請為每個值加上引號，如同 `inference.headers`。 |
| `inference.gateway.streaming`
`CMA_INFERENCE__GATEWAY__STREAMING` | `false` | 伺服器是否傳送該格式的串流呼叫，讓回覆在模型產生時即送達。搭配 `bedrock-invoke` 時，該呼叫會傳送至附加了 `-with-response-stream` 的相同 URL。搭配 `vertex-raw-predict` 時，該呼叫會傳送至以 `:streamRawPredict` 取代 `:rawPredict` 的相同 URL。請在 `inference.gateway.url` 中保留 `:rawPredict`。 |
| `inference.credentials.supplier`
`CMA_INFERENCE__CREDENTIALS__SUPPLIER` | 無 | 必填。閘道憑證的來源。`env` 表示一個長期有效的金鑰，`oauth_exchange` 表示短期權杖，`azure` 表示核發給伺服器自身 Azure 身分的 Microsoft Entra ID 權杖。 |
| `inference.credentials.env.var`
`CMA_INFERENCE__CREDENTIALS__ENV__VAR` | 無 | 搭配 `env` 時為必填。存放金鑰的環境變數名稱。 |
| `inference.credentials.azure.scope`
`CMA_INFERENCE__CREDENTIALS__AZURE__SCOPE` | 無 | 搭配 `azure` 時為必填。伺服器請求權杖所用的範圍：您閘道之應用程式註冊的應用程式 ID URI 或應用程式 ID，後接 `/.default`。 |
| `inference.credentials.send_as.header`
`CMA_INFERENCE__CREDENTIALS__SEND_AS__HEADER` | `Authorization` | 承載憑證的請求標頭。 |
| `inference.credentials.send_as.scheme`
`CMA_INFERENCE__CREDENTIALS__SEND_AS__SCHEME` | `Bearer` | 標頭中位於憑證之前的字詞。在 `Authorization` 以外的任何標頭下，預設為不使用配置。 |
| `inference.credentials.renew_before`
`CMA_INFERENCE__CREDENTIALS__RENEW_BEFORE` | `90s` | 搭配 `oauth_exchange` 時，伺服器提前替換權杖的時間。伺服器會在快取權杖到期前的這段時間停止使用它，並為下一個模型呼叫取得另一個權杖。請將此值保持在低於您權杖有效期的範圍。伺服器會拒絕有效時間少於此值的任何權杖。 |
### 短期閘道權杖
這些設定僅在搭配 `inference.credentials.supplier: oauth_exchange` 時適用。請參閱[短期權杖](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/inference-provider#short-lived-tokens)。`exchange` 設定作為一組是選用的。若未設定，伺服器會將回呼傳回的內容傳送給閘道。
| 設定
環境變數 | 預設值 | 說明 |
| ----------------------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------- |
| `inference.credentials.assertion.url`
`CMA_INFERENCE__CREDENTIALS__ASSERTION__URL` | 無 | 必填。傳回已簽署斷言的 HTTP 回呼 URL。 |
| `inference.credentials.assertion.auth.type`
`CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__TYPE` | 無 | 必填。伺服器向回呼進行驗證的方式，`mtls` 或 `bearer_file`。 |
| `inference.credentials.assertion.auth.cert_file`
`CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__CERT_FILE` | 無 | 搭配 `mtls` 時為必填。伺服器用戶端憑證的路徑。 |
| `inference.credentials.assertion.auth.key_file`
`CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__KEY_FILE` | 無 | 搭配 `mtls` 時為必填。用戶端憑證私密金鑰的路徑。 |
| `inference.credentials.assertion.auth.token_file`
`CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__TOKEN_FILE` | 無 | 搭配 `bearer_file` 時為必填。存放 bearer 權杖之檔案的路徑。 |
| `inference.credentials.assertion.auth.ca_file`
`CMA_INFERENCE__CREDENTIALS__ASSERTION__AUTH__CA_FILE` | 無 | 包含伺服器為回呼所信任之憑證授權單位的 PEM 檔案路徑。 |
| `inference.credentials.assertion.forward_metadata`
`CMA_INFERENCE__CREDENTIALS__ASSERTION__FORWARD_METADATA` | 無 | 伺服器會將其值傳送給回呼的工作階段中繼資料鍵。這些值會以請求主體中的 `session.metadata` 送達。這些值是 API 呼叫者所寫入的任何內容，因此請與您自己的記錄進行核對。 |
| `inference.credentials.exchange.token_url`
`CMA_INFERENCE__CREDENTIALS__EXCHANGE__TOKEN_URL` | 無 | 進行交換時為必填。伺服器用斷言交換權杖的 OAuth 權杖端點。 |
| `inference.credentials.exchange.grant_type`
`CMA_INFERENCE__CREDENTIALS__EXCHANGE__GRANT_TYPE` | 無 | 進行交換時為必填。伺服器傳送的 `grant_type`，例如 `urn:ietf:params:oauth:grant-type:jwt-bearer`。 |
| `inference.credentials.exchange.encoding`
`CMA_INFERENCE__CREDENTIALS__EXCHANGE__ENCODING` | `form` | 伺服器編碼交換請求的方式，`form` 或 `multipart`。 |
| `inference.credentials.exchange.expiry`
`CMA_INFERENCE__CREDENTIALS__EXCHANGE__EXPIRY` | `expires_in` | 伺服器讀取權杖有效期的位置。`expires_in` 表示取回應的 `expires_in` 與權杖的 `exp` 宣告中較早者。`jwt_exp` 表示僅使用 `exp` 宣告。 |
| `inference.credentials.exchange.headers`
僅限檔案 | 無 | 權杖端點的額外請求標頭，格式為標頭名稱對應值的映射。請為每個值加上引號，如同 `inference.headers`。 |
| `inference.credentials.exchange.ca_file`
`CMA_INFERENCE__CREDENTIALS__EXCHANGE__CA_FILE` | 無 | 包含伺服器為權杖端點所信任之憑證授權單位的 PEM 檔案路徑。 |
## 單一登入
若要設定登入，請參閱[單一登入](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configure)。
| 設定
環境變數 | 預設值 | 說明 |
| -------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auth.issuers`
僅限檔案 | 無 | 伺服器接受其權杖的 OpenID Connect 簽發者。請參閱[簽發者項目](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configuration-reference#issuer-entries)。 |
| `auth.refuse_server_api_key`
僅限檔案 | `false` | 伺服器是否在每個路由上拒絕伺服器 API 金鑰。`true` 需要至少一個簽發者。此時所有需要該金鑰的管理 CLI 命令都會失敗。 |
### 簽發者項目
`auth.issuers` 的每個項目接受以下欄位：
| 欄位 | 預設值 | 說明 |
| ----------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | 無 | 必填。簽發者在記錄行中的標籤。伺服器也會將其記錄為每個資源建立者的一部分。 |
| `issuer_url` | 無 | 必填。簽發者的 URL，須與其權杖中 `iss` 宣告完全相同。伺服器會從此主機以及簽發者探索文件中所指定的 `jwks_uri` 主機擷取簽署金鑰。如果您的網路限制對外連線，請允許這兩個主機。 |
| `audiences` | 無 | 必填。權杖的 `aud` 宣告可以攜帶的值。如果應用程式轉送其已持有的權杖，請列出每個應用程式的用戶端 ID。 |
| `roles` | 無 | `group` 與 `role` 配對的清單。群組會完全比對，或作為模式比對，其中 `*` 代表任意長度的字元序列，`?` 代表單一字元。角色為 `admin`、`developer` 或 `user`。符合的最高角色優先。請設定 `roles`、`default_role` 或兩者。 |
| `default_role` | 無 | 群組未符合任何 `roles` 項目之呼叫者的角色。只有在每位能為此受眾取得權杖的人都應具有存取權時，才設定此項。 |
| `subject_claim` | `sub` | 識別呼叫者的宣告。以 `/` 開頭的名稱是指向巢狀宣告的 JSON Pointer。 |
| `stable_subject` | `false` | 僅在 `subject_claim` 指定 `sub` 或 `oid` 以外的宣告時適用。設為 `true` 以確認您的提供者絕不會變更某人在該宣告中的值，也絕不會將其指派給其他人。伺服器不會檢查這一點。設為 `false` 時，[代理權杖](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configuration-reference#agent-identity)會省略 `actor_sub` 和 `actor_iss` 宣告。 |
| `groups_claim` | `groups` | 列出呼叫者群組的宣告。以 `/` 開頭的名稱是指向巢狀宣告的 JSON Pointer。 |
| `jwks_file` | 無 | JSON Web Key Set 檔案的路徑。伺服器從該檔案讀取簽署金鑰，且永不聯繫簽發者。 |
| `login_client_id` | 無 | [終端機登入](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configure#let-developers-log-in-from-a-terminal)所使用之應用程式的用戶端 ID。只有一個簽發者可以設定此項。 |
| `login_scopes` | `[openid]` | 登入時請求的範圍。此欄位需要 `login_client_id`。 |
## 密鑰管理器
若要設定儲存區，請參閱[密鑰管理器](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/agent-identity#secret-manager)。
| 設定
環境變數 | 預設值 | 說明 |
| ----------------------------------------------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `secret_store.type`
`CMA_SECRET_STORE__TYPE` | 無 | 存放 vault 憑證的密鑰管理器。可用值為 `aws_secrets_manager`、`gcp_secret_manager`、`azure_key_vault` 和 `hashicorp_vault`。若未設定，vault 憑證會保留在資料庫中。 |
| `secret_store.prefix`
`CMA_SECRET_STORE__PREFIX` | 無 | 搭配 `secret_store.type` 時為必填。伺服器建立的每個機密名稱的開頭。對於 `aws_secrets_manager` 和 `hashicorp_vault`，它必須以 `/` 結尾；對於 `gcp_secret_manager`，必須以 `-` 或 `_` 結尾；對於 `azure_key_vault`，必須以 `-` 結尾。 |
| `secret_store.region`
`CMA_SECRET_STORE__REGION` | 無 | 僅限 `aws_secrets_manager`，且在該情況下為必填。存放機密的 AWS 區域。 |
| `secret_store.project`
`CMA_SECRET_STORE__PROJECT` | 無 | 僅限 `gcp_secret_manager`，且在該情況下為必填。存放機密的 Google Cloud 專案 ID。 |
| `secret_store.vault_url`
`CMA_SECRET_STORE__VAULT_URL` | 無 | 僅限 `azure_key_vault`，且在該情況下為必填。金鑰保存庫的 URL，例如 `https://my-vault.vault.azure.net`。 |
### HashiCorp Vault
這些設定僅在搭配 `secret_store.type: hashicorp_vault` 時適用。請恰好設定一種登入方法：`token_file`、`kubernetes` 或 `approle`。
| 設定
環境變數 | 預設值 | 說明 |
| -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------- |
| `secret_store.address`
`CMA_SECRET_STORE__ADDRESS` | 無 | 必填。Vault 伺服器的 `https://` URL。 |
| `secret_store.namespace`
`CMA_SECRET_STORE__NAMESPACE` | 無 | 存放掛載點與登入方法的 Vault Enterprise 命名空間。 |
| `secret_store.mount`
`CMA_SECRET_STORE__MOUNT` | `secret` | KV 第 2 版機密引擎的路徑。 |
| `secret_store.ca_cert_file`
`CMA_SECRET_STORE__CA_CERT_FILE` | 無 | 包含簽署 Vault 憑證之憑證授權單位的 PEM 檔案路徑。 |
| `secret_store.token_file`
`CMA_SECRET_STORE__TOKEN_FILE` | 無 | 包含由其他處理程序（例如 Vault Agent）保持最新之 Vault 權杖的檔案路徑。 |
| `secret_store.kubernetes.role`
`CMA_SECRET_STORE__KUBERNETES__ROLE` | 無 | 搭配 `kubernetes` 時為必填。伺服器登入時所用的 Vault 角色。請將其繫結至伺服器的服務帳戶。 |
| `secret_store.kubernetes.mount_path`
`CMA_SECRET_STORE__KUBERNETES__MOUNT_PATH` | `kubernetes` | Vault 掛載 Kubernetes 登入方法的位置。 |
| `secret_store.kubernetes.service_account_token_file`
`CMA_SECRET_STORE__KUBERNETES__SERVICE_ACCOUNT_TOKEN_FILE` | `/var/run/secrets/kubernetes.io/serviceaccount/token` | 伺服器每次登入時出示之服務帳戶權杖的路徑。 |
| `secret_store.approle.role_id`
`CMA_SECRET_STORE__APPROLE__ROLE_ID` | 無 | 搭配 `approle` 時為必填。伺服器登入時所用之 AppRole 角色的 ID。 |
| `secret_store.approle.secret_id_file`
`CMA_SECRET_STORE__APPROLE__SECRET_ID_FILE` | 無 | 搭配 `approle` 時為必填。包含該角色 `secret_id` 的檔案路徑。 |
| `secret_store.approle.mount_path`
`CMA_SECRET_STORE__APPROLE__MOUNT_PATH` | `approle` | Vault 掛載 AppRole 登入方法的位置。 |
## 代理身分
若要設定代理權杖，請參閱[代理身分](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/agent-identity#agent-identity)。本表中的任何設定都會開啟此功能。此時伺服器需要 `agent_identity.issuer`，以及恰好一個存放簽署金鑰的位置：`key_file`、`key_secret` 或 `kms_key`。
| 設定
環境變數 | 預設值 | 說明 |
| ----------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `agent_identity.issuer`
`CMA_AGENT_IDENTITY__ISSUER` | 無 | 代理權杖作為其 `iss` 宣告攜帶的 `https://` URL。 |
| `agent_identity.key_file`
`CMA_AGENT_IDENTITY__KEY_FILE` | 無 | 簽署權杖之 PEM 私密金鑰的路徑。 |
| `agent_identity.key_secret`
`CMA_AGENT_IDENTITY__KEY_SECRET` | 無 | 在您的密鑰管理器中存放 PEM 私密金鑰之機密的名稱，不含 `secret_store.prefix`。 |
| `agent_identity.kms_key.provider`
`CMA_AGENT_IDENTITY__KMS_KEY__PROVIDER` | 無 | 存放簽署金鑰的金鑰管理服務，`aws_kms` 或 `gcp_kms`。 |
| `agent_identity.kms_key.key`
`CMA_AGENT_IDENTITY__KMS_KEY__KEY` | 無 | 搭配 `kms_key.provider` 時為必填。`aws_kms` 為金鑰的 ARN，`gcp_kms` 則為某一個金鑰版本的資源名稱。 |
| `agent_identity.published_key_files`
`CMA_AGENT_IDENTITY__PUBLISHED_KEY_FILES` | 無 | 金鑰集額外 PEM 公開金鑰的路徑。伺服器會發布這些金鑰，但永遠不會使用它們簽署。請在輪替簽署金鑰時使用此設定。 |
| `agent_identity.token_lifetime`
`CMA_AGENT_IDENTITY__TOKEN_LIFETIME` | `5m` | 從權杖的 `iat` 宣告到其 `exp` 宣告的時間。已傳送的權杖在其 `exp` 之前仍然有效。最小值為 `limits.mcp_call_timeout` 加上 `1m`，最大值為 `15m`。 |
| `agent_identity.jwks_uri`
`CMA_AGENT_IDENTITY__JWKS_URI` | `/.well-known/jwks.json` | 簽發者的探索文件為金鑰集提供的 URL。僅當您將金鑰集託管在簽發者 URL 以外的位置時，才設定此項。 |
| `agent_identity.direct.audiences`
僅限檔案 | 無 | 可以取得權杖的接收者。每個項目都有一個 `audience` URL 和 `urls`，即該接收者之 MCP 伺服器的 URL 前綴。 |
| `agent_identity.actor.enabled`
`CMA_AGENT_IDENTITY__ACTOR__ENABLED` | `true` | 伺服器是否將 `actor_sub` 和 `actor_iss` 宣告加入工具呼叫的權杖。`actor_sub` 是建立工作階段之呼叫者的主體（subject）。`actor_iss` 是呼叫者登入時所透過之 `auth.issuers` 項目的 `issuer_url`。這兩個宣告都不表示呼叫者核准了該呼叫。 |
## 輸出閘道
若要設定閘道，請參閱[環境變數憑證](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/agent-identity#environment-variable-credentials)。僅在 `egress.gateway_enabled: true` 時設定本表中的其他設定。若未如此設定，只要設定了其中任何一項，伺服器就不會啟動。
| 設定
環境變數 | 預設值 | 說明 |
| ----------------------------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `egress.gateway_enabled`
`CMA_EGRESS__GATEWAY_ENABLED` | `false` | 伺服器是否與輸出閘道搭配運作，並接受 `environment_variable` vault 憑證。 |
| `egress.allowed_hostnames`
`CMA_EGRESS__ALLOWED_HOSTNAMES` | 無 | 沙箱可透過閘道存取的確切公開主機名稱。不含連接埠的項目（例如 `api.example.com`）會允許 `https` URL 的連接埠 443 和 `http` URL 的連接埠 80。含連接埠的項目（例如 `api.example.com:8443`）僅允許該連接埠。 |
| `egress.swap_header_names`
`CMA_EGRESS__SWAP_HEADER_NAMES` | `Authorization` | 閘道可以放入憑證值的請求標頭。您自己的清單會取代預設值，因此請在其中包含 `Authorization`。 |
| `egress.gateway_listen`
`CMA_EGRESS__GATEWAY_LISTEN` | `:8410` | 伺服器第二個監聽器的位址，該監聽器僅為閘道提供服務。預設值會在所有介面上監聽。 |
| `egress.gateway_key_file`
`CMA_EGRESS__GATEWAY_KEY_FILE` | 無 | 必填。包含閘道向伺服器出示之金鑰的檔案路徑。 |
| `egress.ca_cert_file`
`CMA_EGRESS__CA_CERT_FILE` | 無 | 必填。閘道憑證授權單位之 PEM 憑證的路徑。 |
| `egress.gateway_proxy_address`
`CMA_EGRESS__GATEWAY_PROXY_ADDRESS` | 無 | 必填。沙箱連線至閘道代理連接埠所用的 `host:port`。 |
## MCP 伺服器
請參閱[MCP 伺服器需要允許清單項目](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/differences#mcp-servers-need-an-allowlist-entry)。
| 設定
環境變數 | 預設值 | 說明 |
| --------------------------------------------------------- | ------------------ | ----------------------------------------------- |
| `mcp.allowed_hostnames`
`CMA_MCP__ALLOWED_HOSTNAMES` | 無 | 伺服器可連線之 MCP 伺服器的確切主機名稱。若未設定，伺服器不會連線至任何 MCP 伺服器。 |
| `mcp.private_hostnames`
僅限檔案 | 無 | `mcp.allowed_hostnames` 中可以解析為私人位址的主機名稱。 |
| `mcp.max_result_bytes`
`CMA_MCP__MAX_RESULT_BYTES` | `102400` (100 KiB) | 模型可看到的單一 MCP 工具結果的最大位元組數。最小值為 `1024`。 |
## Git 儲存庫
請參閱[Git 儲存庫需要允許清單項目](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/differences#git-repositories-need-an-allowlist-entry)。
| 設定
環境變數 | 預設值 | 說明 |
| --------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `git.allowed_hostnames`
`CMA_GIT__ALLOWED_HOSTNAMES` | 無 | 工作階段的儲存庫可以位於的 Git 主機。主機名稱會完全比對，不支援萬用字元，且項目不涵蓋其子網域。項目會允許連接埠 443，或其所指定的單一連接埠，例如 `git.example.com:8443`。若未設定此項，伺服器不接受任何儲存庫。 |
| `git.private_hostnames`
僅限檔案 | 無 | `git.allowed_hostnames` 中解析為私人位址的主機名稱，以不含連接埠的形式寫入。對於其他任何主機名稱，伺服器只會連線至其公開位址。 |
| `git.allowed_push_refs`
`CMA_GIT__ALLOWED_PUSH_REFS` | 無 | 代理可以推送的分支，每個都位於 `refs/heads/` 之下。以 `/` 結尾的項目允許其下的所有分支。其他任何項目則允許該單一分支。若未設定此項，代理無法推送。 |
| `git.commit_author_name`
`CMA_GIT__COMMIT_AUTHOR_NAME` | `Claude` | 代理提交上的作者名稱。請與 `git.commit_author_email` 一併設定。 |
| `git.commit_author_email`
`CMA_GIT__COMMIT_AUTHOR_EMAIL` | `noreply@anthropic.com` | 代理提交上的作者電子郵件地址。請與 `git.commit_author_name` 一併設定。 |
| `git.max_concurrent_transfers`
`CMA_GIT__MAX_CONCURRENT_TRANSFERS` | `32` | 單一伺服器同時承載的最大 Git 請求數。最小值為 `1`。 |
| `git.max_session_transfer_bytes`
`CMA_GIT__MAX_SESSION_TRANSFER_BYTES` | `8589934592` (8 GiB) | 單一伺服器為單一工作階段承載的最大 Git 流量（以位元組計），上傳和下載合併計算。每次沙箱接手工作階段時，計數會從零重新開始。達到上限時，伺服器會以 `403` 拒絕該工作階段接下來的 Git 請求。`0` 表示沒有限制。否則，最小值為 `1048576`。 |
| `git.max_push_bytes`
`CMA_GIT__MAX_PUSH_BYTES` | `2147483648` (2 GiB) | 單次推送可傳送的最大位元組數。最小值為 `1048576`。 |
以下限制適用於 Git 儲存庫：
* **通訊協定：** 伺服器不支援 SSH 或 Git LFS，並且會拒絕重新導向，例如已重新命名之儲存庫的重新導向。
* **權杖：** Git 主機必須接受該權杖作為 HTTP Basic 驗證的密碼，使用者名稱為 `x-access-token`。
* **URL：** 儲存庫 URL 只有一個擁有者和一個儲存庫名稱，因此您無法使用 GitLab 子群組中的儲存庫。
* **主機：** 對於位於 `git.allowed_hostnames` 未列出之主機上的 URL，伺服器會傳回 `400`。錯誤訊息會指出 URL 必須位於 `github.com`，即使您列出了其他主機。
* **推送：** 伺服器一律拒絕刪除分支，或變更分支以外任何內容（例如標籤）的推送。
## 網頁工具與技能
請參閱[網頁工具需要伺服器設定](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/differences#web-tools-need-a-server-setting)。
| 設定
環境變數 | 預設值 | 說明 |
| ----------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------- |
| `web_tools.enabled`
`CMA_WEB_TOOLS__ENABLED` | `false` | 代理是否可以使用 `web_search` 和 `web_fetch` 工具。如果您設定了其他 `web_tools` 設定，預設值為 `true`。 |
| `web_tools.allowed_domains`
`CMA_WEB_TOOLS__ALLOWED_DOMAINS` | 無 | 代理可透過網頁工具讀取的唯一網域。項目涵蓋其子網域。 |
| `web_tools.blocked_domains`
`CMA_WEB_TOOLS__BLOCKED_DOMAINS` | 無 | 任何代理都無法透過網頁工具讀取的網域。請設定此項或 `web_tools.allowed_domains`，但不要同時設定兩者。 |
| `web_tools.max_content_tokens`
`CMA_WEB_TOOLS__MAX_CONTENT_TOKENS` | 無 | `web_fetch` 傳回給模型的單一擷取頁面最大 token 數。 |
| `skills.max_name_chars`
`CMA_SKILLS__MAX_NAME_CHARS` | `64` | `SKILL.md` 檔案可擁有的最長 `name`。最大值為 `255`。 |
| `skills.max_description_chars`
`CMA_SKILLS__MAX_DESCRIPTION_CHARS` | `1024` | `SKILL.md` 檔案可擁有的最長 `description`。 |
## 限制、逾時與排程
| 設定
環境變數 | 預設值 | 說明 |
| ------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `limits.max_active_sessions`
`CMA_LIMITS__MAX_ACTIVE_SESSIONS` | `64` | 僅限 `store.backend: memory`。同時執行回合的最大工作階段數。`0` 表示沒有限制。 |
| `limits.max_live_subagent_threads`
`CMA_LIMITS__MAX_LIVE_SUBAGENT_THREADS` | `25` | 單一工作階段同時可持有的最大子代理執行緒數。執行緒在封存或終止之前都會計入，因此閒置的執行緒也會計入。達到上限時，代理無法再啟動其他子代理。最小值為 `1`，最大值為 `4000`。 |
| `scheduler.max_concurrent_turns`
`CMA_SCHEDULER__MAX_CONCURRENT_TURNS` | `64` | 僅限 `store.backend: postgres`。單一伺服器同時執行的最大回合數。最小值為 `1`。伺服器會另外保留僅供子代理回合使用的槽位。其數量為此值的四分之一，且至少為 `4`。使用預設值時，單一伺服器可以執行 64 個回合，外加 16 個子代理回合。 |
| `scheduler.claim_poll_interval`
`CMA_SCHEDULER__CLAIM_POLL_INTERVAL` | `1s` | 僅限 `store.backend: postgres`。有空閒回合槽位的伺服器在資料庫中尋找等待中工作的頻率。最小值為 `50ms`。 |
| `scheduler.sandbox_claim`
`CMA_SCHEDULER__SANDBOX_CLAIM` | `immediate` | worker 可以啟動工作階段沙箱的時機。`immediate` 表示工作階段一建立即可啟動，因此第一個工具呼叫的等待時間最短。`tool_call` 表示在工作階段第一個需要沙箱的工具呼叫時啟動，因此未發出此類呼叫的工作階段不會使用任何沙箱。 |
| `limits.model_call_timeout`
`CMA_LIMITS__MODEL_CALL_TIMEOUT` | `20m` | 單一模型呼叫（包含重試）在伺服器取消之前可執行的時間。 |
| `limits.stream_idle_timeout`
`CMA_LIMITS__STREAM_IDLE_TIMEOUT` | `5m` | 模型呼叫的回應在伺服器放棄該次嘗試之前，可以不傳遞任何內容的時間。 |
| `limits.mcp_call_timeout`
`CMA_LIMITS__MCP_CALL_TIMEOUT` | `4m` | 單一 MCP 工具呼叫在伺服器放棄之前可執行的時間。 |
## 模型與壓縮
| 設定
環境變數 | 預設值 | 說明 |
| ------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `models.settings`
僅限檔案 | 無 | 對伺服器內建模型目錄的變更，以模型 ID 為鍵。請參閱[模型項目](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/configuration-reference#model-entries)。 |
| `compaction.triggers`
僅限檔案 | 約為各模型上下文視窗的 90% | 模型上的回合壓縮其歷史記錄時的上下文大小（以 token 計），以模型 ID 為鍵。最小值為 `50000`。每個模型都必須支援壓縮。 |
### 模型項目
`models.settings` 的每個項目會變更目錄中的模型或新增一個模型。對於目錄中的模型，您省略的欄位會保留其內建值。
| 欄位 | 說明 |
| ------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `fast_supported` | 模型是否接受 `speed: "fast"`。您新增的模型必須設定此欄位。 |
| `inference_geo_supported` | 模型是否接受 `inference_geo`。 |
| `forced_tool_choice_supported` | 模型是否接受強制其呼叫某一個工具的請求。伺服器只會為了執行已核准的 `web_search` 或 `web_fetch` 呼叫而傳送此類請求。設為 `false` 時，伺服器絕不會在此模型上強制使用工具。 |
| `effort_supported` | 模型是否接受努力程度等級。 |
| `effort_levels` | 模型接受的努力程度等級，可從 `low`、`medium`、`high`、`xhigh` 和 `max` 中選擇。在沒有內建等級的模型上搭配 `effort_supported: true` 時為必填。 |
| `effort_default` | 代理未指定努力程度等級之工作階段的等級。必須是 `effort_levels` 其中之一。在沒有內建預設值的模型上搭配 `effort_supported: true` 時為必填。 |
| `thinking` | 伺服器請求的思考模式，`enabled` 或 `adaptive`。 |
| `thinking_budget` | 伺服器搭配 `thinking: enabled` 傳送的思考預算（以 token 計）。 |
| `max_tokens` | 每個模型呼叫的 `max_tokens` 值。 |
## 您伺服器上的主控台
| 設定
環境變數 | 預設值 | 說明 |
| ----------------------------------------- | ------ | ------------------------------------------------------------------------------------------- |
| `console.serve`
`CMA_CONSOLE__SERVE` | `true` | 是否提供[您伺服器上的主控台](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/console)。 |