实例管理

管理所有 OC（OpenClaw）实例的生命周期：创建、配置、健康监控、TG 绑定、聊天绑定、用户分配。

最后更新：2026-03-09

---

1. 实例清单

服务器 ai-jp-1（35.243.76.69）

实例 ID	端口	说明
oc-xialong-main	18789	⚠️ 已交付客户，不可操作

服务器 ai-jp-2（34.85.76.114）

实例 ID	服务名	端口
oc-ai-jp-2-01 ~ 10	openclaw / openclaw-02~10	18789 ~ 18798

服务器 ai-jp-3

实例 ID	端口
oc-ai-jp-3-01 ~ 08	18801 ~ 18808

---

2. API

实例列表

GET /api/v1/instances

返回所有实例（含服务器、健康状态、gateway 信息）。

实例详情

GET /api/v1/instances/:id

返回实例详细信息（config_json、server_id、gateway_port/url/token、健康状态）。

创建实例

POST /api/v1/oc-instances
Body: { id, name, server_id, gateway_port, gateway_url?, gateway_token?, model?, config_json? }

更新实例

PATCH /api/v1/oc-instances/:id
Body: { name?, model?, gateway_port?, gateway_url?, gateway_token?, config_json?, notes? }

删除实例

DELETE /api/v1/oc-instances/:id

软删除（设 deleted_at）。

更新实例配置

PATCH /api/v1/instances/:id/config
Body: { config_json }

直接更新 config_json 字段（JSON 格式的 openclaw.json 配置）。

分配用户

PATCH /api/v1/instances/:id/assign
Body: { user_id }

将实例分配给指定 Portal 用户。

健康检查

GET /api/v1/instances/health-check

触发全量健康检查，返回各实例状态。

---

3. 聊天绑定（Chat Bindings）

管理实例与 Telegram Bot 的绑定关系。

获取绑定

GET /api/v1/instances/:id/chat-bindings

添加绑定

POST /api/v1/instances/:id/chat-bindings
Body: { platform, bot_token, chat_id?, bot_username? }

删除绑定

DELETE /api/v1/instances/:id/chat-bindings/:bid

---

4. Telegram 配置

配置 TG Bot

POST /api/v1/instances/:id/configure-telegram
Body: { bot_token }

自动设置 webhook、获取 bot info、写入绑定。

查询 TG 状态

GET /api/v1/instances/:id/telegram-status

---

5. 实例 HOME 目录规范

实例	HOME 目录	配置文件
小龙主实例	/root/.openclaw	/root/.openclaw/openclaw.json
小二 01	/root/.openclaw	/root/.openclaw/openclaw.json
小二 02–10	/opt/oc-home-NN/.openclaw	/opt/oc-home-NN/.openclaw/openclaw.json

---

6. 模型可用列表

通过 One API（http://35.243.76.69:3001）：

模型别名	Provider
claude-opus-4-6	Anthropic
claude-sonnet-4-6	Anthropic
claude-haiku-4-5	Anthropic
gpt-4o	OpenAI
gpt-4o-mini	OpenAI
gemini-3.1-pro	Google
gemini-3-flash	Google
gemini-2.5-flash	Google
gemini-2.5-pro	Google

Fallback 链：claude-opus → sonnet → gpt-4o → gemini-2.5-flash

---

7. 健康状态

状态	含义
healthy	服务运行中，Key 有效
unhealthy	SSH 检查 inactive 或 HTTP 超时
key_invalid	服务运行但 One API key 已失效
unknown	尚未检查或检查失败

---

8. 数据库

CREATE TABLE oc_instances (
    id VARCHAR(100) PRIMARY KEY,
    container_id VARCHAR(100),
    server_id VARCHAR(36),
    assigned_user_id VARCHAR(36),
    name VARCHAR(100),
    gateway_port INT,
    gateway_url VARCHAR(255),
    gateway_token VARCHAR(255),
    model VARCHAR(100),
    health_status VARCHAR(20) DEFAULT 'unknown',
    health_fail_count INT DEFAULT 0,
    total_requests BIGINT DEFAULT 0,
    total_tokens BIGINT DEFAULT 0,
    last_health_at DATETIME(3),
    created_at DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3),
    deleted_at DATETIME(3),
    notes TEXT,
    config_json TEXT
);

CREATE TABLE oc_chat_bindings (
    id VARCHAR(36) PRIMARY KEY,
    instance_id VARCHAR(100) NOT NULL,
    platform VARCHAR(20) DEFAULT 'telegram',
    bot_token VARCHAR(255),
    chat_id VARCHAR(100),
    bot_username VARCHAR(100),
    is_active TINYINT(1) DEFAULT 1,
    created_at DATETIME(3) DEFAULT CURRENT_TIMESTAMP(3)
);