API 密钥管理

SayClaw 后台的「API 密钥管理」模块整合了三个功能：Key Vault（主密钥保险库）、模型注册表、子Key 清单。管理员可在此完成从模型维护到子Key分配再到实例同步的完整操作链路，无需依赖 AI 协助。

---

功能概览

Tab	功能	说明
主密钥 (Provider Keys)	录入各平台 API Key	加密存储，用于 LiteLLM 配置
子Key 管理 (Virtual Keys)	查看/生成 LiteLLM 子Key	可按实例分配
🤖 模型注册表	管理可用 AI 模型	CRUD 模型，是子Key分配的基础
🔑 子Key 清单	所有实例子Key汇总	可过滤、查看允许模型、一键同步

---

模型注册表

预置模型（5条）

供应商	Model ID	显示名称
OpenAI	litellm/gpt-5.2-pro	GPT-5.2 Pro
OpenAI	litellm/gpt-4o	GPT-4o
Google	litellm/gemini-3-pro-preview	Gemini 3 Pro
Google	litellm/gemini-2.0-flash	Gemini 2.0 Flash
Anthropic	litellm/claude-sonnet-4-6	Claude Sonnet 4.6

新增模型

1. 进入「API 密钥管理」→「🤖 模型注册表」Tab
2. 点击右上角「+ 新增模型」
3. 填写：供应商 / Model ID（格式：litellm/<模型名>）/ 显示名称 / 说明
4. 确认后自动刷新列表

停用模型

• 点击模型行右侧「状态」开关即可停用/启用
• 停用后的模型不再出现在子Key分配的模型选择列表里

---

子Key 系统

设计原则

• 一实例多Key：每个 OC 实例可拥有多个子 Key，按供应商分隔
• 模型白名单：每个子 Key 绑定允许使用的模型列表，LiteLLM 层强制执行
• 独立预算：每个子 Key 各自 $50 预算（默认），互不影响
• 全模型主Key：每个实例有一个 provider=all 的主 Key，不限模型，供实例直接使用

供应商子Key说明

provider	供应商	允许模型
openai	🟢 GPT	gpt-4o, gpt-5.2-pro
google	🔵 Gemini	gemini-3-pro-preview, gemini-2.0-flash
anthropic	🟠 Claude	claude-sonnet-4-6
all	🔘 全模型	不限（主Key）

子Key 清单

进入「🔑 子Key 清单」Tab 可以：

• 按供应商过滤：快速查看所有 OpenAI / Google / Anthropic key
• 按实例过滤：查看某实例下的所有子Key
• 查看预算/用量：预算/已用金额实时显示
• 一键同步到实例：点击「🔄 同步」按钮，将该实例所有活跃子Key的模型列表合并后写入 openclaw.json，并自动重启实例服务

---

同步流程

管理员操作「🔄 同步」
      ↓
POST /instances/:id/sync-models
      ↓
收集该实例所有 is_active=1 子Key 的 models 字段
      ↓
写入 task_queue（type=sync_models_to_instance）
      ↓
Scheduler Worker（每5秒扫描）
      ↓
SSH 到目标服务器 → python3 更新 openclaw.json agents.defaults.model.models
      ↓
systemctl restart <service_name>
      ↓
task_queue.status = "done"

同步结果可在「调度管理」→「任务队列」查看。

---

Admin API 接口

方法	路径	说明
GET	/api/v1/ai-models	获取模型注册表
POST	/api/v1/ai-models	新增模型
PUT	/api/v1/ai-models/:id	编辑/停用模型
GET	/api/v1/instance-keys	子Key全局清单（支持 provider/instance_id 过滤）
GET	/api/v1/instances/:id/keys	某实例的子Key列表
POST	/api/v1/instances/:id/keys	为某实例创建新子Key
DELETE	/api/v1/instances/:id/keys/:kid	停用子Key
POST	/api/v1/instances/:id/sync-models	同步模型到实例（异步任务）

---

DB 表结构

ai_models

CREATE TABLE ai_models (
  id           VARCHAR(36) PRIMARY KEY,
  provider     VARCHAR(50) NOT NULL,     -- openai/google/anthropic
  model_id     VARCHAR(100) NOT NULL,    -- litellm/gpt-4o
  label        VARCHAR(100) NOT NULL,    -- GPT-4o
  description  VARCHAR(255),
  is_active    TINYINT DEFAULT 1,
  sort_order   INT DEFAULT 0,
  created_at   DATETIME(3),
  updated_at   DATETIME(3),
  UNIQUE KEY uk_model_id (model_id)
);

oc_api_keys（扩展后）

-- 新增字段（相比初始版本）
ALTER TABLE oc_api_keys
  ADD COLUMN provider VARCHAR(50) NOT NULL DEFAULT 'all' AFTER instance_id,
  ADD COLUMN models   TEXT NULL COMMENT 'JSON数组，允许使用的模型列表',
  ADD UNIQUE KEY uk_instance_provider (instance_id, provider);