容器与镜像

AiCode 中 AI 执行命令的环境称为「容器」，入口在「设置 → 容器与镜像」。列表为单选，选中的容器即 AI 命令执行、文件读写与终端所在的环境。

后端分两类，二者必选其一：本地容器（在手机上运行 Linux 系统）与远程 SSH（在远程服务器上运行，见远程 SSH 模式）。

容器列表

每行是一个容器配置，名称后附来源标记：内置、自定义、SSH。

三种操作对各类容器均适用：

编辑：行尾铅笔图标。
重置：编辑弹窗右上角刷新图标。此为破坏性操作，会删除容器内已安装的工具与配置，需二次确认；确认后正在运行的 AI 会话与所有终端标签都会关闭。内容较多的大型容器删除可能耗时数十秒，期间显示「正在清理容器数据」及已清理项数，完成后自动关闭，界面不阻塞。
删除：行上左滑露出红色删除按钮。删除本地镜像会一并清理其 rootfs 释放空间（同样显示清理进度）；删除远程 SSH 仅删除配置，不影响服务器数据。

内置 Alpine 也可删除。全部删除后列表显示空态，可一键恢复内置 Alpine，无需担心误删。

容器运行后，App 会自动识别其系统类型，在列表左侧显示对应图标（支持 Alpine、Ubuntu、Debian、CentOS），无法识别则显示默认图标。

内置 Alpine 容器

App 自带 Alpine 镜像，首次启动时自动加入列表并选中，shell 路径已自动配置，无需额外设置。

首次使用需进入终端完成初始化

本地容器的环境准备（解压 rootfs 及安装基础工具）在首次进入终端页面时触发。首次使用请先进入终端完成初始化，之后 AI 命令执行、Git 管理与本地 MCP 才能正常使用。

首次进终端的初始化菜单

无论内置 Alpine 还是自行导入的镜像，rootfs 解压完成后首次进入终端都会弹出初始化菜单，含四个选项：

1. 自动安装依赖（推荐）

列出待装项（bash、curl、ripgrep、git 等基础工具，以及 Node.js 和 Python 3），输入 y 确认后选择软件源并开始安装。

2. 环境安装

打开「环境安装」菜单，按场景选择开发环境（见下节）。场景是一组运行时的组合，选定后确认清单即可安装；菜单中也提供「自定义安装」，可逐项勾选并指定主版本。

3. 手动安装（不再提示）

跳过安装，此后进入终端不再弹出该菜单，工具自行安装。如需恢复菜单，重置容器即可。

4. 退出

本次不安装，下次进入终端仍会提示。

安装失败不影响进入 shell，重新进入终端可再次尝试。

软件源选择

换源时可选择：

1) 自动探测（推荐）：实测各镜像源在当前包管理器下的可达性，自动跳过失效或被墙的源。
2~6) 指定镜像源：华为云、清华 tuna、中科大 ustc、腾讯云、阿里云。
0) 不换源，保持默认。

换源前会备份原配置，失败自动恢复，不影响后续安装。内置 Alpine 的 rootfs 保持官方源，需要国内源时在此菜单切换。

随时安装开发依赖（aicode）

初始化菜单仅在首次进入终端时弹出一次。之后如需安装其他运行时（例如 Java 或 Go），在终端执行命令 aicode 即可打开「环境安装」菜单。

aicode 按场景安装，选定场景并确认清单即可：

场景	安装内容
通用开发	基础工具 + Node.js + Python 3
Python 开发	基础工具 + Python 3 + pip
Node.js / 前端开发	基础工具 + Node.js + npm
Kotlin / Android 开发	基础工具 + JDK 17 + Android SDK
Flutter 开发	基础工具 + JDK + Android SDK + Flutter SDK
Java 开发	基础工具 + JDK
Go 开发	基础工具 + Go
Rust 开发	基础工具 + rustc + cargo
PHP 开发	基础工具 + PHP + Composer
仅基础工具	bash、curl、ripgrep、git

基础工具（bash、curl、ripgrep、git）在任何场景下都会安装。场景默认安装软件仓库的最新主版本；如需指定版本，使用菜单中的「自定义安装」逐项勾选。菜单中还支持单独换软件源、查看已安装的运行时。

「Kotlin / Android 开发」与「Flutter 开发」属重场景：会从国内镜像下载 JDK、Android SDK（含 build-tools、platform-tools）及 Flutter SDK，耗时较长、占用存储较多。建议在 Debian / Ubuntu 镜像中安装（内置 Alpine 因使用 musl libc 需额外处理）；ARM64 设备会自动替换为可执行的 aapt2 等原生二进制。注意 ARM64 容器仅能构建 Flutter debug APK，release 包需通过远程构建。安装完成后，新开终端会自动带上 JAVA_HOME、ANDROID_HOME 等环境变量，具体编译步骤见「进阶教程」中的《在容器中编译 Android 应用》《在容器中编译 Flutter 应用》。

终端右上角的设置图标打开终端设置面板，可调整配色主题、字号、字体与光标样式。

自定义镜像

内置 Alpine 可满足多数场景。如需 Debian / Ubuntu，或预装特定工具链的环境，可自行添加镜像，有两种方式。

方式一：内置镜像下载（推荐）

打开「设置 → 容器与镜像」，点击右上角下载图标。
页面列出可下载的镜像（Alpine、Ubuntu、Debian 等），点击一行查看详情并下载。
右上角可切换下载源（官方源 / 华为云 / 阿里云 / 腾讯云），国内网络建议选国内源。
下载完成后点击「导入」，镜像加入容器列表，选中即可使用。

已下载的镜像可重复导入；左滑可删除已下载的镜像文件。

方式二：手动导入镜像文件

需要特定版本或发行版时，可自行准备 rootfs 镜像导入。

镜像要求：

压缩格式：.tar.gz、.tgz、.tar.xz、.txz
内容须为完整的 Linux rootfs（文件系统根目录，包含 /bin/sh 或其它 shell）
架构须与设备匹配：ARM64 设备用 aarch64 镜像，x86 设备用 x86_64 镜像

镜像来源：

Alpine（体积小、启动快）：https://alpine.linuxhub.cn/alpine/edge/releases/，在 aarch64 目录下选 alpine-minirootfs-*-aarch64.tar.gz
Ubuntu：https://cdimage.ubuntu.com/ubuntu-base/releases/，选 ubuntu-base-*-base-arm64.tar.gz
Debian：可从 Docker Hub 官方镜像（如 arm64v8/debian）导出

具备 Docker 环境时，可从任意镜像导出 rootfs：

bash

docker pull debian:bookworm
docker create --name temp-rootfs debian:bookworm
docker export temp-rootfs | gzip > debian-rootfs.tar.gz
docker rm temp-rootfs

也可在已有 Linux 环境中用 debootstrap（Debian / Ubuntu）或 alpine-make-rootfs（Alpine）自行制作。

导入步骤：

打开「设置 → 容器与镜像」，点击右上角 +，选「本地镜像」。
填写配置：
- 名称：镜像配置的别名。
- shell 路径：容器内 shell，如 /bin/sh 或 /bin/bash。
- 镜像文件：选择准备好的 rootfs 文件。保存时会复制一份到 App 私有目录，此后重置容器均从该副本重新解压，不依赖原始文件；删除镜像时副本一并清理。
- 挂载（可选）：将手机目录挂进容器，见下文「把手机目录挂给 AI 用」。
- proot 参数（可选）：逐项添加，原样追加到 PRoot 启动参数。
- 环境变量（可选）：注入容器内进程的键值对。
保存后在列表中选中该配置，即切换为自定义容器。

首次使用自定义镜像时 App 会解压 rootfs 到私有目录，耗时取决于镜像大小。自定义镜像默认不配置国内软件源，可在首次进入终端的初始化菜单中切换。

常见问题排查

安装软件报错：由容器内硬链接不可用导致。编辑镜像 → proot 参数 → 添加 --link2symlink → 保存，重新进入终端。使用内置下载功能导入的镜像已默认带有该参数。

方向键显示为 ^[[A：当前 shell 为 sh，不支持行编辑。编辑容器，将 Shell 改为 /bin/bash，即可获得方向键、历史记录与补全。

把手机目录挂给 AI 用

AI 运行在容器内，默认只能看到工作区，无法访问手机公共存储。如需访问，需将手机目录挂进容器：

确认存储权限已授权。首次使用时会弹出权限请求；若此前拒绝过，前往系统设置 → 应用 → AiCode → 权限 → 存储开启。
打开「设置 → 容器与镜像」，编辑当前使用的容器。
在「挂载」中添加一条：本地目录填手机上的路径（如 /sdcard/Download），容器目录填容器内路径（如 /mnt/Download）。
保存后重启终端会话，AI 即可通过容器内路径访问。

按需挂载

仅挂载需要的子目录，不要直接挂载整个 /sdcard——那会将手机中所有文件暴露给 AI，存在隐私泄露风险。

例：如需让 AI 查看 App 日志，将本地目录 /storage/emulated/0/Android/data/com.aicode/ 挂到容器 /mnt/aicode，即可读取 /mnt/aicode/files/logs/ 下的日志。注意 Android/data/ 下只能访问 AiCode 自身的目录，其他应用的目录受分区存储限制无法访问。

如需处理的仅为单个文件，更简便的方式是将其复制进工作区，AI 默认即可访问。

全部删除后的行为

即使删除所有容器（包括内置 Alpine），App 仍可正常使用——AI 执行命令时会回退到内置 Alpine 作为默认执行环境。重新打开「容器与镜像」页，可在空状态页面一键恢复内置 Alpine 或添加新镜像。

容器与镜像 ​

容器列表 ​

内置 Alpine 容器 ​

首次进终端的初始化菜单 ​

软件源选择 ​

随时安装开发依赖（aicode） ​

自定义镜像 ​

方式一：内置镜像下载（推荐） ​

方式二：手动导入镜像文件 ​

常见问题排查 ​

把手机目录挂给 AI 用 ​

全部删除后的行为 ​