openclaw-docs

Documentação OpenClaw

Visão Geral

Use esta skill ao escrever, editar ou revisar documentação de desenvolvedor OpenClaw para APIs, SDKs, ferramentas CLI, integrações, guias de início rápido, guias de plataforma ou documentação técnica de produtos.

Escreva documentação que seja concisa, útil e abrangente: rápida para o primeiro sucesso, precisa para produção e fácil de escanear durante a depuração.

Modelo Central

Use um modelo de documentação OpenClaw, fortalecido pelos princípios do Write the Docs:

• Lidere com o que o desenvolvedor está tentando fazer.
• Ofereça um caminho recomendado antes das alternativas.
• Faça exemplos executáveis e realistas.
• Mantenha guias orientados a tarefas e referências exaustivas.
• Explique riscos de produção exatamente onde os desenvolvedores podem cometer erros.
• Vincule conceitos, guias, referências de API, SDKs, testes e solução de problemas para que os leitores possam navegar entre eles sem reler.
• Trate a documentação como parte do ciclo de vida do produto: rascunhe-a antes ou junto com a implementação, revise-a com o código e mantenha-a atualizada.
• Faça cada página ser descobrível, endereçável, cumulativa, completa dentro de seu escopo declarado e fácil de escanear.

Estrutura

Escolha o tipo de página antes de escrever:

• Visão geral: direcione os leitores para o produto, caminho de integração ou guia correto.
• Início rápido: leve um novo usuário a um resultado funcional com o menor número de passos seguros.
• Página de tópico: forneça uma visão geral de ponta a ponta de uma entidade de domínio principal, com configuração, subtópicos principais, solução de problemas e links para referências mais profundas.
• Guia: explique um fluxo de trabalho desde os pré-requisitos até a prontidão para produção.
• Referência de API: defina cada objeto, endpoint, parâmetro, enumeração, resposta, erro e regra de versão.
• Referência de SDK ou CLI: documente instalação, autenticação, comandos ou métodos, opções, exemplos e modos de falha.
• Guia de teste: mostre configuração de sandbox, fixtures, dados de teste, falhas simuladas e diferenças do modo ao vivo.
• Guia de solução de problemas: mapeie sintomas para verificações, causas e correções.

Use esta estrutura de página de tópico padrão:

1. Título: nomeie a entidade ou superfície principal.
2. Visão geral de abertura: comece com algumas frases sem título que expliquem o que é, do que é responsável e do que não é. Não adicione um cabeçalho ## Visão geral a menos que a página seja ela própria um índice de visão geral.
3. Requisitos: inclua somente quando a configuração precisar de contas, versões, permissões, plugins, sistemas operacionais ou credenciais específicas.
4. Início rápido: mostre o caminho de configuração recomendado e a menor verificação confiável.
5. Configuração: mostre a configuração mínima necessária para usar a superfície, variantes comuns entre as quais o usuário deve escolher e onde cada opção é definida: CLI, arquivo de configuração, variável de ambiente, manifesto do plugin, painel ou API.
6. Subtópicos principais: organize os principais conceitos, fluxos de trabalho e decisões da entidade pela intenção do leitor. Coloque cada subtópico principal sob seu próprio cabeçalho; não os envolva em uma seção genérica ## Subtópicos.
7. Solução de problemas: diagnostique falhas observáveis comuns sob um cabeçalho explícito ## Solução de problemas.
8. Relacionados: vincule a guias, referências, comandos, conceitos e tópicos adjacentes.

As páginas de tópico podem ser mais longas que os guias de início rápido, mas não devem se tornar referências exaustivas. Mova tabelas de campos, contratos de API, detalhes internos restritos, detalhes legados e fluxos de trabalho de depuração raros para páginas de referência ou solução de problemas vinculadas quando eles interromperem a visão geral de ponta a ponta.

Para configuração, mantenha as opções críticas para a tarefa em linha. Vincule a documentos de referência para listas completas de opções, padrões, enums, esquemas gerados e configurações avançadas. Não duplique tabelas de referência de configuração exaustivas em páginas de tópico, a menos que a página de tópico seja ela própria a referência.

Use esta estrutura de guia padrão:

1. Título: nomeie o resultado, não o detalhe da implementação.
2. Abertura: declare o que o leitor pode realizar em uma ou duas frases.
3. Antes de começar: liste contas, chaves, permissões, versões, ferramentas e premissas.
4. Escolha um caminho: compare opções somente quando o leitor precisar decidir.
5. Passos: use cabeçalhos liderados por verbo com código, saída esperada e verificações.
6. Teste: mostre a menor prova confiável de que a integração funciona.
7. Prontidão para produção: cubra segurança, idempotência, novas tentativas, limites, observabilidade, migrações e limpeza.
8. Solução de problemas: inclua erros comuns perto do fluxo de trabalho que os causa.
9. Veja também: vincule a conceitos, referências de API, documentação de SDK e guias adjacentes.

Mantenha a navegação baseada na intenção do usuário. Não force os leitores a entender a taxonomia interna do produto antes que possam escolher uma tarefa.

Ciclo de Vida da Documentação

Escreva e mantenha a documentação com a mesma disciplina do código:

• Rascunhe a documentação cedo o suficiente para expor design pouco claro de produto, API, CLI ou configuração.
• Mantenha a fonte da documentação perto do código, configuração, comando, plugin ou protocolo que ela descreve quando a estrutura do repositório permitir.
• Evite verdade duplicada. Se o mesmo contrato aparecer em vários lugares, escolha a página canônica e vincule a ela.
• Atualize a documentação na mesma alteração que as mudanças de comportamento, configuração, API, CLI, plugin ou solução de problemas.
• Remova, redirecione ou marque claramente documentação desatualizada. Documentação incorreta é pior do que documentação ausente.
• Envolva os revisores certos: proprietários do código para comportamento, suporte ou QA para modos de falha do usuário e mantenedores da documentação para estrutura e estilo.
• Preserve orientação de versões mais antigas somente quando os usuários precisarem dela; caso contrário, documente o comportamento atual suportado.

Não use FAQs como depósito de material não relacionado. Promova perguntas recorrentes para páginas de tarefa, conceito, solução de problemas ou referência.

Estilo de Escrita

Escreva em uma voz direta e prática:

• Use tempo presente e voz ativa.
• Dirija-se ao leitor como "você" ao dar instruções.
• Prefira parágrafos curtos e listas escaneáveis.
• Use substantivos concretos: "perfil do agente", "webhook do Gateway", "manifesto do plugin", "estado da sessão".
• Coloque ressalvas exatamente onde elas afetam a etapa.
• Evite linguagem de marketing, hype, benefícios genéricos e alegações vagas.
• Evite longas introduções conceituais antes do primeiro passo acionável.
• Não explique demais conceitos comuns de desenvolvedor, a menos que o produto tenha um contrato não padrão.
• Defina jargões e abreviações específicos da OpenClaw antes do primeiro uso.
• Use caixa baixa para cabeçalhos, a menos que um nome de produto, comando ou identificador OpenClaw exija capitalização.
• Use texto de link descritivo que nomeie o destino ou ação; evite links vagos como "esta página" ou "clique aqui".
• Evite expressões idiomáticas culturalmente específicas, expressões idiomáticas violentas e piadas que tornem a documentação mais difícil de traduzir ou escanear.
• Escreva prosa acessível: não confie em cor, capturas de tela ou posição visual como a única maneira de entender uma instrução.

Use cabeçalhos que descrevam ações ou superfícies de referência:

• Bom: "Criar um agente", "Configurar um canal Slack", "Reparar instalação do plugin"
• Evite: "Como funciona", "Por baixo dos panos", "Notas importantes", a menos que a seção realmente precise dessa forma

Use linguagem modal precisa:

• Use "deve" para comportamento obrigatório.
• Use "pode" para capacidade opcional.
• Use "recomendado" para o caminho padrão.
• Use "evite" para armadilhas conhecidas.
• Explique "por quê" somente quando isso mudar uma decisão do desenvolvedor.

Nível de Detalhe

Varie o detalhe por tipo de página:

• Páginas de visão geral: sejam breves; ajudem os leitores a escolher.
• Guias de início rápido: sejam processuais; incluam apenas o necessário para o primeiro sucesso.
• Guias: sejam completos para um fluxo de trabalho; incluam decisões, efeitos colaterais e tratamento de falhas.
• Referências: sejam exaustivas; documentem cada campo, valor padrão, enum, valor anulável, restrição, resposta e erro.
• Solução de problemas: sejam explícitas; assumam que o leitor está bloqueado e precisa de verificações observáveis.

Aprofunde-se onde os erros são caros:

• Autenticação e tratamento de segredos
• Movimentação de dinheiro, cobrança, permissões e ações irreversíveis
• Webhooks, novas tentativas, eventos duplicados e ordenação
• Idempotência e concorrência
• Diferenças entre sandbox e produção
• Versionamento, migrações e compatibilidade com versões anteriores
• Limites, limites de taxa, cotas e tempos limite
• Códigos de erro e caminhos de recuperação
• Retenção de dados, privacidade e comportamento sensível a conformidade

Não enterre esse detalhe em uma referência distante se os desenvolvedores precisarem dele para concluir a tarefa com segurança.

Exemplos

Faça exemplos com forma de produção, mesmo ao usar dados de teste:

• Prefira comandos ou trechos completos copiáveis.
• Use nomes e valores de variáveis realistas.
• Marque placeholders claramente com nomes entre colchetes angulares, como <API_KEY> ou <CUSTOMER_ID>.
• Mostre a saída de sucesso esperada após os comandos.
• Mostre exemplos completos de requisição e resposta para referências de API quando a forma da resposta for importante.
• Mantenha uma unidade conceitual por bloco de código.
• Use cercas de código específicas de linguagem.
• Evite exemplos de brinquedo que escondam configuração, autenticação, tratamento de erros ou limpeza necessários.

Quando vários idiomas forem úteis, mantenha o mesmo cenário entre os idiomas para que os leitores possam comparar equivalentes.

Descobribilidade e Navegação

Projete cada página para que os leitores possam encontrá-la, vinculá-la e decidir rapidamente se ela responde à pergunta deles:

• Use títulos e cabeçalhos orientados a objetivos que correspondam a termos de pesquisa prováveis.
• Comece cada página com uma resposta concisa para "o que posso fazer aqui?"
• Inclua metadados ou frontmatter exigidos pelo índice de documentação OpenClaw.
• Adicione dicas "Leia quando" para roteamento de listas de documentação ao criar ou alterar páginas de documentação OpenClaw que participam do índice de documentação.
• Vincule a partir de pontos de entrada prováveis, não apenas de páginas de taxonomia interna próximas.
• Mantenha os cabeçalhos das seções estáveis o suficiente para links de issues, PRs, respostas de suporte e respostas de chat.
• Ordene tutoriais e exemplos de pré-requisitos para tarefas avançadas; ordene páginas de referência em ordem alfabética ou tópica quando isso ajudar na consulta.
• Declare o escopo antecipadamente quando uma página for intencionalmente parcial.

Padrão de Referência de API

Para endpoints, métodos, objetos ou comandos, inclua:

1. Declaração de propósito curta.
2. Requisitos de autenticação ou permissão.
3. Forma da requisição, incluindo caminho, consulta, cabeçalhos e campos do corpo.
4. Tabela de parâmetros com tipo, obrigatoriedade, padrão, restrições, valores de enumeração e efeitos colaterais.
5. Forma de retorno com estados de ciclo de vida do objeto.
6. Casos de erro com códigos, causas e orientação de recuperação.
7. Exemplo executável de requisição.
8. Resposta de sucesso representativa.
9. Guias relacionados e páginas de referência adjacentes.

Para objetos aninhados, documente campos filhos perto de seus pais. Não force os leitores a pular entre páginas para entender a forma de uma única requisição.

Verificação

Verifique alterações na documentação como alterações no produto:

• Execute a build de documentação relevante, índice de documentação, formatador, verificador de links ou verificação de documentação gerada quando disponível.
• Execute comandos, trechos e exemplos que a página diz aos usuários para executar sempre que viável.
• Confirme se capturas de tela, rótulos de interface, saída de CLI, chaves de configuração, flags, padrões, erros e caminhos de arquivo correspondem ao comportamento atual.
• Prefira verificações executáveis sobre revisão apenas em prosa para documentação de API, CLI, configuração, referência gerada e solução de problemas.
• Se uma etapa de verificação não for viável, diga o que não foi verificado e por quê.

Verificações de Integridade

Antes de finalizar uma página, verifique:

• A primeira tela diz aos leitores o que eles podem realizar.
• O caminho recomendado é óbvio.
• Pré-requisitos são explícitos e testáveis.
• Exemplos podem ser executados com entradas documentadas.
• A página tem um público claro: usuário, operador, autor de plugin, contribuidor ou mantenedor.
• O comportamento do modo de teste e do modo de produção são separados.
• Valores sensíveis à segurança nunca são expostos em exemplos.
• Cada aviso está anexado à etapa onde ele importa.
• Casos de borda são documentados onde afetam a implementação.
• Campos de API incluem tipos, padrões, restrições e erros.
• A solução de problemas começa a partir de sintomas observáveis.
• Links relacionados ajudam o leitor a continuar sem duplicar a página.
• A página diz onde obter suporte, relatar problemas ou contribuir quando isso for relevante para o próximo passo do leitor.
• A página está completa para o escopo que afirma, ou a limitação é declarada antecipadamente.

Passagem de Revisão

Edite nesta ordem:

1. Remova repetição e explicação genérica.
2. Mova o conhecimento conceitual para abaixo da primeira ação útil, a menos que seja necessário para escolher corretamente.
3. Substitua redação passiva ou abstrata por instruções concretas.
4. Aperte os cabeçalhos até que o esboço pareça um mapa de tarefas.
5. Adicione detalhes operacionais ausentes para segurança em produção.
6. Verifique exemplos quanto à precisão de copiar e colar.
7. Adicione links entre guias, referências, SDKs, testes e superfícies de solução de problemas.
8. Verifique descobribilidade, endereçabilidade, acessibilidade e verificação de documentação como código.