使用手冊

第 01 期 · MCP Server / 本機開發

把 ChatGPT, 變成連到本機的 Codex。

DevSpace 是自架的 MCP server,讓 ChatGPT 透過你自己控制的通道讀寫、執行本機專案程式碼,檔案不上傳第三方。本手冊涵蓋安裝、ChatGPT 連接器設定、MCP 工具總覽、安全模型與實戰流程。

DevSpace 是一個自架的 MCP server。它讓 ChatGPT 透過你自己架設、自己控制的 HTTPS 通道,讀寫、搜尋、執行本機專案的程式碼——檔案不上傳到任何第三方。本手冊涵蓋一行 npm 安裝、ChatGPT 連接器設定、八個 MCP 工具、安全模型,以及一段完整的本機編碼流程。

waishnav/devspace
星標
—
分支
—
授權
—
資料截至
—
閱讀時間
9 分
更新日期
開啟原始報告
GitHub Stars
2.1k
MCP 工具
8
本機預設埠
7676
開源免費授權
MIT
本頁章節

01這到底是什麼

讓 ChatGPT 連到你自己的機器。

DevSpace 是一個 MCP(Model Context Protocol)server,用 TypeScript 寫成,以 npm 套件 @waishnav/devspace 發布。它解決一個具體問題:ChatGPT 本身碰不到你本機的開發環境。DevSpace 在你的機器上開一個本機服務(預設 http://127.0.0.1:7676),你再用自己控制的 HTTPS 通道把它接給 ChatGPT,讓 ChatGPT 能直接操作本機專案,而檔案不會上傳到第三方。

連上之後,ChatGPT 可以讀寫與編輯檔案、搜尋程式碼、檢視目錄、執行 shell 指令(測試、建置、git、套件腳本),也能用隔離的 Git worktree 跑平行工作階段。它會讀取專案根目錄的 AGENTS.md 與 CLAUDE.md 作為指示,並自動探索你 skill 資料夾裡的本機 skill。專案描述一句話總結了定位:把 ChatGPT 變成 Codex,同時把 ChatGPT 的用量分開使用。

關鍵在於主控權在你手上。你決定哪些資料夾(roots)可被存取、通道由你架設、Owner 密碼存在本機 ~/.devspace/auth.json。檔案類工具受路徑邊界限制,但 shell 指令是以你的使用者權限執行——這既是 DevSpace 的能力,也是它最需要謹慎對待的地方。

  1. init

  2. serve

  3. Tunnel

  4. ChatGPT 連接器

  5. Owner 密碼核可

  6. open_workspace

你的檔案、你的工具、你的終端機,不上傳到任何第三方。你在自己的機器上執行它,透過你控制的通道對外開放。

— DevSpace README,專案定位

02安裝與啟動

一行 npm 安裝, 三個指令上線。

環境需求:Node.js >=20.12 <27(官方建議 Node 22 LTS)、npm、Git,以及 Bash 相容的 shell。全域安裝後,只需要 init 設定、serve 啟動、doctor 檢查三個指令。

bash
# 全域安裝
npm install -g @waishnav/devspace

# 互動式設定:選擇可存取的資料夾、本機埠、公開 HTTPS URL
devspace init

# 啟動 MCP server(預設 http://127.0.0.1:7676/mcp)
devspace serve

# 檢查本機環境是否相容
devspace doctor

不想全域安裝:用 npx

若不想全域安裝,或 devspace 指令在 PATH 上找不到,所有指令都能直接用 npx 執行:

bash
npx @waishnav/devspace init
npx @waishnav/devspace serve
npx @waishnav/devspace doctor

038 個 MCP 工具

ChatGPT 透過這些工具操作你的程式碼。

DevSpace 把本機開發拆成八個 MCP 工具,ChatGPT 以明確的工具呼叫使用它們。一切從 open_workspace 開始:它回傳一個 workspaceId,後續所有操作都要重用這個 ID。檔案類工具(read / edit / write)受路徑邊界限制,只能碰你在 init 時允許的 roots;bash 則是真正的 shell 執行。官方建議檔案寫入走 edit / write 工具,而不要用 shell 的 sed -i、heredoc、tee 等重導向。

Session · 01

open_workspace

開啟工作區

指定一個本機專案路徑或 worktree,回傳 workspaceId。每個專案呼叫一次,後續工具都重用這個 ID。會載入根目錄的 AGENTS.md / CLAUDE.md。

File · 02

read

讀取檔案

讀取工作區內的檔案內容。巢狀的指示檔會以 availableAgentsFiles 回傳,提示先讀再動該目錄。

File · 03

edit

局部編輯

對檔案做有範圍的精確修改。官方指引:檔案寫入走 edit/write,而非 shell 的 sed -i、heredoc 或重導向。

File · 04

write

寫入檔案

建立或覆寫整份檔案。與 edit 同受路徑邊界限制,只能寫入 init 時允許的 roots 之內。

Search · 05

ls

檢視目錄

列出目錄內容、檢視專案結構。對應內部的 list_directory,協助 ChatGPT 在編輯前先理解版面。

Search · 06

find

尋找檔案

依檔名或樣式定位檔案(內部 find_files)。在大型 repo 裡快速縮小要讀取的範圍。

Search · 07

grep

搜尋程式碼

在工作區內搜尋字串或樣式(內部 grep_files),用來定位符號、用法與跨檔關聯。

Exec · 08

bash

執行 Shell

跑測試、建置、git、套件腳本。以你的使用者權限執行——能力最強,也最需要謹慎。需要 Bash 相容 shell。

四種公開通道:選一個架 HTTPS

DevSpace 只在本機 127.0.0.1:7676 監聽,對外要靠你自己架的反向代理。官方文件列出四種選擇,設定時填入的都是 origin(不帶 /mcp),在 ChatGPT 連接器才補上 /mcp。

通道服務特性適用情境
Cloudflare Tunnel可搭配 Cloudflare Access 加一層存取控制長期、穩定網域
Tailscale Funnel建立在自有 tailnet 之上,網域穩定已用 Tailscale 的個人/團隊
ngrok / Pinggy啟動最快;臨時網址常每次變動快速試用、臨時連線
網址會變動時用 DEVSPACE_PUBLIC_BASE_URL 環境變數覆寫,或 devspace config set publicBaseUrl https://...

04設定與使用要點 · 官方文件

少踩雷的八條設定要點。

以下整理自 DevSpace 官方的 setup.md、security.md 與 gotchas.md。多數連線失敗都集中在幾個重複出現的點:Node 版本、原生相依、公開網址格式、host header 允許清單。先看過這幾條,可以省下大半的除錯時間。

Node 版本鎖在 20.12–26

DevSpace 要求 Node >=20.12 <27,官方建議 Node 22 LTS。版本不對會直接啟動失敗。用 nvm、fnm 或 mise 切到 22 LTS 最省事。

來源 · 官方 gotchas.md

公開網址填 origin,不要帶 /mcp

init 設定時填 https://your-tunnel.example.com(origin),ChatGPT 連接器才補上 /mcp。帶錯路徑是最常見的連線失敗原因。

來源 · 官方 setup.md

better-sqlite3 載入失敗就 rebuild

原生相依若在不同 Node runtime 下安裝會載不起來。執行 npm rebuild better-sqlite3,再跑 devspace doctor 確認。

來源 · 官方 gotchas.md

臨時通道網址會變,用環境變數覆寫

ngrok / Pinggy 的臨時網址每次重啟常不同。不必改設定檔,直接 DEVSPACE_PUBLIC_BASE_URL="https://new.example.com" devspace serve 即可。

來源 · 官方 setup.md / gotchas.md

遇到 403 / host header 錯誤先跑 doctor

DevSpace 從公開 URL 推導允許的 host。出現 403 時用 devspace doctor 核對 hostname;DEVSPACE_ALLOWED_HOSTS="*" 只用於本機除錯,不要長期開。

來源 · 官方 gotchas.md / security.md

roots 越窄越安全

官方建議把允許的資料夾設窄,例如 ~/work 或 ~/personal/open-source,避免用 ~、/ 或 C:\。root 越窄,越容易推斷對方能碰到什麼。

來源 · 官方 security.md

平行工作用 worktree 模式

在 open_workspace 帶 "mode": "worktree" 可做隔離的平行開發,建在 ~/.devspace/worktrees。需要是 Git repo 且至少有一個 commit;未提交的變更不會被複製過去。

來源 · 官方 chatgpt-coding-workflow.md

檔案寫入走工具,別用 shell 重導向

官方明確要求:檔案修改走 edit / write 工具,不要用 sed -i、heredoc、tee 或生成腳本。shell 留給真正屬於終端機的指令(測試、建置、git)。

來源 · 官方 chatgpt-coding-workflow.md

05實戰流程

從 serve 到讓 ChatGPT 改完你的本機程式碼。

以下示範一段完整流程:本機啟動 DevSpace、用 Cloudflare Tunnel 開公開網址、在 ChatGPT 連接器貼上 /mcp 端點並用 Owner 密碼核可,接著請 ChatGPT 開啟工作區、定位 bug、用 edit 修好、跑 bash 測試驗證。指令與工具名稱皆取自官方文件。

~/work · devspace · ChatGPT 連接器


# 1 · 本機啟動 DevSpace
$ devspace serve
  ok: DevSpace MCP listening on http://127.0.0.1:7676/mcp
  # roots: ~/work  ·  owner password: ~/.devspace/auth.json


# 2 · 另開一個終端,架公開 HTTPS 通道(指向本機埠)
$ cloudflared tunnel --url http://127.0.0.1:7676
  hl: https://devspace-demo.trycloudflare.com


# 3 · ChatGPT 連接器填端點(origin + /mcp),按 Owner 密碼核可
  # Connector URL → https://devspace-demo.trycloudflare.com/mcp
# [Owner password approval page] → 輸入 auth.json 的密碼 ✓ 已連線


# 4 · 在 ChatGPT 裡,請它開啟工作區
$ You ›
  開啟 ~/work/api-server,測試一直在 user serializer 失敗,幫我找出來。


claude: ChatGPT ›
  # → open_workspace { path: "~/work/api-server" }
    # workspaceId: ws_8fa2 · 已讀取 AGENTS.md
  # → bash { cmd: "npm test" }
    hl: FAIL  test/user.test.ts · serialize() drops the email field


  # → grep { pattern: "serialize", path: "src/" }
  # → read { path: "src/user.ts" }
  找到了:serialize() 的回傳物件漏了 email 欄位,
  而測試預期它要存在。我用 edit 補上。


  # → edit { path: "src/user.ts", ... }
    # + email: this.email,


# 5 · 重跑測試驗證(都在你本機,檔案沒上傳)
  # → bash { cmd: "npm test" }
    ok: PASS  test/user.test.ts · 全數通過(12 passed)


claude: ChatGPT ›
  ok: 已修好並通過測試。要我用 bash 跑 git commit,還是你先 review diff?

ChatGPT 跑了 open_workspace、bash、grep、read、edit,全部發生在你本機。原始碼沒有離開過你的機器。

— DevSpace 的核心承諾:能力給 AI,檔案留本機

這段流程為什麼成立

ChatGPT 能改你本機的程式碼,靠的不是檔案上傳,而是它對 DevSpace 發出明確的 MCP 工具呼叫,DevSpace 在你機器上代為執行。read / edit / write 受路徑邊界限制,只能碰你允許的 roots;真正執行測試的 bash 則以你的使用者權限運作。資料流向是反過來的:不是你把程式碼送進雲端,而是你把一條受控的通道借給 ChatGPT。

這也是為什麼安全模型值得花時間設定:shell 能做的事等同你的帳號能做的事。把 roots 設窄、通道加一層存取控制,你才能放心讓 ChatGPT 像一個有本機權限的協作者一樣工作。

06先看清楚這些

能力很強, 先弄懂邊界再連線。

07進階路徑

把 DevSpace 調成你的工作流。

DevSpace 是 TypeScript 開源專案(MIT 授權),原始碼公開可讀。基本連線跑通之後,有幾個方向能把它接進更完整的開發流程。

進階設定地圖

**1. 用 AGENTS.md / CLAUDE.md 給專案指示。**把編碼規範、命名慣例、測試方式寫進專案根目錄的 AGENTS.md 或 CLAUDE.md。open_workspace 會載入它們;巢狀目錄的指示檔會以 availableAgentsFiles 回傳,提示模型先讀再動。

**2. 探索本機 skills。**skills 預設啟用,可用 DEVSPACE_SKILLS=1 devspace serve 明確開啟。模型會先讀你 skill 資料夾裡的 SKILL.md 再使用該 skill。

**3. 在支援的 host 顯示變更卡片。**在 ChatGPT Apps 相容的 host 上,DevSpace 能顯示工具卡與變更摘要。預設 DEVSPACE_WIDGETS=full,改 changes 只顯示彙總;純 MCP client 會忽略 widget 中繼資料。

**4. 用環境變數管理多通道。**網址會變時用 DEVSPACE_PUBLIC_BASE_URL 覆寫;OAuth 重導 host 預設只允許 chatgpt.com、localhost、127.0.0.1,需要時用 DEVSPACE_OAUTH_ALLOWED_REDIRECT_HOSTS 調整。

**5. 用 doctor 當第一道排查。**幾乎所有連線、host、Node、原生相依問題,devspace doctor 都會先點出來。遇到問題先跑它,再對照 gotchas.md。

最該讀的三份官方文件

① docs/setup.md——完整安裝、通道與連接器設定步驟。 ② docs/security.md——權限、roots、host 允許清單與資料流的安全模型。 ③ docs/gotchas.md——14 條最常見的錯誤與對應修法。

把 ChatGPT 變成 Codex,同時把 ChatGPT 的用量分開使用。你的檔案、你的工具、你的終端機,留在你自己的機器上。

— DevSpace · Waishnav,專案 README