---
title: 開始使用自行託管的 Claude Managed Agents
url: https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/quickstart
description: 使用 Docker Compose 在單一機器上啟動自行託管的 Claude Managed Agents，並在沙箱容器中執行第一個工作階段。
---

<Note>
  若要申請自行託管的 Claude Managed Agents 存取權，請聯絡您的 Anthropic 客戶團隊。
</Note>

在本快速入門中，您會使用 Docker Compose 在單一機器上啟動自行託管的 Claude Managed Agents。Compose 堆疊包含伺服器、其 PostgreSQL 資料庫，以及一組 worker，這些 worker 會在各自獨立的沙箱容器中執行每個工作階段。接著，您會從終端機與代理對話，並確認其工具呼叫是在沙箱容器中執行的。之後，您可以在[您伺服器上的主控台](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/console)中開啟該工作階段。

<Warning>
  Compose 堆疊僅供開發使用，不適用於正式環境。它以純 HTTP 提供服務，且預設只會在 Docker 主機的回送位址 `127.0.0.1` 上公開連接埠 8400。在 28.3.3 之前的某些 Docker Engine 版本下，主機區域網路上的機器也能連線到該連接埠。代理工具會在該主機上的容器中執行，因此請使用一台不存放任何需要保護之內容的機器。
</Warning>

在正式環境中，Anthropic 建議使用該版本的兩個 Helm chart。請參閱[在 Kubernetes 上部署](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/kubernetes)。

讓 Claude Code 為您執行本快速入門

```text
請依照 https://platform.claude.com/docs/en/managed-agents/self-hosted/quickstart.md 在這台機器上設定自行託管的 Claude Managed Agents。我已經下載了版本封存檔。
```

如果您是代替某人執行這些步驟的代理：

* **版本封存檔：**&#x8A62;問對方封存檔的位置。只有對方能下載它。
* **Claude API 金鑰：**&#x8ACB;對方自行編輯 `.env`。不要索取金鑰，也不要印出 `.env`。
* **變數：**&#x5982;果您的 shell 不會在指令之間保留變數，請在每個 `ant` 指令中重新設定 `ANTHROPIC_BASE_URL` 與 `ANTHROPIC_API_KEY`。若沒有設定，`ant` 會呼叫託管服務。
* **Compose：**&#x5728;每個 `docker compose` 指令前面加上 `env -u ANTHROPIC_BASE_URL -u ANTHROPIC_API_KEY -u ANTHROPIC_AUTH_TOKEN`，讓您 shell 中的值不會傳到伺服器。
* **聊天：**`ant beta:sessions connect` 需要互動式終端機。若沒有互動式終端機，請使用 `ant beta:sessions:events send` 傳送訊息，並使用 `ant beta:sessions:events list` 讀取回覆。[傳送事件](https://platform.claude.com/docs/zh-TW/managed-agents/events-and-streaming#send-events)與[列出過去的事件](https://platform.claude.com/docs/zh-TW/managed-agents/events-and-streaming#list-past-events)中有範例。
* **主控台：**&#x53EA;有在對方要求時，才執行「在您的伺服器上試用主控台」一節。如果您的 shell 不會在指令之間保留變數，從該節開始，也請在每個 `docker compose` 指令前面加上 `COMPOSE_FILE=docker-compose.yml:docker-compose.oidc.yml`。

## 先決條件

* **版本封存檔：**&#x82E5;要申請下載的存取權，請聯絡您的 Anthropic 帳戶團隊。
* **Claude API 金鑰：**&#x4F3A;服器會使用它來進行模型呼叫。請在 [Claude Console](https://platform.claude.com/settings/keys) 中建立一個。
* **Docker：** [最新版本的 Docker Engine](https://docs.docker.com/engine/install/)，搭配 Compose 外掛程式（`docker compose`，而非較舊的 `docker-compose`）。
* **至少具備兩顆 CPU 的主機：**&#x78;86-64 或 Arm。在較小的主機上，請在建立 `.env` 時將 `CMA_SANDBOX_CPUS` 設為其 CPU 數量。
* **首次啟動時的網路存取：**&#x9996;次建置會從 Docker Hub、Alpine 套件儲存庫以及 GitHub releases 拉取內容。
* **工具：**&#x5728;您執行 Docker 的機器上，您需要 `openssl` 與 [`ant` CLI](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/cli/quickstart#installation)。

## 啟動堆疊

<Steps>
  <Step title="解壓縮封存檔">
    解壓縮封存檔，並在其 `compose` 目錄中作業。在指令中，將 `<archive>` 替換為您封存檔的名稱，不含 `.tar.gz`。

    ```bash
    tar -xzf <archive>.tar.gz && cd <archive>/compose
    ```

    如果您的 umask 比 `022` 更嚴格，二進位檔會失去其他使用者的執行權限，伺服器容器便無法啟動它們。在這種情況下，請將其設為 `022`，然後重新解壓縮封存檔。
  </Step>

  <Step title="建立 .env 檔案">
    Compose 會從 `docker-compose.yml` 旁的 `.env` 檔案讀取堆疊的密鑰。建立檔案：

    ```bash
    cat > .env <<EOF
    CMA_PG_PASSWORD=$(openssl rand -hex 32)
    ANTHROPIC_API_KEY=sk-ant-...
    CMA_SERVER__API_KEY=$(openssl rand -hex 32)
    CMA_STORE__CREDENTIALS_ENCRYPTION_KEY=$(openssl rand -base64 32)
    EOF
    chmod 600 .env
    ```

    請在編輯器中開啟 `.env`，並將 `sk-ant-...` 替換為您的 Claude API 金鑰。此區塊會產生其餘內容：資料庫密碼、您的應用程式所傳送的伺服器 API 金鑰，以及用於加密伺服器所儲存之密鑰的金鑰。
  </Step>

  <Step title="啟動容器">
    建置並啟動堆疊，然後追蹤伺服器的記錄：

    ```bash
    docker compose up --build -d
    docker compose logs -f cma-server
    ```

    當記錄中出現含有 `msg="cma-server listening"` 的一行時，按 Ctrl+C 停止追蹤記錄。
  </Step>

  <Step title="確認伺服器已就緒">
    ```bash
    curl -s http://127.0.0.1:8400/cma-server/readyz
    ```

    已就緒的伺服器會回應 `"status":"ready"`。剛啟動時，在首次檢查執行期間，它可能會有幾秒鐘回應 `"status":"degraded"`。如果持續為 `degraded` 或回應 `"status":"not_ready"`，請參閱[疑難排解](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/quickstart#troubleshooting)。
  </Step>
</Steps>

## 執行您的第一個工作階段

使用 `ant` CLI 建立一個代理，並從您的終端機與它對話。

<Steps>
  <Step title="將 CLI 指向您的伺服器">
    在同一個目錄中開啟第二個終端機，並保留它供 `ant` 使用。以下指令會將 `ANTHROPIC_API_KEY` 設為您的伺服器 API 金鑰，而非您的 Claude API 金鑰，如[在自行託管的伺服器上呼叫 API](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/call-the-api) 所說明：

    ```bash
    export ANTHROPIC_BASE_URL=http://127.0.0.1:8400
    export ANTHROPIC_API_KEY=$(grep '^CMA_SERVER__API_KEY=' .env | cut -d= -f2)
    ```

    請在第一個終端機中執行 `docker compose` 指令。如果您在這個終端機中執行 `docker compose up`，Compose 會將這些變數傳遞給伺服器，伺服器便會呼叫自己，而不是 Claude API。
  </Step>

  <Step title="建立代理">
    將指令後方的檔案儲存為 `quickstart-agent.md`，然後執行該指令。此檔案為代理提供內建工具，並讓代理無需先詢問您即可執行這些工具。

    <CodeGroup>
      <CodeGroupItem>
        ```bash CLI
        ant apply --yes quickstart-agent.md
        ```

        <File filename="quickstart-agent.md">
          ```markdown
          ---
          name: Quickstart agent
          model: claude-opus-5-5
          tools:
            - type: agent_toolset_20260401
          ---

          You are a helpful assistant.
          ```
        </File>
      </CodeGroupItem>
    </CodeGroup>

    此指令會先印出一則警告，指出它 `could not determine the organization and workspace`，並附帶 `404` 錯誤，然後才建立代理。在您自己的伺服器上，這是預期的行為。
  </Step>

  <Step title="啟動工作階段">
    這些指令會找到代理與堆疊的環境、啟動工作階段，並將工作階段的 ID 保存在 `SESSION_ID` 中。堆疊將其環境命名為 `compose-sandbox`。

    ```bash
    AGENT_ID=$(ant beta:agents list --format raw \
      --transform 'data.#(name=="Quickstart agent").id' --raw-output)
    ENVIRONMENT_ID=$(ant beta:environments list --format raw \
      --transform 'data.#(name=="compose-sandbox").id' --raw-output)
    SESSION_ID=$(ant beta:sessions create --agent "$AGENT_ID" \
      --environment-id "$ENVIRONMENT_ID" --transform id --raw-output)
    ```
  </Step>

  <Step title="要求代理執行指令">
    將您的終端機連線到工作階段：

    ```bash
    ant beta:sessions connect "$SESSION_ID"
    ```

    此指令會開啟工作階段的[聊天檢視](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/cli/sessions-connect)。傳送此訊息：

    ```text wrap
    Run `hostname` with the bash tool and tell me the output.
    ```

    代理會回覆一個以 `cma-sandbox-` 開頭的主機名稱。那是執行該指令的沙箱容器名稱，這確認了工具是在沙箱中執行，而非在您的機器上。
  </Step>

  <Step title="找到沙箱容器">
    保持聊天開啟。在第一個終端機中，列出沙箱容器：

    ```bash
    docker ps --filter label=cma-server.sandbox
    ```

    清單會顯示代理所回報的容器。容器會在一個回合結束後約一分鐘結束，而工作階段的下一則訊息會啟動一個新容器。如果清單是空的，請要求代理再次執行 `hostname`，並在它回覆期間再次列出容器。

    若要離開聊天，請在其終端機中按下 Ctrl+C。工作階段會持續執行。
  </Step>
</Steps>

## 在您的伺服器上試用主控台

本節為選用。主控台需要單一登入。若要試用，請搭配版本中的模擬登入提供者重新啟動堆疊。您機器上的連接埠 8080 必須未被占用。

<Warning>
  模擬提供者僅限搭配可拋棄的資料使用。它會將管理員的權杖提供給任何能連線到它的對象。在 Docker Desktop 上，這包括沙箱容器。在 28.3.3 之前的某些 Docker Engine 版本下，這包括您網路上的機器。
</Warning>

<Steps>
  <Step title="搭配模擬登入提供者重新啟動堆疊">
    在第一個終端機中執行這些指令：

    ```bash
    export COMPOSE_FILE=docker-compose.yml:docker-compose.oidc.yml
    docker compose up --build -d
    ```

    `export` 這一行僅適用於第一個終端機，因此請在您為 `docker compose` 開啟的任何新終端機中再次執行它。若要變更此堆疊中伺服器的設定，請編輯 `compose.config.oidc.yaml`，而非 `compose.config.yaml`，然後執行 `docker compose restart cma-server`。
  </Step>

  <Step title="開啟工作階段">
    在同一台機器上的瀏覽器中開啟 `http://127.0.0.1:8400/`，按一下 **Continue with SSO**，然後選取示範管理員 **alice**。在側邊欄中選取 **Sessions**，然後選取該工作階段。

    頁面會隨著代理的工作而更新，您也可以從該頁面傳送訊息給代理。
  </Step>
</Steps>

若也要在主控台中建立代理並啟動工作階段，請參閱[從主控台執行代理](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/console#run-an-agent-from-the-console)。

## 停止堆疊

在第一個終端機中，執行此指令：

```bash
docker compose down --remove-orphans
```

此指令會刪除容器並保留資料庫。若也要刪除資料庫，以及其中所有代理、工作階段與工作階段歷程記錄，請執行 `docker compose down --remove-orphans -v`。

## 疑難排解

* **您的封存檔沒有 `compose` 目錄：**&#x8A72;封存檔包含較早的版本，本頁的指令與其不符。請向您的 Anthropic 帳戶團隊索取目前的版本。若要將執行中的部署移至目前的版本，請參閱[升級自行託管的 Claude Managed Agents](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/upgrade)。

* **伺服器始終無法啟動：**&#x57F7;行 `docker compose logs migrate`。一次性的 `migrate` 容器會建立資料庫資料表。它必須以狀態 `0` 結束，伺服器才會啟動。

* **就緒檢查持續為 `degraded`，或每個回合都失敗：**&#x5982;果您在 `ANTHROPIC_BASE_URL` 為 `http://127.0.0.1:8400` 的終端機中執行了 `docker compose up`，伺服器會呼叫自己，而不是 Claude API。請在未設定該變數的第一個終端機中再次執行 `docker compose up -d`。否則，伺服器記錄會顯示失敗的項目。若要閱讀記錄，請再次執行 `docker compose logs -f cma-server`。

* **就緒檢查回應 `not_ready`：**&#x5728;回應中，找出狀態為 `failed` 的檢查：

  * **`upstream`：**&#x43;laude API 拒絕了您的 Claude API 金鑰。請更正 `.env` 中的 `ANTHROPIC_API_KEY`，然後在第一個終端機中再次執行 `docker compose up -d`。如果您的 shell 也設定了 `ANTHROPIC_API_KEY`，Compose 會使用 shell 的值，因此請先執行 `unset ANTHROPIC_API_KEY`。
  * **`database`：**&#x8CC7;料庫拒絕了伺服器的登入（例如因為密碼錯誤），或是與資料庫的開啟連線中斷。若要查看是哪一種，請再次執行 `docker compose logs -f cma-server`。

* **代理有回覆，但其工具呼叫始終未完成：**&#x6C92;有 worker 在輪詢該環境。請使用 `docker compose logs sandbox` 檢查 worker 的記錄。無法連線至 Docker daemon 通訊端的 worker 會結束，並顯示提及 `CMA_DOCKER_SOCKET` 的訊息。請在 `.env` 中將該變數設為您 daemon 的通訊端路徑，然後在第一個終端機中再次執行 `docker compose up -d`。

* **worker 正在執行，但工具呼叫仍始終未完成：**&#x5806;疊會啟動 10 個 worker，每個 worker 一次執行一個工作階段的容器。工作階段在建立時就會占用一個空閒的 worker，而從未收到訊息的工作階段會保留其 worker 最多一小時。當 10 個都被占用時，任何其他工作階段的工具呼叫都會等待 worker。如果「找到沙箱容器」步驟中的 `docker ps` 指令列出 10 個容器，請封存您未使用的工作階段：

  1. 在第一個終端機中，執行 `docker ps --filter label=cma-server.sandbox --format '{{.Label "cma-server.session"}}'`。它會印出每個容器背後的工作階段 ID。等待中的工作階段還沒有容器，因此不在清單中。
  2. 在第二個終端機中，按 Ctrl+C 離開聊天，並針對每個列出且您未使用的工作階段執行 `ant beta:sessions archive --session-id <session-id>`。
  3. 再次執行 `ant beta:sessions connect "$SESSION_ID"`。當有 worker 接手其工作階段時，工具呼叫就會完成。

## 後續步驟

<CardGroup cols={2}>
  <Card title="呼叫 API" icon="code-brackets" href="https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/call-the-api">
    將 SDK 與 `ant` CLI 指向您的伺服器。
  </Card>

  <Card title="與託管服務的差異" icon="arrows-left-right" href="https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/differences">
    查看哪些功能的行為不同或無法使用。
  </Card>

  <Card title="您伺服器上的主控台" icon="browser" href="https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted/console">
    設定登入，並在瀏覽器中建立代理與執行工作階段。
  </Card>
</CardGroup>