Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

O workspace é a casa do agente. Ele é o único diretório de trabalho usado para ferramentas de arquivo 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.
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 acessar outros locais no host, a menos que o sandboxing esteja ativado. Se você precisar de isolamento, use agents.defaults.sandbox (e/ou configuração de sandbox por agente).Quando o sandboxing está ativado e workspaceAccess não é "rw", as ferramentas operam dentro de um workspace de sandbox em ~/.openclaw/sandboxes, não no seu 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>.
  • Substitua em ~/.openclaw/openclaw.json:
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
}
openclaw onboard, openclaw configure ou openclaw setup criarão o workspace e semearão os arquivos de bootstrap se eles estiverem ausentes.
As cópias de seed do sandbox aceitam apenas arquivos regulares dentro do workspace; aliases de symlink/hardlink que resolvem para fora do workspace de origem são ignorados.
Se você já gerencia os arquivos do workspace por conta própria, pode desativar a criação de arquivos de bootstrap: 
{ agents: { defaults: { skipBootstrap: true } } }

​
Pastas extras de workspace

Instalações mais antigas podem ter criado ~/openclaw. Manter vários diretórios de workspace pode causar confusão de autenticação ou desvio 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ê mantém vários workspaces intencionalmente, certifique-se de que agents.defaults.workspace aponte para o ativo.openclaw doctor avisa quando detecta diretórios extras de workspace.

​
Mapa de arquivos do workspace

Estes são os arquivos padrão que o OpenClaw espera dentro do workspace:
Instruções operacionais para o agente e como ele deve usar a memória. Carregadas no início de cada sessão. Bom lugar para regras, prioridades e detalhes de “como se comportar”.
Persona, tom e limites. Carregado em todas as sessões. Guia: guia de personalidade SOUL.md.
Quem é o usuário e como se dirigir a ele. Carregado em todas as sessões.
O nome, a vibe e o emoji do agente. Criado/atualizado durante o ritual de bootstrap.
Observações sobre suas ferramentas locais e convenções. Não controla a disponibilidade de ferramentas; é apenas orientação.
Pequeno checklist opcional para execuções de Heartbeat. Mantenha-o curto para evitar gasto de tokens.
Checklist opcional de inicialização executado automaticamente no reinício do Gateway (quando hooks internos estão ativados). Mantenha-o curto; use a ferramenta de mensagens para envios de saída.
Ritual único de primeira execução. Criado apenas para um workspace totalmente novo. Exclua-o depois que o ritual for concluído.
Registro diário de memória (um arquivo por dia). Recomendado ler hoje + ontem no início da sessão.
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 o fluxo de trabalho e a descarga automática de memória.
Skills específicas do workspace. Local de Skill com maior precedência para esse workspace. Substitui skills de agente do projeto, skills de agente pessoais, skills gerenciadas, skills incluídas e skills.load.extraDirs quando há colisão de nomes.
Arquivos de UI 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 grandes de bootstrap são truncados quando injetados; ajuste os limites com agents.defaults.bootstrapMaxChars (padrão: 12000) e agents.defaults.bootstrapTotalMaxChars (padrão: 60000). openclaw setup pode recriar padrões ausentes sem sobrescrever arquivos existentes.

​
O que NÃO fica no workspace

Estes ficam em ~/.openclaw/ e NÃO devem ser commitados no repositório do workspace:
  • ~/.openclaw/openclaw.json (configuração)
  • ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (perfis de autenticação do 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 em Git (recomendado, privado)

Trate o workspace 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 workspace fica).
1

Inicialize o repositório

Se o git estiver instalado, workspaces totalmente 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 "Add agent workspace"
2

Adicione um remote privado

  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:
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 commite segredos

Mesmo em um repositório privado, evite armazenar segredos no workspace:
  • Chaves de API, tokens OAuth, senhas ou credenciais privadas.
  • Qualquer coisa em ~/.openclaw/.
  • Dumps brutos de conversas 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*

​
Movendo o workspace para uma nova máquina

1

Clone o repositório

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

Atualize a configuração

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

Semeie arquivos ausentes

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

Copie 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 workspaces diferentes por agente. Consulte Roteamento de canais para a configuração de roteamento.
  • Se agents.defaults.sandbox estiver ativado, sessões não principais podem usar workspaces de sandbox por sessão em agents.defaults.sandbox.workspaceRoot.

​
Relacionados

  • Heartbeat - arquivo de workspace HEARTBEAT.md
  • Sandboxing - acesso ao workspace em ambientes com sandbox
  • Sessão - caminhos de armazenamento de sessão
  • Ordens permanentes - instruções persistentes em arquivos do workspace