Composio CLI 安装完全指南：一键脚本、Shell 配置、校验与卸载-平芜编程栈

Composio CLI 安装完全指南：一键脚本、Shell 配置、校验与卸载

【免费下载链接】composioComposio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio

导读

Composio 是一个为 AI Agent 提供 1000+ 工具包、工具搜索、上下文管理、认证与沙箱工作台的基础设施项目，而其 CLI 是开发者在终端中连接应用、执行工具、检查 schema、调用已认证 API 的核心入口。本文以仓库根目录的 INSTALL.md 为主体，结合 install.sh 源码、install/ 目录下的三个 Shell 变体脚本以及test/目录的安装测试套件，系统讲解 Composio CLI 的一键安装、Shell 自动配置原理、全部环境变量参数、版本固定、手动安装、校验与卸载的完整流程。读完本文，你将能在一台全新机器上快速、安全、可重复地完成 Composio CLI 的安装与卸载，并理解安装器每一步行为背后的实现依据。

快速开始：一行命令完成安装

Composio CLI 提供与 Rust、Node.js 等主流工具一致的一键安装方式：

curl -fsSL https://composio.dev/install | sh

这条命令会完成三件事：

下载并校验官方发布包：将 CLI bundle 安装到~/.composio目录（默认值，可用COMPOSIO_INSTALL_DIR覆盖）。
创建入口点：在~/.local/bin下创建composio可执行文件的符号链接（默认值，可用COMPOSIO_BIN_DIR覆盖），确保composio命令可以直接运行。
自动配置 Shell：根据$SHELL推断登录 Shell（zsh、bash或fish），向对应启动文件写入一段由# Composio CLI标记管理的 PATH 块，让未来的终端都能找到composio。

安装完成后，打开一个新终端，然后登录：

composio login

需要说明的是，安装器默认不会安装 Agent 插件，也不会替你登录，除非你显式要求。

Shell 自动配置：写入哪些文件、为什么这样设计

安装器默认（auto模式）从$SHELL推断登录 Shell，并把 PATH 写入对应启动文件。从 install.sh 的shell_path_files()函数可以看到完整的文件清单：

Shell	被写入的启动文件
zsh	`~/.zshrc`
fish	`~/.config/fish/config.fish`
bash	`~/.bashrc`加上一个登录模式启动文件

bash 的特殊处理是整个设计中容易被忽视、却又最关键的一环。原因在于：登录模式的 bash（macOS Terminal.app 启动的正是这种 shell）从不读取~/.bashrc，它只读取以下三个文件中"第一个存在"的那一个：

~/.bash_profile
~/.bash_login
~/.profile

因此安装器在 install.sh 的bash_login_path_file()中实现了如下选择逻辑：

若~/.bash_profile不存在但~/.bash_login存在，则使用~/.bash_login；
否则使用~/.bash_profile（不存在则创建）。

而在"创建~/.bash_profile"这一场景下还有一个细腻的兼容处理（见 install.sh 的seed_bash_login_file()）：如果系统上原本存在~/.profile（bash 创建该文件之前由登录 shell 读取的配置），新建的~/.bash_profile会先被写入一段"透传 sourcing"代码，继续加载~/.profile，从而保证你已有的登录配置不会失效；~/.profile本身永远不会被修改。

托管 PATH 块与幂等性

安装器写入的是一段托管（managed）PATH 块，即：

# Composio CLI export PATH="<bin目录>:$PATH"

（fish 下为set --export PATH "<bin目录>" $PATH。）

这段块的"托管"语义体现在 install.sh 的write_path_block()中：

幂等：重复安装不会追加第二段块。path_block_current()（install.sh）会检查启动文件中是否已存在唯一且内容正确的托管块，已是最新状态时直接跳过，输出... is already up to date.。
自动对账（reconcile）：当COMPOSIO_BIN_DIR改变导致旧块指向过期路径时，会替换旧的托管块而不是叠加新的，保证每个启动文件始终只有恰好一个托管块。
保留非托管内容：awk 重写逻辑只消费托管块与旧版安装器遗留的export COMPOSIO_INSTALL_DIR=...配套行，其他所有用户内容原样保留。
旧版本块迁移：早期安装器写的是"标记行 +COMPOSIO_INSTALL_DIR导出 + 引用它的 PATH 行"三行结构，新安装器能识别该旧结构并整体迁移为单行块（见 install.sh 的is_legacy_install_dir_assignment()与is_legacy_pair()）。

委托与内联回退双通道

安装器配置 Shell 时并非直接写文件，而是优先委托给已安装的 CLI 执行composio install --shell <shell>（见 install.sh 的setup_requested_shell()）。但存在三种回退到内联写入的情况：

已安装的 CLI 版本太旧，不支持--shell标志（通过"$exe" install --help | grep -- --shell探测）；
委托执行失败；
委托返回成功但delegated_setup_verified()（install.sh）验证发现某个目标启动文件仍是过期块——稳定版 CLI 会跳过已带标记的文件，可能留下指向旧 bin 目录的残留。

任何一条路径失败都不会导致安装失败——二进制安装始终成功，shell 配置失败只会走print_setup_failure_ending()（install.sh）向 stderr 打印警告与一条可复制执行的恢复命令。

从test/目录的测试套件（如 test/install-sh-release-resolution.test.sh）可以看到这一整套行为都被严格验证：测试断言 bash 场景下~/.bashrc与~/.bash_profile都出现托管块、delegated_setup_verified的字节级一致性（渲染函数render_bin_dir()必须与 CLI 侧install.cmd.ts完全一致）、以及test/managed-block-fixtures/下 17 组"before/after"夹具与 CLI 实现共享的 conformance 契约（install.sh）。

选择或跳过 Shell 配置：COMPOSIO_INSTALL_SHELL

如果你不想让安装器自动推断，或者干脆不想改动任何 Shell 文件，可以通过环境变量强制指定：

curl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_SHELL=zsh sh curl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_SHELL=bash sh curl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_SHELL=fish sh curl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_SHELL=none sh

取值说明：

auto（默认）：从$SHELL推断登录 Shell；若$SHELL未设置或不是 zsh/bash/fish，则退化为纯安装模式并打印手动配置 PATH 的命令；
zsh/bash/fish：强制配置指定 Shell；
none：纯安装模式，不修改任何 Shell 文件。适合 CI、Docker 镜像，或由 dotfile 管理器（如 chezmoi、yadm）接管启动文件的场景。

仓库还在 install/ 目录提供了三个 Shell 专属安装器变体：install/zsh.sh、install/bash.sh、install/fish.sh。它们把COMPOSIO_INSTALL_SHELL固定为各自对应的 Shell 后再委托给基础安装器——从源码可见三者除requested_shell()一行外完全字节一致，该结构由测试强制约束（test/install-sh-release-resolution.test.sh 对三个变体逐一校验requested_shell()恰好出现一次且其余部分与install/bash.sh无漂移）。

固定版本安装

Composio CLI 支持两种方式固定安装版本：

# 方式一：环境变量 curl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_VERSION=0.3.1 sh # 方式二：位置参数（支持 stable 与 beta 标签） curl -fsSL https://composio.dev/install | sh -s -- @composio/cli@0.3.1-beta.329

位置参数优先于COMPOSIO_INSTALL_VERSION（install.sh 中先取位置参数、为空时才回落环境变量）。

版本格式在 install.sh 的normalize_version()中被严格校验：必须是X.Y.Z或X.Y.Z-beta.N，可带或不带@composio/cli@前缀；格式非法会在任何网络请求发生前直接报错退出（Invalid Composio CLI version ...）。

若未指定版本，安装器会调用 GitHub Releases API 分页查找最新的稳定版（跳过 beta 标签，见resolve_latest_cli_release()，install.sh），最多翻 5 页、每页 100 条。

全部环境变量与参数一览

以下参数表完整来自 INSTALL.md 并结合作者的使用场景做了补充说明：

变量或参数	说明	默认值
`COMPOSIO_INSTALL_DIR`	存放完整 CLI bundle 的目录（含`release-tag.txt`安装元数据）。	`$HOME/.composio`
`COMPOSIO_BIN_DIR`	`composio`入口点目录。请将其视为可信输入：任何能写入该目录的人都可以替换未来终端将运行的命令。	`$HOME/.local/bin`
`COMPOSIO_INSTALL_VERSION`	要安装的稳定版或 beta 版本号，可带或不带`@composio/cli@`前缀。	最新稳定版
`COMPOSIO_QUIET`	设为`1`或`true`时隐藏进度输出；警告与错误仍会打印。	未设置
`COMPOSIO_DEBUG`	设为`1`或`true`时打印安装器跟踪信息（下载 URL、临时目录、委托命令输出）。	未设置
`COMPOSIO_INSTALL_HELP`	设为`0`时隐藏正常的安装后引导提示；Shell 配置失败仍会警告并（向 stderr）打印恢复命令。	`1`
`COMPOSIO_INSTALL_PLUGINS`	设为`1`时为检测到的 Agent 宿主安装插件（实际执行`composio setup --target auto --yes --if-present`）。	`0`
`COMPOSIO_INSTALL_SHELL`	Shell 配置模式：`auto`从`$SHELL`推断登录 Shell；`zsh`/`bash`/`fish`强制指定；`none`跳过。	`auto`
`COMPOSIO_GITHUB_OWNER`	用于解析 Releases 的 GitHub 组织。	`ComposioHQ`
`COMPOSIO_GITHUB_REPO`	用于解析 Releases 的 GitHub 仓库。	`composio`
`COMPOSIO_GITHUB_URL`	GitHub Web 与发布包下载基地址。	`https://github.com`
`COMPOSIO_GITHUB_API_BASE_URL`	GitHub API 基地址（可用于企业/镜像场景）。	由`COMPOSIO_GITHUB_URL`推导
`--agent`	安装完成后以 Composio Agent 身份登录。	关闭
`--no-plugins`	跳过插件安装（兼容保留，现与默认行为一致）。	关闭

命令行的`--agent`与`--no-plugins`

除环境变量外，安装器还接受两个命令行选项（解析逻辑见 install.sh）：--agent会在安装后执行composio login --agent --no-skill-install；--no-plugins用于显式关闭插件。-h/--help会先于平台检查输出用法（测试 test/install-sh-release-resolution.test.sh 验证了--help在任何平台探测之前就能成功返回）。

安装器的工作流程与安全设计

从 install.sh 的main()主流程可以还原出完整安装流水线：

参数与模式校验：校验COMPOSIO_INSTALL_PLUGINS只能是0/1、COMPOSIO_INSTALL_SHELL只能是auto/zsh/bash/fish/none、参数至多一个版本标签。
平台探测：detect_target()（install.sh）通过uname -ms映射目标——MINGW64*/MSYS*/CYGWIN*直接报错要求使用 WSL；Darwin x86_64还会用sysctl sysctl.proc_translated检测 Rosetta 2 转译环境并自动改下darwin-aarch64包。
预检依赖：要求系统存在curl与unzip，缺失即报错退出。
解析版本与下载 URL：固定版本直接拼releases/download/<version>/composio-<target>.zip；未指定则查询 API 解析最新稳定版。
下载与 SHA-256 校验（详见下一节）。
解压与原子发布：install_bundle()（install.sh）先把内容复制到安装目录下的临时 staging 目录（.composio-install.XXXXXX），再逐个"发布"条目，最后才发布composio二进制本身——即使中途失败，旧安装也不会被半损坏。升级时旧的 bundle 目录（如services/）会被整体替换而非合并。
入口点创建：install_entry_point()（install.sh）在COMPOSIO_BIN_DIR创建指向安装目录二进制的符号链接；若 bin 目录与安装目录相同（legacy 单目录布局）则跳过；若入口点已存在且是目录则拒绝覆盖。
版本自检："$exe" --version必须成功，否则报错（测试中通过TEST_VERSION_EXIT模拟该失败路径）。
可选插件与 Agent 登录：仅当显式开启时执行，且都以COMPOSIO_CLI_INVOCATION_ORIGIN=installer环境变量标记来源（测试断言该标记必须存在）。
Shell 配置：如前述的委托 + 内联回退。
结束语：print_post_install_help()（install.sh）基于"调用终端的继承 PATH 快照"输出三种结局之一——已就绪（composio is ready）、需开新终端、或打印带绝对路径的恢复命令；且结束块之后不允许再有输出（测试用assert_tail逐字节校验结尾）。

安全设计：URL 校验与协议强制

安装器对下载安全非常重视，这在 install.sh 中集中体现：

validate_url()拒绝含不可打印字符/空白/@的 URL；
只允许https://；http://仅对环回地址（localhost、127.0.0.1、[::1]）或通过COMPOSIO_INSTALL_ALLOW_HTTP_HOST显式放行的主机有效；
所有 curl 下载都带--proto '=https' --proto-redir '=https'，重定向只能到达 HTTPS——测试专门构造了重定向降级模拟并断言安装失败（TEST_REDIRECT_DOWNGRADE）。

安装器变体脚本的下载链

三个变体脚本本身并不含安装逻辑：它们下载基础安装器（默认 URL 指向仓库next分支的 install.sh，可用COMPOSIO_INSTALL_SCRIPT_URL覆盖），对下载内容做非空校验后，以COMPOSIO_INSTALL_SHELL=<shell>环境变量执行它。整个变体脚本同样经过validate_url安全检查，并以信号 trap + 临时目录清理保证中断时不留垃圾。

SHA-256 校验：官方源严格、自定义源宽松

安装器对所有发布包执行 SHA-256 校验，但严格程度取决于发布源：

官方源（默认）：即github.com/ComposioHQ/composio且未覆盖 API 基地址（判定逻辑见 install.sh）。以下任一情况都会以Refusing to install中止安装：
- checksums.txt清单缺失或下载失败；
- 清单中没有当前平台归档（composio-<target>.zip）的条目；
- 条目格式非法（不是 64 位十六进制）；
- 校验和不匹配。
自定义源（覆盖了COMPOSIO_GITHUB_URL/COMPOSIO_GITHUB_OWNER/COMPOSIO_GITHUB_REPO/COMPOSIO_GITHUB_API_BASE_URL中的任一）：清单缺失或无条目时只警告并继续，仅格式非法或校验和不匹配才中止——因为镜像源的清单不在项目控制范围内。
无 SHA-256 工具：系统既没有sha256sum也没有shasum（极简容器中偶见）时，警告"跳过校验"并继续（见 install.sh）。

verify_checksum()（install.sh）优先使用sha256sum，其次shasum -a 256；官方源下release-tag.txt会被写入安装目录用于记录已装版本。

手动安装（无需一键脚本）

如果不便使用curl | sh，也可以从项目的 GitHub Releases 手动下载归档。可用的归档命名遵循composio-<platform>-<arch>.zip模式：

composio-linux-x64.zip
composio-linux-aarch64.zip
composio-darwin-x64.zip
composio-darwin-aarch64.zip

解压后需安装整个 bundle。这一点至关重要：CLI 会在可执行文件旁加载支持文件（如services/、local-tools-binaries/、运行辅助 mjs 等），只拷贝嵌套的composio二进制是不够的，会导致部分功能不可用（安装器源码也会在 bundle 中没有支持文件时给出警告，见 install.sh）。

完整的手动安装步骤：

bundle=composio-linux-x64 COMPOSIO_INSTALL_DIR=${COMPOSIO_INSTALL_DIR:-"$HOME/.composio"} COMPOSIO_BIN_DIR=${COMPOSIO_BIN_DIR:-"$HOME/.local/bin"} unzip "$bundle.zip" mkdir -p "$COMPOSIO_INSTALL_DIR" cp -Rp "$bundle"/. "$COMPOSIO_INSTALL_DIR/" chmod +x "$COMPOSIO_INSTALL_DIR/composio" mkdir -p "$COMPOSIO_BIN_DIR" if [ "$COMPOSIO_BIN_DIR" != "$COMPOSIO_INSTALL_DIR" ]; then ln -sf "$COMPOSIO_INSTALL_DIR/composio" "$COMPOSIO_BIN_DIR/composio" fi export PATH="$COMPOSIO_BIN_DIR:$PATH"

安装校验

安装完成后，建议立即验证两件事——版本与命令解析路径：

composio --version which composio

which composio应输出~/.local/bin/composio（或你自定义的$COMPOSIO_BIN_DIR），说明 PATH 配置已生效。若在新终端中composio仍不可用，检查对应启动文件中的# Composio CLI托管块是否存在且内容正确。

卸载与清理

卸载分两个层次：

1. 仅移除程序（保留数据）

删除入口点与发布产物，但不触碰凭据、配置和缓存：

install_dir=${COMPOSIO_INSTALL_DIR:-"$HOME/.composio"} bin_dir=${COMPOSIO_BIN_DIR:-"$HOME/.local/bin"} rm -f \ "$bin_dir/composio" \ "$install_dir/composio" \ "$install_dir/release-tag.txt" \ "$install_dir/run-helpers-runtime.mjs" \ "$install_dir/run-subagent-shared.mjs" \ "$install_dir/run-subagent-acp.mjs" \ "$install_dir/run-subagent-legacy.mjs" \ "$install_dir/run-subagent-output-mcp.mjs" rm -rf \ "$install_dir/services" \ "$install_dir/acp-adapters" \ "$install_dir/local-tools-binaries"

注意：上面的文件列表与当前 release 的目录布局对应；如果你安装的是其他版本，请对照该版本归档的实际内容调整。

随后手动移除启动文件中的托管 PATH 块。需要检查的文件包括：~/.zshrc、~/.bashrc、~/.bash_profile、~/.bash_login、~/.config/fish/config.fish。需要注意的细节：

旧版安装器写入的块在标记行之后还多一行export COMPOSIO_INSTALL_DIR=...（fish 为set --export COMPOSIO_INSTALL_DIR ...），需一并删除。
若删块后~/.bash_profile只剩空行，直接删除该文件：安装器为没有登录启动文件的 bash 系统创建了它，而即使是一个空的~/.bash_profile也会阻止 bash 读取~/.profile。
若安装时系统原本存在~/.profile，安装器创建的那个~/.bash_profile实际是"透传 sourcing"文件（首行注释为# Created by the Composio CLI installer.），卸载时也应一并删除，以恢复 bash 默认的启动文件选择顺序。

2. 完全重置（含数据）

要连凭据、配置、缓存及所有其他 CLI 文件一并清除：

rm -rf "${COMPOSIO_INSTALL_DIR:-$HOME/.composio}"

这是一次不可撤销的完整重置，执行前请确认不再需要其中的任何数据。

支持平台

平台	说明
Linux x64	原生支持
Linux ARM64	原生支持
macOS Intel	原生支持；Rosetta 2 转译 shell 下自动切换 aarch64 包
macOS Apple Silicon	原生支持
Windows	不支持原生安装，请在 WSL 发行版内运行安装器

从安装器源码看，Windows 相关平台标识（MINGW64*/MSYS*/CYGWIN*）会直接被拒绝并提示使用 WSL（install.sh），因此 WSL 是 Windows 上的官方安装路径。

常见问题与排查

composio命令在新终端仍找不到？检查启动文件中# Composio CLI托管块是否存在；若使用 bash，确认~/.bash_profile或~/.bash_login中也有该块（登录 bash 不读~/.bashrc）。
想静默安装？设置COMPOSIO_INSTALL_QUIET=1（或true）隐藏进度，警告与错误仍输出；再配合COMPOSIO_INSTALL_HELP=0可隐藏安装后引导。
想调试安装器？设置COMPOSIO_DEBUG=1，会打印下载 URL、临时目录、委托的 CLI 命令及其捕获输出（测试中亦以+ curl GET ...形式断言该行为，见 test/install-sh-release-resolution.test.sh）。
bin 目录包含特殊字符？安装器会跳过自动 Shell 配置并警告，但安装本身成功。它拒绝的字符集合（:、反引号、$、双引号、反斜杠、CR/LF）恰好是 bash/zsh 双引号内仍会展开或会造成结构破坏的字符——测试用$(touch file)、反引号注入等路径验证了安装器宁可不写 rc 文件也绝不执行命令替换（test/install-sh-release-resolution.test.sh）。
$SHELL未设置或无法识别？安装退化为纯安装模式，不修改任何 Shell 文件，并打印一条带绝对路径的可运行命令，直接执行即可开始使用。
想要旧版安装器行为？若需要"仅安装、不改 Shell"，用COMPOSIO_INSTALL_SHELL=none；该语义的变化历史记录在仓库的变更日志中（见 docs/content/changelog/07-31-26-installer.mdx 与 docs/content/changelog/08-05-26-installer-shell-default.mdx）。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Composio CLI 安装完全指南：一键脚本、Shell 配置、校验与卸载