DEV Community: Let's Write

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 美金……就要看本站能不能帶來一些收入了，不然一直造成支出也不是辦法。

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

Let's Write — Sat, 10 Jan 2026 10:18:06 +0000

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

本篇要解決的問題

之前有寫過一篇：〈使用 Gitea Actions 與 OpenAI 實現自動化 PR Code Review〉。

底下有人留言說，Gitea 還有其他 Code Review 的方式，研究了以後發現，哎哎哎，這不就是 CodiumAI 的 PR-Agent 嗎？之前寫過在 GitHub、GitLab 上使用的，沒想到 Gitea 也有：

再加上本篇，本站對於 CodiumAI PR-Agent Code Review 這塊就湊滿 Git 三神獸了，看能不能解開什麼封印之門（咦？）

CodiumAI PR-Agent 是一個開源的 AI 工具，能夠自動分析 Pull Request 的變更內容。

本篇將用 Docker 來部署並整合到用 Docker 自架的 Gitea，實現以下自動化流程：

自動審查：當開發者建立或更新 PR 時，自動觸發 AI 進行分析。
自動描述：AI 自動生成 PR 的摘要修改點，減少工程師撰寫文件的時間。
品質建議：提供程式碼改進建議、偵測潛在 Bug。
繁體中文友善：設定 AI 以繁體中文回應，好吸收好閱讀。

Docker 安裝 Gitea

架設 Gitea 伺服器，可以參考前一篇 Gitea 的文章，就邊就不重覆寫：

Docker 安裝 Gitea

本文假設我們已經有一個運行中的 Gitea，並且擁有管理員權限。

取得需要的 Token 與 Webhook Secret

在部署 CodiumAI PR-Agent 前，我們需要先準備好 Gitea 的 Token 與 OpenAI API Key。

取得 Gitea Personal Access Token

Token 是為了讓 PR-Agent 可以讀取專案，並進行留言。

登入 Gitea 伺服器。
點擊右上角頭像，進入「設定」。
選擇左側選單的「應用程式」。
在「管理存取權杖」區塊中，點擊「生成新權杖」。
填寫權杖名稱（例如：pr-agent）。
權限設定（重要）：請務必勾選以下權限：

issue：讀取和寫入
repository：讀取和寫入

點擊「產生 Token」並 立即複製（離開頁面後將無法再次查看）。

生成 Webhook Secret

為了確保安全性，我們需要設定一個 Secret 來驗證 Webhook 請求。

產生 Secret 的方式有二種。

在終端機使用 openssl 產生一組高強度的隨機字串：

openssl rand -base64 24

直接跟 AI 要一組，比方在 ChatGPT 或 Gemini 上，輸入：提供我一組 16 碼金鑰。

產生的 Secret 要記下來，之後會填到設定檔中。

準備 OpenAI API Key

前往 OpenAI Platform 建立一組 API Key。

建立 Key，必須要先存一筆金額才能使用。

這功能是要 $$ 的，記得選用 CP 高的模型，才不會幾次 Code Review 下來，荷包大失血。

Docker Compose 與環境變數設定

.env

建立一個專案用資料夾，取名「pr-agent-gitea」。

資料夾裡新增 .env 的檔案，把敏感的資料，如我們前二步取得的 Token，都寫進去，方便管理與保密。

複製貼上以下到 .env：

# ==================== Gitea 連線設定 ====================
# 若 Gitea 在另一台主機，請填寫該主機的固定 IP 或網域
GITEA_URL=http://192.168.xx.xx:3000
GITEA_TOKEN=在此貼上在 Gitea 取得的Token
GITEA_WEBHOOK_SECRET=在此貼上 Secret

# ==================== LLM 模型設定 ====================
OPENAI_KEY=在此貼上 Openai 的 Key

docker-compose.yml

專案裡新增一個 docker-compose.yml 檔，複製貼上以下內容：

services:
  pr-agent:
    image: codiumai/pr-agent:0.31-gitea_app
    container_name: pr-agent
    restart: unless-stopped

    env_file:
      - .env

    environment:
      # ==================== Gitea 連線設定 ====================
      CONFIG__GIT_PROVIDER: "gitea"
      GITEA__URL: ${GITEA_URL}
      GITEA__PERSONAL_ACCESS_TOKEN: ${GITEA_TOKEN}
      GITEA__WEBHOOK_SECRET: ${GITEA_WEBHOOK_SECRET}
      GITEA__SKIP_SSL_VERIFICATION: "false"

      # ==================== OpenAI 模型設定 ====================
      CONFIG__MODEL: "gpt-4.1-mini"
      OPENAI__KEY: ${OPENAI_KEY}

      # ==================== PR 觸發設定 ====================
      # 設定自動執行的指令：描述 (/describe)、審查 (/review)、優化 (/improve)
      GITEA__PR_COMMANDS: '["/describe", "/review", "/improve"]'
      # 設定觸發動作：開啟 PR 或 同步更新代碼時
      GITEA__HANDLE_PR_ACTIONS: '["opened", "synchronize"]'

      # ==================== 語言與輸出設定 ====================
      CONFIG__RESPONSE_LANGUAGE: "zh-TW"
      CONFIG__PUBLISH_OUTPUT: "true"
      CONFIG__PUBLISH_OUTPUT_PROGRESS: "false"

      # ==================== 留言行為設定 ====================
      # 強制使用新留言模式 (false)，不覆蓋舊留言，保留審查歷史
      PR_DESCRIPTION__PERSISTENT_COMMENT: "false"
      PR_REVIEW__PERSISTENT_COMMENT: "false"
      # 關閉行內程式碼註解 (依喜好開啟)
      PR_REVIEW__INLINE_CODE_COMMENTS: "false"

      # ==================== 功能開關設定 ====================
      # 簡化輸出，關閉額外的分類標籤
      PR_DESCRIPTION__ENABLE_SEMANTIC_FILES_TYPES: "false"
      PR_REVIEW__ENABLE_REVIEW_LABELS_EFFORT: "false"
      PR_REVIEW__ENABLE_REVIEW_LABELS_SECURITY: "false"
      GITEA__PUBLISH_LABELS: "false"

      # ==================== 檔案忽略清單 (Cost Saving) ====================
      # 忽略鎖定檔、靜態資源等不需要分析的檔案，大幅節省 Token 費用
      CONFIG__IGNORE__GLOB: "['dist/**', 'build/**', 'out/**', '.next/**', 'coverage/**', 'node_modules/**', 'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', '*.md', '*.txt', '*.log', '*.min.js', '*.min.css', '*.map', '*.svg', '*.png', '*.jpg', '*.jpeg', '*.gif', '*.ico', '*.woff', '*.woff2', '*.ttf', '*.eot', '.env*', '.gitignore', '.eslintrc*', '.prettierrc*', 'tsconfig.json', 'jest.config.*', 'vite.config.*', 'webpack.config.*', '*.spec.ts', '*.spec.js', '*.test.ts', '*.test.js']"

    ports:
      - "3001:3000"

內容說明：

模型選擇 (CONFIG__MODEL)：使用 gpt-4.1-mini，這是 CP 值高的選擇。
語言設定 (CONFIG__RESPONSE_LANGUAGE)：指定 zh-TW，讓 AI 輸出時用正體中文。
忽略清單 (CONFIG__IGNORE__GLOB)：如果想省 $$，這點很重要！要排除 node_modules、圖片檔、lock 檔等，避免 AI 浪費 Token 去讀取這些非程式碼檔案。
ports：這邊指定 3001，主要是 Gitea 預設是 3000，如果 PR-Agent 一樣用 3000 會啟動失敗，因此改用 3001。

docker-compose.yml 檔完成後，專案內開啟終端機，執行：

docker-compose up -d

Container 上看到有 pr-agent，代表啟動成功。

實際執行 Code Review

設定 Gitea Repository Webhook

最後一步，我們要告訴 Gitea 當有 PR 發生時，要把資料送給誰。

進入要進行 Code Review 的專案，點擊「設定」 > 「Webhook」 > 「新增 Webhook」 > 「Gitea」。
Webhook 填寫以下資訊：

目標 URL：http://<我們的_PR_AGENT_IP>:3001/api/v1/gitea_webhooks
HTTP 方法：POST
POST Content Type：application/json
密鑰：填入 .env 中的 GITEA_WEBHOOK_SECRET。
觸發條件：選取「自訂事件」，建議勾選：
問題留言（Issue Comment）
合併請求（Pull Request）
合併請求留言（Pull Request Comment）
合併請求同步（Pull Request Synchronize）

點擊「新增 Webhook」。

驗證成果

我們可以建一個小專案，故意寫錯出幾個 bug，然後發一個 Pull Request。

等待約 10~30 秒，我們會看到：

AI 自動留言 (Describe)：AI 會摘要這個 PR 做了什麼改動。
AI 自動審查 (Review)：AI 會列出「主要變更」、「潛在問題」以及「改進建議」。

進階：手動觸發指令

除了 PR 時自動觸發，我也可以在 PR 的留言區輸入指令與 AI 互動：

/describe：重新生成 PR 描述。
/review：重新執行程式碼審查。
/ask "這段改動有 SQL Injection 風險嗎？"：針對特定問題詢問 AI。

總結

透過 PR-Agent 與 Gitea 的整合，我們可以用極低的成本搭建 Code Review 功能。

雖然 AI 無法 100% 取代人工，但它能幫忙過濾低級錯誤、自動撰寫文件，讓攻城獅能將精力集中在怎麼攻城（欸這什麼結論）。

在本機安裝 Mattermost：打造自主控制的團隊通訊平台

Let's Write — Wed, 10 Dec 2025 12:19:20 +0000

本篇要解決的問題

工作上，各家公司用的通訊軟體，常聽到的是以下三種：LINE、Teams、Slack。

如果稍微比較一下，用起來的經驗如下（以下為 August 個人體感，不代表本台立場 XD）：

LINE、Telegram：適合閒聊

這兩個工具雖然方便，尤其台灣人幾乎都有 LINE，但主要設計給日常聊天使用。

面對工程團隊需要更結構化的溝通方式時，比如：頻道分類、討論串、檔案管理、發送程式碼……等功能就不太行。

還容易讓生活 + 工作的訊息都摻在一起作灑尿牛丸，重要資訊很容易被淹沒。

Slack、Teams：貴

Slack 夠強大，也是專門針對開發團隊用，但免費版只能保留最近 90 天的訊息記錄，而且發送訊息的數量每個月有上限，想要完整保存對話歷史就必須付費。

對小團隊或個人專案來說，魔法小卡沒辦法說發動就發動。

Microsoft Teams 需要企業或教育機構的授權才能充分使用，個人或小團隊要獨立使用並不方便，比如想要用 Webhook，家庭方案還無法使用。

Discord：資料及傳檔限制

雖然 Discord 免費且功能豐富，但所有資料都存放在 Discord 的伺服器上，對於重視資料隱私或需要完全掌控資料的人來說，這是一個重要的考量點。

傳檔案時，如果是免費方案有 10 MB 的限制，想傳大一點的檔案就會被擋下來。

因為使用上述幾個通訊軟體的體感，在詢問了 Gemini 3 Pro 有沒有更適合的工具後，才知道了今天要筆記的這個 Mattermost。

Mattermost 優勢

開源，可以完全安裝在自己的電腦或伺服器上。
類似 Slack 的使用方式，支援頻道分類、討論串、檔案分享等功能，還能透過外掛擴充更多能力。
可以整合 Webhook、機器人帳號。
所有資料都在本地，不用擔心第三方服務終止或資料外洩的問題。

本機安裝 Mattermost

事前準備

在開始之前，請確認電腦已經安裝：

Docker Desktop（包含 Docker Compose）
一個行動硬碟（選用，用來存放圖片和檔案）

Docker Compose 設定檔

建立一個工作目錄，在裡面新增 docker-compose.yml 檔案。

可以直接複製貼上以下：

services:
  db:
    image: postgres:16-alpine
    restart: "no"
    volumes:
      - ./volumes/db:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=mattermost
      - POSTGRES_USER=mmuser
      - POSTGRES_PASSWORD=mmuser_password

  mattermost:
    depends_on:
      - db
    image: mattermost/mattermost-team-edition:latest
    restart: "no"
    security_opt:
      - no-new-privileges:true
    pids_limit: 200
    volumes:
      - ./volumes/config:/mattermost/config:rw
      - ./volumes/logs:/mattermost/logs:rw
      - ./volumes/plugins:/mattermost/plugins:rw
      - ./volumes/client/plugins:/mattermost/client/plugins:rw
      - /Volumes/backup/mattermost_data:/mattermost/data:rw
      - /etc/localtime:/etc/localtime:ro
    environment:
      - MM_SQLSETTINGS_DRIVERNAME=postgres
      - MM_SQLSETTINGS_DATASOURCE=postgres://mmuser:mmuser_password@db:5432/mattermost?sslmode=disable&connect_timeout=10
      - MM_SERVICESETTINGS_SITEURL=http://localhost:8065
      - MM_PLUGINSETTINGS_ENABLEUPLOADS=true
      - MM_PLUGINSETTINGS_ENABLEMARKETPLACE=true
      - MM_SERVICESETTINGS_ALLOWCORSFROM=*
      - MM_WEBSERVER_WEBSOCKETSECUREPORT=8065
      - MM_SERVICESETTINGS_ENABLEINSECUREOUTGOINGCONNECTIONS=true
      - MM_EMAILSETTINGS_SENDPUSHNOTIFICATIONS=true
      - MM_EMAILSETTINGS_PUSHNOTIFICATIONSERVER=https://push-test.mattermost.com
      - MM_EMAILSETTINGS_PUSHNOTIFICATIONCONTENTS=full
      - MM_LOGSETTINGS_FILEMAXAGEDAYS=30
      - MM_LOGSETTINGS_FILECOMPRESS=true

    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "5"

    ports:
      - "8065:8065"

以下逐段說明設定內容：

資料庫服務

db:
  image: postgres:16-alpine
  restart: "no"
  volumes:
    - ./volumes/db:/var/lib/postgresql/data
  environment:
    - POSTGRES_DB=mattermost
    - POSTGRES_USER=mmuser
    - POSTGRES_PASSWORD=mmuser_password

這段設定建立了 PostgreSQL 16 資料庫容器。使用輕量的 Alpine Linux 版本可以減少映像檔大小。

restart: "no" 表示電腦重開機後不會自動啟動，需要手動執行啟動指令，主要是避免重新開機時，行動硬碟沒有插在主機上。

資料庫檔案存放在 ./volumes/db 目錄，這樣即使容器被刪除，資料也不會遺失。

環境變數設定了資料庫名稱、使用者名稱和密碼，這些資訊稍後會被 Mattermost 用來連線。

Mattermost 服務

mattermost:
  depends_on:
    - db
  image: mattermost/mattermost-team-edition:latest
  restart: "no"
  security_opt:
    - no-new-privileges:true
  pids_limit: 200

Mattermost 服務依賴資料庫，Docker 會確保資料庫先啟動。

使用 Team Edition 免費版本，已經足夠小型團隊使用。

security_opt 和 pids_limit 是安全性設定，限制容器的權限提升和程序數量。

儲存策略

volumes:
  - ./volumes/config:/mattermost/config:rw
  - ./volumes/logs:/mattermost/logs:rw
  - ./volumes/plugins:/mattermost/plugins:rw
  - ./volumes/client/plugins:/mattermost/client/plugins:rw
  - /Volumes/backup/mattermost_data:/mattermost/data:rw
  - /etc/localtime:/etc/localtime:ro

這裡採用混合儲存策略，解決 Mattermost 不刪檔特性帶來的空間問題：

存放在本機的檔案

設定檔（config）、日誌（logs）、外掛（plugins）都存在本機的 ./volumes/ 目錄。這些檔案體積小且需要頻繁讀取，放在 Volume 可以確保系統反應速度，避免操作介面卡頓。

存放在行動硬碟的靜態資源

圖片和檔案（data）存在行動硬碟的 /Volumes/backup/mattermost_data 路徑。這是整個設定的關鍵考量點：Mattermost 預設不會刪除任何上傳的檔案，即使訊息被刪除，檔案依然保留在伺服器上。

隨著時間累積，照片、文件、影片……會越來越多，如果全部存在本機，很快就會面臨空間不足的問題。

將這些靜態資源檔案改存到行動硬碟，既能完整保留所有歷史檔案，又不會壓縮主機空間。

請記得修改硬碟路徑：將 /Volumes/backup 改成行動硬碟在 Mac 上的實際掛載位置。

在 Finder 中打開「前往」→「電腦」就能看到硬碟名稱。如果你的行動硬碟名稱是「My Passport」，路徑就是 /Volumes/My Passport/mattermost_data。

最後一行掛載系統時間檔案，確保容器內的時間與主機同步。

資料庫連線設定

environment:
  - MM_SQLSETTINGS_DRIVERNAME=postgres
  - MM_SQLSETTINGS_DATASOURCE=postgres://mmuser:mmuser_password@db:5432/mattermost?sslmode=disable&connect_timeout=10

指定使用 PostgreSQL 資料庫，連線字串包含使用者名稱、密碼、主機名稱（db 就是前面定義的資料庫服務名稱）、Port 和資料庫名稱。在區域網路環境下，為了簡化設定，這裡停用了 SSL 加密。

網站網址設定

- MM_SERVICESETTINGS_SITEURL=http://localhost:8065

這是 Mattermost 對外的網址。如果你只在本機使用，就維持 http://localhost:8065。

如果要讓區域網路內其他裝置存取，可以設定為你電腦的區域網路 IP，例如 http://192.168.1.100:8065。

如果想用 Cloudflare Tunnel 進行內網穿透，可以設定為對外的網址，例如 https://mattermost.yourdomain.com。

外掛市集功能

- MM_PLUGINSETTINGS_ENABLEUPLOADS=true
- MM_PLUGINSETTINGS_ENABLEMARKETPLACE=true

開啟外掛上傳和市集功能，這樣才能安裝 Boards、Todo 等擴充功能。

預設情況下這些功能可能被關閉，需要明確啟用。

WebSocket 連線設定

- MM_SERVICESETTINGS_ALLOWCORSFROM=*
- MM_WEBSERVER_WEBSOCKETSECUREPORT=8065
- MM_SERVICESETTINGS_ENABLEINSECUREOUTGOINGCONNECTIONS=true

WebSocket 是實現即時訊息的關鍵技術，而且後續使用 Boards 看版功能時也需要。

ALLOWCORSFROM=* 允許所有來源的跨域請求，方便在不同裝置上存取。

ENABLEINSECUREOUTGOINGCONNECTIONS 允許 Mattermost 連接到沒有 HTTPS 的外部服務，這在測試環境中很實用。

推播通知設定

- MM_EMAILSETTINGS_SENDPUSHNOTIFICATIONS=true
- MM_EMAILSETTINGS_PUSHNOTIFICATIONSERVER=https://push-test.mattermost.com
- MM_EMAILSETTINGS_PUSHNOTIFICATIONCONTENTS=full

開啟推播通知功能，使用 Mattermost 官方提供的測試推播伺服器（TPNS）。這是免費服務，讓你的手機 App 能收到即時通知。

PUSHNOTIFICATIONCONTENTS=full 表示通知會顯示發訊者姓名和訊息內容；如果改成 generic 則只顯示「您有一則新訊息」。

日誌管理

- MM_LOGSETTINGS_FILEMAXAGEDAYS=30
- MM_LOGSETTINGS_FILECOMPRESS=true

logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "5"

Mattermost 內部的日誌檔案會保留 30 天，超過後自動壓縮舊檔案。

Docker 容器輸出的日誌則限制每個檔案最大 10MB，最多保留 5 個檔案，避免日誌無限膨脹佔用硬碟空間。

對外 Port

ports:
  - "8065:8065"

將容器內的 8065 Port 對應到主機的 8065 Port。

啟動後可以透過 http://localhost:8065 存取 Mattermost。

啟動服務

在 docker-compose.yml 所在目錄執行：

docker compose up -d

-d 參數表示在背景執行。第一次啟動會需要下載映像檔，可能需要幾分鐘時間。

啟動完成後，打開瀏覽器前往 http://localhost:8065，就會看到 Mattermost 的初始設定頁面。按照指示建立管理員帳號、設定團隊名稱，就能開始使用了。

停止服務

當不需要使用時，可以執行：

docker compose down

這會停止並移除容器，但所有資料都保留在 volumes 目錄中，下次啟動時會自動載入。

切換介面語言為繁體中文

預設安裝後，Mattermost 的介面是英文。如果想改成繁體中文，只需要簡單幾個步驟：

點擊畫面右上角的齒輪圖示（Settings）
在設定選單中找到「Display」（顯示設定）
往下捲動到底部，會看到「Language」（語言）選項
點擊「Edit」，從下拉選單中選擇「繁體中文（台灣）」
點擊「Save」儲存

介面會立即切換成繁體中文，所有選單、按鈕、提示訊息都會變成中文顯示。

安裝擴充功能

Mattermost 跟 LINE 很不同的地方，在於可以安裝另外的擴充功能。

以下介紹兩個實用的擴充功能。

Focalboard

Focalboard 是內建的看板工具，類似 Jira 或 Notion，可以用來管理專案任務、追蹤進度。

安裝步驟：

進到 Focalboard 的 GitHub Releases 頁面。
下載最新版本的檔案，因為 Docker 是 Linux，要選擇 mattermost-plugin-focalboard-vxxxx-linux-xxx.tar.gz 的檔案。
Mattermost 點擊左上角的 Mattermost Logo，選擇「System Console」（系統控制台）。
在左側選單找到「Plugins」（擴充程式）→「Plugin Management」（擴充程式管理）。
在上傳擴充程式中，點擊「選擇檔案」，接著選擇剛剛下載的檔案後，點擊「上傳」。
安裝完成後，左側選單會出現「Mattermost Boards」的選項，點擊進去，再啟用擴充程式功能。

使用 Boards：

回到主畫面，點擊左上角的 Mattermost Logo 會出現「Boards」圖示。點擊後可以建立新的看板。

選擇範本（如待辦清單、專案追蹤、內容行事曆等），或從空白看板開始。

看板支援卡片拖曳、自訂欄位、篩選排序等功能。

Todo

Todo 外掛可以讓你在對話中直接建立待辦事項，並在側邊欄追蹤所有未完成的任務。

安裝步驟：

安裝方式跟上面的 Boards 相同。

Todo 的 GitHub Releases。

使用 Todo：

在任何頻道或私訊中，右側會出現更多 Todo 的圖示（三個點 + 三條線）。

點擊後選擇「Add Todo」。

實用技巧：

你可以在任何頻道輸入 /todo add [任務內容] 快速建立待辦事項，不需要依附在特定訊息上。例如：

/todo add 下週一前完成專案提案

4 使用整合的機器人帳號

機器人帳號可以讓 Mattermost 與其他系統整合，執行像是自動化通知等的訊息發送。

建立機器人帳號

步驟：

進入「System Console」（系統控製台）→「Integrations」（整合）→「Bot Accounts」（機器人帳號）。
點擊「Add Bot Account」（新增機器人帳號）。
填寫機器人資訊：
- Username：例如 notification-bot
- Bot Icon：上傳機器人的頭像圖片（選用）
- Display Name：顯示名稱，例如「通知機器人」
- Description：說明這個機器人的用途
- Role：選擇「Member」即可
點擊「Create Bot Account」

建立完成後，頁面會顯示一個 Token（存取權杖）。請務必複製並妥善保存這個 Token，它只會顯示一次。如果遺失，需要重新產生新的 Token。

用 n8n 發送訊息

n8n 是一個開源的工作流程自動化工具，可以串接各種服務。

以下示範如何讓 n8n 透過機器人帳號發送訊息到 Mattermost。

前置作業：

首先需要在 Mattermost 建立一個接收訊息的頻道，例如「系統通知」。

在 n8n 中設定：

在 n8n 工作流程中新增「Mattermost」節點
建立 Credential（憑證）：
- Base URL：填入你的 Mattermost 網址，例如 http://localhost:8065。
- Access Token：貼上前面複製的機器人 Token。
設定要執行的動作：
- Operation：選擇「Post Message」。
- Channel ID：下拉式選單選取。
- Message：輸入要發送的訊息內容。

簡單的測試範例：

建立一個「Schedule Trigger」節點，設定每天早上 9 點執行，連接到 Mattermost 節點發送「早安！今天也要加油」的訊息。這樣就完成了一個簡單的每日問候機器人。

進階應用：

你可以組合更多節點，例如：

監控網站是否正常運作，異常時發送警告訊息
從 Google Sheets 讀取資料，定期發送報表摘要
串接 Webhook，當特定事件發生時自動通知團隊
整合 RSS 閱讀器，自動分享新文章到頻道

機器人帳號讓 Mattermost 不只是通訊軟體，還能執行自動化流程的訊息中心。

結語

透過 Docker Compose，我們可以在本機快速部署 Mattermost，擁有完整的團隊協作功能，同時保有資料的完全控制權。合理的儲存策略配置（本機設定、行動硬碟存檔）讓系統既快速又節省空間。

搭配 Boards 和 Todo 等外掛，以及機器人帳號的自動化整合，Mattermost 可以滿足從團隊溝通到專案管理的各種需求。

而且，以上這些功能都是免費且開源的，不用擔心訂閱費用或資料隱私問題。

最後，August 其實也還用不到一個月，但覺得好用，又能保有隱私，所以先寫了這篇筆記，紀錄一下安裝、使用的過程。

如果有更好的通訊軟體，歡迎留言提供。

DEV Community: Let's Write

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

本篇要解決的問題

lets-social

為什麼要用 lets-social？

支援平台

運作方式

安裝

Claude Code

Codex

其他支援 Agent Skills 的工具

版本與更新

Git 更新（建議）

使用 Skillshare 追蹤（選用）

使用範例

支援的來源

產圖 prompt

視覺風格依文章挑選

每份 prompt 都會包含的內容

圖中文字與字體規則

兩個模型的差別

自訂品牌語氣

只產生部分平台

專案結構

新增其他平台

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

本篇要解決的問題

安裝 Sentry MCP

讓 Claude 知道要抓取哪個專案

安裝 Gitea MCP

方式一：直接用 go run

方式二：下載官方執行檔

方式三：用 Docker

Claude Code 設定排程

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

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

本篇要解決的問題

建立 marketplace 專案結構

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

Host 到 Gitea

驗證

本機測試安裝

正式指向 Gitea

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

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

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

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

參考資料

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

本篇要解決的問題

Agency Agents 是什麼？

安裝 Agency Agents App

Windows

Mac

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

讓 Claude Code、Codex 自動選 Agent

Claude Code、Codex 建立 agency-agents Skill

Claude Code

Codex

Claude Code

Codex

讓 Claude Code 自動使用 Router

Codex 的 AGENTS.md

總結

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

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

本篇要解決的問題

安裝 Buzz Relay

1. 安裝必要工具

2. 下載 Buzz 原始碼

3. 建立 .env

4. 啟動 Buzz Relay

5. 測試 Relay

下載、安裝 Buzz

1. 下載 Buzz Desktop

2. 登入 Buzz

使用 AI Agents 功能

確認有使用 AI

確認 Community 網址相同

開放 Agents 接受回應

3. 建立 `.env`