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推断登录 Shellzsh、bash或fish向对应启动文件写入一段由# Composio CLI标记管理的 PATH 块让未来的终端都能找到composio。安装完成后打开一个新终端然后登录composio login需要说明的是安装器默认不会安装 Agent 插件也不会替你登录除非你显式要求。Shell 自动配置写入哪些文件、为什么这样设计安装器默认auto模式从$SHELL推断登录 Shell并把 PATH 写入对应启动文件。从 install.sh 的shell_path_files()函数可以看到完整的文件清单Shell被写入的启动文件zsh~/.zshrcfish~/.config/fish/config.fishbash~/.bashrc加上一个登录模式启动文件bash 的特殊处理是整个设计中容易被忽视、却又最关键的一环。原因在于登录模式的 bashmacOS 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()如果系统上原本存在~/.profilebash 创建该文件之前由登录 shell 读取的配置新建的~/.bash_profile会先被写入一段透传 sourcing代码继续加载~/.profile从而保证你已有的登录配置不会失效~/.profile本身永远不会被修改。托管 PATH 块与幂等性安装器写入的是一段托管managedPATH 块即# Composio CLI export PATHbin目录:$PATHfish 下为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_SHELLzsh sh curl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_SHELLbash sh curl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_SHELLfish sh curl -fsSL https://composio.dev/install | COMPOSIO_INSTALL_SHELLnone sh取值说明auto默认从$SHELL推断登录 Shell若$SHELL未设置或不是 zsh/bash/fish则退化为纯安装模式并打印手动配置 PATH 的命令zsh/bash/fish强制配置指定 Shellnone纯安装模式不修改任何 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_VERSION0.3.1 sh # 方式二位置参数支持 stable 与 beta 标签 curl -fsSL https://composio.dev/install | sh -s -- composio/cli0.3.1-beta.329位置参数优先于COMPOSIO_INSTALL_VERSIONinstall.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/.composioCOMPOSIO_BIN_DIRcomposio入口点目录。请将其视为可信输入任何能写入该目录的人都可以替换未来终端将运行的命令。$HOME/.local/binCOMPOSIO_INSTALL_VERSION要安装的稳定版或 beta 版本号可带或不带composio/cli前缀。最新稳定版COMPOSIO_QUIET设为1或true时隐藏进度输出警告与错误仍会打印。未设置COMPOSIO_DEBUG设为1或true时打印安装器跟踪信息下载 URL、临时目录、委托命令输出。未设置COMPOSIO_INSTALL_HELP设为0时隐藏正常的安装后引导提示Shell 配置失败仍会警告并向 stderr打印恢复命令。1COMPOSIO_INSTALL_PLUGINS设为1时为检测到的 Agent 宿主安装插件实际执行composio setup --target auto --yes --if-present。0COMPOSIO_INSTALL_SHELLShell 配置模式auto从$SHELL推断登录 Shellzsh/bash/fish强制指定none跳过。autoCOMPOSIO_GITHUB_OWNER用于解析 Releases 的 GitHub 组织。ComposioHQCOMPOSIO_GITHUB_REPO用于解析 Releases 的 GitHub 仓库。composioCOMPOSIO_GITHUB_URLGitHub Web 与发布包下载基地址。https://github.comCOMPOSIO_GITHUB_API_BASE_URLGitHub 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*直接报错要求使用 WSLDarwin 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_ORIGINinstaller环境变量标记来源测试断言该标记必须存在。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_SHELLshell环境变量执行它。整个变体脚本同样经过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.zipcomposio-linux-aarch64.zipcomposio-darwin-x64.zipcomposio-darwin-aarch64.zip解压后需安装整个 bundle。这一点至关重要CLI 会在可执行文件旁加载支持文件如services/、local-tools-binaries/、运行辅助 mjs 等只拷贝嵌套的composio二进制是不够的会导致部分功能不可用安装器源码也会在 bundle 中没有支持文件时给出警告见 install.sh。完整的手动安装步骤bundlecomposio-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 composiowhich 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*会直接被拒绝并提示使用 WSLinstall.sh因此 WSL 是 Windows 上的官方安装路径。常见问题与排查composio命令在新终端仍找不到检查启动文件中# Composio CLI托管块是否存在若使用 bash确认~/.bash_profile或~/.bash_login中也有该块登录 bash 不读~/.bashrc。想静默安装设置COMPOSIO_INSTALL_QUIET1或true隐藏进度警告与错误仍输出再配合COMPOSIO_INSTALL_HELP0可隐藏安装后引导。想调试安装器设置COMPOSIO_DEBUG1会打印下载 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_SHELLnone该语义的变化历史记录在仓库的变更日志中见 docs/content/changelog/07-31-26-installer.mdx 与 docs/content/changelog/08-05-26-installer-shell-default.mdx。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
