amuxOS Docs

简体中文

English

简体中文

English

外观

amux

Latest releaseTotal release asset downloadsLicense: Apache 2.0

Source builds: Go 1.25 or newermacOS and Linux, arm64 and amd64Documentation: English and Simplified Chinese

官网 · GitHub · 文档

amux 在本地和远端机器上运行、协调 Codex、Claude 和 Pi Session，提供 CLI、终端 UI、 Task 与 Schedule API，以及可选的飞书/Lark Bot Bridge。

本仓库是 amux 的开源源码，Go module 为 github.com/amuxos/amux。原创源码、文档和示例默认采用 Apache-2.0， 允许依协议商业使用和闭源集成；另有标注者除外。详见许可说明。

贡献与许可规则见 CONTRIBUTING.md，工程说明见 AGENTS.md；Claude Code 使用 CLAUDE.md 加载后者。

从飞书开始 ​

飞书是面向用户的主要交互入口：私聊发起需求，在群话题中协作，通过进度卡片跟踪委派工作。 已有可用机器人即可开始，普通用户不需要使用 CLI。

下文保留运维者和贡献者需要的安装细节。

构建与运行 ​

预编译版本无需 Go 工具链。先安装并登录原生 Agent，再下载安装器：

sh
curl -fsSL https://github.com/amuxos/amux-releases/releases/latest/download/install.sh -o /tmp/amux-install.sh
bash /tmp/amux-install.sh --runtime codex

独立安装器从 amuxos/amux-releases 下载预编译包，可加 --version vX.Y.Z 固定版本。 安装后打开新 shell，或执行安装器打印的 PATH 命令。

使用 --runtime claude（需要 Node.js 22+）或 --runtime pi 选择其他已安装 Agent。 添加 --feishu 可配置机器人。从源码构建：

sh
git clone https://github.com/amuxos/amux.git
cd amux

源码构建需要 Go 1.25+，并已安装、登录原生 Agent（codex、claude 或 pi）。 在公共 module 目录运行：

bash
# 自动检测已安装的 Agent，交互选择 Runtime。
bash scripts/install.sh --feishu

# 显式选择 Runtime，自动使用对应的 builtin Profile。
bash scripts/install.sh --runtime codex --feishu --interaction-mode singleton

# 仅使用本地 CLI，不配置飞书 Bot。
bash scripts/install.sh --runtime pi

每个 Runtime 自动映射到对应的 builtin/codex、builtin/claude 或 builtin/pi Profile：

  • 仅一个已安装 Runtime 时自动选择；多个时按编号或名称选择。
  • 非交互运行传入 --runtime（别名 --provider）；缺少 Runtime 会在安装前失败。
  • 原生 Agent 管理认证和默认模型；--model 覆盖飞书 Bot 的模型，不附带端点或凭据。

脚本完成构建、安装、PATH 更新、本地系统配置和就绪检查。 启用 --feishu 后须在交互终端完成扫码；未完成时不创建 Session。

  • 默认 singleton 模式创建命名的持久 Session 并绑定 Bot。
  • --feishu-profile 修改 Bot Profile 名称（默认 default），不是 Agent Profile。
  • --session-name 和 --session-cwd 指定 singleton Session 与工作区。
bash
bash scripts/install.sh --runtime claude --feishu --interaction-mode thread \
  --feishu-profile assistant --model sonnet

thread 模式为新对话保存 Profile/Runtime/Model。重复运行复用 Bot 凭据与兼容的 singleton Session；冲突时给出指引，不删除 Session 或绑定。切换到 thread 模式保留旧 Session，但关闭其 singleton 路由；显式 --model 通过 session set-model 更新复用的 Session。

重复安装先暂存、验证新二进制，再停止 Pack autosync 和本地系统；停止失败则中止替换。 配置、凭据、Session 和 Pack 均保留，随后启动新系统，并按原状态恢复 autosync。 此过程会中断活动工作，但不发送测试提示词或聊天消息。

需要全新安装时添加 --clean：

bash
bash scripts/install.sh --clean --runtime codex --feishu --interaction-mode singleton

--clean 会删除 AMUX_HOME（默认 ~/.amux）下全部数据：先停止、卸载 amux， 再清除配置、凭据、Session、日志和托管 Pack。须重新配置飞书；原生 Agent 及其登录信息保留。

  • 源码 checkout 与 singleton 工作区须位于清理目录之外。
  • 二进制和 Claude SDK 暂存到外部，因此 --source、--claude-sidecar 可指向旧安装内部。
  • 卸载也会停止已登记的独立 MCP/GUI 服务，由外部宿主负责重新启动。

Claude 需要锁定 SDK 支持的 Node/npm。源码安装将完整 sidecar 构建到 ~/.amux/sidecars/claude-sdk/，Runtime 自动发现，无需环境变量。 Codex 和 Pi 无需 sidecar；脚本不安装或升级原生 Agent。

高级安装选项
  • 本地二进制： --source /path/to/binaries，目录须包含 amux、amuxd 和 amuxlet。
  • Agent Profile： --agent-profile <ref> 显式选择内置 Profile，并据此推导 Runtime。
  • 强制源码构建： --from-source 即使不在源码 checkout 中也从源码构建。
  • Claude sidecar： --claude-sidecar /path/to/claude-sdk，须包含 dist/、node_modules/ 和 package.json；也可采用相邻的 ../sidecars/claude-sdk/ 布局。
  • 源码目录： 独立脚本接受 --source-root /path/to/public-amux 或 AMUX_INSTALL_SOURCE_ROOT，拒绝内部发行版根目录。
  • Shell PATH： --no-modify-path 跳过添加条目；清空卸载仍会移除旧的托管条目。

全部参数见 bash scripts/install.sh --help。

快速上手 ​

安装完成后先配置一次本地系统，然后启动一个 Session 并交给它工作：

sh
amux setup local
amux session run builtin/codex --name demo
amux session send demo "总结这个仓库的目录结构"
amux session attach demo   # 实时时间线；/detach 或 Ctrl-] 退出

一套安装包含：Hub（amuxd）负责身份、路由与调度；本地或远端 Runtime （amuxlet）执行 Agent Session。Session 是持续对话，Task 是有结果的有界执行， Schedule 按 cron 风格规则触发提示词或子任务。可选的飞书 Bridge 和外部 MCP Host 接入同一控制面。

使用与运维 ​

本地 Session、Task 和 Schedule 需要 Hub 与 Runtime，无需飞书：

操作命令
配置本地系统amux setup local
通过飞书官方注册流程添加 Botamux setup feishu
重新构建后升级，无需重复 setupmake upgrade
下载安装公共最新版本amux update --restart

来自默认发行清单的公共更新在替换二进制和配套 Claude SDK 前校验 SHA256。 用 AMUX_RELEASE_URL 或 --release-url 覆盖清单/归档来源；直接指向归档包的 自定义地址不校验 checksum。

Profile Pack 使用 manifest v2，支持外部 Git Pack，默认没有 Pack 市场。 可选专家编辑需单独配置兼容的 authoring runtime，源码构建不会隐式下载。 捆绑 Skill 和桌面应用不在本仓库范围内。

开发 ​

示例与操作指南见 文档导航 和 示例导航。

本 module 可独立构建。其它发行版依赖其 Go module，在调用应用入口前注册扩展。 详见发行版开发指南。

make check 校验生成的协议与参考文档、用 Python 3 检查第三方声明、运行 Go 测试并 构建命令；npm 可用时测试 sidecar。不运行真实外部账号测试。部分 fixture 和资源仍待审核， 未纳入本仓库；当前套件不代表完整产品验收覆盖。

许可与归属标识 ​

再分发须提供 LICENSE，保留适用的 NOTICE 与其它必需声明， 并按 Apache-2.0 第 4 条标明修改的文件。归属标识可放在第三方声明、文档或“关于”组件列表中， 无需显著展示 Logo 或官网署名。

依赖与原生 Agent 保留各自的许可条款，见第三方声明。 发行归档的许可材料位于 licenses/amux/；许可说明提供义务解释和集成示例。

Released under the Apache-2.0 License.

amuxOS · amuxos.com