OpenCode 在 Termux 上的运行架构
OpenCode (opencode-ai) 是 Bun 编译的单文件 CLI 工具，在 Termux 上通过 glibc-runner 兼容层运行。
完整教程已发布至 GitHub: https://github.com/leemwood/opencode-android-guide
为什么需要特殊处理
OpenCode 的 Linux ARM64 二进制是标准 glibc ELF（Bun 编译，内嵌 Node.js 运行时）。Android 使用 bionic libc，无法直接执行。需通过 glibc-runner (grun) 兼容层运行。
安装速览
前置条件
pkg install glibc-runner glibc glibc-libstdc++ nodejs-lts proot
手动安装（推荐）
# 1. 下载二进制（从 opencode-linux-arm64 npm 子包）
npm pack opencode-linux-arm64 --pack-destination /tmp/
cd $PREFIX/bin
tar xzf /tmp/opencode-linux-arm64-*.tgz --strip-components=2 package/bin/opencode
mv opencode opencode.real
# 2. 创建 grun 包装脚本
cat > $PREFIX/bin/opencode << 'EOF'
#!/data/data/com.termux/files/usr/bin/bash
exec grun $PREFIX/bin/opencode.real "$@"
EOF
chmod +x $PREFIX/bin/opencode
# 3. 验证
opencode --version
# 4. 安装插件层（首次运行自动创建，也可手动准备）
mkdir -p ~/.config/opencode
cd ~/.config/opencode
echo '{"dependencies":{"@opencode-ai/plugin":"最新版本号"}}' > package.json
npm install
npm meta 包结构
opencode-ai— meta 包（7.9KB），通过optionalDependencies按平台拉取子包opencode-linux-arm64— ARM64 Linux 子包（~69MB 压缩，~188MB 解压），仅含bin/opencode二进制
架构层次
opencode 命令 ($PREFIX/bin/opencode)
└─ bash 包装脚本 → grun $PREFIX/bin/opencode.real
└─ glibc-runner 兼容层
└─ opencode.real (175MB Bun-compiled ELF)
└─ 加载 ~/.config/opencode/node_modules/@opencode-ai/plugin/
文件布局
| 路径 | 用途 |
|---|---|
$PREFIX/bin/opencode |
bash 包装脚本，调用 grun $PREFIX/bin/opencode.real "$@" |
$PREFIX/bin/opencode.real |
主程序本体，Bun 编译的 64-bit ARM ELF（~175MB），内含 Node.js 运行时 |
~/.config/opencode/package.json |
npm 依赖声明，锁定 @opencode-ai/plugin 版本 |
~/.config/opencode/node_modules/@opencode-ai/plugin/ |
插件代码（TypeScript 编译产物在 dist/） |
~/.config/opencode/opencode.jsonc |
用户配置（模型、权限等） |
~/.local/share/opencode/opencode.db |
SQLite 数据库（session、状态持久化） |
~/.local/share/opencode/log/opencode.log |
运行日志（JSON 行格式） |
二进制特征识别
file $PREFIX/bin/opencode.real
# ELF 64-bit LSB executable, ARM aarch64, dynamically linked,
# interpreter /lib/ld-linux-aarch64.so.1
readelf -d $PREFIX/bin/opencode.real | grep NEEDED
# libc.so.6, ld-linux-aarch64.so.1, libpthread.so.0, libdl.so.2, libm.so.6
strings $PREFIX/bin/opencode.real | grep -i bun | head -3
# BUN_1.2 ← 确认是 Bun 编译产物
# node_api_* 符号也大量存在（内嵌 Node.js 运行时）
配置结构
~/.config/opencode/opencode.jsonc 最小示例：
{
"$schema": "https://opencode.ai/config.json"
}
插件配置在 ~/.config/opencode/node_modules/@opencode-ai/plugin/：
- dist/index.js — 主入口
- dist/tool.js — 工具定义
- dist/tui.js — 终端 UI
- dist/v2/effect/ — Effect 框架集成
依赖链：@opencode-ai/sdk + @ai-sdk/provider + effect + zod
运行时行为（从日志可见）
日志位于 ~/.local/share/opencode/log/opencode.log，JSON 行格式：
timestamp=... level=INFO run=<id> message="creating instance" directory=...
timestamp=... level=INFO run=<id> message="shell tool using shell" shell=.../glibc/bin/bash
timestamp=... level=INFO run=<id> message=stream providerID=opencode-go modelID=deepseek-v4-pro
关键特征：
- Shell: 使用 glibc bash（$PREFIX/glibc/bin/bash），不是 Termux 原生 bash
- Provider: opencode-go（OpenCode SDK Go 实现）
- Model: 默认 deepseek-v4-pro
- 文件监控: inotify backend（Linux 内核原生）
- LSP/Formatter: 默认全部禁用
- Session: 自动创建，格式 ses_<id>
版本更新
# 更新二进制
npm pack opencode-linux-arm64 --pack-destination /tmp/
cd $PREFIX/bin
tar xzf /tmp/opencode-linux-arm64-*.tgz --strip-components=2 package/bin/opencode
mv opencode opencode.real
# 更新插件层
cd ~/.config/opencode && npm install @opencode-ai/plugin@latest
常见问题
FFF 初始化警告
level=WARN message="failed to initialize fff"
error="Can not run certain FFF features in a file system root or home directories."
文件选择器（fff = fast file finder）在 home 目录下有限制，不影响功能。在具体项目目录下运行以避免此警告。
models.dev 超时
level=ERROR message="Failed to fetch models.dev" cause=Cause([Fail(TimeoutError)])
网络问题导致模型列表拉取失败，不影响已配置模型的使用。
No such file or directory 错误
二进制是 glibc ELF，检查 grun 是否安装 (pkg list-installed | grep glibc-runner) 和包装脚本是否正确。
/tmp 写入权限
Termux /tmp 为 shell:shell 属主，app 用户无写权限。修复：
export TMPDIR="$PREFIX/tmp"
export TMP="$PREFIX/tmp"
export TEMP="$PREFIX/tmp"
与其他技能的关联
- 安装过程 →
npm-glibc-meta（meta 包 + glibc ELF 通用模式） - npm 平台绕过 →
termux-cli-wrapper（--force+ proot/tmpbind mount） - glibc 包生态 →
termux-glibc-packages
