For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /guide/guides/private-market.md.
  • 简体中文
  • 自建插件市场与专家市场

    运行 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
    变量含义
    OCTOP_PORTAL_ORIGIN目录源站,只写协议、主机和端口,不要带路径。未设置时默认 https://octop.cloud。空字符串会关闭远程目录。
    OCTOP_MARKET_REMOTE_ORIGIN安装包源站,同样只写协议、主机和端口。未设置或无法解析时默认 https://download.octop.cloud。

    目录和安装包可以放在同一台机器上,所以上面两个值可以相同。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。

    市场打不开时

    你看到的现象要检查的地方
    插件市场或专家市场显示暂时不可用列表请求失败、超时,或 OCTOP_PORTAL_ORIGIN 为空。在 Octop 所在机器上 curl 两个列表地址,确认 8 秒内返回 "success": true。
    卡片在,安装却提示没有安装包download_url 的协议、主机或端口与 OCTOP_MARKET_REMOTE_ORIGIN 不一致。
    安装后版本对不上目录 version 与 plugin.yaml 不一致,或专家 slug 与 manifest.json 的 id 不一致。
    改了 JSON,页面不变进程内缓存大约 30 秒。等待,或重启 Octop。
    图标是空白图标地址仍指向公网。改成 emoji、icon_name,或浏览器和 Octop 都能打开的地址。