---
title: 自行託管沙箱中的記憶體儲存區
url: https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-memory
description: 將記憶體儲存區附加到在自行託管沙箱中執行的 Claude Managed Agents 工作階段：準備主機、設定同步，以及處理唯讀儲存區與衝突。
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
  zdr:
    eligibility: not-eligible
    note: 不具 ZDR 適用資格，自行託管的 Managed Agents 除外。工作階段是具狀態的資源；對話記錄會保留至您將其刪除為止。
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: beta
---

在自行託管環境上的工作階段附加[記憶體儲存區](https://platform.claude.com/docs/zh-TW/managed-agents/memory)的方式，與雲端環境上的工作階段完全相同。建立工作階段時，請將它們列在 `resources` (csharp, go: `Resources`) 中，如[將記憶體儲存區附加到工作階段](https://platform.claude.com/docs/zh-TW/managed-agents/memory#attach-a-memory-store-to-a-session)所示。一個工作階段最多可接受 8 個記憶體儲存區。

差別在於由誰將儲存區具體化。在自行託管環境上，是由您的 worker（而非 Anthropic 的基礎架構）將每個儲存區下載到沙箱中，並將代理的變更同步回去。

## 需求

* **可掛載記憶體儲存區的 worker：** 使用 `ant` CLI 1.33.0 或更新版本，或 Python、TypeScript 或 Go SDK 中的 `EnvironmentWorker`。
* **POSIX 檔案系統：** 不支援 Windows 主機，因為 worker 在開啟記憶體檔案時需要 `O_NOFOLLOW`。Anthropic 建議使用區分大小寫的檔案系統，以免僅大小寫不同的記憶體路徑發生衝突。macOS 磁碟區預設不區分大小寫，因此這類路徑在該系統上會發生衝突。
* **可寫入的 `/mnt/memory` 目錄：** 請參閱[準備主機](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-memory#prepare-the-host)。若使用 macOS，請參閱[準備 macOS 主機](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-memory#prepare-a-macos-host)。
* **工作項目的密鑰：** 如果由您自己的程式碼啟動 worker，請[轉送工作項目的密鑰](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-per-session#forward-the-work-items-secret)給它。

## 準備主機

若使用 macOS，請跳過下一個命令，改為依照[準備 macOS 主機](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-memory#prepare-a-macos-host)操作。

在啟動 worker 之前，請建立父目錄，並讓執行 worker 的使用者可以寫入該目錄：

```bash
sudo mkdir -p /mnt/memory && sudo chown "$USER" /mnt/memory
```

請勿自行建立任何儲存區的目錄。worker 會在認領工作階段時建立每個儲存區的 `mount_path` (java, php: `mountPath`; csharp, go: `MountPath`) 目錄（例如 `/mnt/memory/user-preferences`），並在處理完該工作階段時將其移除。如果該路徑已存在任何內容，即使只是空目錄，worker 也會使工作項目失敗。

在[每個工作階段一個沙箱的模式](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-per-session)中，沙箱映像需要可寫入的 `/mnt/memory`。您不需要將記憶目錄 bind-mount 到主機，因為儲存區保有每個記憶的持久副本。

### 準備 macOS 主機

在 macOS 上，根磁碟區為唯讀，因此 `mkdir` 無法建立 `/mnt`。請改為在可寫入的資料磁碟區上建立 `/System/Volumes/Data/mnt/memory`。接著在 `/etc/synthetic.conf` 中新增一行，讓 macOS 將 `/mnt` 建立為指向 `/System/Volumes/Data/mnt` 的「symbolic link」（符號連結）。這些步驟需要管理員權限。

若未完成此設定，worker 將無法建立儲存區的目錄，因此會使工作項目失敗。工作階段接著會保持閒置，且不會產生任何錯誤事件。請參閱[記憶體儲存區無法掛載或同步](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-operations#memory-stores-fail-to-mount)。

<Steps>
  <Step title="在資料磁碟區上建立目錄">
    建立 `memory` 目錄，並將 worker 的使用者設為其擁有者。`$USER` 是您自己的使用者名稱。如果 worker 以其他使用者身分執行，請將 `"$USER"` 替換為該使用者的名稱。

    ```bash
    sudo mkdir -p /System/Volumes/Data/mnt/memory && sudo chown "$USER" /System/Volumes/Data/mnt/memory
    ```

    此位置只是其中一個選項。如果您使用其他位置，請變更 `synthetic.conf` 該行中的路徑以配合。Anthropic 僅測試過 `/System/Volumes/Data/mnt`。
  </Step>

  <Step title="在 synthetic.conf 中新增一行">
    執行 `cat -et /etc/synthetic.conf`，它會將每個定位字元顯示為 `^I`，並將每個行尾顯示為 `$`。

    * 如果有一行為 `mnt^ISystem/Volumes/Data/mnt$`，表示此步驟已完成。請前往下一個步驟。
    * 如果有其他行以 `mnt` 開頭，請停止。這台 Mac 上已有其他項目定義了 `/mnt`。
    * 如果最後一行不是以 `$` 結尾，請執行 `echo | sudo tee -a /etc/synthetic.conf` 來結束該行。接著新增該行。
    * 如果沒有輸出任何內容或回報 `No such file or directory`，請新增該行。若檔案不存在，下列命令會建立該檔案。
    * 否則，請新增該行。

    若要新增該行，請執行此命令。此命令只需執行一次，因為每次執行都會再附加一行。

    ```bash
    printf 'mnt\tSystem/Volumes/Data/mnt\n' | sudo tee -a /etc/synthetic.conf
    ```

    此命令會輸出它新增的行。該行將名稱 `mnt` 對應到包含 `memory` 的目錄。檔案中兩個欄位之間需要一個定位字元，由 `\t` 寫入。
  </Step>

  <Step title="建立連結">
    使用 `-t` 選項執行 `apfs.util`。它會根據您新增的行建立連結，無需重新啟動。

    ```bash
    sudo /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -t
    ```
  </Step>

  <Step title="檢查結果">
    列出 `/mnt` 與 `/mnt/memory`。

    ```bash
    ls -ld /mnt /mnt/memory
    ```

    第一行以 `/mnt -> System/Volumes/Data/mnt` 結尾。第二行顯示 worker 的使用者為 `/mnt/memory` 的擁有者。您現在可以啟動 worker。
  </Step>
</Steps>

Anthropic 已在 macOS 26.7.1 上使用 `ant` CLI worker 測試過此設定。

### 隔離共用儲存區的工作階段

兩個工作階段無法在同一個檔案系統上同時掛載同一個儲存區，因為兩者都需要相同的路徑。若要並行執行共用同一儲存區的工作階段，請為每個工作階段提供各自的檔案系統。如果您為每個工作階段使用一個沙箱，每個工作階段就會自動擁有各自的檔案系統。請參閱[每個工作階段執行一個沙箱](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-per-session)。一台主機可以執行許多這類沙箱。

## worker 如何處理記憶

當 worker 認領一個其工作階段附加了記憶體儲存區的工作項目時，它會：

1. **將每個儲存區下載到其 `mount_path` (java, php: `mountPath`; csharp, go: `MountPath`)。** 這與雲端工作階段使用的 `/mnt/memory/` 下的目錄相同，且工作階段的系統提示會向代理描述該目錄。例如，名為「User Preferences」的儲存區會放在 `/mnt/memory/user-preferences/`。
2. **向檔案工具開放這些目錄。** 代理使用與在工作目錄中相同的檔案工具來處理記憶。
3. **在工具呼叫後進行同步。** 如果自上次同步以來已經過[同步間隔](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-memory#sync-interval)（預設為 15 秒），worker 會在工具呼叫後進行同步。每次同步都會將儲存區中已變更的記憶寫入磁碟，並上傳代理變更的檔案。
4. **在工作階段結束或閒置達到 worker 的「idle limit」（閒置限制）時執行最後一次同步。** 最後一次同步最多可能需要 60 秒。屆時仍未上傳的變更會遺失。接著 worker 會移除它所建立的目錄。

閒置限制預設為 60 秒。[worker 何時處理完工作階段](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-reference#when-the-worker-finishes-with-a-session)說明了此限制涵蓋的範圍以及如何變更。

代理的 `write` 和 `edit` 工具只會變更本機副本，而 worker 會在下一次同步時上傳這些變更。`/mnt/memory/` 下、儲存區目錄之外的路徑並非「scratch space」（暫存空間）。worker 的檔案工具會拒絕寫入這些路徑，而 shell 命令寫入該處的任何內容永遠不會同步到儲存區。

[記憶體版本](https://platform.claude.com/docs/zh-TW/managed-agents/memory#audit-memory-changes)、遮蔽處理，以及在 Claude Console 中檢視或編輯記憶體，其運作方式都與雲端工作階段相同。代理對記憶體的讀取與寫入會以一般工具事件的形式出現在[事件串流](https://platform.claude.com/docs/zh-TW/managed-agents/events-and-streaming)中。

每個儲存區目錄都包含一個名為 `.anthropic-memory-store` 的標記檔案，用來將該目錄與其儲存區綁定。請保留此檔案。如果標記遺失或遭修改，且該目錄中仍有檔案，worker 不會同步該目錄。在處理完工作階段時，它也不會移除該目錄。

<Warning>
  如果您在工作階段期間正常停止 worker，或[停止該工作階段的工作項目](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-operations#stop-a-session-gracefully)，worker 仍會上傳新增與變更的檔案。它也會移除儲存區目錄。它不會送出任何刪除，因此代理刪除的記憶會保留在儲存區中，除非先前的同步已將其從儲存區中刪除。被強制終止而非正常停止的 worker 不會執行清理作業，因此未同步的編輯會遺失，且儲存區目錄會殘留下來。請參閱[正常停止 worker](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-operations#stop-workers-gracefully)。
</Warning>

## 設定同步

有兩個 `EnvironmentWorker` 選項控制記憶行為。請在您建構 worker 的任何地方設定它們，包括在 webhook 處理常式中。`ant` CLI worker 一律使用預設值。

### 同步間隔

`memory_sync_interval` (typescript: `memorySyncIntervalMs`; go: `MemorySyncInterval`) 設定工作階段執行期間，兩次同步之間的最短時間。

| 設定 | 值 |
| ----- | ----- |
| 預設 | 15 秒 |
| 最小值 | 5 秒 |
| 範例（10 秒） | `10` (typescript: `10_000`; go: `10 * time.Second`) |
| 停用記憶支援 | `None` (typescript: `null`; go: `-1`) |

worker 不會依計時器進行同步。它會在每次呼叫在您沙箱中執行的工具（例如 `bash`、`read` 或自訂工具）之後檢查間隔。該呼叫不必涉及記憶。若沒有工具呼叫，在[最後一次同步](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-memory#how-the-worker-handles-memory)之前都不會進行任何同步。一個工作階段中的變更，只有在兩者都完成同步後才會傳達到另一個執行中的工作階段，因此等待時間沒有固定長度。

較短的間隔可縮小其他工作階段看到過時記憶的時間範圍，代價是更多的記憶體儲存區請求。

僅在其工作階段未附加任何記憶體儲存區的 worker 上停用記憶支援。已停用的 worker 既不會下載也不會同步儲存區，因此附加了儲存區的工作階段會在沒有這些儲存區的情況下執行，即使其系統提示仍會描述它們。

在啟用記憶支援時，若某個附加了儲存區的工作階段的工作項目送達時沒有 `secret` (csharp, go: `Secret`)，該工作項目會失敗，而不會在沒有記憶的情況下執行。請參閱[記憶體儲存區無法掛載或同步](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-operations#memory-stores-fail-to-mount)。

### 刪除

`memory_sync_deletions` (typescript: `memorySyncDeletions`; go: `MemorySyncDeletions`) 設定代理在本機刪除的檔案是否也會從儲存區中刪除。上傳與下載不受影響。

| 值 | 行為 |
| ----- | ----- |
| `"enabled"` (go: `environments.MemorySyncDeletionsEnabled`)（預設） | 在後續同步確認檔案仍不存在後，從儲存區中刪除該記憶。 |
| `"log_only"` (go: `environments.MemorySyncDeletionsLogOnly`) | 執行相同的檢查，但只記錄原本會刪除的內容。在您信任啟用模式之前，可用它來觀察您的 worker 會刪除哪些內容。 |
| `"disabled"` (go: `environments.MemorySyncDeletionsDisabled`) | 永不從儲存區中刪除。 |

例如，若要最多每 10 秒同步一次，且只記錄 worker 原本會執行的刪除，請使用下列範例。此範例使用 `/workspace` 作為工作目錄，該目錄必須在 worker 啟動前存在。[執行常駐 worker](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-workers#run-an-always-on-worker) 說明如何建立該目錄，以及在 macOS 上應使用什麼。

<CodeGroup exclude="shell, csharp, java, php, ruby">
  <CodeGroupItem language="cURL">
    worker 是長時間執行的處理程序，而不是單一的 HTTP 請求。若要變更同步設定，請使用 Python、TypeScript 或 Go SDK 中的 `EnvironmentWorker`。
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    `ant` CLI worker 一律使用預設的同步設定。若要變更這些設定，請使用 Python、TypeScript 或 Go SDK 中的 `EnvironmentWorker`。
  </CodeGroupItem>

  ```python Python
  import asyncio
  import contextlib
  import os
  import signal
  from anthropic import AsyncAnthropic
  from anthropic.lib.environments import EnvironmentWorker


  async def main() -> None:
      environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
      environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
      async with AsyncAnthropic(auth_token=environment_key) as client:
          worker = EnvironmentWorker(
              client,
              environment_id=environment_id,
              environment_key=environment_key,
              workdir="/workspace",
              memory_sync_interval=10,  # seconds
              memory_sync_deletions="log_only",
          )
          task = asyncio.create_task(worker.run())
          loop = asyncio.get_running_loop()
          for signum in (signal.SIGINT, signal.SIGTERM):
              loop.add_signal_handler(signum, task.cancel)
          with contextlib.suppress(asyncio.CancelledError):
              await task


  asyncio.run(main())
  ```

  ```typescript TypeScript
  import Anthropic from "@anthropic-ai/sdk";
  import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments";

  const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
  const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
  const client = new Anthropic({ authToken: environmentKey });
  const controller = new AbortController();
  process.once("SIGINT", () => controller.abort());
  process.once("SIGTERM", () => controller.abort());

  const worker = new EnvironmentWorker({
    client,
    environmentId,
    environmentKey,
    workdir: "/workspace",
    signal: controller.signal,
    memorySyncIntervalMs: 10_000,
    memorySyncDeletions: "log_only"
  });
  await worker.run();
  ```

  <CodeGroupItem language="C#">
    C# SDK 沒有 `EnvironmentWorker`。
  </CodeGroupItem>

  ```go Go
  package main

  import (
  	"context"
  	"log"
  	"os"
  	"os/signal"
  	"syscall"
  	"time"

  	"github.com/anthropics/anthropic-sdk-go/v2"
  	"github.com/anthropics/anthropic-sdk-go/v2/lib/environments"
  	"github.com/anthropics/anthropic-sdk-go/v2/option"
  )

  func main() {
  	environmentKey := os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")
  	environmentID := os.Getenv("ANTHROPIC_ENVIRONMENT_ID")

  	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
  	defer stop()

  	client := anthropic.NewClient(option.WithAuthToken(environmentKey))

  	worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
  		EnvironmentID:       environmentID,
  		EnvironmentKey:      environmentKey,
  		Workdir:             "/workspace",
  		MemorySyncInterval:  10 * time.Second,
  		MemorySyncDeletions: environments.MemorySyncDeletionsLogOnly,
  	})
  	if err := worker.Run(ctx); err != nil {
  		log.Fatalf("worker: %v", err)
  	}
  }
  ```

  <CodeGroupItem language="Java">
    Java SDK 沒有 `EnvironmentWorker`。
  </CodeGroupItem>

  <CodeGroupItem language="PHP">
    PHP SDK 沒有 `EnvironmentWorker`。
  </CodeGroupItem>

  <CodeGroupItem language="Ruby">
    Ruby SDK 沒有 `EnvironmentWorker`。
  </CodeGroupItem>
</CodeGroup>

## 唯讀儲存區與衝突

### 唯讀儲存區

對於以 `access: "read_only"` 附加的儲存區，`write` 和 `edit` 工具會拒絕變更其目錄內的檔案。worker 永遠不會從中上傳任何內容。

透過 `bash`，或透過您從沙箱提供的自訂工具或 MCP 伺服器所做的變更，不會在本機被阻擋。這些變更永遠不會到達儲存區。已變更的檔案會維持變更後的狀態，直到發生下列其中一種情況：

* **該記憶在儲存區中有了新版本。** worker 的下一次同步會以該版本覆寫檔案。
* **worker 處理完工作階段。** 它會移除該目錄。

若也要讓本機副本保持不變，請為該代理停用 `bash` 工具。此外，不要提供任何會寫入沙箱檔案系統的自訂工具或 MCP 伺服器。不要在儲存區的路徑掛載唯讀磁碟區。掛載會在該路徑放置一個目錄，而如果該處已存在任何內容，worker 會使工作項目失敗。

### 衝突

「conflict」（衝突）是指自上一次同步以來，在儲存區與沙箱中都已變更的記憶。刪除也算是一種變更。對於以 `access: "read_write"` 附加的儲存區，worker 會在下一次同步時解決衝突：

| 在儲存區中 | 在沙箱中 | 結果 |
| ----- | ----- | ----- |
| 已變更 | 已變更 | 儲存區的版本會覆寫該檔案。 |
| 已變更 | 已刪除 | worker 會將儲存區的版本寫回沙箱。 |
| 已刪除 | 已變更 | worker 會根據該檔案重新建立記憶。 |

在前兩列中，代理的變更或刪除會遺失，即使工具呼叫已成功。不會有任何訊息告知代理，而遺失的唯一跡象是 worker 日誌中的一則警告。在最後一列中，儲存區中的刪除會被復原。

## 疑難排解

請參閱[記憶體儲存區無法掛載或同步](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-operations#memory-stores-fail-to-mount)，以了解 worker 日誌訊息及其修正方式。

## 可用性

自行託管沙箱中的記憶體儲存區在所有模型上處於 Beta 階段。

### API 支援

#### [Managed Agents](https://platform.claude.com/docs/zh-TW/managed-agents/overview)

* 可用性：可用

| 狀態 | 雲端平台 |
| ----- | ----- |
| Beta | Claude API |

### 必要的 Beta 標頭

[Beta 標頭概覽](https://platform.claude.com/docs/zh-TW/api/beta-headers)

Beta 標頭可讓您在實驗性功能與新模型能力成為標準 API 的一部分之前搶先存取。

* `managed-agents-2026-04-01`

### 資料處理

[資料處理概覽](https://platform.claude.com/docs/zh-TW/manage-claude/api-and-data-retention#feature-eligibility)

| 項目 | 零資料保留 | HIPAA |
| ----- | ----- | ----- |
| 狀態 | 不符合資格 | 不符合資格 |
| 詳細資訊 | 不具 ZDR 適用資格，自行託管的 Managed Agents 除外。工作階段是具狀態的資源；對話記錄會保留至您將其刪除為止。 [深入了解](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-data-and-access#how-long-data-is-kept) | 不具 HIPAA 適用資格。適用於所有 Managed Agents 子功能。 |

適用端點：

* `/v1/agents`
* `/v1/sessions`
* `/v1/environments`
