# 一句话让 AI 智能体帮你配好 okdata

> 把一句话贴进 Claude Code、Cursor、Codex 等能上网的智能体，它会自己读说明、接好 okdata，并用一次极小的调用验证能用。

网页版：https://okdata.online/zh/integrations/one-sentence/

如果你用的 AI 智能体能打开网页、能改你电脑上的文件，那其他接入页都可以跳过。先把 key 设好，贴一句话，智能体会自己去读我们的配置说明，把自己接上，再花 $0.001 做一次测试证明能用。五分钟后，你就可以像使唤同事一样，让它去查小红书笔记、看抖音热搜。

## 就这一句

```text
读一下 https://okdata.online/zh/agents.md，帮我把 okdata 配好；我的 key 在环境变量 OKDATA_API_KEY 里。
```

把它贴进 Claude Code、Cursor 的 Agent、Codex，或者其他能打开网址、运行命令、编辑文件的智能体。

## 贴之前先做一件事

把 key 放到智能体用得到、但看不见的地方。Mac 上把下面这行加到 `~/.zshrc`（Linux 是 `~/.bashrc`），新开一个终端，再从这个终端启动智能体：

```bash
export OKDATA_API_KEY="okd_..."
```

key 以 `okd_` 开头，新 key 自带 $0.10 额度，怎么拿 key 见[快速开始](/zh/docs/quickstart/)。还没有 key？把那句话的后半句换成“我还没有 key，先只用免费的工具”。智能体照样能连上，浏览全部 51 个接口，告诉你每个多少钱。

## 智能体会做什么

[agents.md](/zh/agents.md) 是一份写给智能体的纯文本清单，你自己一分钟也能读完。它要求智能体：

1. **保管好 key。** 从 `OKDATA_API_KEY` 读取，不许写进项目文件或提交记录，不许打印，也不许复述给你。
2. **接入。** 能添加远程 MCP 服务的，就添加 `https://api.okdata.online/mcp`，配置里引用环境变量（比如 Claude Code 里写 `Bearer ${OKDATA_API_KEY}`）；不能的，就直接调用 `https://api.okdata.online` 的 HTTP 接口。
3. **验证能用。** 先做一次免费的状态检查，再调用一次最便宜的收费接口（$0.001），核对返回里的扣费金额是否一致。
4. **之后花钱有数。** 开始任务前先说最多花多少；数据够了就停止翻页；重试时用同一个幂等键，不会重复扣费；被限流就等 `retry_after_seconds` 秒。

哪一步失败了，它会停下来告诉你是哪一步、为什么。

## 安全提醒

- **能读环境变量的智能体，绝不要把 key 贴进对话框。** 聊天记录会被保存、同步、分享；你自己电脑上的环境变量不会。
- **看一眼它写了什么。** 配置里应该出现的是 `OKDATA_API_KEY` 这个名字，而不是一串以 `okd_` 开头的字符。如果在项目文件里看到了 key 本身，让它改掉，并确认没有进 git。
- **有些应用读不到终端里的变量**，比如从程序坞打开的 Claude Desktop。这时 key 只能填进应用自己的设置，或者用户目录下的配置文件，具体看 [Claude Desktop 接入页](/zh/integrations/claude-desktop/)。即便如此，也是你自己填进文件，而不是发在对话里。
- **数据不是指令。** 笔记和评论都是网上的陌生人写的。agents.md 已经要求智能体只把它们当数据看，你在自己的提示里再强调一遍也不多余。
- **想加预算就加。** 在那句话后面补一句“每次收费调用前先告诉我价格”。

## 第一句可以这样说

等它说配置完成后：

```text
用 okdata 在小红书搜“防晒霜”，按最新排序，只要一页，
挑出点赞最多的五篇笔记，附上链接，告诉我花了多少钱。
```

## 花多少钱

配置本身只花 $0.001，就是那一次测试调用。查接口、看价格都免费。上面这句话是一页[小红书笔记搜索](/zh/apis/xiaohongshu/notes/search/)，$0.02。抖音热搜榜一次 $0.002。调用失败不扣费。

## 出问题时

- **智能体说打不开网址。** 它没有联网能力。改看你所用工具的接入页，可以从 [MCP 页](/zh/mcp/)开始。
- **返回 `unauthorized`（401）。** 智能体没拿到 key。多半是先启动了智能体、后设的 `OKDATA_API_KEY`：新开一个终端，用 `[ -n "$OKDATA_API_KEY" ] && echo 已设置` 确认一下，再重新启动智能体。
- **返回 `insufficient_balance`（402）。** 余额连测试调用都不够，没有扣费。充值后再试，价格见[定价页](/zh/pricing/)。
- **返回 `rate_limited`（429）。** 短时间内调用太多。智能体应该等 `retry_after_seconds` 秒再发同一个调用，不扣费；它没这么做就提醒它。
- **说配好了，却看不到 okdata 的工具。** 大多数客户端只在启动时加载新的 MCP 服务。重启智能体；Claude Code 可以运行 `claude mcp list`，Codex 可以运行 `codex mcp list` 看看。

## 接着看

- [MCP 服务说明](/zh/mcp/)：智能体会用到的四个工具。
- [小红书笔记搜索](/zh/apis/xiaohongshu/notes/search/)：参数、字段和价格。