Saltar para o conteúdo principal

​
Workspace do agente

O workspace é a casa do agente. É o único diretório de trabalho usado para ferramentas de arquivos e para o contexto do workspace. Mantenha-o privado e trate-o como memória. Isso é separado de ~/.openclaw/, que armazena configuração, credenciais e sessões. Importante: o workspace é o cwd padrão, não um sandbox rígido. As ferramentas resolvem caminhos relativos em relação ao workspace, mas caminhos absolutos ainda podem alcançar outros locais no host, a menos que o sandboxing esteja habilitado. Se você precisa de isolamento, use agents.defaults.sandbox (e/ou configuração de sandbox por agente). Quando o sandboxing está habilitado e workspaceAccess não é "rw", as ferramentas operam dentro de um workspace em sandbox sob ~/.openclaw/sandboxes, não no workspace do host.

​
Localização 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>.
  • Substituição em ~/.openclaw/openclaw.json:
{
  agent: {
    workspace: "~/.openclaw/workspace",
  },
}
openclaw onboard, openclaw configure ou openclaw setup criarão o workspace e semearão os arquivos de bootstrap se estiverem ausentes. Se você já gerencia os arquivos do workspace por conta própria, pode desativar a criação de arquivos de bootstrap: 
{ agent: { skipBootstrap: true } }

​
Pastas extras do workspace

Instalações mais antigas podem ter criado ~/openclaw. Manter vários diretórios de workspace pode causar confusão de autenticação ou divergência de estado, porque apenas um workspace fica ativo por vez. Recomendação: mantenha um único workspace ativo. Se você não usa mais as pastas extras, arquive-as ou mova-as para a Lixeira (por exemplo trash ~/openclaw). Se você mantiver intencionalmente vários workspaces, garanta que agents.defaults.workspace aponte para o ativo. openclaw doctor avisa quando detecta diretórios extras de workspace.

​
Mapa de arquivos do workspace (o que cada arquivo significa)

Estes são os arquivos padrão que o OpenClaw espera dentro do workspace:
  • AGENTS.md
    • 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, tom e limites.
    • Carregado em todas as sessões.
  • USER.md
    • Quem é o usuário e como se dirigir a ele.
    • Carregado em todas as sessões.
  • IDENTITY.md
    • Nome do agente, vibe e emoji.
    • Criado/atualizado durante o ritual de bootstrap.
  • TOOLS.md
    • Anotações sobre suas ferramentas e convenções locais.
    • Não controla a disponibilidade de ferramentas; é apenas orientação.
  • HEARTBEAT.md
    • Checklist pequeno opcional para execuções de heartbeat.
    • Mantenha curto para evitar gasto de tokens.
  • BOOT.md
    • Checklist de inicialização opcional executado no reinício do gateway quando hooks internos estão habilitados.
    • Mantenha curto; use a ferramenta de mensagens para envios de saída.
  • BOOTSTRAP.md
    • Ritual de primeira execução, único.
    • Criado apenas para um workspace totalmente novo.
    • Exclua após a conclusão do ritual.
  • memory/YYYY-MM-DD.md
    • Log diário de memória (um arquivo por dia).
    • Recomendado ler hoje + ontem no início da sessão.
  • MEMORY.md (opcional)
    • Memória de longo prazo curada.
    • Carregar apenas na sessão principal e privada (não em contextos compartilhados/de grupo).
Veja Memory para o fluxo de trabalho e o descarte automático de memória.
  • skills/ (opcional)
    • Skills específicas do workspace.
    • Substitui Skills gerenciadas/empacotadas quando os nomes colidem.
  • canvas/ (opcional)
    • Arquivos de UI do Canvas para exibição 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 grandes de bootstrap são truncados quando injetados; ajuste o limite com agents.defaults.bootstrapMaxChars (padrão: 20000). openclaw setup pode recriar padrões ausentes sem sobrescrever arquivos existentes.

​
O que NÃO está no workspace

Eles ficam sob ~/.openclaw/ e NÃO devem ser versionados no repositório do workspace:
  • ~/.openclaw/openclaw.json (configuração)
  • ~/.openclaw/credentials/ (tokens OAuth, chaves de API)
  • ~/.openclaw/agents/<agentId>/sessions/ (transcrições de sessão + metadados)
  • ~/.openclaw/skills/ (Skills gerenciadas)
Se você precisar migrar sessões ou configuração, copie-os separadamente e mantenha-os 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 fique com backup e recuperável. Execute estas etapas na máquina onde o Gateway é executado (é lá que o workspace fica).

​
1. Inicialize o repositório

Se o git estiver instalado, workspaces novos em folha sã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 "Add agent workspace"

​
2. Adicione um remoto privado (opções amigáveis para iniciantes)

Opção A: Interface web do GitHub
  1. Crie um novo repositório privado no GitHub.
  2. Não inicialize com README (evita conflitos de merge).
  3. Copie a URL HTTPS do remoto.
  4. Adicione o remoto e faça o push:
git branch -M main
git remote add origin <https-url>
git push -u origin main
Opção B: GitHub CLI (gh) 
gh auth login
gh repo create openclaw-workspace --private --source . --remote origin --push
Opção C: Interface web do GitLab
  1. Crie um novo repositório privado no GitLab.
  2. Não inicialize com README (evita conflitos de merge).
  3. Copie a URL HTTPS do remoto.
  4. Adicione o remoto e faça o push:
git branch -M main
git remote add origin <https-url>
git push -u origin main

​
3. Atualizações contínuas

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

​
Não versione segredos

Mesmo em um repositório privado, evite armazenar segredos no workspace:
  • Chaves de API, tokens OAuth, senhas ou credenciais privadas.
  • Qualquer coisa sob ~/.openclaw/.
  • Dumps 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/). Starter sugerido para .gitignore: 
.DS_Store
.env
**/*.key
**/*.pem
**/secrets*

​
Movendo o workspace para uma nova máquina

  1. Clone o repositório para o caminho desejado (padrão ~/.openclaw/workspace).
  2. Defina agents.defaults.workspace para esse caminho em ~/.openclaw/openclaw.json.
  3. Execute openclaw setup --workspace <path> para semear quaisquer arquivos ausentes.
  4. Se você precisar de sessões, copie ~/.openclaw/agents/<agentId>/sessions/ da máquina antiga separadamente.

​
Notas avançadas

  • O roteamento multiagente pode usar workspaces diferentes por agente. Veja Channel routing para a configuração de roteamento.
  • Se agents.defaults.sandbox estiver habilitado, sessões que não são a principal podem usar workspaces em sandbox por sessão sob agents.defaults.sandbox.workspaceRoot.