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.

O workspace é o cwd padrão, não um sandbox rígido. As ferramentas resolvem caminhos relativos com base no workspace, mas caminhos absolutos ainda podem acessar outros locais no host, a menos que o isolamento por sandbox esteja habilitado. Se você precisar de isolamento, use agents.defaults.sandbox (e/ou uma configuração de sandbox por agente).Quando o isolamento por sandbox está habilitado e workspaceAccess não é "rw", as ferramentas operam dentro de um workspace de sandbox em ~/.openclaw/sandboxes, não no workspace 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>.
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:

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

As cópias iniciais do sandbox aceitam apenas arquivos regulares dentro do workspace; aliases de links simbólicos ou links físicos que apontam para fora do workspace de origem são ignorados.

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

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

Recomendação: mantenha um único workspace ativo. Se você não usa mais as pastas adicionais, arquive-as ou mova-as para a Lixeira (por exemplo, trash ~/openclaw). Se você mantiver intencionalmente vários workspaces, confirme que agents.defaults.workspace (ou a chave workspace por agente) aponta para o workspace ativo.

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

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

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:

cd ~/.openclaw/workspace
git init
git 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
CLI do GitHub (gh)
Interface web do GitLab

Crie um novo repositório privado no GitHub.
Não o inicialize com um README (isso evita conflitos de mesclagem).
Copie a URL HTTPS do remoto.
Adicione o remoto e envie:

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 o inicialize com um README (isso evita conflitos de mesclagem).
Copie a URL HTTPS do remoto.
Adicione o remoto e envie:

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 "Atualizar memória"
git push

Não envie segredos ao repositório

Mesmo em um repositório privado, evite armazenar segredos no workspace:

Chaves de API, tokens OAuth, senhas ou credenciais privadas.
Qualquer item em ~/.openclaw/.
Dumps brutos de conversas ou anexos sensíveis.

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

Sugestão inicial de .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

Heartbeat — arquivo HEARTBEAT.md do workspace
Isolamento por sandbox — acesso ao workspace em ambientes isolados por sandbox
Sessão — caminhos de armazenamento das sessões
Ordens permanentes — instruções persistentes nos arquivos do workspace

Fundamentals

Sessions and memory

Multi-agent

Messages and delivery

Espaço de trabalho do agente

Local padrão

Pastas adicionais de workspace

Mapa de arquivos do workspace

O que NÃO fica no workspace

Backup com Git (recomendado, privado)

Não envie segredos ao repositório

Como mover o workspace para uma nova máquina

Observações avançadas

Relacionados

​Local padrão

​Pastas adicionais de workspace

​Mapa de arquivos do workspace

​O que NÃO fica no workspace

​Backup com Git (recomendado, privado)

​Não envie segredos ao repositório

​Como mover o workspace para uma nova máquina

​Observações avançadas

​Relacionados

Local padrão

Pastas adicionais de workspace

Mapa de arquivos do workspace

O que NÃO fica no workspace

Backup com Git (recomendado, privado)

Não envie segredos ao repositório

Como mover o workspace para uma nova máquina

Observações avançadas

Relacionados