Agent Workspace

Workspace là “ngôi nhà” của Agent. Đây là thư mục làm việc duy nhất được dùng cho các công cụ xử lý file và context của workspace. Các bạn nên giữ nó riêng tư và coi nó như bộ nhớ của Agent.

Workspace này tách biệt với ~/.openclaw/, nơi lưu trữ config, credentials và sessions.

Quan trọng: workspace là thư mục làm việc mặc định (default cwd), không phải sandbox cứng. Các công cụ sẽ xử lý đường dẫn tương đối dựa trên workspace, nhưng đường dẫn tuyệt đối vẫn có thể truy cập các vị trí khác trên máy trừ khi bật sandboxing. Nếu các bạn cần cô lập, hãy dùng agents.defaults.sandbox (và/hoặc cấu hình sandbox cho từng agent). Khi bật sandboxing và workspaceAccess không phải "rw", các công cụ sẽ hoạt động trong sandbox workspace nằm dưới ~/.openclaw/sandboxes, không phải workspace trên máy của các bạn.

Vị trí mặc định

  • Mặc định: ~/.openclaw/workspace
  • Nếu OPENCLAW_PROFILE được set và không phải "default", vị trí mặc định sẽ là ~/.openclaw/workspace-<profile>.
  • Ghi đè trong ~/.openclaw/openclaw.json:
{
  agent: {
    workspace: "~/.openclaw/workspace",
  },
}

Các lệnh openclaw onboard, openclaw configure, hoặc openclaw setup sẽ tạo workspace và các file bootstrap nếu chúng chưa có.

Nếu các bạn đã tự quản lý các file workspace, có thể tắt việc tạo file bootstrap:

{ agent: { skipBootstrap: true } }

Các thư mục workspace thừa

Các bản cài đặt cũ có thể đã tạo ~/openclaw. Giữ nhiều thư mục workspace có thể gây nhầm lẫn về auth hoặc trạng thái không đồng bộ, vì chỉ có một workspace hoạt động tại một thời điểm.

Khuyến nghị: chỉ giữ một workspace đang hoạt động. Nếu các bạn không còn dùng các thư mục thừa, hãy lưu trữ hoặc chuyển chúng vào Trash (ví dụ trash ~/openclaw). Nếu các bạn cố ý giữ nhiều workspace, hãy đảm bảo agents.defaults.workspace trỏ đến workspace đang hoạt động.

Lệnh openclaw doctor sẽ cảnh báo khi phát hiện các thư mục workspace thừa.

Sơ đồ file trong Workspace (ý nghĩa từng file)

Đây là các file chuẩn mà OpenClaw mong đợi trong workspace:

  • AGENTS.md

    • Hướng dẫn vận hành cho Agent và cách sử dụng bộ nhớ.
    • Được load khi bắt đầu mỗi session.
    • Nơi tốt để đặt các quy tắc, ưu tiên và chi tiết “cách ứng xử”.

  • SOUL.md

    • Tính cách, giọng điệu và ranh giới của Agent.
    • Được load mỗi session.

  • USER.md

    • Thông tin về người dùng và cách xưng hô với họ.
    • Được load mỗi session.

  • IDENTITY.md

    • Tên, phong cách và emoji của Agent.
    • Được tạo/cập nhật trong quá trình bootstrap ritual.

  • TOOLS.md

    • Ghi chú về các công cụ local và quy ước của các bạn.
    • Không kiểm soát tính khả dụng của công cụ; chỉ là hướng dẫn.

  • HEARTBEAT.md

    • Checklist nhỏ tùy chọn cho các lần chạy heartbeat.
    • Giữ ngắn gọn để tránh tốn token.

  • BOOT.md

    • Checklist khởi động tùy chọn, được thực thi khi Gateway restart nếu internal hooks được bật.
    • Giữ ngắn gọn; dùng message tool cho các lần gửi ra ngoài.

  • BOOTSTRAP.md

    • Nghi thức chạy lần đầu tiên (one-time first-run ritual).
    • Chỉ được tạo cho workspace hoàn toàn mới.
    • Xóa nó sau khi hoàn thành nghi thức.

  • memory/YYYY-MM-DD.md

    • Log bộ nhớ hàng ngày (một file mỗi ngày).
    • Khuyến nghị đọc hôm nay + hôm qua khi bắt đầu session.

  • MEMORY.md (tùy chọn)

    • Bộ nhớ dài hạn được tuyển chọn.
    • Chỉ load trong session chính, riêng tư (không phải context chia sẻ/nhóm).

Xem Memory để biết workflow và tính năng tự động flush bộ nhớ.

  • skills/ (tùy chọn)

    • Các skill riêng cho workspace.
    • Ghi đè các skill được quản lý/đóng gói khi tên trùng nhau.

  • canvas/ (tùy chọn)

    • Các file Canvas UI cho hiển thị node (ví dụ canvas/index.html).

Nếu thiếu bất kỳ file bootstrap nào, OpenClaw sẽ chèn một marker “missing file” vào session và tiếp tục. Các file bootstrap lớn sẽ bị cắt ngắn khi chèn vào; điều chỉnh giới hạn bằng agents.defaults.bootstrapMaxChars (mặc định: 20000). Lệnh openclaw setup có thể tạo lại các file mặc định bị thiếu mà không ghi đè các file đã có.

Những gì KHÔNG có trong workspace

Những thứ này nằm dưới ~/.openclaw/ và KHÔNG nên commit vào repo workspace:

  • ~/.openclaw/openclaw.json (config)
  • ~/.openclaw/credentials/ (OAuth tokens, API keys)
  • ~/.openclaw/agents/<agentId>/sessions/ (session transcripts + metadata)
  • ~/.openclaw/skills/ (managed skills)

Nếu các bạn cần di chuyển sessions hoặc config, hãy copy chúng riêng và giữ chúng ngoài version control.

Sao lưu bằng Git (khuyến nghị, private)

Coi workspace như bộ nhớ riêng tư. Đặt nó trong một repo git private để được sao lưu và có thể khôi phục.

Chạy các bước sau trên máy nơi Gateway đang chạy (đó là nơi workspace tồn tại).

1) Khởi tạo repo

Nếu git đã được cài đặt, các workspace mới sẽ được khởi tạo tự động. Nếu workspace này chưa phải là repo, hãy chạy:

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

2) Thêm remote private (các tùy chọn thân thiện với người mới)

Tùy chọn A: GitHub web UI

  1. Tạo một repository private mới trên GitHub.
  2. Không khởi tạo với README (tránh xung đột merge).
  3. Copy URL remote HTTPS.
  4. Thêm remote và push:
git branch -M main
git remote add origin <https-url>
git push -u origin main

Tùy chọn B: GitHub CLI (gh)

gh auth login
gh repo create openclaw-workspace --private --source . --remote origin --push

Tùy chọn C: GitLab web UI

  1. Tạo một repository private mới trên GitLab.
  2. Không khởi tạo với README (tránh xung đột merge).
  3. Copy URL remote HTTPS.
  4. Thêm remote và push:
git branch -M main
git remote add origin <https-url>
git push -u origin main

3) Cập nhật liên tục

git status
git add .
git commit -m "Update memory"
git push

Không commit secrets

Ngay cả trong repo private, hãy tránh lưu trữ secrets trong workspace:

  • API keys, OAuth tokens, passwords, hoặc credentials riêng tư.
  • Bất cứ thứ gì dưới ~/.openclaw/.
  • Các bản dump thô của chat hoặc file đính kèm nhạy cảm.

Nếu các bạn phải lưu trữ tham chiếu nhạy cảm, hãy dùng placeholder và giữ secret thật ở nơi khác (password manager, biến môi trường, hoặc ~/.openclaw/).

Gợi ý .gitignore cơ bản:

.DS_Store
.env
**/*.key
**/*.pem
**/secrets*

Di chuyển workspace sang máy mới

  1. Clone repo về đường dẫn mong muốn (mặc định ~/.openclaw/workspace).
  2. Set agents.defaults.workspace thành đường dẫn đó trong ~/.openclaw/openclaw.json.
  3. Chạy openclaw setup --workspace <path> để tạo các file còn thiếu.
  4. Nếu các bạn cần sessions, hãy copy ~/.openclaw/agents/<agentId>/sessions/ từ máy cũ riêng biệt.

Ghi chú nâng cao

  • Multi-agent routing có thể dùng các workspace khác nhau cho mỗi agent. Xem Channel routing để biết cấu hình routing.
  • Nếu agents.defaults.sandbox được bật, các session không phải main có thể dùng sandbox workspace riêng cho từng session dưới agents.defaults.sandbox.workspaceRoot.