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

Fundamentals

Espaço de trabalho do agente

O workspace é a área principal do agente: o diretório de trabalho usado pelas ferramentas de arquivo e pelo contexto do workspace. Mantenha-o privado e trate-o como memória.

Isso é separado de ~/.openclaw/, que armazena configurações, credenciais e sessões.

Local padrão

  • Padrão: ~/.openclaw/workspace
  • Se OPENCLAW_PROFILE estiver definido e não for "default", o padrão passa a ser ~/.openclaw/workspace-<profile>.
  • OPENCLAW_WORKSPACE_DIR substitui ambos os valores acima quando definido.
  • Agentes não padrão (agents.list[]) sem um workspace explícito são resolvidos como <state-dir>/workspace-<agentId>, não como o workspace padrão compartilhado.

Substitua em ~/.openclaw/openclaw.json:

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

Substituição por agente: agents.list[].workspace.

openclaw onboard, openclaw configure ou openclaw setup criam o workspace e preenchem os arquivos de inicialização caso estejam ausentes.

Se você já gerencia os arquivos do workspace por conta própria, desabilite a criação dos arquivos de inicialização:

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

Pastas adicionais de workspace

Instalações mais antigas podem ter criado ~/openclaw. Manter vários diretórios de workspace pode causar confusão na autenticação ou divergência de estado, pois apenas um workspace fica ativo por vez.

Mapa de arquivos do workspace

Arquivos padrão que o OpenClaw espera encontrar no workspace:

AGENTS.md — instruções operacionais

Instruções operacionais para o agente e sobre como ele deve usar a memória. Carregado no início de cada sessão. É um bom lugar para regras, prioridades e detalhes sobre “como se comportar”.

SOUL.md — personalidade e tom

Personalidade, tom e limites. Carregado em todas as sessões. Guia: guia de personalidade do SOUL.md.

USER.md — quem é o usuário

Quem é o usuário e como se dirigir a ele. Carregado em todas as sessões.

IDENTITY.md — nome, estilo e emoji

O nome, o estilo e o emoji do agente. Criado/atualizado durante o ritual de inicialização.

TOOLS.md — convenções das ferramentas locais

Observações sobre suas ferramentas e convenções locais. Não controla a disponibilidade das ferramentas; serve apenas como orientação.

HEARTBEAT.md — lista de verificação do Heartbeat

Pequena lista de verificação opcional para execuções de Heartbeat. Mantenha-a curta para evitar o consumo excessivo de tokens.

BOOT.md — lista de verificação de inicialização

Lista de verificação opcional de inicialização, executada automaticamente quando o Gateway reinicia (quando os hooks internos estão habilitados). Mantenha-a curta; use a ferramenta de mensagens para envios de saída.

BOOTSTRAP.md — ritual da primeira execução

Ritual único da primeira execução. Criado apenas para um workspace totalmente novo. Exclua-o após a conclusão do ritual.

memory/YYYY-MM-DD.md — registro diário de memória

Registro diário de memória (um arquivo por dia). Recomenda-se ler o registro de hoje e o de ontem no início da sessão.

MEMORY.md — memória de longo prazo selecionada (opcional)

Memória de longo prazo selecionada: fatos duradouros, preferências, decisões e resumos breves. Mantenha os registros detalhados em memory/YYYY-MM-DD.md para que as ferramentas de memória possam recuperá-los sob demanda sem inseri-los em todos os prompts. Carregue MEMORY.md apenas na sessão principal e privada (não em contextos compartilhados ou de grupo). Consulte Memória para ver o fluxo de trabalho e a descarga automática da memória.

skills/ — Skills do workspace (opcional)

Skills específicas do workspace. Local de Skills com a precedência mais alta para esse workspace, à frente das Skills de agente do projeto, Skills pessoais do agente, Skills gerenciadas, Skills incluídas e skills.load.extraDirs quando houver conflito de nomes.

canvas/ — arquivos da interface Canvas (opcional)

Arquivos da interface Canvas para exibições em Nodes (por exemplo, canvas/index.html).

O que NÃO fica no workspace

Os itens a seguir ficam em ~/.openclaw/ e NÃO devem ser enviados ao repositório do workspace:

  • ~/.openclaw/openclaw.json (configuração)
  • ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (perfis de autenticação de modelos: OAuth + chaves de API)
  • ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite (registros de sessões, transcrições e estado de runtime por agente)
  • ~/.openclaw/agents/<agentId>/agent/codex-home/ (conta, configuração, Skills, plugins e estado nativo de threads do runtime Codex por agente)
  • ~/.openclaw/credentials/ (estado de canais/provedores e dados legados de importação do OAuth)
  • ~/.openclaw/agents/<agentId>/sessions/ (fontes de migração legadas e artefatos de arquivamento/suporte)
  • ~/.openclaw/skills/ (Skills gerenciadas)

Se você precisar migrar sessões ou configurações, copie-as separadamente e mantenha-as fora do controle de versão.

Backup com Git (recomendado, privado)

Trate o workspace como memória privada. Coloque-o em um repositório Git privado para que tenha backup e possa ser recuperado.

Execute estas etapas na máquina em que o Gateway é executado (é nela que fica o workspace).

  • Inicialize o repositório

    Se o Git estiver instalado, workspaces novos serão inicializados automaticamente. Se este workspace ainda não for um repositório, execute:

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

  • Adicione um remoto privado

    Interface web do GitHub

    1. Crie um novo repositório privado no GitHub.
    2. Não o inicialize com um README (isso evita conflitos de mesclagem).
    3. Copie a URL HTTPS do remoto.
    4. Adicione o remoto e envie:
    bash
    git branch -M maingit remote add origin <https-url>git push -u origin main

    CLI do GitHub (gh)

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

    Interface web do GitLab

    1. Crie um novo repositório privado no GitLab.
    2. Não o inicialize com um README (isso evita conflitos de mesclagem).
    3. Copie a URL HTTPS do remoto.
    4. Adicione o remoto e envie:
    bash
    git branch -M maingit remote add origin <https-url>git push -u origin main

  • Atualizações contínuas

    bash
    git statusgit add .git commit -m "Atualizar memória"git push

    • Não envie segredos ao repositório

    Sugestão inicial de .gitignore:

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

    Como mover o workspace para uma nova máquina

  • Clone o repositório

    Clone o repositório no caminho desejado (o padrão é ~/.openclaw/workspace).

  • Atualize a configuração

    Defina agents.defaults.workspace como esse caminho em ~/.openclaw/openclaw.json.

  • Crie os arquivos ausentes

    Execute openclaw setup --workspace <path> para criar os arquivos ausentes.

  • Copie as sessões (opcional)

    Se você precisar das sessões, copie ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite separadamente da máquina antiga. Copie ~/.openclaw/agents/<agentId>/sessions/ apenas quando também precisar de entradas de migração legadas ou artefatos de arquivamento/suporte.

    • Observações avançadas

    • O roteamento de múltiplos agentes pode usar workspaces diferentes para cada agente por meio de agents.list[].workspace. Consulte Roteamento de canais para ver a configuração de roteamento.
    • Se agents.defaults.sandbox estiver habilitado, sessões que não sejam a principal poderão usar workspaces de sandbox por sessão em agents.defaults.sandbox.workspaceRoot.

    Relacionados

    Was this useful?
    On this page

    On this page