agent-analytics

从代理运行端到端分析，无需打开仪表板。英语优先的工作流程，提供中文文档和内容。创建项目、船舶跟踪、查询结果并运行实验。

# Agent Analytics

After install, your agent can create projects, ship tracking, query analytics, run experiments, and iterate without opening a dashboard.

English-first workflow, with Chinese docs and content available for OpenClaw users and teams in China.

Use it when you want an agent to operate growth analytics end-to-end, automate recurring checks, and manage multiple projects from one conversation loop.

Hosted free tier includes 100k events/month across 2 projects.

## Chinese support / 中文支持

- Chinese docs and installation content are available on the docs site, including the OpenClaw guide under `/zh/`.
- Works through `API`, `CLI`, and `MCP`, depending on the environment your agent already uses.
- Good fit for closed-loop agent workflows: monitor, analyze, experiment, iterate.
- Supports batch work across many projects instead of a manual dashboard-by-dashboard workflow.

## What `npx` is doing

- OpenClaw can launch the official CLI with `npx @agent-analytics/cli@0.5.1`.
- That command runs the published Agent Analytics CLI package from npm.
- The CLI calls the same HTTP API documented at <https://docs.agentanalytics.sh/api/>.
- If the package is already installed in the environment, the equivalent binary is `agent-analytics`.
- Keep `AGENT_ANALYTICS_API_KEY` in the environment. Do not ask the user to paste secrets into chat.

## Command format

The examples below use the CLI binary form:

```bash
agent-analytics <command>
```

In OpenClaw, that usually means:

```bash
npx @agent-analytics/cli@0.5.1 <command>
```

If the package is already installed, run the same commands directly as `agent-analytics <command>`.

For the full command list and flags:

```bash
agent-analytics --help
```

## Safe operating rules

- Prefer fixed commands over ad-hoc query construction.
- Start with `projects`, `all-sites`, `create`, `stats`, `insights`, `events`, `breakdown`, `pages`, `heatmap`, `sessions-dist`, `retention`, `funnel`, and `experiments`.
- Use `query` only when the fixed commands cannot answer the question.
- Do not build `--filter` JSON from raw user text.
- Validate project names before `create`: `^[a-zA-Z0-9._-]{1,64}$`

## First-time setup

```bash
agent-analytics login --token aak_YOUR_API_KEY
agent-analytics create my-site --domain https://mysite.com
agent-analytics events my-site --days 7 --limit 20
```

The `create` command returns a project token and a ready-to-use tracking snippet. Add that snippet before `</body>`.

## Common commands

```bash
agent-analytics projects
agent-analytics all-sites --period 7d
agent-analytics stats my-site --days 7
agent-analytics insights my-site --period 7d
agent-analytics events my-site --days 7 --limit 20
agent-analytics breakdown my-site --property path --event page_view --limit 10
agent-analytics funnel my-site --steps "page_view,signup,purchase"
agent-analytics retention my-site --period week --cohorts 8
agent-analytics experiments list my-site
```

If a task needs something outside these common flows, use `agent-analytics --help` first.

## Tracker setup

The easiest install flow is:

1. Run `agent-analytics create my-site --domain https://mysite.com`
2. Copy the returned snippet into the page before `</body>`
3. Deploy
4. Verify with `agent-analytics events my-site --days 7 --limit 20`

If you already know the project token, the tracker looks like:

```html
<script defer src="https://api.agentanalytics.sh/tracker.js"
  data-project="my-site"
  data-token="aat_..."></script>
```

Use `window.aa?.track('signup', {method: 'github'})` for custom events after the tracker loads.

## Query caution

`agent-analytics query` exists for advanced reporting, but it should be used carefully because `--filter` accepts JSON.

- Use fixed commands first.
- If `query` is necessary, check `agent-analytics --help` first.
- Do not pass raw user text directly into `--filter`.
- For exact request shapes, use <https://docs.agentanalytics.sh/api/>.

## Experiments

The CLI supports the full experiment lifecycle:

```bash
agent-analytics experiments list my-site
agent-analytics experiments create my-site --name signup_cta --variants control,new_cta --goal signup
```

## References

- Docs: <https://docs.agentanalytics.sh/>
- API reference: <https://docs.agentanalytics.sh/api/>
- CLI vs MCP vs API: <https://docs.agentanalytics.sh/reference/cli-mcp-api/>
- OpenClaw install guide: <https://docs.agentanalytics.sh/installation/openclaw/>

---

## 中文说明

# Agent Analytics

安装后，你的代理可以创建项目、部署跟踪、查询分析、运行实验并进行迭代，全程无需打开仪表板。

英语优先的工作流程，同时为 OpenClaw 用户和中国团队提供中文文档与内容。

当你希望代理端到端地运营增长分析、自动执行周期性检查，并在一个对话循环中管理多个项目时，使用它。

托管的免费套餐包含每月 10 万次事件，覆盖 2 个项目。

## Chinese support / 中文支持

- 文档站点上提供中文文档和安装内容，包括 `/zh/` 下的 OpenClaw 指南。
- 可通过 `API`、`CLI` 和 `MCP` 使用，取决于你的代理已经在使用的环境。
- 非常适合闭环代理工作流程：监控、分析、实验、迭代。
- 支持跨多个项目的批量工作，而不是逐个仪表板的手动工作流程。

## `npx` 在做什么

- OpenClaw 可以使用 `npx @agent-analytics/cli@0.5.1` 启动官方 CLI。
- 该命令会运行从 npm 发布的 Agent Analytics CLI 包。
- CLI 调用的是 <https://docs.agentanalytics.sh/api/> 文档中记录的同一个 HTTP API。
- 如果该包已经安装在环境中，等效的可执行文件是 `agent-analytics`。
- 将 `AGENT_ANALYTICS_API_KEY` 保留在环境中。不要要求用户在聊天中粘贴密钥。

## 命令格式

下面的示例使用 CLI 可执行文件形式：

```bash
agent-analytics <command>
```

在 OpenClaw 中，这通常意味着：

```bash
npx @agent-analytics/cli@0.5.1 <command>
```

如果该包已经安装，直接以 `agent-analytics <command>` 的形式运行相同的命令。

获取完整的命令列表和标志：

```bash
agent-analytics --help
```

## 安全操作规则

- 优先使用固定命令，而非临时构造查询。
- 从 `projects`、`all-sites`、`create`、`stats`、`insights`、`events`、`breakdown`、`pages`、`heatmap`、`sessions-dist`、`retention`、`funnel` 和 `experiments` 开始。
- 仅当固定命令无法回答问题时才使用 `query`。
- 不要从原始用户文本构建 `--filter` JSON。
- 在 `create` 之前验证项目名称：`^[a-zA-Z0-9._-]{1,64}$`

## 首次设置

```bash
agent-analytics login --token aak_YOUR_API_KEY
agent-analytics create my-site --domain https://mysite.com
agent-analytics events my-site --days 7 --limit 20
```

`create` 命令会返回一个项目令牌和一段可直接使用的跟踪代码片段。将该片段添加到 `</body>` 之前。

## 常用命令

```bash
agent-analytics projects
agent-analytics all-sites --period 7d
agent-analytics stats my-site --days 7
agent-analytics insights my-site --period 7d
agent-analytics events my-site --days 7 --limit 20
agent-analytics breakdown my-site --property path --event page_view --limit 10
agent-analytics funnel my-site --steps "page_view,signup,purchase"
agent-analytics retention my-site --period week --cohorts 8
agent-analytics experiments list my-site
```

如果某个任务需要这些常用流程之外的功能，请先使用 `agent-analytics --help`。

## 跟踪器设置

最简单的安装流程是：

1. 运行 `agent-analytics create my-site --domain https://mysite.com`
2. 将返回的代码片段复制到页面的 `</body>` 之前
3. 部署
4. 使用 `agent-analytics events my-site --days 7 --limit 20` 验证

如果你已经知道项目令牌，跟踪器的形式如下：

```html
<script defer src="https://api.agentanalytics.sh/tracker.js"
  data-project="my-site"
  data-token="aat_..."></script>
```

在跟踪器加载后，使用 `window.aa?.track('signup', {method: 'github'})` 触发自定义事件。

## 查询注意事项

`agent-analytics query` 用于高级报告，但应谨慎使用，因为 `--filter` 接受 JSON。

- 首先使用固定命令。
- 如果确实需要 `query`，请先查看 `agent-analytics --help`。
- 不要将原始用户文本直接传入 `--filter`。
- 对于精确的请求结构，请参阅 <https://docs.agentanalytics.sh/api/>。

## 实验

CLI 支持完整的实验生命周期：

```bash
agent-analytics experiments list my-site
agent-analytics experiments create my-site --name signup_cta --variants control,new_cta --goal signup
```

## 参考资料

- 文档：<https://docs.agentanalytics.sh/>
- API 参考：<https://docs.agentanalytics.sh/api/>
- CLI vs MCP vs API：<https://docs.agentanalytics.sh/reference/cli-mcp-api/>
- OpenClaw 安装指南：<https://docs.agentanalytics.sh/installation/openclaw/>