前言

本文檔從運維工程師視角出發，系統闡述 OpenClaw Workspace 的生產環境部署、配置管理、故障診斷、安全加固和自動化運維實踐。所有內容基于 OpenClaw 官方文檔和實際生產經驗，面向具備基礎操作能力的運維人員。

本文與《OpenClaw 進階配置與自動化運維實戰手冊》形成互補：前者側重 Gateway、渠道和 Cron 等系統級配置，后者聚焦 Workspace 這一 Agent 運行環境的規劃與運維。

第一章：Workspace 概念再定義——運維視角

1.1 配置文件體系與內容文件體系的分離

OpenClaw 的 Workspace 本質上是將 Agent 的運行環境拆分為兩個正交體系：

配置文件體系（靜態定義）

openclaw.json：~/.openclaw/openclaw.json，系統憲法，定義 Gateway 行為和 Agent 運行時參數

AGENTS.md：工作手冊，定義任務執行流程、安全邊界、輸出規范

SOUL.md：性格配置，定義 Agent 響應風格和交互模式

IDENTITY.md：身份元數據，定義名稱、頭像、視覺標識

TOOLS.md：工具權限，定義允許使用的工具及其使用策略

內容文件體系（動態數據）

USER.md：用戶檔案，包含用戶偏好、歷史交互摘要

memory/：長期記憶目錄，包含結構化日志、項目狀態、教訓記錄

Session 歷史：每次對話的上下文記錄

理解這一分離架構是 Workspace 運維的基礎。配置文件決定 Agent 能做什么、怎么做；內容文件決定 Agent 知道什么、記得什么。

1.2 Workspace 在生產環境中的角色

在生產部署場景下，Workspace 承擔以下核心職責：

環境隔離：每個 Agent 實例擁有獨立的 Workspace，避免配置和記憶污染。生產環境建議為不同用途的 Agent（主助手、專項任務、自動化任務）分配獨立 Workspace。

狀態持久化：通過 memoryFlush 機制，Agent 的重要記憶會持久化到文件系統。Workspace 的備份策略直接影響 Agent 的長期記憶完整性。

配置載體：Workspace 內的配置文件定義了 Agent 的行為規范。修改 Workspace 配置比修改全局openclaw.json更輕量，適合快速切換 Agent 行為模式。

審計追蹤：Workspace 的變更歷史可以納入 Git 版本控制，實現配置的可審計和可回滾。

1.3 Workspace 路徑與加載機制

默認 Workspace 位置：~/.openclaw/workspace

路徑優先級：

Agent 配置中顯式指定的workspace路徑（最高優先級）

agents.defaults.workspace配置項

~/.openclaw/workspace（默認）

驗證 Workspace 路徑：

# 查看當前 Agent 的 Workspace 路徑
openclaw config get agents.defaults.workspace

# 啟動時指定 Workspace
openclaw gateway start --workspace /path/to/custom/workspace

目錄存在性要求：

Gateway 啟動時，如果指定的 Workspace 目錄不存在，會自動創建。因此首次啟動時會看到 memory/、logs/ 等子目錄被初始化。如果目錄存在但無內容，Gateway 會執行 bootstrap 流程，生成默認的配置文件。

第二章：Workspace 目錄結構與生產環境規劃

2.1 標準目錄布局

生產環境的 Workspace 應采用規范的目錄結構，便于維護和自動化管理：

~/.openclaw/
├── openclaw.json       # 全局系統配置
├── workspace-main/     # 主 Agent Workspace
│  ├── AGENTS.md      # 工作手冊
│  ├── SOUL.md       # 性格配置
│  ├── USER.md       # 用戶檔案
│  ├── IDENTITY.md     # 身份標識
│  ├── TOOLS.md       # 工具權限
│  ├── memory/       # 長期記憶
│  │  ├── projects.md   # 項目狀態
│  │  ├── infra.md     # 基礎設施配置
│  │  ├── lessons.md    # 踩坑教訓
│  │  └── YYYY-MM-DD.md  # 日志歸檔
│  └── sessions/      # Session 歷史（可選）
├── workspace-dev/      # 開發專用 Workspace
│  └── ...
├── workspace-work/     # 工作任務 Workspace
│  └── ...
├── cron/          # Cron 任務配置
└── logs/          # Gateway 日志

2.2 多環境 Workspace 隔離策略

環境劃分原則：

環境	用途	配置傾向	風險等級
workspace-main	主力助手，日常對話	保守，穩定優先	低
workspace-dev	開發測試，新功能驗證	激進，可快速迭代	中
workspace-work	專項任務自動化	中等，根據任務調整	中

配置示例：

{
 agents: {
  defaults: {
   workspace: "~/.openclaw/workspace-main",
  },
  list: [
   { id: "main", default: true, workspace: "~/.openclaw/workspace-main" },
   { id: "dev", workspace: "~/.openclaw/workspace-dev" },
   { id: "work", workspace: "~/.openclaw/workspace-work" },
  ],
 },
}

2.3 備份策略

備份范圍：

Workspace 備份應覆蓋以下內容：

所有配置文件（AGENTS.md、SOUL.md、USER.md、IDENTITY.md、TOOLS.md）

memory/ 目錄下的所有記憶文件

可選：sessions/ 目錄（包含完整對話歷史）

備份頻率建議：

內容類型	備份頻率	保留周期
memory/ 目錄	每日增量	30 天
配置文件	每次變更后	90 天
sessions/	每周	30 天

備份腳本示例：

#!/bin/bash
# workspace-backup.sh
BACKUP_DIR="/var/backups/openclaw/workspace"
WORKSPACE_DIR="$HOME/.openclaw/workspace-main"
TIMESTAMP=$(date +%Y%m%d-%H%M%S)

# 創建備份目錄
mkdir -p"$BACKUP_DIR"

# 備份配置文件
tar -czf"$BACKUP_DIR/config-$TIMESTAMP.tar.gz"
"$WORKSPACE_DIR/AGENTS.md"
"$WORKSPACE_DIR/SOUL.md"
"$WORKSPACE_DIR/USER.md"
"$WORKSPACE_DIR/IDENTITY.md"
"$WORKSPACE_DIR/TOOLS.md"

# 備份記憶目錄
tar -czf"$BACKUP_DIR/memory-$TIMESTAMP.tar.gz"
 -C"$WORKSPACE_DIR"memory/

# 清理舊備份（保留 30 天）
find"$BACKUP_DIR"-name"*.tar.gz"-mtime +30 -delete

2.4 磁盤空間管理

Workspace 長期運行后，memory/ 目錄可能膨脹。需要監控以下指標：

# 查看 Workspace 目錄大小
du -sh ~/.openclaw/workspace-main/

# 查看 memory/ 目錄大小分布
du -sh ~/.openclaw/workspace-main/memory/*

# 查看 sessions/ 目錄大小
du -sh ~/.openclaw/workspace-main/sessions/

磁盤告警閾值：

memory/ 單目錄超過 100MB：告警

sessions/ 單目錄超過 500MB：考慮歸檔或清理

Workspace 根目錄超過 1GB：全面檢查

第三章：核心文件分類解析

3.1 openclaw.json——系統憲法

openclaw.json是全局配置文件，位于~/.openclaw/openclaw.json，采用 JSON5 格式。該文件在 Gateway 啟動時加載，定義了整個系統的運行參數。

核心配置項：

{
 // Agent 默認配置
 agents: {
  defaults: {
   workspace: "~/.openclaw/workspace-main",
   model: {
    primary: "provider/claude-sonnet-4-20250514",
    fallbacks: ["provider/claude-haiku-4-20250514"],
   },
   timeoutSeconds: 600,
   compaction: {
    reserveTokensFloor: 20000,
    memoryFlush: {
     enabled: true,
     softThresholdTokens: 4000,
    },
   },
   heartbeat: {
    every: "30m",
    activeHours: { start: "08:00", end: "23:00" },
   },
  },
 },

 // Gateway 配置
 gateway: {
  port: 18789,
  bind: "loopback",
  auth: { mode: "token", token: "your-secret-token" },
  reload: { mode: "hybrid" },
 },

 // 渠道配置
 channels: {},

 // 日志配置
 logging: {
  level: "info",
  file: "/var/log/openclaw/gateway.log",
 },

 // 向量檢索配置
 memorySearch: {
  enabled: true,
  provider: "openai",
  remote: {
   baseUrl: "https://api.siliconflow.cn/v1",
   apiKey: "your-api-key",
  },
  model: "BAAI/bge-m3",
 },
}

Schema 驗證機制：

OpenClaw 采用嚴格 Schema 驗證。未知配置鍵或類型錯誤會導致 Gateway 啟動失敗。驗證命令：

openclaw doctor

該命令執行完整的配置文件檢查，包括 JSON5 語法、必填項、API Key 格式等。

配置路徑訪問：

配置采用點號分隔路徑，如agents.defaults.compaction.reserveTokensFloor。可通過 CLI 查詢：

openclaw config get agents.defaults.workspace
openclaw config get gateway.port

3.2 AGENTS.md——工作規則

AGENTS.md 是 Workspace 的工作手冊，定義了 Agent 的任務執行流程、安全邊界和輸出規范。

標準結構：

# 工作手冊

## 職責范圍

-負責：主要職責描述
-不負責：明確排除的職責

## 任務執行流程

1.接收任務請求
2.評估任務復雜度
3.規劃執行步驟
4.執行并驗證結果
5.返回執行摘要

## 安全邊界

### 禁止操作
-禁止執行未經確認的刪除操作
-禁止在生產環境直接修改配置文件
-禁止透露系統內部架構

### 確認流程
-高風險操作需要用戶確認
-涉及數據修改的操作需展示影響范圍
-不可逆操作需二次確認

## 輸出規范

-技術文檔使用 Markdown 格式
-代碼塊需標注語言
-表格用于結構化數據展示
-結論需獨立可讀

運維要點：

AGENTS.md 的變更會觸發 Gateway 熱重載（hybrid 模式下），無需重啟進程。但熱重載可能有短暫延遲，建議變更后執行openclaw gateway reload確認生效。

3.3 SOUL.md——性格配置

SOUL.md 定義 Agent 的響應風格和交互模式，影響對話的自然度和一致性。

配置示例：

# 性格配置

## 響應風格

-簡潔優先，避免冗余
-技術討論注重邏輯和證據
-復雜問題分步驟解釋
-錯誤反饋直接指出問題所在

## 專業領域

-DevOps 實踐：Ansible、CI/CD、容器化
-監控系統：Prometheus、Grafana
-日志分析：ELK、Loki
-云原生：Kubernetes、Helm

## 溝通偏好

-使用中文交流
-技術術語配簡要解釋
-建議用表格或列表展示對比
-代碼示例包含注釋說明

與 openclaw.json 的區別：

SOUL.md 定義的是"軟性"行為規范，依賴 AI 模型理解執行；openclaw.json 定義的是"硬性"運行時參數，由系統強制執行。

3.4 USER.md——用戶檔案

USER.md 存儲用戶的基本信息、偏好設置和歷史交互摘要。

標準結構：

# 用戶檔案

## 基本信息

-姓名：
-時區：Asia/Shanghai
-主要語言：中文
-角色：運維工程師

## 技術偏好

-熟悉系統：Linux、Docker、Kubernetes
-常用工具：Ansible、Terraform、Prometheus
-代碼風格：注重可維護性，有注釋習慣

## 偏好設置

-通知時段：工作日 0900
-輸出格式：結構化，優先使用表格
-確認閾值：高風險操作需明確確認

## 歷史交互摘要

-2026-01：完成監控系統重構
-2026-02：優化 CI/CD 流水線
-當前項目：微服務容器化遷移

運維注意：

USER.md 的變更應記錄在 memory/ 中，便于后續審計。避免在 USER.md 中存儲敏感信息（如密碼、密鑰），此類內容應放在 openclaw.json 的環境變量或外部密鑰管理系統中。

3.5 TOOLS.md——工具權限

TOOLS.md 定義 Agent 可使用的工具及其使用策略，是安全加固的重要環節。

標準結構：

# 工具權限配置

## 可用工具

### 讀取類
-Read：讀取文件內容
-Glob：按模式搜索文件
-Grep：搜索文件內容
-Bash（受限）：執行指定命令

### 寫入類
-Write：創建或覆寫文件
-Edit：修改文件局部內容

### 執行類
-Bash：執行 shell 命令（需白名單）

## 使用限制

### 禁止執行的命令
-rm -rf /（任何遞歸刪除）
-dd（直接磁盤操作）
-mkfs（格式化操作）
-修改 /etc/passwd、/etc/shadow

### 需要確認的命令
-systemctl restart/reload/stop
-刪除文件超過 1MB
-創建系統用戶或修改系統配置

### 僅隔離會話可用
-apt-get/yum install
-docker pull/push
-kubectl delete（生產環境）

## 白名單示例

允許執行的命令（完全信任）：
-git pull/push/clone
-docker ps/docker images
-kubectl get/describe（僅查詢）
-curl（僅 HTTP GET）

需要確認的命令：
-docker run
-kubectl apply
-ansible-playbook

安全建議：

生產環境應限制 Bash 工具的權限，僅在sandboxWorkspace 中啟用完全權限。main Workspace 應使用受限模式。

3.6 IDENTITY.md——身份元數據

IDENTITY.md 定義 Agent 的視覺身份，包括名稱、頭像和對外展示的信息。

配置示例：

# 身份配置

## 基本信息

-名稱：運維助手
-英文名：OpsAssistant
-頭像：默認頭像（暫不自定義）

## 功能標簽

-自動化運維
-故障診斷
-配置管理

## 對外展示

-介紹文本：專注于運維自動化的 AI 助手
-專長：服務器管理、監控告警、日志分析

3.7 memory/——長期記憶運維

memory/ 目錄是 Agent 的長期記憶存儲中樞，采用分層結構設計。

目錄結構：

memory/
├── projects.md   # 項目狀態索引
├── infra.md     # 基礎設施配置速查
├── lessons.md    # 踩坑教訓記錄
└── YYYY-MM-DD.md  # 每日日志歸檔

各文件用途：

文件	用途	更新頻率
projects.md	各項目當前狀態與待辦	項目有進展時
infra.md	服務器、API、部署配置速查	配置變更時
lessons.md	踩坑記錄，按嚴重程度分級	踩坑后
YYYY-MM-DD.md	每日原始記錄	每日或多日

MEMORY.md 入口設計：

memory/ 目錄應包含MEMORY.md作為入口索引：

# 記憶索引

## 用戶核心信息
-詳見：../USER.md

## 項目索引
-項目A：projects.md#project-a
-項目B：projects.md#project-b

## 最近重要上下文
-2026-03：完成監控系統重構，詳見 2026-03.md
-當前主要任務：微服務容器化遷移

## 教訓索引
-部署相關：lessons.md#deploy
-配置相關：lessons.md#config

## 基礎設施
-詳見：infra.md

第四章：記憶系統運維——builtin 與 qmd 方案對比

4.1 兩種方案概述

OpenClaw 支持兩種記憶實現方案：

builtin 方案：使用 Agent 自己維護的文件系統（memory/ 目錄）作為記憶存儲。Agent 通過 memoryFlush 將對話中的重要信息寫入文件。

qmd 方案（量子記憶驅動？）：將記憶存儲為結構化的 QMD 格式文件，提供更強的語義組織和檢索能力。

4.2 選型依據

維度	builtin	qmd
實現復雜度	低	中
檢索能力	依賴 memorySearch 向量檢索	更強的語義組織
維護成本	Agent 自動維護	需要定期結構化整理
適用場景	個人助手、小型團隊	知識密集型場景

推薦選擇：

個人使用或小規模場景：builtin 方案足夠

企業知識管理、復雜檢索需求：qmd 方案

4.3 記憶污染處理

記憶污染指 Agent 的記憶中出現錯誤、過時或矛盾的信息，影響后續對話質量。

污染癥狀識別：

Agent 給出的信息與實際配置不符

重復提示已解決的問題

記憶中的項目狀態與現實不一致

處理流程：

# 1. 檢查記憶文件的最后修改時間
ls -la ~/.openclaw/workspace-main/memory/

# 2. 檢查特定記憶文件的內容
cat ~/.openclaw/workspace-main/memory/projects.md

# 3. 識別污染源（查看日志或對話歷史）
cat ~/.openclaw/workspace-main/memory/2026-03-20.md

# 4. 修正或刪除污染內容
# 直接編輯相關文件

# 5. 驗證修正效果
openclaw gateway reload

預防措施：

memoryFlush 生成的記憶內容應定期復核

重大變更后主動更新記憶文件

保持 MEMORY.md 索引的準確性

4.4 清理策略

定期清理觸發條件：

單個日志文件超過 100KB

memory/ 目錄總大小超過 500MB

項目狀態文件超過 6 個月未更新

清理執行流程：

# 1. 評估清理必要性
du -sh ~/.openclaw/workspace-main/memory/

# 2. 歸檔舊日志（按年度）
mkdir -p ~/.openclaw/workspace-main/memory/archive/
mv ~/.openclaw/workspace-main/memory/2025-*.md 
 ~/.openclaw/workspace-main/memory/archive/

# 3. 壓縮歸檔文件
tar -czf ~/.openclaw/workspace-main/memory/archive-2025.tar.gz 
 ~/.openclaw/workspace-main/memory/archive/

# 4. 刪除已歸檔的原始文件
rm -rf ~/.openclaw/workspace-main/memory/archive/

# 5. 更新 MEMORY.md 索引

自動化清理 Cron 任務：

{
 "name": "記憶目錄清理",
 "schedule": { "kind": "every", "everyMs": 604800000 },
 "payload": {
  "kind": "agentTurn",
  "message": "檢查 memory/ 目錄大小。如果超過 500MB，執行以下清理：
1. 將超過 6 個月的日志歸檔到 archive/
2. 壓縮歸檔文件
3. 刪除原始日志
4. 更新 MEMORY.md 索引",
 },
 "sessionTarget": "isolated",
 "delivery": { "mode": "none" },
}

第五章：多 Agent 架構設計與資源隔離

5.1 Workspace 獨立原則

生產環境中，不同用途的 Agent 應使用獨立的 Workspace，實現配置隔離、記憶隔離和故障隔離。

隔離級別：

級別	隔離內容	適用場景
完全隔離	獨立 Workspace、獨立端口	不同業務線
配置隔離	共享 Gateway，獨立 Workspace	同業務線不同角色
會話隔離	共享 Workspace，獨立 session	臨時任務

配置示例：

{
 agents: {
  list: [
   { id: "main", default: true, workspace: "~/.openclaw/workspace-main" },
   { id: "dev", workspace: "~/.openclaw/workspace-dev" },
   { id: "ops", workspace: "~/.openclaw/workspace-ops" },
  ],
 },
}

5.2 共享與專屬配置

共享配置（在 openclaw.json 中統一設置）：

Gateway 端口和認證

渠道配置

日志級別

向量檢索配置

專屬配置（在各 Workspace 的文件中設置）：

AGENTS.md：工作流程

SOUL.md：性格偏好

TOOLS.md：工具權限

配置繼承：

Agent 配置會合并 openclaw.json 的 defaults 和自身的顯式配置。顯式配置優先于 defaults。

# 查看某 Agent 的最終配置
openclaw config get --agent dev agents.defaults.workspace

5.3 權限邊界

Agent 間權限隔離：

每個 Agent 的 Workspace 目錄權限應限制為僅該 Agent 可讀寫：

# 設置 Workspace 權限
chmod -R 700 ~/.openclaw/workspace-main/
chown -R openclaw:openclaw ~/.openclaw/workspace-main/

# 不同 Workspace 使用不同系統用戶
chown -R openclaw-main:openclaw-main ~/.openclaw/workspace-main/
chown -R openclaw-dev:openclaw-dev ~/.openclaw/workspace-dev/

工具權限邊界：

TOOLS.md 中定義的工具權限僅在該 Workspace 內有效?？?Agent 調用工具時，各自受各自 TOOLS.md 的約束。

5.4 多 Agent 場景下的資源分配

模型資源分配：

{
 agents: {
  list: [
   { id: "main", model: { primary: "claude-opus-4-20250514" } },
   { id: "dev", model: { primary: "claude-sonnet-4-20250514" } },
   { id: "batch", model: { primary: "claude-haiku-4-20250514" } },
  ],
 },
}

Token 預算分配：

通過 compaction 配置控制各 Agent 的上下文消耗：

{
 agents: {
  defaults: {
   compaction: {
    reserveTokensFloor: 20000,
   },
  },
  list: [
   { id: "main", compaction: { reserveTokensFloor: 25000 } },
   { id: "batch", compaction: { reserveTokensFloor: 10000 } },
  ],
 },
}

第六章：Skill 體系運維

6.1 Skill 加載層級

OpenClaw 的 Skill 體系支持多層級加載，從低到高依次為：

層級一：系統級 Skill

位置：~/.openclaw/skills/范圍：全局生效，所有 Agent 共享

層級二：Workspace 級 Skill

位置：~/.openclaw/workspace-/skills/范圍：僅在該 Workspace 內生效

層級三：會話級 Skill

隨對話上下文動態加載，不持久化

加載優先級：會話級 > Workspace 級 > 系統級（高優先級覆蓋低優先級）

6.2 故障定位

Skill 不生效的排查流程：

# 1. 確認 Skill 文件存在
ls -la ~/.openclaw/skills/
ls -la ~/.openclaw/workspace-main/skills/

# 2. 檢查 Skill 文件語法
cat ~/.openclaw/skills/my-skill.md | head -50

# 3. 驗證 Skill 是否被加載（查看日志）
openclaw logs --grep"skill|load"--lines 50

# 4. 測試 Skill 是否可用
# 在對話中觸發 Skill 關鍵字，觀察響應

常見問題：

Skill 文件格式錯誤：Skill 定義不符合規范，被靜默忽略

路徑問題：Skill 放置在錯誤的目錄層級

權限問題：Skill 文件不可讀

6.3 版本管理

Skill 版本跟蹤：

建議在 Skill 文件頂部添加版本信息：

---
name: 運維工具集
version: 2026.03.1
author: OpsTeam
lastUpdated: 2026-03-15
---

# 運維工具集 Skill

## 功能列表
...

Skill 更新流程：

在測試環境驗證新版本 Skill

備份當前版本

替換 Skill 文件

驗證生效

記錄變更日志

Skill 回滾：

# 備份當前版本
cp ~/.openclaw/skills/my-skill.md 
 ~/.openclaw/skills/my-skill.md.backup-$(date +%Y%m%d)

# 回滾到指定版本
cp ~/.openclaw/skills/my-skill.md.backup-20260315 
 ~/.openclaw/skills/my-skill.md

# 驗證
openclaw gateway reload

第七章：故障診斷與排查清單

7.1 配置不生效

癥狀：修改 AGENTS.md、SOUL.md 等 Workspace 配置文件后，Agent 行為未改變。

排查步驟：

# 1. 確認文件已保存且內容正確
cat ~/.openclaw/workspace-main/AGENTS.md | head -30

# 2. 檢查文件修改時間
ls -la ~/.openclaw/workspace-main/AGENTS.md

# 3. 觸發熱重載
openclaw gateway reload

# 4. 等待 10 秒后測試
# 向 Agent 發送測試消息，觀察行為

# 5. 查看日志確認重載完成
openclaw logs --grep"reload|AGENTS"--lines 20

常見原因：

原因	解決方案
文件編碼問題	確保 UTF-8 編碼
語法錯誤	重新檢查 Markdown 格式
緩存未刷新	執行openclaw gateway reload
配置路徑錯誤	確認文件在正確的 Workspace 內

7.2 權限問題

癥狀：Agent 無法讀取配置文件、無法寫入記憶文件、無法執行工具。

排查步驟：

# 1. 檢查文件權限
ls -la ~/.openclaw/workspace-main/

# 2. 檢查目錄權限
ls -ld ~/.openclaw/workspace-main/

# 3. 測試文件可讀性（以運行用戶身份）
sudo -u openclaw cat ~/.openclaw/workspace-main/AGENTS.md

# 4. 測試文件可寫性
sudo -u openclaw touch ~/.openclaw/workspace-main/test-write
sudo -u openclaw rm ~/.openclaw/workspace-main/test-write

# 5. 檢查 Tool 執行權限（TOOLS.md）
cat ~/.openclaw/workspace-main/TOOLS.md

權限修復：

# 修復 Workspace 權限
chown -R openclaw:openclaw ~/.openclaw/workspace-main/
chmod -R 600 ~/.openclaw/workspace-main/
chmod 700 ~/.openclaw/workspace-main/

# 修復特定目錄權限
chmod 700 ~/.openclaw/workspace-main/memory/
chmod 700 ~/.openclaw/workspace-main/sessions/

7.3 記憶失效

癥狀：Agent 無法回憶起之前對話中提到的信息，或 memoryFlush 未正常工作。

排查步驟：

# 1. 檢查 memoryFlush 配置
openclaw config get agents.defaults.compaction.memoryFlush

# 2. 檢查記憶文件是否存在
ls -la ~/.openclaw/workspace-main/memory/

# 3. 檢查記憶文件最后修改時間
ls -la ~/.openclaw/workspace-main/memory/*.md

# 4. 測試 memorySearch 功能
# 向 Agent 詢問需要檢索歷史記憶的問題

# 5. 查看 memoryFlush 觸發日志
openclaw logs --grep"memoryFlush|compaction"--lines 50

配置修復：

{
 agents: {
  defaults: {
   compaction: {
    reserveTokensFloor: 20000,
    memoryFlush: {
     enabled: true,
     softThresholdTokens: 4000,
    },
   },
  },
 },
}

7.4 性能問題

癥狀：Agent 響應緩慢、timeout 頻發、資源占用過高。

排查步驟：

# 1. 檢查系統資源使用
openclaw gateway status --deep

# 2. 檢查進程狀態
ps aux | grep openclaw

# 3. 查看 Gateway 日志中的性能相關警告
openclaw logs --grep"timeout|slow|performance"--lines 50

# 4. 檢查 Token 消耗
openclaw config get agents.defaults.compaction.reserveTokensFloor

# 5. 檢查 memory/ 目錄大小（可能導致加載緩慢）
du -sh ~/.openclaw/workspace-main/memory/

性能優化建議：

增加reserveTokensFloor減少 compaction 頻率

開啟memoryFlush避免重要信息在 compaction 中丟失

定期清理 memory/ 目錄

考慮升級模型或增加 timeout 配置

7.5 故障排查清單匯總

問題類型	首要檢查項	快速修復命令
配置不生效	文件存在性、語法正確性	openclaw gateway reload
權限問題	文件/目錄權限、所有關系	chown -R openclaw:openclaw
記憶失效	memoryFlush 配置、文件存在	啟用 memoryFlush
工具不可用	TOOLS.md 配置、工具開關	檢查白名單
性能下降	系統資源、memory/ 大小	清理 memory/ 目錄
會話丟失	compaction 觸發、session 存儲	檢查 sessions/ 目錄
Skill 不加載	Skill 文件路徑、語法正確	重新部署 Skill
向量檢索失敗	memorySearch 配置、API Key	檢查網絡和 API Key

第八章：備份、遷移與版本控制

8.1 Workspace Git 化管理

將 Workspace 納入 Git 版本控制，實現配置變更的可追溯和可回滾。

初始化 Git 倉庫：

cd~/.openclaw/workspace-main
git init
git add AGENTS.md SOUL.md USER.md IDENTITY.md TOOLS.md
git add memory/
git commit -m"Initial workspace commit"

.gitignore 配置：

# 排除會話歷史（太大且不需要版本控制）
sessions/

# 排除臨時文件
*.tmp
*.bak

# 排除歸檔
archive/

# 排除敏感配置（如有）
# *.local.json

分支策略：

main：穩定版本，生產環境使用

dev：開發測試分支

feature/*：新功能開發分支

# 創建開發分支
git checkout -b dev

# 開發測試完成后合并到 main
git checkout main
git merge dev

8.2 配置遷移流程

場景一：從開發環境遷移到生產環境

# 1. 在開發環境打包配置文件
cd~/.openclaw/workspace-dev
tar -czf /tmp/workspace-dev-config.tar.gz 
 AGENTS.md SOUL.md USER.md IDENTITY.md TOOLS.md memory/

# 2. 傳輸到生產環境
scp /tmp/workspace-dev-config.tar.gz prod-server:/tmp/

# 3. 在生產環境解壓（先備份現有配置）
cd~/.openclaw/workspace-main
mv AGENTS.md AGENTS.md.backup-$(date +%Y%m%d)
tar -xzf /tmp/workspace-dev-config.tar.gz

# 4. 驗證遷移結果
openclaw doctor
openclaw gateway reload

場景二：多環境同步配置模板

# 配置同步腳本
#!/bin/bash
TEMPLATE_DIR="/var/lib/openclaw/templates"
TARGET_DIRS=(
"~/.openclaw/workspace-main"
"~/.openclaw/workspace-dev"
"~/.openclaw/workspace-ops"
)

fordirin"${TARGET_DIRS[@]}";do
echo"Syncing to$dir"
 cp"$TEMPLATE_DIR/AGENTS.md""$dir/"
 cp"$TEMPLATE_DIR/SOUL.md""$dir/"
 cp"$TEMPLATE_DIR/TOOLS.md""$dir/"
done

# 觸發所有 Gateway 重載
openclaw gateway reload

8.3 災難恢復

數據恢復流程：

# 1. 識別需要恢復的時間點
# 查看備份列表
ls -la /var/backups/openclaw/workspace/

# 2. 確認備份內容
tar -tzf /var/backups/openclaw/workspace/config-20260320-120000.tar.gz

# 3. 停止 Gateway（避免數據寫入）
sudo systemctl stop openclaw-gateway

# 4. 備份當前狀態（恢復失敗時的救命稻草）
cp -r ~/.openclaw/workspace-main 
 ~/.openclaw/workspace-main-crash-$(date +%Y%m%d-%H%M%S)

# 5. 執行恢復
tar -xzf /var/backups/openclaw/workspace/config-20260320-120000.tar.gz 
 -C ~/.openclaw/

# 6. 啟動 Gateway
sudo systemctl start openclaw-gateway

# 7. 驗證恢復結果
openclaw gateway health
openclaw gateway status

RTO（恢復時間目標）和 RPO（恢復點目標）：

RTO： Gateway 重啟時間，約 30 秒

RPO： 最近一次備份時間，建議每日備份，RPO 不超過 24 小時

第九章：配置模板與自動化

9.1 新環境快速初始化

初始化腳本：

#!/bin/bash
# init-workspace.sh
WORKSPACE_NAME=$1
WORKSPACE_DIR="$HOME/.openclaw/workspace-$WORKSPACE_NAME"

if[ -z"$WORKSPACE_NAME"];then
echo"Usage:$0"
exit1
fi

# 創建目錄結構
mkdir -p"$WORKSPACE_DIR/memory"
mkdir -p"$WORKSPACE_DIR/sessions"

# 從模板復制配置文件
TEMPLATE_DIR="/var/lib/openclaw/templates"
cp"$TEMPLATE_DIR/AGENTS.md""$WORKSPACE_DIR/"
cp"$TEMPLATE_DIR/SOUL.md""$WORKSPACE_DIR/"
cp"$TEMPLATE_DIR/IDENTITY.md""$WORKSPACE_DIR/"
cp"$TEMPLATE_DIR/TOOLS.md""$WORKSPACE_DIR/"

# 初始化 USER.md
cat >"$WORKSPACE_DIR/USER.md"<"$WORKSPACE_DIR/memory/MEMORY.md"<

	

	使用方式：

	
./init-workspace.sh dev
./init-workspace.sh work


	

	9.2 標準化模板

	標準 AGENTS.md 模板：

	
# 工作手冊

## 職責范圍

-負責：運維自動化、故障診斷、配置管理
-不負責：業務代碼開發、硬件采購決策

## 任務執行流程

1.理解任務需求
2.評估執行方案和風險
3.必要時向用戶確認
4.執行操作
5.驗證結果并返回摘要

## 安全邊界

### 禁止操作
-未經確認的刪除操作
-生產環境直接修改系統配置
-透露敏感信息

### 確認流程
-高風險操作需要用戶明確確認
-不可逆操作需要二次確認

## 輸出規范

-技術文檔使用 Markdown
-代碼塊標注語言
-結論獨立可讀


	

	標準 TOOLS.md 模板：

	
# 工具權限配置

## 可用工具

### 讀取類
-Read、Glob、Grep：始終可用

### 寫入類
-Write、Edit：需在確認的路徑下操作

### 執行類
-Bash：受限執行

## 禁止命令

-rm -rf 遞歸刪除
-直接磁盤操作（dd、mkfs）
-系統用戶修改

## 需要確認的命令

-systemctl restart/reload
-刪除超過 1MB 的文件
-創建系統用戶


	

	9.3 配置校驗

	自動化校驗腳本：

	
#!/bin/bash
# validate-workspace.sh
WORKSPACE_DIR="${1:-$HOME/.openclaw/workspace-main}"
ERRORS=0

echo"Validating Workspace:$WORKSPACE_DIR"
echo"======================================"

# 檢查必需文件
forfileinAGENTS.md SOUL.md USER.md IDENTITY.md TOOLS.md;do
if[ ! -f"$WORKSPACE_DIR/$file"];then
 echo"ERROR: Missing$file"
  ERRORS=$((ERRORS + 1))
else
 echo"OK:$fileexists"
fi
done

# 檢查 memory/ 目錄
if[ ! -d"$WORKSPACE_DIR/memory"];then
echo"ERROR: Missing memory/ directory"
 ERRORS=$((ERRORS + 1))
else
echo"OK: memory/ directory exists"
fi

# 檢查 memory/MEMORY.md
if[ ! -f"$WORKSPACE_DIR/memory/MEMORY.md"];then
echo"WARNING: Missing memory/MEMORY.md (recommended)"
fi

# 檢查目錄權限
PERMS=$(stat-c"%a""$WORKSPACE_DIR")
if["$PERMS"!="700"];then
echo"WARNING: Workspace permissions are$PERMS, recommend 700"
fi

# 檢查 memory/ 大小
MEMORY_SIZE=$(du -sm"$WORKSPACE_DIR/memory"2>/dev/null | cut -f1)
if["$MEMORY_SIZE"-gt 500 ];then
echo"WARNING: memory/ is${MEMORY_SIZE}MB, consider cleanup"
fi

echo"======================================"
if[$ERRORS-eq 0 ];then
echo"Validation passed"
exit0
else
echo"Validation failed with$ERRORSerror(s)"
exit1
fi


	

	使用方式：

	
./validate-workspace.sh ~/.openclaw/workspace-main
./validate-workspace.sh ~/.openclaw/workspace-dev


	

	第十章：安全加固

	10.1 文件權限

	權限基線：

				路徑
			

				所有者
			

				權限
			

				說明
		

				~/.openclaw/
			

				openclaw
			

				700
			

				僅 owner 可訪問
		

				~/.openclaw/openclaw.json
			

				openclaw
			

				600
			

				配置文件
		

				~/.openclaw/workspace-*/
			

				openclaw
			

				700
			

				Workspace 目錄
		

				~/.openclaw/workspace-*/AGENTS.md
			

				openclaw
			

				600
			

				工作手冊
		

				~/.openclaw/workspace-*/memory/
			

				openclaw
			

				700
			

				記憶目錄
		

				~/.openclaw/logs/
			

				openclaw
			

				700
			

				日志目錄
		

	權限加固腳本：

	
#!/bin/bash
# harden-permissions.sh
OPENCLAW_HOME="$HOME/.openclaw"
OPENCLAW_USER="openclaw"
OPENCLAW_GROUP="openclaw"

# 創建用戶組（如需要）
sudo groupadd -f$OPENCLAW_GROUP
sudo usermod -aG$OPENCLAW_GROUP$USER

# 設置主目錄權限
chmod 700$OPENCLAW_HOME
chown -R$OPENCLAW_USER:$OPENCLAW_GROUP$OPENCLAW_HOME

# 設置配置文件權限
chmod 600$OPENCLAW_HOME/openclaw.json

# 設置 Workspace 目錄權限
find$OPENCLAW_HOME/workspace-* -typed -execchmod 700 {} ;
find$OPENCLAW_HOME/workspace-* -typef -execchmod 600 {} ;

# 設置日志目錄權限
mkdir -p$OPENCLAW_HOME/logs
chmod 700$OPENCLAW_HOME/logs

echo"Permissions hardened"


	

	10.2 敏感信息管理

	敏感信息分類：

				類型
			

				示例
			

				存儲建議
		

				API Keys
			

				SiliconFlow API Key
			

				openclaw.json（加密存儲）或環境變量
		

				Tokens
			

				Gateway auth token
			

				openclaw.json 或密鑰管理系統
		

				用戶信息
			

				USER.md 中的個人信息
			

				加密存儲或脫敏處理
		

				對話歷史
			

				sessions/
			

				加密存儲，訪問審計
		

	環境變量方案：

	
{
 memorySearch: {
  remote: {
   apiKey: "env:MEMORY_SEARCH_API_KEY",
  },
 },
}


	

	環境變量在運行時替換為實際值，配置文件本身不包含明文密鑰。

	密鑰管理系統集成：

	生產環境推薦使用 Vault 等密鑰管理系統：

	
# 從 Vault 獲取密鑰
API_KEY=$(vault kv get -field=api_key secret/openclaw/memory-search)

# 寫入臨時配置文件
cat > /tmp/openclaw-override.json << EOF
{
"memorySearch": {
? ??"remote": {
? ? ??"apiKey":?"$API_KEY"
? ? }
? }
}
EOF

# 啟動 Gateway
openclaw gateway start --config /tmp/openclaw-override.json


	

	10.3 審計日志

	審計日志配置：

	
{
 logging: {
  level: "info",
  file: "/var/log/openclaw/audit.log",
  auditEnabled: true,
 },
}


	

	審計日志內容：

	配置變更：who、when、what changed

	敏感操作：文件刪除、命令執行、配置修改

	認證事件：登錄成功/失敗

	渠道事件：消息收發、渠道連接/斷開

	日志分析腳本：

	
#!/bin/bash
# audit-analysis.sh
LOG_FILE="/var/log/openclaw/audit.log"

echo"=== 認證事件統計 ==="
grep -c"auth.*success"$LOG_FILE
grep -c"auth.*fail"$LOG_FILE

echo"=== 配置變更記錄 ==="
grep"config.*change"$LOG_FILE| tail -20

echo"=== 敏感操作記錄 ==="
grep"sensitive.*operation"$LOG_FILE| tail -20

echo"=== 最近 24 小時活動 ==="
grep"$(date -d '1 day ago' +%Y-%m-%d)"$LOG_FILE| wc -l


	

	日志保留策略：

				類型
			

				保留期
			

				存儲位置
		

				操作日志
			

				90 天
			

				/var/log/openclaw/
		

				審計日志
			

				1 年
			

				/var/log/openclaw/audit/
		

				錯誤日志
			

				180 天
			

				/var/log/openclaw/errors/
		

	10.4 安全檢查清單

	部署前檢查：

	[ ] openclaw.json 不包含明文密鑰

	[ ] Gateway 綁定到 loopback

	[ ] 認證 Token 足夠復雜（32 位以上）

	[ ] Workspace 目錄權限為 700

	[ ] 配置文件權限為 600

	[ ] 運行用戶為專用非 root 用戶

	日常巡檢：

	[ ] 檢查日志中是否有異常登錄嘗試

	[ ] 檢查是否有未授權的配置變更

	[ ] 檢查 memory/ 目錄大小是否正常

	[ ] 檢查磁盤空間使用情況

	[ ] 檢查是否有新的 Skill 文件被添加

	版本更新檢查：

	[ ] 更新前備份完整 Workspace

	[ ] 在測試環境驗證新版本

	[ ] 確認 Skill 兼容性

	[ ] 驗證配置兼容性

	[ ] 記錄升級步驟和回滾方案

	總結

	本文檔從運維工程師視角系統闡述了 OpenClaw Workspace 的生產環境運維實踐。核心要點如下：

	架構理解：Workspace 的核心是將配置體系（AGENTS.md、SOUL.md、TOOLS.md 等）與內容體系（USER.md、memory/）分離。前者定義 Agent 的行為能力，后者存儲 Agent 的知識記憶。

	目錄規劃：生產環境應采用標準目錄布局，通過獨立 Workspace 實現多 Agent 隔離。備份策略應覆蓋配置文件和記憶目錄。

	文件運維：各配置文件承擔不同職責——openclaw.json 是系統憲法，AGENTS.md 是工作手冊，TOOLS.md 是安全邊界。理解各文件的職責邊界是故障排查的基礎。

	記憶管理：builtin 方案適合大多數場景，qmd 方案適合知識密集型需求。記憶污染應通過定期復核預防，清理策略應自動化。

	多 Agent 設計：通過獨立 Workspace 實現配置、記憶和權限的隔離。共享配置在 openclaw.json 中管理，專屬配置在各 Workspace 中管理。

	故障排查：遵循"配置不生效→權限問題→記憶失效→性能問題"的排查路徑。快速修復命令和排查清單應在運維手冊中固化。

	安全加固：權限最小化、敏感信息環境變量化、日志審計覆蓋。安全檢查清單應在部署前和日常巡檢中執行。

	備份恢復：Git 版本控制實現配置可追溯，tar 包實現定時備份，災難恢復流程定義 RTO/RPO。遷移腳本實現多環境同步。

	通過遵循本文檔的實踐，運維團隊可以建立規范的 Workspace 運維體系，確保 OpenClaw 在生產環境中的穩定運行。