Integrar aplicativos OpenClaw - Cloud Monitor: Central de Documentação do Alibaba Cloud

Limites

Limite	Descrição
Versão do OpenClaw	v26.2.19 ou posterior. Versões anteriores não incluem o plugin `diagnostics-otel`. Atualize primeiro.
Protocolo de envio	Apenas o protocolo HTTP/Protobuf é suportado; HTTP/JSON e gRPC não são suportados.
Tipos de dados	Somente dados de rastreamento e métricas são suportados. Dados de log não têm suporte.
Serviço Cloud Monitor	Você deve ter ativado o Cloud Monitor 2.0 e criado um workspace.

Etapa 1: Obtenha o comando de instalação

Antes de instalar o plugin, obtenha um comando de instalação no console do Cloud Monitor 2.0.

Faça login no console do Cloud Monitor 2.0 e selecione o workspace de destino.
No painel de navegação à esquerda, clique em Integration Center.
Na seção AI Application Observability, clique em cartão OpenClaw.

Na área de configuração de parâmetros, insira o nome do aplicativo, selecione o método de conexão conforme necessário e clique em Get ao lado de LicenseKey.

O console gera um comando de instalação com base na sua configuração. Clique em ícone de cópia no canto superior direito para copiar o comando. O comando contém informações do endpoint, como o endpoint e a LicenseKey. Para instalação manual, anote as seguintes informações:

Parâmetro	Descrição	Exemplo
Endpoint	Endpoint de envio de rastreamentos e métricas OTLP	`https://proj-xtrace-xxx.cn-hangzhou-intranet.log.aliyuncs.com/apm/trace/opentelemetry/v1/traces` `https://proj-xtrace-xxx.cn-hangzhou-intranet.log.aliyuncs.com/apm/trace/opentelemetry/v1/metrics`
x-arms-license-key	LicenseKey para autenticação de gravação de dados	`d95vgxi0cn@xxxxx`
x-arms-project	Nome do projeto do Simple Log Service	`proj-xtrace-xxx-cn-hangzhou`
x-cms-workspace	ID do workspace do Cloud Monitor 2.0	`default-cms-xxx-cn-hangzhou`
serviceName	O nome do aplicativo.	openclaw-xxx

Etapa 2: Instale e integre

Método 1: Instalação com um clique (recomendado)

Na máquina em que o OpenClaw está em execução, abra um terminal, cole o comando de instalação da etapa anterior e execute-o:

curl -fsSL https://arms-apm-cn-hangzhou-pre.oss-cn-hangzhou.aliyuncs.com/opentelemetry-instrumentation-openclaw/install.sh | bash -s -- \
  --endpoint "https://<YOUR_ENDPOINT>" \
  --x-arms-license-key "<YOUR_LICENSE_KEY>" \
  --x-arms-project "<YOUR_PROJECT>" \
  --x-cms-workspace "<YOUR_WORKSPACE>" \
  --serviceName "<YOUR_SERVICE_NAME>"

O script de instalação executa automaticamente as seguintes ações:

Verifica se o Node.js, o npm e a CLI do OpenClaw estão presentes no ambiente.
Baixa e extrai o plugin opentelemetry-instrumentation-openclaw no diretório de extensões do OpenClaw.
Instala as dependências de tempo de execução do plugin.
Localiza automaticamente a extensão diagnostics-otel e instala suas dependências, caso ainda não estejam instaladas.
Atualiza o arquivo openclaw.json com as configurações de ambos os plugins. Para as versões v2026.4.25 e posteriores do OpenClaw, também adiciona automaticamente hooks.allowConversationAccess: true.
Reinicia o gateway para aplicar a nova configuração.

A saída esperada é semelhante à seguinte:

[INFO]  Checking prerequisites...
[OK]    Node.js v24.14.0
[OK]    npm 11.9.0
[OK]    OpenClaw CLI found
[INFO]  Downloading plugin...
[OK]    Downloaded
[INFO]  Extracting...
[OK]    Extracted
[INFO]  Installing npm dependencies...
[OK]    Dependencies installed
[INFO]  Locating diagnostics-otel extension...
[OK]    Found diagnostics-otel at: /home/.../extensions/diagnostics-otel
[OK]    diagnostics-otel dependencies already present
[INFO]  Updating config...
[OK]    Config updated
[INFO]  Restarting OpenClaw gateway...
[OK]    Gateway restarted
════════════════════════════════════════════════════
  ✅ opentelemetry-instrumentation-openclaw installed successfully!
════════════════════════════════════════════════════

Parâmetros de instalação

Parâmetro	Obrigatório	Descrição
`--endpoint`	Sim	O endpoint de envio de dados OTLP, obtido no Integration Center do Cloud Monitor 2.0.
`--x-arms-license-key`	Sim	A LicenseKey para autenticação de gravação de dados.
`--x-arms-project`	Sim	O nome do projeto do Simple Log Service.
`--x-cms-workspace`	Sim	O identificador do workspace do Cloud Monitor 2.0.
`--serviceName`	Sim	O nome do serviço reportado, que aparece como nome do aplicativo na lista de aplicativos do Cloud Monitor 2.0.
`--plugin-url`	Não	Uma URL personalizada para download do tarball.
`--install-dir`	Não	Um diretório de instalação personalizado.
`--disable-metrics`	Não	Desativa o envio de métricas ignorando a configuração do `diagnostics-otel`. Isso ativa apenas o envio de rastreamentos.

Método 2: Instalação manual

Para realizar uma instalação manual, siga estas etapas.

1. Baixe e extraia o plugin

curl -fsSL -o opentelemetry-instrumentation-openclaw.tar.gz https://arms-apm-cn-hangzhou-pre.oss-cn-hangzhou.aliyuncs.com/opentelemetry-instrumentation-openclaw/opentelemetry-instrumentation-openclaw.tar.gz
tar -xzf opentelemetry-instrumentation-openclaw.tar.gz
cd opentelemetry-instrumentation-openclaw
npm install --omit=dev

2. Ative o plugin diagnostics-otel

openclaw plugins enable diagnostics-otel

3. Edite o arquivo de configuração

Edite o arquivo ~/.openclaw/openclaw.json e adicione a seguinte configuração. Substitua os espaços reservados pelas informações do endpoint da Etapa 1.

{
  "plugins": {
    "allow": ["opentelemetry-instrumentation-openclaw", "diagnostics-otel"],
    "load": {
      "paths": ["<PATH_TO_OPENTELEMETRY_INSTRUMENTATION_OPENCLAW>"]
    },
    "entries": {
      "opentelemetry-instrumentation-openclaw": {
        "enabled": true,
        "hooks": {
          "allowConversationAccess": true
        },
        "config": {
          "endpoint": "<ENDPOINT>",
          "headers": {
            "x-arms-license-key": "<YOUR_LICENSE_KEY>",
            "x-arms-project": "<YOUR_ARMS_PROJECT>",
            "x-cms-workspace": "<YOUR_WORKSPACE_ID>"
          },
          "serviceName": "<YOUR_SERVICE_NAME>"
        }
      },
      "diagnostics-otel": {
        "enabled": true
      }
    }
  },
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "<ENDPOINT>",
      "protocol": "http/protobuf",
      "headers": {
        "x-arms-license-key": "<YOUR_LICENSE_KEY>",
        "x-arms-project": "<YOUR_ARMS_PROJECT>",
        "x-cms-workspace": "<YOUR_WORKSPACE_ID>"
      },
      "serviceName": "<YOUR_SERVICE_NAME>",
      "traces": false,
      "metrics": true,
      "logs": false
    }
  }
}

Compatibilidade de versão : A configuração hooks.allowConversationAccess é suportada apenas nas versões v2026.4.25 e posteriores do OpenClaw. Em versões anteriores, remova a seção hooks para evitar o erro "Unrecognized key" ao iniciar o gateway.

4. Reinicie o gateway

openclaw gateway restart

Método 3: Integração com contêineres

Primeiro, selecione uma imagem base do OpenClaw. Caso já tenha criado uma imagem personalizada a partir da imagem base oficial, use-a. Em seguida, instale os plugins de observabilidade do OpenClaw na imagem base e reconstrua sua própria imagem do OpenClaw, conforme o exemplo abaixo:

FROM ghcr.io/openclaw/openclaw:latest
RUN curl -fsSL https://arms-apm-cn-hangzhou-pre.oss-cn-hangzhou.aliyuncs.com/opentelemetry-instrumentation-openclaw/install.sh | bash -s -- \
  --endpoint "https://<YOUR_ENDPOINT>" \
  --x-arms-license-key "<YOUR_LICENSE_KEY>" \
  --x-arms-project "<YOUR_PROJECT>" \
  --x-cms-workspace "<YOUR_WORKSPACE>" \
  --serviceName "<YOUR_SERVICE_NAME>"

Este é o mesmo script de instalação usado na instalação com um clique.

Em seguida, crie uma imagem personalizada do OpenClaw a partir deste Dockerfile e use-a no seu ambiente de contêineres.

Se precisar configurar dinamicamente o endpoint de envio, o nome do aplicativo e outras definições para a sua instância do OpenClaw, gere a imagem do OpenClaw da seguinte forma:

FROM ghcr.io/openclaw/openclaw:latest
RUN curl -fsSL https://arms-apm-cn-hangzhou-pre.oss-cn-hangzhou.aliyuncs.com/opentelemetry-instrumentation-openclaw/install-ack.sh | bash -s

Ao executar a imagem, defina as seguintes variáveis de ambiente para especificar o endpoint de envio, o nome do aplicativo e outras informações:

Variável de ambiente	Descrição
`ARMS_OTLP_ENDPOINT`	A URL do seu endpoint
`ARMS_LICENSE_KEY`	Sua LicenseKey
`ARMS_PROJECT`	Seu projeto
`ARMS_CMS_WORKSPACE`	Seu workspace
`ARMS_SERVICE_NAME`	O nome do serviço

Parâmetros de configuração

opentelemetry-instrumentation-openclaw

Parâmetro	Tipo	Obrigatório	Descrição
`endpoint`	String	Sim	O endpoint de envio de dados OTLP, obtido no Integration Center do Cloud Monitor 2.0.
`headers.x-arms-license-key`	String	Sim	A LicenseKey para autenticação de identidade.
`headers.x-arms-project`	String	Sim	O projeto do Simple Log Service para armazenar dados de rastreamento.
`headers.x-cms-workspace`	String	Sim	O workspace de destino do Cloud Monitor 2.0 para envio de dados.
`serviceName`	String	Sim	O nome do serviço reportado, que aparece como nome do aplicativo na lista de aplicativos do Cloud Monitor 2.0.
`debug`	Boolean	Não	Ativa o log de depuração. O valor padrão é `false`.
`batchSize`	Number	Não	O número máximo de spans a serem mantidos no buffer antes do envio em lote. O valor padrão é `10`.
`flushIntervalMs`	Number	Não	Tempo máximo de espera do buffer (em milissegundos). O padrão é `5000`.
`enableTracePropagation`	Boolean	Não	Ativa a propagação do W3C Trace Context para correlacionar solicitações upstream e downstream. O valor padrão é `false`.
`propagationTargetUrls`	String[]	Não	Injeta o cabeçalho `traceparent` em URLs downstream correspondentes (correspondência de substring de URL).
`resourceAttributes`	Object	Não	Especifique atributos de Resource personalizados para injetar no OTel Resource, como `{"deployment.environment": "production"}`.
`globalSpanAttributes`	Object	Não	Atributos globais de Span, injetados em todos os spans (como `{"biz.team": "payment"}`).

Nota : A configuração hooks.allowConversationAccess: true deve ser feita no campo hooks das entradas do plugin (no mesmo nível de config ). Caso contrário, a política de segurança do OpenClaw bloqueará os hooks relacionados à conversa. Somente as versões do OpenClaw >= 2026.4.25 suportam este campo. Não o configure em versões anteriores.

Fallback de variáveis de ambiente

Caso um campo de configuração não esteja definido, o plugin lê o valor da variável de ambiente correspondente. Este método é ideal para ambientes de contêineres e Kubernetes.

Variável de ambiente	Configuração correspondente	Descrição
`ARMS_OTLP_ENDPOINT`	`endpoint`	Endpoint de envio OTLP
`ARMS_LICENSE_KEY`	`headers.x-arms-license-key`	LicenseKey do ARMS
`ARMS_PROJECT`	`headers.x-arms-project`	Nome do projeto ARMS
`ARMS_CMS_WORKSPACE`	`headers.x-cms-workspace`	Identificador do workspace
`ARMS_SERVICE_NAME` / `OTEL_SERVICE_NAME`	`serviceName`	Nome do serviço
`ARMS_TRACE_DEBUG`	`debug`	Log de depuração (`true` / `1`)
`OTEL_RESOURCE_ATTRIBUTES`	`resourceAttributes`	Propriedades personalizadas do Resource (`key1=value1,key2=value2`)
`OTEL_SPAN_ATTRIBUTES`	`globalSpanAttributes`	Atributos globais do Span (`key1=value1,key2=value2`)

Prioridade: Arquivo de configuração > Variáveis de ambiente > Valores padrão.

Importante : O gateway do OpenClaw é executado no modo daemon por padrão e não herda variáveis de ambiente do shell de origem. Para desenvolvimento local, use o arquivo de configuração. As variáveis de ambiente são adequadas para ambientes de contêineres, como docker e Kubernetes.

diagnostics-otel

Parâmetro	Tipo	Obrigatório	Descrição
`enabled`	Boolean	Sim	Especifique se o recurso de diagnósticos deve ser ativado. Defina como `true` para ativá-lo.
`otel.enabled`	Boolean	Sim	Especifique se a exportação de dados do OpenTelemetry deve ser ativada. Defina como `true` para ativar.
`otel.endpoint`	String	Sim	Endpoint de envio de dados OTLP. O plugin anexa automaticamente o caminho `/v1/traces` ou `/v1/metrics`.
`otel.protocol`	String	Sim	Protocolo de envio. Atualmente, apenas `http/protobuf` é suportado.
`otel.headers`	Object	Sim	Os cabeçalhos de autenticação incluídos nas solicitações de envio.
`otel.serviceName`	String	Sim	O nome do serviço reportado. Deve ser consistente com o `serviceName` configurado em `opentelemetry-instrumentation-openclaw`.
`otel.traces`	Boolean	Sim	Especifique se os dados de rastreamento devem ser reportados. Recomendamos definir como `false`, pois o rastreamento é tratado pelo `opentelemetry-instrumentation-openclaw`.
`otel.metrics`	Boolean	Sim	Especifique se os dados de métricas devem ser reportados. Defina este parâmetro como `true` para visualizar métricas como uso de tokens, número de chamadas e latência.
`otel.logs`	Boolean	Sim	Especifique se os dados de log devem ser reportados. Este recurso não é suportado atualmente pelo Cloud Monitor 2.0. Recomendamos definir este parâmetro como `false`.
`otel.sampleRate`	Number	Não	A taxa de amostragem de rastreamento varia de 0.0 a 1.0 e se aplica apenas ao span raiz. Um valor de `1` indica amostragem completa.
`otel.flushIntervalMs`	Number	Não	O intervalo de atualização de dados em lote, em milissegundos. O valor mínimo é `1000` e o valor padrão é `60000`.

Etapa 3: Verifique a instalação

Execute o seguinte comando para verificar se os plugins estão ativos:

openclaw plugins list

A saída esperada é semelhante a esta:

┌───────────────────┬─────────────────┬──────────┬──────────┬────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬────────────┐
│ Name              │ ID              │ Format   │ Status   │ Source                                                                                                                                                                     │ Version    │
├───────────────────┼─────────────────┼──────────┼──────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼────────────┤
│ OpenClaw OTel     │ opentelemetry-  │ openclaw │ enabled  │ ~/.openclaw/extensions/opentelemetry-instrumentation-openclaw/dist/index.js                                                                                                │ 0.1.3-beta │
│ Plugin            │ instrumentation │          │          │ Report OpenClaw AI agent execution traces to any OTLP-compatible backend via OpenTelemetry                                                                                 │            │
│ @openclaw/        │ diagnostics-    │ openclaw │ enabled  │ ~/.openclaw/npm/node_modules/@openclaw/diagnostics-otel/dist/index.js                                                                                                      │ 2026.5.6   │
│ diagnostics-otel  │ otel            │          │          │                                                                                                                                                                            │            │
└───────────────────┴─────────────────┴──────────┴──────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴────────────┘

Etapa 4: Visualize os dados de monitoramento

Após a conclusão da instalação, envie algumas mensagens para o OpenClaw para acionar a execução do agente. Em seguida, visualize os dados de monitoramento reportados pelo OpenClaw no console do Cloud Monitor 2.0.

Faça login no console do Cloud Monitor 2.0 e selecione o workspace de destino.
No painel de navegação à esquerda, escolha Application Observability > AI Application Observability.
Na lista de aplicativos, localize o nome do serviço configurado (por exemplo, openclaw-gateway).
Clique em nome do aplicativo ou selecione Trace Analysis para visualizar o rastreamento, o consumo de tokens, as entradas e saídas do LLM e a distribuição de latência.

Desinstalar

Para desinstalar o plugin, execute o seguinte comando:

curl -fsSL https://arms-apm-cn-hangzhou-pre.oss-cn-hangzhou.aliyuncs.com/opentelemetry-instrumentation-openclaw/uninstall.sh | bash

O script de desinstalação remove automaticamente o diretório de instalação do opentelemetry-instrumentation-openclaw e todas as configurações relacionadas no openclaw.json. O script também desativa a configuração do diagnostics-otel.

Parâmetro	Descrição
`-y` / `--yes`	Ignora o prompt de confirmação.
`--install-dir`	Especifica o diretório de instalação do plugin. Caso não seja fornecido, o diretório será detectado automaticamente.
`--keep-metrics`	Desinstala apenas o `opentelemetry-instrumentation-openclaw` (Trace) e mantém a configuração do `diagnostics-otel` (Metrics).

Perguntas frequentes

Nenhum dado aparece no console após a configuração?

Verifique os seguintes itens em ordem:

Confirme se a versão do seu OpenClaw é a v26.2.19 ou posterior. Execute openclaw --version para verificar.
Confirme se o gateway foi reiniciado (ele reinicia automaticamente após uma instalação com um clique, mas exige a execução de openclaw gateway restart para uma instalação manual). Se a reinicialização falhar, execute openclaw doctor e reinicie o gateway após a correção dos problemas.
Confirme se a URL do endpoint está correta e acessível na rede. Teste a conectividade com curl.
Confirme se todos os três valores de cabeçalho (x-arms-license-key, x-arms-project e x-cms-workspace) foram inseridos corretamente.
Caso a versão do OpenClaw seja 2026.4.25 ou posterior, defina hooks.allowConversationAccess como true na configuração do plugin para impedir que a política de segurança bloqueie hooks relacionados à conversa. Se a versão for anterior à 2026.4.25, certifique-se de que a configuração não contenha o campo hooks para evitar um erro de "Unrecognized key".
Note que o flushIntervalMs padrão é de 60 segundos. Em tarefas de curta duração, aguarde alguns minutos até que os dados apareçam.

A integração afeta o desempenho?

O impacto é mínimo. O opentelemetry-instrumentation-openclaw usa o mecanismo de exportação em lote do OpenTelemetry. Os dados de Span são armazenados em buffer na memória e reportados em lotes em intervalos regulares, o que não bloqueia o fluxo normal de processamento do agente.

Posso instalar apenas o envio de rastreamentos?

Sim. Adicione o parâmetro --disable-metrics durante a instalação para ignorar a configuração do diagnostics-otel e ativar apenas o envio de rastreamentos.

Haverá conflito entre rastreamentos de plugins diferentes?

Não. O script de instalação define diagnostics.otel.traces como false por padrão. O componente opentelemetry-instrumentation-openclaw é responsável exclusivamente por reportar rastreamentos. Não ocorrerão conflitos mesmo se ambos reportarem dados simultaneamente.

A instalação substituirá as configurações existentes?

Não. O script de instalação usa uma estratégia de atualização por mesclagem: atualiza apenas os campos necessários, como endpoint e headers, e mantém inalteradas as configurações existentes para traces, logs e sampleRate.

Por que o consumo de tokens é sempre 0?

O OpenClaw v2026.3.8 contém um bug que causa a coleta incorreta do consumo de tokens. Esse bug foi corrigido na v2026.4.5 e em versões posteriores.

Posso usar gRPC para reportar dados?

O plugin diagnostics-otel no OpenClaw suporta apenas http/protobuf. Caso defina grpc, a configuração é ignorada silenciosamente. Nenhum erro é gerado, mas a configuração não tem efeito.