Linux 三端 CLI 配置笔记

最近把 Claude Code、Codex CLI、Gemini CLI、Cursor 统一接入了 CLIProxyAPI，让多台设备共享同一套订阅，不用每台机器都单独登录，这里记录一下服务端部署和客户端配置的过程，笔者用的是 Ubuntu 20.04 做服务端，客户端分别有 Windows 11、macOS 和 Linux，如有疏漏欢迎指出

服务端部署

安装

一键安装：

curl -fsSL https://raw.githubusercontent.com/brokechubb/cliproxyapi-installer/refs/heads/master/cliproxyapi-installer | bash

手动安装的话直接下载二进制就行：

mkdir -p /opt/cli-proxy-api && cd /opt/cli-proxy-api
wget https://github.com/router-for-me/CLIProxyAPI/releases/latest/download/cli-proxy-api-linux-amd64 -O cli-proxy-api
chmod +x cli-proxy-api

配置文件

默认路径 ~/.cli-proxy-api/config.yaml，也可以放在二进制同级目录

port: 8317
tls:
  enable: false
remote-management:
  allow-remote: true
  secret-key: <bcrypt哈希>
  disable-control-panel: false
auth-dir: /opt/cli-proxy-api/auths
api-keys:
  - <自行生成的api-key>
debug: false
logging-to-file: true
logs-max-total-size-mb: 100
request-retry: 3
max-retry-interval: 30
routing:
  strategy: round-robin
ws-auth: false
usage-statistics-enabled: true

port 默认 8317，可以改成自己想用的端口，api-keys 是给客户端鉴权用的，后面客户端配置里填的 key 就是这里的值，自行生成即可：

import secrets
print('sk-' + secrets.token_hex(32))

给多个用户用就在 api-keys 下面加多行，每人一个 key

OAuth 登录

启动服务后打开管理面板 http://服务端IP:端口/management.html，页面上有各平台的 OAuth 登录按钮，直接在浏览器里完成授权

如果服务端没有桌面环境，用命令行登录：

./cli-proxy-api --claude-login -no-browser
./cli-proxy-api --codex-login
./cli-proxy-api --login --project_id <Google Cloud项目ID>

-no-browser 会在终端输出 URL，复制到其他设备的浏览器里完成授权，同一命令重复执行可以添加多个账号做负载均衡

systemd 服务

cat > /etc/systemd/system/cli-proxy-api.service << 'EOF'
[Unit]
Description=CLIProxyAPI - Multi-provider AI API Proxy
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/cli-proxy-api
Environment=HOME=/root
ExecStart=/opt/cli-proxy-api/cli-proxy-api
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable cli-proxy-api
systemctl start cli-proxy-api

验证服务是否正常：

curl http://127.0.0.1:8317/v1/models -H "Authorization: Bearer <你的api-key>"

能返回模型列表就没问题，别忘了防火墙放行端口：

ufw allow 8317/tcp

客户端配置

下文中 <your-api-key> 统一指服务端 config.yaml 里 api-keys 中的值，<server-ip> 和 <port> 指服务端的 IP 和端口

Claude Code

安装

Claude Code 已切换为 native installer，不再推荐 npm 方式：

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

也支持包管理器安装（不会自动更新，需手动升级）：

# macOS (Homebrew)
brew install --cask claude-code

# Windows (WinGet)
winget install Anthropic.ClaudeCode

安装后二进制位于 ~/.local/bin/claude（Windows 为 %USERPROFILE%\.local\bin\claude.exe），确保该路径在 PATH 中

配置

编辑 ~/.claude/settings.json（Windows 路径为 C:\Users\用户名.claude\settings.json）：

{
  "env": {
    "ANTHROPIC_API_KEY": "<your-api-key>",
    "ANTHROPIC_BASE_URL": "http://<server-ip>:<port>"
  }
}

只需要填 API key 和服务端地址，模型启动后在界面里选就行

清除旧 OAuth 凭证

如果之前用订阅方式登录过（/login 或 OAuth 授权），Claude Code 会优先使用缓存的 OAuth token 而非 settings.json 中的 API key 配置，表现为界面上显示 sk-ant-... 开头的 key，需要清除旧凭证

Claude Code 在不同平台使用不同的凭证存储机制：

平台	主存储位置	说明
macOS	Keychain	凭证存入系统钥匙串，`~/.claude/.credentials.json` 迁移后会被自动删除
Linux（桌面）	Secret Service / libsecret	通过系统密钥环存储，回退到 `~/.claude/.credentials.json`
Linux（无头/容器）	`~/.claude/.credentials.json`	无桌面环境时直接用文件存储
Windows	Credential Manager	存入 Windows 凭据管理器，但在 Git Bash 环境下存在已知 bug 可能未持久化（#29049），回退到 `~/.claude/.credentials.json`

清除方法：

macOS——删除 Keychain 中的条目：

security delete-generic-password -s "Claude Code-credentials"

Linux——删除凭证文件：

rm ~/.claude/.credentials.json

Windows——需要同时清除两个位置（因为已知 bug，token 可能没进 Credential Manager 而是落在文件里）：

# 1. 删除凭据管理器中的条目（如果存在）
# 打开「控制面板 → 凭据管理器 → Windows 凭据」，找到 Claude Code 相关条目删除
# 或通过命令行：
cmdkey /delete:Claude Code-credentials

# 2. 删除文件凭证（如果存在）
del %USERPROFILE%\.claude\.credentials.json

三个平台通用的方式是在 Claude Code 交互界面中执行 /logout，然后重启

交互模式 "Not logged in" 问题

配好 API key 后，claude -p "say hi" 能正常返回，但打开交互模式输入消息后提示 "Not logged in"，这是一个已知问题（#27900），原因是交互模式的认证流程优先查找 OAuth session，在没有 OAuth 登录记录的机器上会忽略 API key

排查步骤：

检查 ~/.claude.json（注意不是 ~/.claude/settings.json）中的 customApiKeyResponses 字段——首次启动时 Claude Code 会弹出 "是否信任此自定义 API key" 的对话框，如果选了拒绝，你的 key 后缀会被记录在 rejected 列表中，交互模式就会拒绝使用这个 key：

# 查看当前状态
python3 -c "import json; d=json.load(open('$HOME/.claude.json')); print(json.dumps(d.get('customApiKeyResponses', {}), indent=2))"

如果 rejected 列表中包含你的 key 后缀，将它移到 approved：

python3 -c "
import json, os
p = os.path.expanduser('~/.claude.json')
d = json.load(open(p))
d['customApiKeyResponses'] = {'approved': ['<你的key后20位>'], 'rejected': []}
json.dump(d, open(p, 'w'), indent=2)
"

检查同一文件中是否有残留的 oauthAccount 字段——如果之前用其他账号做过 OAuth 登录，缓存的账号信息可能与当前 API key 冲突：

python3 -c "
import json, os
p = os.path.expanduser('~/.claude.json')
d = json.load(open(p))
d.pop('oauthAccount', None)
json.dump(d, open(p, 'w'), indent=2)
"

跳过 onboarding

Claude Code 首次启动会进入交互式引导（信任目录、使用条款等），走代理时这个流程可能会卡住，可以手动写入完成标记跳过。注意 ~/.claude.json 可能已经存在其他配置，不要用 cat > 或重定向覆盖，用 merge 方式写入：

python3 -c "
import json, os
p = os.path.expanduser('~/.claude.json')
d = json.load(open(p)) if os.path.exists(p) else {}
d['hasCompletedOnboarding'] = True
json.dump(d, open(p, 'w'), indent=2)
"

启动和验证

claude

或者非交互式测试：

claude -p "say hi"

能正常返回就说明配置没问题

Codex CLI

安装和更新

npm install -g @openai/codex
npm update -g @openai/codex

配置

~/.codex/config.toml：

model_provider = "cliproxyapi"

[model_providers.cliproxyapi]
name = "CLIProxyAPI"
base_url = "http://<server-ip>:<port>/v1"
wire_api = "responses"

~/.codex/auth.json：

{
  "OPENAI_API_KEY": "<your-api-key>"
}

base_url 注意末尾要带 /v1，wire_api = "responses" 不能省，Codex 走的是 OpenAI Responses API 格式，模型启动后用 /model 命令切换

启动和验证

codex

Gemini CLI

安装和更新

npm install -g @google/gemini-cli
npm update -g @google/gemini-cli

配置

Gemini CLI 没有配置文件，通过环境变量配置：

export GEMINI_API_KEY="<your-api-key>"
export GOOGLE_GEMINI_BASE_URL="http://<server-ip>:<port>"

写入 ~/.bashrc 或 ~/.zshrc 持久化，Windows 用 PowerShell 设用户级环境变量：

[System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', '<your-api-key>', 'User')
[System.Environment]::SetEnvironmentVariable('GOOGLE_GEMINI_BASE_URL', 'http://<server-ip>:<port>', 'User')

Gemini CLI 也支持 Google OAuth 直连，不走代理时可以免费用 Gemini 系列（1000次/天），启动 gemini 后选 Login with Google 就行，此时不要设上面的环境变量

启动和验证

gemini

Cursor

Cursor 不是 CLI 工具，但通过 Override OpenAI Base URL 也能接入 CLIProxyAPI，所有模型（包括 Claude）统一走 OpenAI 兼容接口

配置

打开 Cursor → Settings → Models，在 OpenAI API Key 输入框填入 <your-api-key>，开启 Override OpenAI Base URL，填入：

http://<server-ip>:<port>/v1

然后在顶部 Add model 输入框手动添加 CLIProxyAPI 暴露的模型名，如 claude-opus-4-6、gpt-5.3-codex 等，添加后打开模型开关即可在 Chat/Composer 中选用，可用模型名通过 http://<server-ip>:<port>/v1/models 查看

Anthropic API Key、Google API Key 等其他 provider 的 key 不需要填，全部走 OpenAI Override 即可，CLIProxyAPI 内部会自动做格式转换（OpenAI ↔ Claude ↔ Gemini）

Cursor 目前没有独立的 Anthropic Base URL 覆盖选项，所以 Claude 模型必须通过 OpenAI 兼容接口访问，另外 Agent 模式下 Tool calling 可能存在兼容性问题，普通聊天和代码生成不受影响

代理与 NO_PROXY 配置

如果客户端通过本地代理访问外网，务必把 CLIProxyAPI 服务端地址加入直连规则或 NO_PROXY，这不仅仅是"避免多余转发"的问题——

为什么必须配

当 API 请求经过代理链路（特别是经过 CDN 中转的节点）时，链路中间可能存在 60 秒左右的空闲超时。普通对话请求几秒到几十秒就能返回，不会触发超时。但部分大请求（如 Claude Code 压缩 170k tokens 的上下文、处理大文件等）在 API 端的 prefill 阶段需要超过 60 秒才开始返回数据，此时中间链路会认为连接空闲并主动断开，客户端收到错误后自动重试，每次又等 60 秒又超时，导致一个请求反复失败十几次，耗时数十分钟甚至完全无法完成

配置方法

macOS / Linux

在 ~/.zshrc 或 ~/.bashrc 中添加：

export NO_PROXY="localhost,127.0.0.1,<server-ip>"

Windows

设置用户级环境变量（通过「系统属性 → 环境变量」或 PowerShell）：

[System.Environment]::SetEnvironmentVariable('NO_PROXY', 'localhost,127.0.0.1,<server-ip>', 'User')

同时在代理客户端的路由规则中将 <server-ip> 加入直连列表，仅设 NO_PROXY 环境变量可能不够——部分代理客户端通过系统代理或 TUN 模式接管流量，不受环境变量控制

Ubuntu 服务端（如果服务端自身也需要走代理）

在 systemd service 中配置代理时同样要排除自身：

[Service]
Environment="HTTP_PROXY=http://代理地址:端口"
Environment="HTTPS_PROXY=http://代理地址:端口"
Environment="NO_PROXY=localhost,127.0.0.1"

感谢

# CLIProxyAPI GitHub
https://github.com/router-for-me/CLIProxyAPI
# CLIProxyAPI 官方文档
https://help.router-for.me/
# Claude Code 官方文档
https://code.claude.com/docs/en/overview
# Claude Code 认证文档
https://code.claude.com/docs/en/authentication
# Claude Code 故障排查
https://code.claude.com/docs/en/troubleshooting
# Codex CLI 配置文档
https://developers.openai.com/codex/config-advanced/

posted @ 2026-02-28 05:00 Pyrokine 阅读(3735) 评论(0) 收藏举报

刷新页面返回顶部

Pyrokine

Ubuntu20.04 部署 CLIProxyAPI 及 Win/Mac/Linux 三端 CLI 配置笔记

Ubuntu20.04 部署 CLIProxyAPI 及 Win/Mac/Linux 三端 CLI 配置笔记

服务端部署

安装

配置文件

OAuth 登录

systemd 服务

客户端配置

Claude Code

Codex CLI

Gemini CLI

Cursor

代理与 NO_PROXY 配置

为什么必须配

配置方法

感谢

公告