参考
配置与环境变量
端口、状态文件、Node 路径，各类密钥的来源，以及联网搜索服务和记忆方式的设置。
环境变量
| 变量 | 作用 |
|---|---|
RNA_AGENT_PORT | 守护进程端口，默认 4317，取值 1024 到 65535。CLI 用它选择要连接的守护进程 |
RNA_AGENT_STATE | 状态文件位置。同一状态文件不允许多个守护进程同时写入 |
RNA_AGENT_NODE | 启动器使用的 Node 可执行文件绝对路径 |
RNA_MODEL_API_KEY 等 | 提供商配置中 apiKeyEnv 引用的变量，必须对守护进程可见 |
TYPESAFE_API_KEY | 没有在设置里保存 JEV 密钥时使用的密钥 |
TYPESAFE_ENDPOINT | JEV 服务地址，只能用环境变量设置，界面里只读 |
旧名称 PI_FORGE_PORT、PI_FORGE_STATE 仍然兼容，新名称优先。桌面版另有 RNA_DESKTOP_DATA（数据目录）。守护进程启动的终端会清掉 RNA_、TYPESAFE_、OPENVIKING_ 开头和 *API_KEY 的变量，密钥不会进入你在面板里打开的 shell。
数据位置
| 场景 | 位置 |
|---|---|
| 桌面版私有服务 | ~/Library/Application Support/Rna Agent |
| 桌面版连接信息 | 同目录下的 desktop-connection.json |
| 源码运行 | 仓库内 prototypes/control-center/.state/（已被 gitignore） |
| SDK 示例 | .rna-sdk-state/ 或示例自带的状态目录 |
状态文件 state.json 旁有几个附属文件：<state>.secrets（密钥，0600）、<state>.subscriptions（订阅登录，0600）、<state>.rna/（会话日志；用本地记忆时还有 memory/embedded.sqlite）。它们都随恢复点备份。
密钥来源
模型、联网搜索和记忆服务的密钥有两种来源：
- 在设置中保存，写入本机凭据文件（
state.json旁的 secrets，权限0600）； - 在设置中指定一个环境变量名，运行时读取。
JEV 密钥不同：在 设置 → 高级 → 判断 的“JEV 独立 API Key”里保存，或者用固定的环境变量 TYPESAFE_API_KEY，没有指定变量名的字段。
| 服务 | 设置位置 |
|---|---|
| 模型提供商 | 设置 → 模型 |
| ChatGPT 订阅登录 | 设置 → 模型 → OpenAI · ChatGPT 订阅（浏览器或设备码登录，请求时自动刷新） |
| JEV 判断 | 设置 → 高级 → 判断 |
| 联网搜索与抓取 | 设置 → 高级 → 网页工具 |
| 项目记忆（OpenViking） | 设置 → 高级 → 记忆 → 高级连接设置 |
设置接口只报告某个密钥是否已配置和来源，从不回显。
联网搜索服务
web_search 和 web_fetch 两个工具通过你选的搜索服务运行，在 设置 → 高级 → 网页工具 里开启（默认关闭），对所有项目和会话生效。不论选哪个服务，模型看到的是同样的两个工具。
| 服务 | 密钥 | 读取网页 |
|---|---|---|
| FastCRW（默认） | 可选，也可使用自建的兼容服务 | 经服务 |
| Firecrawl | 可选，不填也能用，按 IP 限制次数 | 经服务 |
| Tavily | 需要 | 经服务 |
| Brave Search | 需要 | 本机直接读取 |
| 智谱 Web Search | 需要（智谱 API 密钥） | 经服务 |
| 博查 Bocha | 需要 | 本机直接读取 |
- 只提供搜索的服务（Brave、博查）读取网页时由本机直接访问目标网站：只访问公开地址，连接固定在检查过的地址上，每一次跳转都重新检查，也不发送密钥；本机和内网地址不会被读取，靠脚本渲染的页面可能读不到正文。
- 每个服务有自己的地址和密钥。换服务时改用新服务的官方地址，原来保存的密钥和环境变量名会被清除，不会发给新的服务；需要密钥的服务没有密钥时不会被请求。
- “保存并检查连接”会各发一次搜索和读取请求。请求超时可设 1 到 120 秒。
- 命令行：
./rna web-config --enabled true --provider firecrawl、./rna web-test，密钥不接受命令行明文。 - Firecrawl（无密钥）和本机直接读取做过真实验证；Tavily、Brave、智谱和博查按各自文档实现，只用本地模拟服务测试过。
记忆方式
在 设置 → 高级 → 记忆 里选“OpenViking 语义记忆”或“本地记忆（内置）”，配置项 memory.backend 取 openviking 或 embedded，命令行为 ./rna memory-config --backend embedded。两种方式各自保存自己的记忆，互不迁移。详见 记忆。
网络
- 守护进程默认只监听
127.0.0.1，检查 Host 和 Origin，写入请求要求application/json。 - 远端模型地址必须是 HTTPS，本机地址可以用 HTTP。
- 探测模型目录时不跟随重定向，错误响应不回显上游原文。