mirror of
https://github.com/Finesssee/ProxyPilot.git
synced 2026-11-18 18:04:20 +00:00
docs: rebrand to ProxyPilot with fork attribution
This commit is contained in:
@@ -0,0 +1,6 @@
|
||||
ProxyPilot
|
||||
|
||||
ProxyPilot is a fork and rebrand of the CLIProxyAPI project (the underlying proxy engine).
|
||||
|
||||
This repository is distributed under the MIT License; see LICENSE.
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
# CLI Proxy API
|
||||
# ProxyPilot (CLIProxyAPI fork)
|
||||
|
||||
English | [中文](README_CN.md)
|
||||
|
||||
A proxy server that provides OpenAI/Gemini/Claude/Codex compatible API interfaces for CLI.
|
||||
ProxyPilot is a desktop-friendly wrapper around the `CLIProxyAPI` proxy engine (this repo), focused on running and managing a local proxy with a tray app + installer.
|
||||
|
||||
It now also supports OpenAI Codex (GPT models) and Claude Code via OAuth.
|
||||
ProxyPilot is forked from the original **CLIProxyAPI** project and rebranded; the underlying engine remains compatible with OpenAI/Gemini/Claude/Codex-style clients and SDKs.
|
||||
|
||||
So you can use local or multi-account CLI access with OpenAI(include Responses)/Gemini/Claude-compatible clients and SDKs.
|
||||
Windows app packaging: `docs/proxypilot.md`
|
||||
|
||||
## Sponsor
|
||||
|
||||
@@ -16,7 +16,7 @@ This project is sponsored by Z.ai, supporting us with their GLM CODING PLAN.
|
||||
|
||||
GLM CODING PLAN is a subscription service designed for AI coding, starting at just $3/month. It provides access to their flagship GLM-4.6 model across 10+ popular AI coding tools (Claude Code, Cline, Roo Code, etc.), offering developers top-tier, fast, and stable coding experiences.
|
||||
|
||||
Get 10% OFF GLM CODING PLAN:https://z.ai/subscribe?ic=8JVLJQFSKB
|
||||
Get 10% OFF GLM CODING PLAN: https://z.ai/subscribe?ic=8JVLJQFSKB
|
||||
|
||||
## Overview
|
||||
|
||||
@@ -40,28 +40,27 @@ Get 10% OFF GLM CODING PLAN:https://z.ai/subscribe?ic=8JVLJQFSKB
|
||||
- OpenAI-compatible upstream providers via config (e.g., OpenRouter)
|
||||
- Reusable Go SDK for embedding the proxy (see `docs/sdk-usage.md`)
|
||||
|
||||
## Getting Started
|
||||
## Getting Started (Engine)
|
||||
|
||||
CLIProxyAPI Guides: [https://help.router-for.me/](https://help.router-for.me/)
|
||||
Upstream-style docs for the engine live here:
|
||||
|
||||
- CLIProxyAPI Guides: https://help.router-for.me/
|
||||
- Management API: https://help.router-for.me/management/api
|
||||
|
||||
## Cursor IDE
|
||||
|
||||
- Integration guide: [docs/cursor-ide.md](docs/cursor-ide.md)
|
||||
- Integration guide: `docs/cursor-ide.md`
|
||||
|
||||
## Compatibility
|
||||
|
||||
- Quick matrix: [docs/compat-matrix.md](docs/compat-matrix.md)
|
||||
|
||||
## Management API
|
||||
|
||||
see [MANAGEMENT_API.md](https://help.router-for.me/management/api)
|
||||
- Quick matrix: `docs/compat-matrix.md`
|
||||
|
||||
## SDK Docs
|
||||
|
||||
- Usage: [docs/sdk-usage.md](docs/sdk-usage.md)
|
||||
- Advanced (executors & translators): [docs/sdk-advanced.md](docs/sdk-advanced.md)
|
||||
- Access: [docs/sdk-access.md](docs/sdk-access.md)
|
||||
- Watcher: [docs/sdk-watcher.md](docs/sdk-watcher.md)
|
||||
- Usage: `docs/sdk-usage.md`
|
||||
- Advanced (executors & translators): `docs/sdk-advanced.md`
|
||||
- Access: `docs/sdk-access.md`
|
||||
- Watcher: `docs/sdk-watcher.md`
|
||||
- Custom Provider Example: `examples/custom-provider`
|
||||
|
||||
## Contributing
|
||||
@@ -94,9 +93,10 @@ CLI wrapper for instant switching between multiple Claude accounts and alternati
|
||||
|
||||
Native macOS GUI for managing CLIProxyAPI: configure providers, model mappings, and endpoints via OAuth - no API keys needed.
|
||||
|
||||
> [!NOTE]
|
||||
> [!NOTE]
|
||||
> If you developed a project based on CLIProxyAPI, please open a PR to add it to this list.
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
||||
This project is licensed under the MIT License - see `LICENSE`.
|
||||
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
# Desktop UI for CLIProxyAPI — Shared Spec (Windows first)
|
||||
# Desktop UI (ProxyPilot) — Shared Spec (Windows first)
|
||||
|
||||
This doc captures shared architecture and product decisions for a desktop “controller app” that manages a local `CLIProxyAPI` instance. OS-specific details live in:
|
||||
This doc captures shared architecture and product decisions for a desktop “controller app” that manages a local `CLIProxyAPI` instance.
|
||||
|
||||
OS-specific details live in:
|
||||
|
||||
- Windows: `docs/windows-ui-spec.md`
|
||||
- macOS (future): `docs/macos-ui-spec.md` (not yet)
|
||||
@@ -9,7 +11,7 @@ This doc captures shared architecture and product decisions for a desktop “con
|
||||
|
||||
A small tray-first desktop app that can:
|
||||
|
||||
- start/stop/restart the local proxy
|
||||
- start/stop/restart the local proxy engine (CLIProxyAPI)
|
||||
- show health + port + “copy base URL” snippets for IDE/agentic CLIs
|
||||
- surface logs/request diagnostics to debug issues like 400/429, “prompt too long”, streaming quirks
|
||||
|
||||
@@ -33,7 +35,7 @@ We can support both Wails and Tauri without forking business logic by standardiz
|
||||
|
||||
## Shared control interface
|
||||
|
||||
### Proposed Go package
|
||||
### Go package
|
||||
|
||||
- `internal/desktopctl`
|
||||
- Pure Go logic for process management, config reading/writing, health, logs, autostart primitives.
|
||||
@@ -54,7 +56,7 @@ Wails can call `internal/desktopctl` directly; Tauri can call `cliproxyctl`.
|
||||
|
||||
### Core controls
|
||||
|
||||
- Start/Stop/Restart `CLIProxyAPI`.
|
||||
- Start/Stop/Restart the proxy engine.
|
||||
- Detect if a proxy is already running:
|
||||
- If owned by UI: show as “Managed”.
|
||||
- If not owned: show as “External” and offer “Attach” (read-only) vs “Stop anyway” behind a confirmation.
|
||||
@@ -109,7 +111,7 @@ Wails can call `internal/desktopctl` directly; Tauri can call `cliproxyctl`.
|
||||
|
||||
## Cross-platform notes
|
||||
|
||||
We should split OS-specific operations behind small interfaces in `internal/desktopctl`:
|
||||
Split OS-specific operations behind small interfaces in `internal/desktopctl`:
|
||||
|
||||
- Process operations (spawn, signal/terminate, pid discovery)
|
||||
- Autostart
|
||||
@@ -122,6 +124,6 @@ Windows and macOS implementations can live in separate files via Go build tags:
|
||||
|
||||
## Open questions
|
||||
|
||||
- Should the desktop app bundle `cliproxyapi-latest` or manage an existing install?
|
||||
- Should the desktop app bundle the engine binary, or manage an existing install?
|
||||
- Do we want a dedicated “desktop control” HTTP endpoint in the proxy (vs local process control only)?
|
||||
|
||||
|
||||
+21
-111
@@ -1,54 +1,29 @@
|
||||
# ProxyPilot (CLIProxyAPI Desktop + Agentic CLI Hardening)
|
||||
# ProxyPilot (Desktop wrapper for CLIProxyAPI)
|
||||
|
||||
ProxyPilot is the desktop-facing packaging/branding for running and managing a local `CLIProxyAPI` instance, with extra compatibility features for agentic CLIs (Factory Droid, Codex CLI, Warp).
|
||||
ProxyPilot is the desktop-facing packaging/branding for running and managing a local `CLIProxyAPI` instance, with extra compatibility features for agentic CLIs (Droid/Factory, Codex CLI, Warp).
|
||||
|
||||
This doc summarizes the current behavior and the key “quality of life” features added recently.
|
||||
ProxyPilot is a fork/rebrand of CLIProxyAPI: the engine is still `CLIProxyAPI`, and ProxyPilot is the Windows tray app + installer + updater UX around it.
|
||||
|
||||
## What’s included
|
||||
|
||||
- **ProxyPilot tray app (Windows)** to start/stop/restart the proxy, open UI, open logs, and toggle autostart.
|
||||
- **Droid/Factory reliability fixes** so tool calls are emitted consistently and errors show up even for strict streaming clients.
|
||||
- **Agentic prompt-budget middleware** to prevent upstream “prompt too long” failures.
|
||||
- **Long-session memory** with anchored summaries + persistent TODO + pinned state (local disk).
|
||||
- ProxyPilot tray app (Windows) to start/stop/restart the proxy engine, open the dashboard, open logs, and toggle autostart.
|
||||
- Prompt-budget middleware to reduce “prompt too long” failures in strict CLIs.
|
||||
- Long-session memory with pinned state + persistent TODO (local disk).
|
||||
- Optional auth debugging and cooldown reset endpoints for local troubleshooting.
|
||||
|
||||
## Quickstart (Windows)
|
||||
## Install / uninstall (Windows)
|
||||
|
||||
## Build/Package without PowerShell
|
||||
- Install: run `dist\\ProxyPilot-Setup.exe`
|
||||
- Launch: Start Menu → ProxyPilot
|
||||
- Uninstall: Settings → Apps → Installed apps → ProxyPilot → Uninstall
|
||||
|
||||
If you have Go installed, you can build/package from a single command (no `.ps1` scripts):
|
||||
## Build / package
|
||||
|
||||
- Build: `go run .\cmd\proxypilotpack build`
|
||||
- Zip: `go run .\cmd\proxypilotpack package-zip`
|
||||
- Installer (legacy, IExpress): `go run .\cmd\proxypilotpack package-setup`
|
||||
- Installer (recommended, Inno Setup): `go run .\cmd\proxypilotpack package-inno` (requires Inno Setup `ISCC.exe`)
|
||||
If you have Go installed:
|
||||
|
||||
### Build the proxy
|
||||
|
||||
- `.\scripts\build-cliproxyapi.ps1`
|
||||
|
||||
### Build ProxyPilot tray app
|
||||
|
||||
- `.\scripts\build-cliproxytray.ps1`
|
||||
|
||||
Output:
|
||||
|
||||
- `bin\ProxyPilot.exe`
|
||||
|
||||
### Package (zip)
|
||||
|
||||
- `.\scripts\package-cliproxytray.ps1`
|
||||
|
||||
Output:
|
||||
|
||||
- `dist\ProxyPilot.zip`
|
||||
|
||||
### Package (self-extracting installer)
|
||||
|
||||
- `.\scripts\package-cliproxytray-installer.ps1`
|
||||
|
||||
Output:
|
||||
|
||||
- `dist\ProxyPilot-Setup.exe`
|
||||
- Build binaries: `go run .\\cmd\\proxypilotpack build`
|
||||
- Package zip: `go run .\\cmd\\proxypilotpack package-zip` → `dist\\ProxyPilot.zip`
|
||||
- Package installer (recommended): `go run .\\cmd\\proxypilotpack package-inno` (requires Inno Setup `ISCC.exe`) → `dist\\ProxyPilot-Setup.exe`
|
||||
|
||||
## Endpoints / health
|
||||
|
||||
@@ -59,75 +34,14 @@ Example:
|
||||
|
||||
- `curl -H "Authorization: Bearer local-dev-key" http://127.0.0.1:<port>/v1/models`
|
||||
|
||||
## Agentic CLI compatibility (Droid / Codex / Warp)
|
||||
|
||||
### Tool-call correctness
|
||||
|
||||
For `/v1/responses` traffic from agentic CLIs, the proxy applies:
|
||||
|
||||
- Tool schema tightening (`additionalProperties:false`) to reduce invalid tool argument payloads.
|
||||
- Tool argument sanitization (strip unknown fields from tool call args).
|
||||
- Conversion of plain-text `<tool_call>{...}</tool_call>` blocks into structured Responses `function_call` items (when present).
|
||||
- If a Factory/Stainless client omits `tools`, the proxy injects a minimal `tools` set and forces `tool_choice:"auto"` so the model can emit tool calls.
|
||||
|
||||
### Streaming behavior (Factory/Stainless)
|
||||
|
||||
Some strict clients request `stream:true` but don’t reliably render JSON error bodies.
|
||||
For `factory-cli`/Stainless user agents, CLIProxyAPI may:
|
||||
|
||||
- Call upstream non-streaming and synthesize SSE so the client gets usable output/error text.
|
||||
|
||||
## Prompt budget (prevent “prompt too long”)
|
||||
|
||||
The `CodexPromptBudgetMiddleware` applies to agentic CLIs and will trim oversized requests:
|
||||
|
||||
- Keeps recent messages/input items
|
||||
- Truncates very large text blocks
|
||||
- Preserves tool call/result pairing to avoid “tool_use/tool_result mismatch” errors
|
||||
- Avoids disabling tools for Droid/Factory
|
||||
|
||||
Model-aware budget:
|
||||
|
||||
- If the chosen model has a small `context_length`, the middleware uses a smaller max body budget to reduce upstream failures.
|
||||
|
||||
Override:
|
||||
|
||||
- `CLIPROXY_AGENTIC_MAX_BODY_BYTES` (bytes, clamped)
|
||||
|
||||
## Long-session memory (anchored compression + retrieval)
|
||||
|
||||
See `docs/memory.md` for details.
|
||||
|
||||
Key points:
|
||||
|
||||
- Events are stored to `.proxypilot/memory/sessions/<sessionKey>/events.jsonl`
|
||||
- Anchored summary: `summary.md`
|
||||
- Pinned always-on state: `pinned.md`
|
||||
- Persistent TODO: `todo.md`
|
||||
|
||||
Session key precedence:
|
||||
|
||||
1. `X-CLIProxyAPI-Session`
|
||||
2. `X-Session-Id`
|
||||
3. JSON `prompt_cache_key`
|
||||
4. JSON `metadata.session_id` / `session_id`
|
||||
5. Hash fallback (auth+UA hashed; raw values not stored)
|
||||
|
||||
### Persistent TODO updates
|
||||
|
||||
You can update the TODO without touching files by sending:
|
||||
|
||||
- `X-CLIProxyAPI-Todo: <markdown>`
|
||||
|
||||
The proxy saves it to `todo.md` and strips the header before forwarding upstream.
|
||||
|
||||
## Autostart
|
||||
## Autostart toggles (tray)
|
||||
|
||||
ProxyPilot tray app can toggle:
|
||||
- “Launch on login” (starts ProxyPilot)
|
||||
- “Auto-start proxy” (starts `cliproxyapi-latest` when ProxyPilot launches)
|
||||
|
||||
On Windows this uses a per-user autostart mechanism (no admin required).
|
||||
- `Launch on login` (starts ProxyPilot)
|
||||
- `Auto-start proxy` (starts the proxy engine when ProxyPilot launches)
|
||||
|
||||
On Windows this uses a per-user Run entry (no admin required).
|
||||
|
||||
## Logs / diagnostics
|
||||
|
||||
@@ -137,7 +51,3 @@ Useful paths:
|
||||
- `logs/cliproxyapi.err.log`
|
||||
- `logs/v1-responses-*.log` / `logs/v1-chat-completions-*.log` (request logs, if enabled)
|
||||
|
||||
## Repo safety / public readiness
|
||||
|
||||
- `config.yaml`, auth files, logs, binaries, and memory state are gitignored.
|
||||
- Use `local-dev-key` only as an example; real keys should stay out of git.
|
||||
|
||||
Reference in New Issue
Block a user