DEV Community: Let's Write

告別逾期罰單！用 n8n 免費打造全台路邊停車費自動查詢 Telegram 機器人通知

Let's Write — Tue, 15 Sep 2026 12:41:53 +0000

本篇要解決的問題

最近裝的一個 App，因為變成必須要付費訂閱，才能有自動繳停車費的功能。為了避免停車費過期而多收錢，所以讓 ChatGPT 寫一個簡單的 n8n Workflow，匯入後修改一下設定資料，就可以每天自動通知還有沒有未繳的停車費。

August 希望做到以下幾件事：

不用每天自己打開停車費網站查詢。
可以同時查詢汽車、機車。
可以設定多台車。
一次查詢多個縣市。
每天固定時間自動執行。
有未繳停車費時，主動透過 Telegram 通知。
某個縣市 API 發生錯誤時，也要告訴我，不能直接把它當成「沒有欠費」。

而且，以上全部的需求，都可以放在 同一個 n8n Workflow 裡，不需要汽車、機車各做一份。

Workflow JSON 下載、匯入

直接複製以下 n8n Workflow，接著進入 n8n，直接貼上：

{
  "name": "全台路邊停車費自動查詢｜多車輛＋21縣市＋Telegram v4",
  "nodes": [
    {
      "parameters": {},
      "id": "9d4d1385-782c-4c2d-9c50-5b1a80cf6d83",
      "name": "手動測試",
      "type": "n8n-nodes-base.manualTrigger",
      "typeVersion": 1,
      "position": [-1160, 160]
    },
    {
      "parameters": {
        "rule": {
          "interval": [
            {
              "field": "cronExpression",
              "expression": "0 9 * * *"
            }
          ]
        }
      },
      "id": "ec576177-01d7-468f-8777-196e1656a71d",
      "name": "每天 09:00",
      "type": "n8n-nodes-base.scheduleTrigger",
      "typeVersion": 1.2,
      "position": [-1160, -40]
    },
    {
      "parameters": {
        "assignments": {
          "assignments": [
            {
              "id": "4728964e-002f-4430-838c-6e44d2deda12",
              "name": "telegramChatId",
              "value": "請改成你的 Telegram Chat ID",
              "type": "string"
            },
            {
              "id": "990ecf7e-feaa-4a91-9118-f378adb5d4d9",
              "name": "notifyWhenClear",
              "value": false,
              "type": "boolean"
            },
            {
              "id": "c69ea629-43b8-466a-bbb0-a5610d2d83e7",
              "name": "vehiclesJson",
              "value": "[\n  {\n    \"label\": \"我的汽車\",\n    \"carId\": \"ABC-1234\",\n    \"carType\": \"C\"\n  },\n  {\n    \"label\": \"我的機車\",\n    \"carId\": \"XYZ-5678\",\n    \"carType\": \"M\"\n  }\n]",
              "type": "string"
            },
            {
              "id": "fc5463ba-96f0-49a6-a280-3863bdd345bc",
              "name": "citiesJson",
              "value": "[\n  {\n    \"name\": \"臺北市\",\n    \"urlTemplate\": \"https://trafficapi.pma.gov.taipei/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"新北市\",\n    \"urlTemplate\": \"https://trafficapi.traffic.ntpc.gov.tw/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"桃園市\",\n    \"urlTemplate\": \"https://bill-epark.tycg.gov.tw/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"臺中市\",\n    \"urlTemplate\": \"http://tcparkingapi.taichung.gov.tw:8081/NationalParkingPayBillInquiry.Api/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true,\n    \"note\": \"來源未涵蓋：尚未確認此 :8081 API 是否支援 HTTPS，因此暫保留原 HTTP endpoint。\"\n  },\n  {\n    \"name\": \"臺南市\",\n    \"urlTemplate\": \"https://parkingbill.tainan.gov.tw/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"高雄市\",\n    \"urlTemplate\": \"https://kpp.tbkc.gov.tw/parking/V1/parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"基隆市\",\n    \"urlTemplate\": \"https://park.klcg.gov.tw/TrafficPayBill/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"新竹市\",\n    \"urlTemplate\": \"https://his.futek.com.tw:5443/TrafficPayBill/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"新竹縣\",\n    \"urlTemplate\": \"https://hcpark.hchg.gov.tw/NationalParkingPayBillInquiry/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"苗栗縣\",\n    \"urlTemplate\": \"https://miaoliparking.jotangi.com.tw/TrafficPayBill/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"彰化縣\",\n    \"urlTemplate\": \"https://chpark.chcg.gov.tw/TrafficPayBill/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"南投縣\",\n    \"urlTemplate\": \"https://parking.nantou.gov.tw/TrafficPayBill/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"雲林縣\",\n    \"urlTemplate\": \"https://parking.yunlin.gov.tw/TrafficPayBill/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"嘉義縣\",\n    \"urlTemplate\": \"https://8voc0wuf1g.execute-api.ap-southeast-1.amazonaws.com/default/chiayi/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"嘉義市\",\n    \"urlTemplate\": \"https://parking.chiayi.gov.tw/cypark/api/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"屏東縣\",\n    \"urlTemplate\": \"https://8voc0wuf1g.execute-api.ap-southeast-1.amazonaws.com/default/pingtung/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"宜蘭縣\",\n    \"urlTemplate\": \"https://billparking.e-land.gov.tw/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"花蓮縣\",\n    \"urlTemplate\": \"https://hl.parchere.com.tw/TrafficPayBill/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"臺東縣\",\n    \"urlTemplate\": \"https://tt.guoyun.com.tw/TrafficPayBill/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"澎湖縣\",\n    \"urlTemplate\": \"https://parking.penghu.gov.tw/TrafficPayBill/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"金門縣\",\n    \"urlTemplate\": \"https://km.guoyun.com.tw/TrafficPayBill/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  }\n]",
              "type": "string"
            }
          ]
        },
        "options": {}
      },
      "id": "cfc69392-3221-4479-b078-437991a0b749",
      "name": "設定（只改這裡）",
      "type": "n8n-nodes-base.set",
      "typeVersion": 3.4,
      "position": [-920, 60]
    },
    {
      "parameters": {
        "mode": "runOnceForAllItems",
        "jsCode": "const cfg = $input.first().json;\n\nfunction parseJsonField(value, fieldName) {\n  if (Array.isArray(value)) return value;\n  try {\n    return JSON.parse(value);\n  } catch (e) {\n    throw new Error(`${fieldName} 不是合法 JSON：${e.message}`);\n  }\n}\n\nconst vehicles = parseJsonField(cfg.vehiclesJson, 'vehiclesJson');\nconst cities = parseJsonField(cfg.citiesJson, 'citiesJson');\n\nif (!Array.isArray(vehicles) || vehicles.length === 0) {\n  throw new Error('vehiclesJson 至少要有一台車。');\n}\n\nconst enabledCities = Array.isArray(cities)\n  ? cities.filter(c => c?.enabled !== false && c?.name && c?.urlTemplate)\n  : [];\n\nif (enabledCities.length === 0) {\n  throw new Error('citiesJson 至少要啟用一個縣市。');\n}\n\nconst allowedTypes = new Set(['C', 'M', 'O']);\nconst output = [];\n\nfor (const vehicle of vehicles) {\n  const carId = String(vehicle?.carId ?? '').trim();\n  const carType = String(vehicle?.carType ?? '').trim().toUpperCase();\n  const label = String(vehicle?.label ?? carId).trim();\n\n  if (!carId) throw new Error(`車輛缺少 carId：${JSON.stringify(vehicle)}`);\n  if (!allowedTypes.has(carType)) {\n    throw new Error(`${carId} 的 carType 必須是 C、M 或 O，目前為：${carType}`);\n  }\n\n  for (const city of enabledCities) {\n    const queryUrl = String(city.urlTemplate)\n      .replace('{CarID}', encodeURIComponent(carId))\n      .replace('{CarType}', encodeURIComponent(carType));\n\n    output.push({\n      json: {\n        label,\n        carId,\n        carType,\n        cityName: city.name,\n        queryUrl,\n        telegramChatId: cfg.telegramChatId ?? '',\n        notifyWhenClear: Boolean(cfg.notifyWhenClear)\n      }\n    });\n  }\n}\n\nreturn output;"
      },
      "id": "fe4cf409-253c-453c-bb87-34849dfcc386",
      "name": "建立 車輛 × 縣市 查詢清單",
      "type": "n8n-nodes-base.code",
      "typeVersion": 2,
      "position": [-680, 60]
    },
    {
      "parameters": {
        "batchSize": 1,
        "options": {}
      },
      "id": "da0e1f61-1d54-4afb-82af-752252f5c50f",
      "name": "Loop Over Items（每次 1 筆）",
      "type": "n8n-nodes-base.splitInBatches",
      "typeVersion": 3,
      "position": [-420, 60]
    },
    {
      "parameters": {
        "method": "GET",
        "url": "={{ $json.queryUrl }}",
        "options": {
          "response": {
            "response": {
              "fullResponse": true,
              "neverError": true,
              "responseFormat": "json"
            }
          },
          "timeout": 10000
        }
      },
      "id": "0707ce96-44ea-4630-a5fd-184d25e128bc",
      "name": "查詢停車費 API",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [-160, 200],
      "onError": "continueRegularOutput"
    },
    {
      "parameters": {
        "mode": "runOnceForEachItem",
        "jsCode": "const row = $json ?? {};\n\nconst base = {\n  cityName: row.cityName ?? '',\n  label: row.label ?? row.carId ?? '',\n  carId: row.carId ?? '',\n  carType: row.carType ?? '',\n  queryUrl: row.queryUrl ?? '',\n  telegramChatId: row.telegramChatId ?? '',\n  notifyWhenClear: Boolean(row.notifyWhenClear)\n};\n\n// Network/TLS/DNS errors continued by the HTTP Request node arrive as `error`.\nif (row.error) {\n  return {\n    json: {\n      ...base,\n      status: 'ERROR',\n      apiMessage: row.error.message || String(row.error),\n      httpStatus: null,\n      hasUnpaid: false,\n      totalCount: 0,\n      totalAmount: 0,\n      details: [],\n      isQueryFailed: true\n    }\n  };\n}\n\nconst httpStatus = Number(row.statusCode ?? 0);\nlet res = row.body ?? {};\n\nif (typeof res === 'string') {\n  try {\n    res = JSON.parse(res);\n  } catch {\n    return {\n      json: {\n        ...base,\n        status: 'ERROR',\n        apiMessage: `API 回傳非 JSON 內容${httpStatus ? `（HTTP ${httpStatus}）` : ''}`,\n        httpStatus: httpStatus || null,\n        hasUnpaid: false,\n        totalCount: 0,\n        totalAmount: 0,\n        details: [],\n        isQueryFailed: true\n      }\n    };\n  }\n}\n\nif (httpStatus && (httpStatus < 200 || httpStatus >= 300)) {\n  return {\n    json: {\n      ...base,\n      status: 'ERROR',\n      apiMessage:\n        res?.Message ||\n        res?.message ||\n        `HTTP ${httpStatus}`,\n      httpStatus,\n      hasUnpaid: false,\n      totalCount: 0,\n      totalAmount: 0,\n      details: [],\n      isQueryFailed: true\n    }\n  };\n}\n\nconst status = String(res?.Status ?? '').toUpperCase();\nconst apiMessage = String(res?.Message ?? '');\n\nlet result = res?.Result ?? null;\nif (typeof result === 'string' && result.trim()) {\n  try {\n    result = JSON.parse(result);\n  } catch {\n    return {\n      json: {\n        ...base,\n        status: 'ERROR',\n        apiMessage: 'Result 欄位不是合法 JSON',\n        httpStatus: httpStatus || null,\n        hasUnpaid: false,\n        totalCount: 0,\n        totalAmount: 0,\n        details: [],\n        isQueryFailed: true\n      }\n    };\n  }\n}\n\nconst bills = Array.isArray(result?.Bills) ? result.Bills : [];\nconst reminders = Array.isArray(result?.Reminders) ? result.Reminders : [];\nconst details = [];\n\nfor (const bill of bills) {\n  details.push({\n    kind: '停車單',\n    amount: Number(bill?.PayAmount ?? bill?.Amount ?? 0),\n    parkingDate: bill?.ParkingDate ?? '',\n    dueDate: bill?.PayLimitDate ?? '',\n    billNo: bill?.BillNo ?? ''\n  });\n}\n\nfor (const reminder of reminders) {\n  details.push({\n    kind: '催繳單',\n    amount: Number(\n      reminder?.PayAmount ??\n      (Number(reminder?.Amount ?? 0) + Number(reminder?.ExtraCharge ?? 0))\n    ),\n    parkingDate: reminder?.ParkingDate ?? '',\n    dueDate: reminder?.ReminderLimitDate ?? reminder?.PayLimitDate ?? '',\n    billNo: reminder?.ReminderNo ?? reminder?.BillNo ?? ''\n  });\n}\n\nconst totalCount = Number(result?.TotalCount ?? details.length ?? 0);\nconst computedAmount = details.reduce((sum, d) => sum + Number(d.amount || 0), 0);\nconst totalAmount = Number(result?.TotalAmount ?? computedAmount);\n\nconst success = status === 'SUCCESS';\n\nreturn {\n  json: {\n    ...base,\n    status,\n    apiMessage,\n    httpStatus: httpStatus || null,\n    hasUnpaid: success && !!result && (totalCount > 0 || details.length > 0),\n    totalCount,\n    totalAmount,\n    details,\n    isQueryFailed: !success\n  }\n};"
      },
      "id": "0a7b65f9-6d37-49d4-9fd4-f4f749f73c46",
      "name": "整理單筆結果",
      "type": "n8n-nodes-base.code",
      "typeVersion": 2,
      "position": [320, 120]
    },
    {
      "parameters": {
        "amount": 1,
        "unit": "seconds"
      },
      "id": "aa5bc5ca-c35c-4f8a-97b4-1b29fef023a8",
      "name": "等待 1 秒（API 節流）",
      "type": "n8n-nodes-base.wait",
      "typeVersion": 1.1,
      "position": [320, 200],
      "webhookId": "61c9dc0a-3b6d-49d5-b022-e6a9054e3dd3"
    },
    {
      "parameters": {
        "mode": "runOnceForAllItems",
        "jsCode": "const rows = $input.all().map(i => i.json);\nconst first = rows[0] ?? {};\n\nconst unpaidRows = rows.filter(r => r.hasUnpaid);\nconst failedRows = rows.filter(r => r.isQueryFailed);\n\nconst totalCount = unpaidRows.reduce((s, r) => s + Number(r.totalCount || 0), 0);\nconst totalAmount = unpaidRows.reduce((s, r) => s + Number(r.totalAmount || 0), 0);\n\nconst lines = [];\n\nif (unpaidRows.length) {\n  lines.push('🚗 路邊停車費提醒', '');\n\n  for (const row of unpaidRows) {\n    const vehicleIcon = row.carType === 'M' ? '🛵' : '🚙';\n    lines.push(`${vehicleIcon}【${row.label}｜${row.carId}】`);\n    lines.push(`${row.cityName}：${row.totalCount} 筆，合計 $${row.totalAmount}`);\n\n    for (const d of row.details.slice(0, 10)) {\n      const parts = [\n        d.kind,\n        `$${d.amount}`,\n        d.parkingDate ? `停車日 ${d.parkingDate}` : null,\n        d.dueDate ? `期限 ${d.dueDate}` : null\n      ].filter(Boolean);\n      lines.push(`- ${parts.join('｜')}`);\n    }\n\n    if (row.details.length > 10) {\n      lines.push(`- 另有 ${row.details.length - 10} 筆未列出`);\n    }\n    lines.push('');\n  }\n\n  lines.push(`總計：${totalCount} 筆，$${totalAmount}`);\n} else {\n  lines.push('✅ 目前沒有查到待繳路邊停車費');\n}\n\nif (failedRows.length) {\n  lines.push('', `⚠️ 有 ${failedRows.length} 個查詢失敗，這些縣市「不能視為沒有欠費」：`);\n  for (const row of failedRows.slice(0, 20)) {\n    lines.push(`- ${row.label}｜${row.cityName}｜${row.apiMessage || row.status || '未知錯誤'}`);\n  }\n  if (failedRows.length > 20) {\n    lines.push(`- 另有 ${failedRows.length - 20} 個失敗未列出`);\n  }\n}\n\nconst shouldNotify =\n  unpaidRows.length > 0 ||\n  failedRows.length > 0 ||\n  Boolean(first.notifyWhenClear);\n\nreturn [{\n  json: {\n    telegramChatId: first.telegramChatId ?? '',\n    shouldNotify,\n    hasUnpaid: unpaidRows.length > 0,\n    totalCount,\n    totalAmount,\n    failedQueries: failedRows.length,\n    message: lines.join('\\n')\n  }\n}];"
      },
      "id": "4b6dabed-b0b9-4e24-bd69-249d9cac4bbf",
      "name": "彙總全部結果",
      "type": "n8n-nodes-base.code",
      "typeVersion": 2,
      "position": [-160, -120]
    },
    {
      "parameters": {
        "conditions": {
          "options": {
            "caseSensitive": true,
            "leftValue": "",
            "typeValidation": "strict",
            "version": 2
          },
          "conditions": [
            {
              "id": "60315e8a-26c6-47fe-b311-0864f215d707",
              "leftValue": "={{ $json.shouldNotify }}",
              "rightValue": true,
              "operator": {
                "type": "boolean",
                "operation": "true",
                "singleValue": true
              }
            }
          ],
          "combinator": "and"
        },
        "options": {}
      },
      "id": "c44271f5-b4ec-4a02-bd5a-37e9b53cc1ab",
      "name": "需要通知？",
      "type": "n8n-nodes-base.if",
      "typeVersion": 2.2,
      "position": [80, -120]
    },
    {
      "parameters": {
        "chatId": "={{ $json.telegramChatId }}",
        "text": "={{ $json.message }}",
        "additionalFields": {}
      },
      "id": "427558ca-fc5c-4d35-aa31-3e1d2286e556",
      "name": "Telegram 通知",
      "type": "n8n-nodes-base.telegram",
      "typeVersion": 1.2,
      "position": [320, -160]
    },
    {
      "parameters": {
        "mode": "combine",
        "combineBy": "combineByPosition",
        "options": {}
      },
      "id": "e11fc337-e4bd-406f-9f9b-9cebc88e6e96",
      "name": "合併查詢參數與 HTTP 回應",
      "type": "n8n-nodes-base.merge",
      "typeVersion": 3.2,
      "position": [80, 120]
    }
  ],
  "connections": {
    "手動測試": {
      "main": [
        [
          {
            "node": "設定（只改這裡）",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "每天 09:00": {
      "main": [
        [
          {
            "node": "設定（只改這裡）",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "設定（只改這裡）": {
      "main": [
        [
          {
            "node": "建立 車輛 × 縣市 查詢清單",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "建立 車輛 × 縣市 查詢清單": {
      "main": [
        [
          {
            "node": "Loop Over Items（每次 1 筆）",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Loop Over Items（每次 1 筆）": {
      "main": [
        [
          {
            "node": "彙總全部結果",
            "type": "main",
            "index": 0
          }
        ],
        [
          {
            "node": "查詢停車費 API",
            "type": "main",
            "index": 0
          },
          {
            "node": "合併查詢參數與 HTTP 回應",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "查詢停車費 API": {
      "main": [
        [
          {
            "node": "合併查詢參數與 HTTP 回應",
            "type": "main",
            "index": 1
          }
        ]
      ]
    },
    "整理單筆結果": {
      "main": [
        [
          {
            "node": "等待 1 秒（API 節流）",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "等待 1 秒（API 節流）": {
      "main": [
        [
          {
            "node": "Loop Over Items（每次 1 筆）",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "彙總全部結果": {
      "main": [
        [
          {
            "node": "需要通知？",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "需要通知？": {
      "main": [
        [
          {
            "node": "Telegram 通知",
            "type": "main",
            "index": 0
          }
        ],
        []
      ]
    },
    "合併查詢參數與 HTTP 回應": {
      "main": [
        [
          {
            "node": "整理單筆結果",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  },
  "pinData": {},
  "active": false,
  "settings": {
    "executionOrder": "v1",
    "timezone": "Asia/Taipei"
  },
  "versionId": "1aa3b0b1-0acf-40f7-b71c-03a93d7beb1a",
  "meta": {
    "templateCredsSetupCompleted": false
  },
  "tags": []
}

如果是想用匯入的方式，就把上面的程式碼複製後存成 JSON，進入 n8n：

Workflows
→ Import from File
→ 選擇剛才下載的 JSON

不管是用複製貼上的，還是匯入，之後只需要修改 「設定（只改這裡）」 這個 Node 就可以，說明如下。

車輛設定

找到：

vehiclesJson

例如：

[
  {
    "label": "我的汽車",
    "carId": "ABC-1234",
    "carType": "C"
  },
  {
    "label": "我的機車",
    "carId": "XYZ-5678",
    "carType": "M"
  }
]

carType 的設定：

值	車種
`C`	汽車
`M`	機車
`O`	其他

如果有多台車，繼續往下增加即可。

例如：

[
  {
    "label": "汽車",
    "carId": "ABC-1234",
    "carType": "C"
  },
  {
    "label": "我的機車",
    "carId": "XYZ-5678",
    "carType": "M"
  },
  {
    "label": "家人的機車",
    "carId": "AAA-8888",
    "carType": "M"
  }
]

Telegram 設定

接著修改：

telegramChatId

填入自己的 Telegram Chat ID。

如果不知道自己的 Telegram Chat ID 是多少，只需要加入這個帳號，進行對話後就會看得到了：User Info。

最後進入：

Telegram 通知

設定自己的 Telegram Bot Credential。

如果不希望「沒有欠費」時也收到通知，可以保持：

notifyWhenClear = false

這樣平常沒有欠費就完全不打擾。

如果沒有用 Telegram，或是想接收別的通知，那只需要把上面 Workflow 的 JSON，貼給 ChatGPT，請它改成你習慣的通知方式即可。

n8n Workflow 說明

這段是詳細說明上面那段 JSON 的各個部份，是在做什麼的。

整個 Workflow 最主要可以分成幾個部分。

每天自動執行

Workflow 預設：

每天 09:00

自動執行一次。

另外也保留：

手動測試

剛設定完成時，可以先按手動執行確認是否正常。

設定車輛與縣市

「設定（只改這裡）」Node 集中放：

telegramChatId
notifyWhenClear
vehiclesJson
citiesJson

所以日後新增汽車、機車，基本上只需要改這一個地方。

citiesJson 則放各縣市停車費查詢端點。

目前這份 Workflow 已經預先放入 21 個縣市的設定；如果某個 API 日後有更換網址，也只需要修改這裡，不必重新改整個流程。

建立查詢清單

接下來的 Code Node 會把：

車輛
×
縣市

自動組合成每一筆查詢。

例如：

我的汽車 → 臺北市
我的汽車 → 新北市
我的汽車 → 桃園市

我的機車 → 臺北市
我的機車 → 新北市
我的機車 → 桃園市
...

所以新增車輛時，不需要增加新的 HTTP Request Node。

逐筆查詢停車費

接著使用：

Loop Over Items

一次只處理一筆查詢。

流程是：

查詢 API
↓
整理結果
↓
等待 1 秒
↓
下一筆

August 刻意加上 等待 1 秒，避免短時間內大量呼叫各縣市 API。

整理待繳停車費

每一個縣市回傳結果之後，Workflow 會統一整理成：

縣市
車牌
車種
待繳筆數
待繳金額
停車日期
繳費期限
停車單 / 催繳單

所以即使不同縣市的資料來源不同，後面的通知流程仍然可以使用相同格式。

最後統一通知

全部縣市查詢完成後，再一次彙整。

例如：

🚗 路邊停車費提醒

🚙【我的汽車｜ABC-1234】
臺北市：2 筆，合計 $80
- 停車單｜$40｜停車日 2026-09-10｜期限 2026-09-25
- 停車單｜$40｜停車日 2026-09-11｜期限 2026-09-26

🛵【我的機車｜XYZ-5678】
新北市：1 筆，合計 $20
- 停車單｜$20｜停車日 2026-09-12｜期限 2026-09-27

總計：3 筆，$100

這樣不用收到幾十則 Telegram 訊息，而是每天最多收到一份整理好的結果。

另外，如果某個 API 查詢失敗，也會另外標示：

⚠️ 有 2 個查詢失敗，
這些縣市不能視為沒有欠費：

- 我的汽車｜某縣市｜查詢失敗
- 我的機車｜某縣市｜Timeout

這點很重要，因為「API 查不到」跟「沒有停車費」是兩件完全不同的事情。

最後把 Workflow 啟用後，基本上就不用再管它了。

之後只要有未繳的路邊停車費，就會自動收到 Telegram 通知。

用 Chrome 擴充 + 自架 n8n，讓 AI 幫你整理 Google Chat 對話與自動產生 Jira 任務

Let's Write — Fri, 11 Sep 2026 10:09:28 +0000

本篇要解決的問題

如果想把工作、私人生活切開來，在公司的通訊軟體就不能還是在用 LINE，像之前有寫過 Mattermost 這個通訊軟體。

最近處理工作的事情，團隊選擇的是 Google Chat，用了一陣子後才發現，因為是免費版，沒有 Google Chat App、Chat API，也不能裝 Chat Bot，等於想在 Chat 使用 AI 是被封印的事。

可是總會有要讓 AI 幫忙整理討論或是撈舊訊息的時候，跟 ChatGPT 討論後，發現只剩下直接從瀏覽器下手這方法。

於是就有了這篇的 Let's Chat AI 擴充功能，直接讀畫面上的聊天內容，再送去 AI，最後把 AI 處理後的結果顯示出來。

本篇使用的擴充功能：Let's Chat AI

Let's Chat AI 是什麼？

Let's Chat AI 是一個 Chrome 擴充。

我們在 Google Chat 裡開著某個聊天室，點一下按鈕，它就把「螢幕上已經載入的訊息」送去整理，幾秒後回給你：

討論摘要，如重點、決策、工作項目、待確認項目。
工作項目清單，如誰負責什麼。
Jira 議題草稿，可一鍵複製成純文字貼進 Jira。
自己打一句指示，如「把上週跟晶片掃描器有關的討論整理出來」「列出 Amy 提到的待辦」。

簡單來說，就是給用免費版 Google Chat，沒有 Chat API 可用的小團隊。

怎麼運作

flowchart LR
  A["Google Chat<br/>你點一下「AI」"] -->|送出已載入的訊息| B["你自己的 n8n<br/>＋ 你的 AI 金鑰"]
  B -->|帶金鑰呼叫| C["AI<br/>Gemini / OpenAI"]
  C -->|回結構化結果| B
  B -->|整理好的內容| D["擴充面板<br/>看結果 / 複製"]

中間站是「我們自己的 n8n」，n8n 是一個開源的自動化工具，提供自架版本。

AI 的金鑰只放在 n8n 裡，擴充本身不儲存任何金鑰。

因此換 AI 供應商只要改 n8n。

關於隱私

只有在主動按功能鍵、看到「即將送出 N 則訊息」確認畫面、按下送出之後，訊息才會離開瀏覽器。

不會背景監聽、不會自動上傳、不會保存聊天紀錄。解析結果只存在記憶體，關掉面板或切換聊天室就丟掉。

擴充的本機設定只有三樣：webhook 網址、擷取則數上限、debug 開關。

只在 chat.google.com 上運作，權限只要 storage。

連 n8n 的網域權限是在設定時才執行請求的。

能做什麼

功能	說明
整理討論	摘要、決策、工作項目、待確認
整理工作項目	專注抽出「誰要做什麼」
產生 Jira Draft	Title / Description / Acceptance Criteria / Technical Notes / Pending Questions，一鍵複製純文字
自由指示	面板上直接打字，讓 AI 依指示撈 / 比對 / 整理已載入的訊息
自動往回載入	按下功能鍵時，自動把訊息串往上捲、載入較早的訊息（則數上限預設 50，面板或選項都能改，10–500）
可拖拉的按鈕	右下角的 AI 按鈕可以拖到順手的位置，位置會記住

怎麼用

一、安裝擴充

在 Google 擴充功能商店裡直接進行安裝：

Let's Chat AI

二、接上你自己的 n8n（五步）

GitHub 資料夾裡有兩份可直接匯入的設定檔，自行選要用 Gemini 還是 OpenAI 的 API：

google-chat-ai.gemini.workflow.json（Google Gemini）
google-chat-ai.openai.workflow.json（OpenAI）

Gemini API 有免費額度可以使用，建議先用 Gemini 來測試這擴充功能有沒有滿足你的需求。

1. 拿一把自己的 AI 金鑰

Gemini：到 Google AI Studio 按 Create API key。
OpenAI：到 platform.openai.com 建立 secret key（sk-…）。

2. 把設定檔匯入 n8n

n8n 左上角 ＋ → Import from File…，選對應的 *.workflow.json。
匯入後畫面上有一張黃色便利貼，寫著這份的重點，忘記可以回去看。

3. 把金鑰貼進去

打開 Call Gemini（或 Call OpenAI）節點 → Credential → Create New，選 Header Auth：

	Gemini	OpenAI
名稱	`X-goog-api-key`	`Authorization`
值	你的 Gemini token	`Bearer sk-…`（`Bearer` 後面有一個空格）

4. 打開開關

workflow 右上角點擊 Publish。

5. 複製網址，貼進擴充

打開 Webhook 節點，複製 Production URL（長得像 https://你的n8n/webhook/google-chat-ai）。

Chrome 工具列的擴充圖示 → 選項 → 貼進「n8n Webhook URL」→ 儲存（會跳權限請求，允許）→ 按測試連線，看到「連線成功」就完成了。

公司內網的 n8n 只有 http 沒有 https？ 可以。擴充接受 http://，只是不加密，
所以只適合沒有對外、在信任的內網裡的 n8n。

三、開始整理

打開 Google Chat，進入某個 Space 或 DM。需要更早的訊息可以先手動往上捲一點。
點 Let's Chat AI 的按鈕開啟面板。
打一句指示，或選整理討論 / 整理工作項目 / 產生 Jira Draft。
確認「即將送出 N 則訊息」→ 送出。
看結果。Jira Draft 可按「複製 Jira Draft」拿純文字。

兩份設定檔差在哪

	Gemini 版	OpenAI 版
檔名	`google-chat-ai.gemini.workflow.json`	`google-chat-ai.openai.workflow.json`
呼叫的 API	`generativelanguage.googleapis.com`	`api.openai.com/v1/chat/completions`
預設模型	`gemini-3.5-flash-lite`	`gpt-5.6-luna`
金鑰 header	`X-goog-api-key`	`Authorization: Bearer sk-…`

其餘節點（Webhook → Prepare Prompt → Call → Shape Result → Respond）完全一樣。

想改整理的口氣，改 Prepare Prompt 節點裡的 prompt 就好，別動最後 Respond 回的
{ "success": true, "result": { … } } 形狀，那是擴充在讀的。

原始碼

Let's Chat AI 擴充功能：https://chromewebstore.google.com/detail/lets-chat-ai/cjhllfpcohiiclodggnfemcchidlgaaj。

GitHub：https://github.com/letswritetw/extension-lets-chat-ai

請大家多多支持，安裝來用、推薦給朋友、回報問題、給個評價都好，你的一個小小動作，對本站都是大大的鼓勵。

Agent Skill 開發：用 lets-social 自動將文章轉化為 IG、Threads、FB 社群貼文

Let's Write — Tue, 01 Sep 2026 14:21:22 +0000

本篇要解決的問題

以前流行手寫套件，分享到 GitHub 上讓人取用，而現在，流行的是寫 Skill 了。

因為來自 Google 的流量一直在下降，所以 Let's Write 這陣子建了 Instagram、Threads 帳號，增加導流的平台。

只是每個社群都有各自的風格。

為了讓一篇文章出來後，可以針對不同的平台，撰寫不同的貼文，就讓 AI 建立了本篇的 Skill，期待有效的增加本站流量。

這是公開的 Skill，大家可以直接從 GitHub 上下載，安裝方式寫在簡易版的 README.md 中，以下筆記文是把安裝、使用的說明貼上來。

GitHub：https://github.com/letswritetw/lets-social

取用前請給本專案一個星星，你一個小小的動作，對本站都是大大的鼓勵。

lets-social

功用：把一篇文章轉寫成符合 Instagram、Facebook、Threads 與 Telegram 等，符合社群平台特性的貼文內容。

lets-social 是純指令型 Agent Skill。

當我們提供已完成的文章、Markdown、純文字、本機檔案後，Agent 都能讀取的內容，然後先建立一份內部 Source Brief，再針對每個指定平台獨立撰寫發文文字。

Instagram 預設會附上 Nano Banana 2 與 ChatGPT Images 2.0 的可直接使用 prompt。

Threads 只在圖片能補充內容時提供。

它不負責發佈、排程，也不替來源補上未經證實的資料。

所有輸出都必須保留原文的事實、不確定性、立場與作者語氣。

為什麼要用 lets-social？

每個社群平台都有不同的閱讀方式：

Facebook 適合補充背景。
Threads 適合從一個明確觀察切入。
Telegram 則重視資訊密度與掃讀效率。

lets-social 會依平台重新判斷 Hook、資訊順序、語氣與 CTA，不會只把同一份文案改成不同長度。

圖片也採用相同原則：

Instagram 預設需要視覺素材。
Threads 不會為了湊格式加入裝飾圖。

支援平台

平台	預設輸出	內容重點
Instagram	Caption、CTA、可選 Hashtag 或 Carousel、產圖 prompt	手機閱讀、實用價值與配圖
Facebook	Post、CTA	背景、寫作動機與作者觀點
Threads	單篇貼文或適合的串文；必要時附產圖 prompt	口語觀察與討論感
Telegram	Message、連結位置建議	清楚、易掃讀與資訊密度

運作方式

來源文章
    -> 內部 Source Brief
        -> Instagram 草稿
        -> Facebook 草稿
        -> Threads 草稿
        -> Telegram 草稿
        -> Instagram Image Brief
        -> 可選的 Threads Image Brief
    -> 每份 Image Brief 產生兩個模型的完整 prompt
    -> 來源忠實度與平台差異檢查
    -> Markdown 輸出

每個平台都從同一份 Source Brief 出發，不會拿某個平台的草稿當成另一個平台的輸入。

同一平台的兩份產圖 prompt 使用相同 Image Brief，讓主體、構圖與訊息保持一致。

安裝

Clone 或下載此 repository。

再將完整的 lets-social 目錄放到 Agent 支援的 Skill 路徑。

請保留 SKILL.md、references/ 與 examples/ 的相對位置。

若希望之後能更新，請使用 Git Clone，並直接 Clone 到下列 Skill 路徑，因為下載 ZIP 的安裝方式不會保留 Git 更新紀錄。

Claude Code

安裝為個人 Skill：

git clone https://github.com/letswritetw/lets-social.git ~/.claude/skills/lets-social

Windows 使用者

Git Bash 可以直接用上面的指令，但 PowerShell 和 cmd 不會展開 ~，會在當前目錄建一個名字叫 ~ 的資料夾，所以請改用下面的指令。

PowerShell：

git clone https://github.com/letswritetw/lets-social.git "$HOME/.claude/skills/lets-social"

cmd：

git clone https://github.com/letswritetw/lets-social.git "%USERPROFILE%/.claude/skills/lets-social"

或安裝在單一專案，在專案根目錄執行：

git clone https://github.com/letswritetw/lets-social.git .claude/skills/lets-social

Claude Code 可以依 description 自動選用，也可以用 /lets-social 明確呼叫。

/lets-social 把 ./article.md 轉成 Instagram 與 Threads 貼文。

Codex

安裝為個人 Skill：

git clone https://github.com/letswritetw/lets-social.git ~/.agents/skills/lets-social

Windows 使用者

Git Bash 可以直接用上面的指令。但 PowerShell 和 cmd 不會展開 ~，請改用下面的指令。

PowerShell：

git clone https://github.com/letswritetw/lets-social.git "$HOME/.agents/skills/lets-social"

cmd：

git clone https://github.com/letswritetw/lets-social.git "%USERPROFILE%/.agents/skills/lets-social"

或安裝在單一 repository，在 repository 根目錄執行：

git clone https://github.com/letswritetw/lets-social.git .agents/skills/lets-social

Codex 可以依 description 自動選用，也可以用 $lets-social 明確呼叫。

$lets-social 把 ./article.md 轉成 Instagram 與 Threads 貼文。

其他支援 Agent Skills 的工具

請依工具文件提供的安裝路徑，複製完整的 lets-social 目錄。

此專案遵循 Agent Skills 規格，使用包含 name 與 description 的 YAML frontmatter、Markdown 指令本文，以及按需求讀取的 reference 檔案。

安裝後，可以從工具的 Skill 選單呼叫 lets-social，或在提示中直接指定：

使用 lets-social，把這篇文章轉成 Facebook 與 Telegram 貼文。

Agent Skills 規格定義可攜的封裝格式，不負責統一各工具的安裝路徑，也不保證每個工具都支援相同的產品專屬功能。

lets-social 只使用共通 frontmatter 欄位與一般 Markdown 相對連結，降低對單一工具的依賴。

版本與更新

Git 更新（建議）

使用 Git Clone 安裝的使用者，可以依安裝位置執行：

# Claude Code 個人 Skill
git -C ~/.claude/skills/lets-social pull --ff-only

# Codex 個人 Skill
git -C ~/.agents/skills/lets-social pull --ff-only

Windows 使用者

PowerShell 和 cmd 一樣不會展開 ~。Git Bash 可直接使用上面的指令。

PowerShell，Claude Code：

git -C "$HOME/.claude/skills/lets-social" pull --ff-only

PowerShell，Codex：

git -C "$HOME/.agents/skills/lets-social" pull --ff-only

cmd，Claude Code：

git -C "%USERPROFILE%/.claude/skills/lets-social" pull --ff-only

cmd，Codex：

git -C "%USERPROFILE%/.agents/skills/lets-social" pull --ff-only

專案層級或其他 Agent 的安裝位置，請將上面的路徑替換為實際的 lets-social 目錄。

--ff-only 會在本機內容與遠端版本分歧時停止，不會直接覆蓋使用者的修改。

下載 ZIP 或直接複製資料夾的使用者，請重新下載最新版，並以完整目錄取代舊版。

若曾自訂 Skill，請先備份或保留差異。

使用 Skillshare 追蹤（選用）

Skillshare 使用者可以用它安裝並更新：

skillshare install letswritetw/lets-social
skillshare sync

之後檢查與更新：

skillshare check lets-social
skillshare update lets-social
skillshare sync

請不要加 --track。

這個 repository 把 SKILL.md 放在根目錄，--track 會改用追蹤模式，把它記成 _lets-social 並回報 0 skills，Skill 不會被 sync 到 Agent 的目錄。

不加 --track 時 skillshare update 一樣可以更新。

Skillshare 是選用的第三方工具，不是執行 lets-social 的必要相依套件。

使用範例

使用 lets-social，把 article.md 轉成 Instagram、Facebook、
Threads 與 Telegram 貼文。

幫我宣傳這篇技術文章，只做 Threads 和 Telegram。Threads 口語一點，
Telegram 像頻道公告，所有平台都不要 Hashtag。

把這篇文章改寫成 Facebook 宣傳文。保留作者的技術語氣，
CTA 要引導讀者閱讀完整文章。

Instagram 不要產圖 prompt；Threads 這篇要一張配圖。

如果 Agent 無法讀取網址，Skill 會停止產生貼文，並要求你提供文章本文或 Markdown。

它不會假裝已經讀過網頁。

支援的來源

已完成的純文字或 Markdown。
可讀取的本機文章或文件。
目前 Agent 具備網頁讀取能力時可使用網址。
先前由 lets-social 產生的內容，可用於單一平台調整。

來源必須包含足以支撐貼文的文章內容。只有標題或搜尋摘要並不足夠。

產圖 prompt

Instagram 預設在文案後輸出 Image Direction、Nano Banana 2 Prompt 與 ChatGPT Images 2.0 Prompt。

兩份 prompt 都是完整內容，可以分別貼進 Gemini 與 ChatGPT，不需要再補文章背景。

Threads 只有在圖片能說明比較、流程、具體物件、空間關係或文章支持的視覺概念時才輸出這三個欄位。純觀點與討論型貼文會保留文字形式。使用者可以明確要求加入或省略圖片 prompt。

每個平台各自建立 Image Brief。

同一平台的兩份 prompt 必須使用相同主體、構圖、圖中文字與排除條件。

視覺風格依文章挑選

不套用單一固定風格。

Skill 會依文章實際內容選一個方向，在 Image Brief 說明選擇理由，並讓同一平台的所有圖片維持同一套風格。

方向	適合的文章
知識圖卡	檢查清單、評估條件、操作步驟
編輯式圖解	架構、資料流、請求生命週期、前後對照
大字海報	單一主張或一個反直覺的結論
終端機或藍圖	底層工程、工具、協定、除錯
插畫場景	團隊流程、職涯、決策

原文若指向更合適的方向，也可以改寫成自訂風格。使用者明確指定風格時以使用者為準。

每份 prompt 都會包含的內容

至少四個具名顏色，並說明每個顏色負責什麼；使用者要求單色時例外。
來源支持的重點短句，直接寫在圖上。
閱讀層級：哪個元素先讀、其次、最後。
足夠的紋理、標註或結構細節，避免變成空泛的素材圖。

圖中文字與字體規則

圖中文字預設為必要，不是選配。

標題一句、重點三到五句、可選的結語一句，全部在 prompt 中逐字列出並指定位置，並要求模型不要輸出其他文字。

每一句都必須是原文支持的說法，不能新增數字、結果或保證。

中文、日文、韓文一律指定清楚精確的粗體無襯線字，不使用手寫、毛筆、書法或做舊效果。

產圖模型處理手寫 CJK 一定會糊，這條規則在所有風格下都成立。裝飾性手寫只用在兩到四個字的英文短語上，並且在 prompt 中明講這個分工。

兩個模型的差別

Nano Banana 2 維持單張，對應 Instagram 的 4:5 封面。

ChatGPT Images 2.0 一次最多可產 10 張，且每張可以承載不同內容，所以它那份 prompt 是一組編號系列：

第 1 張是封面，之後每個重點各一張，可選最後一張放結語或導讀 CTA。

預設為封面加三到五個重點，也就是四到六張。

輸出含 Carousel 大綱時改以大綱為準。整組共用同一個背景、色盤、字體規則與視覺語彙，只有內容改變。

需要單張時，只取第 1 張。

Skill 只撰寫 prompt，不會連線到 Gemini 或 ChatGPT。實際產圖功能與費用依使用者的帳號方案而定。

自訂品牌語氣

預設語氣清楚、專業、容易親近，並以實用與易懂的方式表達技術內容。

原文明確呈現的作者語氣擁有較高優先順序。

我們可以直接用自然語言覆寫設定：

語氣更像個人心得，不要 emoji，不要 Hashtag，技術名詞要精確。

使用者可以調整文風，但不能藉此改變來源事實或加入沒有根據的資訊。

只產生部分平台

只要指定需要的平台：

只產生 Threads 與 Telegram。

後續也能只調整單一平台：

Threads 再短一點，語氣更口語。

Skill 只會修改 Threads，不會重新產生其他平台內容。

專案結構

lets-social/
├── .gitignore
├── SKILL.md
├── README.md
├── README-full.md
├── CHANGELOG.md
├── LICENSE
├── references/
│   ├── instagram.md
│   ├── facebook.md
│   ├── threads.md
│   ├── telegram.md
│   ├── brand-voice.md
│   ├── image-prompts.md
│   └── output-format.md
└── examples/
    ├── input-example.md
    └── output-example.md

此 repository 不需要 runtime、套件管理工具、建置系統或 API server。

只有實際使用 prompt 產圖時才需要開啟外部產圖服務。

新增其他平台

在 references/ 新增一份專用文件，定義平台目標、內容判斷、輸出欄位與檢查項目。
在 SKILL.md 加入平台路由，不要把詳細規則複製回主檔。
在 references/output-format.md 加入最小且實用的輸出格式。
補上範例，並確認 Hook、結構、資訊順序與 CTA 都和其他平台不同。

除非需要可重複且具確定性的工具操作，否則請維持純指令結構。

Claude Code + Sentry MCP + Gitea MCP：每日自動抓 bug、修復、開 PR

Let's Write — Sun, 23 Aug 2026 07:38:03 +0000

本篇要解決的問題

除了開發新專案，工程師日常最耗時的工作通常是排查、修復既有系統的 Bug。

而當 Anthropic 推出 Model Context Protocol （MCP）後，AI 在軟體開發自動化（DevOps Automation）有了全新落地應用，那有沒有辦法可以讓 AI 自己去找 bug 然後再自己修？

想到以前曾用過一陣子 Sentry，查了一下有 MCP 可用。

再查了一下 Gitea，也確定有 MCP 可用。

那把兩邊尬在一起，不就可以達成本篇的目標：AI 自己找 bug 後自己修？

本文實作如何透過 Sentry MCP 自動抓取 Production 錯誤堆疊，再結合 Gitea MCP 讓 Claude Code 實現每日自動找 Bug、本機修復測試、自動提交 PR 的完整除錯流程。

安裝 Sentry MCP

本機要先安裝 Claude CLI：https://code.claude.com/docs/en/quickstart

1 先下指令安裝，安裝 Sentry MCP：

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp --scope user

2 登入 Sentry 帳戶進行授權：

終端機輸入 claude，接著輸入：

/mcp list

清單裡會看到 sentry 顯示為未授權，對 sentry 那項按 enter，瀏覽器會開啟頁面，都按 Approve 就行：

Claude Code 終端機執行 MCP list 選擇 Sentry 授權

Sentry 官方網站 OAuth 授權頁面點擊 Approve

Sentry MCP 授權成功完成提示頁面

接著 Claude 要重啟，可以問問 Claude 有了 Sentry MCP 後它可以做到哪些事，August 詢問後回答如下：

查 issue：search_issues 搜錯誤，按專案/時間/狀態過濾
查事件：search_events 挖詳細 event 資料，stack trace、tag、breadcrumb 都能看
AI 診斷：analyze_issue_with_seer 丟給 Seer 分析根因，給修復建議
改狀態：update_issue 標 resolved/ignored、指派負責人
找組織/專案：find_organizations、find_projects 列出可存取範圍
通用查詢：get_sentry_resource、execute_sentry_tool 存取更細資源

讓 Claude 知道要抓取哪個專案

Sentry 後台的側邊導覽列，點擊「設定 > 專案」，然後點擊要讓 Claude 分析的專案後，會看到專案資訊：

Sentry 後台專案設定中查看 Project Slug 與專案編號

提供 Slug 或是專案編號給 Claude 都行，就會抓到了，以下是 August 提供專案編號的示範：

在 Claude Code 對話中提供 Sentry 專案編號進行讀取

安裝 Gitea MCP

下列有三種方式，無論選擇哪種安裝方式，都需要先取得一組具備讀寫權限的 Gitea Token。

詳細的 Token 建立步驟與權限設定，請參考站內筆記文：

CodiumAI PR-Agent，在 Gitea 上用 AI 來 Code Review

方式一：直接用 go run

需要本機有 Go 才能使用：

claude mcp add --transport stdio --scope user gitea \
  --env GITEA_ACCESS_TOKEN=你的token \
  --env GITEA_HOST=https://your-gitea.internal \
  -- go run gitea.com/gitea/gitea-mcp@latest -t stdio

方式二：下載官方執行檔

官方 releases 有提供 gitea-mcp_Windows_x86_64.zip 給 Windows，以及 gitea-mcp_Darwin_arm64.tar.gz 給 Apple Silicon Mac。

Windows：

從 https://gitea.com/gitea/gitea-mcp/releases 下載 gitea-mcp_Windows_x86_64.zip
解壓縮,把 gitea-mcp.exe 放到一個固定資料夾(例如 C:\Tools\gitea-mcp)。

把該資料夾加進系統環境變數 PATH。

Mac：

curl -LO [https://gitea.com/gitea/gitea-mcp/releases/download/v1.2.0/gitea-mcp_Darwin_arm64.tar.gz](https://gitea.com/gitea/gitea-mcp/releases/download/v1.2.0/gitea-mcp_Darwin_arm64.tar.gz)
tar -xzf gitea-mcp_Darwin_arm64.tar.gz
sudo mv gitea-mcp /usr/local/bin/
chmod +x /usr/local/bin/gitea-mcp

安裝好 Gitea MCP 後，接上 Claude Code：

claude mcp add --transport stdio --scope user gitea --env GITEA_ACCESS_TOKEN=你的token --env GITEA_HOST=https://your-gitea.internal -- gitea-mcp -t stdio

方式三：用 Docker

官方也提供 docker.gitea.com/gitea-mcp-server 這個 image，不需要額外編譯或裝 Go。

claude mcp add --transport stdio --scope user gitea \
--env GITEA_ACCESS_TOKEN=你的token \
--env GITEA_HOST=https://your-gitea.internal \
-- docker run --rm -i -e GITEA_ACCESS_TOKEN -e GITEA_HOST [docker.gitea.com/gitea-mcp-server](http://docker.gitea.com/gitea-mcp-server)

不管選擇哪種方式，安裝好後在 Claude Code 輸入 /mcp，確認 Gitea 連線成功。

Claude Code 設定排程

Claude Code 選好本機專案後，貼上以下：

建立一個本機的排程，在本專案執行以下「Sentry issue 自動修復」功能：

Sentry 組織 slug: your-org-slug
Sentry 專案 slug: your-project
Gitea repo: Gitea 專案網址

步驟 1 - 找 issue:
呼叫 search_issues 找未解決的 error 類型 issue，
一次只查一種類型，不要用 OR / AND 組合查詢：

- "unresolved error issues" (limit 3)
  依事件數排序，取前 3 個。

步驟 2 - 抓細節:
對每個候選 issue 呼叫 get_issue_details，
取得完整 stack trace 與 trace ID。

步驟 3 - 分析根因:
對每個 issue 呼叫 analyze_issue_with_seer。
若 Seer 沒有給出可行的修正建議，
改用步驟 2 拿到的 stack trace 自行分析程式碼、
定位根因所在的檔案與函式。

步驟 4 - 本機修復:
只處理「根因明確、修改範圍小」的 issue（跳過需要
架構調整或影響多個模組的問題，改走步驟 6 的 fallback）。
在本機修改對應程式碼，接著執行專案既有的測試指令，
確認測試全數通過才進入下一步；測試沒過就放棄這個
issue、改走步驟 6。

步驟 5 - 開 PR（Gitea，透過 gitea-mcp）:
a. 呼叫 pull_request_read（method: list, state: open）
檢查 owner/repo 是否已有相同 issue 的開啟中 PR，
有的話跳過，避免重複開單。
b. git checkout -b fix/issue-<issue-id>-<date> main
commit 訊息包含 Sentry issue ID。
git push 到 Gitea。
c. 呼叫 pull_request_write（method: create）：- owner/repo - head: fix/issue-<issue-id>-<date> - base: main - title: "fix: <根因摘要>" - body:
"Sentry issue: <issue 連結>
Trace ID: <trace id>

        根因: <Seer 或自行分析的結論>
        修改內容: <變更摘要>
        測試結果: 已跑過既有測試並通過"

d. 每次執行最多開 2 個 PR，超過就停止並在最後總結說明。

步驟 6 - 無法修復時（fallback）:
若 Seer 與自行分析都無法定位可行修正，或修改範圍過大、
或測試沒通過，改呼叫 issue_write（method: create）
在 Gitea 開一個 issue，內容包含 Sentry issue 連結、
trace ID、已知線索，標記給人工處理，不要硬修。

執行完畢後，用一段文字總結：處理了幾個 issue、開了幾個 PR、
有幾個轉成 fallback issue，並列出每個 PR / issue 的連結。

需要替換的是前面幾行的這 3 個：

Sentry 組織 slug: your-org-slug
Sentry 專案 slug: your-project
Gitea repo: Gitea 專案網址

前 2 個值可以在 Sentry 後台取得。

第 3 個值就是 Gitea 上的專案取得。

送出後，Claude Code 會詢問執行的時間，提供後就會建立完成。

建議是建立完成後，執行一次，看還會遇到什麼問題。

建立好的排程，會出現在「Routines」裡：

Claude Code 自動排程 Routine 建立成功介面

進階整合：搭配 CodiumAI PR-Agent 實現 Gitea 自動 Code Review

最後再搭配這篇，就會在有 PR 時自動再做一次 Code Review：

CodiumAI PR-Agent，在 Gitea 上用 AI 來 Code Review

公司內部自架 Claude Code Marketplace，讓團隊共用 skill

Let's Write — Tue, 18 Aug 2026 13:18:47 +0000

本篇要解決的問題

有些 skill 只適合在公司內部使用，而這個 skill 又想讓其他同事能一起使用的話，就需要一個可以讓大家方便安裝、更新的平台。

本篇主要筆記，用自架的 Gitea 建立一個內部專用的 Claude Code plugin marketplace，讓團隊裡每個人寫的 skill 不再各自散落在自己電腦裡，而是能集中在一個地方統一發布、安裝、更新版本。

其他同事只要裝一次就能共用、之後改版也能一起同步拿到最新版。

這篇整理實作過程中每一個能正確跑通的步驟，讓大家避免在這過程中踩到的坑。

可用 GitHub、GitLab、Gitea，主要是專案可以有版控就行。

本篇示範的是在自架的 Gitea 上實作。

建立 marketplace 專案結構

Gitea 上新建一個 repo（例如 claude-plugins），本機目錄結構：

claude-plugins/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── your-plugin-name/
        ├── .claude-plugin/
        │   └── plugin.json
        └── skills/
            └── your-skill/
                └── SKILL.md

讓 Claude Code 直接產生 SKILL.md、plugin.json、marketplace.json

看到上面的架構，有一堆的檔案要建立時，不用感到驚慌失措或是害怕。

因為我們只需要把上面的架構貼給 Claude Code，讓它讀取之前已經寫好的 skill 內容，依照結構把 SKILL.md、plugin.json、marketplace.json 都建出來即可。

底下附上完整的 marketplace.json 範例，供對照參考：

{
  "name": "claude-plugins",
  "owner": { "name": "August" },
  "plugins": [
    { "name": "ai-tools", "source": "./plugins/ai-tools" },
    { "name": "ai-tools2", "source": "./plugins/ai-tools2" }
  ]
}

必要欄位：name（kebab-case，公開可見）、owner、plugins。
每個 plugin entry 至少要有 name 和 source。
若 source 是同一個 repo 內的相對路徑，要以 ./ 開頭，不可用 ../ 跳出去。
一個 plugin 可以裝多個 skill：skills/ 資料夾下每個子資料夾都是獨立一個 skill，不需要每個 skill 各自開一個 plugin。

Host 到 Gitea

不限 GitHub，GitLab、Bitbucket、自架伺服器都支援。把整個 claude-plugins repo push 到 Gitea 即可，不需要額外設定。

驗證

claude-plugins 專案上打開終端機，輸入：

claude plugin validate .

會檢查 JSON schema、重複的 plugin 名稱、路徑穿越等問題。

檔案寫的有問題，就會看到哪邊寫錯、哪邊建議要寫，再照著回應讓 Claude 繼續做修改即可。

本機測試安裝

/plugin marketplace add ./claude-plugins
/plugin install ai-tools@claude-plugins

安裝語法格式固定是 plugin名稱@marketplace名稱，分別對應 plugin.json 的 name 和 marketplace.json 的 name。

有幾個 plugin 就要執行幾次安裝指令。

要注意的是，這步可以跳過嗎？技術上可以，因為下一步的遠端安裝跟這步沒有依賴關係，直接對 Gitea 網址下指令一樣裝得起來。但跳過等於少了一層「出包前先在本機攔下來」的保護。

正式指向 Gitea

/plugin marketplace add https://gitea.你們公司.internal/team/claude-plugins.git

讓團隊自動加入（選用，非必要步驟）

最直接的方式：手動下指令。

同事不需要碰任何設定檔，兩行指令就能裝好：

/plugin marketplace add https://gitea.你們公司.internal/team/claude-plugins.git
/plugin install ai-tools@claude-plugins
/plugin install ai-tools2@claude-plugins

裝完就能直接用，缺點是每次換電腦、換專案，或新同事加入，都要重新打一次這幾行。

如果不想讓同事記指令、手動輸入，才需要往下看設定檔自動化這條路。

進階：讓同事 trust 專案資料夾就自動裝好。

以下的內容，要放在每一個開發中的專案裡的 .claude/settings.json：

{
  "extraKnownMarketplaces": {
    "claude-plugins": {
      "source": {
        "source": "url",
        "url": "https://gitea.你們公司.internal/team/claude-plugins.git"
      }
    }
  },
  "enabledPlugins": {
    "ai-tools@claude-plugins": true,
    "ai-tools2@claude-plugins": true
  }
}

extraKnownMarketplaces 只負責自動註冊 marketplace 來源。
enabledPlugins 才是真正讓 plugin 自動裝上並啟用的關鍵，兩者要同時寫，同事 trust 專案資料夾後才會完全不用手動 /plugin install。
如果目前還沒有同事需要同步使用，這一步可以先跳過，不影響前面步驟的成果，等有需要再回頭補上即可。

Gitea 上有新版本時，同事怎麼更新

如果有發佈新版本，記得 plugin.json 裡的 version 要往上加一版，沒改版號的話，其他同事那邊不會被判斷成有更新。

同事更新分兩步，順序不能反：

/plugin marketplace update claude-plugins
/plugin update ai-tools@claude-plugins

第一行只是刷新 marketplace 目錄，讓 Claude Code 知道有新版本存在。

第二行才是真正把新內容拉下來、覆蓋本機快取。

也可以用互動面板 /plugin → 選到該 plugin → Update now 達到一樣效果。

參考資料

這篇文章記錄的是目前版本觀察到的行為，Claude Code 的 plugin 系統仍在快速迭代中，實際行為可能隨版本更新而改變，建議操作前對照當下的官方文件再確認一次。

Agency Agents 教學：讓 Claude Code 與 Codex 自動切換 AI 專家角色

Let's Write — Sat, 15 Aug 2026 01:53:09 +0000

本篇要解決的問題

現在工作上幾乎都用 Claude Code、Codex 來進行開發，只是常常會遇到以下狀況：

要讓 AI 做 UI，會希望它像 UI 設計師一樣。

要 Code Review，希望它變成 Code Reviewer。

下一個專案要處理 Docker，又希望它不要一直卡在前端的事情上。

雖然我們可以每次都在 Prompt 裡打一大串：

你現在是一位資深前端工程師，
熟悉 Vue、React、Accessibility、Core Web Vitals……

再雖然我們可以把自己習慣的 Prompt 存起來複製貼上，但基本上人類都是懶惰的，能少打一個字就少打一個字，可以的話最好是 AI 能自己懂現在要扮演什麼樣的專業角色，這就是為什麼貓咪們看到人類都會覺得：

最近看到一個 GitHub 專案，發現可以解決上面很愛演的困擾：Agency Agents

簡單來說，這專案就是：

幫 AI 準備好一大票不同領域的專家角色，需要誰時，就叫誰出來~~當奴才~~工作。

官方目前已經有 230+ 個不同領域的 Agent，而且除了 Claude Code，也支援 Codex、Cursor、GitHub Copilot、Gemini CLI …… 等工具。

本篇除了筆記 Agency Agents 的安裝方式，也會多做一步：

建立一個 Router Skill，讓 Claude Code、Codex 自己判斷這次應該找哪個 Agent。

這樣平常只要正常描述需求：

幫我重新設計這個 Dashboard，完成後用 Vue 實作。

AI 就可以自己判斷要用 UI Designer，或是 Frontend Developer~~，或是鏟屎的~~。

Agency Agents 是什麼？

Agency Agents 不是新的 AI 模型，也不是另一套 Claude Code 或 Codex。

它比較像是一套「AI 專家角色設定檔」。

每一個 Agent 裡都已經寫好角色、工作方式、核心任務、交付內容、檢查項目等設定。

官方對它的定位也是「specialized AI agent personalities」，每個角色除了專業領域之外，還會包含自己的工作流程與交付方式。

例如 Frontend Developer，就不是只有：

You are a Frontend Developer.

然後就句點。

它裡面還會定義前端開發時要注意的東西，例如：

Vue / React / Angular
Responsive Web Design
Accessibility
Core Web Vitals
Component architecture
Performance
Testing

所以原本我們跟 Codex 說：

幫我做這個 Vue 頁面

裝完 Agency Agents 後，就可以直接指定要哪個角色，該角色會自動補足我們遺忘的專業度：

Use the Frontend Developer agent to implement this Vue page.

安裝 Agency Agents App

官方做了一套 Agency Agents App，它是 Agency Agents 的管理工具，可以瀏覽有哪些角色，再把 Agent 安裝進我們使用的 Coding Agent。

Windows

Windows 建議直接用 Agency Agents App。

到 Agency Agents App 的 GitHub Release 下載 Windows Installer 後安裝即可。

目前官方提供 x64 與 ARM64 的 Windows installer；官方也有特別註明 Windows 版本目前尚未 Code Sign，所以如果跳出 Windows SmartScreen，可以從「其他資訊」繼續執行。

裝完開啟 Agency Agents。

接著就可以選想使用的 Agent，以及要安裝到哪一套工具。

Mac

Mac 可以直接使用 Homebrew：

brew install --cask msitarzewski/agency-agents/agency-agents

這也是 Agency Agents 主專案目前提供的快速安裝方式。

裝完後開啟 Agency Agents App。

不論是 Windows 還是 Mac，Agency Agents App 的介面都長得相同：

前端工程師可以先裝哪些 Agent？

Agency Agents 的角色很多，不建議看到什麼就全部裝，最後搞得像寶可夢一樣不全部收集完就睡不著。

以平常前端開發來說，可以先從這幾個開始：

Agent	適合工作
Frontend Developer	Vue、React、JavaScript、CSS、RWD
UI Designer	UI、Dashboard、Design System、版面設計
UX Researcher	UX、流程、資訊架構、易用性
Software Architect	系統架構、大型重構
Code Reviewer	PR、Code Review、Bug、Regression
Senior Developer	比較複雜的開發工作
DevOps Automator	Docker、CI/CD、Jenkins、部署
Minimal Change Engineer	修 Bug，而且不要順手就重構整個宇宙

安裝角色時，就可以直接選擇要裝在哪些 AI 上：

讓 Claude Code、Codex 自動選 Agent

Agency Agents 官方提供的是「角色」。

接下來這段則是自己另外加上的功能：

Agency Agents Router。

概念很簡單，我們再建立一個 Skill，專門負責判斷以下情境：

分析使用者需求 → 需要專家嗎？
需要專家 → 找最適合的 Agency Agent。
不需要專家 → 自己直接做。

就不會看到「Vue」三個字，就一定叫 Frontend Developer。

所以 Router 要判斷的是：這個工作有沒有必要使用專家。

例如：

「把 margin-top 20px 改成 24px」→ 不用 Agent。

「重新設計整個後台，考慮 RWD 與無障礙」→ 用 Agent。

Claude Code、Codex 建立 agency-agents Skill

Claude Code、Codex 的 Skill 放置位置不同。

Claude Code

Mac：

終端機輸入：

open ~/.claude/skills

Windows：

開啟任一個資料夾，檔案路徑輸入：

%USERPROFILE%\.claude\skills\

接著新增以下資料夾跟檔案：

agency-agents
└── SKILL.md

Codex

Mac：

open ~/.agents/skills

Windows：

%USERPROFILE%\.agents\skills\

同樣建立：

agency-agents
└── [SKILL.md](http://skill.md/)

接著 SKILL.md 的內容，Claude Code、Codex 有一點不同，可以各自複製貼上。

Claude Code

https://github.com/letswritetw/agency-agents-skill/blob/main/claude/SKILL.md

Codex

https://github.com/letswritetw/agency-agents-skill/blob/main/codex/SKILL.md

讓 Claude Code 自動使用 Router

Skill 建好後其實就可以用了，Claude Code 會依照 description 判斷什麼時候載入。

不過如果要讓 AI 更積極一點想到 Agency Agents Router，需要再到全域 CLAUDE.md 補一段規則。

打開 CLAUDE.md 檔的方式如下。

Mac：

終端機輸入：

open ~/.claude/CLAUDE.md

Windows：

開啟任一個資料夾，檔案路徑輸入：

%USERPROFILE%\.claude\CLAUDE.md

在打開的 CLAUDE.md 中加入：

## Agency Agents

For development tasks that would materially benefit from specialist expertise, use the `agency-agents` skill to select and delegate to the most appropriate installed Agency Agent.

Prefer using the `agency-agents` skill automatically when the current task clearly matches its purpose. The user should not need to explicitly request the skill.

Use the minimum number of agents necessary.

Prefer direct execution for simple or mechanical tasks.

Do not delegate unless specialist expertise is likely to materially improve correctness, design quality, architecture, maintainability, reliability, performance, accessibility, or review quality.

Do not expand the requested scope merely because additional agents are available.

The user's original requirements, constraints, and project conventions always take priority over agent routing.

之後平常就不用輸入：

Use agency-agents.

直接講需求即可。

Codex 的 AGENTS.md

Codex 也可以在自己的 AGENTS.md 補上 Router 使用規則。

Mac：

終端機輸入：

open ~/.codex/AGENTS.md

Windows：

開啟任一個資料夾，檔案路徑輸入：

%USERPROFILE%\.codex\AGENTS.md

在打開的 AGENTS.md 中加入：

<!-- AGENCY_AGENTS_START -->

## Agency Agents

For software development tasks that would materially benefit from specialist expertise, use the `agency-agents` skill to select and delegate to the most appropriate installed custom agent.

When the current task clearly matches the `agency-agents` skill description, prefer implicit invocation instead of requiring the user to explicitly request `$agency-agents`.

Use the minimum number of agents necessary.

Prefer direct execution for simple or mechanical tasks.

Do not delegate unless specialist expertise is likely to materially improve correctness, design quality, architecture, maintainability, reliability, performance, accessibility, or review quality.

For tasks spanning multiple disciplines, let the `agency-agents` skill determine whether sequential delegation is useful.

Do not expand the requested scope merely because additional agents are available.

The user's original requirements, constraints, project conventions, and requested scope remain the source of truth.

<!-- AGENCY_AGENTS_END -->

總結

Agency Agents 裡面有一堆角色可以使用，目前 August 還在實驗中，看是不是在開發上會產生更精緻的結果。

記得幾年前 ChatGPT 剛出來時，網路上有很多人在分享怎麼寫 Prompt，很多開頭的第一句都是寫「請你扮演 XXX」。

這件事情現在已經不用了，因為已經可以讓 AI 自己選擇適合的角色來扮演。

這個 Agency Agents 專案目前有 143k 的星星數，看來懶惰的人類是很多的（誤），只好再放一次貓咪怎麼看我們人類的圖：

Buzz 自架教學：使用 Docker 架設 Relay 與設定 AI Agent 自動回覆

Let's Write — Fri, 31 Jul 2026 14:38:33 +0000

寫在文章之前，關於本文配圖

這篇文章的配圖，選擇了熊本城，是因為這周發生了熊本大地震，而 August 在今年的五月才去那裡旅遊過。

記得在逛熊本城的時候，裡面有個影片，是在講十年前的熊本大地震發生後，這幾年一路是怎麼走過來，一路又修復成目前的樣子。

雖然，這次又發生了地震，但相信熊本可以再站起來的。

本篇要解決的問題

最近一直在找一個可以把 AI Agent 一起加入到群組聊天的通訊軟體。

大部份都要錢，比如 Slack、Google Chat、Teams。

剛好不知怎麼回事，最近也常常看到講 AI 的電子報提到一個 Buzz，似乎可以解決這需求。

Buzz，是一套可自架的團隊協作工具。除了頻道聊天，也能加入 Codex、Claude Code 等 AI Agent，讓團隊成員直接在頻道中透過 tag Agent 來呼叫 AI。

雖說官方提供了 Self Hosting 的安裝說明，但實際上還是踩了幾個坑才順利的讓 Agent 回覆訊息。

本篇就是筆記實作安裝 Buzz 時的筆記，也把怎麼跳過這些坑的方式紀錄下來，讓看到這篇的你可以從從容容、遊刃有餘的閃過。

完成本文後，可以做到：

在 Mac 上透過 Docker Compose 自架 Buzz Relay。
使用 Buzz Desktop 連接自己的 Relay。
建立 Buzz Community 與頻道。
啟動內建的三個 Agent。
使用 Codex 作為 Fizz 的 AI 執行環境。（也可以用 Claude）
在頻道中透過 @Fizz 讓 Agent 回覆訊息。

安裝 Buzz Relay

1. 安裝必要工具

需要先安裝好以下：

Git
Docker Desktop
Docker Compose 2.24.4 以上

確認 Docker Desktop 已經啟動後，再繼續安裝。

2. 下載 Buzz 原始碼

Clone 官方 GitHub 上的專案：https://github.com/block/buzz

接著進到「deploy/compose」資料夾中，本篇會用 Docker 的方式安裝。

3. 建立 `.env`

deploy/compose 的資料夾裡有一個「.env.example」，這份檔另存為「.env」。

接著，把 .env 裡「buzz.example.com」、「CHANGE_ME…」的部份全都修改，變成我們要的內容。

另外要注意，目前官方的版本有個 bug，主要是Buzz Relay 容器會顯示 unhealthy，造成後續安裝不起來，目前解決的方式就是：

# 原本
BUZZ_GIT_CONFORMANCE_PROBE=true

# 改成
BUZZ_GIT_CONFORMANCE_PROBE=false

需要 KEY 的部份，可以使用以下指令產生隨機密鑰：

openssl rand -hex 32

產生一般密碼：

openssl rand -base64 24

不同用途的密鑰應分開產生，不要全部使用同一組。

如果覺得一行行修改很麻煩，這一步 ChatGPT 有給了一組指令，直接專案內開啟終端機執行以下也行：

cat > .env <<EOF
BUZZ_IMAGE=ghcr.io/block/buzz:main

BUZZ_DOMAIN=127.0.0.1
RELAY_URL=ws://127.0.0.1:3300

BUZZ_MEDIA_BASE_URL=http://127.0.0.1:3300/media
BUZZ_MEDIA_SERVER_DOMAIN=127.0.0.1

BUZZ_CORS_ORIGINS=tauri://localhost,http://tauri.localhost,https://tauri.localhost,http://127.0.0.1:3300

BUZZ_REQUIRE_AUTH_TOKEN=false
BUZZ_REQUIRE_RELAY_MEMBERSHIP=false
BUZZ_ALLOW_NIP_OA_AUTH=false

BUZZ_AUTO_MIGRATE=true
BUZZ_GIT_CONFORMANCE_PROBE=false

RUST_LOG=buzz_relay=info,buzz_db=info,buzz_auth=info,buzz_pubsub=info,tower_http=info

BUZZ_RELAY_PRIVATE_KEY=$(openssl rand -hex 32)
BUZZ_GIT_HOOK_HMAC_SECRET=$(openssl rand -hex 32)

POSTGRES_DB=buzz
POSTGRES_USER=buzz
POSTGRES_PASSWORD=$(openssl rand -hex 16)

REDIS_PASSWORD=$(openssl rand -hex 16)

BUZZ_S3_ACCESS_KEY=$(openssl rand -hex 10)
BUZZ_S3_SECRET_KEY=$(openssl rand -hex 16)
BUZZ_S3_BUCKET=buzz-media
BUZZ_S3_ADDRESSING_STYLE=path

BUZZ_HTTP_PORT=3300
EOF

因為 3000 是個很多應用程式都會預設使用的 PORT，所以上面的範例改用 3300。

4. 啟動 Buzz Relay

專案中開啟終端機，依序執行以下：

加入執行權限：

chmod +x run.sh

啟動：

./run.sh start

查看狀態：

./run.sh status

正常情況下會看到：

relay       healthy
postgres    healthy
redis       healthy
minio       healthy

5. 測試 Relay

打開瀏覽器，網址貼上：http://127.0.0.1:3300。

成功的話就會看到結果：

順便推薦一下本站開發的擴充功能 Let’s JSON，網址如果回傳的是 JSON，就會看到像上面截圖那樣美美的樣子。

Buzz Relay 安裝成功，剩下的事就是讓各個要使用的團隊成員電腦安裝 Buzz，然後設定抓我們自架的 Buzz Relay 了。

下載、安裝 Buzz

1. 下載 Buzz Desktop

前往 Buzz Releases：

https://github.com/block/buzz/releases

Apple Silicon Mac，例如 M1、M2、M3、M4，下載名稱包含以下文字的版本：

aarch64

Intel Mac 則下載：

x64

Windows 下載：

Buzz_0.5.2_x64-setup_alpha-unsigned.exe

但因為 Windows 版本的 Buzz 目前尚未完成數位簽章，開啟時系統會跳出安全性警告；此時可點擊「更多資訊」並選擇「仍要執行」（或於檔案屬性中勾選「取消封鎖」）即可完成安裝。

2. 登入 Buzz

安裝完 Buzz，打開後會遇到幾個項目，因為 Relay 我們是自架的，因此以下選項要這樣選擇。

Join or create a community：選擇「I already have a community」。

Reconnect to your community：選擇「I’m a member or admin」。

接著會需要輸入我們 Buzz Relay 的網址，之前的 .env 裡寫的是 http://127.0.0.1:3300，這邊就照填，如果上面你有自行修改的話，這邊就填寫你修改的。

以上，就可以進到我們自架的 Buzz 了。

使用 AI Agents 功能

這段就是 August 一直踩坑的部份，只要下列幾個坑都閃過，之後在對話框裡 @ AI Agents 就會得到回應。

確認有使用 AI

本機確定有安裝好 Claude CLI，或 Codex CLI。

如果沒有訂閱這兩家方案，也可以找網路上提供有免費額度的 LLM 來使用。

August 因為 Claude、ChatGPT 都有付費訂閱，所以示範的是這兩家的。

在 Buzz 的設定頁裡，要確認有使用 AI，如圖：

顯示為「Ready」代表有連結成功。

Buzz Agent 指的是用各家的 API。

確認 Community 網址相同

點擊左下角自己的帳號，接著「Local Dev > Community settings」：

裡面會看到一個設定是「Relay URL」：

要確認 URL 裡，ws:// 後的網址，跟我們的網址是相同的，比方上面在設定 Community 的網址是 http://127.0.0.1:3300，那這邊 ws:// 後就要是 127.0.0.1:3300。

這邊如果不相同，那 Agents 收到的來源就會不同，就會一直抓不到我們 @ 它們的訊息。

開放 Agents 接受回應

在 Agent 的設定畫面裡，點擊「Advanced」，裡面有一項「Who can talk to this agent」，要選成「Anyone」：

然後，上面的頁籤切到「Customize for this agent」，確認有選好要使用的模型：

最後，要確認 Agents 是運行中的：

實際測試

可以做一個簡單的測試，看 AI Agents 是不是會回應。

我們在預設建好的 Channel 裡，@ Agent 就行，就像我們在 LINE 上 @ 朋友們一樣。

成功的話，就會看到被 @ 的 Agent 正在思考中的訊息，也會對訊息回應 Emoji，思考完成，Agent 就會回覆訊息，如下圖：

小結

雖然可以把 AI Agents 加進聊天中，但 Windows 版的安裝比較麻煩。

而且，Codex、Claude Code 上都裝了很多習慣的 Skills，表面上 AI 是回說可以直接用，但輸入 / 或 $ 時沒有出現選項，也不知道到底有用 Skills 還是沒有。

只能說，Buzz 還是一個正在開發中的工具，看 GitHub 上的 Release 紀錄更新得很頻繁，再給它一點時間，它會更好的（？）。

Outline Wiki 自架教學（三）：Codex 串接 MCP

Let's Write — Fri, 24 Jul 2026 13:44:02 +0000

本篇要解決的問題

上一篇是 Outline + Claude，不一定每個人都有訂閱 Claude 方案，所以也提供 Codex 的方式。

跟著本篇一步步走，完成設定後，Codex 可以透過 MCP 呼叫 Outline 工具，執行很多好棒棒的事，例如：

搜尋或列出 Outline 文件
讀取、編輯文件集內的文件
建立文件集
移動文件
執行 MCP Server 已提供的其他 Outline 操作

Codex App、Codex CLI 與 IDE 擴充套件會共用 Codex 的 MCP 設定，因此設定完成後，不需要在每個客戶端重複設定。

前置準備

開始前，請先確認已具備以下環境：

安裝 Codex
安裝 Node.js
可正常連線的 Outline

建立 Outline API Token

進入喜好設定

登入 Outline 後，點擊左下角帳號旁的「⋯」，再選擇「喜好設定」。

開啟 API & Access

在左側設定選單中選擇「API & Access」，接著點擊右上角的「新 API 金鑰」。

設定金鑰名稱、範圍與到期日

建議輸入容易辨識用途的名稱，例如：「AI MCP」、「Codex MCP」等等。

原始流程中的設定為：

範圍： 留空
到期日： 沒有期限

範圍留空通常代表不限制特定 API 權限。這種設定操作最簡單，但權限也較大。

複製 API Token

建立完成後，點擊「複製」，並先將 Token 暫存在安全的位置，因為 Token 只會出現一次。

注意：API Token 等同於帳號憑證，不要貼到 Git、公開文件、部落格文章、聊天群組或未加密的筆記中。

設定 Codex MCP

開啟 Codex 設定檔

Codex 使用 config.toml 儲存 MCP 與其他本機設定。

作業系統	使用者層級設定檔路徑
Windows	`%USERPROFILE%\.codex\config.toml`
macOS	`~/.codex/config.toml`

使用者層級的設定會套用到 Codex App、Codex CLI 與 IDE 擴充套件。

Windows

開啟 PowerShell，執行：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex" | Out-Null
New-Item -ItemType File -Force "$env:USERPROFILE\.codex\config.toml" | Out-Null
notepad "$env:USERPROFILE\.codex\config.toml"

這三個指令會依序：

建立 .codex 資料夾。
建立 config.toml。
使用記事本開啟設定檔。

也可以開啟任一個資料夾，在檔案路徑列貼上：

%USERPROFILE%\.codex

接著開啟 config.toml。

macOS：使用 Finder 開啟

開啟 Finder。
點擊上方選單的「前往」。
選擇「前往檔案夾⋯」。
貼上下列路徑：

~/.codex/

找到並開啟：

config.toml

macOS：使用終端機開啟

也可以在終端機執行：

mkdir -p "$HOME/.codex"
touch "$HOME/.codex/config.toml"
open -e "$HOME/.codex/config.toml"

這三個指令會依序建立設定資料夾、建立設定檔，並使用 macOS 文字編輯器開啟。

若檔案已存在，建議先複製一份備份，再進行修改。

加入 Outline MCP Server

請將下列設定加入 config.toml：

[mcp_servers.outline]
command = "npx"
args = [
  "-y",
  "mcp-remote",
  "https://192.168.x.x:3023/mcp",
  "--header",
  "Authorization:${AUTH_HEADER}"
]

[mcp_servers.outline.env]
AUTH_HEADER = "Bearer YOUR_OUTLINE_API_TOKEN"
NODE_TLS_REJECT_UNAUTHORIZED = "0"

請替換以下內容：

設定值	說明
`https://192.168.x.x:3023/mcp`	Outline MCP Server 的連線網址
`YOUR_OUTLINE_API_TOKEN`	前一步建立的 Outline API Token

使用有效 HTTPS 憑證時的簡化設定

如果 Outline MCP Server 已使用有效且受信任的 HTTPS 憑證，Codex 可以直接連線，不需要 Node.js、npx 或 mcp-remote。

[mcp_servers.outline]
url = "https://YOUR_MCP_HOST/mcp"
http_headers = { Authorization = "Bearer YOUR_OUTLINE_API_TOKEN" }

例如：

[mcp_servers.outline]
url = "https://outline-mcp.example.com/mcp"
http_headers = { Authorization = "Bearer YOUR_OUTLINE_API_TOKEN" }

這是較簡單的正式環境設定方式。

注意：這個範例會把 Token 直接寫在 config.toml 中。請妥善保護設定檔，不要提交到 Git。

Windows 與 macOS 的 npx 路徑問題

Codex App 原則上可以直接執行 npx。

若 MCP 啟動失敗，可能是桌面程式找不到 npx 的執行路徑。

Windows

在 PowerShell 執行：

where.exe npx

可能會回傳：

C:\Program Files\nodejs\npx.cmd

可以將：

command = "npx"

改成 TOML 的單引號字串：

command = 'C:\Program Files\nodejs\npx.cmd'

TOML 的單引號字串不需要將 Windows 反斜線寫成 \\。

macOS

在終端機執行：

which npx

Apple Silicon Mac 使用 Homebrew 時，可能回傳：

/opt/homebrew/bin/npx

Intel Mac 使用 Homebrew 時，可能回傳：

/usr/local/bin/npx

接著將：

command = "npx"

改成實際查到的完整路徑，例如：

command = "/opt/homebrew/bin/npx"

注意：不要直接照抄範例路徑，應先使用 where.exe npx 或 which npx，再填入自己電腦實際回傳的結果。

重新啟動 Codex

修改 config.toml 後，需要重新啟動正在使用的 Codex。

Codex App／ChatGPT 桌面版： 完整結束後重新開啟。
Codex CLI： 離開目前工作階段，再重新執行 codex。
IDE 擴充套件： 重新啟動擴充套件或重新載入編輯器視窗。

只關閉視窗不一定代表程式已完全結束：

Windows： 從系統匣結束程式，或到工作管理員確認是否仍在背景執行。
macOS： 按下 Command + Q，必要時到「活動監視器」確認程式是否仍在執行。

重新啟動時，Codex 會：

讀取 ~/.codex/config.toml
透過 npx 啟動 mcp-remote
使用 Authorization Header 連接 Outline MCP Server
載入 MCP Server 提供的工具

首次執行 npx -y mcp-remote 時，可能需要下載套件，因此等待時間會比後續啟動稍長。

測試 Outline MCP 是否連線成功

使用 Codex CLI 檢查

先執行：

codex mcp list

正常情況下，清單中會出現：

outline

也可以執行：

codex mcp --help

查看目前版本支援的 MCP 管理指令。

進入 Codex CLI 後，輸入：

/mcp

即可查看目前工作階段載入的 MCP Server 與工具。

使用對話測試

在 Codex 中輸入：

可以接到 Outline MCP 嗎？請列出目前可使用的 Outline 工具。

接著再測試實際讀取：

請列出 Outline 中目前可以看到的文件與文件集。

也可以指定操作：

請搜尋 Outline 中包含「前端」關鍵字的文件。

連線成功時，Codex 會顯示已載入 Outline 工具，並能回傳工作區中的文件或 Collection 資訊。

Outline Wiki 自架教學（二）：ClaudeCodex 串接 MCP

Let's Write — Fri, 24 Jul 2026 13:07:20 +0000

Outline Wiki 自架教學（二）：Claude 串接 MCP

本篇要解決的問題

上一篇我們自架了 Outline Wiki，接著我們就要發揮它的威力了，就是可以使用 MCP，讓 Claude、Codex 來幫我們新增、編輯、彙整……我們的文件。

本篇主要是寫 Outline + Claude，下一篇會是 Outline + Codex。

照著本篇實作，完成設定後，Claude Desktop 可以透過 MCP 呼叫 Outline 工具，例如：

搜尋或列出 Outline 文件
讀取、編輯文件集內的文件
建立文件集
移動文件
執行 MCP Server 已提供的其他 Outline 操作

前置準備

開始前，請先確認已具備以下環境：

安裝 Claude Desktop
安裝 Node.js
可正常連線的 Outline

建立 Outline API Token

進入喜好設定

登入 Outline 後，點擊左下角帳號旁的「⋯」，再選擇「喜好設定」。

從左下角選單進入喜好設定

開啟 API & Access

在左側設定選單中選擇「API & Access」，接著點擊右上角的「新 API 金鑰」。

進入 API & Access 並建立新 API 金鑰

設定金鑰名稱、範圍與到期日

建議輸入容易辨識用途的名稱，例如：「AI MCP」、「Claude MCP」等等。

原始流程中的設定為：

範圍： 留空
到期日： 沒有期限

設定 API 金鑰範圍與到期日

範圍留空通常代表不限制特定 API 權限。這種設定操作最簡單，但權限也較大。

複製 API Token

建立完成後，點擊「複製」，並先將 Token 暫存在安全的位置，因為 Token 只會出現一次。

複製 Outline API Token

注意：API Token 等同於帳號憑證，不要貼到 Git、公開文件、部落格文章、聊天群組或未加密的筆記中。

設定 Claude Desktop MCP

開啟 Claude Desktop 設定檔

Claude Desktop 在 Windows 與 macOS 使用相同的設定檔名稱，但存放路徑不同。

作業系統	設定檔路徑
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`

Windows

開啟任一個資料夾，檔案路徑列貼上：

%APPDATA%\Claude\claude_desktop_config.json

也可以按下 Win + R，貼上相同路徑後按 Enter。

macOS：使用 Finder 開啟

開啟 Finder。
點擊上方選單的「前往」。
選擇「前往檔案夾⋯」。
貼上下列路徑：

~/Library/Application Support/Claude/

找到並開啟：

claude_desktop_config.json

macOS：使用終端機開啟

也可以在終端機執行：

mkdir -p "$HOME/Library/Application Support/Claude"
touch "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
open -e "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

這三個指令會依序建立設定資料夾、建立設定檔，並使用 macOS 文字編輯器開啟。

若檔案已存在，建議先複製一份備份，再進行修改。

加入 Outline MCP Server

請將下列設定加入 JSON 最外層物件中的 mcpServers：

{
  "mcpServers": {
    "outline": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://192.168.x.x:3023/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_OUTLINE_API_TOKEN",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

NODE_TLS_REJECT_UNAUTHORIZED=0 會停用 Node.js 的 TLS 憑證驗證。它只適合在可信任的內部網路中暫時測試，不建議用於公開網路或正式環境。較安全的做法是替 MCP Server 設定可被系統信任的有效憑證。

Windows 與 macOS 原則上可共用這份設定。如果 macOS 無法直接找到 npx，可以先在終端機執行：

which npx

假設回傳：

/opt/homebrew/bin/npx

便可將 command 改成完整路徑：

"command": "/opt/homebrew/bin/npx"

常見位置如下：

安裝方式	`npx` 可能的位置
Apple Silicon Mac 使用 Homebrew	`/opt/homebrew/bin/npx`
Intel Mac 使用 Homebrew	`/usr/local/bin/npx`
Node.js 官方 `.pkg`	以 `which npx` 的回傳結果為準

注意：不要直接照抄表格中的路徑。應先執行 which npx，再使用自己電腦實際回傳的結果。

請替換以下內容：

設定值	說明
`https://YOUR_MCP_HOST/mcp`	Outline MCP Server 的連線網址
`YOUR_OUTLINE_API_TOKEN`	前一步建立的 Outline API Token

例如 MCP Server 位於內部網路，可改成：

"https://192.168.x.x:3023/mcp"

合併既有設定時的注意事項

若 claude_desktop_config.json 已經有其他設定，不要直接覆蓋整份檔案，只需要把 mcpServers 合併進最外層物件。

Windows 設定範例

例如原本已有其他欄位：

{
  "coworkUserFilesPath": "C:\\Users\\Sean\\Claude",
  "preferences": {},
  "mcpServers": {
    "outline": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOUR_MCP_HOST/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_OUTLINE_API_TOKEN",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

macOS 設定範例

macOS 也使用相同的 JSON 結構。若 npx 可直接執行：

{
  "preferences": {},
  "mcpServers": {
    "outline": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOUR_MCP_HOST/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_OUTLINE_API_TOKEN",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

若 Claude Desktop 找不到 npx，將 command 改成 which npx 查到的完整路徑，例如：

"command": "/opt/homebrew/bin/npx"

JSON 常見錯誤包括：

欄位之間少了逗號
最後一個欄位多了逗號
大括號或中括號數量不一致
Windows 路徑中的反斜線沒有寫成 \\
macOS 路徑含有空白時，終端機指令沒有使用引號或跳脫字元
把 mcpServers 貼到最外層物件之外

重新啟動 Claude Desktop

修改設定檔後，必須完整關閉 Claude Desktop，再重新開啟。

只關閉視窗不一定代表程式已完全結束：

Windows： 從系統匣結束 Claude，或到工作管理員確認 Claude 是否仍在背景執行。
macOS： 按下 Command + Q，或從上方選單選擇「Claude」→「結束 Claude」。必要時可到「活動監視器」確認程式是否仍在執行。

重新啟動時，Claude Desktop 會：

讀取 claude_desktop_config.json
透過 npx 啟動 mcp-remote
使用 Authorization Header 連接 Outline MCP Server
載入 MCP Server 提供的工具

首次執行 npx -y mcp-remote 時，可能需要下載套件，因此等待時間會比後續啟動稍長。

測試 Outline MCP 是否連線成功

重新開啟 Claude Desktop 後，可以輸入：

可以接到 Outline MCP 嗎？請列出目前可使用的 Outline 工具。

接著再測試實際讀取：

請列出 Outline 中目前可以看到的文件與文件集。

也可以指定操作：

請搜尋 Outline 中包含「前端」關鍵字的文件。

連線成功時，Claude 會顯示已載入 Outline 工具，並能回傳工作區中的文件或 Collection 資訊。

Outline Wiki 自架教學（一）：Docker 安裝、Gitea OIDC 與 AI 知識庫準備

Let's Write — Fri, 26 Jun 2026 13:49:09 +0000

Outline Wiki 自架教學（一）：Docker 安裝、Gitea OIDC 與 AI 知識庫準備

本篇要解決的問題

公司開發團隊裡，想架一套內部的知識庫，又要能支援 AI，常見的痛點有幾個：

文件資料留在自己的機器上，不對外，以免洩露商業機密。
想要加上 AI？得付 $$，比如 Notion，或是也可以自架的 Docmost。
Outline Wiki 裝起來很難，August 失敗過一次，最後是靠 Claude Opus 4.8 的輔助才成功。

本篇筆記文，會用一份 Docker Compose 檔，把 Outline，以及需要的 PostgreSQL、Redis、Caddy 全包進去，並針對上面這些坑一次閃掉。

另外也先說明本文裡的基本設定：

本機已裝好 Docker。
對內 PORT 是 3002，對外是 3001。

關於 Outline + AI 的補充說明：

自架版 Outline 沒有內建的「AI Answers」功能，網路上常看到的 OPENAI_API_KEY 對自架版是無效的。想要 Outline 加上 AI，正解是用 MCP 外接，讓 Claude / Codex 透過 Outline 的 API 來操作（作法將寫在下一篇）。

步驟 1：安裝 Gitea

第一個管理員帳號要用 Gitea 登入，所以得先有一台 Gitea。

Gitea 本身也能用 Docker 自架，這部分 August 之前寫過，直接看這篇：

安裝 Gitea。

只要你的 Gitea 已經能正常登入，就可以往下走。

Outline 並不限定 Gitea，任何相容 OIDC 的供應商（Keycloak、Authentik、Google⋯）都行，差別只在 OIDC_* 那幾個網址。

步驟 2：從 Gitea 取得 Client ID 與 Secret

Outline 走 OIDC 登入，需要在 Gitea 建立一個「OAuth2 應用程式」，拿到 Client ID 和 Client Secret。

進入 Gitea 後，到 設定（Settings）→ 應用程式（Applications），找到「管理 OAuth2 應用程式」區塊。

在 Gitea 的「設定 → 應用程式」頁面，找到「管理 OAuth2 應用程式」的建立表單

需要填兩個欄位：

應用程式名稱：填一個自己記得註是做什麼的名稱，如：Outline Wiki Login。
重新導向 URI：要填的 PORT 是有對外加上憑證，比如本篇用的是 3001。

https://<你的IP或網域>:3001/auth/oidc.callback

例如主機 IP 是 192.168.11.111，就填 https://192.168.11.111:3001/auth/oidc.callback。這個 IP 與埠號要跟等一下 Compose 裡的 URL= 完全一致。

Gitea OAuth2 應用程式表單，填入應用程式名稱與重新導向 URI（重點是 Redirect URI 結尾為 /auth/oidc.callback）

按下「建立應用程式」後，Gitea 會顯示 Client ID 與 Client Secret。

Gitea 建立完成後顯示的 Client ID 與 Client Secret 畫面。

要注意，Client Secret 只會完整顯示這一次，先複製存好。等一下要填進 Compose 的 OIDC_CLIENT_ID 與 OIDC_CLIENT_SECRET。

步驟 3-1：安裝 Outline Wiki：Windows 版

Windows 用 Docker Desktop，這裡用具名 volume（由 Docker 管理）存附件，啟動最單純。

先新增一個空資料夾，接著我們要放進下面的 2 個檔案。

Caddyfile

資料夾內新增一個檔案，檔名：Caddfile。

Caddyfile 負責「對外用 HTTPS、把流量轉給 Outline」。

檔案內容複製貼上以下，再把 192.168.11.111 換成我們 Windows 主機的區網 IP：

{
  default_sni 192.168.11.111
}

192.168.11.111:3001 {
  tls internal
  reverse_proxy outline:3002
}

tls internal：Caddy 自己簽一張憑證。因為我們用的是區網 IP，本來就申請不到正式憑證，自簽夠用。
3001 是對外埠、outline:3002 是 Outline 容器內部埠，兩者分工，注意不能寫成一樣。

docker-compose.yml

資料夾內再新增一個檔案，檔名：docker-compose.yml。

檔案內容複製貼上以下：

# =============================================================================
# Outline Wiki — Docker Compose 教學範例
# =============================================================================
# 架構：
#   outline   → 主應用 (Node.js)
#   caddy     → 反向代理 + 自動 HTTPS
#   postgres  → 資料庫
#   (外部)    → Redis，負責快取 / WebSocket / 背景工作佇列
#
# ⚠️ 發佈前務必把所有 <...> 佔位符換成你自己的值。
#    範例裡的密鑰、密碼、IP 全是假的，不要直接拿去用。
# =============================================================================

services:
  # ---------------------------------------------------------------------------
  # Outline 主應用
  # ---------------------------------------------------------------------------
  outline:
    image: outlinewiki/outline:latest
    container_name: outline
    restart: unless-stopped
    environment:
      - NODE_ENV=production

      # --- 安全密鑰 (必填) ---------------------------------------------------
      # 兩把都要用 32-byte 隨機 hex 字串。產生方式:
      #   openssl rand -hex 32
      # ⚠️ 換掉後不要再改，改了會讓既有 session / 加密資料失效。
      - SECRET_KEY=<openssl rand -hex 32 產生>
      - UTILS_SECRET=<openssl rand -hex 32 產生>

      # --- 資料庫連線 (必填) -------------------------------------------------
      # 格式：postgres://帳號:密碼@主機:埠/資料庫名
      # 主機名 postgres = 下面那個 service 名稱，Docker 內部 DNS 解析。
      - DATABASE_URL=postgres://outline_user:<DB_密碼>@postgres:5432/outline
      - PGSSLMODE=disable   # 同一台 Docker 內部連線，不需 SSL

      # --- Redis 連線 (必填) -------------------------------------------------
      # 格式：redis://:密碼@主機:埠/DB編號
      # 這裡指向下面內建的 redis service，主機名 redis = service 名。
      - REDIS_URL=redis://redis:6379/1

      # --- 對外網址 (必填) ---------------------------------------------------
      # 使用者瀏覽器看到的完整網址，要跟 Caddy / 反代對外位置一致。
      - URL=https://<你的網域或IP>:8443
      - PORT=3019            # 容器內部監聽埠 (給 Caddy 反代用,不直接對外)
      - FORCE_HTTPS=false    # HTTPS 由 Caddy 處理，這裡關掉避免重導迴圈

      # --- 檔案儲存 (必填) ---------------------------------------------------
      # local = 存本機磁碟 (搭配下面 volumes)。也可改 s3 接物件儲存。
      - FILE_STORAGE=local
      - FILE_STORAGE_LOCAL_ROOT_DIR=/var/lib/outline/data
      # 上傳/匯入大小上限 (bytes)。預設約 1MB,匯入大 zip (如從
      # Docmost/Notion 匯出) 會跳「file too large」。調大解決。
      # 算法: MB × 1048576。下面 = 250MB。
      - FILE_STORAGE_UPLOAD_MAX_SIZE=262144000            # 附件上限
      - FILE_STORAGE_IMPORT_MAX_SIZE=262144000            # 單篇匯入
      - FILE_STORAGE_WORKSPACE_IMPORT_MAX_SIZE=262144000  # zip 整包匯入 (關鍵)

      # --- 登入: Gitea OIDC (選填) -------------------------------------------
      # 任何相容 OIDC 的供應商都行 (Gitea / Keycloak / Authentik / Google...)。
      # client id/secret 從你的 OIDC 供應商後台拿。
      - OIDC_CLIENT_ID=<OIDC_CLIENT_ID>
      - OIDC_CLIENT_SECRET=<OIDC_CLIENT_SECRET>
      - OIDC_AUTH_URI=http://<OIDC主機>/login/oauth/authorize
      - OIDC_TOKEN_URI=http://<OIDC主機>/login/oauth/access_token
      - OIDC_USERINFO_URI=http://<OIDC主機>/login/oauth/userinfo
      - OIDC_USERNAME_CLAIM=preferred_username   # 用哪個欄位當帳號
      - OIDC_DISPLAY_NAME=Gitea                   # 登入按鈕顯示文字
      - OIDC_SCOPES=openid profile email

      # --- SMTP 寄信 (選填) --------------------------------------------------
      # 用途：magic-link 登入信 + 通知信。
      # Gmail 範例：密碼要用「應用程式密碼」，不是帳號密碼。
      # (Google 帳號 → 安全性 → 兩步驟驗證 → 應用程式密碼)
      - SMTP_HOST=smtp.gmail.com
      - SMTP_PORT=587
      - SMTP_SECURE=false    # 587 用 STARTTLS，所以這裡 false
      - SMTP_USERNAME=<你的gmail@gmail.com>
      - SMTP_PASSWORD=<Gmail 應用程式密碼>
      - SMTP_FROM_EMAIL=<你的gmail@gmail.com>
      - SMTP_REPLY_EMAIL=<你的gmail@gmail.com>

    volumes:
      # 用具名 volume，由 Docker 管理。注意：這裡存的是「附件/上傳檔」
      # (圖片、PDF...)，不是文章本體。文章內容存在 PostgreSQL，不是 .md 檔。
      - outline_data:/var/lib/outline/data
    depends_on:
      postgres:
        condition: service_healthy   # 等 DB 健康檢查通過才啟動 outline
      redis:
        condition: service_healthy   # 等 Redis 就緒

  # ---------------------------------------------------------------------------
  # Redis — 快取 / WebSocket / 背景工作佇列 (內建獨立 service)
  # ---------------------------------------------------------------------------
  redis:
    image: redis:7-alpine
    container_name: outline_redis
    restart: unless-stopped
    volumes:
      - redis_data:/data   # 持久化 (選用,Outline 主要當快取，掉了也能重建)
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]   # 回 PONG 才算就緒
      interval: 10s
      timeout: 5s
      retries: 5

  # ---------------------------------------------------------------------------
  # Caddy — 反向代理，自動處理 HTTPS 憑證
  # ---------------------------------------------------------------------------
  caddy:
    image: caddy:2
    container_name: outline_caddy
    restart: unless-stopped
    ports:
      - "8443:8443"   # 對外開的埠 (主機：容器)。實際反代規則寫在 Caddyfile。
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro   # :ro = 唯讀掛載
      - caddy_data:/data       # 存 TLS 憑證，別刪，刪了要重新申請
      - caddy_config:/config
    depends_on:
      - outline

  # ---------------------------------------------------------------------------
  # PostgreSQL
  # ---------------------------------------------------------------------------
  postgres:
    image: pgvector/pgvector:pg16
    container_name: outline_postgres
    restart: unless-stopped
    environment:
      # 這三個要跟上面 DATABASE_URL 裡的帳號/密碼/DB名一致。
      - POSTGRES_USER=outline_user
      - POSTGRES_PASSWORD=<DB_密碼>
      - POSTGRES_DB=outline
    volumes:
      - pg_data:/var/lib/postgresql/data   # 資料庫實體資料，千萬別誤刪
    ports:
      # 只綁 127.0.0.1 = 僅本機可連，不對外曝露 DB。安全做法。
      - "127.0.0.1:5432:5432"
    healthcheck:
      # 確認 DB 真的可接受連線，outline 才會啟動 (見上面 depends_on)。
      test: ["CMD-SHELL", "pg_isready -U outline_user -d outline"]
      interval: 10s
      timeout: 5s
      retries: 5

# -----------------------------------------------------------------------------
# 具名 volume — 由 Docker 管理,容器刪掉資料還在。
# -----------------------------------------------------------------------------
volumes:
  outline_data:
  pg_data:
  redis_data:
  caddy_data:
  caddy_config:

接著要把所有 <...> 的部份換成自己的值，要改這幾項：

SECRET_KEY、UTILS_SECRET：開啟終端機，執行兩次 openssl rand -hex 32 產生 32-byte 隨機字串。沒有 openssl 的話，那就用 Claude、ChatGPT 等 AI，對話中讓它們生成 2 組使用。
DATABASE_URL 與 POSTGRES_PASSWORD：兩邊的密碼要一致。
URL：填 https://<你的IP>:3001，IP 要跟 Caddyfile 一樣。
OIDC_CLIENT_ID、OIDC_CLIENT_SECRET：填上一段從 Gitea 拿到的值。
OIDC_AUTH_URI / OIDC_TOKEN_URI / OIDC_USERINFO_URI：把 <OIDC主機> 換成 Gitea 網址。
（選填）SMTP：要寄邀請信 / magic-link 才需要填。

啟動

在 docker-compose.yml 所在資料夾開終端機：

docker compose up -d

第一次啟動 Outline 會自動跑資料庫遷移（migration），會需要多等個十幾秒。

看到 outline 正常起來後，瀏覽器打開 https://<你的IP>:3001。

瀏覽器會跳「您的連線不是私人連線 / 不安全」警告。

這是因為 tls internal 用的是自簽憑證，屬於正常現象。點「進階 → 繼續前往」就能進到 Outline。

進站後點 Continue with Gitea 用 Gitea 帳號登入，第一個登入的人就是管理員。

之後的成員，在 Outline 後台用 Email 邀請即可（這也是為什麼上面要設定 SMTP）。

步驟 3-2：安裝 Outline Wiki：Ubuntu 版

Ubuntu 版跟 Windows 版幾乎一樣，只有兩個差別：

附件改用 bind mount（./data）：附件直接落在專案資料夾，搬家 / 備份複製整個資料夾就帶走，不必像具名 volume 還要 tar 撈。
OIDC 的 Gitea 可以在另一台機器，只要這台 Ubuntu 連得到即可。

檔案

一樣是兩個檔案：docker-compose.yml 和 Caddyfile。

Caddyfile 內容（把 IP 換成你的 Ubuntu 主機 IP）：

{
  default_sni 192.168.11.111
}

192.168.11.111:3001 {
  tls internal
  reverse_proxy outline:3002
}

docker-compose.yml 的內容複製貼上以下：

# =============================================================================
# Outline Wiki — Ubuntu 單主機部署版 (教學範例)
# =============================================================================
# 跟 Windows 版的差異：
#   1. 內建 Redis service — 不依賴外部 Redis 主機，一台 Ubuntu 全包。
#   2. 全部服務同一台主機，對外只露 Caddy 的 8443。
#   3. OIDC 仍可指向「另一台」Gitea/OIDC 主機，只要這台網路連得到。
#
# 架構：
#   outline   → 主應用 (Node.js)
#   redis     → 快取 / WebSocket / 背景佇列
#   caddy     → 反向代理 + 自動 HTTPS
#   postgres  → 資料庫
#
# ⚠️ 發佈前把所有 <...> 佔位符換成你自己的值。範例的密鑰/密碼/IP 全是假的。
#
# 部署步驟：
#   1. 整個資料夾複製到 Ubuntu (含 Caddyfile)。
#   2. 全域搜尋取代 <你的Ubuntu主機IP> → 實際 IP。
#   3. docker compose up -d
# =============================================================================

services:
  # ---------------------------------------------------------------------------
  # Outline 主應用
  # ---------------------------------------------------------------------------
  outline:
    image: outlinewiki/outline:latest
    container_name: outline
    restart: unless-stopped
    environment:
      - NODE_ENV=production

      # --- 安全密鑰 (必填) ---------------------------------------------------
      # 兩把都用 32-byte 隨機 hex。產生: openssl rand -hex 32
      # ⚠️ 換掉後別再改，改了會讓既有 session / 加密資料失效。
      - SECRET_KEY=<openssl rand -hex 32 產生>
      - UTILS_SECRET=<openssl rand -hex 32 產生>

      # --- 資料庫連線 (必填) -------------------------------------------------
      # 格式：postgres://帳號:密碼@主機:埠/資料庫名
      # 主機名 postgres = 下面的 service 名，Docker 內部 DNS 解析。
      - DATABASE_URL=postgres://outline_user:<DB_密碼>@postgres:5432/outline
      - PGSSLMODE=disable   # 同台 Docker 內部連線,不需 SSL

      # --- Redis 連線 (必填) -------------------------------------------------
      # ★ Ubuntu 版重點：指向「內建」redis service，主機名 redis = service 名。
      #   不像基本版要填外部 Redis IP/密碼。
      - REDIS_URL=redis://redis:6379/1

      # --- 對外網址 (必填) ---------------------------------------------------
      # 使用者瀏覽器看到的完整網址，要跟 Caddy 對外位置一致。
      - URL=https://<你的Ubuntu主機IP>:8443
      - PORT=3019            # 容器內部監聽埠 (給 Caddy 反向代理，不直接對外)
      - FORCE_HTTPS=false    # HTTPS 由 Caddy 處理，這裡關掉避免重導迴圈

      # --- 檔案儲存 (必填) ---------------------------------------------------
      - FILE_STORAGE=local
      - FILE_STORAGE_LOCAL_ROOT_DIR=/var/lib/outline/data
      # 上傳/匯入大小上限 (bytes)。預設約 1MB，匯入大 zip 會跳「file too large」。
      # 算法: MB × 1048576。下面 = 250MB。
      - FILE_STORAGE_UPLOAD_MAX_SIZE=262144000            # 附件上限
      - FILE_STORAGE_IMPORT_MAX_SIZE=262144000            # 單篇匯入
      - FILE_STORAGE_WORKSPACE_IMPORT_MAX_SIZE=262144000  # zip 整包匯入 (關鍵)

      # --- 登入: Gitea OIDC (選填) -------------------------------------------
      # 任何相容 OIDC 供應商皆可 (Gitea / Keycloak / Authentik / Google...)。
      # ★ Ubuntu 版注意：OIDC 主機可在「另一台」機器，確認這台 Ubuntu 連得到。
      - OIDC_CLIENT_ID=<OIDC_CLIENT_ID>
      - OIDC_CLIENT_SECRET=<OIDC_CLIENT_SECRET>
      - OIDC_AUTH_URI=http://<OIDC主機>/login/oauth/authorize
      - OIDC_TOKEN_URI=http://<OIDC主機>/login/oauth/access_token
      - OIDC_USERINFO_URI=http://<OIDC主機>/login/oauth/userinfo
      - OIDC_USERNAME_CLAIM=preferred_username   # 用哪個欄位當帳號
      - OIDC_DISPLAY_NAME=Gitea                   # 登入按鈕顯示文字
      - OIDC_SCOPES=openid profile email

      # --- SMTP 寄信 (選填) --------------------------------------------------
      # 用途：magic-link 登入信 + 通知信。
      # Gmail 範例：密碼要用「應用程式密碼」,不是帳號密碼。
      # (Google 帳號 → 安全性 → 兩步驟驗證 → 應用程式密碼)
      - SMTP_HOST=smtp.gmail.com
      - SMTP_PORT=587
      - SMTP_SECURE=false    # 587 用 STARTTLS，所以 false
      - SMTP_USERNAME=<你的gmail@gmail.com>
      - SMTP_PASSWORD=<Gmail 應用程式密碼>
      - SMTP_FROM_EMAIL=<你的gmail@gmail.com>
      - SMTP_REPLY_EMAIL=<你的gmail@gmail.com>

    volumes:
      # 存的是「附件/上傳檔」(圖片、PDF...)，不是文章本體 (文章在 PostgreSQL)。
      # ★ 用 bind mount: 附件直接落在專案資料夾 ./data,搬家複製即帶走。
      #   對比 named volume (outline_data:) 要 tar 才能撈出，bind 好搬很多。
      #   注意：DB 不要 bind，DB 檔不能直接 copy，一律用 pg_dump 備份。
      - ./data:/var/lib/outline/data
    depends_on:
      postgres:
        condition: service_healthy   # 等 DB 健康檢查通過才啟動
      redis:
        condition: service_healthy   # 等 Redis 就緒

  # ---------------------------------------------------------------------------
  # Redis — 內建獨立 service (★ Ubuntu 版才有,基本版用外部 Redis)
  # ---------------------------------------------------------------------------
  redis:
    image: redis:7-alpine
    container_name: outline_redis
    restart: unless-stopped
    volumes:
      - redis_data:/data   # 持久化 (選用，Outline 主要當快取，掉了也能重建)
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]   # 回 PONG 才算就緒
      interval: 10s
      timeout: 5s
      retries: 5

  # ---------------------------------------------------------------------------
  # Caddy — 反向代理，自動處理 HTTPS 憑證
  # ---------------------------------------------------------------------------
  caddy:
    image: caddy:2
    container_name: outline_caddy
    restart: unless-stopped
    ports:
      - "8443:8443"   # 對外唯一開的埠 (主機:容器)。反代規則寫在 Caddyfile。
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro   # :ro = 唯讀掛載
      - caddy_data:/data       # 存 TLS 憑證，別刪，刪了要重新申請
      - caddy_config:/config
    depends_on:
      - outline

  # ---------------------------------------------------------------------------
  # PostgreSQL — pgvector 映像 (支援向量搜尋)
  # ---------------------------------------------------------------------------
  postgres:
    image: pgvector/pgvector:pg16
    container_name: outline_postgres
    restart: unless-stopped
    environment:
      # 這三個要跟上面 DATABASE_URL 的帳號/密碼/DB名一致。
      - POSTGRES_USER=outline_user
      - POSTGRES_PASSWORD=<DB_密碼>
      - POSTGRES_DB=outline
    volumes:
      - pg_data:/var/lib/postgresql/data   # 資料庫實體資料，千萬別誤刪
    ports:
      # 只綁 127.0.0.1 = 僅本機可連，不對外曝露 DB。安全做法。
      - "127.0.0.1:5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U outline_user -d outline"]
      interval: 10s
      timeout: 5s
      retries: 5

# -----------------------------------------------------------------------------
# 具名 volume — 由 Docker 管理，容器刪掉資料還在。
# -----------------------------------------------------------------------------
volumes:
  # outline_data 改用 bind mount (./data)，不在這裡宣告。
  pg_data:
  redis_data:
  caddy_data:
  caddy_config:

要修改的部份，如：密鑰、DB、OIDC、SMTP，都與 Windows 版填法完全相同。

啟動

在 docker-compose.yml 所在資料夾開終端機：

docker compose up -d

確認與登入流程跟 Windows 版一樣：瀏覽器打開 https://<你的IP>:3001，遇到憑證警告點「繼續前往」，再用 Gitea 登入。

結語

照著上面的步驟做，我們就會有一套 完全自架 + 免費 + 可以用 MCP 接上 AI 的 Outline Wiki。

怎麼用 MCP 接上 Claude、Codex，下一篇會說明。

OpenClaw：安裝教學，在 macOS 用虛擬機 (Ubuntu) 安全部署龍蝦 AI

Let's Write — Tue, 03 Mar 2026 12:39:26 +0000

OpenClaw：安裝教學，在 macOS 用虛擬機 (Ubuntu) 安全部署龍蝦 AI

本篇要解決的問題

自從 OpenClaw 橫空出世後，三不五時就會看到相關的文章和影音介紹，看起來是個跨時代的產物。不過伴隨而來的，也有不少資安方面的疑慮。

相信很多人都想試試龍蝦的威力，但說實話，安裝起來沒那麼簡單。

本篇主要筆記怎麼安裝 OpenClaw。為了安全考量，選擇先在本機架設虛擬機，再於虛擬機上安裝 OpenClaw。這樣萬一出事了，大不了直接把虛擬機砍掉就好。

本篇注意事項：

本篇安裝 OpenClaw 時，官方的版本是 2026.3.2。官方更新速度很快，也許會遇到不同的安裝設定，如果遇到有疑問或不知道是什麼的狀況，建議詢問 AI。
本篇是使用 macOS，虛擬機是使用 Ubuntu-24.04.4。

以下將 OpenClaw 簡稱龍蝦。

安裝虛擬機

下載並安裝 VirtualBuddy：https://github.com/insidegui/VirtualBuddy/releases。

安裝完 VirtualBuddy 後，打開來，選擇 Linux > 左下角的 Custom Link。

輸入：

https://cdimage.ubuntu.com/releases/24.04.4/release/ubuntu-24.04.4-live-server-arm64.iso

或者手動下載 iso：https://cdimage.ubuntu.com/releases/24.04.4/release/

點擊「64-bit ARM (ARMv8/AArch64) server install image」。

在 VirtualBuddy 的介面，選擇 Linux > 左下角的 Custom File，選擇剛剛下載的檔案。

安裝的設定可以如下：

Virtual CPUs：3 或 4
Memory：4
Display Width / Height：都拉到最小值

安裝時，遇到「Install OpenSSH server」，記得這選項要打勾。

安裝完並重開機後，建議後續改用 Mac 的終端機 ssh 的方式來操作。

比方登入後，會看到這段訊息：

我們只需要在終端機上輸入：

ssh [你的帳號]@192.168.64.13
範例：
ssh letswrite@192.168.64.13

接著輸入帳號，就可以遠端登入了。

安裝 Node.js

本篇透過 npm 來安裝 OpenClaw，因此需要先安裝 Node.js。

下載並執行 NVM 安裝腳本

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

更新環境設定

source ~/.bashrc

# 如果是用 Zsh
source ~/.zshrc

安裝 Node.js（npm 會一併安裝）

nvm install --lts

取得 Telegram Bot Token

龍蝦可以在多個平台使用，在看了幾個官方的 Releases，會發現每次更版都有針對 Telegram 的部分，看起來對 Telegram 的支援度較高，因此本篇使用 Telegram。

註冊了 Telegram 會員後，登入，我們要先建立一個機器人用的帳號。

Telegram 上要新增一個機器人很容易，一樣跟機器人對話就可以建立。

點擊這個網址加入 BotFather 為好友：https://telegram.me/BotFather。

接著對話框中傳送這個給 BotFather：

/newbot

再按照 BotFather 需要我們回應的訊息，一步步回應後，就可以得到 Telegram Bot 的 Token，如下圖：

這個 Token 要存下來，之後安裝龍蝦時，就可以在安裝過程中直接輸入。

安裝 OpenClaw：正常版

以下是平常有扶老婆婆過馬路，有積功德，可以一路順順走下去的 Happy Path 版本。

輸入指令：

npm i -g openclaw

安裝完後，接著輸入以下指令，開始進行設定：

openclaw onboard

Onboarding mode

直接使用 QuickStart。

Model/auth provider

根據網路上看到的災情 +
August 本人的 Google Antigravity 被封殺過的人體實驗證明 +
各家 API 的花費如果要到 Pro 等級的很燒 $$ 經驗……

那個，對，August 曾經選擇 Gemini Pro 3 的 API，安裝個 gog 跟一些 skills 就燒掉了 3 美金，所以除非口袋很深，不然不建議用 API 的方式。

建議二種：

ChatGPT 是 Plus 以上方案的，就選 OpenAI 的 OpenAI Codex (ChatGPT OAuth)。
如果有訂閱 GitHub Copilot，就選 Copilot 的 GitHub Copilot (GitHub device login)。

如果是選 OpenAI Codex，選了以後，就會看到一個網址，貼到瀏覽器上後，執行登入，接著會看到「無法連上這個網站」的畫面，莫驚慌莫害怕，我們只要把登入結果的 URL 回貼到終端機上就可以了。

如果是選 GitHub Copilot，選了以後，會看到一個網址，用 GitHub 帳號授權登入後，填寫介面提供的代碼，就完成了。

其他使用模型的方式 August 沒試過，大家可以抱著探索自己口袋深度的心態勇敢按下去。

Select channel

選擇 Telegram (Bot API)，再選 Enter Telegram bot token。

然後把我們在前一段從 Telegram 上取得的 Token 貼上去，就可以了。

接著會問要不要安裝 skill，在這邊可裝可不裝，看個人需求，這個階段跳過也無所謂，後續再跟 Agent 說要裝 XX skill 就行。

下一步會看到問要不要再輸入「GOOGLE_PLACES_API_KEY」、「GEMINI_API_KEY」、「OPENAI_API_KEY」、「ELEVENLABS_API_KEY」，可以都選「No」，因為凡是 Key、Token……都是要發動魔法小卡的。

「NOTION_API_KEY」，如果想讓 Agent 控制 Notion，可以填，在 Notion 的 integrations 頁面上可以取得 Key。

Enable hooks

這一步一開始沒看懂，問了 Gemini 後才懂意思，如下：

boot-md：當系統（Gateway）啟動時，會自動讀取並執行工作區中的 BOOT.md 檔案。這適合用來初始化環境變數或設定當次啟動的特殊邏輯。
bootstrap-extra-files：允許系統在啟動時載入額外的設定檔案（如 USER.md 或 SOUL.md）。這對於維持 AI 對你（使用者）的身份認知非常重要。
command-logger：（推薦勾選）將你下達的所有指令記錄到審計日誌（Audit log）中。重視 ISO 27001 與安全稽核的作業習慣。
session-memory：（核心功能）當執行 /new 或 /reset 指令開新對話時，會自動將之前的上下文（Context）存入記憶。這能確保 AI 即使重啟對話，也能維持開發進度的連續性。

勾不勾選就看個人需求，後續也都可以再更改。

最後，就安裝成功了，之後只要在 Telegram 建的機器人上隨便傳一句訊息，就會收到要配對的指令：

把最後一行的指令在終端機上執行，會看到收到以下的回傳訊息：

Approved telegram sender xxxxxxxxxx.

代表配對完成，可以在 Telegram Bot 上使用 OpenClaw 了。

安裝 OpenClaw：遇到神奇錯誤版

過年前 August 安裝龍蝦，都是上一段的正常版本。

但遇到 Google Antigravity 用到被停權，前幾天帳號終於解封後，再安裝時就出現了錯誤。

如果進行到最後一步，看到以下錯誤，就代表恭喜你，要走這段的版本：

Error: systemctl is-enabled unavailable: Command failed: systemctl --user is-enabled openclaw-gateway.service

解決方式如下，就照著一步步輸入指令就可以，以下都是來自於 Claude 提供的解方。

第一步：前置準備（安裝前先做）

sudo loginctl enable-linger $USER
echo 'export XDG_RUNTIME_DIR=/run/user/$(id -u)' >> ~/.bashrc
echo 'export DBUS_SESSION_BUS_ADDRESS=unix:path=${XDG_RUNTIME_DIR}/bus' >> ~/.bashrc
source ~/.bashrc

第二步：正常安裝 OpenClaw

openclaw onboard

遇到 systemctl 相關錯誤直接忽略，繼續完成設定。

第三步：手動建立 Gateway Service

安裝完成後執（一次性的複製貼上即可）：

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/openclaw-gateway.service << EOF
[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
Environment="PATH=$(dirname $(which openclaw)):/usr/local/bin:/usr/bin:/bin"
ExecStart=$(which openclaw) gateway run
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable openclaw-gateway
systemctl --user start openclaw-gateway

第四步：確認正常運作

systemctl --user status openclaw-gateway
systemctl --user is-enabled openclaw-gateway
openclaw status

is-enabled 應顯示 enabled。

openclaw status 裡 gateway 應顯示 reachable。

重新安裝 gateway

openclaw gateway install --force

接著重啟：

openclaw gateway restart

常用管理指令

systemctl --user stop openclaw-gateway      # 停止
systemctl --user restart openclaw-gateway   # 重啟
journalctl --user -u openclaw-gateway -f    # 即時 log

按照上面的步驟執行後，OpenClaw 就安裝成功了。

後續想要修改設定

比方在安裝時，選了使用 GitHub Copilot，之後如果想換用 Openai Codex，或是一些設定值想要修改，要怎麼做呢？

很簡單，執行以下命令：

openclaw config

修改完成後，要再重啟 gateway：

openclaw gateway restart

站內搜尋加上 AI：使用 Google Vertex AI Search（RAG）打造智慧問答型搜尋

Let's Write — Tue, 20 Jan 2026 14:40:02 +0000

本篇要解決的問題

之前就一直想試試看 RAG（Retrieval-Augmented Generation） 要怎麼應用在實際場景，但卡在自建 RAG 架構的門檻不低（像是要處理向量資料庫、轉檔、索引……bla bla bla），又想說成本會不會很高？直到這幾天發現了 Google 有 Vertex AI Search 這功能，讓 Gemini 判斷了一下可能成本，發現，意外的蠻便宜的耶，就決定來應用一下。

簡單說明 RAG（以下為 Gemini 提供）：

RAG 就像是為 AI 掛載了一份「即時參考資料」。它並非單一資料庫，而是包含三個核心動作，而 Vertex AI Search 已經把這些複雜的底層邏輯都封裝好了：

檢索（Retrieval）：當使用者問問題時，系統去你的網站（資料庫）找出最相關的幾段文字。
增強（Augmented）：把這些找出來的文字，連同原本的問題，一起塞進給 AI 的指令（Prompt）裡。
生成（Generation）：AI 閱讀了你給它的「臨時參考資料」，最後產出正確的回答。

因為本站重點都在實作，因此本篇的使用情境設定如下：

當網站內容累積到一定程度後，傳統的關鍵字搜尋往往無法精準回應使用者的需求。透過 Vertex AI Search，可以實作 RAG 架構，讓站內搜尋不只是「找關鍵字」，而是能「閱讀」我們的網站內容並整理出答案。

而在打不過 AI 就加入它的時代，我們可以達成：

自然語言提問：使用者問「怎麼實作 code review」，AI 能從多篇文章中彙整答案。
低開發成本：不需自行維護向量資料庫 (Vector DB) 或處理複雜的資料清洗。
高精準度：結合 Google 的語意搜尋與生成能力。

本篇實作成果，已經放上了首頁，以及每篇筆記文的文末，會看到一個「Vertex AI 搜尋」的輸入框，大家可以試一試喔，覺得好用或不好用，都歡迎留言。

建立 Google Vertex AI Search (RAG) 實作流程：資料匯入

首先，必須要有一個 Google Cloud 的帳號，有了帳號後新增專案，而這個專案必須是「付費帳戶」，就是要付 $$ 的。

有了一個付費帳戶的專案，接著開始以下幾個步驟。

進入 Vertex AI 後台：從 Google Cloud 控制台進入 Vertex AI 介面。

啟用 API：點擊「啟用所有建議的 API」以確保功能完整。

因為啟用不用 $$，之後有使用到才要，為了防止後續步驟陣亡的莫名其妙，這邊就給它全部打開。

選擇應用程式類型：點擊「運用 AI 模式打造站內搜尋服務」。

填寫應用程式資訊：輸入名稱並選取區域（建議選 global）。

建立資料儲存庫 (Data Store)：點擊建立按鈕。

選取資料來源：選擇「網站內容」。

因為本篇是應用在站內搜尋，因此是選「網站內容」，如果大家使用時目的不同，可以詢問 AI 用哪一個省成本。

指定索引路徑：輸入網址模式，如 www.letswrite.tw/*。

「自動檢索網址並持續更新」：建議打勾，之後網站有更新，Vertex 就會自動更新。

啟用強化功能：設定儲存庫名稱並建議勾選「文件處理設定」。

下面截圖中的選項要不要勾看網站的內容，一樣可以跟 AI 討論是否都勾。

選取計費模式：初期選擇「一般計費模式」。

連結 Data Store：勾選剛建好的儲存庫並點擊繼續。

監控進度：在資料頁面查看「正在建立初始索引」。

增加 Sitemap：手動新增 Sitemap 網址以確保文章完整收錄。

索引完成：當狀態顯示「初始索引建立完成」時，可以看到目前文件的總體積與數量（本站約 340 MB，共 696 份文件）。

將 Vertex AI Search 放上網站

調整回覆風格：在「設定」中將搜尋類型改為「搜尋答案」，並在操作說明加入「簡明扼要、不超過 100 字、繁體中文」等指令。

整合權限設定：選取「公開存取權」並填入允許的網域。

實作：iframe 與加到 WordPress

本站是用 WordPress 架站的，照著上圖直接照放程式碼，發現樣式會被影響，因此把 Vertex Search 的頁面做一個 HTML 檔案，然後在 WordPress 上嵌入。

iframe.html

我們將 Widget 放在新增的 HTML 檔案中，並處理 Shadow DOM 的 Enter 事件以動態撐開高度。

<!doctype html>
<html lang="zh-TW">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vertex AI Search - Let's Write</title>
    <style>
      body {
        margin: 0;
        padding: 0;
        width: 100%;
        font-family: sans-serif;
      }
      #searchWidgetTrigger {
        width: 100%;
        padding: 12px;
        box-sizing: border-box;
        border: 1px solid #ccc;
        border-radius: 8px;
        -webkit-appearance: none; /* 移除 iOS 預設樣式 */
      }
      gen-search-widget {
        display: block;
        margin-top: 10px;
      }
    </style>
  </head>
  <body>
    <input id="searchWidgetTrigger" inputmode="search" />

    <gen-search-widget
      configId="9a35bc9d-f398-4b2b-bfeb-28091c39e3f6"
      triggerId="searchWidgetTrigger"
      anchorsTarget="_blank"
      alwaysOpened
      placeholder="Vertex AI 搜尋"
    ></gen-search-widget>

    <script src="https://cloud.google.com/ai/gen-app-builder/client?hl=zh_TW"></script>

    <script>
      const widget = document.querySelector("gen-search-widget");
      const searchInput = document.getElementById("searchWidgetTrigger");
      let triggered = false;

      // 處理 Enter 按下時的邏輯
      const onEnterPressed = () => {
        // 防止重複觸發
        if (triggered) return;
        triggered = true;

        // 通知父頁面調整 iframe 高度
        window.parent.postMessage(
          { type: "setHeight", height: 500 },
          "https://www.letswrite.tw",
        );

        // 2 秒後重置觸發狀態，允許下次搜尋
        setTimeout(() => {
          triggered = false;
        }, 2000);
      };

      // 深度遍歷 shadow DOM，為所有 input 和 button 添加事件監聽
      const setupDeepListener = (root, depth = 0) => {
        // 防止無限遞迴
        if (depth > 5) return;

        const inputs = root.querySelectorAll("input");
        const buttons = root.querySelectorAll("button");

        // 為所有 input 元素添加事件監聽
        inputs.forEach((input) => {
          // 避免重複添加監聽器
          if (input.dataset.listenerAdded) return;
          input.dataset.listenerAdded = "true";

          // 桌機：Enter 鍵 (keyup)
          input.addEventListener("keyup", (e) => {
            if (e.key === "Enter" || e.keyCode === 13) {
              onEnterPressed();
            }
          });

          // 手機：Enter 鍵 (keypress)
          input.addEventListener("keypress", (e) => {
            if (e.key === "Enter" || e.keyCode === 13) {
              onEnterPressed();
            }
          });

          // 手機：輸入變化時觸發 (失焦或完成輸入)
          input.addEventListener("change", () => {
            setTimeout(onEnterPressed, 100);
          });
        });

        // 為所有 button 元素添加點擊監聽 (手機端主要觸發方式)
        buttons.forEach((button) => {
          if (button.dataset.listenerAdded) return;
          button.dataset.listenerAdded = "true";

          button.addEventListener("click", () => {
            onEnterPressed();
          });
        });

        // 遞迴檢查嵌套的 shadow DOM
        root.querySelectorAll("*").forEach((el) => {
          if (el.shadowRoot) {
            setupDeepListener(el.shadowRoot, depth + 1);
          }
        });
      };

      // 設置 shadow DOM 監聽器
      const setupShadowListener = () => {
        try {
          const shadow = widget.shadowRoot;
          if (!shadow) return false;

          // 初始化深度監聽
          setupDeepListener(shadow);

          // 使用 MutationObserver 監聽動態添加的元素
          const observer = new MutationObserver((mutations) => {
            mutations.forEach((mutation) => {
              mutation.addedNodes.forEach((node) => {
                if (node.nodeType === 1) {
                  // 如果新增節點有 shadow root，遞迴設置監聽
                  if (node.shadowRoot) {
                    setupDeepListener(node.shadowRoot);
                  }
                  // 如果新增 input 或 button，重新掃描整個 shadow DOM
                  if (node.tagName === "INPUT" || node.tagName === "BUTTON") {
                    setupDeepListener(shadow);
                  }
                }
              });
            });
          });

          observer.observe(shadow, {
            childList: true,
            subtree: true,
          });

          return true;
        } catch (e) {
          return false;
        }
      };

      // 等待 widget 定義並設置監聽
      customElements.whenDefined("gen-search-widget").then(() => {
        setTimeout(() => {
          // 每 500ms 嘗試設置監聽，直到成功
          const interval = setInterval(() => {
            if (setupShadowListener()) {
              clearInterval(interval);
            }
          }, 500);

          // 15 秒後停止嘗試
          setTimeout(() => clearInterval(interval), 15000);
        }, 1000);
      });

      // 外層 input 的 Enter 鍵監聽 (keyup)
      searchInput.addEventListener("keyup", (e) => {
        if (e.key === "Enter" || e.keyCode === 13) {
          onEnterPressed();
        }
      });

      // 外層 input 的 Enter 鍵監聽 (keypress)
      searchInput.addEventListener("keypress", (e) => {
        if (e.key === "Enter" || e.keyCode === 13) {
          onEnterPressed();
        }
      });

      // 監聽整個文檔的 Enter 鍵 (keyup,捕獲階段)
      document.addEventListener(
        "keyup",
        (e) => {
          if (
            e.target.tagName === "INPUT" &&
            (e.key === "Enter" || e.keyCode === 13)
          ) {
            onEnterPressed();
          }
        },
        true,
      );

      // 監聽整個文檔的 Enter 鍵 (keypress 捕獲階段)
      document.addEventListener(
        "keypress",
        (e) => {
          if (
            e.target.tagName === "INPUT" &&
            (e.key === "Enter" || e.keyCode === 13)
          ) {
            onEnterPressed();
          }
        },
        true,
      );

      // 監聽所有按鈕點擊 (捕獲階段 主要針對手機端)
      document.addEventListener(
        "click",
        (e) => {
          if (e.target.tagName === "BUTTON" || e.target.closest("button")) {
            setTimeout(onEnterPressed, 100);
          }
        },
        true,
      );
    </script>
  </body>
</html>

WordPress 裡嵌入 iframe 頁面

透過 WP Code 等插件，可以選擇在標題上方，或各文章頁底部自動插入 iframe。

以下是範例。

(function() {
    const target = document.querySelector('.bwp-section-header-separator');
    if (target && !document.getElementById('vertexIframe')) {
        const htmlString = `
            <div class="vertex-ai-container" style="width: 100%; margin: 20px 0;">
                <iframe id="vertexIframe" 
                        src="/iframe.html" 
                        style="width: 100%; border: none; overflow: hidden; transition: height 0.3s ease; height: 85px;" 
                        scrolling="no">
                </iframe>
            </div>`;
        target.insertAdjacentHTML('beforebegin', htmlString);
    }

    window.addEventListener('message', function(event) {
        // 建議加入來源網域檢查（因 iframe 同源可省略，但若跨網域則必須）
        // if (event.origin !== "https://YOUR_IFRAME_DOMAIN") return;
        if (event.data && event.data.type === 'setHeight') {
            const iframe = document.getElementById('vertexIframe');
            if (iframe) {
                iframe.style.height = (event.data.height + 10) + 'px';
            }
        }
    }, false);
})();

成本分析預估

基於目前的網站規模（約 700 份文件），August 預計在官網測試一個月多來評估，主要是成本考量。

以下是「Gemini 3 思考型」做的成本預估：

項目	估計單價 (USD)	說明
資料儲存 (Storage)	約 $1.00 / GB / 月	340 MB 體積產生的月費微乎其微。
企業版查詢 (Enterprise)	$4.00 / 1,000 次查詢	包含 RAG 生成式回答與語意搜尋。
Gemini 2.5 Flash Token	依流量計費	由於 Flash 價格極低，主要成本集中在查詢次數費。

如果每月有 1,000 次有效查詢，預估成本約為 $4 ~ $10 美金。

一個月 5 美金以下，就還可以接受，超過 5 美金……就要看本站能不能帶來一些收入了，不然一直造成支出也不是辦法。