---
title: "讓 Codex 能呼叫你的命令列工具"
description: "把重複訪問 API、日誌、資料庫或團隊指令碼的動作封裝成 agent-friendly CLI，並配套 skill 固化呼叫方法。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

當 Codex 總要訪問同一個 API、日誌來源、匯出檔案、本地資料庫或團隊指令碼時，不要每次把說明粘進 prompt。更穩的做法是做一個 agent-friendly CLI，讓它能搜尋、讀取、下載、匯出，並保持預設輸出足夠小。

> [!TIP]
> CLI 負責把外部系統變成穩定命令；skill 負責告訴 Codex 什麼時候用這個 CLI、怎麼縮小輸出、哪些寫操作必須先確認。

<Cards>
  <Card title="Agent-friendly CLIs" href="https://developers.openai.com/codex/use-cases/agent-friendly-clis">
    檢視 OpenAI 對 Codex 可呼叫 CLI 的官方建議。
  </Card>
  <Card title="Skills" href="/zh-Hant/docs/codex/official/03-extensions/09-skills-reuse">
    把 CLI 呼叫方法沉澱成可複用 skill。
  </Card>
  <Card title="MCP tools" href="/zh-Hant/docs/codex/understanding/mcp-tools-guide">
    對比 CLI、MCP、browser 和 skill 的職責。
  </Card>
</Cards>

## 什麼時候該做 CLI

適合：

- CI 日誌在構建頁面後面，需要按 build URL 下載。
- API 響應很大，需要搜尋和按 ID 讀取。
- 客服工單、Slack 匯出、日誌包需要索引。
- 團隊指令碼太大，需要拆成可組合命令。
- Codex 需要把附件、trace、report、video、log bundle 下載到檔案。

不適合：

- 一次性任務。
- 只需要讀本地 repo。
- 還沒想清楚認證和許可權。
- 寫操作不可審查。

## 判斷標準

一個動作重複出現三次以上，就應該考慮 CLI。判斷時不要先問“能不能寫指令碼”，先問這四件事：

- Codex 是否經常需要從同一個外部系統取資料。
- 這個系統是否有穩定 ID、分頁、搜尋、下載或匯出概念。
- 預設輸出能否控制在小範圍內，完整資料能否寫到檔案。
- 寫操作是否能拆成 `draft` 和 `submit` 兩步。

只要其中三項成立，CLI 通常比把長說明塞進 prompt 更穩。CLI 讓外部系統有了穩定命令面，skill 再把呼叫時機和禁區告訴 Codex。

## 命令面應該小而可組合

```mermaid
flowchart LR
    Setup["setup-check"] --> Search["search"]
    Search --> Read["read --id"]
    Read --> Download["download --out"]
    Read --> Draft["draft"]
    Draft --> Submit["submit"]
```

推薦把動作拆開：

- `setup-check`：檢查認證和環境。
- `search`：小結果搜尋。
- `read`：按穩定 ID 讀取單條。
- `download`：把大內容匯出到檔案。
- `draft`：準備寫入內容。
- `submit`：真正寫入，需要明確確認。

不要把搜尋、下載、寫入都塞進一個大命令。動作越小，Codex 越容易保持邊界。

## 推薦 command surface

```text
team-tool setup-check
team-tool search --query "..." --limit 10
team-tool read --id "..."
team-tool download --id "..." --out ./logs
team-tool draft --id "..." --message-file ./draft.md
team-tool submit --draft-id "..." --confirm
```

設計重點：

- `setup-check` 先失敗清楚，避免任務中途才發現缺 token。
- `search` 只返回摘要和穩定 ID，不返回整段大 JSON。
- `read` 按 ID 取精確物件，適合放進上下文。
- `download` 把大附件、日誌、trace 寫入檔案，再返回路徑。
- `draft` 生成可審查內容。
- `submit` 是唯一 live write，必須顯式確認。

## 給 Codex 的構建提示詞

```text
请创建一个 Codex 可以调用的 CLI，并配套创建一个 skill。

材料：
{文档 URL / OpenAPI spec / 已脱敏 curl / 现有脚本 / 日志目录 / CSV / JSON / SQLite}

第一版只支持：
{只读搜索、按 ID 读取、下载日志到 ./logs}

写入边界：
{暂不写入，或只创建草稿，submit 前必须确认}

要求：
先展示 command surface，不要直接写代码。
只询问会阻塞构建的信息。
```

關鍵是先看 command surface。CLI 設計錯了，後面實現再完整也不好用。

## 輸入材料要真實

可以給：

- 文件 URL。
- OpenAPI spec。
- 已脫敏 `curl`。
- 示例 JSON / CSV。
- SQLite 資料庫。
- 現有指令碼。
- 你希望模仿的 `--help`。

不要給：

- 真實 token。
- 生產賬號。
- 未脫敏客戶資料。
- 無法驗證的口頭描述。

認證資訊應走環境變數、配置檔案或 secret store。CLI 缺認證時要清楚報錯。

## 驗收方式

一個 CLI 做完後，不要只在原始碼目錄裡跑一次。

驗收：

1. 安裝到 `PATH`。
2. 換一個臨時目錄執行。
3. 缺少認證時錯誤清楚。
4. 搜尋預設輸出小。
5. 大響應能匯出到檔案。
6. 寫操作不會直接執行，或有明確確認。
7. companion skill 能說明何時使用和何時禁止。

如果 Codex 預設輸出巨大 JSON，讓它改成摘要 + 檔案路徑。

## 後續複用

跑順後，把 CLI 使用方式寫進 skill。以後新任務只需要說：

```text
请使用 $ci-logs 检查这个 build URL 的失败 job。
```

穩定之後再考慮 automation。先有 CLI 和 skill，再談定時或批次執行。

## Skill 要記錄什麼

companion skill 不是 CLI README 的復讀。它應該告訴未來的 Codex 任務：

- 什麼時候必須先跑 `setup-check`。
- 搜尋預設 `--limit` 用多少。
- 大輸出應該寫到哪個目錄。
- 哪些命令只讀，哪些命令會寫入。
- `submit`、上傳、刪除、重試這類動作需要使用者明確確認。
- CLI 失敗時先修 CLI 還是回退到別的工具。

如果 skill 沒有寫審批邊界，CLI 以後會被誤用。尤其是內部工具，一定要把 live write 和 destructive action 寫成硬邊界。

## 官方資料

- [OpenAI Codex use case: Create a CLI Codex can use](https://developers.openai.com/codex/use-cases/agent-friendly-clis)
- [Codex skills](https://developers.openai.com/codex/skills)
- [Build Codex plugins](https://developers.openai.com/codex/plugins/build)
