Custom GPT Actions 实战：从单一 GPT 到企业级 GPT 生态

Custom GPT Actions 是 OpenAI 给 GPT 增加的『调外部 API』能力。本文从单一 GPT 接自家 API 写到企业级部署——schema 设计、鉴权、GPT Store 发布、企业 Teams / Enterprise 共享、调试、安全最佳实践。

Actions 本质：GPT + OpenAPI + HTTP

┌────────────────────────────────────┐
│  用户问："客户 X 最近下了什么单？"  │
└────────────────────────────────────┘
              ↓
┌────────────────────────────────────┐
│  Custom GPT（LLM）                  │
│  - 看 system prompt + 用户问题      │
│  - 决定调哪个 action               │
│  - 决定传什么参数                    │
└────────────────────────────────────┘
              ↓
┌────────────────────────────────────┐
│  Actions 引擎（ChatGPT 代理）        │
│  - 调 HTTP endpoint                │
│  - 鉴权 header                     │
│  - 返回结果给 LLM                 │
└────────────────────────────────────┘
              ↓
┌────────────────────────────────────┐
│  后端 API（你的服务）              │
│  - /customers/{id}/orders          │
│  - 鉴权、查询、返回数据            │
└────────────────────────────────────┘

三个组件：

1. Custom GPT：用户配置的 GPT（有 system prompt + knowledge + Actions schema）。
2. Actions 引擎：ChatGPT 后端代理，负责 HTTP 调用 + 鉴权。
3. 后端 API：你的服务（CRM / 工单系统 / 知识库）。

Actions schema 设计

OpenAPI 3.1 子集是 Actions 的标准格式。最小示例：

openapi: 3.1.0
info:
  title: CRM API
  description: 客户与订单管理 API
  version: 1.0.0
servers:
  - url: https://crm.example.com/api
paths:
  /customers/{customer_id}/orders:
    get:
      operationId: get_customer_orders
      summary: 获取指定客户的最近订单
      description: |
        当用户询问「客户 X 的订单」「客户 X 最近买了什么」时调用。
        返回最近 30 天的订单列表。
      parameters:
        - name: customer_id
          in: path
          required: true
          schema:
            type: string
          description: 客户 ID（如 C001）
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 10
          description: 返回订单数量限制
      responses:
        '200':
          description: 订单列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  orders:
                    type: array
                    items:
                      type: object
                      properties:
                        order_id: { type: string }
                        amount: { type: number }
                        status: { type: string }
                        created_at: { type: string, format: date-time }

关键设计：

• operationId：GPT 用它来引用这个 action，命名要清晰（get_customer_orders 而非 getOrders1）。
• description：包含 trigger 条件（什么情况下 GPT 该调这个 action）和返回结构。这是 GPT 决定『调不调 / 怎么用』的核心依据。
• parameters 必须 schema 详细：每个参数都有 type / description，避免 GPT 传错值。

鉴权

OAuth 配置示例（接 Notion）：

Authorization URL: https://api.notion.com/v1/oauth/authorize
Token URL: https://api.notion.com/v1/oauth/token
Scopes: read_content, update_content

用户首次跟 GPT 对话时，会跳到 Notion 登录页授权，之后 GPT 拿短期 access token 调 API。

GPT Store 发布

发布到公共 GPT Store 的关键步骤：

1. 完成基础信息：logo、name（≤ 40 字）、description（≤ 8000 字）、category。
2. 隐私与法律：填写 privacy policy URL（公开页面）。
3. Actions 测试：每个 action 跑 10+ 测试用例，确认无 schema 错误。
4. Submit for review：在 GPT Builder 后台提交，OpenAI 团队人工审核（通常 1-2 周）。
5. Featured 推荐：审核通过后可申请首页 Featured——这才是 discoverability 的关键。

提高 discoverability 的三件事：

• 头像 + 名称 + 描述足够抓人（用户第一眼）。
• 类别标签准确（用户搜索时能命中）。
• 早期拉一波真实用户评分（分享到社群 / 朋友圈）。

企业部署

三种部署形态：

企业部署的关键设置：

• Privacy: Only people in my workspace
• Allowed users: SSO 域（如 @yourcompany.com）
• Audit log: 开启，记录每次调用
• Data retention: 控制 retention 周期（默认 30 天）

调试：Inspector 工具

Custom GPT 编辑器的 Actions tab 里有个 Inspector Playground：

1. 打开 GPT Builder → Actions → Test
2. 输入模拟 query："客户 C001 最近下了什么单？"
3. 看 GPT 是否触发 get_customer_orders action
4. 看参数是否正确（customer_id="C001"）
5. 看后端返回是否符合 schema

外部调试技巧：

• 用 ngrok http 8000 把本地服务暴露到公网，URL 填进 GPT 配置。
• 在后端加详细日志（每次调用打印 endpoint / params / user_id）。
• 生产前跑完整 test suite。

安全最佳实践

Actions 接进的是用户对话——攻击面比普通 API 大。三层防护：

1. 防 prompt injection

# 后端：不要把用户原话传给 GPT 作为『工具返回值』
@app.post("/query")
def query(query: str, user: User):
    # 用户的查询原话可能含 prompt injection
    # 不要 echo 回模型
    result = safe_search(query)
    return {"result": result, "trusted": True}

GPT 收到工具返回值时要知道『这是系统数据不是用户输入』。

2. 限流

# 每个 user / IP / endpoint QPS 限速
@limiter.limit("100/minute", key_func=lambda: request.user_id)
@limiter.limit("10/second", key_func=lambda: request.remote_addr)
def call_action():
    ...

Actions 一旦上线，单个用户可以高频调，限流是必须的。

3. 审计

# 每次调用记日志
audit_log.record(
    user_id=user.id,
    action="get_customer_orders",
    params={"customer_id": customer_id},
    timestamp=now(),
    response_status=200,
)

合规要求（金融 / 医疗）+ 事后溯源都需要 audit log。

完整 schema 示例

接企业 CRM 的最小可用 schema：

openapi: 3.1.0
info:
  title: Enterprise CRM
  description: 客户、订单、产品查询
  version: 1.0.0
servers:
  - url: https://crm.example.com/api/v1
paths:
  /customers/{customer_id}:
    get:
      operationId: get_customer
      summary: 查询客户基本信息
      parameters:
        - name: customer_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: 客户信息
          content:
            application/json:
              schema:
                type: object
                properties:
                  customer_id: { type: string }
                  name: { type: string }
                  email: { type: string }
                  tier: { type: string, enum: [gold, silver, bronze] }
  /customers/{customer_id}/orders:
    get:
      operationId: get_customer_orders
      summary: 查询客户订单
      parameters:
        - name: customer_id
          in: path
          required: true
          schema: { type: string }
        - name: limit
          in: query
          schema: { type: integer, default: 10 }
      responses:
        '200':
          description: 订单列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  orders:
                    type: array
                    items:
                      type: object
                      properties:
                        order_id: { type: string }
                        amount: { type: number }
                        status: { type: string }

部署 checklist

• Actions schema 用 OpenAPI 3.1，operationId / description 清晰
• 鉴权按场景选（自家 API 用 API key，第三方用 OAuth）
• 每个 action 跑 10+ 测试 query（正常 / 异常 / 边界）
• 后端有 prompt injection 防护（不 echo 用户原话）
• 限流按 user / IP / endpoint 多维度
• Audit log 记录 user_id / endpoint / params / 时间戳
• GPT Store 发布有 privacy policy URL
• 企业部署用 Private to workspace + SSO

常见坑

1. schema description 写得太笼统：GPT 不会精确知道何时调。description 必须含 trigger 条件 + 参数说明 + 返回结构。
2. 鉴权选 OAuth 但没配 refresh token：短期 access token 过期后用户要重新授权，体验差。配 refresh token 让 GPT 自动续期。
3. 不测边界 case：schema 测通后没测『参数缺失』『返回空』『返回错误』三种情况，GPT 拿到错误响应不知道怎么 fallback。
4. 企业部署忘了关 audit：默认开启但 retention 不设，企业合规要求保留 1 年以上。
5. schema 版本不演进：API 改了但 schema 没同步更新，GPT 拿到返回对不上 schema 直接报错。Schema 用 Git 管理，跟后端 API 同步更新。

下一步

• 想了解 Custom GPT 入门？读 《Custom GPTs 完全上手指南：从想法到发布到 GPT Store》。
• 想了解 GPT Store 上线全流程？读 《自定义 GPT 完全指南：从想法到上线 GPT Store》。
• 想了解 Actions 背后的 Responses API？读 《OpenAI API 函数调用实战：Responses API 工具使用完全指南》。