对接配置

Starlens 的对接配置分为四类：登录认证、服务端环境变量、外部工具访问、AI Provider。建议先把登录和数据库跑通，再开启 Token、MCP 和 AI 能力。

GitHub OAuth

GitHub OAuth 用于浏览器登录和 Stars 同步授权。创建 OAuth App 后，需要配置回调地址：

{NEXTAUTH_URL}/api/auth/callback/github

本地开发示例：

http://localhost:3000/api/auth/callback/github

生产环境示例：

https://your-starlens.example.com/api/auth/callback/github

必填变量：

服务端环境变量

最小可运行配置：

AUTH_SECRET="replace-with-random-secret"
NEXTAUTH_URL="http://localhost:3000"
AUTH_GITHUB_ID="github-client-id"
AUTH_GITHUB_SECRET="github-client-secret"
DATABASE_URL="postgres://starlens:starlens@localhost:54329/starlens_dev"
TOKEN_ENCRYPTION_SECRET="replace-with-random-32-byte-secret"

可选 AI 默认配置：

SYSTEM_AI_API_KEY="sk-..."
SYSTEM_AI_BASE_URL="https://api.openai.com/v1"
SYSTEM_AI_MODEL="gpt-4.1-mini"

变量说明：

个人 API Token

个人 API Token 用于 CLI、脚本和 Agent 访问 Starlens API。Token 在设置页创建，明文只展示一次，服务端只保存哈希、前缀和后缀。

请求头格式：

Authorization: Bearer stl_xxx

Token 适合调用：

Token 管理接口只允许浏览器会话访问。Bearer Token 不能继续创建新的 Token。

HTTP API 示例

Hermes、OpenClaw 和自定义 agent runtime 默认通过 HTTP API 接入 Starlens。不要为这类 agent 优先接本地 MCP stdio server；HTTP 直连链路更短，也更适合服务端、容器、远程 worker、审计和重试。

Agent 运行时只需要两个配置值：

STARLENS_TOKEN="stl_xxx"
STARLENS_API_BASE_URL="https://your-starlens.example.com"

搜索收藏仓库：

curl "$STARLENS_API_BASE_URL/api/search?q=vector&page=1&pageSize=20&sort=relevance" \
  -H "Authorization: Bearer $STARLENS_TOKEN"

更新仓库备注和重点收藏：

curl -X PATCH "$STARLENS_API_BASE_URL/api/repos/{repoId}" \
  -H "Authorization: Bearer $STARLENS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"isFavorite":true,"note":"适合做本地 RAG 原型评估。"}'

添加标签：

curl -X POST "$STARLENS_API_BASE_URL/api/repos/{repoId}/tags" \
  -H "Authorization: Bearer $STARLENS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tag":"rag"}'

AI Provider

AI Provider 在设置页维护，支持多个配置，但运行时通常读取启用且设为默认的配置。

配置建议：

• displayName 使用能识别用途的名称，例如“公司网关”“个人 Gemini”。
• model 填实际可用模型 ID，不要填展示名。
• extraHeaders 只放网关必需的额外 header，不要放无关业务信息。
• 保存后使用“验证”检查密钥、Base URL 和模型列表是否可用。

MCP Server

MCP server 位于 apps/mcp，通过 stdio 暴露 Starlens 工具。它只推荐给 Codex、opencode、Claude Code、Cursor、支持 MCP 的 IDE 和桌面 MCP 客户端。Hermes、OpenClaw 和服务端 agent runtime 应使用上面的 HTTP API。

它不重新实现业务逻辑，只通过 @starlens/agent-tools 调用 HTTP API。

本地启动：

STARLENS_TOKEN="stl_xxx" \
STARLENS_API_BASE_URL="http://localhost:3000" \
corepack pnpm mcp:start

Cursor 配置示例：

{
  "mcpServers": {
    "starlens": {
      "command": "corepack",
      "args": ["pnpm", "mcp:start"],
      "cwd": "/path/to/starlens",
      "env": {
        "STARLENS_TOKEN": "stl_xxx",
        "STARLENS_API_BASE_URL": "http://localhost:3000"
      }
    }
  }
}

终端 Coding CLI 配置示例：

Codex、opencode、Claude Code 属于本地开发工具客户端，推荐通过 MCP 接入。先把 token 放入本机私有 env 文件，避免在多个配置文件里散落明文：

mkdir -p ~/.starlens
chmod 700 ~/.starlens

cat > ~/.starlens/agent.env <<'EOF'
export STARLENS_TOKEN="stl_xxx"
export STARLENS_API_BASE_URL="http://localhost:3000"
EOF

chmod 600 ~/.starlens/agent.env

Codex ~/.codex/config.toml：

[mcp_servers.starlens]
type = "stdio"
command = "zsh"
args = ["-lc", "source \"$HOME/.starlens/agent.env\" && cd \"/path/to/starlens\" && corepack pnpm mcp:start"]
startup_timeout_sec = 30
default_tools_approval_mode = "approve"

opencode ~/.config/opencode/opencode.json：

{
  "mcp": {
    "starlens": {
      "type": "local",
      "command": [
        "zsh",
        "-lc",
        "source \"$HOME/.starlens/agent.env\" && cd \"/path/to/starlens\" && corepack pnpm mcp:start"
      ],
      "enabled": true,
      "timeout": 10000
    }
  }
}

Claude Code：

claude mcp add-json starlens '{
  "type": "stdio",
  "command": "zsh",
  "args": [
    "-lc",
    "source \"$HOME/.starlens/agent.env\" && cd \"/path/to/starlens\" && corepack pnpm mcp:start"
  ]
}'

可用 MCP 工具：

安全建议

• 不要把 .env、真实 Token 或 AI API Key 提交到仓库。
• 生产环境为 AUTH_SECRET 和 TOKEN_ENCRYPTION_SECRET 使用高强度随机值。
• 为不同设备或 Agent 创建不同 Token，便于撤销和审计。
• 如果 GitHub OAuth 回调域名变更，需要同步修改 NEXTAUTH_URL 和 GitHub OAuth App 配置。
• 如果 AI Provider 使用企业网关，优先通过额外 header 传递网关要求，不要在提示词或备注里存放密钥。