docs: add English README

README.en-US.md

@@ -0,0 +1,124 @@
+# Foxcode Unified Cache Proxy
+
+A unified proxy designed to optimize cache hit rates for Foxcode API requests.
+
+## Features
+
+- ✅ **Claude Channel** - Injects `metadata.user_id` to enable Prompt caching
+- ✅ **Codex Channel** - Removes dynamic timestamps + injects `prompt_cache_key` to stabilize prefix caching
+- ✅ **Gemini Channel** - Removes dynamic timestamps + v1beta path conversion
+- ✅ Multi-channel routing support
+- ✅ Automatic retry for network exceptions
+- ✅ Health check endpoint
+- ✅ Streaming response support
+- ✅ Systemd service configuration
+
+## Background
+
+### Claude Caching
+Foxcode requires the `metadata.user_id` field in the request to enable Prompt caching.
+
+### Codex Caching
+The OpenAI Codex API uses automatic prefix caching, but `@mariozechner/pi-coding-agent`'s `buildSystemPrompt()` injects a dynamic timestamp (`Current date and time: ...`) in every request, causing the prefix to never match. This proxy removes that timestamp to stabilize the cache.
+
+### Gemini Caching
+Gemini 2.5+ supports implicit caching, which similarly requires the removal of dynamic timestamps.
+
+> ⚠️ **Note: The Gemini channel on the foxcode relay does not support implicit caching and is currently unavailable. Please test independently with other relays.**
+
+## Installation
+
+```bash
+git clone https://github.com/1034378361/foxcode-cache-proxy.git
+cd foxcode-cache-proxy
+```
+
+## Usage
+
+### Direct Run
+
+```bash
+node proxy.js
+```
+
+### Multi-Channel Routing
+
+| Channel Type | Path Prefix | Handling Method |
+|--------------|-------------|-----------------|
+| Claude       | `/droid`, `/aws`, `/super`, `/ultra` | Inject `metadata.user_id` |
+| Codex        | `/codex` | Remove timestamp + inject `prompt_cache_key` |
+| Gemini       | `/gemini` | Remove timestamp + add `/v1beta` prefix |
+
+### Environment Variable Configuration
+
+| Variable | Default Value | Description |
+|----------|---------------|-------------|
+| `PROXY_PORT` | 18800 | Port the proxy listens on |
+| `TARGET_HOST` | code.newcli.com | Foxcode API address |
+| `USER_ID` | openclaw-user | User identifier for Claude caching |
+| `RETRY_MAX` | 3 | Maximum number of retries |
+| `RETRY_DELAY` | 1000 | Initial retry delay (ms) |
+| `TIMEOUT_MS` | 180000 | Request timeout (ms) |
+
+### Systemd Service (Recommended)
+
+```bash
+# Copy service file
+cp foxcode-proxy.service ~/.config/systemd/user/
+
+# Enable and start
+systemctl --user daemon-reload
+systemctl --user enable foxcode-proxy
+systemctl --user start foxcode-proxy
+
+# Check status
+systemctl --user status foxcode-proxy
+journalctl --user -u foxcode-proxy -f
+```
+
+## Configuration Example
+
+### OpenClaw
+
+Modify `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "models": {
+    "providers": {
+      "foxcode-droid": {
+        "baseUrl": "http://127.0.0.1:18800/droid",
+        "apiKey": "your-api-key",
+        "api": "anthropic-messages"
+      },
+      "foxcode-codex": {
+        "baseUrl": "http://127.0.0.1:18800/codex",
+        "apiKey": "your-api-key",
+        "api": "openai-responses"
+      }
+    }
+  }
+}
+```
+
+## Health Check
+
+```bash
+curl http://127.0.0.1:18800/health
+# {"status":"ok","codexSessions":0,"timestamp":1234567890}
+```
+
+## Cache Effects
+
+### Codex Cache Hit Example
+```
+🟢 [CACHE] Removed timestamp from instructions (16124 -> 16055)
+🟢 [CACHE] Timestamp removed for stable caching
+```
+
+### Claude Cache Hit
+Enabled via `metadata.user_id`; cache information can be found in the `usage` field of the API response.
+
+## License
+
+MIT