自建插件市场与专家市场
运行 Octop 的机器访问不了 octop.cloud 或 download.octop.cloud 时,可以在自己的网络里提供这两份目录,不需要部署完整的公网门户。Octop 读取两份 JSON 列表,再按条目里的 download_url 下载安装包。
技能市场是另一套服务,见技能市场。
Octop 怎么读取目录
打开插件市场或专家市场
│
▼
Octop 进程 GET {OCTOP_PORTAL_ORIGIN}/api/market/plugins
GET {OCTOP_PORTAL_ORIGIN}/api/market/experts
│
│ 成功后把 data.items 缓存 30 秒
▼
你点击安装
│
▼
Octop 进程 GET 该条目的 download_url
(协议、主机、端口必须与 OCTOP_MARKET_REMOTE_ORIGIN 一致)
两份目录都是一次取全量,Octop 不传查询参数。专家的搜索和场景筛选在本地完成,所以每条专家都要带上 content 和 quick_prompts。详情页读的是同一份缓存,不会再请求 /{id}。
请求不带登录态,把市场放在内网。Octop 不会附带 Token。
单次目录响应不超过 1 MiB,必须在 8 秒内返回。请求头是 Accept: application/json 和 User-Agent: Octop。success 必须是 JSON 布尔值 true,data.items 必须是数组,不是对象的元素会被丢掉。HTTP 错误、超时、门户地址为空,或者 success 不是 true,都算目录不可用,插件市场和专家市场会显示暂时不可用。
成功结果在进程里缓存 30 秒。改完 JSON 后等一会儿,或重启 Octop,再刷新页面。
让 Octop 指向自建市场
在运行 octop run 的机器上设置环境变量,然后重启进程。可以写进 ~/.octop/env(服务启动时会载入),也可以写进 systemd 的 Environment=。
OCTOP_PORTAL_ORIGIN=http://market.internal:9000
OCTOP_MARKET_REMOTE_ORIGIN=http://market.internal:9000
目录和安装包可以放在同一台机器上,所以上面两个值可以相同。download_url 的协议、主机和端口必须与 OCTOP_MARKET_REMOTE_ORIGIN 一致。环境变量写了端口时,URL 也要使用该端口。没写端口时,Octop 使用该协议的默认端口。路径和查询参数不限制。
静态安装包可以这样放:
/octop/market/plugins/{id}/{version}/{id}-{version}.zip
/octop/market/experts/{slug}/{version}/{slug}-{version}.zip
图标不要指向公网。浏览器直接加载插件卡片的 icon。专家的 icon_url 若是 http 或 https 图片,Octop 进程会在创建专家时下载。下载失败时,创建照常继续,只是不用这张图。使用内网能打开的地址,或改用 icon_name。
HTTP 接口
Octop 只调用下面两个列表接口,安装包来自 download_url。
openapi: 3.0.3
info:
title: Octop private plugin and expert market
version: "1"
description: >
Catalog read by the Octop server. Octop calls only the two list
operations. Archive bytes are fetched from download_url.
servers:
- url: http://market.internal:9000
paths:
/api/market/plugins:
get:
operationId: listMarketPlugins
summary: Full plugin catalog
responses:
"200":
description: Catalog envelope
content:
application/json:
schema:
$ref: "#/components/schemas/PluginCatalog"
/api/market/experts:
get:
operationId: listMarketExperts
summary: Full expert catalog
responses:
"200":
description: Catalog envelope
content:
application/json:
schema:
$ref: "#/components/schemas/ExpertCatalog"
components:
schemas:
Localized:
oneOf:
- type: string
- type: object
properties:
zh: { type: string }
en: { type: string }
PluginCatalog:
type: object
required: [success, data]
properties:
success: { type: boolean, enum: [true] }
data:
type: object
required: [items]
properties:
items:
type: array
items: { $ref: "#/components/schemas/Plugin" }
ExpertCatalog:
type: object
required: [success, data]
properties:
success: { type: boolean, enum: [true] }
data:
type: object
required: [items]
properties:
items:
type: array
items: { $ref: "#/components/schemas/Expert" }
Plugin:
type: object
required: [id, version, download_url]
properties:
id: { type: string, pattern: "^[A-Za-z0-9][A-Za-z0-9._-]{0,80}$" }
version: { type: string }
name: { $ref: "#/components/schemas/Localized" }
description: { $ref: "#/components/schemas/Localized" }
kind: { type: string, default: tool }
icon: { type: string, description: "Emoji, or an http(s) URL the browser can load" }
group: { type: string }
requires:
type: array
items: { type: string }
download_url: { type: string, format: uri }
updated_at: { type: string, description: "ISO-8601. Octop sorts newer stamps first." }
Expert:
type: object
required: [slug, download_url]
properties:
id: { type: string }
slug: { type: string, pattern: "^[A-Za-z0-9][A-Za-z0-9._-]{0,80}$" }
label: { $ref: "#/components/schemas/Localized" }
description: { $ref: "#/components/schemas/Localized" }
scene: { type: string }
sub_scene: { type: string }
icon_url: { type: string, description: "http(s) raster image, or omit and use icon_name" }
icon_name: { type: string }
color: { type: string }
skill_slugs:
type: array
items: { type: string }
skill_count: { type: integer }
content: { $ref: "#/components/schemas/Localized" }
quick_prompts:
type: array
items:
type: object
properties:
title: { $ref: "#/components/schemas/Localized" }
description: { $ref: "#/components/schemas/Localized" }
prompt: { $ref: "#/components/schemas/Localized" }
color: { type: string }
icon_name: { type: string }
task_examples:
type: object
properties:
zh: { type: array, items: { type: string } }
en: { type: array, items: { type: string } }
download_url: { type: string, format: uri }
updated_at: { type: string }
id 和 slug 以字母或数字开头,后面可以是字母、数字、.、_、-,总共最长 81 个字符。
安装插件时,目录里的 version 必须和压缩包内 plugin.yaml 的 version 逐字一致,id 也必须一致。安装专家时,压缩包里 manifest.json 的 id 必须等于目录里的 slug。
updated_at 使用同一种 ISO-8601 写法,例如 2026-10-26T00:00:00Z。Octop 按这个字符串倒序排列。
已知的插件分组会显示成翻译后的标签,其他字符串归到其他:lifestyle、news、finance、media、fun、games、tools、ops。
已知的专家场景会翻译,其他字符串按原文显示:ecommerce、finance、content-creation、lifestyle、marketing、mysticism、academic、legal、tech、education、healthcare、hr、media、design。
最小部署
同一源站同时提供目录和文件时,目录可以这样放:
/srv/market/
├── api/market/plugins # Content-Type: application/json
├── api/market/experts
└── octop/market/
├── plugins/weather/0.1.0/weather-0.1.0.zip
└── experts/ops-engineer/1.0.0/ops-engineer-1.0.0.zip
api/market/plugins 的正文:
{
"success": true,
"data": {
"items": [
{
"id": "weather",
"version": "0.1.0",
"name": { "zh": "天气", "en": "Weather" },
"description": { "zh": "查询城市天气", "en": "City weather" },
"kind": "tool",
"icon": "☀️",
"group": "lifestyle",
"requires": [],
"download_url": "http://market.internal:9000/octop/market/plugins/weather/0.1.0/weather-0.1.0.zip",
"updated_at": "2026-10-26T00:00:00Z"
}
]
}
}
用 Nginx 把这个目录挂到任意端口,下面的 9000 只是示例。改端口时,环境变量和每条 download_url 里的端口也要一起改。api/market/plugins 和 api/market/experts 没有扩展名,需要自己标成 JSON:
server {
listen 9000;
server_name market.internal;
root /srv/market;
location /api/market/ {
default_type application/json;
}
}
设好两个环境变量并重启 Octop,插件市场和专家市场应列出你的条目。安装时只会向 market.internal 请求 ZIP。
市场打不开时