Configurando o Grok Bot no Cursor

O Grok Bot no Cursor traz rotinas de automação powered by IA diretamente para o seu fluxo de trabalho de desenvolvimento. Ao configurar rotinas de webhook, gatilhos do Slack e fluxos de trabalho de automação, você pode conectar serviços externos e deixar o bot lidar com tarefas repetitivas automaticamente. Este guia cobre todo o processo de configuração, desde a configuração inicial até a solução de problemas avançada.

O que é o Grok Bot?

O Grok Bot é uma camada de automação no Cursor que usa rotinas baseadas em webhook para responder a eventos de serviços externos. Quando um gatilho dispara, o bot executa uma rotina predefinida, como executar análise de código, gerar resumos ou enviar notificações.

Os componentes principais de uma configuração do Grok Bot são:

• Rotinas: Sequências de ações que o bot executa quando acionado
• Gatilhos: Eventos que iniciam uma rotina, como uma mensagem do Slack ou uma chamada de webhook
• URLs de Webhook: Endereços de endpoint para os quais serviços externos enviam dados
• Ações: Etapas individuais dentro de uma rotina, como edições de arquivos, comandos de terminal ou chamadas de API

dica

Antes de configurar o Grok Bot, certifique-se de que sua instalação do Cursor esteja atualizada. Os recursos de rotina de webhook recebem melhorias frequentes, e versões mais antigas podem não suportar todos os tipos de gatilho descritos neste guia.

Configuração Inicial

Ativando o Grok Bot

Para ativar o Grok Bot no Cursor, navegue até as configurações de automação:

1. Abra as Configurações do Cursor (Ctrl+, ou Cmd+,)
2. Navegue até a seção Automations na barra lateral esquerda
3. Alterne Enable Grok Bot para ativar o recurso
4. Clique em Generate Webhook Secret para criar uma chave secreta para autenticar solicitações recebidas

// Exemplo da configuração gerada armazenada em settings.json
{
  "cursor.grokBot.enabled": true,
  "cursor.grokBot.webhookSecret": "whsec_abc123def456ghi789",
  "cursor.grokBot.defaultModel": "cursor-agent-pro",
  "cursor.grokBot.maxConcurrentRoutines": 3
}

aviso

Mantenha seu segredo de webhook privado. Qualquer pessoa com esse segredo pode acionar rotinas na sua máquina. Se o segredo for comprometido, gere um novo imediatamente no painel de configurações.

Criando Sua Primeira Rotina

Uma rotina é um conjunto de instruções que o bot segue quando acionado. Crie uma a partir do painel Automations:

1. Abra o painel Automations (Ctrl+Shift+A)
2. Clique em New Routine
3. Dê à rotina um nome descritivo, como "Slack Code Review Request"
4. Selecione um tipo de gatilho (Webhook, Slack, Manual ou Agendado)
5. Defina as ações que a rotina deve executar
6. Salve e ative a rotina

# Exemplo de configuração de rotina
name: "Slack Code Review Request"
description: "When a Slack message mentions @code-review, analyze the referenced file"
trigger:
  type: slack
  condition: "message.contains('@code-review')"
actions:
  - type: parse_message
    extract:
      file_path: "regex:review\\s+(.+)"
      question: "regex:asking\\s+(.+)"
  - type: read_file
    path: "{{file_path}}"
  - type: analyze
    prompt: "Review this code for potential issues, security vulnerabilities, and improvement suggestions."
  - type: slack_reply
    message: "{{analysis_result}}"

Rotinas de Webhook

Rotinas de webhook permitem que serviços externos acionem ações no Cursor enviando solicitações HTTP POST para uma URL designada.

Entendendo a URL do Webhook

Quando você cria uma rotina acionada por webhook, o Cursor gera uma URL de webhook exclusiva. Esta URL é o endereço para o qual os serviços externos enviam suas cargas úteis.

# Exemplo de formato de URL de webhook
http://localhost:7541/webhooks/routines/rtn_abc123def456

aviso

Um problema comum relatado por usuários é que a configuração da rotina de webhook não mostra nenhuma URL POST. Isso geralmente acontece quando a rotina não foi totalmente salva ou o tipo de gatilho não foi definido como "Webhook" antes de salvar. Se você não vê uma URL POST, siga estas etapas:

1. Reabra o editor de rotina
2. Confirme que o tipo de gatilho está definido como "Webhook"
3. Clique em Save explicitamente (não apenas feche o painel)
4. Reabra a rotina para verificar se a URL agora é exibida

Se a URL ainda não aparecer, reinicie o Cursor e tente novamente. Este é um problema conhecido que foi relatado e está sendo monitorado para correção.

Registrando uma Rotina de Webhook

Veja como criar uma rotina acionada por webhook passo a passo:

1. Abra o painel Automations
2. Clique em New Routine
3. Defina o nome como "GitHub PR Notification"
4. Defina o tipo de gatilho como Webhook
5. Salve a rotina para gerar a URL do webhook
6. Copie a URL POST exibida
7. Configure seu serviço externo para enviar solicitações para essa URL

# Exemplo: Enviando um webhook de uma GitHub Action
import json
import urllib.request

webhook_url = "http://localhost:7541/webhooks/routines/rtn_abc123def456"
webhook_secret = "whsec_abc123def456ghi789"

payload = {
    "event": "pull_request.opened",
    "repository": "my-org/my-repo",
    "pr_number": 42,
    "pr_title": "Add payment gateway integration",
    "author": "jane-dev",
    "changed_files": ["src/payment/stripe.ts", "src/api/routes.ts"],
}

req = urllib.request.Request(
    webhook_url,
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Content-Type": "application/json",
        "X-Webhook-Secret": webhook_secret,
    },
    method="POST",
)

try:
    with urllib.request.urlopen(req) as response:
        print(f"Status: {response.status}")
        print(f"Response: {response.read().decode()}")
except urllib.error.URLError as e:
    print(f"Webhook delivery failed: {e}")

Validando Solicitações de Webhook

Sempre valide solicitações de webhook recebidas para garantir que venham de uma fonte confiável. O segredo do webhook que você gerou durante a configuração deve ser incluído no cabeçalho X-Webhook-Secret.

// Exemplo de lógica de validação (Node.js)
const crypto = require("crypto");

function validateWebhook(req, res, next) {
  const secret = req.headers["x-webhook-secret"];
  const expectedSecret = process.env.CURSOR_WEBHOOK_SECRET;

  if (!secret || secret !== expectedSecret) {
    return res.status(401).json({ error: "Invalid webhook secret" });
  }

  // Opcional: verificar o timestamp da solicitação para prevenir ataques de repetição
  const timestamp = req.headers["x-webhook-timestamp"];
  const now = Date.now();
  const maxAge = 5 * 60 * 1000; // 5 minutos

  if (timestamp && now - parseInt(timestamp) > maxAge) {
    return res.status(401).json({ error: "Webhook timestamp expired" });
  }

  next();
}

dica

Para configurações de produção, use uma ferramenta como ngrok ou Cloudflare Tunnel para expor seu endpoint de webhook local à internet. Isso permite que serviços externos como GitHub, Slack ou Jira acessem sua instância local do Cursor.

Integração com Slack

O Slack é uma das fontes de gatilho mais comuns para rotinas do Grok Bot. Você pode configurar o Slack para enviar mensagens ao Cursor quando eventos específicos ocorrem.

Configurando um Gatilho do Slack

1. Vá para a página de Aplicativos da API do Slack
2. Clique em Create New App e escolha From scratch
3. Nomeie o aplicativo como "Cursor Grok Bot" e selecione seu workspace
4. Em Event Subscriptions, ative eventos
5. Insira sua URL de webhook do Cursor como a Request URL
6. Inscreva-se nos eventos de bot message.channels e reaction_added
7. Em OAuth & Permissions, adicione os escopos chat:write e channels:read
8. Instale o aplicativo em seu workspace e copie o Bot User OAuth Token

// Exemplo: Manipulador de gatilho do Slack em uma rotina do Grok Bot
const slackTrigger = {
  type: "slack",
  events: ["message.channels"],
  conditions: {
    // Acionar apenas quando a mensagem menciona @cursor-bot
    mentions_bot: true,
    // Acionar apenas em canais específicos
    channels: ["#code-review", "#bug-reports", "#deployments"],
    // Ignorar mensagens do próprio bot
    ignore_bots: true,
  },
};

Enviando Respostas para o Slack

Quando uma rotina é concluída, você pode enviar o resultado de volta para o canal do Slack de origem:

const { WebClient } = require("@slack/web-api");

const slack = new WebClient(process.env.SLACK_BOT_TOKEN);

async function replyToSlack(channel, text) {
  await slack.chat.postMessage({
    channel: channel,
    text: text,
    // Opcional: formatar como uma mensagem Slack Block Kit
    blocks: [
      {
        type: "section",
        text: {
          type: "mrkdwn",
          text: text,
        },
      },
      {
        type: "divider",
      },
      {
        type: "context",
        elements: [
          {
            type: "mrkdwn",
            text: ":robot_face: Generated by Cursor Grok Bot",
          },
        ],
      },
    ],
  });
}

aviso

Se seu gatilho do Slack não está disparando, verifique as seguintes causas comuns:

1. O aplicativo Slack não está inscrito nos tipos de evento corretos
2. O usuário bot não tem permissão para ler o canal de destino
3. A URL do webhook está incorreta ou inacessível pela internet
4. O cabeçalho X-Webhook-Secret não corresponde ao valor esperado
5. O filtro de condição em sua rotina não corresponde à mensagem recebida

O Slack não repete entregas de webhook com falha por padrão. Se seu endpoint retornar uma resposta não-200, o evento é silenciosamente descartado. Sempre verifique os logs da API do Slack para erros de entrega.

Configuração de Gatilhos

O Grok Bot suporta vários tipos de gatilho além de webhooks e Slack. Entender cada tipo de gatilho ajuda você a escolher o certo para seu caso de uso.

Tipos de Gatilho Disponíveis

Tipo de Gatilho	Descrição	Caso de Uso
Webhook	Solicitação HTTP POST de qualquer serviço externo	Eventos do GitHub, atualizações do Jira, pipelines de CI/CD
Slack	Mensagens ou reações do Slack	Notificações de equipe, solicitações de revisão de código
Schedule	Gatilho baseado em tempo (expressão cron)	Verificações periódicas, resumos noturnos
File Watch	Acionado quando um arquivo muda no disco	Auto-formatação, auto-teste ao salvar
Manual	Acionado por atalho de teclado ou comando	Análise de código sob demanda

Exemplo de Gatilho de Agendamento

name: "Nightly Dependency Audit"
description: "Check for outdated dependencies every night at 2 AM"
trigger:
  type: schedule
  cron: "0 2 * * *"
actions:
  - type: terminal_command
    command: "npm audit --json"
  - type: analyze
    prompt: "Analyze these npm audit results and summarize the critical vulnerabilities."
  - type: slack_reply
    channel: "#security-alerts"
    message: "{{analysis_result}}"

Exemplo de Gatilho de Monitoramento de Arquivo

name: "Auto-Format on Save"
description: "Run formatter whenever a TypeScript file is saved"
trigger:
  type: file_watch
  patterns:
    - "**/*.ts"
    - "**/*.tsx"
  events: ["save"]
actions:
  - type: terminal_command
    command: "npx prettier --write {{file_path}}"
  - type: terminal_command
    command: "npx eslint --fix {{file_path}}"

dica

Gatilhos de monitoramento de arquivo podem ser barulhentos se você salvar frequentemente. Adicione um período de debounce à configuração do gatilho para agrupar salvamentos rápidos em uma única execução. Isso evita que o bot execute múltiplas rotinas sobrepostas para o mesmo arquivo.

Editando Rotinas

Rotinas são armazenadas como arquivos de configuração YAML e podem ser editadas diretamente ou através do editor visual no Cursor.

Usando o Editor Visual

O editor visual no painel Automations fornece uma interface de arrastar e soltar para construir rotinas:

1. Arraste blocos de ação da paleta à esquerda
2. Arrange-os na ordem desejada
3. Clique em cada bloco para configurar seus parâmetros
4. Use o botão Test para executar a rotina com entrada de exemplo
5. Salve a rotina para ativá-la

Editando o YAML Diretamente

Para mais controle, você pode editar o arquivo YAML da rotina diretamente. Arquivos de rotina são armazenados no diretório .cursor/automations/:

# Listar todas as rotinas
ls -la .cursor/automations/

# Editar uma rotina específica
code .cursor/automations/nightly-audit.yaml

# .cursor/automations/code-review-bot.yaml
name: "Smart Code Review Bot"
description: "Analyzes changed files and posts a review comment"
trigger:
  type: webhook
  filter:
    event: "pull_request.opened"
actions:
  - type: parse_payload
    extract:
      pr_number: "$.pull_request.number"
      changed_files: "$.pull_request.changed_files"
      repo: "$.repository.full_name"

  - type: loop
    over: "{{changed_files}}"
    actions:
      - type: read_file
        path: "{{item}}"
      - type: analyze
        prompt: |
          Review this file for:
          1. Security vulnerabilities
          2. Performance issues
          3. Code style violations
          4. Missing error handling

  - type: format_output
    template: |
      ## Automated Code Review

      {{#each results}}
      ### {{this.file}}
      {{this.review}}
      {{/each}}

  - type: webhook_response
    status: 200
    body: "{{formatted_output}}"

aviso

Ao editar arquivos YAML de rotina diretamente, sempre valide a sintaxe antes de salvar. Um arquivo YAML malformado fará com que a rotina falhe silenciosamente. Use cursor.automations.validate na paleta de comandos para verificar todas as rotinas.

Fluxos de Trabalho de Automação

Combinar múltiplas rotinas cria fluxos de trabalho de automação poderosos que conectam todo o seu pipeline de desenvolvimento.

Exemplo de Fluxo de Trabalho: Automação do Ciclo de Vida de PR

Este fluxo de trabalho automatiza todo o ciclo de vida de pull request:

# Rotina 1: PR Aberto - Análise Inicial
name: "PR Initial Analysis"
trigger:
  type: webhook
  filter:
    event: "pull_request.opened"
actions:
  - type: analyze
    prompt: "Summarize this PR and identify the main changes."
  - type: slack_reply
    channel: "#pr-updates"
    message: "New PR: {{pr_title}}\nSummary: {{analysis_result}}"

---

# Rotina 2: Solicitação de Revisão de PR - Análise Profunda
name: "PR Deep Analysis"
trigger:
  type: slack
  conditions:
    mentions_bot: true
    contains_keyword: "deep-review"
actions:
  - type: analyze
    prompt: "Perform a comprehensive code review including security, performance, and architecture."
  - type: slack_reply
    channel: "{{trigger_channel}}"
    message: "{{analysis_result}}"

---

# Rotina 3: PR Mesclado - Atualização de Documentação
name: "PR Merged - Update Docs"
trigger:
  type: webhook
  filter:
    event: "pull_request.closed"
    merged: true
actions:
  - type: analyze
    prompt: "Update the README and CHANGELOG based on the merged changes."
  - type: terminal_command
    command: "git add README.md CHANGELOG.md && git commit -m 'docs: update for PR #{{pr_number}}'"

Exemplo de Fluxo de Trabalho: Resposta a Incidentes

name: "Incident Response Bot"
description: "When an error alert is posted to Slack, analyze and suggest fixes"
trigger:
  type: slack
  channels: ["#alerts", "#incidents"]
  conditions:
    contains_keyword: "ERROR"
actions:
  - type: parse_message
    extract:
      error_text: "regex:ERROR:\\s*(.+)"
      stack_trace: "regex:at\\s+(.+)"

  - type: search_codebase
    query: "{{error_text}}"

  - type: analyze
    prompt: |
      An error has occurred. Here is the error message and the relevant code.
      Suggest a fix and explain the root cause.
      Error: {{error_text}}
      Stack trace: {{stack_trace}}
      Relevant file: {{search_result}}

  - type: slack_reply
    channel: "{{trigger_channel}}"
    message: |
      :rotating_light: *Automated Analysis*
      *Likely cause:* {{analysis_result.cause}}
      *Suggested fix:* {{analysis_result.fix}}
      *File to check:* {{search_result}}

dica

Construa seus fluxos de trabalho incrementalmente. Comece com uma rotina de notificação simples, teste-a minuciosamente, depois adicione ações mais complexas. Isso facilita identificar qual etapa está falhando quando algo dá errado.

Solução de Problemas

URL de Webhook Não Aparece

Este é o problema mais comumente relatado. Ao criar uma rotina acionada por webhook, o campo de URL POST pode aparecer vazio.

Causa raiz: A rotina foi salva antes que o tipo de gatilho fosse definido, ou a rotina foi apenas parcialmente salva.

Solução:

1. Exclua a rotina e crie uma nova
2. Defina o tipo de gatilho como "Webhook" antes de inserir qualquer outro detalhe
3. Clique em Save e aguarde a URL ser gerada
4. Se a URL ainda não aparecer, verifique o painel de saída do Cursor por erros (View > Output > Cursor Automations)
5. Como solução alternativa, você pode construir a URL manualmente usando o ID da rotina do arquivo YAML:

http://localhost:7541/webhooks/routines/{ROUTINE_ID}

Gatilhos do Slack Não Disparam

Se seus gatilhos do Slack não estão respondendo a mensagens:

1. Verifique se o aplicativo Slack está instalado em seu workspace
2. Confirme que a URL de inscrição de eventos está acessível (use o recurso de verificação da API do Slack)
3. Confirme se o usuário bot foi convidado para o canal de destino (/invite @cursor-grok-bot)
4. Verifique se as condições da rotina não estão muito restritivas
5. Revise o log do Cursor Automations para eventos recebidos:

# Ver o log de automação
cat .cursor/automations/logs/automation.log | tail -100

# Filtrar por eventos do Slack
grep "slack" .cursor/automations/logs/automation.log

aviso

O Slack tem um tempo limite de 3 segundos para verificação da URL de inscrição de eventos. Se o Cursor demorar mais de 3 segundos para responder à solicitação de verificação inicial, o Slack rejeitará a URL. Certifique-se de que o Cursor esteja em execução e responsivo quando configurar a inscrição de eventos no painel da API do Slack.

Problemas de Edição de Rotina

Se você não consegue salvar ou editar uma rotina:

1. Verifique se o arquivo YAML é válido usando a paleta de comandos
2. Garanta que nenhum outro processo bloqueou o arquivo de rotina
3. Verifique se você tem permissões de escrita no diretório .cursor/automations/
4. Tente excluir o diretório .cursor/automations/cache/ para forçar uma atualização
5. Reinicie o Cursor se o editor visual ficar sem resposta

Depurando Execução de Rotina

Ative o log de depuração para ver informações detalhadas sobre a execução da rotina:

// Em settings.json
{
  "cursor.grokBot.debug": true,
  "cursor.grokBot.logLevel": "verbose"
}

# Ver logs de depuração em tempo real
tail -f .cursor/automations/logs/automation.log

# Filtrar por uma rotina específica
grep "routine_id: rtn_abc123" .cursor/automations/logs/automation.log

Melhores Práticas

• Comece simples: Comece com uma rotina de notificação básica antes de construir fluxos de trabalho complexos
• Teste com entrada de exemplo: Use o botão Test no editor visual antes de ativar uma rotina
• Use condições sabiamente: Adicione filtros de condição para evitar que rotinas disparem em cada mensagem ou evento
• Monitore o tempo de execução: Rotinas de longa duração podem bloquear a execução de outras rotinas. Defina um tempo limite.
• Controle de versão de suas rotinas: Armazene arquivos YAML de rotina em seu repositório git para colaboração em equipe
• Documente seus fluxos de trabalho: Adicione descrições claras a cada rotina para que os colegas de equipe entendam seu propósito
• Rotacione segredos de webhook: Regenere periodicamente seu segredo de webhook para segurança
• Use variáveis de ambiente: Referencie valores sensíveis através de variáveis de ambiente em vez de codificá-los no YAML

dica

Crie um repositório de rotinas compartilhado que sua equipe possa referenciar. Cada membro da equipe pode se inscrever nas rotinas de que precisa, e as atualizações são automaticamente recebidas quando o repositório é clonado. Isso promove consistência em toda a equipe.

Conclusão

O Grok Bot no Cursor fornece uma camada de automação flexível que conecta seu editor a serviços externos através de rotinas de webhook e gatilhos do Slack. Seguindo as etapas de configuração neste guia e abordando cenários comuns de solução de problemas, você pode construir fluxos de trabalho de automação robustos que economizam tempo e reduzem o esforço manual.

As coisas mais importantes a lembrar são: sempre valide solicitações de webhook, defina o tipo de gatilho antes de salvar uma rotina e teste minuciosamente com as ferramentas de teste integradas antes de ativar rotinas em produção. Com essas práticas em vigor, o Grok Bot se torna uma parte confiável do seu kit de ferramentas de desenvolvimento.