Criando habilidades personalizadas no OpenClaw: um tutorial mão na massa

As habilidades nativas do OpenClaw cobrem fluxos comuns, e a ClawHub hospeda muitas outras. Mas as que mais importam geralmente são aquelas que ninguém criou ainda: automações moldadas para seus próprios projetos e ferramentas.

Este tutorial mostra como criar duas habilidades personalizadas. A primeira envolve um script em Python que converte notebooks Jupyter em documentos Word. Se você escreve em notebooks mas entrega arquivos .docx para editores ou stakeholders, isso transforma uma exportação manual em um comando de barra. A segunda gera imagens com Nano Banana Pro via API da Replicate, adicionando gestão de credenciais e escopo de ambiente por cima do básico.

O tutorial também aborda sandboxing com Docker, controle por metadados e publicação de habilidades na ClawHub. Para uma visão mais ampla da plataforma OpenClaw, veja OpenClaw Projects: What You Can Build e nosso guia sobre as principais habilidades de agentes. 

O que são habilidades do OpenClaw?

Habilidades são como você adiciona novos comportamentos ao agente do OpenClaw. Pode ser algo simples, como um comando de barra que reformata código, ou algo mais complexo, como um fluxo multietapas que revisa PRs e posta comentários no Jira ou Slack.

Se você já usou servidores MCP (Model Context Protocol) no Claude Code ou ferramentas parecidas, as habilidades têm outro papel. Servidores MCP são processos separados que expõem ferramentas por um protocolo padronizado, ideal para integrações que precisam de estado persistente ou múltiplos endpoints de ferramenta. 

As habilidades pulam tudo isso: você escreve instruções em linguagem natural que o agente lê e segue em tempo de execução, ficando mais rápidas de construir quando você só precisa automatizar uma coisa. A comparação entre OpenClaw e Claude Code aprofunda os trade-offs.

Hooks, outro ponto de extensão, disparam automaticamente quando algo acontece, como a conclusão de uma chamada de ferramenta ou a geração de uma resposta pelo modelo. As habilidades ficam em espera até você digitar um comando de barra ou o agente decidir que uma é relevante para a tarefa atual.

O OpenClaw vem com 49 habilidades que cobrem e-mail, calendários, GitHub, automação de navegador e mais. A comunidade já publicou milhares adicionais na ClawHub. Para entender como a plataforma evoluiu, veja o histórico de MoltBot para ClawdBot.

Pré-requisitos

Você vai precisar de:

• OpenClaw instalado e rodando via Telegram (guia de instalação). A integração BotFather do Telegram tem o melhor suporte a comandos de barra, que é como você vai acionar habilidades ao longo do tutorial.
• uv instalado (as duas habilidades aqui usam para dependências Python)
• Conforto com terminal, YAML e Markdown
• Um token da API da Replicate para a habilidade de geração de imagens (cadastro gratuito, cobrança por uso)
• Uma conta GitHub com pelo menos uma semana, se quiser publicar na ClawHub

Se preferir rodar o OpenClaw com modelos locais, o tutorial OpenClaw com Ollama cobre essa configuração.

Criando sua primeira habilidade no OpenClaw

A primeira habilidade envolve um script em Python que converte notebooks Jupyter para documentos Word, tratando formatação de markdown, blocos de código, imagens, tabelas e hyperlinks para que a saída .docx preserve a estrutura do notebook original. Se você entrega conteúdo de notebook para quem trabalha em Word, isso vira um único comando de barra em vez de exportação manual.

Crie a pasta da habilidade no diretório de habilidades gerenciadas do OpenClaw:

mkdir -p ~/.openclaw/skills/notebook-to-docx

Habilidades em ~/.openclaw/skills ficam disponíveis em todas as sessões. Você também pode colocá-las dentro de um projeto em <project>/skills para restringi-las àquele workspace; quando o nome aparece nos dois locais, a cópia do workspace prevalece sobre a gerenciada, que por sua vez substitui qualquer habilidade empacotada com o mesmo nome.

Escrevendo o SKILL.md

Toda habilidade precisa de um arquivo: SKILL.md. O frontmatter YAML no topo define como o OpenClaw carrega a habilidade, e o corpo em markdown abaixo traz as instruções que o agente segue em tempo de execução.

Crie ~/.openclaw/skills/notebook-to-docx/SKILL.md, começando pelo frontmatter:

---
name: notebook-to-docx
description: Convert Jupyter notebooks to Word documents with proper formatting
user-invocable: true
metadata: {"openclaw": {"requires": {"bins": ["uv"]}}}
---

name também é o comando de barra (/notebook-to-docx). description dá ao agente um resumo para julgar relevância à tarefa atual. Definir user-invocable: true registra o comando de barra no seu chat do Telegram. O JSON de metadata cuida do gate no carregamento: requires.bins instrui o OpenClaw a ignorar esta habilidade se uv não estiver no PATH do sistema, em vez de falhar em tempo de execução. 

Se você quiser o contrário — a habilidade nunca dispara a menos que você digite o comando explicitamente — defina disable-model-invocation: true.

Dica: frontmatter YAML só suporta valores de uma linha. Strings multilinha ou blocos escalares causam erro de parsing, por isso metadata é um objeto JSON de uma linha em vez de YAML aninhado.

Abaixo do frontmatter, adicione o corpo das instruções:

# Notebook to DOCX Converter
 
Converts Jupyter notebooks (.ipynb) to Word documents (.docx) with proper formatting.
 
## Usage
 
Run the conversion script:
 
	uv run --with nbformat --with python-docx --with Pillow python {baseDir}/notebook_to_docx.py <notebook_path> [output_path]
 
If output_path is not specified, creates a .docx file with the same name as the notebook.
 
## Features
 
- Markdown formatting preserved as Word styles (bold, italics, headings)
- Backticks preserved around inline code with monospace font
- Code blocks show triple backticks and language name, use Courier New font
- Non-code text uses Poppins font
- Images embedded with alt text
- Hyperlinks preserved and clickable
- Markdown tables converted to Word tables
 
## Requirements
 
- nbformat
- python-docx
- Pillow

{baseDir} é uma variável de template que resolve para o caminho da pasta da habilidade em tempo de execução, então você não precisa fixar a localização. Isso importa quando outra pessoa instala sua habilidade em um diretório diferente. 

As flags uv run --with puxam as três bibliotecas necessárias, mantendo a habilidade autocontida em vez de presumir que esses pacotes existem no ambiente do usuário.

O script de apoio

O script Python fica na mesma pasta do SKILL.md. Com ~490 linhas, é longo demais para incluir aqui, então baixe o script completo neste gist e salve como notebook_to_docx.py em ~/.openclaw/skills/notebook-to-docx/. Ele cobre tudo listado na seção Features do SKILL.md acima.

Aqui está o ponto de entrada para você ver, em alto nível, o que ele faz:

def convert_notebook_to_docx(notebook_path, output_path=None):
	notebook_path = Path(notebook_path)
	if output_path is None:
    	output_path = notebook_path.with_suffix('.docx')
	else:
    	output_path = Path(output_path)
 
	with open(notebook_path, 'r', encoding='utf-8') as f:
    	nb = nbformat.read(f, as_version=4)
 
	doc = Document()
	create_styles(doc)
 
	style = doc.styles['Normal']
	style.font.name = 'Poppins'
	style.font.size = Pt(11)
 
	base_path = notebook_path.parent
 
	for cell in nb.cells:
    	if cell.cell_type == 'markdown':
        	process_markdown_cell(doc, cell.source, base_path)
    	elif cell.cell_type == 'code':
        	process_code_cell(doc, cell.source, cell.get('outputs', []))
 
	doc.save(output_path)
	print(f'Converted: {notebook_path} -> {output_path}')
	return output_path

Testando a habilidade

O OpenClaw faz snapshot da lista de habilidades ao iniciar a sessão, mas um watcher embutido detecta novos arquivos SKILL.md em ~250ms. Se a habilidade não aparecer, reinicie a sessão.

Este é o notebook de teste que usaremos:

Abra seu chat do Telegram com o OpenClaw e digite /notebook-to-docx, depois indique qual notebook converter:

O documento Word resultante:

Títulos, blocos de código, formatação inline e hyperlinks chegam nos estilos corretos do Word. Se algo parecer estranho na sua saída, verifique se a lista de recursos no SKILL.md bate com o que o script suporta.

Segurança e sandboxing no OpenClaw

O OpenClaw pode executar ferramentas dentro de contêineres Docker, o que limita o que uma habilidade com falhas ou comprometida pode acessar na sua máquina. A configuração fica em agents.defaults.sandbox dentro de ~/.openclaw/openclaw.json, com três modos:

• "off" é o padrão: as ferramentas rodam direto no host, sem isolamento.
• "non-main" mantém sua sessão principal no host e move sessões em segundo plano/automatizadas para contêineres.
• Com "all", toda sessão roda em contêiner, independente do contexto.

Além do modo, você escolhe um nível de acesso ao workspace que define quanto do seu filesystem o contêiner enxerga. O padrão, "none", dá ao sandbox um diretório isolado em ~/.openclaw/sandboxes, sem acesso aos arquivos do seu projeto. 

Com "ro", seu workspace é montado como somente leitura em /agent, então o agente pode ler seu código, mas não alterar nada. "rw" vai além e concede acesso total de leitura e escrita em /workspace.

Uma configuração funcional que isola sessões em segundo plano e ainda dá acesso de escrita fica assim:

{
  "agents": {
	"defaults": {
  	"sandbox": {
    	"mode": "non-main",
    	"scope": "session",
    	"workspaceAccess": "rw"
  	}
	}
  }
}

Isso se torna relevante assim que suas habilidades começam a chamar APIs ou lidar com credenciais. 

Quando uma habilidade roda dentro de um contêiner, variáveis de ambiente do host não aparecem automaticamente. Um REPLICATE_API_TOKEN que você exportou no .bashrc não vai existir no sandbox; então segredos precisam passar pelo sistema de configuração do OpenClaw, que é o que vamos configurar a seguir.

Dica: se sua habilidade usa requires.bins no metadata para exigir uma CLI, essa checagem roda no host na carga. Mas, com agente em sandbox, o binário também precisa existir dentro do contêiner. Instale via sandbox.docker.setupCommand ou crie uma imagem Docker customizada.

O sandbox também limita o estrago quando operações de arquivo ou comandos de shell dão errado. Uma habilidade que, por engano, roda rm -rf / atinge o filesystem do contêiner, não sua máquina real — um bom motivo para ativá-lo mesmo que você confie no seu código. 

Para saber mais sobre como fluxos de trabalho com agentes de IA lidam com limites de segurança, veja AI Agent Workflows with Claude CoWork.

Criando uma habilidade conectada a API

A segunda habilidade gera imagens usando o modelo Nano Banana Pro (Gemini 3 Pro Image) do Google via API da Replicate, o que exige configurar gestão de credenciais e gating de ambiente além do básico do SKILL.md.

Crie a pasta da habilidade:

mkdir -p ~/.openclaw/skills/nano-banana-pro

Crie ~/.openclaw/skills/nano-banana-pro/SKILL.md, começando pelo frontmatter:

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image on Replicate
user-invocable: true
metadata: {"openclaw": {"emoji": "🎨", "requires": {"env": ["REPLICATE_API_TOKEN"], "bins": ["uv"]}, "primaryEnv": "REPLICATE_API_TOKEN"}}
---

A estrutura é a mesma da primeira habilidade, mas o campo metadata faz mais coisas. Ele inclui dois gates: requires.env verifica se REPLICATE_API_TOKEN existe antes de carregar a habilidade, e requires.bins verifica a presença do uv. Se faltar algo, a habilidade é ignorada silenciosamente. 

O campo emoji define um ícone na lista de comandos de barra do Telegram. E primaryEnv mapeia REPLICATE_API_TOKEN para o atalho apiKey na config (mais abaixo, na parte de credenciais).

Se você quiser que a interface de Skills no macOS ofereça instalação em um clique para binários necessários, adicione um array install ao metadata:

metadata: {"openclaw": {"requires": {"bins": ["uv"]}, "install": [{"id": "brew", "kind": "brew", "formula": "uv", "bins": ["uv"], "label": "Install uv (brew)"}]}}

No Linux, faça a instalação manualmente ou via sandbox.docker.setupCommand.

Abaixo do frontmatter, adicione o corpo das instruções:

# Nano Banana Pro Image Generator
 
Generate and edit images using Google's Nano Banana Pro model via the Replicate API.
 
## Usage
 
Run the generation script:
 
	uv run --with replicate python {baseDir}/generate.py --prompt "<user prompt>" [--aspect-ratio 1:1] [--output image.png]
 
## Options
 
- --prompt: The image description (required)
- --aspect-ratio: Ratio like 1:1, 4:3, 16:9 (default: 1:1)
- --output: Output file path (default: generated_image.png)
 
## Tips
 
- For text in images, be specific about fonts, size, and placement
- The model supports resolutions up to 2K
- Safety filtering is on by default

O corpo é mais curto que o da primeira habilidade porque o script de geração concentra a complexidade. A variável {baseDir} funciona do mesmo jeito, apontando para a pasta da habilidade em tempo de execução.

O script de geração

Adicione ~/.openclaw/skills/nano-banana-pro/generate.py:

import replicate
import urllib.request
import argparse
 
def main():
	parser = argparse.ArgumentParser()
	parser.add_argument("--prompt", required=True)
    parser.add_argument("--aspect-ratio", default="1:1")
	parser.add_argument("--output", default="generated_image.png")
	args = parser.parse_args()
 
	output = replicate.run(
    	"google/nano-banana-pro",
    	input={
        	"prompt": args.prompt,
        	"aspect_ratio": args.aspect_ratio,
        	"output_format": "png",
        	"safety_filter_level": "block_only_high",
    	},
	)
 
	# Replicate returns a FileOutput; download the image
	url = str(output[0]) if isinstance(output, list) else str(output)
	urllib.request.urlretrieve(url, args.output)
	print(f"Image saved to {args.output}")
 
if __name__ == "__main__":
	main()

Ele faz o parse dos argumentos, chama replicate.run() com o nome do modelo e parâmetros de entrada, e baixa a imagem resultante. A biblioteca replicate lê REPLICATE_API_TOKEN do ambiente automaticamente.

Configurando a credencial da API

Adicione uma entrada em ~/.openclaw/openclaw.json:

{
  "skills": {
	"entries": {
  	"nano-banana-pro": {
    	"enabled": true,
    	"apiKey": "r8_your_replicate_token_here",
    	"env": {
      	"REPLICATE_API_TOKEN": "r8_your_replicate_token_here"
    	}
  	}
	}
  }
}

Há duas formas de fornecer a credencial aqui. O campo apiKey é um atalho que mapeia para o que primaryEnv declara no metadata da habilidade. O bloco env dá controle mais fino, permitindo injetar múltiplas variáveis de ambiente se a habilidade precisar. 

Ambas as abordagens limitam os valores à execução do agente. Eles são definidos quando a execução começa e limpos quando termina, sem vazar para o ambiente global do seu shell.

Testando

Inicie uma nova sessão do OpenClaw e invoque a habilidade:

/nano_banana_pro generate a beautiful and accurate diagram of how backpropagation works

Aqui está o diagrama que a habilidade gerou via Nano Banana Pro na Replicate:

A imagem chegou, mas até aqui tivemos um desvio. A primeira versão desse SKILL.md não tinha seção ## Rules, o que deu espaço para o agente improvisar. Quando o Nano Banana Pro retornou erro de "serviço indisponível" por alta demanda, o agente decidiu sozinho tentar google/nano-banana (a variante não-Pro) como fallback e gerou a imagem com esse modelo.

Do ponto de vista do agente, a escolha fazia sentido: concluir a tarefa por qualquer meio disponível. Do seu, não era o que você pediu. A correção foi adicionar restrições comportamentais ao corpo das instruções:

## Rules
 
- Only use the google/nano-banana-pro model. Never fall back to other models like google/nano-banana or any alternative. If the model is unavailable or rate-limited, report the error to the user and stop.
- After generating an image, send the image file directly in the chat. Do not just save it to the workspace silently.

O agente trata as instruções do SKILL.md como diretrizes, não limites rígidos, e vai preencher lacunas com julgamento próprio. Tudo que você não proibir explicitamente, ele pode decidir tentar. 

Se um comportamento é importante — qual modelo usar, para onde enviar a saída, se deve tentar novamente em caso de falha —, detalhe isso em uma seção de Regras.

Publicando e compartilhando habilidades na ClawHub

A ClawHub é o registro público de habilidades do OpenClaw, gratuito para explorar e instalar. Para publicar, você precisa de uma conta GitHub com pelo menos uma semana.

Configurando a CLI

Instale a CLI da ClawHub globalmente:

npm i -g clawhub

Depois, autentique:

clawhub login

Isso abre o navegador para autenticação via GitHub. Depois, você pode buscar, instalar e publicar habilidades pelo terminal.

Publicando sua habilidade

Para publicar a habilidade de geração de imagens:

clawhub publish ~/.openclaw/skills/nano-banana-pro \
  --slug nano-banana-pro \
  --name "Nano Banana Pro" \
  --version 1.0.0 \
  --tags latest

O --slug é o identificador único na ClawHub e deve ser exclusivo no registro inteiro. Se alguém já publicou uma habilidade com esse slug, o comando falha com "only the owner can publish updates". Nesse caso, escolha outro slug, algo como seunome-nano-banana-pro.

O --version segue versionamento semântico. Sempre que publicar uma atualização, incremente a versão e, se quiser, adicione um changelog:

clawhub publish ~/.openclaw/skills/nano-banana-pro \
  --slug nano-banana-pro \
  --version 1.1.0 \
  --changelog "Added image editing with --image-input flag"

A ClawHub mantém o histórico de versões para que os usuários possam auditar mudanças e voltar atrás se necessário.

Para operações em lote, clawhub sync --all varre seu diretório de habilidades e publica de uma vez as novas ou atualizadas:

clawhub sync --all --bump patch

Instalando habilidades da comunidade

Para instalar uma habilidade publicada por outra pessoa:

clawhub search "calendar"
clawhub install caldav-calendar

Habilidades instaladas vão para ./skills por padrão, e o OpenClaw as detecta como habilidades do workspace na próxima sessão.

Um alerta sobre habilidades de terceiros

Em janeiro de 2026, pesquisadores de segurança da Koi descobriram 341 habilidades maliciosas na ClawHub no que ficou conhecido como o incidente ClawHavoc. Os atacantes usaram nomes typosquattados e etapas falsas de instalação "pré-requisito" para distribuir o Atomic macOS Stealer (AMOS), shells reversas e payloads de exfiltração de credenciais. 

Em meados de fevereiro de 2026, a contagem passou de 824 habilidades sinalizadas em dezenas de categorias.

Antes de instalar qualquer habilidade da comunidade, leia o SKILL.md e os arquivos de apoio. Desconfie de etapas de instalação "pré-requisito" suspeitas, código ofuscado ou comandos base64. A ClawHub oculta automaticamente habilidades com três ou mais denúncias de usuários, mas novos pacotes maliciosos podem surgir mais rápido do que a moderação acompanha. 

Ferramentas como Clawdex podem escanear suas habilidades instaladas contra um banco de dados de pacotes maliciosos conhecidos.

Trate habilidades de terceiros com o mesmo cuidado que você teria com qualquer código de terceiros: revise antes de rodar.

Conclusão

Entre o formato SKILL.md, o escopo de credenciais via openclaw.json e a CLI da ClawHub, você tem o ciclo completo: da automação local ao pacote compartilhado. 

A maior parte do trabalho ao criar uma nova habilidade no OpenClaw é escrever instruções claras no corpo em markdown e decidir o que restringir no metadata. O código em si, seja um script de conversão ou uma chamada de API, fica em arquivos separados onde você pode testar e iterar de forma independente.

Para ir além do escopo deste tutorial, as habilidades empacotadas no repositório do OpenClaw mostram como o time principal estrutura fluxos mais complexos. O overview do Claude Opus 4.6 aprofunda como escolhas de modelo afetam o comportamento do agente, e o curso Introduction to Claude Models oferece prática hands-on com os modelos por trás de agentes como o OpenClaw.