Migrar do OpenClaw

O hermes claw migrate importa a sua configuração do OpenClaw (ou do antigo Clawdbot/Moldbot) para o Hermes. Este guia mostra exatamente o que é migrado, o mapeamento das chaves de configuração e o que conferir depois da migração.

observação

Está vindo do Claude Code ou do OpenAI Codex CLI? Use o hermes import-agent.

dica

Se a sua instalação do OpenClaw usava vários provedores, o hermes setup --portal reduz tudo a um único OAuth — mais de 300 modelos e o Tool Gateway num só login. Veja Nous Portal.

Início rápido

# Prévia e migração (sempre mostra uma prévia antes e pede confirmação)
hermes claw migrate

# Só a prévia, sem alterar nada
hermes claw migrate --dry-run

# Migração completa incluindo chaves de API, sem confirmação
hermes claw migrate --preset full --migrate-secrets --yes

A migração sempre mostra uma prévia completa do que será importado antes de mudar qualquer coisa. Revise a lista e confirme para seguir.

Por padrão, lê de ~/.openclaw/. Diretórios antigos ~/.clawdbot/ ou ~/.moltbot/ são detectados automaticamente. O mesmo vale para os nomes antigos de arquivo de configuração (clawdbot.json, moltbot.json).

Opções

Opção	Descrição
--dry-run	Só a prévia — para depois de mostrar o que seria migrado.
--preset <name>	full (todas as configurações compatíveis) ou user-data (exclui a configuração de infraestrutura). Nenhum dos dois importa segredos por padrão — passe --migrate-secrets explicitamente.
--overwrite	Sobrescreve arquivos existentes do Hermes em caso de conflito (por padrão, a migração se recusa a aplicar quando o plano tem conflitos).
--migrate-secrets	Inclui as chaves de API. Necessário mesmo com --preset full — nenhum preset importa segredos em silêncio.
--no-backup	Pula o snapshot zip de ~/.hermes/ feito antes da migração (por padrão, um único arquivo de ponto de restauração é gravado antes de aplicar, em ~/.hermes/backups/pre-migration-*.zip; restaurável com hermes import).
--source <path>	Diretório do OpenClaw personalizado.
--workspace-target <path>	Onde colocar o AGENTS.md.
--skill-conflict <mode>	skip (padrão), overwrite ou rename.
--yes	Pula a confirmação depois da prévia.

O que é migrado

Persona, memória e instruções

O quê	Origem no OpenClaw	Destino no Hermes	Observações
Persona	workspace/SOUL.md	~/.hermes/SOUL.md	Cópia direta
Instruções do espaço de trabalho	workspace/AGENTS.md	AGENTS.md em --workspace-target	Exige a opção --workspace-target
Memória de longo prazo	workspace/MEMORY.md	~/.hermes/memories/MEMORY.md	É dividida em entradas, mesclada com as existentes e deduplicada. Usa o delimitador §.
Perfil do usuário	workspace/USER.md	~/.hermes/memories/USER.md	Mesma lógica de mesclagem por entrada da memória.
Arquivos de memória diária	workspace/memory/*.md	~/.hermes/memories/MEMORY.md	Todos os arquivos diários são mesclados na memória principal.

Os arquivos do espaço de trabalho também são procurados em workspace.default/ e workspace-main/ como caminhos alternativos (o OpenClaw renomeou workspace/ para workspace-main/ nas versões recentes e usa workspace-{agentId} em instalações com vários agentes).

Skills (4 origens)

Origem	Local no OpenClaw	Destino no Hermes
Skills do espaço de trabalho	workspace/skills/	~/.hermes/skills/openclaw-imports/
Skills gerenciadas/compartilhadas	~/.openclaw/skills/	~/.hermes/skills/openclaw-imports/
Pessoais entre projetos	~/.agents/skills/	~/.hermes/skills/openclaw-imports/
Compartilhadas no projeto	workspace/.agents/skills/	~/.hermes/skills/openclaw-imports/

Conflitos de skill são tratados pelo --skill-conflict: skip mantém a skill que já existe no Hermes, overwrite substitui e rename cria uma cópia com sufixo -imported.

Configuração de modelos e provedores

O quê	Caminho na config do OpenClaw	Destino no Hermes	Observações
Modelo padrão	agents.defaults.model	config.yaml → model	Pode ser uma string ou um objeto {primary, fallbacks}
Provedores personalizados	models.providers.*	config.yaml → custom_providers (migrado automaticamente para o dicionário canônico providers: na próxima migração de configuração do hermes update)	Mapeia baseUrl, apiType/api — lida tanto com os valores curtos ("openai", "anthropic") quanto com os hifenizados ("openai-completions", "anthropic-messages", "google-generative-ai")
Chaves de API dos provedores	models.providers.*.apiKey	~/.hermes/.env	Exige --migrate-secrets. Veja Resolução de chaves de API abaixo.

Comportamento do agente

O quê	Caminho na config do OpenClaw	Caminho na config do Hermes	Mapeamento
Máximo de turnos	agents.defaults.timeoutSeconds	agent.max_turns	timeoutSeconds / 10, limitado a 200
Modo verboso	agents.defaults.verboseDefault	agent.verbose	"off" / "on" / "full"
Esforço de raciocínio	agents.defaults.thinkingDefault	agent.reasoning_effort	"always"/"high"/"xhigh" → "high", "auto"/"medium"/"adaptive" → "medium", "off"/"low"/"none"/"minimal" → "low"
Compressão	agents.defaults.compaction.mode	compression.enabled	"off" → false, qualquer outro valor → true
Modelo de compressão	agents.defaults.compaction.model	compression.summary_model	Cópia direta da string
Atraso humano	agents.defaults.humanDelay.mode	human_delay.mode	"natural" / "custom" / "off"
Tempos do atraso humano	agents.defaults.humanDelay.minMs / .maxMs	human_delay.min_ms / .max_ms	Cópia direta
Fuso horário	agents.defaults.userTimezone	timezone	Cópia direta da string
Timeout de execução	tools.exec.timeoutSec	terminal.timeout	Cópia direta (o campo é timeoutSec, não timeout)
Sandbox Docker	agents.defaults.sandbox.backend	terminal.backend	"docker" → "docker"
Imagem Docker	agents.defaults.sandbox.docker.image	terminal.docker_image	Cópia direta

Políticas de reinício de sessão

Caminho na config do OpenClaw	Caminho na config do Hermes	Observações
session.reset.mode	session_reset.mode	"daily", "idle" ou os dois
session.reset.atHour	session_reset.at_hour	Hora (0–23) do reinício diário
session.reset.idleMinutes	session_reset.idle_minutes	Minutos de inatividade

Observação: o OpenClaw também tem session.resetTriggers (um vetor simples de strings, como ["daily", "idle"]). Se o session.reset estruturado não existir, a migração cai para a inferência a partir do resetTriggers.

Servidores MCP

Campo do OpenClaw	Campo do Hermes	Observações
mcp.servers.*.command	mcp_servers.*.command	Transporte stdio
mcp.servers.*.args	mcp_servers.*.args
mcp.servers.*.env	mcp_servers.*.env
mcp.servers.*.cwd	mcp_servers.*.cwd
mcp.servers.*.url	mcp_servers.*.url	Transporte HTTP/SSE
mcp.servers.*.tools.include	mcp_servers.*.tools.include	Filtro de ferramentas
mcp.servers.*.tools.exclude	mcp_servers.*.tools.exclude

TTS (síntese de voz)

As configurações de TTS são lidas de dois locais da configuração do OpenClaw, nesta ordem de prioridade:

1. messages.tts.providers.{provider}.* (local canônico)
2. talk.providers.{provider}.* no nível raiz (alternativa)
3. Chaves planas antigas messages.tts.{provider}.* (formato mais velho)

O quê	Destino no Hermes
Nome do provedor	config.yaml → tts.provider
ID de voz do ElevenLabs	config.yaml → tts.elevenlabs.voice_id
ID de modelo do ElevenLabs	config.yaml → tts.elevenlabs.model_id
Modelo da OpenAI	config.yaml → tts.openai.model
Voz da OpenAI	config.yaml → tts.openai.voice
Voz do Edge TTS	config.yaml → tts.edge.voice (o OpenClaw renomeou "edge" para "microsoft" — os dois são reconhecidos)
Arquivos de TTS	~/.hermes/tts/ (cópia de arquivo)

Plataformas de mensagens

Plataforma	Caminho na config do OpenClaw	Variável no .env do Hermes	Observações
Telegram	channels.telegram.botToken ou .accounts.default.botToken	TELEGRAM_BOT_TOKEN	O token pode ser uma string ou um SecretRef. Os dois formatos, plano e por contas, são suportados.
Telegram	credentials/telegram-default-allowFrom.json	TELEGRAM_ALLOWED_USERS	Juntado por vírgulas a partir do vetor allowFrom[]
Discord	channels.discord.token ou .accounts.default.token	DISCORD_BOT_TOKEN
Discord	channels.discord.allowFrom ou .accounts.default.allowFrom	DISCORD_ALLOWED_USERS
Slack	channels.slack.botToken ou .accounts.default.botToken	SLACK_BOT_TOKEN
Slack	channels.slack.appToken ou .accounts.default.appToken	SLACK_APP_TOKEN
Slack	channels.slack.allowFrom ou .accounts.default.allowFrom	SLACK_ALLOWED_USERS
WhatsApp	channels.whatsapp.allowFrom ou .accounts.default.allowFrom	WHATSAPP_ALLOWED_USERS	Autenticação por pareamento com QR do Baileys — é preciso parear de novo depois da migração
Signal	channels.signal.account ou .accounts.default.account	SIGNAL_ACCOUNT
Signal	channels.signal.httpUrl ou .accounts.default.httpUrl	SIGNAL_HTTP_URL
Signal	channels.signal.allowFrom ou .accounts.default.allowFrom	SIGNAL_ALLOWED_USERS
Matrix	channels.matrix.accessToken ou .accounts.default.accessToken	MATRIX_ACCESS_TOKEN	Usa accessToken (não botToken)
Mattermost	channels.mattermost.botToken ou .accounts.default.botToken	MATTERMOST_BOT_TOKEN

Outras configurações

O quê	Caminho no OpenClaw	Caminho no Hermes	Observações
Modo de aprovação	approvals.exec.mode	config.yaml → approvals.mode	"auto"→"off", "always"→"manual", "smart"→"smart"
Lista de comandos permitidos	exec-approvals.json	config.yaml → command_allowlist	Padrões mesclados e deduplicados
URL do CDP do navegador	browser.cdpUrl	config.yaml → browser.cdp_url
Navegador headless	browser.headless	config.yaml → browser.headless
Chave de busca do Brave	tools.web.search.brave.apiKey	.env → BRAVE_API_KEY	Exige --migrate-secrets
Token de autenticação do gateway	gateway.auth.token	.env → HERMES_GATEWAY_TOKEN	Exige --migrate-secrets
Diretório de trabalho	agents.defaults.workspace	config.yaml → terminal.cwd	Migrações antigas ainda podem gerar MESSAGING_CWD como alternativa de compatibilidade

Arquivado (sem equivalente direto no Hermes)

Estes itens são salvos em ~/.hermes/migration/openclaw/<timestamp>/archive/ para revisão manual:

O quê	Arquivo no acervo	Como recriar no Hermes
IDENTITY.md	archive/workspace/IDENTITY.md	Mescle no SOUL.md
TOOLS.md	archive/workspace/TOOLS.md	O Hermes já traz instruções de ferramentas embutidas
HEARTBEAT.md	archive/workspace/HEARTBEAT.md	Use tarefas cron para o que é periódico
BOOTSTRAP.md	archive/workspace/BOOTSTRAP.md	Use arquivos de contexto ou skills
Tarefas cron	archive/cron-config.json	Recrie com hermes cron create
Plugins	archive/plugins-config.json	Veja o guia de plugins
Hooks/webhooks	archive/hooks-config.json	Use hermes webhook ou os hooks do gateway
Backend de memória	archive/memory-backend-config.json	Configure com hermes honcho
Registro de skills	archive/skills-registry-config.json	Use hermes skills config
Interface/identidade	archive/ui-identity-config.json	Use o comando /skin
Logs	archive/logging-diagnostics-config.json	Ajuste na seção de logging do config.yaml
Lista de vários agentes	archive/agents-list.json	Use os perfis do Hermes
Vínculos de canal	archive/bindings.json	Configuração manual por plataforma
Canais complexos	archive/channels-deep-config.json	Configuração manual da plataforma

Resolução de chaves de API

Com o --migrate-secrets ativado, as chaves de API são coletadas de quatro origens, nesta ordem de prioridade:

1. Valores da configuração — models.providers.*.apiKey e as chaves dos provedores de TTS no openclaw.json
2. Arquivo de ambiente — ~/.openclaw/.env (chaves como OPENROUTER_API_KEY, ANTHROPIC_API_KEY etc.)
3. Sub-objeto env da configuração — openclaw.json → "env" ou "env"."vars" (algumas instalações guardam as chaves aí em vez de num .env separado)
4. Perfis de autenticação — ~/.openclaw/agents/main/agent/auth-profiles.json (credenciais por agente)

Os valores da configuração têm prioridade. Cada origem seguinte preenche o que ainda estiver faltando.

Destinos de chave suportados

OPENROUTER_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, DEEPSEEK_API_KEY, GEMINI_API_KEY, ZAI_API_KEY, MINIMAX_API_KEY, ELEVENLABS_API_KEY, TELEGRAM_BOT_TOKEN, VOICE_TOOLS_OPENAI_KEY

Chaves fora dessa lista nunca são copiadas.

Tratamento de SecretRef

Na configuração do OpenClaw, tokens e chaves de API podem estar em três formatos:

// String simples
"channels": { "telegram": { "botToken": "123456:ABC-DEF..." } }

// Template de variável de ambiente
"channels": { "telegram": { "botToken": "${TELEGRAM_BOT_TOKEN}" } }

// Objeto SecretRef
"channels": { "telegram": { "botToken": { "source": "env", "id": "TELEGRAM_BOT_TOKEN" } } }

A migração resolve os três formatos. Para templates de ambiente e objetos SecretRef com source: "env", ela busca o valor em ~/.openclaw/.env e no sub-objeto env do openclaw.json. Objetos SecretRef com source: "file" ou source: "exec" não têm como ser resolvidos automaticamente — a migração avisa sobre eles, e esses valores precisam ser adicionados ao Hermes manualmente com hermes config set.

Depois da migração

1. Confira o relatório da migração — ele é impresso ao final, com a contagem de itens migrados, pulados e em conflito.

2. Revise os arquivos arquivados — tudo que estiver em ~/.hermes/migration/openclaw/<timestamp>/archive/ precisa de atenção manual.

3. Comece uma sessão nova — skills e entradas de memória importadas só valem em sessões novas, não na atual.

4. Verifique as chaves de API — rode hermes status para conferir a autenticação nos provedores.

5. Teste as mensagens — se você migrou tokens de plataforma, reinicie o gateway: systemctl --user restart hermes-gateway

6. Confira as políticas de sessão — rode hermes config show e veja se o valor de session_reset é o que você espera.

7. Pareie o WhatsApp de novo — o WhatsApp usa pareamento por QR code (Baileys), e não migração de token. Rode hermes whatsapp para parear.

8. Limpe o que sobrou — depois de confirmar que está tudo funcionando, rode hermes claw cleanup para renomear os diretórios remanescentes do OpenClaw para .pre-migration/ (evita confusão de estado).

Resolução de problemas

"OpenClaw directory not found"

A migração procura em ~/.openclaw/, depois ~/.clawdbot/ e então ~/.moltbot/. Se a sua instalação está em outro lugar, use --source /caminho/do/seu/openclaw.

"No provider API keys found"

As chaves podem estar em vários lugares, dependendo da versão do OpenClaw: dentro do openclaw.json em models.providers.*.apiKey, em ~/.openclaw/.env, no sub-objeto "env" do openclaw.json ou em agents/main/agent/auth-profiles.json. A migração verifica os quatro. Se as chaves usam SecretRefs com source: "file" ou source: "exec", não há como resolvê-las automaticamente — adicione-as com hermes config set.

Skills não aparecem depois da migração

As skills importadas vão para ~/.hermes/skills/openclaw-imports/. Comece uma sessão nova para que elas passem a valer, ou rode /skills para conferir se foram carregadas.

A voz do TTS não foi migrada

O OpenClaw guarda as configurações de TTS em dois lugares: messages.tts.providers.* e a configuração talk no nível raiz. A migração verifica os dois. Se o seu ID de voz foi definido pela interface do OpenClaw (que grava em outro caminho), talvez você precise defini-lo manualmente: hermes config set tts.elevenlabs.voice_id YOUR_VOICE_ID.

---