start / overview

What corlinman is.corlinman 是什么。总览

corlinman is a self-hosted intelligent-agent platform: one binary that gives a language model durable memory, real sandboxed tools, seven chat channels, and a human approval gate — running on your own hardware, auditable end to end.corlinman 是一个自托管智能体平台：一体成形的程序，给语言模型装上持久记忆、真实的沙箱工具、七个聊天渠道和人工审批门 —— 跑在你自己的硬件上，端到端可审计。

The loop回路 回路The loop

Every request, from any channel, travels the same path:来自任何渠道的每一个请求，都走同一条路径：

Messages land from QQ, Telegram, Discord, Slack, Feishu, WeChat 公众号 or the built-in web chat. The agent recalls context from hybrid retrieval, reasons with whichever model you bound, fires tools inside a sandboxed plugin runtime, and anything irreversible waits in an approval queue until you say yes.消息从 QQ、Telegram、Discord、Slack、飞书、微信公众号或内置网页聊天进来。智能体先用混合检索召回上下文，再用你绑定的模型推理，工具在沙箱化的插件运行时中执行 —— 任何不可逆的操作都会进入审批队列，等你点头才放行。

The pillars支柱 支柱The pillars

• Durable memory — per-session history in SQLite plus a knowledge store with FTS5 keyword search, vector index, decay & consolidation.持久记忆 —— SQLite 里的会话历史，加上带 FTS5 关键词检索、向量索引、衰减与固化机制的知识库。 → memory & rag记忆与检索
• Real tools — sync / async / service plugins in any language, optional Docker sandbox, a skills library, a marketplace.真实工具 —— 任意语言编写的 sync / async / service 三类插件、可选 Docker 沙箱、技能库、扩展市场。 → tools & skills工具与技能
• Seven channels — one agent, every room it's invited to.七个渠道 —— 同一个智能体，出现在所有邀请它的房间里。 → channels渠道
• Human-in-the-loop — per-tool approval rules: auto, prompt, or deny.人在回路 —— 按工具粒度的审批规则：auto、prompt、deny。 → approvals审批
• Operations plane — a Spatial Glass admin console with live logs, RAG debugging and a theme studio.运维后台 —— Spatial Glass 管理台：实时日志、RAG 调试、主题工作室。 → admin ui后台
• One binary — install in sixty seconds, upgrade in place, China mirrors built in.一体成形 —— 六十秒装好，原地升级，内置国内镜像加速。 → install安装

At a glance速览 速览At a glance

sources: README.md · docs/architecture.md

start / install

Install in sixty seconds.六十秒装好。安装

One script handles preflight checks, Docker or native mode, the QQ sidecar, China mirrors, and a health gate that won't report success until the gateway actually answers.一个脚本搞定一切：预检、Docker 或原生模式、QQ 边车、国内镜像，外加一个健康门 —— 网关真正应答之前绝不报成功。

Quickstart一键安装 一键安装Quickstart

curl -fsSL https://raw.githubusercontent.com/sweetcornna/corlinman/main/deploy/install.sh | bash

Default is Docker mode. For native (systemd) mode with a version pin:默认是 Docker 模式。原生（systemd）模式并锁定版本：

curl -fsSL https://raw.githubusercontent.com/sweetcornna/corlinman/main/deploy/install.sh | \
  bash -s -- --mode native --version v1.19.1

What preflight checks预检查什么 预检Preflight

• Disk ≥ 5 GB, RAM ≥ 1 GB磁盘 ≥ 5 GB，内存 ≥ 1 GB
• Port 6005 free (override with CORLINMAN_PORT) — fails fast with the holding PID端口 6005 空闲（用 CORLINMAN_PORT 覆盖）—— 被占用时直接报出占用进程的 PID
• Docker Engine 24+ with compose v2 (docker mode only)Docker Engine 24+ 且带 compose v2（仅 docker 模式）
• Health gate: polls GET /health until HTTP 200 (timeout CORLINMAN_HEALTH_TIMEOUT, default 60 s)健康门：轮询 GET /health 直到 HTTP 200（超时 CORLINMAN_HEALTH_TIMEOUT，默认 60 秒）

Docker vs native两种模式 两种模式Docker vs native

QQ sidecarQQ 边车 QQ 边车QQ sidecar

NapCat (OneBot v11) is bundled by default in both modes — docker layers docker-compose.qq.yml, native provisions an AppImage + systemd unit. Opt out with --without-qq. Pin the version with NAPCAT_VERSION (default v4.18.4).两种模式都默认捆绑 NapCat（OneBot v11）—— docker 叠加 docker-compose.qq.yml，原生模式安装 AppImage + systemd 单元。不需要就加 --without-qq。用 NAPCAT_VERSION 锁版本（默认 v4.18.4）。

China mirrors国内加速 国内加速China mirrors

Mirror mode auto-enables when pypi.org TTFB exceeds 3 seconds, or force it with --china. Override individual mirrors with CN_PIP_INDEX, CN_GH_PROXY, CN_DOCKER_MIRROR.当 pypi.org 首字节超过 3 秒时镜像模式自动开启，也可以用 --china 强制。单项镜像可用 CN_PIP_INDEX、CN_GH_PROXY、CN_DOCKER_MIRROR 覆盖。

Upgrade升级 升级Upgrade

bash deploy/install.sh --upgrade
# pin a release · 锁定版本:
bash deploy/install.sh --upgrade --version v1.19.1

Upgrades never touch $CORLINMAN_DATA_DIR. For production, pin the compose image tag: CORLINMAN_TAG=v1.19.1.升级永远不会动 $CORLINMAN_DATA_DIR。生产环境建议锁定镜像 tag：CORLINMAN_TAG=v1.19.1。

sources: deploy/install.sh · README.md

start / first run

First run, first five minutes.首次启动的五分钟。首次启动

Log in, rotate the seed password, connect a model — through the web wizard or entirely from the terminal.登录、换掉种子密码、接上模型 —— 走网页向导，或者全程在终端里完成。

Log in登录 登录Log in

Open http://localhost:6005/login (or your server's IP). First boot seeds admin / root — the UI immediately redirects to /account/security and a red banner persists until you change the password. corlinman doctor also warns while the seed credential is alive.打开 http://localhost:6005/login（或你服务器的 IP）。首次启动会种入 admin / root —— UI 会立刻重定向到 /account/security，红色横幅会一直挂着，直到你改掉密码。种子凭据还在时 corlinman doctor 也会一直告警。

Connect a model接入模型 接入模型Connect a model

Path A — the wizard. Visit /onboard: a 4-step flow (account → connect LLM → pick models → confirm) that writes config.toml atomically.路径 A —— 向导。访问 /onboard：四步流程（账户 → 接入 LLM → 选模型 → 确认），原子化写入 config.toml。

Path B — no key yet? At step 2, click Skip — use mock provider. It writes [providers.mock] enabled = true and echoes prompts back so you can explore every screen end-to-end.路径 B —— 还没有 API key？在第 2 步点 Skip — use mock provider。它会写入 [providers.mock] enabled = true，把你的输入原样回显，让你先把每个界面端到端逛一遍。

Headless servers. corlinman init is the CLI equivalent: walks the password change, provider key paste and model alias write, then restarts the gateway.无浏览器的服务器。corlinman init 是 CLI 版向导：依次完成改密码、粘贴供应商 key、写模型别名，最后重启网关。

Verify with doctor用 doctor 体检 体检Doctor

corlinman doctor          # human output · 人类可读
corlinman doctor --json   # CI-friendly · 给 CI 用

Nine local checks: data-dir writability, config parseability, Python 3.12+, required packages, config loader, provider registry, a P1+P2 boot simulation, must_change_password, and port_bindable. Results are ok or warn — never a hard fail.九项本地检查：数据目录可写、配置可解析、Python 3.12+、依赖包、配置加载器、供应商注册表、P1+P2 启动模拟、must_change_password、port_bindable。结果只有 ok 或 warn —— 永远不会硬性失败。

Profiles多实例 多实例Profiles

Each profile is a self-contained agent: its own persona (SOUL.md), distilled memory (MEMORY.md), learned user facts (USER.md), session history (state.db) and skill library. The protected default profile lives at ~/.corlinman/profiles/default/. Use one per workspace — research bot, coding pair, weekend project.每个 profile 都是一个自洽的智能体：自己的人格（SOUL.md）、蒸馏记忆（MEMORY.md）、学到的用户事实（USER.md）、会话历史（state.db）和技能库。受保护的 default profile 在 ~/.corlinman/profiles/default/。一个工作空间一个 profile —— 研究助手、结对编程、周末项目，各管各的。

Share live status cards分享实时状态卡 状态卡Status cards

Set [server] public_url (e.g. https://bot.example.com) and every channel reply can append a link to GET /status/{token} — a public, signed, real-time page streaming the agent's work (tokens, tool calls, timings). Toggle with [channels] status_url_in_replies (default on). If public_url is unset, the origin is learned from the first request through allowed_public_origins + trusted_proxies and persisted to <data_dir>/public_origin.配置 [server] public_url（如 https://bot.example.com）后，每条渠道回复都能附上一个 GET /status/{token} 链接 —— 一个公开的、带签名的实时页面，直播智能体的工作（token 流、工具调用、耗时）。开关是 [channels] status_url_in_replies（默认开）。如果没设 public_url，会通过 allowed_public_origins + trusted_proxies 从首个请求学习来源，并持久化到 <data_dir>/public_origin。

sources: docs/quickstart.md · docs/profiles.md · docs/config.example.toml

run / channels

One agent, seven rooms.一个智能体，七个房间。渠道

Every channel feeds the same loop with the same memory, tools and approvals. Configure each under [channels.*] in config.toml, or from /admin/channels — status lights, connection reset, inline keyword editors, recent transcripts.每个渠道都接入同一条回路，共享同一份记忆、工具和审批。在 config.toml 的 [channels.*] 下配置，或直接用 /admin/channels —— 状态灯、重连按钮、内联关键词编辑器、近期消息记录。

QQ — NapCat / OneBot v11 QQ

Bundled by default (see install). A forward-WebSocket bridge with image/audio multimodal, per-group keyword filters, "正在输入…" indicator, heartbeat watcher, and a durable inbox that leaves a breadcrumb if the gateway crashes mid-reply.默认捆绑（见安装）。正向 WebSocket 桥接，支持图片/语音多模态、按群关键词过滤、「正在输入…」指示、心跳监视，以及一个持久化收件箱 —— 网关在回复中途崩溃也会留下断点痕迹。

[channels.qq]
enabled  = true
ws_url   = "ws://napcat:3001"
self_ids = [123456789]
rate_limit = { group_per_min = 20, sender_per_min = 5 }

Telegram 电报

Long-poll bot adapter (webhook optional with TELEGRAM_WEBHOOK_SECRET). Real-time typing indicator plus a mutable spinner that edits one placeholder message in place as the turn progresses: 🧠 思考中… → 🔧 调用工具 → 📎 已发送文件 → ✍️ 生成回复中… → final reply. File replies (HTML/PDF/images/voice) via the send_attachment builtin.长轮询 bot 适配器（webhook 可选，配 TELEGRAM_WEBHOOK_SECRET）。实时「正在输入」指示，外加一个原地编辑的状态条：同一条占位消息随回合推进被改写 —— 🧠 思考中… → 🔧 调用工具 → 📎 已发送文件 → ✍️ 生成回复中… → 最终回复。文件回复（HTML/PDF/图片/语音）走内置的 send_attachment 工具。

[channels.telegram]
enabled   = true
bot_token = { env = "TELEGRAM_BOT_TOKEN" }   # from @BotFather
allowed_chat_ids = []          # empty = allow all · 留空 = 全部放行
require_mention_in_groups = false
rate_limit = { chat_per_min = 20, sender_per_min = 5 }

Discord · Slack · Feishu 三兄弟

Configured under [channels.discord] / [channels.slack] / [channels.feishu] with the same routing, rate-limit and chat-service plumbing. All three share the Telegram-style mutable-spinner status core, and since v1.19 outbound text is capability-aware: markdown renders natively on Discord/Slack/Feishu instead of being flattened.分别在 [channels.discord] / [channels.slack] / [channels.feishu] 下配置，复用同一套路由、限流和聊天服务管线。三者都共享 Telegram 式的原地编辑状态条；并且从 v1.19 起出站文本按渠道能力感知：Discord/Slack/飞书原生渲染 markdown，不再被拍平。

WeChat 公众号 & QQ official bot 公众号

Both shipped in v1.1.0 and are managed from /admin/channels. See the channel pages in the admin console for credential entry and webhook URLs.两者都在 v1.1.0 上线，统一从 /admin/channels 管理。凭据填写和 webhook 地址见后台对应渠道页。

Web chat网页聊天 网页聊天Web chat

/admin/chat is a first-class channel driven by the same loop: token streaming, collapsible reasoning blocks, tool-call cards, nested sub-agent cards, inline approval prompts, artifact side-panel with sandboxed preview, branch/edit/regenerate, token + cost meter, in-conversation search, and session resume from /admin/sessions./admin/chat 是由同一条回路驱动的一等渠道：token 流式输出、可折叠的推理块、工具调用卡片、嵌套子智能体卡片、内联审批提示、带沙箱预览的 artifact 侧栏、分支/编辑/重新生成、token 与费用计量、会话内搜索，还能从 /admin/sessions 续接任意会话。

Scheduler — the eighth channel定时任务 —— 第八个渠道 定时任务Scheduler

Cron jobs dispatch agent turns on a schedule; sessions are keyed scheduler:<name> so approval rules can whitelist them.Cron 任务按计划触发智能体回合；会话以 scheduler:<名字> 为键，审批规则可以据此放行白名单。

[[scheduler.jobs]]
name     = "daily-brief"
cron     = "0 0 8 * * * *"        # sec min hour day month weekday year
timezone = "Asia/Shanghai"
action   = { type = "run_agent", prompt = "生成今日简报" }

Actions: run_agent, run_tool, or subprocess. The admin page shows a live next-trigger countdown, manual trigger button and execution history.动作类型：run_agent、run_tool、subprocess。后台页面有下次触发的实时倒计时、手动触发按钮和执行历史。

sources: docs/config.example.toml · deploy/.env.template · README.md

run / providers & models

Any model you trust.用你信任的任何模型。模型与供应商

Providers are free-form named entries in [providers.*]; a kind field picks the wire shape. Aliases give models friendly names; agents and even single requests can pin their own model.供应商是 [providers.*] 下自由命名的条目，kind 字段决定协议形态。别名给模型起好记的名字；每个 agent、甚至单个请求都能钉住自己的模型。

Production providers可用供应商 可用Production

Mistral, Cohere, Together, Groq, Replicate, Bedrock and Azure kinds are declared but raise NotImplementedError today — route them through an openai_compatible proxy instead. Legacy kind = "newapi" entries are silently routed through the openai_compatible adapter.Mistral、Cohere、Together、Groq、Replicate、Bedrock、Azure 这些 kind 已声明但目前会抛 NotImplementedError —— 请改走 openai_compatible 代理。旧的 kind = "newapi" 条目会被静默路由到 openai_compatible 适配器。

Configuring a provider配置一个供应商 配置Config

[providers.anthropic]
kind    = "anthropic"
api_key = { env = "ANTHROPIC_API_KEY" }   # or { value = "sk-..." } (redacted by `config show`)
enabled = true

# local vLLM / Ollama / SiliconFlow / any OpenAI-shaped endpoint
# 本地 vLLM / Ollama / 硅基流动 / 任何 OpenAI 形状的端点
[providers.local]
kind     = "openai_compatible"
api_key  = { env = "LOCAL_API_KEY" }
base_url = "http://localhost:8000/v1"
enabled  = true

Model aliases模型别名 别名Aliases

[models]
default = "smart"

[models.aliases]
smart = "claude-opus-4-7"          # shorthand — provider inferred · 简写，自动推断供应商
cheap = "gpt-4o-mini"

[models.aliases.gpt4o-via-router]  # full form — pin provider + params · 完整形式
model    = "openai/gpt-4o"
provider = "openrouter"
params   = { temperature = 0.3 }

Per-agent binding按 agent 绑定 按 agent 绑定Per-agent

Agent cards (agents/*.md) carry a model frontmatter field that pins that persona to a model or alias; a single request can also override via its model + provider_hint. Manage everything visually at /admin/models.Agent 卡片（agents/*.md）的 frontmatter 里有 model 字段，把该人格钉到某个模型或别名上；单个请求也能用 model + provider_hint 覆盖。所有这些都可以在 /admin/models 可视化管理。

Embeddings向量嵌入 向量Embeddings

[embedding]
provider  = "openai"               # must match a [providers.*] key · 必须对应一个供应商条目
model     = "text-embedding-3-small"
dimension = 1536
enabled   = true

# CN-resident alternative · 国内可用替代:
# provider = "siliconflow"  model = "BAAI/bge-large-zh-v1.5"  dimension = 1024

Omit the section (or enabled = false) and retrieval falls back to BM25-only. Anthropic has no embedding endpoint — use an OpenAI-kind provider here.不写这一节（或 enabled = false）时检索退化为纯 BM25。Anthropic 没有 embedding 端点 —— 这里要用 OpenAI 形状的供应商。

sources: docs/config.example.toml · docs/providers.md

run / memory & rag

Context that survives restarts.重启也不丢的上下文。记忆与检索

Two memory systems work together: per-session conversation history, and a knowledge store with hybrid retrieval that decays, consolidates, and can be debugged visually.两套记忆系统协同工作：按会话的对话历史，和一个带混合检索的知识库 —— 会衰减、会固化，还能可视化调试。

Conversation memory会话记忆 会话Sessions

Append-only message history in SQLite (sessions.sqlite), keyed by channel binding or a client-supplied session_key, trimmed to a configurable cap. Long sessions can be compacted with /compact (summary-based context compaction).SQLite（sessions.sqlite）里只追加的消息历史，按渠道绑定或客户端传入的 session_key 索引，按可配置上限裁剪。长会话可以用 /compact 做基于摘要的上下文压缩。

Knowledge memory知识记忆 知识库Knowledge

• Keyword — SQLite FTS5 (BM25), available today, debuggable at /admin/rag.关键词 —— SQLite FTS5（BM25），现在就可用，可在 /admin/rag 调试。
• Vector — HNSW index (vector/index.usearch) + chunk store (vector/chunks.sqlite), fused with BM25 via Reciprocal Rank Fusion; cross-encoder rerank (bge-reranker-v2-m3) on the roadmap.向量 —— HNSW 索引（vector/index.usearch）+ 分块库（vector/chunks.sqlite），与 BM25 做 RRF 融合；cross-encoder 重排（bge-reranker-v2-m3）在路线图上。

[rag]
top_k       = 8
bm25_weight = 1.0
hnsw_weight = 1.0
rrf_k       = 60
epa_enabled = true     # Tag-Memo EPA boost · 标签备忘加权

Decay & consolidation衰减与固化 衰减与固化Decay

Chunk scores decay on a half-life ([memory.decay]: half_life_hours, floor_score, recall_boost — recalling a chunk resets its clock). A periodic job promotes chunks above promotion_threshold into an immune consolidated namespace ([memory.consolidation]). Old context fades; load-bearing facts harden.分块得分按半衰期衰减（[memory.decay]：half_life_hours、floor_score、recall_boost —— 一旦被召回就重置时钟）。周期任务把得分超过 promotion_threshold 的分块晋升到免疫衰减的 consolidated 命名空间（[memory.consolidation]）。旧的上下文淡去，承重的事实硬化。

Tag Memo 标签备忘

The corlinman_tagmemo package fits an EPA basis over tags and feeds a chunk_epa cache that boosts RRF fusion — tune with epa_base_tag_boost and epa_boost_range under [rag].corlinman_tagmemo 包在标签上拟合 EPA 基底，生成 chunk_epa 缓存来增强 RRF 融合 —— 用 [rag] 下的 epa_base_tag_boost 和 epa_boost_range 调节。

Debugging retrieval调试检索 调试Debug

/admin/rag shows stats cards (chunks indexed, storage size, last update), a debug-query box with per-chunk score bars, tag filters, per-chunk metadata (source path, timestamp), and a confirm-gated FTS5 rebuild trigger./admin/rag 提供统计卡（已索引分块数、存储大小、最近更新）、带逐块评分条的调试查询框、标签过滤、逐块元数据（来源路径、时间戳），以及需二次确认的 FTS5 重建按钮。

sources: docs/architecture.md · docs/config.example.toml

run / tools & skills

Hands, not just words.不只会说，还会动手。工具与技能

Plugins give the agent executable tools in any language; skills teach it procedures in Markdown; the marketplace hot-plugs both. Subagents fan work out under hard caps.插件给智能体提供任意语言写的可执行工具；技能用 Markdown 教它流程方法；市场让两者都能热插拔。子智能体在硬性上限内并行分摊工作。

Plugin runtime插件运行时 插件Plugins

Any language that can speak the stdio/gRPC JSON contract — Python, Node, Go, Rust, bash. Test-invoke any tool from /admin/plugins with a schema-driven form.任何能说 stdio/gRPC JSON 契约的语言都行 —— Python、Node、Go、Rust、bash。在 /admin/plugins 用按 schema 生成的表单试调任何工具。

The sandbox沙箱 沙箱Sandbox

Optional Docker sandboxing wraps plugin processes with memory/CPU limits, a read-only root filesystem, network isolation and capability drops:可选的 Docker 沙箱把插件进程包起来：内存/CPU 限额、只读根文件系统、网络隔离、能力裁剪：

docker compose -f docker/compose/docker-compose.yml \
  -f docker/compose/docker-compose.sandbox.yml up -d
# or at install time · 或在安装时:
install.sh --enable-docker-sandbox      # CORLINMAN_ENABLE_DOCKER_SANDBOX=1

Untrusted plugins can additionally demand human approval before every call — see approvals.不受信任的插件还可以要求每次调用前都人工审批 —— 见审批。

Skills技能 技能Skills

Procedural knowledge as SKILL.md bundles (frontmatter + Markdown), stored per-profile under profiles/{name}/skills/ and indexed at startup ([skills] autoload = true). ~17 skills ship bundled. /admin/skills has an Installed tab (bundled rows read-only) and a Browse Hub tab that proxies ClawHub for one-click community installs with SSE progress.以 SKILL.md 包（frontmatter + Markdown）承载的流程性知识，按 profile 存放在 profiles/{名字}/skills/，启动时建立索引（[skills] autoload = true）。出厂自带约 17 个技能。/admin/skills 有「已安装」标签页（自带技能只读）和「逛 Hub」标签页 —— 代理 ClawHub，一键安装社区技能，SSE 实时进度。

Marketplace扩展市场 市场Marketplace

Three installable kinds — skills, MCP servers, plugins — from a GitHub-backed registry:三种可安装的扩展 —— 技能、MCP 服务器、插件 —— 来自一个 GitHub 托管的注册表：

[marketplace]
registry_repo  = "sweetcornna/corlinman-marketplace"
registry_ref   = "main"
default_source = "github"          # or "clawhub"

[marketplace.github_proxy]         # China acceleration · 国内加速
mode   = "auto"                    # off / auto / on
preset = "ghproxy"                 # ghproxy / jsdelivr / mirror / custom

Skills auto-activate within the 30-second registry refresh; MCP servers and plugins install staged and stay inert until you explicitly enable them.技能在 30 秒一轮的注册表刷新内自动激活；MCP 服务器和插件则是暂存式安装 —— 装好后保持惰性，直到你显式启用。

Subagents子智能体 子智能体Subagents

The agent can fan out work with subagent.spawn / spawn_many / spawn_inline, governed by supervisor caps:智能体可以用 subagent.spawn / spawn_many / spawn_inline 把工作扇出，由监管上限约束：

[subagent]
max_concurrent_per_parent = 10
max_concurrent_per_tenant = 15
max_depth                 = 1
max_wall_seconds_ceiling  = 300

Watch live dispatches at /admin/subagents. Agent cards (agents/*.md) define reusable personas with their own model bindings.在 /admin/subagents 看实时调度。Agent 卡片（agents/*.md）定义可复用的人格，各自绑定模型。

Document generation文档生成 文档生成Doc-gen

corlinman-md2pdf converts Markdown to clean, CJK-correct PDFs — used by the agent to send real files back through channels (e.g. Telegram's send_attachment).corlinman-md2pdf 把 Markdown 转成干净、中文排版正确的 PDF —— 智能体用它通过渠道发回真正的文件（比如 Telegram 的 send_attachment）。

sources: docs/plugin-authoring.md · docs/marketplace.md · docs/config.example.toml

run / approvals

Govern, don't hope.治理，而不是祈祷。人在回路

Every tool call the model emits is matched against approval rules before the plugin runtime ever sees it. Irreversible actions wait for a human.模型发出的每一个工具调用，都会先过一遍审批规则，再交给插件运行时。不可逆的操作要等人点头。

Rules规则 规则Rules

[[approvals.rules]]
plugin = "file-ops"
tool   = "file-ops.write"     # omit to cover every tool · 省略则覆盖该插件全部工具
mode   = "prompt"             # auto / prompt / deny

[[approvals.rules]]
plugin = "shell"
mode   = "prompt"
allow_session_keys = ["scheduler:daily-brief", "scheduler:git-sync"]

Matching匹配 匹配Matching

Most-specific-first: a plugin + tool rule beats a plugin-wide rule; with no matching rule the call passes (default-auto). allow_session_keys lets trusted sessions — like whitelisted scheduler jobs — bypass a prompt rule.最具体者优先：plugin + tool 规则压过整个插件的规则；没有命中任何规则时放行（默认 auto）。allow_session_keys 让受信会话 —— 比如白名单里的定时任务 —— 绕过 prompt 规则。

Where you approve在哪里批 在哪批Where

/admin/approvals streams pending calls live (SSE) with a history tab. In the web chat, approval prompts also appear inline in the conversation — Approve once, Always for this session, or Deny without leaving the thread./admin/approvals 实时（SSE）展示待审调用，附历史标签页。在网页聊天里，审批提示还会内联出现在对话中 —— 批一次、本会话始终允许、或拒绝，都不用离开当前对话。

sources: docs/config.example.toml · README.md

operate / console & cli

The terminal is a channel too.终端也是一个渠道。命令行

A full interactive console with the entire brain — memory, tools, subagents, persona — or a thin client attached to a running gateway.一个带完整大脑的交互式控制台 —— 记忆、工具、子智能体、人格全都在 —— 也可以作为瘦客户端挂到正在运行的网关上。

corlinman console 交互REPL

corlinman console [PROMPT] [--attach URL] [--model M] [--agent CARD]
                  [--session KEY] [--data-dir DIR] [-p/--print]

• Embedded mode (default) — boots the full agent servicer on a private per-process socket: builtin tools, subagent spawning, memory, persona all apply.内嵌模式（默认）—— 在进程私有 socket 上启动完整的 agent 服务：内置工具、子智能体、记忆、人格全部生效。
• Attach mode (--attach http://host:6005) — OpenAI-compatible SSE client to a running gateway; session state rides the X-Session-Key header.挂载模式（--attach http://host:6005）—— 以 OpenAI 兼容 SSE 客户端连到运行中的网关；会话状态走 X-Session-Key 头。

The REPL keeps a fixed bottom input, queues what you type while a turn is running, and Ctrl+C interrupts the turn instead of killing the process. Tool progress renders at off | new | all | verbose.REPL 底部输入框固定，回合进行中输入的内容会排队，Ctrl+C 中断当前回合而不是杀掉进程。工具进度有 off | new | all | verbose 四档。

Slash commands斜杠命令 斜杠命令Slash

/help /new /reset /model /sessions /title /usage
/status /resume /compact /verbose /clear /persona

/model opens a two-stage picker; /compact does summary-based context compaction; /resume continues a past session. The same command set works in the web chat composer./model 打开两段式选择器；/compact 做基于摘要的上下文压缩；/resume 续接历史会话。同一套命令在网页聊天的输入框里同样可用。

One-shot & pipes一次性与管道 管道Pipes

corlinman console -p "summarize deploy logs from this week"
# prompt in → final text on stdout; pipe-friendly · 输入进，结果出，可接管道

Smart routing can send trivially simple turns to a cheaper model: [console] small_fast_model plus opt-in [console.auto_route].智能路由可以把特别简单的回合送给更便宜的模型：[console] small_fast_model 加上自愿开启的 [console.auto_route]。

Setup & health from the terminal终端里完成配置与体检 无界面Headless

corlinman init       # headless onboarding · 无界面初始化：密码、key、模型别名
corlinman doctor     # nine local checks · 九项本地检查，--json 给 CI

sources: docs/PLAN_CLI_CONSOLE.md · README.md

operate / admin ui

The operations plane.运维平面。后台

A Spatial Glass console — Apple-style liquid-glass optics, day & night themes, a ⌘K command palette, and SSE-driven pages that update as the agent thinks.一个 Spatial Glass 管理台 —— 苹果式液态玻璃光学、日夜双主题、⌘K 命令面板，所有页面由 SSE 驱动，智能体一边思考页面一边更新。

Core pages十大核心页 十大核心页Core pages

A Developer-Settings toggle reveals the extended set: Credentials, Config (Monaco TOML editor with schema hints), Logs (virtualized SSE stream with level/subsystem filters), System (version check + one-click upgrade with progress bar), Sessions (turn-timeline replay), Profiles, Persona, Subagents, Marketplace, Evolution, Hooks and more.打开开发者设置后还有扩展页面：凭据、配置（Monaco TOML 编辑器，带 schema 提示）、日志（虚拟化 SSE 流，按级别/子系统过滤）、系统（版本检查 + 带进度条的一键升级）、会话（回合时间线回放）、Profiles、人格、子智能体、市场、演化、Hooks 等等。

Theme Studio 主题工作室

Since v1.19.0 you can recolour the whole console — accent hue, glass opacity, design tokens — and changes apply instantly across every page. Day and night themes both pass WCAG AA contrast; the UI ships bilingual (zh-CN / en).从 v1.19.0 起可以整体重新调色 —— 强调色相、玻璃不透明度、设计 token —— 改动即时应用到每个页面。日夜主题都通过 WCAG AA 对比度；UI 本身就是双语的（zh-CN / en）。

Config hot-reload配置热加载 热加载Hot-reload

config.toml is watched; edits apply atomically via POST /admin/config after validation. Providers, models, approvals, scheduler, RAG, marketplace, logging and memory settings apply live; bind, port and channel enablement return requires_restart: true.config.toml 处于监视之下；编辑经校验后通过 POST /admin/config 原子化生效。供应商、模型、审批、定时任务、RAG、市场、日志、记忆这些都即时生效；bind、port 和渠道启停会返回 requires_restart: true。

sources: README.md · docs/architecture.md

operate / faq

When something looks wrong.不对劲的时候看这里。疑难排解

The short list of real-world fixes, straight from the runbook.来自运维手册的真实修复清单，短而管用。

I forgot the admin password忘了管理员密码 忘记密码Password

Stop the gateway, delete the [admin] block from config.toml, restart. The seed kicks back in — you're on admin / root again with forced rotation.停掉网关，删掉 config.toml 里的 [admin] 块，重启。种子凭据重新生效 —— 又回到 admin / root，并强制改密。

/onboard says "already onboarded"/onboard 说「已经初始化过了」 向导跳过Onboard

The wizard short-circuits once [admin] plus at least one enabled [providers.*] block exists. To re-run: stop the gateway, back up the config, strip the [providers.*] blocks (or the whole file — it re-seeds), restart.一旦存在 [admin] 加至少一个启用的 [providers.*] 块，向导就会短路。想重跑：停网关、备份配置、删掉 [providers.*] 块（或整个文件 —— 会重新播种），再重启。

/login returns 503/login 返回 503 登录 503503

A brief 503 means the admin state isn't wired yet — the gateway is still warming up; wait two seconds and retry. A persistent 503 with session_store_missing is a data-dir permissions problem: chown <data_dir>/admin-sessions.sqlite back to the process owner.短暂的 503 表示管理状态还没接好 —— 网关还在预热，等两秒重试。持续 503 且带 session_store_missing 是数据目录权限问题：把 <data_dir>/admin-sessions.sqlite chown 回进程属主。

Where are the logs?日志在哪？ 日志在哪Logs

# docker
docker logs corlinman --tail 50
# native · 原生
journalctl -u corlinman-gateway -f

With [logging] file_rolling = true, daily files land in <data_dir>/logs/corlinman.log.YYYY-MM-DD. Format defaults to structured JSON; level is configurable (trace…error). The same stream feeds /admin/logs.开了 [logging] file_rolling = true 时，按天滚动的文件在 <data_dir>/logs/corlinman.log.YYYY-MM-DD。默认结构化 JSON 格式；级别可配（trace…error）。同一条流也喂给 /admin/logs。

Preflight failed预检失败 预检失败Preflight

• disk < 5 GB / RAM < 1 GB — hard requirements; free space or resize.磁盘 < 5 GB / 内存 < 1 GB —— 硬性要求；清空间或扩容。
• port 6005 held — the error names the PID; stop it or set CORLINMAN_PORT.端口 6005 被占 —— 报错会给出 PID；停掉它，或改 CORLINMAN_PORT。
• docker missing / too old — needs Engine 24+; or switch to --mode native.docker 缺失 / 太旧 —— 需要 Engine 24+；或者改用 --mode native。

My systemd edits disappeared after reinstall重装后 systemd 改动没了 单元被覆盖Systemd

Running install.sh without --upgrade rewrites the unit and compose override. Always upgrade with --upgrade, and keep customizations in a drop-in: /etc/systemd/system/corlinman-gateway.service.d/override.conf. Since v1.10.0 the gateway runs as the non-privileged corlinman user.不带 --upgrade 跑 install.sh 会重写单元和 compose 覆盖文件。升级永远走 --upgrade，定制放进 drop-in：/etc/systemd/system/corlinman-gateway.service.d/override.conf。从 v1.10.0 起网关以非特权 corlinman 用户运行。

Will upgrading eat my data?升级会吃掉数据吗？ 升级丢数据吗Data safety

No. bash deploy/install.sh --upgrade never touches $CORLINMAN_DATA_DIR — docker pulls/rebuilds and restarts; native re-syncs the venv (uv sync --frozen) and restarts the unit. Pin releases with --version vX.Y.Z / CORLINMAN_TAG.不会。bash deploy/install.sh --upgrade 永远不碰 $CORLINMAN_DATA_DIR —— docker 拉新镜像/重建后重启；原生模式重新同步 venv（uv sync --frozen）后重启单元。用 --version vX.Y.Z / CORLINMAN_TAG 锁定版本。

Which config edits need a restart?哪些配置要重启？ 哪些要重启Restart

Only bind, port and channel enablement. Everything else — providers, models, approvals, scheduler, RAG, marketplace, logging, memory — hot-reloads atomically after validation.只有 bind、port 和渠道启停。其余一切 —— 供应商、模型、审批、定时任务、RAG、市场、日志、记忆 —— 校验通过后原子化热加载。

sources: docs/quickstart.md · README.md