English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Fundamentals

Espaço de trabalho do agente

O espaço de trabalho é a casa do agente. Ele é o único diretório de trabalho usado para ferramentas de arquivo e para o contexto do espaço de trabalho. Mantenha-o privado e trate-o como memória.

Isso é separado de ~/.openclaw/, que armazena configuração, 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>.
  • Substitua em ~/.openclaw/openclaw.json:
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
}

openclaw onboard, openclaw configure ou openclaw setup criarão o espaço de trabalho e adicionarão os arquivos iniciais se eles estiverem ausentes.

Se você já gerencia os arquivos do espaço de trabalho por conta própria, pode desabilitar a criação de arquivos de bootstrap:

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

Pastas extras do espaço de trabalho

Instalações mais antigas podem ter criado ~/openclaw. Manter vários diretórios de espaço de trabalho pode causar confusão de autenticação ou desvio de estado, porque apenas um espaço de trabalho fica ativo por vez.

Mapa de arquivos do espaço de trabalho

Estes são os arquivos padrão que o OpenClaw espera dentro do espaço de trabalho:

AGENTS.md - instruções operacionais

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

SOUL.md - persona e tom

Persona, tom e limites. Carregado em todas as sessões. Guia: guia de personalidade 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, vibe, emoji

O nome, a vibe e o emoji do agente. Criado/atualizado durante o ritual de bootstrap.

TOOLS.md - convenções de ferramentas locais

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

HEARTBEAT.md - checklist de Heartbeat

Pequeno checklist opcional para execuções de Heartbeat. Mantenha-o curto para evitar gasto de tokens.

BOOT.md - checklist de inicialização

Checklist opcional de inicialização executado automaticamente no reinício do Gateway (quando hooks internos estão habilitados). Mantenha-o curto; use a ferramenta de mensagem para envios de saída.

BOOTSTRAP.md - ritual da primeira execução

Ritual único da primeira execução. Criado apenas para um espaço de trabalho totalmente novo. Exclua-o depois que o ritual estiver completo.

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

Registro diário de memória (um arquivo por dia). Recomendado ler hoje + ontem no início da sessão.

MEMORY.md - memória de longo prazo curada (opcional)

Memória de longo prazo curada. Carregue apenas na sessão principal e privada (não em contextos compartilhados/de grupo). Consulte Memória para ver o fluxo de trabalho e o flush automático de memória.

skills/ - Skills do espaço de trabalho (opcional)

Skills específicas do espaço de trabalho. Local de Skills de maior precedência para esse espaço de trabalho. Substitui Skills de agente do projeto, Skills pessoais do agente, Skills gerenciadas, Skills empacotadas e skills.load.extraDirs quando há colisão de nomes.

canvas/ - arquivos de UI do Canvas (opcional)

Arquivos de UI do Canvas para exibições de nodes (por exemplo, canvas/index.html).

O que NÃO fica no espaço de trabalho

Estes ficam em ~/.openclaw/ e NÃO devem ser commitados no repositório do espaço de trabalho:

  • ~/.openclaw/openclaw.json (configuração)
  • ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (perfis de autenticação de modelo: OAuth + chaves de API)
  • ~/.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 canal/provedor mais dados legados de importação OAuth)
  • ~/.openclaw/agents/<agentId>/sessions/ (transcrições de sessão + metadados)
  • ~/.openclaw/skills/ (Skills gerenciadas)

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

Backup com Git (recomendado, privado)

Trate o espaço de trabalho como memória privada. Coloque-o em um repositório git privado para que ele tenha backup e possa ser recuperado.

Execute estas etapas na máquina em que o Gateway roda (é onde o espaço de trabalho fica).

  • Inicialize o repositório

    Se git estiver instalado, espaços de trabalho totalmente novos são inicializados automaticamente. Se este espaço de trabalho ainda não for um repositório, execute:

    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"

  • Adicione um remoto privado

    UI web do GitHub

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

    GitHub CLI (gh)

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

    UI web do GitLab

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

  • Atualizações contínuas

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

    • Não commite segredos

    Sugestão inicial de .gitignore:

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

    Movendo o espaço de trabalho para uma nova máquina

  • Clone o repositório

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

  • Atualize a configuração

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

  • Adicione arquivos ausentes

    Execute openclaw setup --workspace <path> para adicionar quaisquer arquivos ausentes.

  • Copie sessões (opcional)

    Se você precisar de sessões, copie ~/.openclaw/agents/<agentId>/sessions/ separadamente da máquina antiga.

    • Observações avançadas

    • O roteamento multiagente pode usar espaços de trabalho diferentes por agente. Consulte Roteamento de canais para a configuração de roteamento.
    • Se agents.defaults.sandbox estiver habilitado, sessões não principais podem usar espaços de trabalho de sandbox por sessão em agents.defaults.sandbox.workspaceRoot.

    Relacionados