mirror of
https://github.com/Gitlawb/openclaude.git
synced 2026-08-24 10:14:19 -05:00
JATMNandGitHub
94e8ff3941
* chore: centralize Bun version and refresh CI tool pins - add .bun-version as the shared Bun source of truth for workflows and Docker builds - update PR and release workflows to read Bun from bun-version-file - refresh pinned GitHub Actions and Docker action SHAs to newer low-risk releases - align contributor docs with Bun 1.3.13 guidance * test: stabilize reset and provider profile persistence Harden knowledge graph reset behavior across Windows file-lock scenarios by improving SQLite and JSON reset signaling, preserving a safe JSON source of truth when SQLite cannot be cleared, and adding direct storage regression coverage. Also centralize deterministic config-home handling for tests, tighten provider profile persistence path resolution and cleanup semantics, isolate environment-sensitive suites with the env mutex, and remove flaky external npx dependency from the SDK consumer type test. * test: fix Codex OAuth callback flake Investigate the real provider smoke failure from GitHub Actions and fix the root cause instead of patching the symptom. - make Codex OAuth callback host explicit and consistent across redirect URI generation and listener binding - allow safe loopback host overrides for localhost, 127.0.0.1, and ::1 - harden Codex OAuth tests with env/fetch isolation so they do not poison neighboring provider suites - pin the OAuth callback tests to 127.0.0.1 to avoid localhost IPv4/IPv6 family mismatch flakes in CI Validated with bun test src/services/api/codexOAuth.test.ts, bun test src/services/api/providerConfig.codexSecureStorage.test.ts, and bun run test:provider. * test: harden Codex OAuth callback tests Investigate the recurring provider-smoke OAuth failures across multiple PR runs and fix the flaky callback test design at the root. - remove the free-port reservation race from Codex OAuth tests - add bounded callback retry only for loopback listener warm-up during the in-process OAuth test flow - move ephemeral callback port support into an explicit CodexOAuthService test seam instead of widening production env parsing - keep runtime callback-port semantics unchanged while adding regression coverage for callback host and port parsing Validated with targeted Codex OAuth tests and repeated provider-bucket reruns to check for recurring flake. * test: serialize provider shared-state suites Fix the recurring provider smoke flake at the root cause by serializing test suites that mutate process.env or globalThis.fetch. Add a shared test mutation lock and wire it into the provider bucket so Codex OAuth no longer races with unrelated provider/config/openai shim tests under Bun's parallel test execution. Cleanup now releases the lock in finally blocks, and the shared lock waits indefinitely by default to avoid timeout-based CI flakes. * test: fix smoke root causes and noisy suites Replace the Codex OAuth test's live loopback listener dependency with an injected listener seam, avoid module-mock leakage across provider suites, and clean up the auth-code listener test setup. Also harden noisy storage and search tests by asserting expected log output, isolating SQLite masterpiece persistence per test cwd, and removing routine benchmark/stress logging from passing runs. * build: harden Bun version install in Docker Validate the repo-tracked .bun-version value before using it in the Docker build stage, strip line endings, and install Bun through a quoted semver-only variable instead of raw shell expansion. * test: replace flaky conversation arc benchmark Fix the recurring smoke failure caused by an absolute wall-clock assertion in the normal unit suite. Replace the CI-speed-sensitive conversation arc benchmark with deterministic regression coverage that verifies repeated fact extraction, expected entity shapes, bounded graph growth, and populated-summary behavior. * test: isolate shared-state smoke suites * test: restore codex credential mocks between suites * test: fix shared-state and provider init-order flakes * test: isolate remaining shared-state smoke suites Serialize the remaining smoke-sensitive suites that mutate process env, CLAUDE_CONFIG_DIR, fetch, or SDK session globals. Add shared lock coverage to discovery, agent/skills loading, platform storage, and SDK lifecycle/preserved-segment tests. Restore session and cwd state inside the lock boundary so parallel files cannot leak bootstrap state into knowledge graph and SDK isolation tests. Validated with repeated smoke and full-suite passes: - bun run smoke (2x) - bun test - bun test --max-concurrency=1 - bun run test:provider - python -m pytest -q python/tests - npm run test:provider-recommendation
163 lines
3.9 KiB
Markdown
163 lines
3.9 KiB
Markdown
# OpenClaude on Android (Termux)
|
||
|
||
A complete guide to running OpenClaude on Android using Termux + proot Ubuntu.
|
||
|
||
---
|
||
|
||
## Prerequisites
|
||
|
||
- Android phone with ~700MB free storage
|
||
- [Termux](https://f-droid.org/en/packages/com.termux/) installed from **F-Droid** (not Play Store)
|
||
- An [OpenRouter](https://openrouter.ai) API key (free, no credit card required)
|
||
|
||
---
|
||
|
||
## Why This Setup?
|
||
|
||
OpenClaude requires [Bun](https://bun.sh) to build, and Bun does not support Android natively. The workaround is running a real Ubuntu environment inside Termux via `proot-distro`, where Bun's Linux binary works correctly.
|
||
|
||
---
|
||
|
||
## Installation
|
||
|
||
### Step 1 — Update Termux
|
||
|
||
```bash
|
||
pkg update && pkg upgrade
|
||
```
|
||
|
||
Press `N` or Enter for any config file conflict prompts.
|
||
|
||
### Step 2 — Install dependencies
|
||
|
||
```bash
|
||
pkg install nodejs-lts git proot-distro
|
||
```
|
||
|
||
Verify Node.js:
|
||
```bash
|
||
node --version # should be v20+
|
||
```
|
||
|
||
### Step 3 — Clone OpenClaude
|
||
|
||
```bash
|
||
git clone https://github.com/Gitlawb/openclaude.git
|
||
cd openclaude
|
||
npm install
|
||
npm link
|
||
```
|
||
|
||
### Step 4 — Install Ubuntu via proot
|
||
|
||
```bash
|
||
proot-distro install ubuntu
|
||
```
|
||
|
||
This downloads ~200–400MB. Wait for it to complete.
|
||
|
||
### Step 5 — Install Bun inside Ubuntu
|
||
|
||
```bash
|
||
proot-distro login ubuntu
|
||
curl -fsSL https://bun.sh/install | bash
|
||
source ~/.bashrc
|
||
bun --version # should show 1.3.13+
|
||
```
|
||
|
||
### Step 6 — Build OpenClaude
|
||
|
||
```bash
|
||
cd /data/data/com.termux/files/home/openclaude
|
||
bun run build
|
||
```
|
||
|
||
You should see:
|
||
```
|
||
✓ Built openclaude v0.1.6 → dist/cli.mjs
|
||
```
|
||
|
||
### Step 7 — Save env vars permanently
|
||
|
||
Still inside Ubuntu, add your OpenRouter config to `.bashrc`:
|
||
|
||
```bash
|
||
echo 'export CLAUDE_CODE_USE_OPENAI=1' >> ~/.bashrc
|
||
echo 'export OPENAI_API_KEY=your_openrouter_key_here' >> ~/.bashrc
|
||
echo 'export OPENAI_BASE_URL=https://openrouter.ai/api/v1' >> ~/.bashrc
|
||
echo 'export OPENAI_MODEL=qwen/qwen3.6-plus-preview:free' >> ~/.bashrc
|
||
source ~/.bashrc
|
||
```
|
||
|
||
Replace `your_openrouter_key_here` with your actual key from [openrouter.ai/keys](https://openrouter.ai/keys).
|
||
|
||
### Step 8 — Run OpenClaude
|
||
|
||
```bash
|
||
node dist/cli.mjs
|
||
```
|
||
|
||
Select **3** (3rd-party platform) at the login screen. Your env vars will be detected automatically.
|
||
|
||
---
|
||
|
||
## Restarting After Closing Termux
|
||
|
||
Every time you reopen Termux after killing it, run:
|
||
|
||
```bash
|
||
proot-distro login ubuntu
|
||
cd /data/data/com.termux/files/home/openclaude
|
||
node dist/cli.mjs
|
||
```
|
||
|
||
---
|
||
|
||
## Recommended Free Model
|
||
|
||
**`qwen/qwen3.6-plus-preview:free`** — Best free model on OpenRouter as of April 2026.
|
||
|
||
- 1M token context window
|
||
- Beats Claude 4.5 Opus on Terminal-Bench 2.0 agentic coding (61.6 vs 59.3)
|
||
- Built-in chain-of-thought reasoning
|
||
- Native tool use and function calling
|
||
- $0/M tokens (preview period)
|
||
|
||
> ⚠️ Free status may change when the preview period ends. Check [openrouter.ai](https://openrouter.ai/qwen/qwen3.6-plus-preview:free) for current pricing.
|
||
|
||
---
|
||
|
||
## Alternative Free Models (OpenRouter)
|
||
|
||
| Model ID | Context | Notes |
|
||
|---|---|---|
|
||
| `qwen/qwen3-coder:free` | 262K | Best for pure coding tasks |
|
||
| `openai/gpt-oss-120b:free` | 131K | OpenAI open model, strong tool calling |
|
||
| `nvidia/nemotron-3-super-120b-a12b:free` | 262K | Hybrid MoE, good general use |
|
||
| `meta-llama/llama-3.3-70b-instruct:free` | 66K | Reliable, widely tested |
|
||
|
||
Switch models anytime:
|
||
```bash
|
||
export OPENAI_MODEL=qwen/qwen3-coder:free
|
||
node dist/cli.mjs
|
||
```
|
||
|
||
---
|
||
|
||
## Why Not Groq or Cerebras?
|
||
|
||
Both were tested and fail due to OpenClaude's large system prompt (~50K tokens):
|
||
|
||
- **Groq free tier**: TPM limits too low (6K–12K tokens/min)
|
||
- **Cerebras free tier**: TPM limits exceeded, even on `llama3.1-8b`
|
||
|
||
OpenRouter free models have no TPM restrictions — only 20 req/min and 200 req/day.
|
||
|
||
---
|
||
|
||
## Tips
|
||
|
||
- **Don't swipe Termux away** from recent apps mid-session — use the home button to minimize instead.
|
||
- The Ubuntu environment persists between Termux sessions; your build and config are saved.
|
||
- Run `bun run build` again only if you pull updates to the OpenClaude repo.
|