跳转到正文
kxen

配置

查询用户配置、项目覆盖、角色路由、资源限制和扩展设置。

更新于 查看 Markdown

kxen 使用 TOML 保存非敏感配置。

配置层级

  • 用户配置： file:///Users/you/.agents/kxen/config.toml
  • 项目配置： file:///path/to/workspace/.agents/kxen/config.toml

项目配置只在 Workspace 已信任时加载，并且只能包含以下顶层表项:

  • roles
  • limits
  • hooks

这些表项按字段覆盖用户配置，Hook 列表按事件以 user -> project 顺序追加。项目配置出现其他顶层键时，整个 Workspace 配置加载失败并显示具体键名，不会静默忽略。

send_when_running、statusline、voice、embedding、composer_suggestions、search、coding_rules 和 experimental 只允许出现在用户配置。项目不能改变个人交互偏好、开启数据外发能力或扩大宿主机能力面。

用户配置示例

send_when_running = "queue"

[limits]
global_concurrent = 8
daily_token_budget = 500000

[limits.providers.anthropic]
concurrent = 2
rpm = 30
input_usd_per_million = 3.0
output_usd_per_million = 15.0
daily_cost_budget_usd = 10.0
circuit_failure_threshold = 3
circuit_cooldown_seconds = 60

[roles.execution]
provider = "xai"
model = "grok-4.6"
account = "work"
fallback = "research"

[roles.suggestion]
provider = "xai"
model = "grok-4.6"
fallback = "chat"

[voice]
engine = "apple"
fallback = ["openai"]
locale = "zh-CN"
transcribe_model = "whisper-1"

[embedding]
provider = "ollama"
model = "nomic-embed-text"
base_url = "http://localhost:11434"

[composer_suggestions]
enabled = true
semantic = false
llm = false

[search]
engine = "auto"

[experimental]
automatic_knowledge_distillation = false
browser_automation = false
remote_mcp = false

[custom_providers.example]
base_url = "https://api.example.com/v1"
protocol = "openai"
models = ["example-model"]
capabilities = ["text"]

# 需要固定查询参数的端点（如 Azure OpenAI）用 query_params 子表声明
[custom_providers.azure]
base_url = "https://<resource>.openai.azure.com/openai/deployments/<deployment>"
protocol = "openai"
models = ["gpt-4o"]
capabilities = ["text"]

[custom_providers.azure.query_params]
api-version = "2024-10-21"

search.engine、Google CSE、SearXNG、凭证来源和 fallback 行为见 Web 与 Search。

Web 与托盘

[web]
enabled = true
bind = "127.0.0.1"
port = 7824

[tray]
default_open = "window"
close_to_tray = true

web.enabled 是浏览器访问开关，系统托盘可以启停并持久化；桌面端 bind 保持 loopback，优先端口被占用时回退随机端口。tray.default_open 取 window 或 browser，决定托盘左键动作。两者都是用户级配置，浏览器访问与远程使用的完整说明见 Web 模式。

voice.fallback 不只是启动失败时的引擎顺序。当 engine = "apple" 时，把已配置的 cloud Provider 放入该数组也表示允许上传录音，用云端终稿升级本机识别。保存凭证本身不会授权上传；纯本地模式应保持 fallback = []。需要云转写的音频有 5 分钟和固定缓冲大小上限，超限时不会上传。

项目配置示例

受信任 Workspace 可以在 .agents/kxen/config.toml 中提供项目所需的角色、资源策略和 Hook:

[roles.execution]
provider = "custom:example"
model = "example-model"

[limits.providers."custom:example"]
concurrent = 2
rpm = 30

[hooks]
pre_tool_use = [{ matcher = "exec", command = "./scripts/check-command.sh" }]

custom_providers 只允许出现在用户配置。项目不能新增或覆盖自定义 endpoint，避免把用户保存的 custom:<name> API key 和会话内容重定向到项目控制的地址。项目 roles 可以引用用户已经定义的 custom Provider。

用户自定义远程端点必须使用 https://；http:// 只允许明确的 localhost 或 loopback IP。URL 不能内嵌 username 或 password。API key 和 OAuth token 只能来自用户认证存储。models 至少包含一个无空白身份，capabilities 只能使用 text、vision 或 audio。

embedding.base_url 使用相同的传输安全边界。显式 loopback OpenAI-compatible 或 Ollama endpoint 可以使用 HTTP；其他 endpoint 必须使用 HTTPS。

同一 [embedding] 配置也用于 OKF Knowledge retrieval。Knowledge 首轮始终可以用本地 BM25 返回结果；已配置 endpoint 时，缺失的 task query 和 concept 向量在后台经 MRM 预热，后续轮次从应用数据目录的 embedding-cache.json 读取。缓存 identity 包含 endpoint、provider、model 和内容 SHA-256；配置或文件内容改变后会自然生成新键并由 LRU 淘汰旧向量。项目文件不能提供 endpoint 或凭证，embedding 也不能改变 Rule、Skill、Command 等 handler 的激活语义。

Composer 主动推荐

composer_suggestions.enabled 默认是 true，只启用本地候选。它按完整 draft、最近 4 条有效 Session 文本、已选文件和目录、先前 context sources、最近 involved 文件、Git status/diff、文件路径、mtime 和受信任 Workspace 的截断文本摘要排序。索引尊重 .gitignore，不跟随 symlink，不读取敏感路径；未信任 Workspace 只使用路径和 mtime。

semantic 和 llm 默认都是 false，只能从用户 Settings 或用户配置显式启用:

  • semantic: 只把完整输入、近期 Session 文本和最多 8 个本地 shortlist 的截断摘要发送给 [embedding] Provider。向量缓存在 Workspace 隔离的 composer-suggestions/<workspace-hash>/embedding-cache.json 中。失败时保留 BM25 Local 结果。
  • llm: 通过 roles.suggestion 路由，缺少可用绑定时按该角色的 fallback 进入 chat。请求只包含截断 draft、近期 Session 文本、已选路径和本地候选 metadata，不包含图片、完整 diff 或完整源文件。返回的文件 id 必须来自本地 shortlist，文本候选不会自动发送。

两条远端路径都经过 Workspace MRM、并发/RPM/Circuit、durable usage attempt、Goal budget、10 秒 timeout、取消和输出上限。Session 正在运行或尚未持久化时不会发起远端推荐。Settings 的高级区域可以配置全部开关和 embedding endpoint。

网络代理

Provider、OAuth、Remote MCP、Web Fetch 和 Web Search 使用应用内受保护 connector，不继承 HTTP_PROXY、HTTPS_PROXY 或 ALL_PROXY 等环境变量。这些 connector 在实际连接前验证本次 DNS 解析的全部地址，避免系统代理把已检查的目标重定向到另一网络边界。

显式配置的 localhost 或 loopback endpoint 使用独立 loopback resolver，不会扩大普通公网 endpoint 的访问范围。需要强制使用企业出口代理的环境不能依赖 Shell 代理变量自动生效。Browser 使用自己的进程内受控代理，不使用这些环境变量。

资源限制

  • global_concurrent: 所有模型调用的全局并发上限，默认值为 8。
  • daily_token_budget: 按本地日期统计的已结算 token admission 阈值，留空表示不限。达到阈值后拒绝新请求，但单次请求和并发在途请求可能越过该值，因此它不是账单硬上限。
  • limits.providers.<id>.concurrent: Provider 并发上限。
  • limits.providers.<id>.rpm: 每个账号的 60 秒请求上限。
  • input_usd_per_million 和 output_usd_per_million: 用户实际合同或账单的计价口径。
  • daily_cost_budget_usd: 按上述显式单价和已结算 usage 计算的 Provider 每日金额 admission 阈值，不是账单硬上限。
  • circuit_failure_threshold: 连续失败熔断阈值，默认 3，设置 0 关闭。
  • circuit_cooldown_seconds: 熔断冷却时间，默认 60 秒。

多个账号共享 Provider 并发池，RPM 按账号分别记录。实际在飞调用、RPM 窗口和路由历史由进程共享；Circuit 按 Workspace、Provider 和自定义 endpoint 隔离。切换 Workspace 不会重置共享并发或 RPM，也不会让一个 Workspace 的端点故障熔断另一个 Workspace。kxen 不内置可能漂移的公开模型价格；没有显式单价时金额保持 UNKNOWN，配置金额预算但缺少单价会失败关闭。token 趋势按本地日期持久化 90 天，Settings 展示最近 14 天。

沙箱

QuickJS 沙箱（workflow 与动态工具 dyn__*）的资源上限在 [sandbox] 下配置，只读取个人配置，项目 .agents/kxen/config.toml 不能放宽沙箱边界：

[sandbox]
workflow_timeout_seconds = 600                  # workflow 墙钟超时，缺省 600
memory_limit_mb = 64                            # QuickJS 堆内存上限（两个宿主共用），缺省 64
dynamic_tool_timeout_seconds = 300              # 动态工具沙箱超时，缺省 300
dynamic_tool_max_implementation_chars = 20000   # 动态工具实现源码上限（字符），缺省 20000

留空或设为 0 均取缺省值。栈深（1MB）与单次 workflow 的 agent 派发数（32）保持内置，不可配置。

实验能力

  • automatic_knowledge_distillation: 定期使用每个 Session 所属 Workspace 的 MRM 和模型路由处理近期内容，并且只写个人知识。
  • browser_automation: 允许 Agent 驱动本机 Chrome，页面数据可能进入当前 Provider 上下文。
  • remote_mcp: 加载 Streamable HTTP 和 SSE server，工具参数会发送给远端 server。

三项默认都是 false，只读取个人配置。项目 .agents/kxen/config.toml 不能扩大这些能力面。

运行中消息

  • queue: 新消息进入等待队列。
  • interrupt: 取消当前 run 后处理新消息。

Hook

Hook 可以在 pre_tool_use、post_tool_use、session_start、stop、notification、teammate_idle 和 task_completed 事件上运行命令，并通过 matcher 限定工具名、Session、通知或 Team 对象。用户 Hook 先加载，受信任 Workspace 的项目 Hook 随后追加。

Hook 命令在所属 Workspace 中执行，限时 10 秒，并通过 KXEN_EVENT、KXEN_TOOL 和 KXEN_PAYLOAD 获得事件上下文。命令仍受 Shell Safety 约束；Ask 需要当次 Approval，没有 Approval channel 时失败关闭。pre_tool_use 非零退出、Safety 拒绝、超时或未获批准会阻止工具；post_tool_use 失败只记录。task_completed Hook 成功后 Team task 才提交为 completed，其他 named Hook 按对应生命周期记录失败。

凭证

API key、OAuth access token 和 refresh token 不写入 TOML。配置文件只引用 Provider、账号名、模型和非敏感端点信息。当前消息、附件、注入知识和工具结果会按需要发送给实际选中的模型 Provider，设置页会显示对应隐私提示。

编辑此页
导航

输入关键词以搜索…

↑↓ 移动↵ 打开Esc 关闭