Communitygithub.com

ALT-F1-OpenClaw/openclaw-skill-openproject

OpenProject CRUD 技能——透過 OpenProject API v3 並使用 API Token 認證,管理工作套件、專案、群組、新聞、使用者、觀察者、關聯、通知、時間記錄、評論、附件、Wiki 頁面、狀態等。支援雲端與自託管實例。

openclaw-skill-openproject 是什麼?

這是一個專為 AI Agent(如 Claude Code、Cursor、Codex)設計的 OpenProject 技能,提供完整的 CRUD 操作能力。它透過 OpenProject API v3 與 API Token 認證,讓開發者能夠以命令列形式管理 OpenProject 中的多種資源,包括工作套件、專案、群組、新聞、使用者、觀察者、關聯、通知、時間記錄、評論、附件、Wiki 頁面、狀態與轉換等。支援雲端與自託管實例,並內建速率限制與指數退避重試機制,確保穩定性與安全性。此技能透過 Node.js 腳本執行,依賴 commander 與 dotenv 套件,適用於 Node >= 18 的環境。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add ALT-F1-OpenClaw/openclaw-skill-openproject

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

由 @altf1be 提供的 OpenProject

透過 API v3 管理 OpenProject 工作套件、專案、群組、新聞、使用者、觀察者、關聯、通知、時間記錄、評論、附件、Wiki 頁面與工作流程轉換。適用於雲端與自託管實例。

設定

  1. 登入你的 OpenProject 實例
  2. 前往 我的帳號 → 存取權杖 → + 新增
  3. 建立 API 權杖並複製
  4. 設定環境變數(或在 {baseDir} 中建立 .env):
OP_HOST=https://projects.xflowdata.com
OP_API_TOKEN=your-api-token
OP_DEFAULT_PROJECT=my-project
  1. 安裝相依套件:cd {baseDir} && npm install

指令

工作套件

# 列出工作套件(可選篩選條件)
node {baseDir}/scripts/openproject.mjs wp-list --project my-project --status open --assignee me

# 建立工作套件
node {baseDir}/scripts/openproject.mjs wp-create --project my-project --type Task --subject "修復登入錯誤" --description "使用者無法登入"

# 讀取工作套件詳細資訊
node {baseDir}/scripts/openproject.mjs wp-read --id 42

# 更新工作套件
node {baseDir}/scripts/openproject.mjs wp-update --id 42 --subject "新標題" --priority High

# 刪除工作套件(需要 --confirm)
node {baseDir}/scripts/openproject.mjs wp-delete --id 42 --confirm

專案

# 列出所有專案
node {baseDir}/scripts/openproject.mjs project-list

# 讀取專案詳細資訊
node {baseDir}/scripts/openproject.mjs project-read --id my-project

# 建立專案
node {baseDir}/scripts/openproject.mjs project-create --name "我的專案" --identifier my-project

評論(活動)

# 列出工作套件的評論
node {baseDir}/scripts/openproject.mjs comment-list --wp-id 42

# 新增評論
node {baseDir}/scripts/openproject.mjs comment-add --wp-id 42 --body "準備好進行審查"

附件

# 列出工作套件的附件
node {baseDir}/scripts/openproject.mjs attachment-list --wp-id 42

# 上傳附件
node {baseDir}/scripts/openproject.mjs attachment-add --wp-id 42 --file ./screenshot.png

# 刪除附件(需要 --confirm)
node {baseDir}/scripts/openproject.mjs attachment-delete --id 10 --confirm

時間記錄

# 列出時間記錄
node {baseDir}/scripts/openproject.mjs time-list --project my-project

# 記錄工時
node {baseDir}/scripts/openproject.mjs time-create --wp-id 42 --hours 2.5 --comment "程式碼審查" --activity-id 1

# 更新時間記錄
node {baseDir}/scripts/openproject.mjs time-update --id 5 --hours 3 --comment "已更新"

# 刪除時間記錄(需要 --confirm)
node {baseDir}/scripts/openproject.mjs time-delete --id 5 --confirm

狀態與轉換

# 列出所有狀態
node {baseDir}/scripts/openproject.mjs status-list

# 更新工作套件狀態
node {baseDir}/scripts/openproject.mjs wp-update --id 42 --status "進行中"

使用者

# 列出所有使用者(可選篩選條件)
node {baseDir}/scripts/openproject.mjs user-list
node {baseDir}/scripts/openproject.mjs user-list --status active --name "John"

# 讀取使用者詳細資訊
node {baseDir}/scripts/openproject.mjs user-read --id 5

# 顯示目前已認證的使用者
node {baseDir}/scripts/openproject.mjs user-me

通知

# 列出通知(全部或僅未讀)
node {baseDir}/scripts/openproject.mjs notification-list
node {baseDir}/scripts/openproject.mjs notification-list --unread
node {baseDir}/scripts/openproject.mjs notification-list --reason mentioned --project 5

# 讀取通知詳細資訊
node {baseDir}/scripts/openproject.mjs notification-read --id 100

# 標記為已讀(單一或全部)
node {baseDir}/scripts/openproject.mjs notification-mark-read --id 100
node {baseDir}/scripts/openproject.mjs notification-mark-read --all
node {baseDir}/scripts/openproject.mjs notification-mark-read --all --project 5

# 標記為未讀
node {baseDir}/scripts/openproject.mjs notification-mark-unread --id 100
node {baseDir}/scripts/openproject.mjs notification-mark-unread --all

文件

node {baseDir}/scripts/openproject.mjs document-list
node {baseDir}/scripts/openproject.mjs document-read --id 5
node {baseDir}/scripts/openproject.mjs document-update --id 5 --title "已更新標題"

修訂

node {baseDir}/scripts/openproject.mjs revision-read --id 10
node {baseDir}/scripts/openproject.mjs revision-list-by-wp --wp-id 42

能力與動作

node {baseDir}/scripts/openproject.mjs capability-list --principal me
node {baseDir}/scripts/openproject.mjs capability-global
node {baseDir}/scripts/openproject.mjs action-list
node {baseDir}/scripts/openproject.mjs action-read --id work_packages/create

我的偏好設定

node {baseDir}/scripts/openproject.mjs my-preferences-read
node {baseDir}/scripts/openproject.mjs my-preferences-update --time-zone "Europe/Brussels" --comment-order desc

渲染

node {baseDir}/scripts/openproject.mjs render-markdown --text "**粗體** 和 *斜體*"
node {baseDir}/scripts/openproject.mjs render-plain --text "純文字"

文章(論壇)

node {baseDir}/scripts/openproject.mjs post-read --id 5
node {baseDir}/scripts/openproject.mjs post-attachment-list --id 5

提醒

node {baseDir}/scripts/openproject.mjs reminder-list
node {baseDir}/scripts/openproject.mjs reminder-create --wp-id 42 --remind-at "2026-03-20T09:00:00Z" --note "檢查狀態"
node {baseDir}/scripts/openproject.mjs reminder-update --id 3 --remind-at "2026-03-21T09:00:00Z"
node {baseDir}/scripts/openproject.mjs reminder-delete --id 3 --confirm

專案狀態

node {baseDir}/scripts/openproject.mjs project-status-read --id on_track

專案階段(企業版)

# 列出專案階段定義
node {baseDir}/scripts/openproject.mjs project-phase-definition-list

# 讀取階段定義
node {baseDir}/scripts/openproject.mjs project-phase-definition-read --id 1

# 讀取專案階段
node {baseDir}/scripts/openproject.mjs project-phase-read --id 5

投資組合(企業版)

# 列出投資組合
node {baseDir}/scripts/openproject.mjs portfolio-list

# 讀取投資組合
node {baseDir}/scripts/openproject.mjs portfolio-read --id 1

# 更新投資組合
node {baseDir}/scripts/openproject.mjs portfolio-update --id 1 --name "Q1 投資組合"

# 刪除投資組合(需要 --confirm)
node {baseDir}/scripts/openproject.mjs portfolio-delete --id 1 --confirm

方案(企業版)

# 列出方案
node {baseDir}/scripts/openproject.mjs program-list

# 讀取方案
node {baseDir}/scripts/openproject.mjs program-read --id 1

# 更新方案
node {baseDir}/scripts/openproject.mjs program-update --id 1 --name "平台方案"

# 刪除方案(需要 --confirm)
node {baseDir}/scripts/openproject.mjs program-delete --id 1 --confirm

佔位使用者(企業版)

# 列出佔位使用者
node {baseDir}/scripts/openproject.mjs placeholder-user-list

# 讀取佔位使用者
node {baseDir}/scripts/openproject.mjs placeholder-user-read --id 10

# 建立佔位使用者
node {baseDir}/scripts/openproject.mjs placeholder-user-create --name "未來開發者"

# 更新佔位使用者
node {baseDir}/scripts/openproject.mjs placeholder-user-update --id 10 --name "資深開發者"

# 刪除佔位使用者(需要 --confirm)
node {baseDir}/scripts/openproject.mjs placeholder-user-delete --id 10 --confirm

預算(企業版)

# 列出專案預算
node {baseDir}/scripts/openproject.mjs budget-list --project my-project

# 讀取預算詳細資訊
node {baseDir}/scripts/openproject.mjs budget-read --id 3

會議(企業版)

# 讀取會議
node {baseDir}/scripts/openproject.mjs meeting-read --id 10

# 列出會議附件
node {baseDir}/scripts/openproject.mjs meeting-attachment-list --id 10

# 上傳附件到會議
node {baseDir}/scripts/openproject.mjs meeting-attachment-add --id 10 --file ./agenda.pdf

工作日(工作日/非工作日)

# 檢查日期是否為工作日
node {baseDir}/scripts/openproject.mjs day-read --date 2026-03-18

# 列出某範圍內的天數
node {baseDir}/scripts/openproject.mjs days-list --from 2026-03-01 --to 2026-03-31

# 列出所有非工作日(假期)
node {baseDir}/scripts/openproject.mjs non-working-days-list

# 查看特定非工作日
node {baseDir}/scripts/openproject.mjs non-working-day-read --date 2026-12-25

# 顯示週間排程(哪些天是工作日)
node {baseDir}/scripts/openproject.mjs week-days-list

# 查看特定週間
node {baseDir}/scripts/openproject.mjs week-day-read --day 6

設定

# 查看實例設定
node {baseDir}/scripts/openproject.mjs config-read

# 查看專案特定設定
node {baseDir}/scripts/openproject.mjs project-config-read --project my-project

OAuth

# 讀取 OAuth 應用程式
node {baseDir}/scripts/openproject.mjs oauth-app-read --id 1

# 讀取 OAuth 用戶端憑證
node {baseDir}/scripts/openproject.mjs oauth-credentials-read --id 1

說明文字

# 列出所有屬性說明文字
node {baseDir}/scripts/openproject.mjs help-text-list

# 讀取說明文字
node {baseDir}/scripts/openproject.mjs help-text-read --id 1

自訂欄位與選項

# 列出階層式自訂欄位的項目
node {baseDir}/scripts/openproject.mjs custom-field-items --id 10

# 讀取自訂欄位項目
node {baseDir}/scripts/openproject.mjs custom-field-item-read --id 25

# 取得自訂欄位項目的分支(上層)
node {baseDir}/scripts/openproject.mjs custom-field-item-branch --id 25

# 讀取自訂選項值
node {baseDir}/scripts/openproject.mjs custom-option-read --id 3

自訂動作

# 讀取自訂動作
node {baseDir}/scripts/openproject.mjs custom-action-read --id 1

# 在工作套件上執行自訂動作
node {baseDir}/scripts/openproject.mjs custom-action-execute --id 1 --wp-id 42

群組

# 列出所有群組
node {baseDir}/scripts/openproject.mjs group-list

# 讀取群組詳細資訊(含成員)
node {baseDir}/scripts/openproject.mjs group-read --id 3

# 建立群組(含成員)
node {baseDir}/scripts/openproject.mjs group-create --name "開發團隊" --members 5,6,7

# 更新群組(取代成員列表)
node {baseDir}/scripts/openproject.mjs group-update --id 3 --name "工程部門" --members 5,6,7,8

# 刪除群組(需要 --confirm)
node {baseDir}/scripts/openproject.mjs group-delete --id 3 --confirm

新聞

# 列出所有新聞
node {baseDir}/scripts/openproject.mjs news-list

# 讀取新聞詳細資訊
node {baseDir}/scripts/openproject.mjs news-read --id 5

# 建立新聞項目
node {baseDir}/scripts/openproject.mjs news-create --project my-project --title "Sprint 12 已發布" --summary "錯誤修復與效能最佳化" --description "此處提供完整詳細資訊..."

# 更新新聞項目
node {baseDir}/scripts/openproject.mjs news-update --id 5 --title "已更新標題"

# 刪除新聞項目(需要 --confirm)
node {baseDir}/scripts/openproject.mjs news-delete --id 5 --confirm

觀察者

# 列出工作套件的觀察者
node {baseDir}/scripts/openproject.mjs watcher-list --wp-id 42

# 新增觀察者
node {baseDir}/scripts/openproject.mjs watcher-add --wp-id 42 --user-id 5

# 移除觀察者
node {baseDir}/scripts/openproject.mjs watcher-remove --wp-id 42 --user-id 5

# 列出可作為觀察者的使用者
node {baseDir}/scripts/openproject.mjs watcher-available --wp-id 42

關聯

# 列出所有關聯(可依工作套件或類型篩選)
node {baseDir}/scripts/openproject.mjs relation-list --wp-id 42
node {baseDir}/scripts/openproject.mjs relation-list --type blocks

# 讀取關聯詳細資訊
node {baseDir}/scripts/openproject.mjs relation-read --id 5

# 建立關聯(類型:relates、duplicates、blocks、precedes、follows、includes、partof、requires)
node {baseDir}/scripts/openproject.mjs relation-create --wp-id 42 --to-wp-id 43 --type blocks
node {baseDir}/scripts/openproject.mjs relation-create --wp-id 42 --to-wp-id 43 --type precedes --lag 2

# 更新關聯
node {baseDir}/scripts/openproject.mjs relation-update --id 5 --type follows --lag 1

# 刪除關聯(需要 --confirm)
node {baseDir}/scripts/openproject.mjs relation-delete --id 5 --confirm

Wiki 頁面

# 讀取 Wiki 頁面
node {baseDir}/scripts/openproject.mjs wiki-read --id 72

# 列出 Wiki 頁面的附件
node {baseDir}/scripts/openproject.mjs wiki-attachment-list --id 72

# 上傳附件到 Wiki 頁面
node {baseDir}/scripts/openproject.mjs wiki-attachment-add --id 72 --file ./diagram.png

參考資料

# 列出工作套件類型
node {baseDir}/scripts/openproject.mjs type-list

# 列出優先級
node {baseDir}/scripts/openproject.mjs priority-list

# 列出專案成員
node {baseDir}/scripts/openproject.mjs member-list --project my-project

# 列出版本/里程碑
node {baseDir}/scripts/openproject.mjs version-list --project my-project

# 列出類別
node {baseDir}/scripts/openproject.mjs category-list --project my-project

安全性

  • API Token 認證(基本認證,使用者名稱為 apikey)
  • 機密或權杖不會輸出到 stdout
  • 所有刪除操作都需要明確的 --confirm 標誌
  • 防止路徑遍歷攻擊的檔案上傳保護
  • 內建速率限制與指數退避重試機制
  • 懶載入配置驗證(僅在指令執行時檢查)

相依套件

  • commander — CLI 框架
  • dotenv — 環境變數載入
  • Node.js 內建 fetch(需要 Node >= 18)

作者

Abdelkrim BOUJRAF — ALT-F1 SRL,布魯塞爾 🇧🇪 🇲🇦 X:@altf1be

相關技能