Gistify
Kembali ke Beranda
Gistify Snippet
kyiov
@kyiov
Jul 15·1 file(s)
Public

A premium developer's guide to running Claude Code CLI for free using AgentRouter and HCNSEC (IAMHC) API proxies.

synced from github gist claude-proxy-guide.md

#tools
claude-proxy-guide.mdmarkdown
378 baris

Running Claude Code via Third-Party API Proxies

A comprehensive, step-by-step developer's guide to installing, configuring, and running Anthropic's Claude Code CLI client on PC, Linux, macOS, and Termux using alternative compatible API endpoints.

Table of Contents

  1. Overview & Comparison
  2. Step 1: Get Your API Credentials
  3. Step 2: Install Claude Code CLI
  4. Step 3: Configuration Templates
  5. Quick Switcher Script
  6. Step 4: Running Claude Code
  7. Troubleshooting & Common Pitfalls

Overview & Comparison

Claude Code normally requires an active Claude Pro subscription or official Anthropic API keys. By routing requests through compatible third-party API proxy services, you can run Claude Code for free or at a significantly lower cost using alternative routing endpoints.

API Gateways Comparison

Feature Provider A: AgentRouter Provider B: HCNSEC (formerly IAMHC)
Referral Link Yes (AgentRouter Link) Yes (HCNSEC Invite Link)
Featured Models claude-opus-5, glm-5.2 DeepSeek-V4-Pro, DeepSeek-V4-Flash, glm-5.2
Trial Credit ~$100 USD (+$50 USD referral) ~$2,000 USD
Base URL https://agentrouter.org https://api.hcnsec.cn

Step 1: Get Your API Credentials

  1. Sign up on your chosen platform:
  1. Navigate to the API Keys / Tokens (令牌) tab.
  2. Generate a new API key. It should start with sk-.

[!IMPORTANT]
API Key vs. Redemption Code:
If you have a token ending in == (e.g. AXfq6y...==), this is a Redemption Code (兑换码), not an API Key. You must redeem it in the portal (Top Up -> Redeem Code) to add credits to your account first, then create a standard sk- key.

Step 2: Install Claude Code CLI

Install Node.js on your system first. Then run the installation command:

For Termux Users (Android)

If you are running in a Termux environment, it is highly recommended to pin the version to 2.1.112 for the best compatibility and stability:

npm install -g @anthropic-ai/claude-code@2.1.112

If you encounter shebang interpretation errors, run:

termux-fix-shebang $(which claude)

For PC / Linux / macOS Users

Install the latest stable version:

npm install -g @anthropic-ai/claude-code

Step 3: Configuration Templates

Open the Claude Code settings file using a terminal text editor:

nano ~/.claude/settings.json

Replace the file content with one of the following JSON templates. Make sure to paste your own API Key in ANTHROPIC_AUTH_TOKEN.

Template A: AgentRouter Configuration

{
 "env": {
  "ANTHROPIC_AUTH_TOKEN": "YOUR_AGENTROUTER_API_KEY",
  "ANTHROPIC_BASE_URL": "https://agentrouter.org",
  "ANTHROPIC_MODEL": "claude-opus-5",
  "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
 },
 "permissions": {
  "allow": [],
  "deny": []
 },
 "skipWorkflowUsageWarning": true
}

Template B: HCNSEC (IAMHC) Configuration

{
 "env": {
  "ANTHROPIC_AUTH_TOKEN": "YOUR_HCNSEC_API_KEY",
  "ANTHROPIC_BASE_URL": "https://api.hcnsec.cn",
  "ANTHROPIC_MODEL": "DeepSeek-V4-Flash",
  "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
 },
 "permissions": {
  "allow": [],
  "deny": []
 },
 "skipWorkflowUsageWarning": true
}

[!WARNING]
Base URL Structure:
Do NOT add /v1 at the end of the ANTHROPIC_BASE_URL (e.g. use https://api.hcnsec.cn instead of https://api.hcnsec.cn/v1).
The Claude Code client automatically appends /v1/messages internally. If /v1 is present in your config, the client will try to call /v1/v1/messages which results in a 404 Not Found error.

Supported Model Values

You can substitute the ANTHROPIC_MODEL in your settings file with any of these exact model IDs:

  • For AgentRouter:
  • claude-opus-4-8
  • claude-opus-4-7
  • claude-opus-5
  • glm-5.2
  • For HCNSEC:
  • DeepSeek-V4-Flash (Highly Recommended for speed)
  • DeepSeek-V4-Pro
  • glm-5.2
  • glm-5.1
  • glm-4.7
  • Kimi-K2.6
  • MiniMax-M3

Quick Switcher Script (Optional)

If you use both providers and want to switch between them instantly without editing files manually, you can set up this helper CLI switcher script.

Switcher Setup

  1. Create the script file:
nano ~/.claude/switch-claude.sh
  1. Paste the following script code:
 #!/data/data/com.termux/files/usr/bin/bash

 # Color definitions
 RED='\e[1;31m'
 GREEN='\e[1;32m'
 YELLOW='\e[1;33m'
 BLUE='\e[1;34m'
 CYAN='\e[1;36m'
 BOLD='\e[1m'
 RESET='\e[0m'

 # Configuration paths
 CONFIG_DIR="$HOME/.claude"
 SETTINGS_FILE="$CONFIG_DIR/settings.json"
 KEYS_FILE="$CONFIG_DIR/keys.conf"

 # Ensure config directory exists
 mkdir -p "$CONFIG_DIR"

 # Defaults
 DEFAULT_AGENTROUTER_MODEL="claude-opus-4-8"
 DEFAULT_HCNSEC_MODEL="glm-5.2"

 # Load saved keys if they exist
 if [ -f "$KEYS_FILE" ]; then
     source "$KEYS_FILE"
 fi

 # Set models to defaults if not present
 if [ -z "$AGENTROUTER_MODEL" ]; then
     AGENTROUTER_MODEL=$DEFAULT_AGENTROUTER_MODEL
 fi
 if [ -z "$HCNSEC_MODEL" ]; then
     HCNSEC_MODEL=$DEFAULT_HCNSEC_MODEL
 fi

 # Function to save keys and models
 save_config() {
     cat << EOF > "$KEYS_FILE"
 AGENTROUTER_KEY="$AGENTROUTER_KEY"
 HCNSEC_KEY="$HCNSEC_KEY"
 AGENTROUTER_MODEL="$AGENTROUTER_MODEL"
 HCNSEC_MODEL="$HCNSEC_MODEL"
 EOF
 }

 # Prompt for key if not saved
 get_key() {
     local provider_name=$1
     local current_key=$2
     if [ -z "$current_key" ]; then
         echo -e "${YELLOW}Kunci API untuk $provider_name belum disimpan.${RESET}"
         read -p "Masukkan API Key: " new_key
         echo "$new_key"
     else
         echo "$current_key"
     fi
 }

 show_usage() {
     echo -e "${CYAN}┌────────────────────────────────────────────────────────┐${RESET}"
     echo -e "${CYAN}│${RESET}         ${BOLD}CLAUDE CODE PROVIDER SWITCHER CLI${RESET}            ${CYAN}│${RESET}"
     echo -e "${CYAN}└────────────────────────────────────────────────────────┘${RESET}"
     echo -e "${BOLD}Penggunaan:${RESET}"
     echo -e "  ${GREEN}switch-claude 1${RESET} (atau ${GREEN}agentrouter${RESET})  : Beralih ke AgentRouter"
     echo -e "  ${GREEN}switch-claude 2${RESET} (atau ${GREEN}hcnsec${RESET})       : Beralih ke HCNSEC/IAMHC"
     echo -e "  ${GREEN}switch-claude --model 1 <nama_model>${RESET} : Ubah model AgentRouter"
     echo -e "  ${GREEN}switch-claude --model 2 <nama_model>${RESET} : Ubah model HCNSEC"
     echo -e "  ${GREEN}switch-claude --reset${RESET}            : Hapus kunci API yang disimpan"
     echo ""
     exit 1
 }

 # Handle reset flag
 if [ "$1" == "--reset" ]; then
     rm -f "$KEYS_FILE"
     echo -e "${RED}Konfigurasi yang disimpan telah dihapus!${RESET}"
     echo -e "${YELLOW}Silakan jalankan script kembali untuk memulai ulang.${RESET}"
     exit 0
 fi

 # Handle model change flag
 if [ "$1" == "--model" ]; then
     if [ "$2" == "1" ] || [ "$2" == "agentrouter" ]; then
         if [ -n "$3" ]; then
             AGENTROUTER_MODEL="$3"
             save_config
             echo -e "${GREEN}Model AgentRouter berhasil diubah menjadi: ${YELLOW}$3${RESET}"
             exit 0
         else
             echo -e "${RED}Harap sebutkan nama modelnya. Contoh: switch-claude --model 1 claude-opus-4-7${RESET}"
             exit 1
         fi
     elif [ "$2" == "2" ] || [ "$2" == "hcnsec" ]; then
         if [ -n "$3" ]; then
             HCNSEC_MODEL="$3"
             save_config
             echo -e "${GREEN}Model HCNSEC berhasil diubah menjadi: ${YELLOW}$3${RESET}"
             exit 0
         else
             echo -e "${RED}Harap sebutkan nama modelnya. Contoh: switch-claude --model 2 DeepSeek-V4-Flash${RESET}"
             exit 1
         fi
     else
         show_usage
     fi
 fi

 # Parse argument
 PROVIDER=""
 if [ "$1" == "1" ] || [ "$1" == "agentrouter" ]; then
     PROVIDER="agentrouter"
 elif [ "$1" == "2" ] || [ "$1" == "hcnsec" ]; then
     PROVIDER="hcnsec"
 elif [ -n "$1" ]; then
     show_usage
 else
     # Interactive menu if no argument
     echo -e "${CYAN}┌────────────────────────────────────────────────────────┐${RESET}"
     echo -e "${CYAN}│${RESET}         ${BOLD}CLAUDE CODE PROVIDER SWITCHER CLI${RESET}            ${CYAN}│${RESET}"
     echo -e "${CYAN}└────────────────────────────────────────────────────────┘${RESET}"
     echo -e "${BOLD}Pilih Provider:${RESET}"
     echo -e "  ${CYAN}[1]${RESET} AgentRouter (${BLUE}https://agentrouter.org${RESET})"
     echo -e "  ${CYAN}[2]${RESET} HCNSEC/IAMHC (${BLUE}https://api.hcnsec.cn${RESET})"
     echo ""
     read -p "Pilihan Anda (1/2): " pilihan
     if [ "$pilihan" == "1" ]; then
         PROVIDER="agentrouter"
     elif [ "$pilihan" == "2" ]; then
         PROVIDER="hcnsec"
     else
         echo -e "${RED}Pilihan tidak valid!${RESET}"
         show_usage
     fi
 fi

 if [ "$PROVIDER" == "agentrouter" ]; then
     AGENTROUTER_KEY=$(get_key "AgentRouter" "$AGENTROUTER_KEY")
     save_config
     
     # Write settings.json nicely formatted
     cat << EOF > "$SETTINGS_FILE"
 {
   "env": {
     "ANTHROPIC_AUTH_TOKEN": "$AGENTROUTER_KEY",
     "ANTHROPIC_BASE_URL": "https://agentrouter.org",
     "ANTHROPIC_MODEL": "$AGENTROUTER_MODEL",
     "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
   },
   "permissions": {
     "allow": [],
     "deny": []
   },
   "skipWorkflowUsageWarning": true
 }
 EOF
     
     echo -e "\n${GREEN}BERHASIL DIUBAH!${RESET}"
     echo -e "Endpoint: ${CYAN}https://agentrouter.org${RESET}"
     echo -e "Model: ${YELLOW}$AGENTROUTER_MODEL${RESET}"
     echo -e "Jalankan ${GREEN}claude${RESET} untuk memulai."

 elif [ "$PROVIDER" == "hcnsec" ]; then
     HCNSEC_KEY=$(get_key "HCNSEC" "$HCNSEC_KEY")
     save_config
     
     # Write settings.json nicely formatted
     cat << EOF > "$SETTINGS_FILE"
 {
   "env": {
     "ANTHROPIC_AUTH_TOKEN": "$HCNSEC_KEY",
     "ANTHROPIC_BASE_URL": "https://api.hcnsec.cn",
     "ANTHROPIC_MODEL": "$HCNSEC_MODEL",
     "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
   },
   "permissions": {
     "allow": [],
     "deny": []
   },
   "skipWorkflowUsageWarning": true
 }
 EOF
     
     echo -e "\n${GREEN}BERHASIL DIUBAH!${RESET}"
     echo -e "Endpoint: ${CYAN}https://api.hcnsec.cn${RESET}"
     echo -e "Model: ${YELLOW}$HCNSEC_MODEL${RESET}"
     echo -e "Jalankan ${GREEN}claude${RESET} untuk memulai."
 fi
  1. Make it executable and globally link it:
chmod +x ~/.claude/switch-claude.sh
ln -sf ~/.claude/switch-claude.sh /data/data/com.termux/files/usr/bin/switch-claude

How to Use

  • Interactive Mode: Simply run switch-claude and select option 1 or 2.
  • Quick Commands:
  • Switch to AgentRouter: switch-claude 1 (or switch-claude agentrouter)
  • Switch to HCNSEC: switch-claude 2 (or switch-claude hcnsec)
  • Reset Saved Keys: switch-claude --reset

Step 4: Running Claude Code

Once configured, simply run:

claude

The Claude Code interactive CLI terminal should start up immediately and connect to the proxy endpoint seamlessly.

Troubleshooting & Common Pitfalls

Error: "There's an issue with the selected model (status 404)"

  • Reason: You probably appended /v1 to the base URL in your settings.json.
  • Fix: Remove the /v1 suffix from your ANTHROPIC_BASE_URL parameter.

Error: "Invalid API Key" / "Invalid Token" (status 401/403)

  • Reason 1: You might have pasted a Redemption Code (base64-like string ending in ==) directly into the config. Check the Step 1 instructions.
  • Reason 2: The model configured in ANTHROPIC_MODEL is not bound to your proxy channel/tier. Double-check your proxy account balance.

Node.js 22+ Compatibility Crash on Old Versions

  • Reason: Very old Claude Code versions (e.g., 0.2.x) crash on newer Node versions (like Node 22/26) due to dependency issues.
  • Fix: Upgrade to version 2.1.112 or later which fixes the Node interpreter crash.
Diskusi & Komentar0

Belum ada komentar — jadilah yang pertama memberikan masukan atau diskusi kode.

Masuk dengan akun GitHub untuk menulis komentar dan berdiskusi.