AI 编程工具实战教程

2026 年，全球 AI 大模型市场呈现"百花齐放"的格局。本节带你快速了解主流模型的特点和价格。

国外旗舰模型

国内主流模型

Claude Code 是 Anthropic 推出的命令行 AI 编程工具，支持读取、编辑、执行代码。

步骤一：安装 Git Bash（仅 Windows）

下载地址：https://git-scm.com/downloads/win，安装时一路点下一步。

步骤二：安装 Claude Code

打开 PowerShell（如有代理先开启），运行：

$env:http_proxy="http://127.0.0.1:10808"
$env:https_proxy="http://127.0.0.1:10808"
& ([scriptblock]::Create((irm https://daheiai.com/cc.ps1))) 2.1.153

步骤三：配置 PATH 环境变量

把 C:\Users\你的用户名\.local\bin 加到用户 PATH 中：

1. 开始菜单搜「环境变量」→ 编辑系统环境变量
2. 用户变量 → Path → 新建
3. 填入上述路径

步骤四：接入 GLM 模型

使用智谱官方一键安装助手：

npx @z_ai/coding-helper

按引导依次选择：中国版套餐 → 输入 GLM API Key → 选择 Claude Code → 配置刷新 → 启动。

常用命令

开启最高权限（免确认模式）

在对话框输入：

bypassPermissions

授权后 Claude Code 执行命令不再频繁询问。

Skills 是 Anthropic 官方提供的技能扩展包，可以让 Claude Code 拥有专业能力，例如生成 PPT、Word、Excel、PDF 等文档。 安装一次，永久可用。

步骤一：克隆官方 Skills 仓库

新建一个文件夹用来存放 skills（这里用 D:\claude-skill 作为示例）：

cd D:\
mkdir claude-skill
cd claude-skill
git clone https://github.com/anthropics/skills.git anthropic-skills

步骤二：复制到 Claude Code 的 skills 目录

把克隆下来的 skills 复制到 Claude Code 配置文件夹中：

New-Item -Path "C:\Users\你的用户名\.claude\skills" -ItemType Directory -Force
Copy-Item -Path "D:\claude-skill\anthropic-skills\skills\*" -Destination "C:\Users\你的用户名\.claude\skills\" -Recurse -Force

步骤三：验证安装

重启 Claude Code，输入：

/skills

看到 pptx、docx、xlsx 等文件夹就说明安装成功。

常用 Skills 一览

实战：一键生成 PPT

在 Claude Code 对话框直接用自然语言描述需求：

请用 pptx skill 帮我生成一份 PPT：

主题：vibe coding 的发展历程
页数：8 页
风格：现代科技感，深蓝主色调

内容大纲：
1. 封面 - 标题 + 副标题
2. 什么是 vibe coding
3. 起源背景（2024 年 AI 编程兴起）
4. 核心特点（自然语言驱动开发）
5. 代表工具（Claude Code、Cursor、Codex）
6. 实际应用场景
7. 优势与挑战
8. 未来展望

要求：每页有清晰标题，重点用项目符号

Claude 会自动调用 pptx skill，先生成每页 HTML 设计，再转换为 .pptx 文件，保存到当前工作目录。

Codex 是 OpenAI 推出的 AI 编程 Agent，兼容 OpenAI 格式 API。

步骤一：下载安装

前往官方仓库：https://github.com/openai/codex

步骤二：填入 API Key

启动时选择「使用 API」，填入 ZCHAT API Key。

步骤三：编辑 config.toml

路径：C:\Users\你的用户名\.codex\config.toml

model_provider = "openai-chat-completions"

[model_providers.openai-chat-completions]
name = "ZCHAT"
wire_api = "responses"
base_url = "https://api.zchat.tech/v1"

设置最高权限

在输入框左下角点击「默认权限」，选择 完全自动（Full Auto），即可全程无需确认。

典型使用场景

• 📁 自动整理文件夹、批量重命名
• 🐛 修复代码 bug、生成单元测试
• 📊 数据分析与可视化
• 📝 自动生成项目文档
• 🚀 一键部署到 GitHub / 服务器

Q: 出现 403 Forbidden 错误怎么办？

可能原因：①上下文过长，输入 /compact 压缩；②AI 生成了无权限执行的命令；③API Key 余额不足。

Q: 下载安装包时网络中断？

设置 PowerShell 代理后重试：

$env:http_proxy="http://127.0.0.1:10808"
$env:https_proxy="http://127.0.0.1:10808"

Q: ZCHAT 接入 Claude Code 失败？

因 ZCHAT 仅支持 OpenAI 格式，而 Claude Code 用 Anthropic 原生格式，两者不兼容。建议 Claude Code 接 GLM，Codex 接 ZCHAT。

Q: 如何卸载 Claude Code？

打开「设置 → 应用 → 已安装的应用」，搜索"Claude Code"卸载即可。

Drivers AI（drivers-ai.com）是杨逸自建的 AI 接口中转平台， 把 Claude Pro、ChatGPT Plus 等订阅打包成 API，朋友拼车共享，国内直连，无需挂梯子。

步骤一：注册账号

浏览器打开 http://drivers-ai.com → 点「注册」→ 填邮箱密码 → 完成。

步骤二：创建 API 密钥

登录后左侧菜单 → API 密钥 → 点「创建」：

创建成功后会显示 sk-xxx 密钥，立刻复制保存，关闭后看不到完整 Key。

步骤三：Claude Code 配置（接入 Claude）

打开 PowerShell，运行（替换成你的 sk-xxx）：

$env:ANTHROPIC_BASE_URL="http://drivers-ai.com"
$env:ANTHROPIC_AUTH_TOKEN="sk-你的claude-key"
$env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC="1"
claude

步骤四：Codex 配置（接入 GPT）

按 Win + R → 输入 %userprofile%\.codex → 进入配置目录（不存在则手动新建）。

在该目录创建 config.toml 文件：

model_provider = "OpenAI"
model = "gpt-5.5"
review_model = "gpt-5.5"
model_reasoning_effort = "xhigh"
disable_response_storage = true
network_access = "enabled"
windows_wsl_setup_acknowledged = true

[model_providers.OpenAI]
name = "OpenAI"
base_url = "http://drivers-ai.com"
wire_api = "responses"
requires_openai_auth = true

[features]
goals = true

同目录创建 auth.json（替换成你的 GPT 密钥）：

{
  "OPENAI_API_KEY": "sk-你的gpt-key"
}

PowerShell 运行：

codex

步骤五：网页直接聊天（最省事）

不想配命令行？打开网页版 AI-Chat：

http://chat.drivers-ai.com

这是基于 Open WebUI 的聊天界面，体验类似 ChatGPT 官网，支持 Claude 和 GPT 任意切换。

① 首次注册

② 配置 API 接入（关键步骤）

登录后默认看不到任何模型，需要手动配置：

③ 开始聊天

常见问题

Q：注册后看不到任何模型？

需要按步骤②配置 API 连接。普通用户注册后没有管理员权限，看不到 Admin Panel——只有第一个注册的账号是管理员。如果你是普通用户，联系管理员（杨逸）帮你配置。

Q：选了模型聊天报错？

① 检查 API Key 是否在 Drivers AI 后台正确创建；② 检查 Key 对应的分组是否匹配（GPT 类模型必须用 openai-default 组的 Key，Claude 必须用 anthropic-default 组的 Key）；③ 试试别的模型。

Q：drivers-ai.com 打开很慢？

服务器在美国弗吉尼亚，国内访问延迟 200-300ms，正常现象。代码调用不影响速度，只是网页慢。

Q：用 Claude 中转站时还要不要梯子？

不需要。中转站服务器替你访问 Claude，你只需访问中转站（国内可直连）。

Q：额度用完了怎么办？

联系管理员（杨逸）协调，或等下一个 5 小时窗口期自动恢复。

本章以本站 yiyang-ai.com 为例，带你从购买域名、用 AI 写前端页面、创建 GitHub 仓库、 用 Git 更新代码，到把阿里云域名连接到 GitHub Pages。主线以 Windows 为例，Linux/macOS 命令放在每一步后面做补充。

一、先确定网页风格

个人网页不要一开始就堆技术，先决定“别人打开第一页时看到什么”。本站采用的是学术个人主页风格：左侧固定个人信息，右侧按模块展示履历。

二、在阿里云创建域名

域名相当于网站地址，例如本站使用 yiyang-ai.com。如果还没有域名，可以在阿里云完成购买和实名认证。

1. 打开 阿里云域名注册，搜索想要的域名。
2. 选择后缀，例如 .com、.cn、.net，优先选择短、好记、和自己名字/品牌相关的域名。
3. 创建或选择“域名信息模板”，按个人或企业身份填写资料。
4. 完成邮箱验证和实名认证。国内域名服务通常需要实名后才能稳定解析和使用。
5. 购买成功后，进入“域名控制台”，确认域名状态正常。

三、准备 Windows 开发环境

这类静态个人网页不需要服务器，也不需要数据库。你只需要浏览器、代码编辑器和 Git。

Windows 推荐安装

官网下载：

https://git-scm.com/downloads/win
https://code.visualstudio.com/

如果你的 Windows 支持 winget，也可以直接运行：

winget install --id Git.Git -e
winget install --id Microsoft.VisualStudioCode -e

Linux / macOS 补充

Ubuntu / Debian：

sudo apt update
sudo apt install git

macOS 安装 Xcode Command Line Tools：

xcode-select --install

macOS 如果使用 Homebrew：

brew install git

四、用 AI 生成个人主页前端代码

把需求说清楚，比“帮我做一个网站”有效得多。可以先把个人资料整理成清单，再让 AI 输出一个单文件静态页面。

可以直接复制给 AI 的提示词

请帮我写一个单文件个人主页 index.html，要求：
1. 面向学术/科研个人主页，整体简洁、专业、有一点现代感。
2. 页面左侧固定栏：头像、姓名、中英文名、邮箱、Google Scholar、GitHub、Blog。
3. 页面右侧主内容：个人介绍、Currently Teaching、Research Interests、Education、Publications、Patents、Experience、Awards。
4. 使用纯 HTML + CSS，不使用框架，移动端自适应。
5. 头像文件名为 1.png，和 index.html 放在同一个目录。
6. 请给出完整代码，不要省略。

保存文件时建议采用下面的结构。本站就是这种结构：

my-website/
  index.html
  course.html
  1.png
  CNAME
  README.md

本地预览

最简单的方法是双击 index.html。如果想模拟真实网站访问，可以开一个本地服务。

Windows PowerShell：

cd D:\my-website
python -m http.server 8000

浏览器打开：

http://localhost:8000

Linux / macOS：

cd ~/my-website
python3 -m http.server 8000

五、创建 GitHub 仓库

个人主页推荐使用 GitHub Pages。最省心的命名方式是：

<你的 GitHub 用户名>.github.io

例如本站仓库是：

https://github.com/yiyang-zju/yiyang-zju.github.io.git

1. 打开 GitHub，右上角点击 +，选择 New repository。
2. Repository name 填 用户名.github.io，例如 yiyang-zju.github.io。
3. 选择 Public。GitHub Pages 免费公开发布通常使用公开仓库最方便。
4. 先不要勾选 README、.gitignore、License，避免和本地文件产生冲突。
5. 创建后复制仓库 HTTPS 地址。

六、连接 GitHub 仓库并第一次发布

下面以 Windows PowerShell 为主。如果你已经在 Git Bash 里，也可以直接使用同样的 Git 命令。

cd D:\my-website
git init
git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
git add .
git commit -m "Initial personal website"
git branch -M main
git remote add origin https://github.com/<用户名>/<用户名>.github.io.git
git push -u origin main

Linux / macOS 命令

cd ~/my-website
git init
git add .
git commit -m "Initial personal website"
git branch -M main
git remote add origin https://github.com/<用户名>/<用户名>.github.io.git
git push -u origin main

七、开启 GitHub Pages

1. 进入 GitHub 仓库页面。
2. 点击 Settings。
3. 左侧进入 Pages。
4. Source 选择 Deploy from a branch。
5. Branch 选择 main，目录选择 /(root)，点击保存。

稍等几分钟后，默认网址会是：

https://<用户名>.github.io

八、把阿里云域名连接到 GitHub Pages

这一步分两边做：GitHub 记录你想绑定的域名，阿里云负责把访问请求解析到 GitHub Pages。

1. 在项目里创建 CNAME 文件

在网站根目录创建名为 CNAME 的文件，注意文件名全部大写，里面只写一行域名。

yiyang-ai.com

然后提交：

git add CNAME
git commit -m "Add custom domain"
git push

2. 在 GitHub Pages 填写 Custom domain

1. 仓库页面进入 Settings → Pages。
2. 在 Custom domain 填入你的域名，例如 yiyang-ai.com。
3. 保存后等待 DNS 检查。
4. 检查通过后，勾选 Enforce HTTPS。如果暂时不能勾选，等 DNS 生效后再回来开。

3. 在阿里云云解析 DNS 添加记录

进入阿里云控制台 → 云解析 DNS → 找到你的域名 → 解析设置 → 添加记录。

4. 检查 DNS 是否生效

Windows PowerShell：

nslookup yiyang-ai.com
nslookup www.yiyang-ai.com

Git Bash / Linux / macOS：

dig yiyang-ai.com
dig www.yiyang-ai.com

DNS 生效可能需要几分钟到数小时。等 GitHub Pages 页面显示 DNS check successful 后，就可以通过自己的域名访问网站。

九、以后如何更新网页

例如你修改了 index.html 的论文、经历或照片，只需要：

cd D:\my-website
git status
git add index.html
git commit -m "Update profile page"
git push

如果同时改了课程页和头像：

git add index.html course.html 1.png
git commit -m "Update personal website content"
git push

十、常见问题

Q：浏览器打开还是旧页面？

先强制刷新 Ctrl + F5。GitHub Pages 部署也可能有短暂延迟，等 1-3 分钟再看。

Q：GitHub Pages 显示 404？

确认仓库根目录里有 index.html，Pages 的 branch 是 main，目录是 /(root)。

Q：自定义域名无法访问？

检查三件事：CNAME 文件是否存在且只有一行域名；GitHub Pages 的 Custom domain 是否保存成功；阿里云解析记录是否填对。

Q：我已经有仓库了，提示 remote origin already exists？

git remote -v
git remote set-url origin https://github.com/<用户名>/<仓库名>.git
git push -u origin main

Q：要不要备案？

如果只是把域名解析到 GitHub Pages，通常不涉及阿里云国内服务器备案流程。但如果你把网站部署到中国内地服务器，通常需要按服务商要求完成备案。

参考资料

• GitHub Pages 自定义域名官方文档
• GitHub Pages 自定义域名排错
• GitHub：把本地代码添加到 GitHub
• 阿里云云解析 DNS：添加解析记录
• 阿里云域名注册入口
• One Page Love：个人网站设计参考
• Figma：个人网站案例与模板

本章记录一次完整的 Kiro RS 反代 Claude Code 实战：用 hank9999/kiro.rs 把 Kiro 的后端能力包装成 Anthropic Messages 兼容接口，再接入 Claude Code 或 ccswitch。

一、先理解技术路线

这套方案不是普通网页反向代理，而是一个 协议转换代理：

Claude Code / ccswitch
        ↓
Kiro RS 本地服务
        ↓
Kiro OAuth 凭据池 credentials.json
        ↓
Kiro / AWS 后端
        ↓
返回 Anthropic Messages 格式结果

二、准备环境

Windows 推荐使用 Docker Desktop 部署，这样不用手动编译 Rust 项目。

docker version
docker compose version

创建运行目录：

mkdir D:\kiro-rs
cd D:\kiro-rs
mkdir config

三、编写 Docker Compose

在 D:\kiro-rs 下创建 docker-compose.yml：

services:
  kiro-rs:
    image: ghcr.io/hank9999/kiro-rs:latest
    container_name: kiro-rs
    extra_hosts:
      - "host.docker.internal:host-gateway"
    ports:
      - "8990:8990"
    volumes:
      - ./config/:/app/config/
    restart: unless-stopped

四、生成服务 API Key

这个 Key 是客户端访问你本地 Kiro RS 的认证密钥，不是 Kiro 账号密码。

$bytes = New-Object byte[] 24
$rng = [System.Security.Cryptography.RandomNumberGenerator]::Create()
$rng.GetBytes($bytes)
$rng.Dispose()
$apiKey = "sk-kiro-rs-" + ([System.BitConverter]::ToString($bytes)).Replace("-", "").ToLower()
$apiKey

五、创建 config.json

在 D:\kiro-rs\config 下创建 config.json。把下面的 YOUR_API_KEY 换成上一步生成的 Key。

{
  "host": "0.0.0.0",
  "port": 8990,
  "apiKey": "YOUR_API_KEY",
  "adminApiKey": "YOUR_ADMIN_KEY",
  "region": "us-east-1",
  "authRegion": "us-east-1",
  "apiRegion": "us-east-1",
  "tlsBackend": "native-tls",
  "loadBalancingMode": "balanced",
  "defaultEndpoint": "ide",
  "extractThinking": true
}

六、准备 Kiro 凭据 credentials.json

Kiro RS 需要 credentials.json。它里面保存的是 OAuth 凭据，例如 refreshToken，不是你的账号密码。

如果你已经通过 Kiro IDE 或 AIClient-2-API 授权过，本机通常会有：

C:\Users\你的用户名\.aws\sso\cache\kiro-auth-token.json

可以用下面的命令把它转换成 Kiro RS 需要的格式：

$src = "$env:USERPROFILE\.aws\sso\cache\kiro-auth-token.json"
$dst = "D:\kiro-rs\config\credentials.json"

$obj = Get-Content -Raw $src | ConvertFrom-Json
$reg = $obj.region
if ([string]::IsNullOrWhiteSpace($reg)) { $reg = "us-east-1" }

$method = $obj.authMethod
if ([string]::IsNullOrWhiteSpace($method)) { $method = "social" }

$cred = [ordered]@{
  accessToken  = $obj.accessToken
  refreshToken = $obj.refreshToken
  expiresAt    = $obj.expiresAt
  authMethod   = $method
  region       = $reg
  authRegion   = $reg
  apiRegion    = "us-east-1"
  priority     = 0
  endpoint     = "ide"
}

$cacheDir = "$env:USERPROFILE\.aws\sso\cache"
$clientCache = Get-ChildItem $cacheDir -Filter "*.json" |
  ForEach-Object {
    try { Get-Content -Raw $_.FullName | ConvertFrom-Json } catch { $null }
  } |
  Where-Object { $_.clientId -and $_.clientSecret } |
  Select-Object -First 1

if ($clientCache) {
  $cred.clientId = $clientCache.clientId
  $cred.clientSecret = $clientCache.clientSecret
  if ($cred.authMethod -eq "IdC") { $cred.authMethod = "idc" }
}

$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
[System.IO.File]::WriteAllText($dst, ((@($cred)) | ConvertTo-Json -Depth 5), $utf8NoBom)

七、启动 Kiro RS

cd D:\kiro-rs
docker compose up -d
docker ps --filter name=kiro-rs
docker logs --tail 50 kiro-rs

日志里看到下面这类信息，说明服务已经起来：

已加载 1 个凭据配置
启动 Anthropic API 端点: 0.0.0.0:8990
GET  /v1/models
POST /v1/messages

八、测试接口是否可用

先测模型列表：

$apiKey = "YOUR_API_KEY"

Invoke-RestMethod `
  -Uri "http://127.0.0.1:8990/v1/models" `
  -Headers @{ "x-api-key" = $apiKey }

再测真实对话：

$apiKey = "YOUR_API_KEY"

$body = @{
  model = "claude-sonnet-4-5-20250929"
  max_tokens = 128
  stream = $false
  messages = @(
    @{
      role = "user"
      content = "Say OK in English only."
    }
  )
} | ConvertTo-Json -Depth 8

Invoke-RestMethod `
  -Uri "http://127.0.0.1:8990/v1/messages" `
  -Method Post `
  -Headers @{
    "Content-Type" = "application/json"
    "x-api-key" = $apiKey
  } `
  -Body $body

如果返回类似下面的内容，就说明反代成功：

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "OK"
    }
  ]
}

九、接入 ccswitch / Claude Code

在 ccswitch 中新增 Claude 供应商时，重点是：请求地址填基地址，不要填到 /v1/messages。

配置 JSON 可以写成：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8990",
    "ANTHROPIC_MODEL": "claude-sonnet-4-5-20250929",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5-20250929",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-sonnet-4-5-20250929",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001"
  }
}

模型映射建议：

当前实测更稳的 Kiro 模型白名单：

十、Claude Code 验证

保存并启用供应商后，打开命令行测试 Claude Code：

claude

进入 Claude Code 后可以输入：

你好
帮我检查一下当前电脑配置

实测成功时，Claude Code 会正常执行命令，例如读取 Windows 系统信息、CPU、内存、磁盘信息，并返回分析结果。

十一、海外服务器接入 sub2api 分发

如果只是自己本机使用，http://127.0.0.1:8990 就够了。 但如果要让 海外服务器上的 sub2api 给其他用户分发，Kiro RS 必须部署在同一台海外服务器上，或者至少能被 sub2api 容器稳定访问。

服务器目录建议：

mkdir -p /opt/kiro-rs/config
cd /opt/kiro-rs

海外服务器上的 docker-compose.yml 可以这样写：

services:
  kiro-rs:
    image: ghcr.io/hank9999/kiro-rs:latest
    container_name: kiro-rs
    restart: unless-stopped
    ports:
      - "127.0.0.1:8990:8990"
    volumes:
      - ./config:/app/config

启动后，把 Kiro RS 接入 sub2api 所在 Docker 网络，并设置容器别名：

SUB2API_NET=$(docker inspect sub2api --format '{{range $k,$v := .NetworkSettings.Networks}}{{$k}}{{end}}')
docker network disconnect "$SUB2API_NET" kiro-rs 2>/dev/null || true
docker network connect --alias kiro-rs "$SUB2API_NET" kiro-rs

从 sub2api 网络里验证 Kiro RS 是否可访问：

API_KEY=$(jq -r .apiKey /opt/kiro-rs/config/config.json)
docker run --rm --network "$SUB2API_NET" curlimages/curl:latest -sS http://kiro-rs:8990/v1/models -H "x-api-key: $API_KEY"

在 sub2api 中创建账号时，建议这样填：

十二、16 账号号池的经验总结

多账号池的 credentials.json 是数组格式。每个账号都应该包含刷新所需字段，尤其是 IdC 模式下的 clientId 和 clientSecret。

[
  {
    "authMethod": "idc",
    "accessToken": "ACCESS_TOKEN",
    "refreshToken": "REFRESH_TOKEN",
    "clientId": "CLIENT_ID",
    "clientSecret": "CLIENT_SECRET",
    "region": "us-east-1",
    "authRegion": "us-east-1",
    "apiRegion": "us-east-1",
    "endpoint": "ide",
    "priority": 0,
    "disabled": false
  }
]

新增号池时，不需要换 sub2api 中的 API Key。只要 config.json 里的 apiKey 不变，外部调用入口就不变。

十三、远程服务器常用检查命令

下面命令在本机 Windows PowerShell 中执行，通过 SSH 查看海外服务器状态。把服务器 IP 和密钥路径换成自己的。

查看号池总览：

ssh -i "$env:USERPROFILE\.ssh\kiro_rs_sync_ed25519" root@YOUR_SERVER_IP 'ADMIN_KEY=$(jq -r .adminApiKey /opt/kiro-rs/config/config.json); curl -s http://127.0.0.1:8990/api/admin/credentials -H x-api-key:${ADMIN_KEY} | jq "{total,available,currentId,disabled:([.credentials[] | select(.disabled==true)] | length)}"'

查看每个账号状态：

ssh -i "$env:USERPROFILE\.ssh\kiro_rs_sync_ed25519" root@YOUR_SERVER_IP 'ADMIN_KEY=$(jq -r .adminApiKey /opt/kiro-rs/config/config.json); curl -s http://127.0.0.1:8990/api/admin/credentials -H x-api-key:${ADMIN_KEY} | jq ".credentials[] | {id,priority,disabled,disabledReason,successCount,refreshFailureCount,lastUsedAt,expiresAt}"'

查看 Kiro RS 日志：

ssh -i "$env:USERPROFILE\.ssh\kiro_rs_sync_ed25519" root@YOUR_SERVER_IP 'docker logs --tail=100 kiro-rs'

测试真实对话：

ssh -i "$env:USERPROFILE\.ssh\kiro_rs_sync_ed25519" root@YOUR_SERVER_IP 'API_KEY=$(jq -r .apiKey /opt/kiro-rs/config/config.json); BODY="{\"model\":\"claude-sonnet-4-5-20250929\",\"max_tokens\":40,\"messages\":[{\"role\":\"user\",\"content\":\"hi, reply ok\"}]}"; curl -s http://127.0.0.1:8990/v1/messages -H Content-Type:application/json -H x-api-key:${API_KEY} -H anthropic-version:2023-06-01 -d "$BODY"'

十四、常见问题

Q：ccswitch 启用时报 .claude.json expected value at line 1 column 1？

这通常是 C:\Users\你的用户名\.claude.json 文件开头带 UTF-8 BOM，部分 JSON 解析器不能识别。可以备份后重写为无 BOM UTF-8。

$p = "$env:USERPROFILE\.claude.json"
$bak = "$env:USERPROFILE\.claude.json.bak-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
Copy-Item -LiteralPath $p -Destination $bak

$text = [System.IO.File]::ReadAllText($p, [System.Text.Encoding]::UTF8)
if ($text.Length -gt 0 -and $text[0] -eq [char]0xFEFF) {
  $text = $text.Substring(1)
}

$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
[System.IO.File]::WriteAllText($p, $text, $utf8NoBom)

node -e "const fs=require('fs'); JSON.parse(fs.readFileSync(process.env.USERPROFILE+'/.claude.json','utf8')); console.log('JSON OK')"

Q：模型列表能返回，但对话失败？

优先检查 credentials.json 是否加载成功。运行：

docker logs --tail 80 kiro-rs

如果看到 已加载 0 个凭据配置，说明还没有有效 Kiro 凭据；如果看到 已加载 1 个凭据配置，说明凭据池已经识别。

Q：报错 502 上游 API 调用失败：所有凭据均已禁用（0/1） 怎么办？

这个错误通常不是 ccswitch 填错，而是 Kiro RS 的凭据池被自动禁用了。最常见原因是：credentials.json 里只有 accessToken/refreshToken，缺少 IdC 刷新所需的 clientId/clientSecret。刚启动时旧 Token 还没过期，所以能跑；一旦需要刷新 Token，就会连续失败，最后显示 TooManyRefreshFailures。

先看管理接口状态：

$adminKey = "YOUR_ADMIN_API_KEY"

Invoke-RestMethod `
  -Uri "http://127.0.0.1:8990/api/admin/credentials" `
  -Headers @{ "x-api-key" = $adminKey } |
  ConvertTo-Json -Depth 8

如果返回里有 "available": 0、"disabled": true 或 "disabledReason": "TooManyRefreshFailures"，就按下面命令补齐字段并重启。命令会自动备份旧凭据文件：

$credPath = "D:\kiro-rs\config\credentials.json"
$cacheDir = "$env:USERPROFILE\.aws\sso\cache"
$stamp = Get-Date -Format "yyyyMMdd-HHmmss"

Copy-Item $credPath "$credPath.bak-$stamp"

$cred = Get-Content -Raw $credPath | ConvertFrom-Json
$clientCache = Get-ChildItem $cacheDir -Filter "*.json" |
  ForEach-Object {
    try { Get-Content -Raw $_.FullName | ConvertFrom-Json } catch { $null }
  } |
  Where-Object { $_.clientId -and $_.clientSecret } |
  Select-Object -First 1

if (-not $clientCache) {
  throw "没有找到包含 clientId/clientSecret 的 SSO 缓存，请先重新完成一次 Kiro 登录授权。"
}

$cred.clientId = $clientCache.clientId
$cred.clientSecret = $clientCache.clientSecret
if ($cred.authMethod -eq "IdC") { $cred.authMethod = "idc" }

$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
[System.IO.File]::WriteAllText($credPath, ($cred | ConvertTo-Json -Depth 10), $utf8NoBom)

cd D:\kiro-rs
docker compose restart kiro-rs

最后再发一个最小请求验证：

$apiKey = "YOUR_API_KEY"

$body = @{
  model = "claude-sonnet-4-5-20250929"
  max_tokens = 64
  stream = $false
  messages = @(
    @{ role = "user"; content = "Say OK only." }
  )
} | ConvertTo-Json -Depth 8

Invoke-RestMethod `
  -Uri "http://127.0.0.1:8990/v1/messages" `
  -Method Post `
  -Headers @{
    "Content-Type" = "application/json"
    "x-api-key" = $apiKey
  } `
  -Body $body

Q：ccswitch 里请求地址应该填什么？

填 http://127.0.0.1:8990，不要填 /v1/messages。ccswitch 会自己拼接 Claude API 路径。

Q：可以接入 sub2api 吗？

可以，但前提是你的 sub2api 支持 Anthropic / Claude Compatible 上游。 如果 sub2api 和 Kiro RS 在同一台服务器同一个 Docker 网络里，Base URL 填 http://kiro-rs:8990。 如果只是本机自己测试，才使用 http://127.0.0.1:8990。

Q：sub2api 后台测试成功，但用户 key 调用报 No available accounts？

优先检查 用户 API Key 绑定的分组 和 Kiro RS 账号所在分组 是否一致。 实战中最容易出现的情况是：后台测试的是账号 A，但用户 key 走的是另一个空分组，所以 sub2api 日志里会出现 group_id=某个分组、error="no available accounts"。

Q：为什么 Claude Code 还是显示 Opus 4.8？

这通常是本机 Claude Code 配置没有指定 ANTHROPIC_MODEL，或者 ccswitch 仍然保留旧模型配置。 对 Kiro 分组建议显式设置 ANTHROPIC_MODEL=claude-sonnet-4-5-20250929，并把 ANTHROPIC_DEFAULT_OPUS_MODEL 也临时映射到 Sonnet 4.5。 改完配置后，需要关闭旧的 Claude Code 终端重新打开。

Q：如何停止或重启服务？

停止服务：

cd D:\kiro-rs
docker compose down

重启服务：

cd D:\kiro-rs
docker compose up -d

查看实时日志：

docker logs -f kiro-rs