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

本篇要解決的問題

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

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

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

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

前置準備

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

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

建立 Outline API Token

進入喜好設定

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

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

開啟 API & Access

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

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

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

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

原始流程中的設定為：

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

設定 API 金鑰範圍與到期日

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

複製 API Token

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

複製 Outline API Token

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

設定 Codex MCP

開啟 Codex 設定檔

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

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

Windows

開啟 PowerShell，執行：

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

這三個指令會依序：

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

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

%USERPROFILE%.codex

接著開啟 config.toml。

macOS：使用 Finder 開啟

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

~/.codex/

1. 找到並開啟：

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 憑證時的簡化設定

如果 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 Filesnodejsnpx.cmd

可以將：

command = "npx"

改成 TOML 的單引號字串：

command = 'C:Program Filesnodejsnpx.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 會：

1. 讀取 ~/.codex/config.toml
2. 透過 npx 啟動 mcp-remote
3. 使用 Authorization Header 連接 Outline MCP Server
4. 載入 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 資訊。

Summary