English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

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:
json5
{  agents: {    defaults: {      workspace: "~/.openclaw/workspace",    },  },}

openclaw onboard, openclaw configure ou openclaw setup criarão o espaço de trabalho e inicializarão os arquivos de bootstrap 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:

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

Pastas extras do espaço de trabalho

Instalações antigas podem ter criado ~/openclaw. Manter vários diretórios de espaço de trabalho pode causar confusão de autenticação ou divergência 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 e convenções locais. Não controla a disponibilidade das ferramentas; serve apenas como 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 na reinicialização 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 for concluído.

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: fatos duráveis, preferências, decisões e resumos curtos. Mantenha registros detalhados em memory/YYYY-MM-DD.md para que as ferramentas de memória possam recuperá-los sob demanda sem injetá-los em cada prompt. Carregue MEMORY.md 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 com maior precedência para esse espaço de trabalho. Sobrescreve Skills de agente do projeto, Skills pessoais de agente, Skills gerenciadas, Skills incluídas e skills.load.extraDirs quando os nomes entram em conflito.

canvas/ - arquivos de interface do usuário do Canvas (opcional)

Arquivos de interface do usuário do Canvas para exibições de nós (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 de runtime Codex por agente, configuração, Skills, Plugins e estado nativo de threads)
  • ~/.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 onde o Gateway roda (é onde o espaço de trabalho fica).

  • Inicializar o repositório

    Se o git estiver instalado, espaços de trabalho novos são inicializados automaticamente. Se este espaço de trabalho 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 "Add agent workspace"

  • Adicionar um remote privado

    Interface 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 remote e faça push:
    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

    Interface 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 remote e faça push:
    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 "Update memory"git push

    • Não commite segredos

    Modelo inicial sugerido de .gitignore:

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

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

  • Clonar o repositório

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

  • Atualizar a configuração

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

  • Inicializar arquivos ausentes

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

  • Copiar sessões (opcional)

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

    • Observações avançadas

    • O roteamento multiagente pode usar espaços de trabalho diferentes por agente. Consulte Roteamento de canais para ver 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.

    Relacionado

    • Heartbeat - arquivo de espaço de trabalho HEARTBEAT.md
    • Sandboxing - acesso ao espaço de trabalho em ambientes com sandbox
    • Sessão - caminhos de armazenamento de sessão
    • Ordens permanentes - instruções persistentes em arquivos do espaço de trabalho
    Was this useful?
    On this page

    On this page