OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Fundamentals

Không gian làm việc của agent

Không gian làm việc là thư mục chính của tác tử: thư mục làm việc được dùng cho các công cụ tệp và ngữ cảnh không gian làm việc. Hãy giữ riêng tư và coi đó là bộ nhớ.

Nơi này tách biệt với ~/.openclaw/, nơi lưu trữ cấu hình, thông tin xác thực và phiên.

Vị trí mặc định

  • Mặc định: ~/.openclaw/workspace
  • Nếu OPENCLAW_PROFILE được đặt và không phải là "default", giá trị mặc định sẽ trở thành ~/.openclaw/workspace-<profile>.
  • OPENCLAW_WORKSPACE_DIR ghi đè cả hai giá trị trên khi được đặt.
  • Các tác tử không phải mặc định (agents.list[]) không có không gian làm việc được chỉ định rõ ràng sẽ phân giải thành <state-dir>/workspace-<agentId>, không phải không gian làm việc mặc định dùng chung.

Ghi đè trong ~/.openclaw/openclaw.json:

json5
{  agents: {    defaults: {      workspace: "~/.openclaw/workspace",    },  },}

Ghi đè theo từng tác tử: agents.list[].workspace.

openclaw onboard, openclaw configure hoặc openclaw setup sẽ tạo không gian làm việc và cung cấp các tệp khởi tạo nếu chúng chưa tồn tại.

Nếu bạn đã tự quản lý các tệp trong không gian làm việc, hãy tắt việc tạo tệp khởi tạo:

json5
{ agents: { defaults: { skipBootstrap: true } } }

Các thư mục không gian làm việc bổ sung

Các bản cài đặt cũ có thể đã tạo ~/openclaw. Việc giữ nhiều thư mục không gian làm việc có thể gây nhầm lẫn về thông tin xác thực hoặc làm trạng thái sai lệch, vì mỗi thời điểm chỉ có một không gian làm việc hoạt động.

Sơ đồ tệp không gian làm việc

Các tệp tiêu chuẩn mà OpenClaw mong đợi có trong không gian làm việc:

AGENTS.md - hướng dẫn vận hành

Hướng dẫn vận hành cho tác tử và cách tác tử nên sử dụng bộ nhớ. Được tải khi bắt đầu mỗi phiên. Đây là nơi phù hợp để đặt các quy tắc, mức ưu tiên và chi tiết về "cách hành xử".

SOUL.md - cá tính và giọng điệu

Cá tính, giọng điệu và ranh giới. Được tải trong mọi phiên. Hướng dẫn: hướng dẫn cá tính SOUL.md.

USER.md - người dùng là ai

Thông tin về người dùng và cách xưng hô với họ. Được tải trong mọi phiên.

IDENTITY.md - tên, phong cách, emoji

Tên, phong cách và emoji của tác tử. Được tạo/cập nhật trong nghi thức khởi tạo.

TOOLS.md - quy ước công cụ cục bộ

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

HEARTBEAT.md - danh sách kiểm tra heartbeat

Danh sách kiểm tra nhỏ tùy chọn cho các lần chạy Heartbeat. Hãy giữ ngắn gọn để tránh tiêu tốn token.

BOOT.md - danh sách kiểm tra khi khởi động

Danh sách kiểm tra khi khởi động tùy chọn, được tự động chạy khi Gateway khởi động lại (khi bật hook nội bộ). Hãy giữ ngắn gọn; dùng công cụ tin nhắn để gửi ra ngoài.

BOOTSTRAP.md - nghi thức chạy lần đầu

Nghi thức chạy lần đầu chỉ thực hiện một lần. Chỉ được tạo cho không gian làm việc hoàn toàn mới. Xóa tệp sau khi hoàn tất nghi thức.

memory/YYYY-MM-DD.md - nhật ký bộ nhớ hằng ngày

Nhật ký bộ nhớ hằng ngày (mỗi ngày một tệp). Khuyến nghị đọc hôm nay + hôm qua khi bắt đầu phiên.

MEMORY.md - bộ nhớ dài hạn được tuyển chọn (tùy chọn)

Bộ nhớ dài hạn được tuyển chọn: các dữ kiện, tùy chọn, quyết định và bản tóm tắt ngắn có giá trị lâu dài. Giữ nhật ký chi tiết trong memory/YYYY-MM-DD.md để các công cụ bộ nhớ có thể truy xuất theo yêu cầu mà không chèn chúng vào mọi prompt. Chỉ tải MEMORY.md trong phiên chính, riêng tư (không phải ngữ cảnh dùng chung/nhóm). Xem Bộ nhớ để biết quy trình và cơ chế tự động ghi bộ nhớ.

skills/ - Skills của không gian làm việc (tùy chọn)

Skills dành riêng cho không gian làm việc. Đây là vị trí Skills có mức ưu tiên cao nhất cho không gian làm việc đó, đứng trước Skills của tác tử dự án, Skills cá nhân của tác tử, Skills được quản lý, Skills đi kèm và skills.load.extraDirs khi trùng tên.

canvas/ - các tệp giao diện Canvas (tùy chọn)

Các tệp giao diện Canvas dành cho màn hình Node (ví dụ: canvas/index.html).

Những gì KHÔNG nằm trong không gian làm việc

Các mục sau nằm trong ~/.openclaw/ và KHÔNG nên được commit vào repo không gian làm việc:

  • ~/.openclaw/openclaw.json (cấu hình)
  • ~/.openclaw/state/openclaw.sqlite (trạng thái thiết lập và chứng thực của không gian làm việc dùng chung)
  • ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (hồ sơ xác thực mô hình: OAuth + khóa API)
  • ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite (các hàng phiên, bản chép lời và trạng thái runtime theo từng tác tử)
  • ~/.openclaw/agents/<agentId>/agent/codex-home/ (tài khoản runtime Codex theo từng tác tử, cấu hình, Skills, plugin và trạng thái luồng gốc)
  • ~/.openclaw/credentials/ (trạng thái kênh/nhà cung cấp cùng dữ liệu nhập OAuth cũ)
  • ~/.openclaw/agents/<agentId>/sessions/ (nguồn di chuyển cũ và các thành phần lưu trữ/hỗ trợ)
  • ~/.openclaw/skills/ (Skills được quản lý)

Nếu cần di chuyển phiên hoặc cấu hình, hãy sao chép chúng riêng biệt và không đưa vào hệ thống kiểm soát phiên bản.

Các bản phát hành OpenClaw cũ đã ghi các tệp phụ không gian làm việc openclaw-workspace-state.json, .openclaw/workspace-state.json và .attested. Runtime hiện tại chỉ sử dụng cơ sở dữ liệu SQLite dùng chung cho trạng thái đó. Nếu Doctor báo cáo một trong các tệp này, hãy chạy openclaw doctor --fix; Doctor nhập trạng thái cũ hợp lệ và chỉ xóa nguồn sau khi xác minh các hàng trong cơ sở dữ liệu.

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

Hãy coi không gian làm việc là bộ nhớ riêng tư. Đặt nó trong một repo git riêng tư để có thể sao lưu và khôi phục.

Chạy các bước này trên máy đang chạy Gateway (đó là nơi không gian làm việc tồn tại).

  • Khởi tạo repo

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

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

  • Thêm remote riêng tư

    Giao diện web GitHub

    1. Tạo một kho lưu trữ riêng tư mới trên GitHub.
    2. Không khởi tạo bằng README (để tránh xung đột hợp nhất).
    3. Sao chép URL remote HTTPS.
    4. Thêm remote và đẩy lên:
    bash
    git branch -M maingit remote add origin <https-url>git push -u origin main

    GitHub CLI (gh)

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

    Giao diện web GitLab

    1. Tạo một kho lưu trữ riêng tư mới trên GitLab.
    2. Không khởi tạo bằng README (để tránh xung đột hợp nhất).
    3. Sao chép URL remote HTTPS.
    4. Thêm remote và đẩy lên:
    bash
    git branch -M maingit remote add origin <https-url>git push -u origin main

  • Cập nhật liên tục

    bash
    git statusgit add .git commit -m "Update memory"git push

    • Không commit bí mật

    Nội dung khởi đầu được đề xuất cho .gitignore:

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

    Di chuyển không gian làm việc sang máy mới

  • Sao chép repo

    Sao chép repo vào đường dẫn mong muốn (mặc định là ~/.openclaw/workspace).

  • Cập nhật cấu hình

    Đặt agents.defaults.workspace thành đường dẫn đó trong ~/.openclaw/openclaw.json.

  • Cung cấp các tệp còn thiếu

    Chạy openclaw setup --workspace <path> để cung cấp mọi tệp còn thiếu.

  • Sao chép phiên (tùy chọn)

    Nếu cần các phiên, hãy sao chép riêng ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite từ máy cũ. Chỉ sao chép ~/.openclaw/agents/<agentId>/sessions/ khi bạn cũng cần dữ liệu đầu vào cho quá trình di chuyển cũ hoặc các thành phần lưu trữ/hỗ trợ.

    • Ghi chú nâng cao

    • Định tuyến đa tác tử có thể sử dụng không gian làm việc khác nhau cho từng tác tử thông qua agents.list[].workspace. Xem Định tuyến kênh để biết cấu hình định tuyến.
    • Nếu bật agents.defaults.sandbox, các phiên không phải phiên chính có thể sử dụng không gian làm việc sandbox theo từng phiên trong agents.defaults.sandbox.workspaceRoot.

    Liên quan

    • Heartbeat - tệp không gian làm việc HEARTBEAT.md
    • Sandbox - quyền truy cập không gian làm việc trong môi trường sandbox
    • Phiên - đường dẫn lưu trữ phiên
    • Mệnh lệnh thường trực - hướng dẫn lâu dài trong các tệp không gian làm việc
    Was this useful?
    On this page

    On this page