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.

O espaço de trabalho é o cwd padrão, não uma sandbox rígida. As ferramentas resolvem caminhos relativos a partir do espaço de trabalho, mas caminhos absolutos ainda podem alcançar outros lugares no host, a menos que a sandbox esteja habilitada. Se você precisar de isolamento, use agents.defaults.sandbox (e/ou a configuração de sandbox por agente).Quando a sandbox está habilitada e workspaceAccess não é "rw", as ferramentas operam dentro de um espaço de trabalho em sandbox em ~/.openclaw/sandboxes, não no espaço de trabalho do host.

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 inicializarão os arquivos de bootstrap se eles estiverem ausentes.

As cópias de inicialização da sandbox aceitam apenas arquivos regulares dentro do espaço de trabalho; aliases de symlink/hardlink que resolvem para fora do espaço de trabalho de origem são ignorados.

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 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.

Recomendação: mantenha um único espaço de trabalho ativo. Se você não usa mais as pastas extras, arquive-as ou mova-as para a Lixeira (por exemplo, trash ~/openclaw). Se você mantém vários espaços de trabalho intencionalmente, confira se agents.defaults.workspace aponta para o ativo.openclaw doctor avisa quando detecta diretórios extras de espaço de trabalho.

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).

Se algum arquivo de bootstrap estiver ausente, o OpenClaw injeta um marcador de “arquivo ausente” na sessão e continua. Arquivos de bootstrap grandes são truncados quando injetados; ajuste os limites com agents.defaults.bootstrapMaxChars (padrão: 20000) e agents.defaults.bootstrapTotalMaxChars (padrão: 60000). openclaw setup pode recriar padrões ausentes sem sobrescrever arquivos existentes.

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:

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"

Adicionar um remote privado

Interface web do GitHub
GitHub CLI (gh)
Interface web do GitLab

Crie um novo repositório privado no GitHub.
Não inicialize com um README (evita conflitos de merge).
Copie a URL remota HTTPS.
Adicione o remote e faça push:

git branch -M main
git remote add origin <https-url>
git push -u origin main

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

Crie um novo repositório privado no GitLab.
Não inicialize com um README (evita conflitos de merge).
Copie a URL remota HTTPS.
Adicione o remote 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

Mesmo em um repositório privado, evite armazenar segredos no espaço de trabalho:

Chaves de API, tokens OAuth, senhas ou credenciais privadas.
Qualquer coisa em ~/.openclaw/.
Despejos brutos de chats ou anexos sensíveis.

Se você precisar armazenar referências sensíveis, use placeholders e mantenha o segredo real em outro lugar (gerenciador de senhas, variáveis de ambiente ou ~/.openclaw/).

Modelo inicial sugerido de .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

​Local padrão

​Pastas extras do espaço de trabalho

​Mapa de arquivos do espaço de trabalho

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

​Backup com git (recomendado, privado)

​Não commite segredos

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

​Observações avançadas

​Relacionado

Local padrão

Pastas extras do espaço de trabalho

Mapa de arquivos do espaço de trabalho

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

Backup com git (recomendado, privado)

Não commite segredos

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

Observações avançadas

Relacionado