# 在智能体里安装 Beatra Skill，用设备码登录
> 给 WorkBuddy、千问办公、豆包工作、Codex 或 Claude Code 发一条消息装好 Beatra Skill，在浏览器批准一次设备码登录。

步骤最后验证：2026-11-09

Beatra Skill 把 Beatra 的全部能力（图片、视频、音乐、语音和公开社交数据）装进一个包。给智能体发一条消息就能装好；之后 Skill 用设备码登录 Beatra，你在浏览器里批准一次，登录信息只保存在你自己的电脑上。安装和登录免费，生成媒体消耗 Beatra 积分。

## 开始之前 [#requirements]

| 项目 | 要求 |
| --- | --- |
| 智能体 | WorkBuddy、千问办公、豆包工作、Codex、Claude Code、Cursor，或其他能安装 Skill、能运行脚本的智能体 |
| Python | 智能体运行的机器上有 Python 3.10 或更高版本。Skill 的脚本只用标准库。 |
| 网络 | 能访问 HTTPS。Skill 会自动为这台电脑选择国际线路或中国大陆线路的 Beatra 服务地址。 |
| 账号 | 一个 Beatra 账号。授权页面上可以直接登录或注册。 |
| 费用 | 安装和登录免费，生成消耗积分，见[计费与用量](https://docs.beatra.cn/zh/docs/mechanisms/billing)。 |

### 发送安装消息

```text title="发给智能体"
请帮我安装 Beatra；需要登录授权时告诉我：https://beatra.ai/install.md
```

智能体会从 Beatra 下载 Skill 安装包，解压前先校验 SHA-256，再用智能体自己的 Skill 机制把 `beatra` 目录装好，和你的其他 Skill 放在一起。

**检查点**

- [x] 智能体告诉你 Beatra Skill 已安装。

### 在浏览器里批准设备码

Skill 会运行它的登录助手 `scripts/authorize.py`。助手向 Beatra 申请设备码，并在浏览器里打开授权页面；打不开浏览器时，智能体会把链接发给你。在页面上登录，然后点「允许连接」。授权页面最长保持一小时，智能体会自己发现你已批准，不需要你在对话里确认。

**检查点**

- [x] 授权页面显示「已批准」，智能体接上后变成「已连接」。
- [x] 智能体告诉你 Beatra 已就绪。助手用一次不扣费的请求检查新连接，不会产生费用。

### 发出第一个请求

有些智能体只在会话开始时加载 Skill。你的智能体如果是这样，先开一个新会话，再说出你想要的结果：

```text title="发给智能体"
帮我做一张秋季咖啡新品海报，竖版，顶部留出标题位置
```

**检查点**

- [x] 智能体确认已创建 Beatra 任务，之后交给你成品和本次消耗的积分。

### 在控制台里找到这台电脑

打开[控制台](https://console.beatra.cn/agents)的「设备」。Skill 登录过的每台电脑都列在这里，可以随时断开任意一台。

**检查点**

- [x] 「设备」里列出了这台电脑，状态是已连接。

## 电脑上保存了什么 [#local-files]

登录信息只保存在你的用户目录 `~/.beatra/` 下：`credentials.json` 存设备凭据，`installation.json` 存一个固定的安装标识，不含密钥。在 macOS 和 Linux 上，这个目录只有你自己的用户能读（目录权限 0700，文件 0600）。同一台电脑上的所有 Beatra Skill 共用这一份登录，再装一个 Beatra Skill 不需要再批准一次。

## 保持登录 [#stay-signed-in]

- 每次使用 Skill 都会自动续期；连续 15 天没有使用，登录失效。
- 失效后，或者在控制台断开这台电脑后，让智能体重新运行 `python3 scripts/authorize.py`，批准一次即可。
- 想换另一个 Beatra 账号，让智能体运行 `python3 scripts/authorize.py --force`，用那个账号批准。

## 更新 Skill [#update]

Skill 会一直停留在安装时的版本。它每天最多检查一次你当初安装它的商店或工具；那里有新版本时，输出一行提示，写明更新命令。用安装消息装的，把安装消息再发一次就会更新到最新版本。其他安装方式的更新命令见[排错指南：版本不兼容](https://docs.beatra.cn/zh/docs/troubleshooting#version-mismatch)。

## 卸载 Skill [#uninstall]

让智能体卸载 Beatra。它会先运行 Skill 里的 `scripts/uninstall.py`：如果这是这台电脑上最后一个 Beatra Skill，脚本会断开这台电脑与 Beatra 的连接，并删除 `~/.beatra/` 里的登录文件；还有其他 Beatra Skill 时，共用的登录保留。然后智能体删除 Skill 目录。

## 某一步没成功 [#if-a-step-fails]

把同一句安装消息再发一次。智能体会保留已经正确的设置，只继续没做完的部分。遇到具体提示时：

- `BEATRA_AUTH_PENDING`、`access_denied`、`expired_token` 或 `BEATRA_AUTH_REQUIRED`：见[排错指南：登录失败](https://docs.beatra.cn/zh/docs/troubleshooting#sign-in)。
- 微信二维码或验证码的问题：见[登录问题排查](https://docs.beatra.cn/zh/docs/sign-in-help)。
- 提示积分不足：见[排错指南：积分不足](https://docs.beatra.cn/zh/docs/troubleshooting#credits)。

想比较 Skill、Beatra MCP 和 REST API，见[选择使用方式](https://docs.beatra.cn/zh/docs/choose-integration)。Skill 能调用的每个工具见 [MCP 工具参考](https://docs.beatra.cn/zh/docs/mcp-tools)。