gongzhiyong
1f21309597
Remove user-facing new-api naming; Docker/network/container names use heicode. Go imports updated; Dockerfiles and workflows ldflags fixed. Made-with: Cursor
77 lines
3.1 KiB
Markdown
77 lines
3.1 KiB
Markdown
# 环境变量手册（Heicode 客户端）
|
||
|
||
仅列出 Heicode 客户端（`cc-haha/`）当前 **代码中已支持** 的环境变量。Manager（`heicode/`）的环境变量请以 `heicode/CLAUDE.md` 与 `heicode/.env.example` 为准。
|
||
|
||
> 来源代码：
|
||
> - `cc-haha/src/server/config/providerPresets.ts`
|
||
> - `cc-haha/src/server/api/heicode-auth.ts`
|
||
> 改动这些变量后 **需要重启** 本地服务才能生效。
|
||
|
||
## 一、Provider Base URL 覆盖
|
||
|
||
让客户端把某个 provider 的 `baseUrl` 指向本地或自部署网关，常用于联调本机 Manager。
|
||
|
||
| 变量 | 作用对象 | 示例 |
|
||
|------|----------|------|
|
||
| `HEICODE_TAIJIAICLOUD_BASE_URL` | `taijiaicloud` provider | `http://localhost:3000` |
|
||
| `HEICODE_CLAWDROUTER_BASE_URL` | `clawdrouter` provider | `http://localhost:4000` |
|
||
|
||
行为：
|
||
- 模块加载时读取，未设置则用 preset 中的默认 baseUrl
|
||
- 末尾斜杠会被自动去除
|
||
|
||
## 二、OAuth 配置
|
||
|
||
客户端浏览器登录会按如下顺序解析授权地址：
|
||
|
||
1. 若设置了 `HEICODE_<PROVIDER>_OAUTH_AUTHORIZE_URL`，用其值
|
||
2. 否则使用 `<baseUrl>/heicode/oauth/authorize`
|
||
|
||
`<PROVIDER>` 取值范围与 base URL 相同（`TAIJIAICLOUD` / `CLAWDROUTER`）。
|
||
|
||
| 变量 | 用途 | 默认 |
|
||
|------|------|------|
|
||
| `HEICODE_<PROVIDER>_OAUTH_AUTHORIZE_URL` | OAuth 授权入口 | `<baseUrl>/heicode/oauth/authorize` |
|
||
| `HEICODE_<PROVIDER>_OAUTH_TOKEN_URL` | OAuth `code → token` 交换端点 | `<baseUrl>/heicode/oauth/token` |
|
||
| `HEICODE_<PROVIDER>_OAUTH_CLIENT_ID` | OAuth Client ID（启用 PKCE 时必需） | 未设置 |
|
||
| `HEICODE_<PROVIDER>_OAUTH_SCOPE` | OAuth Scope（可选，与 `client_id` 一并使用） | 未设置 |
|
||
|
||
设置规则：
|
||
- **仅设置 AUTHORIZE_URL**：客户端跳转浏览器后，平台必须直接以 `?token=...` 形式回调（适合 Manager 当前的 loopback 实现）
|
||
- **同时设置 AUTHORIZE_URL + TOKEN_URL + CLIENT_ID**：启用标准 OAuth2 Authorization Code + PKCE
|
||
- **未设置 AUTHORIZE_URL** 时，客户端默认用 `<baseUrl>/heicode/oauth/authorize`，与 Manager 默认路由对齐
|
||
|
||
详见 [`../integration/heicode-oauth-flow.md`](../integration/heicode-oauth-flow.md)。
|
||
|
||
## 三、本地服务
|
||
|
||
| 变量 | 用途 | 默认 |
|
||
|------|------|------|
|
||
| `SERVER_PORT` | 客户端本地 HTTP/WS 服务端口 | `3456` |
|
||
|
||
## 四、配置示例
|
||
|
||
### 仅切 baseUrl 到本地 Manager
|
||
|
||
```bash
|
||
HEICODE_TAIJIAICLOUD_BASE_URL=http://localhost:3000 \
|
||
bun run src/server/index.ts
|
||
```
|
||
|
||
### 启用浏览器登录 + 标准 OAuth
|
||
|
||
```bash
|
||
export HEICODE_TAIJIAICLOUD_BASE_URL=http://localhost:3000
|
||
export HEICODE_TAIJIAICLOUD_OAUTH_AUTHORIZE_URL=http://localhost:3000/heicode/oauth/authorize
|
||
export HEICODE_TAIJIAICLOUD_OAUTH_TOKEN_URL=http://localhost:3000/heicode/oauth/token
|
||
export HEICODE_TAIJIAICLOUD_OAUTH_CLIENT_ID=heicode-desktop
|
||
export HEICODE_TAIJIAICLOUD_OAUTH_SCOPE=models:read,messages:write
|
||
bun run src/server/index.ts
|
||
```
|
||
|
||
> 注：当前 Manager 的实现仅以 loopback 直接回 `?token=...`，标准 OAuth 等待平台侧补全后再启用。
|
||
|
||
## 五、变更约束
|
||
|
||
新增环境变量时请同步更新本文与代码注释，避免漂移。本文不是 `.env.example` 的替代，仅作为 docs 索引。
|