---
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="/docs/codex/official/03-extensions/09-skills-reuse">
    把 CLI 调用方法沉淀成可复用 skill。
  </Card>
  <Card title="MCP tools" href="/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)
