與託管服務的差異
了解哪些功能只有自行託管的 Claude Managed Agents 具備、它不具備哪些託管功能、哪些功能的行為不同，以及哪些功能需要先進行伺服器設定。
自行託管的 Claude Managed Agents 伺服器與 Anthropic 的託管 Managed Agents 服務具有相同的 API，但本頁面所列的差異除外。下列表格說明各項的因應方式。在將應用程式移至您的伺服器之前，請先查看這些表格。不會從託管服務複製任何內容，包括工作階段歷程記錄。請在您的伺服器上重新建立您的代理、技能、vault 憑證與記憶體儲存區。
只有您的伺服器具備的功能
| 功能 | 用途 | 設定方式 |
|---|---|---|
| 可選擇推論供應商 | 伺服器可以將模型呼叫傳送至雲端供應商或您自己的模型閘道，而非 Claude API。 | 推論供應商 |
| 單一登入 | 人員使用來自您 OpenID Connect 身分識別提供者的權杖呼叫伺服器。伺服器會根據權杖中的群組為每個呼叫者指派角色。伺服器 API 金鑰仍可繼續使用。 | 單一登入 |
| 您自己的密鑰管理器 | 伺服器可以將每個新 vault 憑證的密鑰儲存在您的密鑰管理器中，而非其自身的資料庫。 | 密鑰管理器 |
| 代理身分 | 伺服器可以簽署一個短期有效的權杖，並將其隨代理對 MCP 伺服器的呼叫一併傳送。MCP 伺服器或閘道會根據您發布的公開金鑰驗證該權杖。 | 代理身分 |
無法使用的功能
| 功能 | 會發生什麼 | 替代做法 |
|---|---|---|
| 雲端環境 | 只有 self_hosted 環境存在。要求雲端環境會傳回 400 錯誤。 | 為每個環境部署自行託管的 worker。 |
| Claude API 的其餘部分，例如 Messages API 與 Models API | 伺服器不提供這些 API。SDK 對 /v1/messages 與 /v1/models 的呼叫會傳回 404 錯誤。 | 從未指向您伺服器的用戶端，將這些請求傳送至 Claude API 或您的供應商。 |
| 檔案工作階段資源，以及 Files API | 伺服器會拒絕 file 資源，且 /v1/files 不存在。memory_store 資源可以正常運作。 | 將檔案放在 worker 的工作目錄中。請參閱在工作階段中移入與移出資料。若要讓模型看到圖片或 PDF，請在訊息中以 base64 傳送。 |
mcp_oauth vault 憑證 | 伺服器會在您建立時拒絕它們，因為伺服器沒有可重新整理權杖的 OAuth 流程。 | 將權杖儲存為 static_bearer 憑證。在舊權杖到期之前，以新權杖更新該憑證。 |
預先建置的 docx、pdf、pptx 與 xlsx 技能 | 伺服器會拒絕宣告這些技能的代理。只有您上傳的技能存在。 | 從技能儲存庫下載其原始碼，並將其上傳為自訂技能。 |
| 排程部署與夢境 | 伺服器沒有對應的路由。 | 從您自己的排程器（例如 cron 工作）啟動工作階段。Dreams 沒有替代方案。 |
| Webhook | 伺服器不會傳送任何 webhook，因此透過 webhook 啟動的 worker 永遠不會啟動。 | 透過工作階段的事件串流追蹤工作階段，或列出其事件。讓您的 worker 持續執行，以便它們能夠輪詢。 |
行為不同的功能
| 功能 | 有何不同 | 該怎麼做 |
|---|---|---|
| Claude Console | 位於 platform.claude.com 的 Claude Console 不會顯示您伺服器上的內容。 | 使用您伺服器上的主控台。 |
| 工具呼叫 | 即使沒有 worker 在輪詢其環境，工作階段的模型回合仍會執行。接著第一個工具呼叫會等待，且不會出現錯誤，直到有 worker 執行它為止。 | 如果工作階段停在某個工具呼叫，請確認有 worker 正在輪詢其環境。 |
| 記憶體儲存區 | API 是完整的。由 worker（而非伺服器）將每個附加的儲存區複製到沙箱中，並將變更寫回。請參閱自行託管沙箱中的記憶體儲存區。 | 請以 ant 的最新版本執行您的 worker，並提供可寫入的 /mnt/memory 目錄。 |
| 自訂技能上傳 | 伺服器不會解壓縮 zip 封存檔。上傳 zip 封存檔會傳回 400 錯誤，訊息為 SKILL.md not found in uploaded files。 | ant apply 與 Python SDK 的 files_from_dir 輔助函式可直接使用。若使用其他方式，請將技能的檔案以個別部分上傳，並讓每個部分的檔案名稱以技能的資料夾開頭，例如 my-skill/SKILL.md。 |
| 多代理協調 | 代理只能委派給您列出的子代理。動態工作流程、advisor（顧問）以及代理自行定義的子代理皆無法使用。伺服器只在 multiagent 區塊的 type 為 coordinator 時才接受該區塊。多代理協調中的範例將 type 設為 multiagent_20261001，這會傳回 400 錯誤。具有 advisor 設定的區塊也會傳回 400 錯誤。 | 將 multiagent 設為 {"type": "coordinator", "agents": [...]}。在 agents 中列出 1 到 20 個代理。每個項目採用預先定義代理的形式之一。 |
| GitHub 儲存庫工作階段資源 | 伺服器會拒絕 github_repository 資源，直到您在其設定中列出其 Git 主機為止。伺服器不會探索儲存庫 .claude/skills 目錄中的技能，因此請將技能附加至代理。 | 請參閱Git 儲存庫需要允許清單項目。 |
| MCP 伺服器 | 伺服器只會連線至您在其設定中列出的 MCP 主機。 | 請參閱MCP 伺服器需要允許清單項目。 |
| 網頁工具 | web_search 與 web_fetch 工具在您於伺服器設定中開啟之前皆為關閉。 | 請參閱網頁工具需要伺服器設定。 |
environment_variable vault 憑證 | 在您開啟輸出閘道（位於您的沙箱與網際網路之間的代理伺服器）之前，伺服器會拒絕它們。 | 請參閱環境變數憑證。若沒有閘道，請透過您自己的工具，為沙箱提供其所需的 CLI 與 API 憑證。 |
| 自訂工具結果 | 伺服器會將自訂工具結果的完整文字傳送給模型。如果結果對模型的 context window（上下文視窗）而言過大，伺服器仍會以 200 回應，隨後工作階段會以 session.error 結束。 | 在傳送之前，先在您的用戶端縮短過長的結果。 |
| MCP 工具結果 | 伺服器會截斷大於其 mcp.max_result_bytes 設定（預設為 100 KiB）的結果。它會告知模型結果已被截斷，其餘部分則會遺失。託管服務也會截斷過長的結果，但對於在雲端沙箱中的工作階段，可以將完整結果儲存至檔案。 | 若要變更此限制，請在設定檔中設定 mcp.max_result_bytes。 |
| 以 URL 傳送的圖片與文件 | 伺服器會接受帶有 url 來源的 image 或 document 區塊，但模型永遠看不到它，而且不會出現錯誤。帶有 file 來源的 image 區塊也是如此。 | 以 base64 傳送資料，文件則可以 text 傳送。 |
rescheduling 工作階段狀態 | 伺服器會重試因暫時性原因而失敗的模型呼叫，並在事件串流上回報每次嘗試，與託管服務的做法相同。工作階段的狀態在兩次嘗試之間維持為 running，因此 statuses[]=rescheduling 篩選條件不會比對到任何工作階段。 | 從事件串流讀取重試資訊。 |
| 工作階段中繼資料（使用模型閘道時） | 如果伺服器的 inference.credentials.assertion.forward_metadata 設定列出了工作階段中繼資料鍵，新增、移除或變更其中任一鍵的更新會傳回 400 錯誤。 | 請在建立工作階段時設定這些鍵。關於此設定，請參閱短期閘道權杖。 |
需要伺服器設定的功能
在您變更伺服器的設定檔之前，這些功能中的每一項都處於關閉狀態，或會拒絕所有主機。
MCP 伺服器需要允許清單項目
伺服器只會連線至主機列於其設定檔中 mcp.allowed_hostnames 下的 MCP 伺服器：
mcp:
allowed_hostnames:
- mcp.example.com主機必須完全相符，不支援萬用字元也不包含子網域，且清單預設為空。在 MCP 伺服器的主機列入清單之前，您的伺服器會拒絕儲存指定該 MCP 伺服器的代理。
位於您私人網路內的 MCP 伺服器不需要 MCP 通道。依照 MCP 連接器的說明，將其 URL 放入代理定義中，並將其主機加入允許清單。URL 須遵守兩項規則：
- 必須使用
https，除非 MCP 伺服器位於 loopback 位址上。 - 如果其主機是只解析為私人或保留位址的名稱，您的伺服器預設會拒絕連線。請選擇符合您情況的修正方式：
| 您的情況 | 修正方式 |
|---|---|
位址位於 10.0.0.0/8、172.16.0.0/12 或 192.168.0.0/16 內，且您控制該名稱的 DNS 記錄 | 保留該名稱，並也將其列於設定檔中的 mcp.private_hostnames 下。 |
| 任何其他情況 | 在 URL 與允許清單中以 IP 位址取代名稱。MCP 伺服器的憑證必須指名該位址。 |
Git 儲存庫需要允許清單項目
在託管服務上，使用自行託管的沙箱的工作階段不能具有 github_repository 資源。在您的伺服器上，工作階段則可以。在您於其設定檔中列出其 Git 主機之前，伺服器會拒絕這些資源。代理只能推送至您列出的分支：
git:
allowed_hostnames:
- github.com
allowed_push_refs:
- refs/heads/agent/請注意以下幾點：
- URL： 主機不必是
github.com，但 URL 必須使用 HTTPS。 - 權杖： 您的用戶端傳送的權杖永遠不會到達沙箱，因為 Git 流量會經過您的伺服器，由伺服器加入權杖。
- 分支： 代理不會得知分支清單，因此請在您的提示中指定分支名稱。
- 強制推送： 伺服器不會拒絕強制推送（force push），因此代理可以覆寫您列出的任何分支。若要拒絕強制推送，請在您的 Git 主機上保護該分支。
存取 GitHub說明了請求內容以及如何輪替權杖。如果複製失敗，工作階段會收到指出原因的 session.error 事件。若要檢查推送，請在您的 Git 主機上尋找該分支。即使是您的主機拒絕的推送，伺服器的日誌也會顯示 ok。
網頁工具需要伺服器設定
web_search 與 web_fetch 工具預設為關閉。若要開啟它們，請將此內容加入伺服器的設定檔：
web_tools:
enabled: true只使用此設定時，會套用每個代理自身的網域清單與內容限制，與託管服務相同。
若要限制每個代理的工具，請設定 web_tools.allowed_domains、web_tools.blocked_domains 或 web_tools.max_content_tokens。這些設定中的每一項也都會開啟這些工具。伺服器會拒絕儲存要求超出這些設定所允許範圍的代理。例如，它會拒絕允許 web_tools.allowed_domains 以外網域的代理，或設定較大內容限制的代理。如果這類代理已經存在，在您更新之前它無法啟動工作階段。
在工具關閉期間，代理會發生什麼情況取決於其工具集中的 web_search 與 web_fetch 項目：
| 工具集包含 | 會發生什麼 |
|---|---|
| 沒有任一工具的項目 | 代理會在沒有這些工具的情況下執行，且不會有任何錯誤提示。 |
只關閉其工具的項目，例如 {"name": "web_fetch", "enabled": false} | 相同。 |
| 讓其工具保持開啟的項目，或設定其網域清單、內容限制或位置的項目 | 伺服器會拒絕儲存該代理或為其啟動工作階段。 |
有哪些網頁工具可用也取決於您的推論供應商。
取決於您推論供應商的差異
某些功能只在伺服器的 inference.provider 設定為特定值時才能運作。下表說明在其他值下會發生什麼情況。其中某些情況不會傳回任何錯誤。
web_search 與 web_fetch 列會在您開啟網頁工具之後適用。在此之前，兩種工具在任何供應商下都無法運作。
| 功能 | 在 inference.provider 為下列值時可運作 | 在其他值下 | 該怎麼做 |
|---|---|---|---|
web_search 工具 | anthropic、vertex、foundry | 伺服器永遠不會將此工具提供給模型。代理仍可儲存與執行，也仍會列出此工具，但模型無法呼叫它。 | 為代理提供可進行搜尋的自訂工具或 MCP 伺服器。 |
web_fetch 工具 | anthropic、foundry | 與 web_search 相同。 | 為代理提供可擷取網頁的自訂工具或 MCP 伺服器。 |
inference_geo | anthropic | 伺服器會拒絕儲存設定此項的代理。 | 從代理中移除 inference_geo。 |
快速模式（speed: "fast"） | 取決於供應商與代理的模型 | 設定此項的代理必須通過兩項檢查。 儲存代理時： 伺服器的模型目錄必須將代理的模型列為接受快速模式的模型。否則，伺服器會拒絕儲存該代理。 每個回合： 如果供應商未針對該模型或部署提供快速模式，該回合會以錯誤結束。 | 從代理中移除 speed。請參閱接受快速模式的模型。 |
在 anthropic 下，伺服器預設會要求使用 Claude API 的伺服器端備援。當安全分類器拒絕某個請求時，另一個 Claude 模型（可能是能力較弱的模型）便可以回答該請求。由 Anthropic 挑選模型，且不會有任何事件回報此變更，但讀取工作階段會顯示該模型的 ID。若要關閉備援，請設定 inference.model_fallback: false。在其他供應商下，此類請求會以拒絕結束該回合。
您供應商的文件會說明哪些模型與區域支援各項功能。自訂工具、MCP 工具以及由您的 worker 執行的工具，在所有供應商下都相同。
接受快速模式的模型
預設情況下，伺服器的模型目錄會將四個模型列為接受快速模式的模型：Claude Opus 5.5、Claude Opus 5、Claude Opus 4.8 與 Claude Opus 4.6。在 Claude Opus 4.6 上，Claude API 會接受該請求，但以標準速度執行。下列 inference.provider 值是例外：
foundry： 目錄只列出 Claude Opus 5.5。- 使用
format: vertex-raw-predict的gateway： 目錄不列出任何模型。 vertex： 目錄不列出任何模型，且沒有任何設定能改變這一點。
若要變更目錄列出的內容，請參閱模型項目。
如果您已在執行自行託管的沙箱
worker 軟體相同，因此您的 worker 可以連線至您的伺服器。執行您自己的 worker列出了進行輪詢之程序的三個值，以及要先變更的項目。透過 webhook 啟動的 worker 在此無法運作。
這個頁面有幫助嗎？