CodeBuddy Local Gateway

非官方社区项目，与腾讯、CodeBuddy 或各模型官方团队无隶属或关联关系。

这个项目把当前系统用户已经登录的 CodeBuddy 会话复用为两个本地入口，不需要 TokenHub API Key，也不会复制或导出 CodeBuddy 登录凭据：

1. MCP 桥接：枚举当前账号可用模型，并把指定模型作为只读推理子 Agent。
2. OpenAI 兼容反代：提供动态模型列表和 Chat Completions 文本接口。

hy3-local-gateway 是为兼容已有安装保留的包名和命令名；网关已经不再固定使用 Hy3。核心实现在 src/codebuddy.js，ask_hy3 只是兼容入口。

环境要求

• Node.js 20 或更高版本。
• 使用当前系统用户运行过 codebuddy 并完成登录。
• CodeBuddy 的 /model 菜单中能够看到并使用所需模型。

推荐直接从 GitHub 全局安装：

npm install --global github:Embracecactus/hy3-local-gateway

安装后会得到一个与源码目录无关的命令：

hy3-local-gateway --help

如果需要参与开发，也可以克隆仓库后安装并链接本地命令：

npm install
npm link

功能一：MCP 桥接

MCP Server 通过 stdio 提供三个工具：

• list_codebuddy_models：读取当前 CodeBuddy 登录账号可用的模型 ID。
• ask_codebuddy：通过 model 参数调用任意可用模型，默认使用 hy3。
• ask_hy3：兼容旧配置的 Hy3 固定入口。

模型在这些入口中不能读取文件、执行命令或修改项目。调用方需要先读取必要上下文， 再把相关代码和任务完整放进 prompt。

Codex 全局注册：

codex mcp add codebuddy-local -- hy3-local-gateway mcp

查看注册状态：

codex mcp get codebuddy-local

重启 Codex 后可以直接请求：

先调用 list_codebuddy_models 获取模型列表，再读取相关代码并调用 ask_codebuddy，
选择 hy3 对必要代码做一次独立审查。

原来已经注册为 hy3-local 的配置不需要修改，ask_hy3 仍然可用。

其他 MCP Host 使用相同的 stdio 配置：

{
  "command": "hy3-local-gateway",
  "args": ["mcp"]
}

手动启动或测试：

hy3-local-gateway mcp

# 在源码仓库中开发时：
npm run start:mcp
npm run test:mcp

功能二：OpenAI Chat Completions 反代

启动：

hy3-local-gateway proxy

# 在源码仓库中开发时：
npm run start:proxy

默认连接信息：

Base URL: http://127.0.0.1:8787/v1
API Key: local-placeholder
Default model: hy3

默认只监听回环地址，不校验入站 API Key。这里的 local-placeholder 只是满足部分 客户端的必填校验，不参与上游 CodeBuddy 认证。

接口

• GET /health
• GET /v1/models：动态读取当前 CodeBuddy 账号可用模型并缓存 5 分钟。
• POST /v1/chat/completions：请求中的 model 会原样交给 CodeBuddy。

查看模型：

curl http://127.0.0.1:8787/v1/models \
  -H 'Authorization: Bearer local-placeholder'

普通请求：

curl http://127.0.0.1:8787/v1/chat/completions \
  -H 'Authorization: Bearer local-placeholder' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "model": "hy3",
    "messages": [
      {"role": "user", "content": "只回复 hello"}
    ]
  }'

流式请求：

curl -N http://127.0.0.1:8787/v1/chat/completions \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "model": "hy3",
    "messages": [{"role": "user", "content": "介绍一下你自己"}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

Python OpenAI SDK：

from openai import OpenAI

client = OpenAI(
    api_key="local-placeholder",
    base_url="http://127.0.0.1:8787/v1",
)

models = client.models.list()
print([model.id for model in models.data])

response = client.chat.completions.create(
    model="hy3",
    messages=[{"role": "user", "content": "你好"}],
)

print(response.choices[0].message.content)

CC Switch 读取模型

CC Switch 的供应商文档 会使用配置的 API Key 请求 OpenAI 兼容的 /v1/models。先启动本项目的 proxy， 然后在 CC Switch 新增或编辑支持模型获取的自定义供应商：

Endpoint / Base URL: http://127.0.0.1:8787/v1
API Key: local-placeholder
API Format: OpenAI Chat Completions

点击模型输入框旁的“获取模型”按钮，即可读取本机 CodeBuddy 当前账号的模型列表。 本项目暂不实现 OpenAI Responses API；给 Codex 配置供应商时应选择 Chat Completions 格式，或者使用 CC Switch 提供的本地协议转换功能。

反代配置

推荐使用新的 CODEBUDDY_PROXY_* 环境变量：

CODEBUDDY_PROXY_PORT=9000 hy3-local-gateway proxy

设置本地访问令牌：

CODEBUDDY_PROXY_TOKEN='请换成随机长字符串' hy3-local-gateway proxy

设置令牌后，请求必须携带：

Authorization: Bearer 请换成随机长字符串

配置项：

环境变量	默认值	说明
CODEBUDDY_PROXY_HOST	127.0.0.1	监听地址
CODEBUDDY_PROXY_PORT	8787	监听端口
CODEBUDDY_PROXY_TOKEN	空	入站 Bearer Token
CODEBUDDY_PROXY_TIMEOUT_MS	300000	单次模型调用超时
CODEBUDDY_PROXY_MAX_BODY_BYTES	2097152	最大请求体大小
CODEBUDDY_QUERY_TIMEOUT_MS	300000	MCP 单次模型调用超时
CODEBUDDY_MODEL_DISCOVERY_TIMEOUT_MS	60000	模型发现超时
CODEBUDDY_MODEL_CACHE_TTL_MS	300000	动态模型缓存时间
CODEBUDDY_MODELS	空	可选的逗号分隔静态模型列表

旧的 HY3_PROXY_HOST、HY3_PROXY_PORT、HY3_PROXY_TOKEN、 HY3_PROXY_TIMEOUT_MS 和 HY3_PROXY_MAX_BODY_BYTES 仍兼容；同一配置同时出现时， CODEBUDDY_PROXY_* 优先。

正常情况下不要设置 CODEBUDDY_MODELS，网关会读取真实模型列表。只有 CodeBuddy 版本暂不支持动态发现或需要固定暴露模型时，才使用例如：

CODEBUDDY_MODELS='hy3,另一个模型ID' hy3-local-gateway proxy

如果监听地址不是回环地址，程序会强制要求配置 CODEBUDDY_PROXY_TOKEN。不建议将 该服务直接暴露到公网。

兼容范围与限制

反代实现的是 Chat Completions 的实用子集：

• 支持文本 system、developer、user、assistant、tool 历史消息。
• 支持普通 JSON 响应。
• 支持 SSE 响应格式，但当前是缓冲式流式：等待模型完成后一次发送正文， 不是逐 token 输出。
• 支持 reasoning_effort 的 low、medium、high、xhigh。
• 支持 response_format: {"type": "text"} 和 json_object。
• 不支持图片、音频等非文本内容。
• 不支持外部 tools / Function Calling；这类请求会返回明确的 HTTP 400。
• 不提供 OpenAI Responses API。

因此：

• 需要模型作为独立评审或推理子 Agent 时，优先使用 MCP。
• 只需要 OpenAI 兼容文本对话和模型发现的客户端，可以使用本地反代。
• 依赖 Function Calling 的完整编码 Agent，不能把这个反代当成透明底层模型。

验证命令

不调用模型、不消耗 CodeBuddy 额度的离线验证：

npm test

使用当前 CodeBuddy 登录实际调用 Hy3：

npm run test:hy3

从系统临时目录验证全局安装，不依赖源码路径：

npm run test:global:mcp
npm run test:global:models
npm run test:global:chat -- --chat-model=glm-5.1

所有真实模型调用都会消耗当前登录 CodeBuddy 账号对应的额度。