配置

AgentHub 的配置按职责分层。本地执行配置靠近 Desktop/Edge，身份和团队配置放在 Hub，provider 凭据不能进入前端代码。

配置状态

下面描述的是公开配置契约和发布边界。Hub、Edge、Desktop 继续收敛期间，具体文件名和参数仍可能调整。

配置分层

层级	负责人	典型配置	公开文档规则
Desktop	用户设备	Local Edge 地址、界面语言、主题、最近 workspace	可公开描述
Local Edge	本地操作者	Workspace allowlist、runtime profile、adapter path、本地端口	不含 secret 时可公开
Hub Server	产品后端	OIDC client、项目、设备、会话、审计、路由	描述行为，不写私有部署路径
Web	静态客户端 + Hub	Hub URL、官网/文档 metadata、功能可用状态	不放模型 key 或本地文件路径
Integration Gateway	服务端集成	飞书/Lark app id、事件路由、队列名、绑定状态	Secret 留在服务端

本地 Desktop 与 Edge

本地预览时，Desktop 应指向 127.0.0.1:3210 这类 loopback Local Edge 地址。Edge 在启动 runtime adapter 前，应配置明确的 workspace allowlist。

建议本地默认值：

Local Edge 只绑定 loopback；
用 mock runtime 验证 UI 和事件流；
Claude Code、Codex、OpenCode 只有在本机 CLI 已安装并完成鉴权后再启用；
runtime 失败、超时或需要审批时也要发出 run event；
本地 workspace 路径不要进入截图、公开文档、issue 评论或浏览器存储。

Hub 与 Web

Hub 是身份会话、项目、设备、路由和审计的产品边界。Web 是 Hub-backed 协作界面，不能绕过 Hub 直接访问 Local Edge 或本地文件。

Hub/Web 配置需要回答：

问题	预期负责人
当前认证的 TokenDance ID subject 是谁？	TokenDance ID + Hub
用户能访问哪个项目和组织？	Hub
哪个设备或 Edge 可以接收任务？	Hub
Run 能触达哪个 workspace？	Edge allowlist + Hub policy
Web/Desktop 展示哪些事件？	Hub + Edge event contract

Runtime Profile

Runtime profile 把 Agent Profile 连接到具体 adapter。一个可审查的 profile 应声明：

展示名称和用途；
adapter 类型，例如 mock、Claude Code、Codex、OpenCode 或 custom；
允许的 workspace 和审批策略；
模型/provider 需求，但不暴露真实 key；
timeout、cancel、retry 行为；
event 能力，包括消息、tool call、diff、artifact 和 approval。

Profile 应足够小，便于审查。如果某个 profile 需要宽泛文件系统权限、特权命令或隐藏 provider 凭据，应把它当作安全审查项，而不是普通 preset。

一个公开文档里可以保留的 profile 示例应只展示结构，不包含真实路径和密钥：

JSON

{
  "id": "codex-local",
  "label": "Codex Local",
  "adapter": "codex",
  "edge": "http://127.0.0.1:3210",
  "workspacePolicy": "allowlist",
  "approval": {
    "write": "ask",
    "shell": "ask"
  },
  "events": ["run.message.delta", "run.tool.call", "run.diff.ready", "run.approval.requested", "run.completed"]
}

真实 profile 可以多一个本地 adapter path 或 provider 环境变量名，但绝不要把实际 key 值写进配置文件、公开文档或浏览器存储。

配置清单

接本地链路或审查 PR 时使用这张清单。具体 source 文件名可能随实现变化；但归属和校验方式不应随之变化。

设置	Owner	Source	安全示例	校验
Local Edge URL	Desktop	UI setting 或本地 config	`http://127.0.0.1:3210`	Desktop 显示选中 Edge online
Edge bind address	Local Edge	CLI flag 或本地 config	`127.0.0.1:3210`	loopback health check 有响应
Workspace allowlist	Local Edge	CLI flag 或本地 config	`workspace_123`	workspace 外返回 `workspace_outside_allowlist`
Runtime profile	Local Edge	CLI flag 或 profile config	`agenthub-runner-mock`	runtime inventory 列出 mock profile
Agent profile	Hub/Desktop	Hub API 或本地 profile registry	`codex-local`	新 run 记录选中的 profile
Approval policy	Edge + Desktop	profile policy	`write=ask`, `shell=ask`	write/shell action 暂停等待审批
Hub URL	Web/Desktop	public env 或本地 config	`https://hub.example.invalid`	Web 调 Hub，不直连 Local Edge
TokenDance ID issuer	Hub	server-side OIDC config	`https://id.example.invalid`	login exchange 创建 Hub session
飞书/Lark gateway route	Integration Gateway	server-side route config	`/integrations/feishu/events`	challenge 和 event callback 通过

环境变量归属

环境变量按拥有者分开，不要用单个 .env 同时承载官网、Hub、Edge 和 runtime 的全部 secret：

变量类型	归属	公开文档怎么写
Provider key	本地 runtime 或服务端 secret store	只写变量名和用途，不写值
Edge token	Local Edge / Desktop 本地配置	只用于 loopback 边界，避免截图
OIDC client id	Hub 或公开站点低风险登录	可以公开 client id 和 discovery URL
OIDC client secret	Hub Server / TokenDance ID 客户端配置	不公开
Session signing secret	Hub Server	不公开
Feishu/Lark secret	Integration Gateway	不公开

本地配置示例

公开安全的本地示例可以展示意图，但不暴露私有路径或 secret：

JSON

{
  "desktop": {
    "edgeUrl": "http://127.0.0.1:3210",
    "language": "auto",
    "theme": "system"
  },
  "edge": {
    "bind": "127.0.0.1:3210",
    "workspacePolicy": "allowlist",
    "workspaces": ["workspace_123"],
    "defaultRuntime": "mock"
  },
  "profiles": [
    {
      "id": "mock-local",
      "adapter": "mock",
      "approval": { "write": "ask", "shell": "deny" }
    }
  ]
}

把 mock runtime 换成 Claude Code、Codex 或 OpenCode 时，CLI 登录状态和 provider 凭据仍应留在该 runtime 归属的本地环境或 secret store 中。AgentHub profile 只引用 adapter 和所需环境变量名。

Feature Flag

AgentHub 的多个产品面成熟度不同，因此 feature flag 应明确可见。

Flag 区域	默认公开口径	原因
Desktop mock preview	官网 demo 可开启	展示 UI，不触碰本地文件
真实 runtime adapter	仅本地预览	需要本地 CLI 登录和 provider credential
Hub-backed Web task	预览 / 进行中	需要 Hub session、project、routing 和 audit 证据
飞书/Lark 入口	开发中	需要 gateway 校验、queue、binding 和 card 证据
Remote/Cloud Edge	开发中	需要 device identity、relay、degraded state 和 audit

不要用隐藏 flag 静默开启本地文件系统访问、shell 命令、provider credential 或远程路由。任何改变信任边界的 feature，都应同步到安全边界、产品状态和路线图。

Secret

以下内容不能进入公开文档、前端 bundle、浏览器存储、截图或飞书/Lark 卡片 payload：

模型 provider API key；
TokenDance ID client secret；
Hub session signing secret；
飞书/Lark verification token、encrypt key、app secret、tenant token、OAuth refresh token；
生产 host、SSH alias、web root、backup path、rollback command。

TokenDance API key 用于模型 API 调用，不是 AgentHub 登录凭据，也不应被当作浏览器会话使用。

校验

把配置分享给其他成员前：

启动 Local Edge，确认 health check 成功。
启动 Desktop，确认连接到预期 Edge。
运行 mock task，确认出现 run.started、run.message.delta 和终态事件。
只有在本地凭据已经放在仓库外之后，才运行真实 runtime。
确认 Web 以 Hub 为边界，不直接请求本地文件访问。
检查日志和截图，确认没有 secret、私有绝对路径和不应公开的 raw model output。

下一步按快速上手跑通本地链路，再阅读安全边界了解权限和 secret 边界。