---
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
---
在自行託管環境上的工作階段附加[記憶體儲存區](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`。建議使用區分大小寫的檔案系統，以免僅大小寫不同的記憶路徑發生衝突。
* **可寫入的 `/mnt/memory` 目錄：** 請參閱[準備主機](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-memory#prepare-the-host)。
* **工作項目的密鑰：** 如果由您自己的程式碼啟動 worker，請[轉送工作項目的密鑰](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-workers#forward-the-work-items-secret)給它。
在 [Claude Platform on AWS](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-platform-on-aws) 上，記憶體儲存區無法附加到自行託管環境上的工作階段。
## 準備主機
在啟動 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-workers#run-one-sandbox-per-session)中，沙箱映像需要可寫入的 `/mnt/memory`。您不需要將記憶目錄 bind-mount 到主機，因為 worker 會在沙箱結束前將其內容上傳到儲存區。
### 隔離共用儲存區的工作階段
兩個工作階段無法同時在同一台主機上掛載同一個儲存區，因為兩者都需要相同的路徑。如果您的工作階段附加了相同的儲存區，請在每個檔案系統上只執行一個工作階段。為每個工作階段提供[專屬的沙箱](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-workers#run-one-sandbox-per-session)即可滿足此規則。
## worker 如何處理記憶
當 worker 認領一個其工作階段附加了記憶體儲存區的工作項目時，它會：
1. **將每個儲存區下載到其 `mount_path` (java, php: `mountPath`; csharp, go: `MountPath`)。** 這與雲端工作階段使用的 `/mnt/memory/` 下的目錄相同，且工作階段的系統提示會向代理描述該目錄。例如，名為「User Preferences」的儲存區會放在 `/mnt/memory/user-preferences/`。
2. **向檔案工具開放這些目錄。** 代理使用與在工作目錄中相同的檔案工具來處理記憶。
3. **在工具呼叫後協調變更，** 每個同步間隔最多一次（預設為 15 秒）。儲存區中已變更的記憶會寫入磁碟，而代理變更的檔案會上傳到儲存區。
4. **在工作階段結束時執行最後一次同步。** 它會在最多 30 秒內清空所有仍待處理的上傳，然後移除它所建立的目錄。
Anthropic 端的記憶體儲存區仍是唯一的事實來源。[記憶版本](https://platform.claude.com/docs/zh-TW/managed-agents/memory#audit-memory-changes)、遮蔽，以及在 Console 中檢視或編輯記憶，運作方式都與雲端工作階段相同。代理的記憶讀取與寫入會以一般工具事件的形式出現在[事件串流](https://platform.claude.com/docs/zh-TW/managed-agents/events-and-streaming)中。
由於每個 worker 都是依間隔進行同步，在一個工作階段中寫入的變更，只有在兩者都完成同步後，才會對另一個執行中的工作階段可見。在預設間隔下，這通常遠少於一分鐘。雲端沙箱上的工作階段幾乎可以立即看到彼此的變更。
每個儲存區目錄都包含一個名為 `.anthropic-memory-store` 的標記檔案，用來將該目錄與其儲存區綁定。請保留此檔案：worker 不會同步標記遺失或遭修改的目錄。
被強制終止而非正常停止的 worker 不會執行清理作業，因此未同步的編輯會遺失，且儲存區目錄會殘留下來。請參閱[正常停止 worker](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-operations#stop-workers-gracefully)。
## 設定同步
有兩個 `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 上停用記憶支援。已停用的 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 原本會執行的刪除：
```python Python
worker = EnvironmentWorker(
client,
environment_id=environment_id,
environment_key=environment_key,
workdir="/workspace",
memory_sync_interval=10, # seconds
memory_sync_deletions="log_only",
)
```
```typescript TypeScript
const worker = new EnvironmentWorker({
client,
environmentId,
environmentKey,
workdir: "/workspace",
memorySyncIntervalMs: 10_000,
memorySyncDeletions: "log_only"
});
```
C# SDK 沒有 `EnvironmentWorker`。
```go Go
worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
EnvironmentID: environmentID,
EnvironmentKey: environmentKey,
Workdir: "/workspace",
MemorySyncInterval: 10 * time.Second,
MemorySyncDeletions: environments.MemorySyncDeletionsLogOnly,
})
```
Java SDK 沒有 `EnvironmentWorker`。
PHP SDK 沒有 `EnvironmentWorker`。
Ruby SDK 沒有 `EnvironmentWorker`。
## 唯讀儲存區與衝突
對於以 `access: "read_only"` 附加的儲存區，`write` 和 `edit` 工具會拒絕變更其目錄內的檔案。worker 永遠不會從中上傳任何內容。
透過 `bash`，或透過您從沙箱提供的自訂工具或 MCP 伺服器所做的變更，不會在本機被阻擋。這些變更永遠不會同步到儲存區，且該記憶的下一次遠端變更會覆寫它們。如果本機副本本身在工作階段期間必須保持不變：
* 為該代理停用 `bash` 工具，且不要提供任何會寫入沙箱檔案系統的自訂工具。
* 不要以唯讀方式掛載儲存區路徑。worker 本身必須建立該目錄，並將下載的記憶寫入其中。
衝突會以儲存區為準來解決。假設代理變更了一個記憶檔案，而該檔案自工作階段上次同步以來在儲存區中也已變更。在下一次同步時，worker 會保留儲存區的版本，用它覆寫本機檔案，並記錄一則警告。`write` 和 `edit` 工具本身會成功，且不會有錯誤傳達給代理。如果代理的變更仍然適用，它可以在同步後重新讀取該檔案並再次進行變更。
## 疑難排解
請參閱[記憶體儲存區無法掛載](https://platform.claude.com/docs/zh-TW/managed-agents/self-hosted-sandboxes-operations#memory-stores-fail-to-mount)，以了解 worker 的記錄訊息及其修正方式。