对接配置

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://your-openai-compatible-provider.example/v1"
SYSTEM_AI_MODEL="your-model-id"
SYSTEM_AI_PROVIDER_TYPE="openai_compatible"
SYSTEM_AI_ENABLED="true"
SYSTEM_AI_FALLBACK_MODEL=""
SYSTEM_AI_EXTRA_HEADERS=""

变量说明：

个人 API Token

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

请求头格式：

Authorization: Bearer stl_xxx

Token 适合调用：

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

个人 Token 当前是账号级粗粒度凭据，并不只读。它可以调用仓库写操作、触发同步和管理 AI Provider 配置；请按完整账号凭据保存，并为不同设备或 Agent 分别创建 Token，便于撤销。

Agent Skill

Skill 是最轻量的行为说明层，适合 Claude Code、Cursor、VS Code、OpenClaw、Hermes 等支持 Skill 文件的客户端。Skill 声明何时调用 Starlens、使用哪些端点以及如何处理错误；MCP 是可选的工具传输层，两者职责不同。

推荐使用 CLI 一键安装：

npm install -g @starlens-app/cli@latest
stars setup

stars setup 会调用 agentskills.io 标准命令 npx skills add https://github.com/yuanyang749/starlens 安装 Skill，然后引导你为支持的客户端配置 MCP。Skill 的实际安装位置由 skills CLI 根据客户端约定管理，Starlens 不再自行复制或维护客户端目录。

只安装 Skill、不配置 MCP：

npx skills add https://github.com/yuanyang749/starlens

Skill 已安装、只配置 MCP：

stars install-mcp

对于不支持 Skill 文件的自定义 agent runtime，Agent 运行时需要以下配置值：

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

接入原则：

• 如果 Agent 支持 skill/instruction 文件，使用 stars setup 完成 Skill 与 MCP 配置，或直接使用 npx skills add 只安装 Skill。
• 如果 Agent 只支持 system prompt，把安装后的 SKILL.md 内容粘贴到该 Agent 的长期指令里。
• Token 放在 Agent 的 secret/env 配置里，不要写进 prompt 或仓库文件。
• Hermes、OpenClaw 这类服务端/远程 runtime 默认使用 HTTP API，不优先接 MCP。

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 在设置页维护，支持多个配置，但运行时通常读取启用且设为默认的配置。

当前自然语言问答和多轮聊天运行时要求 OpenAI-compatible Chat Completions。Native 类型目前用于保存配置和拉取模型列表；如需在问答中调用对应服务，请选择 openai_compatible 并填写该服务的 OpenAI-compatible Base URL。

配置建议：

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

MCP Server

MCP server 适合 Codex、opencode、Claude Code、Cursor、支持 MCP 的 IDE 和桌面 MCP 客户端。Hermes、OpenClaw 和服务端 agent runtime 应使用上面的 HTTP API。

推荐先通过 stars setup 完成 Skill 安装和 MCP 配置；如果 Skill 已经安装，使用 stars install-mcp 只写入 MCP 配置：

stars setup
# 或
stars install-mcp

也可以参考下面两种模式的手动配置方法。

托管模式（HTTP MCP）

使用托管服务 https://starlens.520ai.xin 时，MCP 通过 HTTP 协议连接，无需在本地启动任何服务，只需 API Token。

Claude Code：

claude mcp add-json starlens '{
  "type": "http",
  "url": "https://starlens.520ai.xin/mcp",
  "headers": { "Authorization": "Bearer stl_xxx" }
}'

Cursor ~/.cursor/mcp.json：

{
  "mcpServers": {
    "starlens": {
      "url": "https://starlens.520ai.xin/mcp",
      "headers": { "Authorization": "Bearer stl_xxx" }
    }
  }
}

Codex ~/.codex/config.toml：

[mcp_servers.starlens]
url = "https://starlens.520ai.xin/mcp"
http_headers = {Authorization = "Bearer stl_xxx"}
startup_timeout_sec = 30
default_tools_approval_mode = "approve"

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

{
  "mcp": {
    "starlens": {
      "type": "remote",
      "url": "https://starlens.520ai.xin/mcp",
      "headers": { "Authorization": "Bearer stl_xxx" },
      "enabled": true
    }
  }
}

自部署模式（stdio MCP）

使用自己部署的 Starlens 实例时，MCP 通过 stdio 协议启动本地进程。先把 token 写入本机私有 env 文件：

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

cat > ~/.starlens/agent.env <<'EOF'
export STARLENS_TOKEN="stl_xxx"
export STARLENS_API_BASE_URL="https://your-starlens.example.com"
EOF

chmod 600 ~/.starlens/agent.env

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"
  ]
}'

Cursor ~/.cursor/mcp.json：

{
  "mcpServers": {
    "starlens": {
      "command": "corepack",
      "args": ["pnpm", "mcp:start"],
      "cwd": "/path/to/starlens",
      "env": {
        "STARLENS_TOKEN": "stl_xxx",
        "STARLENS_API_BASE_URL": "https://your-starlens.example.com"
      }
    }
  }
}

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
    }
  }
}

本地直接启动（调试用）：

STARLENS_TOKEN="stl_xxx" \
STARLENS_API_BASE_URL="http://localhost:3000" \
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 传递网关要求，不要在提示词或备注里存放密钥。