實戰手冊 · Field Manual 2026 夏季號

github.com/Waishnav/devspace · 2.1k ★

第 01 期 · MCP Server / 本機開發

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

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

2.1k

GitHub Stars

MCP 工具

7676

本機預設埠

MIT

開源免費授權

這到底是什麼

讓 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 的能力,也是它最需要謹慎對待的地方。

DevSpace · 連線生命週期

init→ serve→ Tunnel→ ChatGPT 連接器→ Owner 密碼核可→ open_workspace

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

— DevSpace README,專案定位

安裝與啟動

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

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

# 全域安裝
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 執行:

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

init 會問你三件事。一、允許 ChatGPT 存取哪些專案資料夾(roots,例如 ~/work,~/personal);二、本機埠(預設 7676);三、你的公開 HTTPS base URL——來自 Cloudflare Tunnel、ngrok、Pinggy、Tailscale Funnel 或其他反向代理,填 origin 不要帶 /mcp。設定會寫到 ~/.devspace/config.json,Owner 密碼寫到 ~/.devspace/auth.json(請保密)。

8 個 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

檢視目錄

列出目錄內容、檢視專案結構。對應內部的 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://...`

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

少踩雷的
八條設定要點。

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

TIP 01

Node 版本鎖在 20.12–26

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

來源 · 官方 gotchas.md

TIP 02

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

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

來源 · 官方 setup.md

TIP 03

better-sqlite3 載入失敗就 rebuild

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

來源 · 官方 gotchas.md

TIP 04

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

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

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

TIP 05

遇到 403 / host header 錯誤先跑 doctor

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

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

TIP 06

roots 越窄越安全

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

來源 · 官方 security.md

TIP 07

平行工作用 worktree 模式

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

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

TIP 08

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

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

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

實戰流程

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

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

~/work · devspace · ChatGPT 連接器

# 1 · 本機啟動 DevSpace $ devspace serve 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 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 失敗,幫我找出來。

ChatGPT › → open_workspace { path: "~/work/api-server" } workspaceId: ws_8fa2 · 已讀取 AGENTS.md → bash { cmd: "npm test" } 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" } PASS test/user.test.ts · 全數通過(12 passed)

ChatGPT › 已修好並通過測試。要我用 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 像一個有本機權限的協作者一樣工作。

先看清楚這些

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

shell 等於你的帳號權限。檔案類工具受路徑邊界限制,但 bash 是以你的使用者身分執行,能做你帳號能做的任何事。官方明說:把連上的 client 當成「擁有你機器存取權的可信協作者」對待。連線前先確認你信任它。
roots 不要設太寬。避免用 ~、/ 或 C:\ 當 root。設成 ~/work 或 ~/personal/open-source 這類窄範圍,才容易推斷對方能碰到什麼。
Owner 密碼與 auth.json 要保密。密碼存在 ~/.devspace/auth.json,是核可連線的唯一關卡。部署情境可用 DEVSPACE_OAUTH_OWNER_TOKEN="$(openssl rand -base64 32)" 設一組高強度權杖。
通道最好再加一層保護。只靠 Owner 密碼不夠;官方建議在通道前再疊 Cloudflare Access 或 Tailscale 之類的存取控制,縮小公開面。
不要隨便開 shell 指令日誌。指令預覽預設關閉,DEVSPACE_LOG_SHELL_COMMANDS=1 才會記錄。若指令含密鑰,開啟會把祕密寫進日誌,請勿開啟。
Windows 只支援 Bash 環境。shell 執行需要 Bash 相容 shell,PowerShell 與 cmd.exe 尚未支援。請用 Git Bash、WSL、MSYS2 或 Cygwin,並以 devspace doctor 驗證。
worktree 模式有前提。需是 Git repo、路徑在版控內、至少一個 commit、有效的 baseRef;未提交的變更不會複製到 worktree。要嘛先 commit,要嘛改用 checkout 模式。
workspaceId 是 session 識別碼。server 重啟後舊的 workspaceId 會失效,出現 unknown workspace 時請重新呼叫 open_workspace。它仍是早期專案(2026 年 6 月建立),連線細節持續演進,以官方 docs 為準。

進階路徑

把 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