Clawdbot API密钥配置失败会导致无法调用远程服务或触发自动化任务；需通过控制台获取唯一SK开头密钥，再以环境变量、config.yaml或Docker注入方式配置，并验证权限与作用域。
如果您已下载Clawdbot客户端并准备启用其API功能，但无法调用远程服务或触发自动化任务，则很可能是API密钥未正确配置。以下是完成Clawdbot API密钥配置及进阶使用的具体步骤：
一、获取Clawdbot API密钥
API密钥是Clawdbot服务端识别合法客户端身份的唯一凭证，必须通过官方控制台生成，不可复用他人密钥或使用默认值。
1、访问 https://console.clawdbot.dev/login 并使用注册邮箱登录。
2、在左侧导航栏点击 “API管理” 选项卡。
3、点击页面右上角 “新建密钥” 按钮。
4、在弹出窗口中输入描述性名称（如“prod-server-01”），勾选所需权限范围（仅勾选 “bot:execute” 和 “webhook:read” 即可），然后点击确认。
5、系统生成密钥后，立即复制显示的 SK_开头的32位字符串 ——该密钥**仅显示一次**，关闭页面后不可再次查看。
二、在Clawdbot CLI中配置密钥
Clawdbot命令行工具通过环境变量或配置文件读取密钥，优先级为：命令行参数 > 环境变量 > 配置文件。推荐使用环境变量方式以避免密钥硬编码。
1、打开终端，执行以下命令写入环境变量（Linux/macOS）：
export CLAWDBOT_API_KEY="SK_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
2、若使用Windows PowerShell，运行：
$env:CLAWDBOT_API_KEY="SK_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
3、验证是否生效：运行 clawdbot auth test，返回 "status": "authenticated" 即表示密钥已加载成功。
三、在config.yaml中静态配置密钥
适用于容器化部署或需多环境隔离的场景。配置文件中的密钥将被CLI自动加载，无需每次启动时设置环境变量。
1、在用户主目录下创建 ~/.clawdbot/config.yaml（Windows为 %USERPROFILE%\.clawdbot\config.yaml）。
2、写入以下内容（注意缩进为两个空格，冒号后保留一个空格）：
api_key: SK_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
3、确保文件权限为仅当前用户可读：
chmod 600 ~/.clawdbot/config.yaml（Linux/macOS）。
四、在Docker容器中注入密钥
Docker环境下禁止将密钥写入镜像层，必须通过运行时注入方式传递，防止密钥泄露至镜像历史记录中。
1、构建镜像时不包含任何密钥字段，基础Dockerfile保持如下结构：
FROM clawdbot/cli:latest
2、运行容器时通过 --env 参数传入：
docker run --env CLAWDBOT_API_KEY=SK_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx clawdbot/cli:latest bot start
3、若使用docker-compose.yml，应在 services.bot.environment 下添加：
CLAWDBOT_API_KEY: "${CLAWDBOT_API_KEY}"，并在宿主机shell中预先 export 该变量。
五、验证API密钥权限与作用域
密钥权限错误会导致特定接口返回403 Forbidden而非401 Unauthorized。必须确认当前密钥具备目标操作所需的最小权限集。
1、执行 clawdbot webhook list，若返回 "error": "insufficient_scope"，说明密钥缺少 webhook:read 权限。
2、重新进入控制台，找到对应密钥，点击 “编辑权限”，勾选缺失项并保存。
3、CLI端无需重启，下次请求将自动携带更新后的权限声明。
