qoder2api

qoder2api 把本机已经登录的 Qoder CLI 会话转换为 OpenAI 与 Anthropic 兼容接口。它是一个仅绑定回环地址的单进程用户服务，默认监听 127.0.0.1:8963。

本项目不会创建额度或绕过 Qoder 套餐限制。所有上游请求都会使用当前 Qoder 账号，且 Qoder 私有协议可能随官方客户端变化。

接口

GET  /v1/models
POST /v1/chat/completions
POST /v1/messages
GET  /healthz

前三个接口使用安装时生成的同一个随机密钥：OpenAI 客户端发送 Authorization: Bearer <key>，Anthropic 客户端发送 x-api-key: <key>。/healthz 免鉴权，只返回状态、产品版本和可用协议。

程序拒绝监听非回环地址。日志不记录 token、请求正文或 reasoning 内容。

支持平台

• Windows amd64
• macOS amd64、arm64
• Linux amd64、arm64

这些平台与 Qoder CLI 官方支持范围一致。使用前先安装 Qoder CLI 并运行 qoder login；服务启动只读取并解密本地 ~/.qoder/.auth，不会做远程登录探测。

安装和使用

需要 Node.js 22.14.0 或更高版本时，可通过 npm 首次分发：

npm install -g qoder2api
qoder2api install

也可以不保留全局 npm 包，直接执行一步安装：

npx -y qoder2api install

npm 安装本身不会注册或启动后台服务。另一种方式是从 GitHub Release 下载当前平台压缩包并解压。Windows 可直接双击 qoder2api.exe 完成安装，也可以与 macOS、Linux 一样显式执行：

qoder2api install
qoder2api status
qoder2api config get api_key

install 会把程序复制到用户目录、创建配置和随机 API Key、只为当前用户登记登录启动项，并立即启动：

• Windows：隐藏的当前用户登录任务
• macOS：~/Library/LaunchAgents/com.qoder2api.plist
• Linux：systemd user service

服务不会在异常退出后自动重启。停止服务会等待最多 30 秒让现有请求结束。

卸载默认保留配置和日志：

qoder2api uninstall
qoder2api uninstall --purge

--purge 只删除 qoder2api 自有数据，不删除 Qoder 登录态或 Pi、OpenClaw 等客户端配置。 通过 npm 全局安装的用户应先运行上述原生卸载命令，再运行 npm uninstall -g qoder2api。npm 不使用安装或卸载生命周期脚本修改后台服务；详细职责边界见 npm 分发文档。

CLI

qoder2api serve
qoder2api install
qoder2api uninstall [--purge]
qoder2api start|stop|restart|status
qoder2api logs [--follow] [--lines N]
qoder2api update
qoder2api doctor
qoder2api version
qoder2api config list|get|set|rotate-key
qoder2api integrate list
qoder2api integrate pi
qoder2api integrate pi --remove
qoder2api integrate openclaw
qoder2api integrate openclaw --remove

运行时配置优先级为：serve 参数 > QODER2API_* 环境变量 > config.json > 默认值。可用环境变量为 QODER2API_LISTEN、QODER2API_API_KEY、QODER2API_QODER_AUTH_DIR 和 QODER2API_DEFAULT_MODEL。

配置与状态目录遵循 Windows AppData、macOS 系统目录或 Linux XDG 约定；配置文件限制为当前用户读取。config list 会隐藏密钥，config get api_key 用于取得完整密钥。修改配置后执行 qoder2api restart。

Pi 集成

qoder2api integrate pi

该命令以临时文件和原子替换方式更新 ~/.pi/agent/models.json，修改前创建带 UTC 时间戳的备份。适配器只管理 qoder Provider 及 qoder/* 选择项，保留 OpenAI、openai-codex 和其他用户配置，并写入 off/low/medium/high/xhigh/max 思考等级映射。

成功后 Pi 会登记为受管理集成；以后 qoder2api update 成功会重新同步模型和密钥。删除集成使用：

qoder2api integrate pi --remove

OpenClaw 集成

先确认 OpenClaw CLI 已安装且 qoder2api 服务正常，然后运行：

qoder2api integrate openclaw

该命令通过 OpenClaw 官方 config patch 接口注册 qoder2api Provider，依次执行配置 dry-run、备份、写入、Schema 校验、模型目录检查和运行中 Gateway 的 SecretRef 刷新。模型在 OpenClaw 中使用 qoder2api/<模型 ID>，例如 qoder2api/Qwen3.8-Max。集成不会修改 OpenClaw 当前默认模型。

API Key 不会复制到 OpenClaw 配置。OpenClaw 使用文件型 SecretRef 从 qoder2api 的跨平台配置目录读取 /api_key。重复运行命令会同步最新模型能力；qoder2api update 成功后也会自动同步受管理的 OpenClaw 集成。

删除集成使用：

qoder2api integrate openclaw --remove

删除只移除由 qoder2api 管理的 Provider 和 SecretRef Provider，并保留 OpenClaw 的其他模型、默认模型、Fallback、Agent、Channel 与会话。修改前同样会创建备份；如果检测到同名但不属于 qoder2api 的 Provider，命令会拒绝覆盖或删除。

安全更新

qoder2api 不自动检查更新。手动运行：

qoder2api update

更新器只接受稳定语义版本，验证内置 Ed25519 公钥签名的清单及产物 SHA-256，并校验当前平台。替换前停止服务，替换后重启并检查 /healthz；任何替换、启动或健康检查错误都会恢复旧程序和原服务状态。Windows 使用临时 helper 避免覆盖运行中的 EXE。受管理的客户端集成同步失败不会回滚已经健康的新版本，但命令会返回非零并提示重新同步。

开发

需要 Go 1.24 或更高版本：

go test ./...
go vet ./...
go build -o qoder2api .

Qoder 私有协议客户端版本位于 internal/qoder.ClientProtocolVersion，与 qoder2api 产品版本彼此独立。对外模型名称和已验证的上游 key 映射统一维护在 internal/qoder，不会从 qoder --list-models 猜测。

Qoder model-server 已知的 SSE 非标准 framing、尾部元数据截断及允许的恢复边界记录在 docs/qoder-sse-recovery.md。修改流解析器前应先核对该文档，避免重新引入静默丢帧或语义修补。

发布 tag vX.Y.Z 会触发五平台构建、测试、静态检查、逐产物 version 验证、SHA-256 清单和 Ed25519 签名；GitHub Release 成功后再生成 npm tarball。发布仓库需配置：

• Actions variable UPDATE_PUBLIC_KEY：base64 编码的 32-byte Ed25519 公钥
• Actions secret UPDATE_SIGNING_KEY：base64 编码的 Ed25519 PEM 私钥
• Actions variable NPM_TRUSTED_PUBLISHING_ENABLED：首次手工发布并配置 npm Trusted Publisher 后设为 true

许可证：MIT。