263 lines
6.3 KiB
Markdown
263 lines
6.3 KiB
Markdown
# ClaudeX Proxy Setup
|
||
|
||
Idempotent Windows setup for running Claude Code through [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) with Codex OAuth authentication.
|
||
|
||
The script installs and configures the proxy, adds a `claudex` PowerShell command with model aliases, and keeps the proxy running through Task Scheduler.
|
||
|
||
> BIG NOTE: Claude Code doesn’t properly compact context. This means that once you hit 100% of the model’s context limit, you can no longer compact it, because the compaction task itself would exceed the limit.
|
||
> Keep an eye on `/context`, and don’t trust the maximum Claude Code shows you. It’s probably different.
|
||
|
||
|
||
## What it does
|
||
|
||
`setup-claudex-proxy.ps1`:
|
||
|
||
- Checks whether the `claude` command is installed.
|
||
- Installs Claude Code through its Windows installer when missing.
|
||
- Downloads CLIProxyAPI `v7.2.71` for Windows x64.
|
||
- Extracts it into:
|
||
|
||
```text
|
||
C:\Program Files\CLIProxyAPI_7.2.71_windows_amd64
|
||
```
|
||
|
||
- Creates a localhost-only `config.yaml` on port `8317`.
|
||
- Stores Codex OAuth credentials under:
|
||
|
||
```text
|
||
%USERPROFILE%\.cli-proxy-api
|
||
```
|
||
|
||
- Adds a managed `claudex` function to Windows PowerShell and PowerShell 7 profiles.
|
||
- Adds the model aliases `sol`, `terra`, and `luna`.
|
||
- Opens Codex OAuth login only when no existing Codex credential is detected.
|
||
- Creates or updates a Task Scheduler task named `CLIProxyAPI`.
|
||
- Starts the proxy at boot under the current Windows user.
|
||
- Restarts the proxy if it exits.
|
||
- Verifies that port `8317` is listening.
|
||
- Skips completed steps when rerun.
|
||
|
||
## Requirements
|
||
|
||
- Windows 10 or Windows 11, x64
|
||
- PowerShell 5.1 or newer
|
||
- Administrator access
|
||
- Internet access
|
||
- A ChatGPT account with Codex access
|
||
|
||
The script automatically requests elevation through UAC.
|
||
|
||
## Installation
|
||
|
||
Download or clone the repository, then open PowerShell in the repository directory:
|
||
|
||
```powershell
|
||
Unblock-File .\setup-claudex-proxy.ps1
|
||
powershell -ExecutionPolicy Bypass -File .\setup-claudex-proxy.ps1
|
||
```
|
||
|
||
The script may open a browser for Codex OAuth authentication.
|
||
|
||
After setup finishes, open a new PowerShell window.
|
||
|
||
## Usage
|
||
|
||
Run Claude Code using one of the configured aliases:
|
||
|
||
```powershell
|
||
claudex sol
|
||
claudex terra
|
||
claudex luna
|
||
```
|
||
|
||
Additional Claude Code arguments are passed through:
|
||
|
||
```powershell
|
||
claudex sol --dangerously-skip-permissions
|
||
```
|
||
|
||
A complete model name can also be used directly:
|
||
|
||
```powershell
|
||
claudex gpt-5.6-sol
|
||
```
|
||
|
||
The default model is `sol`, so this also works:
|
||
|
||
```powershell
|
||
claudex
|
||
```
|
||
|
||
## Options
|
||
|
||
Force CLIProxyAPI to be downloaded and installed again:
|
||
|
||
```powershell
|
||
.\setup-claudex-proxy.ps1 -ForceReinstall
|
||
```
|
||
|
||
Skip the interactive Codex login:
|
||
|
||
```powershell
|
||
.\setup-claudex-proxy.ps1 -SkipCodexLogin
|
||
```
|
||
|
||
Configure everything without starting the scheduled task:
|
||
|
||
```powershell
|
||
.\setup-claudex-proxy.ps1 -NoStart
|
||
```
|
||
|
||
Options can be combined:
|
||
|
||
```powershell
|
||
.\setup-claudex-proxy.ps1 -ForceReinstall -NoStart
|
||
```
|
||
|
||
## Files created
|
||
|
||
```text
|
||
C:\Program Files\CLIProxyAPI_7.2.71_windows_amd64\
|
||
├── cli-proxy-api.exe
|
||
├── config.yaml
|
||
├── run-proxy.ps1
|
||
├── proxy-watchdog.log
|
||
└── logs\
|
||
```
|
||
|
||
PowerShell profile blocks are written to the applicable paths below:
|
||
|
||
```text
|
||
Documents\WindowsPowerShell\profile.ps1
|
||
Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1
|
||
Documents\PowerShell\profile.ps1
|
||
Documents\PowerShell\Microsoft.PowerShell_profile.ps1
|
||
```
|
||
|
||
The generated section is wrapped in markers so rerunning the setup updates it instead of duplicating it.
|
||
|
||
## Task Scheduler
|
||
|
||
The script creates a task named:
|
||
|
||
```text
|
||
CLIProxyAPI
|
||
```
|
||
|
||
Check its status:
|
||
|
||
```powershell
|
||
Get-ScheduledTask -TaskName CLIProxyAPI
|
||
Get-ScheduledTaskInfo -TaskName CLIProxyAPI
|
||
```
|
||
|
||
Start or stop it manually:
|
||
|
||
```powershell
|
||
Start-ScheduledTask -TaskName CLIProxyAPI
|
||
Stop-ScheduledTask -TaskName CLIProxyAPI
|
||
```
|
||
|
||
Check whether the proxy is listening:
|
||
|
||
```powershell
|
||
Test-NetConnection 127.0.0.1 -Port 8317
|
||
```
|
||
|
||
## Custom model aliases
|
||
|
||
Edit the managed alias table in your PowerShell profile:
|
||
|
||
```powershell
|
||
$global:ClaudeModelAliases = @{
|
||
sol = 'gpt-5.6-sol'
|
||
terra = 'gpt-5.6-terra'
|
||
luna = 'gpt-5.6-luna'
|
||
}
|
||
```
|
||
|
||
Then reload the current profile:
|
||
|
||
```powershell
|
||
. $PROFILE
|
||
```
|
||
|
||
Rerunning the setup script restores the aliases defined inside the installer.
|
||
|
||
## Re-running and existing installations
|
||
|
||
The setup is intended to be idempotent:
|
||
|
||
- Existing Claude Code installations are skipped.
|
||
- Existing CLIProxyAPI binaries are skipped unless `-ForceReinstall` is used.
|
||
- Existing Codex credentials are reused.
|
||
- The scheduled task is replaced only when its configuration differs.
|
||
- Managed PowerShell profile blocks are updated in place.
|
||
- A different existing `config.yaml` is backed up before replacement.
|
||
|
||
Configuration backups use names such as:
|
||
|
||
```text
|
||
config.yaml.bak-20260712-193000
|
||
```
|
||
|
||
## Troubleshooting
|
||
|
||
### `claudex` is not recognized
|
||
|
||
Open a new PowerShell window or reload the profile:
|
||
|
||
```powershell
|
||
. $PROFILE
|
||
```
|
||
|
||
### Port 8317 is not listening
|
||
|
||
Check the scheduled task and logs:
|
||
|
||
```powershell
|
||
Get-ScheduledTaskInfo -TaskName CLIProxyAPI
|
||
Get-Content "C:\Program Files\CLIProxyAPI_7.2.71_windows_amd64\proxy-watchdog.log" -Tail 100
|
||
```
|
||
|
||
CLIProxyAPI application logs are stored under:
|
||
|
||
```text
|
||
C:\Program Files\CLIProxyAPI_7.2.71_windows_amd64\logs
|
||
```
|
||
|
||
### OAuth login needs to be repeated
|
||
|
||
Run:
|
||
|
||
```powershell
|
||
& "C:\Program Files\CLIProxyAPI_7.2.71_windows_amd64\cli-proxy-api.exe" `
|
||
-config "C:\Program Files\CLIProxyAPI_7.2.71_windows_amd64\config.yaml" `
|
||
-codex-login
|
||
```
|
||
|
||
Then restart the task:
|
||
|
||
```powershell
|
||
Stop-ScheduledTask -TaskName CLIProxyAPI
|
||
Start-ScheduledTask -TaskName CLIProxyAPI
|
||
```
|
||
|
||
### Remove the scheduled task
|
||
|
||
```powershell
|
||
Unregister-ScheduledTask -TaskName CLIProxyAPI -Confirm:$false
|
||
```
|
||
|
||
The installation directory, OAuth credentials, and profile block must be removed separately.
|
||
|
||
## Security and compatibility
|
||
|
||
The generated proxy configuration binds only to `127.0.0.1`. Do not expose port `8317` to your LAN or the public internet without proper authentication and network controls.
|
||
|
||
CLIProxyAPI is a third-party project. This repository is not affiliated with OpenAI, Anthropic, Claude Code, or CLIProxyAPI. Provider behavior, model availability, OAuth flows, subscription limits, and terms may change. Review the relevant terms before use.
|
||
|
||
## License
|
||
|
||
This project is licensed under the MIT License. See [LICENSE](LICENSE).
|