使用指南

按顺序做完管理员部分，企业就能用起来；把员工部分的链接发给员工即可。

购买套餐

  1. 在套餐里选团队版或企业版，填写企业名称、联系人、席位数和首次预充值金额。
  2. 席位数是能开通的员工账号上限；预充值是模型用量的余额，员工每次调用按实际用量扣减。
  3. 付款后页面显示激活码和企业编号。激活码只显示一次、只能用一次，请立即保存；企业编号续充时要用。

安装企业网关

网关是企业自己的服务，装在内网的一台电脑或服务器上（macOS 或 Linux）。员工的 AI 请求、对话原文和调用记录都只存在这台机器上。

先装好 uv（macOS：brew install uv），然后在这台机器的终端运行：

安装完成后网关自动启动，管理后台默认是 http://127.0.0.1:8787。准备事项、常用命令和全部配置项见下载网关。

建议同时开启开机自启，电脑重启或网关意外退出后不用人工处理：安装时用下面这条命令，或装好后在安装目录运行 bin/officoa-gateway enable-autostart。macOS 和 Linux 的区别见开机自启说明。

模型服务

模型由平台提供：企业从平台购买的模型用量（Token）就是员工实际使用的额度，不需要另外准备模型服务商的账号或密钥。网关激活后员工即可使用，每次调用按实际用量从企业预充值里扣减，余量在管理后台“概览”可见，用完到续充额度页充值。

有特殊需要、要接企业自有模型服务（OpenAI 兼容接口）时，可以在 gateway.env 填写 OFFICOA_UPSTREAM_URL 与 OFFICOA_UPSTREAM_KEY_FILE，此时网关直接调用该服务，不使用平台的模型额度。一般不需要。

激活与管理员账号

  1. 浏览器打开管理后台，输入激活码，填写管理员姓名、邮箱和密码（至少 8 位）。
  2. 激活成功后自动登录。概览页显示企业名称、席位用量和预充值余额。
  3. 以后用这个邮箱和密码登录；登录 8 小时后需要重新登录。
激活码一旦成功使用就失效。如果激活前遗失，请提交工单，附上企业编号。

允许的编码工具

员工可以用以下工具调用 AI，管理员在管理后台的设置 → 允许的编码工具里勾选企业允许哪些（默认全部允许）：

  • OpenCode：命令行与桌面版。带会话编号，对话记录按会话归类最准，交接时能导入会话。
  • VS Code 自带 Chat：VS Code 1.122 及以上，用内置的 GitHub Copilot Chat，不需要登录 GitHub。
  • Continue：VS Code 里的 Continue 插件。

员工工具里模型分组显示的名称默认是“企业 AI 网关”，管理员可在后台设置 → 允许的编码工具改成公司自己的品牌（如“星河 AI”）。改名后员工重新运行一次配置命令、重开工具即可看到新名称。

员工在邀请页只能从允许的工具里选；来自未允许工具的调用会被网关拒绝，记在调用记录里，调用记录也能按工具筛选。VS Code 和 Continue 的调用同样经过审核、脱敏和计费，在“对话记录”里由网关按每段对话的第一条提问归并（OpenCode 带会话编号，归类更准，并支持交接时导入会话）。

工具是靠接入时写入的配置识别的，员工有办法绕开，所以“允许的工具”是使用规范，不是安全边界。真正防止内容绕过网关外发的，是网络出口只放行网关（见 IT 部署要求）。

邀请员工

  1. 打开员工与邀请，点新建员工并邀请，填写姓名、工作空间（项目名，用于归类调用记录）和额度。额度按金额（元）填写，旁边会显示约合多少 Token（按默认模型估算）。
  2. 复制生成的邀请链接，通过企业微信、邮件等发给员工。链接只能用一次，7 天内有效。
  3. 员工领取后，列表里显示他的 Key 前几位和“有效”。完整的 Key 只有员工本人见过，管理员看不到。

员工数不能超过席位数。要腾出席位，对离开的员工点停用。

企业策略

管理后台的企业策略页由企业管理员配置，只对本企业生效，修改立即生效：

  1. 谁能调阅员工的对话原文：默认没有人能看。勾选的后台账号在对话记录、调用详情、会话详情里直接看到原文，不用填理由；每次查看的人、时间、查看内容都记在本页的“原文调阅记录”里。请结合当地劳动与隐私法规，并事先告知员工。
  2. 外发前审核不可用时：默认阻断，员工看到“审核暂不可用，稍后再试”。也可以选择放行，但审核不可用期间内容不经检查、不脱敏就会发给模型，每次放行都会记一条风险事件，一般不建议。
  3. 失败或中断的调用怎么计费：模型已经开始返回、但中途失败或被中断的调用（编码工具通常会自动重试）。模型服务商照样按用量收费，所以都会扣企业预充值；可以选择是否计入员工个人额度。从未发出、被阻断的调用不收费。

管理员账号

在管理员账号页给同事开通后台账号，三种角色：

  • 企业管理员：管理员工、额度、交接、设置、企业策略与账号。
  • 财务：只看概览、调用记录和额度流水。
  • 安全审核：只看概览、调用记录、风险事件和审核设置。

新账号的初始密码只显示一次，请当面或通过企业内部渠道转交，对方首次登录必须修改。账号能否调阅原文与角色无关，只看企业策略里是否勾选。离职的同事请停用账号，停用后立即退出登录，也会自动从原文授权名单里移除。

每日简报

管理后台的每日简报按项目（即员工的工作空间）汇总某一天的工作情况，可以切换到前一天、后一天或任选日期：

  • 汇总：活跃项目与员工数、AI 调用、会话与代码提交数、拦截与脱敏、费用与 Token。
  • 需要关注：消息被拦截的员工、调用多次失败的员工、额度用到 80% 以上的员工、企业预充值不足 20%、用量待确认的调用。
  • 每个项目：参与的员工与时段、用了哪些编码工具、当天的会话、当天的代码提交、近 7 天的调用趋势。

会话标题取自对话内容，只对企业策略里授权调阅原文的账号显示；代码提交需要员工电脑安装同步代理才会上报。推送到手机（飞书 / 企业微信）在后续版本提供。

日常管理

  • 调用记录：每次调用的员工、编码工具、模型、用量和费用，可按工具筛选。原始请求、实际发给模型的内容和回复只有企业策略授权的账号能调阅（见下方“企业策略”）。
  • 风险事件：被拦截或脱敏的内容，只显示打码后的片段。
  • 额度与流水：每个员工的额度、已用和流水，可调整额度；顶部“额度分配”显示在职员工还可用的额度合计和企业剩余预充值，分给员工的额度合计超过企业剩余时会提醒（员工额度不会失效，但企业预充值用完后全体员工都无法调用）。额度周期可选“累计”（默认，不重置）或“每月 1 日重置”（员工已用清零，企业预充值的消耗照常累计）。
  • 对话记录：分两种看法。按问答：员工与 AI 的每一轮问答一行（时间、员工、工具、项目、提问、回复、调用次数、费用），可按员工、工具、项目、日期筛选、按关键词搜索，点一行展开全文；按会话：员工的每一段完整对话，交接时用（VS Code 与 Continue 的对话由网关按第一条提问归并成会话）。提问和回复属于原文：只有企业策略授权的账号能看（打开即显示），每次查看记入调阅日志。
  • 设置：外发前审核的开关和规则说明。审核关闭时网关会拦下全部请求，不会不经审核就发出。

推送提醒

在管理后台设置 → 推送提醒里配置，把提醒推送到飞书或企业微信的群：

  1. 在飞书群里添加“自定义机器人”，或在企业微信群里添加“群机器人”，复制它的 Webhook 地址。飞书机器人开启了“签名校验”的，同时复制签名密钥。
  2. 选择推送渠道，填入 Webhook 地址（和签名密钥），勾选要推送的提醒，保存后点“发送测试消息”确认群里能收到。

可推送的提醒：员工额度用到 80% 或用完；企业预充值剩余不足 20% 或用完；员工的消息因敏感信息被拦截（同一员工 10 分钟内只推送一次，全部记录见“风险事件”）。同一额度周期内每个提醒只发一次，调高员工额度或续充后会重新计算。推送内容只有员工姓名、规则名和金额，不含对话原文。

续充额度

  1. 打开续充额度，填写企业编号、联系人邮箱和金额，付款。
  2. 网关一分钟内自动同步新额度；也可以在管理后台概览点同步授权立即生效。

企业预充值余额用完后，所有员工的调用都会被拒绝，直到续充。员工个人额度用完只影响本人。

员工离职与交接

在交接中心发起交接，按顺序完成：发起 → 冻结与同步 → 吊销 → 移交 → 验收。接任者能看到离职员工的对话档案和关联的代码提交，接着往下做。

只需要让某人停止使用时：吊销 Key 让他的 Key 立即失效（之后可重新邀请）；停用同时释放他占用的席位。

员工指南

这一部分可以直接发给员工。你会用到：管理员发来的邀请链接、一台 Mac，以及你要用的编码工具（OpenCode、VS Code 或 VS Code 里的 Continue 插件）。

领取 Key

  1. 打开邀请链接，点“领取我的 Key”Key 只显示这一次，在这个页面完成配置之前不要关掉它。
  2. 选择你用的编码工具页面只列出企业允许的工具。用多个工具时，每个工具按各自的步骤配置一次，Key 相同。
  3. 复制页面上的配置命令，到“终端”里运行命令本身不含 Key。运行后终端会提示粘贴 Key。
  4. 回到网页复制 Key，粘贴到终端，回车粘贴时屏幕上不显示任何字符，这是正常的。看到“完成。身份：……”就好了。然后按下面你所用工具的说明打开它。

配置 OpenCode

配置命令会把 Key 存到 ~/.officoa/opencode.key（仅你可读），并写入 OpenCode 的全局配置（原配置自动备份）。完全退出 OpenCode（桌面版用 ⌘Q）再重新打开，模型列表里出现“企业 AI 网关”就生效了。

用 VS Code 选哪个？ VS Code 里有两个可以对话的地方，它们是两个不同的工具： 右侧的 CHAT 面板是 VS Code 自带 Chat（推荐，不用装插件，有 Agent 模式）； 左侧边栏的 CONTINUE 面板是 Continue 插件（备选，适合习惯 Continue 或不想启用 Copilot 插件的同事）。 在邀请页选一个、按对应步骤配置即可；两个都配也可以，Key 相同。面板可以拖到另一边，位置不影响使用。

配置 VS Code 自带 Chat（推荐，右侧 CHAT 面板）

需要 VS Code 1.122 或更新版本。配置命令会把企业网关的模型写入 VS Code 的自定义模型配置 chatLanguageModels.json（含你的 Key，仅你可读；原配置自动备份）。

  1. 完全退出 VS Code 再打开，按 ⌃⌘I 打开右侧的 CHAT 面板，点输入框下方的模型名（默认显示 Auto），展开最下面的 Other Models，选 deepseek-flash（企业 AI 网关），之后就在这里对话。列表上方标着 Upgrade 的 Claude、GPT 等是 GitHub 的付费模型，不要选。左侧资源管理器显示的是 VS Code 上次打开的文件夹（你电脑上原有的项目），与接入无关，可用“文件 → 关闭文件夹”关掉。
  2. 如果 Chat 一直显示 Getting chat ready：打开扩展视图，搜索 @builtin copilot，启用“GitHub Copilot Chat”。VS Code 的 Chat 由这个内置插件提供，新装的 VS Code 里它可能是禁用的。
  3. 出现“Set BYOK utility models”提示时点 Configure，把 Chat: Utility Model 和 Chat: Utility Small Model 都选为企业网关的模型（标有 Custom Endpoint）。这样起对话标题、生成提交信息等辅助功能也经过企业网关；不设置时这些功能用的是 GitHub 的模型。
  4. 不要登录 GitHub。在设置里把 telemetry.telemetryLevel 设为 off，把 editor.inlineSuggest.enabled 设为 false（行内补全不能经过企业网关）。

配置 Continue（备选，左侧 CONTINUE 面板）

先在 VS Code 扩展里安装 Continue。配置命令会写入 ~/.continue/config.yaml（含你的 Key，仅你可读；原配置自动备份）。重新打开 VS Code，点左侧边栏的 Continue 图标打开 CONTINUE 面板，模型选择“企业 AI 网关”，之后就在这里对话（右侧的 CHAT 是 VS Code 自带 Chat，不是 Continue）。如果 Continue 弹出要求填写 OpenAI、Anthropic 等 API Key 的窗口，直接关掉，不需要填写。

不要登录 Continue 账号；在 Continue 设置里关闭 Telemetry（或把 VS Code 设置 continue.telemetryEnabled 设为 false）。

开始使用

像平时一样提问、让 AI 读写代码。所有请求经过企业网关，用量计入你的个人额度。额度不够时请联系管理员调整。

内容被拦截或脱敏时

  • 被拦截：消息里有访问密钥、私钥这类内容时，整条消息不会发出，工具里会看到拦截提示。把密钥删掉再发一次即可，不用新开会话，被拦截的那条不会再被带上。
  • 被脱敏：手机号、身份证号和企业规定的内部词汇会被替换成 [已脱敏·手机号·3fa2c1] 这样的占位符再发出，对话照常进行。同一个值每次都换成同一个占位符，模型仍能分辨“是不是同一个号码”。

换电脑、丢了 Key

请管理员重新邀请你。领取新 Key 后，旧 Key 自动失效；在新电脑上按上面的步骤重新配置一次。同时用多个工具的，每个工具都要重新运行一次配置命令。

IT 部署要求

要确保员工的 AI 请求一定经过网关，只装网关不够，员工电脑和网络出口也要配合。以下要求来自我们对 OpenCode 网络行为的实测。

网关服务器

  • 配置要求（CPU、内存、磁盘按使用人数、操作系统、网络与需放行的地址）见服务器配置要求。20 人以内：2 核、4 GB 内存、100 GB SSD 即可。
  • 开启开机自启（bin/officoa-gateway enable-autostart）。macOS 用 launchd，需要该用户自动登录；Linux 用 systemd 用户服务，运行 sudo loginctl enable-linger <用户名> 后开机即启动。
  • 员工电脑能访问它的端口（默认 8787）。给内网使用时在 gateway.env 设置 OFFICOA_HOST=0.0.0.0 和 OFFICOA_GATEWAY_PUBLIC_URL=http://<内网地址>:8787，再重启。
  • 需要访问本平台（激活、授权同步、计量与模型调用），不需要放行模型服务商的地址。

员工电脑

用 OpenCode 的电脑：

  • 下发并锁定 OpenCode 全局配置（~/.config/opencode/opencode.jsonc），其中必须有 "enabled_providers": ["officoa"]。员工运行配置命令时会自动写入；用设备管理工具统一下发并设为只读更稳妥。
    只靠项目里的配置文件不够：OpenCode 找不到企业配置时，会不提示地改用内置的免费模型，把内容发到 opencode.ai。全局配置能杜绝这种情况。
  • 设置环境变量 OPENCODE_DISABLE_MODELS_FETCH=1 和 OPENCODE_DISABLE_FREE_MODELS=1（2.x 版本，第二道防线）。
  • 预装 ripgrep（brew install ripgrep），否则出口管控后 OpenCode 的搜索功能会因为下载不到它而失败。
  • 用脚本或其他程序启动 OpenCode 时，要同时设置工作目录和 PWD 环境变量，否则 OpenCode 会找错项目、读不到配置。

用 VS Code（自带 Chat 或 Continue）的电脑：

  • VS Code 1.122 或更新版本。用设备管理工具下发 VS Code 策略 TelemetryLevel = off，并锁定设置：editor.inlineSuggest.enabled = false；chat.utilityModel 与 chat.utilitySmallModel 设为企业网关的模型，辅助功能才不会用 GitHub 的模型。
  • 员工不要登录 GitHub。只用 Continue 的企业，建议在 VS Code 里禁用内置的“GitHub Copilot Chat”插件：我们实测发现它即使没登录也会连 GitHub Copilot 的服务地址。
  • Continue 关闭 Telemetry（设置 continue.telemetryEnabled = false），不要登录 Continue 账号。
  • VS Code 与 Continue 的配置文件里保存着员工 Key（权限 600）。员工离职或换电脑时，吊销 Key 即可让这些配置失效。

网络出口

  • 员工电脑访问 AI 服务的出口只放行企业网关；不需要为 OpenCode 放行 npm、GitHub 或 opencode.ai。
  • OpenCode 桌面版自身的外联不受上面的配置控制，需要在出口拦截：*.sentry.io（错误上报）和 opencode.ai/update（自动更新，建议由 IT 统一分发版本）。
  • VS Code 即使关闭了遥测，我们实测仍会连接以下地址，需要在出口拦截：*.applicationinsights.azure.com（遥测）、github.com、api.github.com、*.githubcopilot.com、www.githubstatus.com，以及云主机元数据地址 169.254.169.254。插件市场 marketplace.visualstudio.com 与 *.vscode-cdn.net 只在需要员工自行安装、更新插件时放行。
  • 在防火墙层面拦截，不要只靠代理设置：实测 VS Code 的辅助进程会绕过代理设置直连外部地址，程序也可以不遵守代理变量。

数据与备份

  • 全部数据在安装目录的 data/：数据库、对话原文档案、网关凭证、脱敏用的本地密钥。平台上没有副本，请定期备份。
  • gateway.env 请一并纳入备份。data/ 里的网关凭证文件（platform.credential，权限 600）是企业使用平台模型服务的凭据，泄露后请联系平台重置。

常见问题

OpenCode 报 “ECONNREFUSED” 或连不上
网关没有运行或地址不对。在网关机器上运行 bin/officoa-gateway status，没运行就 start。员工电脑上的地址来自 OFFICOA_GATEWAY_PUBLIC_URL，改过它要让员工重新运行配置命令。
电脑重启后网关没有起来
没有开启开机自启，或开启了但该用户还没登录。运行 bin/officoa-gateway status：显示“未开启自启”就运行 enable-autostart；macOS 请打开该用户的自动登录，Linux 请管理员运行 sudo loginctl enable-linger <用户名>。
VS Code 的 Chat 一直显示 Getting chat ready，没有选模型的地方
内置的“GitHub Copilot Chat”插件被禁用了。打开扩展视图，搜索 @builtin copilot，启用它，然后重开 VS Code。
Continue 的回复是一堆 <｜DSML｜…> 之类的乱码
Continue 没把这个模型当作支持工具调用的模型。重新运行邀请页上 Continue 的配置命令（v1.4.1 起配置里带 capabilities: [tool_use]），然后在 Continue 里新开对话。
VS Code 提示“缺少个人 Key”
自定义模型配置里没有带上 Key。重新运行邀请页上 VS Code 的配置命令；手动配置时注意 Key 要写在 requestHeaders 的 Authorization 里（apiKey 字段只认 VS Code 安全存储的引用）。
提示“企业未允许使用……调用 AI”
你用的工具不在企业允许的范围内，或者没有按邀请页配置（网关识别不出是哪个工具）。按邀请页上对应工具的命令重新配置；需要用其他工具时请联系管理员在设置里勾选。
调用返回 502
网关连不上平台的模型服务。检查网关服务器能否访问本平台，用 bin/officoa-gateway logs 看具体错误。
提示额度不足
员工个人额度用完时，管理员在额度与流水里调整；企业预充值用完时，到续充额度付款。
配置命令提示 Key 格式不对
粘贴的不是 Key。最常见的是剪贴板里还是刚才复制的命令：回到邀请页面，点 Key 旁边的“复制”，再粘贴。
OpenCode 里看不出变化，后台也没有调用记录
OpenCode 没有用上企业配置。完全退出 OpenCode 再打开；检查 ~/.config/opencode/opencode.jsonc 里是否有 officoa；确认选择的模型属于“企业 AI 网关”。
邀请链接打不开或显示已过期
链接 7 天有效、只能用一次，重新邀请后旧链接作废。请管理员再点一次重新邀请。
激活时提示激活码无效
确认没有多余的空格，字母 O 和数字 0 不会同时出现（激活码不含 0、O、1、I）。激活码只能用一次；仍有问题请提交工单。

没有找到答案？提交工单。