CLI Setup 命令

为 Codex 或 Claude 安装 1MCP CLI 的引导文档和钩子配置。

概要

npx -y @1mcp/agent cli-setup (--codex | --claude) [选项]

描述

cli-setup 会安装轻量级引导文件，让 Codex 或 Claude 会话按 1MCP CLI 工作流启动。它会写入：

• 受管理的 1MCP.md 引导文档
• 在会话开始时注入启动文档的钩子配置
• 从 AGENTS.md 或 CLAUDE.md 指向启动文档的引用

cli-setup 不会替代 instructions。它的作用是确保会话准备好按正确顺序使用 instructions、inspect 和 run。

可以把 cli-setup 理解为把现有 agent 工作流迁移到 1MCP CLI 模式的桥。它负责教客户端怎么开始，但真正的实时发现和执行仍然通过 instructions、inspect、run 完成。

必选客户端

必须且只能选择一个目标：

• --codex - 仅为 Codex 安装
• --claude - 仅为 Claude 安装

如果两个都不传或同时传入，命令会报错。

选项

• --scope <global|repo|all> - 安装范围，默认 global
• --repo-root <path> - repo 级安装时使用的仓库根目录

范围行为

• global - 写入用户 home 目录下的 Codex 或 Claude 配置位置
• repo - 在指定仓库内写入 repo-local 配置
• all - 同时写入全局与 repo 级配置

写入的文件

Codex

• 全局受管理文档：~/.codex/1MCP.md
• 全局 hooks：~/.codex/hooks.json
• 全局启动引用：~/.codex/AGENTS.md
• Repo 受管理文档：<repo>/.codex/1MCP.md
• Repo hooks：<repo>/.codex/hooks.json
• Repo 启动引用：<repo>/AGENTS.md

Claude

• 全局受管理文档：~/.claude/1MCP.md
• 全局 hooks：~/.claude/settings.json
• 全局启动引用：~/.claude/CLAUDE.md
• Repo 受管理文档：<repo>/.claude/1MCP.md
• Repo hooks：<repo>/.claude/settings.json
• Repo 启动引用：<repo>/CLAUDE.md

示例

安装全局 Codex 配置

npx -y @1mcp/agent cli-setup --codex

安装 Repo 级 Claude 配置

npx -y @1mcp/agent cli-setup --claude --scope repo --repo-root .

同时安装全局和 Repo 级 Codex 配置

npx -y @1mcp/agent cli-setup --codex --scope all

Codex 后续配置

当使用 --codex 时，命令还会输出一段必须加入 config.toml 的配置，用于开启 Codex hooks，以及带网络访问的 workspace-write 沙箱。

最终工作流

受管理的启动文档会告诉客户端：

1. 如果当前会话尚未通过 hooks 注入最新内容，就先执行 1mcp instructions
2. 不知道提供方或工具时，可先执行 1mcp inspect --search <query>（也可指定服务器）；已知目标时直接检查
3. 在选择工具前执行 1mcp inspect <server> 并阅读适用的服务器指令
4. 在调用工具前先执行 1mcp inspect <server>/<tool>
5. 只有在确认 schema 之后才执行 1mcp run <server>/<tool> --args '<json>'

搜索默认使用不区分大小写的字面子串匹配。使用带引号的 --search 'filesystem/*read?' --glob 可按 */? 对整个引用匹配。--include-descriptions 将有效描述纳入匹配；--show-descriptions 独立控制描述显示。

重新运行相同的 cli-setup 命令即可更新任意范围的受管理指引。重复执行是幂等的，并保留无关的启动文档内容和 hooks。启动引用保持轻量，hooks 仍调用 1mcp instructions。

另请参阅

• CLI 模式指南 - 面向 agent 的 CLI 工作流概念说明
• Instructions 命令 - cli-setup 最终引导会话进入的命令
• Inspect 命令 - 发现工具和查看 schema
• Run 命令 - 调用选中的工具
• Codex 集成指南 - Codex 的完整配置流程