@hjd-hitsz/claudex-web 0.0.0-stage → 4.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (317) hide show
  1. package/.env.example +27 -0
  2. package/CHANGELOG.md +449 -0
  3. package/LICENSE +674 -0
  4. package/README.md +128 -2
  5. package/bin/claudex-web.mjs +129 -0
  6. package/build-info.json +8 -0
  7. package/client/dist/_baseMerge.js +1 -0
  8. package/client/dist/abnfDiagram-WEYOIA3C.js +1 -0
  9. package/client/dist/apl.js +1 -0
  10. package/client/dist/app.js +393 -0
  11. package/client/dist/apple-touch-icon.png +0 -0
  12. package/client/dist/arc.js +1 -0
  13. package/client/dist/architectureDiagram-ZHVYKT53.js +36 -0
  14. package/client/dist/asciiarmor.js +1 -0
  15. package/client/dist/asn1.js +1 -0
  16. package/client/dist/asterisk.js +1 -0
  17. package/client/dist/blockDiagram-RJAE7QA3.js +140 -0
  18. package/client/dist/brainfuck.js +1 -0
  19. package/client/dist/c4Diagram-XDPPPE54.js +38 -0
  20. package/client/dist/channel.js +1 -0
  21. package/client/dist/chunk-2E7WHVMD.js +88 -0
  22. package/client/dist/chunk-2Q5K7J3B.js +1 -0
  23. package/client/dist/chunk-4EMNKR2T.js +1 -0
  24. package/client/dist/chunk-55XCU76K.js +1 -0
  25. package/client/dist/chunk-5VM5RSS4.js +15 -0
  26. package/client/dist/chunk-JWPE2WC7.js +1 -0
  27. package/client/dist/chunk-VQ5W62QI.js +1 -0
  28. package/client/dist/chunk-XXDRQBXY.js +1 -0
  29. package/client/dist/chunk-ZCHMQSOR.js +2 -0
  30. package/client/dist/classDiagram-v2-4MYWR3UA.js +217 -0
  31. package/client/dist/clike.js +1 -0
  32. package/client/dist/clojure.js +1 -0
  33. package/client/dist/cmake.js +1 -0
  34. package/client/dist/cobol.js +1 -0
  35. package/client/dist/code-highlight-style.js +13 -0
  36. package/client/dist/coffeescript.js +1 -0
  37. package/client/dist/commonlisp.js +1 -0
  38. package/client/dist/cose-bilkent-JH36ORCC.js +1 -0
  39. package/client/dist/crystal.js +1 -0
  40. package/client/dist/css.js +1 -0
  41. package/client/dist/cynefin-EF2NZ3EQ.js +141 -0
  42. package/client/dist/cynefinDiagram-WF24UDRP.js +62 -0
  43. package/client/dist/cypher.js +1 -0
  44. package/client/dist/cytoscape.esm.js +321 -0
  45. package/client/dist/d.js +1 -0
  46. package/client/dist/dagre-NK4GIZVX.js +4 -0
  47. package/client/dist/defaultLocale.js +1 -0
  48. package/client/dist/diagram-CBK3MWTC.js +24 -0
  49. package/client/dist/diagram-I5XIIV2D.js +24 -0
  50. package/client/dist/diagram-ODIL2UCW.js +30 -0
  51. package/client/dist/diagram-PFBEJUXE.js +3 -0
  52. package/client/dist/diagram-RJA3I4VV.js +41 -0
  53. package/client/dist/diagram-TYUNFSNR.js +200 -0
  54. package/client/dist/diff.js +1 -0
  55. package/client/dist/dockerfile.js +1 -0
  56. package/client/dist/document-editor.js +1040 -0
  57. package/client/dist/dtd.js +1 -0
  58. package/client/dist/dylan.js +1 -0
  59. package/client/dist/ebnf.js +1 -0
  60. package/client/dist/ebnfDiagram-V4P3TTPT.js +1 -0
  61. package/client/dist/ecl.js +1 -0
  62. package/client/dist/eiffel.js +1 -0
  63. package/client/dist/elk-QONTBCTQ.js +27 -0
  64. package/client/dist/elm.js +1 -0
  65. package/client/dist/erDiagram-KYQIGQAA.js +99 -0
  66. package/client/dist/erlang.js +1 -0
  67. package/client/dist/factor.js +1 -0
  68. package/client/dist/favicon.ico +0 -0
  69. package/client/dist/favicon.png +0 -0
  70. package/client/dist/fcl.js +1 -0
  71. package/client/dist/file-panel.js +1 -0
  72. package/client/dist/flowDiagram-IUGLLWBU.js +213 -0
  73. package/client/dist/forth.js +1 -0
  74. package/client/dist/fortran.js +1 -0
  75. package/client/dist/ganttDiagram-R7GPNTJY.js +292 -0
  76. package/client/dist/gas.js +1 -0
  77. package/client/dist/gherkin.js +1 -0
  78. package/client/dist/gitGraphDiagram-PDYL7XHY.js +106 -0
  79. package/client/dist/graph.js +1 -0
  80. package/client/dist/groovy.js +1 -0
  81. package/client/dist/haskell.js +1 -0
  82. package/client/dist/haxe.js +1 -0
  83. package/client/dist/http.js +1 -0
  84. package/client/dist/idl.js +1 -0
  85. package/client/dist/index.html +25 -0
  86. package/client/dist/index.js +2 -0
  87. package/client/dist/index10.js +1 -0
  88. package/client/dist/index11.js +1 -0
  89. package/client/dist/index12.js +1 -0
  90. package/client/dist/index13.js +7 -0
  91. package/client/dist/index14.js +1 -0
  92. package/client/dist/index15.js +1 -0
  93. package/client/dist/index16.js +6 -0
  94. package/client/dist/index17.js +1 -0
  95. package/client/dist/index18.js +3 -0
  96. package/client/dist/index19.js +1 -0
  97. package/client/dist/index2.js +1 -0
  98. package/client/dist/index20.js +1 -0
  99. package/client/dist/index21.js +1 -0
  100. package/client/dist/index22.js +1 -0
  101. package/client/dist/index3.js +1 -0
  102. package/client/dist/index4.js +1 -0
  103. package/client/dist/index5.js +1 -0
  104. package/client/dist/index6.js +13 -0
  105. package/client/dist/index7.js +1 -0
  106. package/client/dist/index8.js +1 -0
  107. package/client/dist/index9.js +1 -0
  108. package/client/dist/infoDiagram-MVDRKAX5.js +2 -0
  109. package/client/dist/init.js +1 -0
  110. package/client/dist/isArrayLikeObject.js +1 -0
  111. package/client/dist/ishikawaDiagram-HPEHV2GE.js +70 -0
  112. package/client/dist/javascript.js +1 -0
  113. package/client/dist/journeyDiagram-BOSHW7O7.js +139 -0
  114. package/client/dist/julia.js +1 -0
  115. package/client/dist/kanban-definition-FNSA4HC5.js +89 -0
  116. package/client/dist/katex.js +257 -0
  117. package/client/dist/linear.js +1 -0
  118. package/client/dist/livescript.js +1 -0
  119. package/client/dist/lua.js +1 -0
  120. package/client/dist/mathematica.js +1 -0
  121. package/client/dist/mbox.js +1 -0
  122. package/client/dist/mermaid.core.js +310 -0
  123. package/client/dist/mindmap-definition-6OY57UG3.js +98 -0
  124. package/client/dist/mirc.js +1 -0
  125. package/client/dist/mllike.js +1 -0
  126. package/client/dist/modelica.js +1 -0
  127. package/client/dist/mscgen.js +1 -0
  128. package/client/dist/mumps.js +1 -0
  129. package/client/dist/nginx.js +1 -0
  130. package/client/dist/notification-worker.js +45 -0
  131. package/client/dist/nsis.js +1 -0
  132. package/client/dist/ntriples.js +1 -0
  133. package/client/dist/octave.js +1 -0
  134. package/client/dist/ordinal.js +1 -0
  135. package/client/dist/oz.js +1 -0
  136. package/client/dist/pascal.js +1 -0
  137. package/client/dist/pegDiagram-ECIUJNBX.js +1 -0
  138. package/client/dist/perl.js +1 -0
  139. package/client/dist/pieDiagram-GNMPY74T.js +39 -0
  140. package/client/dist/pig.js +1 -0
  141. package/client/dist/powershell.js +1 -0
  142. package/client/dist/properties.js +1 -0
  143. package/client/dist/protobuf.js +1 -0
  144. package/client/dist/pug.js +1 -0
  145. package/client/dist/puppet.js +1 -0
  146. package/client/dist/purify.es.js +3 -0
  147. package/client/dist/python.js +1 -0
  148. package/client/dist/q.js +1 -0
  149. package/client/dist/quadrantDiagram-D57K4MC3.js +7 -0
  150. package/client/dist/r.js +1 -0
  151. package/client/dist/railroadDiagram-Y72NRBL7.js +1 -0
  152. package/client/dist/requirementDiagram-EQYSW5RA.js +84 -0
  153. package/client/dist/rpm.js +1 -0
  154. package/client/dist/ruby.js +1 -0
  155. package/client/dist/sankeyDiagram-SY24JHO5.js +40 -0
  156. package/client/dist/sas.js +1 -0
  157. package/client/dist/scheme.js +1 -0
  158. package/client/dist/sequenceDiagram-BLEHNHQU.js +169 -0
  159. package/client/dist/shell.js +1 -0
  160. package/client/dist/sieve.js +1 -0
  161. package/client/dist/simple-mode.js +1 -0
  162. package/client/dist/sizeCapture-INFHLROL.js +1 -0
  163. package/client/dist/smalltalk.js +1 -0
  164. package/client/dist/solr.js +1 -0
  165. package/client/dist/sparql.js +1 -0
  166. package/client/dist/spreadsheet.js +1 -0
  167. package/client/dist/sql.js +1 -0
  168. package/client/dist/stateDiagram-v2-A6IESKWZ.js +291 -0
  169. package/client/dist/stex.js +1 -0
  170. package/client/dist/style.css +1 -0
  171. package/client/dist/stylus.js +1 -0
  172. package/client/dist/swift.js +1 -0
  173. package/client/dist/swimlanes-B3ENRKFQ.js +1 -0
  174. package/client/dist/swimlanesDiagram-AYQRV4AK.js +8 -0
  175. package/client/dist/tcl.js +1 -0
  176. package/client/dist/terminal-panel.js +18 -0
  177. package/client/dist/textile.js +1 -0
  178. package/client/dist/tiddlywiki.js +1 -0
  179. package/client/dist/tiki.js +1 -0
  180. package/client/dist/timeline-definition-JXYKGLGB.js +120 -0
  181. package/client/dist/toml.js +1 -0
  182. package/client/dist/troff.js +1 -0
  183. package/client/dist/ttcn-cfg.js +1 -0
  184. package/client/dist/ttcn.js +1 -0
  185. package/client/dist/turtle.js +1 -0
  186. package/client/dist/usecaseDiagram-WPOLBNNX.js +370 -0
  187. package/client/dist/vb.js +1 -0
  188. package/client/dist/vbscript.js +1 -0
  189. package/client/dist/velocity.js +1 -0
  190. package/client/dist/vennDiagram-Q3Y3IDCW.js +34 -0
  191. package/client/dist/verilog.js +1 -0
  192. package/client/dist/vhdl.js +1 -0
  193. package/client/dist/wardleyDiagram-IVAIDKWA.js +78 -0
  194. package/client/dist/webidl.js +1 -0
  195. package/client/dist/xquery.js +1 -0
  196. package/client/dist/xychartDiagram-4URNHDU4.js +7 -0
  197. package/client/dist/yacas.js +1 -0
  198. package/client/dist/z80.js +1 -0
  199. package/docs/architecture/backend-regressions.md +53 -0
  200. package/docs/architecture/backends.md +113 -0
  201. package/docs/architecture/behavior.md +206 -0
  202. package/docs/architecture.md +306 -0
  203. package/docs/background-tasks.md +39 -0
  204. package/docs/cli-command-coverage.md +60 -0
  205. package/docs/deployment.md +269 -0
  206. package/docs/development.md +385 -0
  207. package/docs/images/desktop-dark.png +0 -0
  208. package/docs/images/desktop-light.png +0 -0
  209. package/docs/images/mobile-sidebar.png +0 -0
  210. package/docs/images/mobile.png +0 -0
  211. package/docs/releases/v2.0.0.md +5 -0
  212. package/docs/releases/v2.1.0.md +6 -0
  213. package/docs/releases/v2.1.1.md +6 -0
  214. package/docs/releases/v2.1.2.md +8 -0
  215. package/docs/releases/v2.2.0.md +11 -0
  216. package/docs/releases/v2.3.0.md +12 -0
  217. package/docs/releases/v2.3.1.md +8 -0
  218. package/docs/releases/v2.4.0.md +8 -0
  219. package/docs/releases/v2.4.1.md +8 -0
  220. package/docs/releases/v2.4.2.md +8 -0
  221. package/docs/releases/v3.0.0.md +9 -0
  222. package/docs/releases/v3.1.0.md +10 -0
  223. package/docs/releases/v3.1.1.md +7 -0
  224. package/docs/releases/v4.0.0-beta.1.md +10 -0
  225. package/docs/releases/v4.0.0.md +20 -0
  226. package/docs/releases/v4.0.1.md +10 -0
  227. package/docs/versioning.md +119 -0
  228. package/package.json +70 -4
  229. package/scripts/install-services.mjs +134 -0
  230. package/scripts/restart-when-idle.mjs +125 -0
  231. package/scripts/start-backend.mjs +29 -0
  232. package/server/src/agent-messages.mjs +124 -0
  233. package/server/src/application.mjs +133 -0
  234. package/server/src/auth.mjs +328 -0
  235. package/server/src/backends/claude/account.mjs +171 -0
  236. package/server/src/backends/claude/adapter.mjs +366 -0
  237. package/server/src/backends/claude/agent-history.mjs +70 -0
  238. package/server/src/backends/claude/background-tasks.mjs +168 -0
  239. package/server/src/backends/claude/catalogue.mjs +266 -0
  240. package/server/src/backends/claude/execution-errors.mjs +44 -0
  241. package/server/src/backends/claude/execution-session.mjs +390 -0
  242. package/server/src/backends/claude/git-tool-changes.mjs +77 -0
  243. package/server/src/backends/claude/goals.mjs +319 -0
  244. package/server/src/backends/claude/history-actions.mjs +170 -0
  245. package/server/src/backends/claude/history.mjs +65 -0
  246. package/server/src/backends/claude/hooks.mjs +232 -0
  247. package/server/src/backends/claude/input-stream.mjs +24 -0
  248. package/server/src/backends/claude/messages-request.mjs +34 -0
  249. package/server/src/backends/claude/messages.mjs +300 -0
  250. package/server/src/backends/claude/model-options.mjs +18 -0
  251. package/server/src/backends/claude/native-commands.mjs +48 -0
  252. package/server/src/backends/claude/native-records.mjs +76 -0
  253. package/server/src/backends/claude/process-ownership.mjs +82 -0
  254. package/server/src/backends/claude/project-instructions.mjs +40 -0
  255. package/server/src/backends/claude/provider-balance.mjs +40 -0
  256. package/server/src/backends/claude/provider-environment.mjs +93 -0
  257. package/server/src/backends/claude/provider-transport.mjs +70 -0
  258. package/server/src/backends/claude/recovery.mjs +54 -0
  259. package/server/src/backends/claude/runtime.mjs +463 -0
  260. package/server/src/backends/claude/session-worker.mjs +32 -0
  261. package/server/src/backends/claude/sessions.mjs +347 -0
  262. package/server/src/backends/claude/token-usage.mjs +98 -0
  263. package/server/src/backends/claude/worker-client.mjs +344 -0
  264. package/server/src/backends/claude/worker-launcher.mjs +119 -0
  265. package/server/src/backends/claude/worker-location.mjs +31 -0
  266. package/server/src/backends/claude/worker-revision.mjs +45 -0
  267. package/server/src/backends/claude/worker-server.mjs +290 -0
  268. package/server/src/backends/cli-installation.mjs +140 -0
  269. package/server/src/backends/codex/adapter.mjs +153 -0
  270. package/server/src/backends/codex/compaction-recovery.mjs +78 -0
  271. package/server/src/backends/codex/events.mjs +125 -0
  272. package/server/src/backends/codex/methods.mjs +17 -0
  273. package/server/src/backends/codex/reference-mcp.mjs +97 -0
  274. package/server/src/backends/codex/reference-tools.mjs +71 -0
  275. package/server/src/backends/codex/requests.mjs +170 -0
  276. package/server/src/backends/codex/subscriptions.mjs +91 -0
  277. package/server/src/backends/codex/upstream.mjs +148 -0
  278. package/server/src/backends/configuration.mjs +122 -0
  279. package/server/src/backends/identity-mapping.mjs +87 -0
  280. package/server/src/backends/manager.mjs +412 -0
  281. package/server/src/backends/network-proxy.mjs +55 -0
  282. package/server/src/backends/provider-presets.mjs +45 -0
  283. package/server/src/backends/providers.mjs +132 -0
  284. package/server/src/backends/storage.mjs +35 -0
  285. package/server/src/bridge/conversation-policy.mjs +29 -0
  286. package/server/src/bridge/file-operations.mjs +47 -0
  287. package/server/src/bridge/product-methods.mjs +66 -0
  288. package/server/src/compaction.mjs +82 -0
  289. package/server/src/config.mjs +57 -0
  290. package/server/src/file-content.mjs +99 -0
  291. package/server/src/file-undo.mjs +142 -0
  292. package/server/src/http/router.mjs +80 -0
  293. package/server/src/http/static.mjs +62 -0
  294. package/server/src/product-config.mjs +80 -0
  295. package/server/src/project-models.mjs +59 -0
  296. package/server/src/rpc-transport.mjs +21 -0
  297. package/server/src/server.mjs +20 -0
  298. package/server/src/summary-translation.mjs +82 -0
  299. package/server/src/system-auth.mjs +45 -0
  300. package/server/src/thread-folders.mjs +76 -0
  301. package/server/src/thread-names.mjs +264 -0
  302. package/server/src/thread-projects.mjs +36 -0
  303. package/server/src/tls.mjs +87 -0
  304. package/server/src/version.mjs +55 -0
  305. package/server/src/web-config-migration.mjs +48 -0
  306. package/server/src/workspace/commands.mjs +33 -0
  307. package/server/src/workspace/files.mjs +44 -0
  308. package/server/src/workspace/service.mjs +27 -0
  309. package/server/src/workspace/terminals.mjs +122 -0
  310. package/shared/backend-activity.mjs +13 -0
  311. package/shared/backend-capabilities.mjs +33 -0
  312. package/shared/backend-identity.mjs +17 -0
  313. package/shared/compaction-state.mjs +49 -0
  314. package/shared/file-types.mjs +82 -0
  315. package/shared/product-contract.mjs +26 -0
  316. package/shared/rpc-limits.mjs +2 -0
  317. package/shared/terminal-workspace.mjs +26 -0
@@ -0,0 +1,269 @@
1
+ # 部署与维护
2
+
3
+ 本文面向安装和运行 Claudex Web 的使用者,说明发行包安装、配置、服务管理、升级与故障处理。界面预览与快速开始见 [README](../README.md)。
4
+
5
+ ## 安装发行包
6
+
7
+ 稳定版 [v4.0.1](https://github.com/hjd-hitsz/claudex-web/releases/tag/v4.0.1):
8
+
9
+ ```bash
10
+ npm install -g https://github.com/hjd-hitsz/claudex-web/releases/download/v4.0.1/claudex-web-4.0.1.tgz
11
+ ```
12
+
13
+ 准备 Node.js 24+、npm、Codex CLI、OpenSSL、Linux PAM、`pamtester`、`/usr/bin/zsh` 和 systemd 后,以运行代理后端的普通用户安装:
14
+
15
+ ```bash
16
+ npm install -g https://github.com/hjd-hitsz/claudex-web/releases/download/v4.0.1/claudex-web-4.0.1.tgz
17
+ claudex-web service install
18
+ loginctl enable-linger "$USER"
19
+ claudex-web service status
20
+ curl --cacert "${CLAUDEX_WEB_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/claudex-web}/tls/certificate.pem" https://127.0.0.1:8766/healthz
21
+ ```
22
+
23
+ `service install` 创建缺失的后端服务并安装网页服务,启用两者的自启动;已有后端服务继续使用原配置。`enable-linger` 使用户服务可在开机后、登录前启动,是否需要管理员操作由系统授权策略决定。npm 全局命令所在目录需在 `PATH` 中,目标电脑的防火墙需允许访问网页端口。
24
+
25
+ 默认网页地址为 `https://电脑IP:8766`,本机可使用 `https://127.0.0.1:8766`。网页登录使用运行服务的系统账户,成功后沿用本机 Codex 授权,以服务用户的完全访问权限执行任务。访问和登录均使用加密连接。
26
+
27
+ ### 下载后安装与校验
28
+
29
+ 从目标版本 Release 下载 `.tgz` 和同名 `.sha256` 文件,将两者放在同一目录,然后执行:
30
+
31
+ ```bash
32
+ sha256sum -c claudex-web-4.0.1.tgz.sha256
33
+ npm install -g ./claudex-web-4.0.1.tgz
34
+ claudex-web service install
35
+ ```
36
+
37
+ 安装使用构建生成或对应版本 Release 提供的 `.tgz` 文件。安装过程中,npm 会获取运行依赖,目标电脑需具备相应缓存或能访问配置的 npm registry。
38
+
39
+ 文件差异与撤销校验需要服务环境能够运行 `git`。文件变更汇总也支持 Git 仓库以外的目录;“撤销”遇到后续修改冲突时会保留当前文件。升级后先等待当前任务和网页终端结束,再重启网页服务并刷新页面,以使用更新后的功能。
40
+
41
+ ## 计划与执行
42
+
43
+ 计划模式先调查需求并给出完整方案,支持继续提交修改意见。方案完成后可批准执行,批准成功后自动回到执行模式;发送失败时保留方案供重试。刷新后恢复方案和待批准状态,底部未发送草稿与附件在批准时保持独立。计划调查、修改和批准后的执行均使用当前选择的模型,并计入该模型的正常用量。
44
+
45
+ ## HTTPS 与系统登录
46
+
47
+ 系统登录需要 Linux PAM 与 `pamtester`。Debian / Ubuntu 可由管理员安装:
48
+
49
+ ```bash
50
+ sudo apt-get install pamtester openssl
51
+ ```
52
+
53
+ 网页登录只允许运行 Claudex Web 的系统账户,使用该账户的系统密码。账户须有可用密码,且处于允许登录的状态。默认使用系统的 `login` PAM 服务,管理员可通过 `AUTH_PAM_SERVICE` 指定专用策略。仅配置 SSH 密钥、没有可用系统密码的账户,需要先在系统中设置密码。网页服务继续以普通用户身份运行。
54
+
55
+ 登录状态默认保留 30 天,`AUTH_SESSION_DAYS` 可设为 1~90 天。刷新网页、重新打开浏览器或重启服务后,有效登录会自动恢复。退出会让同一浏览器的所有标签页返回登录页面,其他设备继续保持登录。到期或清除浏览器 Cookie 后需要重新登录。未发送草稿保留在原浏览器,已经提交的任务继续运行。
56
+
57
+ ### 证书配置
58
+
59
+ 未指定证书时,首次启动生成一年有效的本站证书,保存在 `CLAUDEX_WEB_CONFIG_DIR/tls`(默认 `~/.config/claudex-web/tls`)。证书包含 localhost、当前主机名及生成时的本机 IP,私钥仅服务用户可读。首次访问前,在服务电脑查看指纹,并与浏览器显示的证书核对,再按设备的证书管理方式安装该证书:
60
+
61
+ ```bash
62
+ openssl x509 -in "${CLAUDEX_WEB_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/claudex-web}/tls/certificate.pem" -noout -fingerprint -sha256
63
+ ```
64
+
65
+ 登录页和“设置 → 网页登录”中的“浏览器证书安装”提供证书下载与 Ubuntu、Windows、macOS、iPhone/iPad、Android 安装步骤。先向管理员核对证书,再下载并安装到用于访问的设备上。安装后重新打开浏览器,确认地址栏的证书警告消失,再输入登录密码。
66
+
67
+ Ubuntu 上,在文件管理器中打开证书下载目录,右键选择“在终端打开”。将下载的 DER 格式证书转换为 PEM 格式并安装到系统信任库,按提示输入本机管理员密码:
68
+
69
+ ```bash
70
+ openssl x509 -inform DER -in claudex-web.cer -out claudex-web.crt
71
+ sudo install -m 644 claudex-web.crt /usr/local/share/ca-certificates/claudex-web.crt
72
+ sudo update-ca-certificates
73
+ ```
74
+
75
+ 重复下载时请核对实际文件名。完全退出浏览器后重新访问;Chrome / Chromium 仍有警告时,在“设置 → 隐私和安全 → 安全 → 管理证书”的自定义或受信任证书中导入 `claudex-web.crt`。Firefox 可在“设置 → 隐私与安全 → 证书 → 查看证书 → 证书颁发机构”中导入,并信任此证书以标识网站。浏览器版本不同,入口名称可能略有差异;完成后重启浏览器并检查证书警告。
76
+
77
+ 首次证书警告发生在网页打开之前。核对证书后,可通过浏览器的“高级 → 继续访问”进入下载页面;浏览器没有继续入口时,请管理员直接提供证书。证书更新后,各设备需要重新核对并安装。使用证书机构签发的证书仍有警告时,请管理员检查证书配置或提供所需的信任证书。
78
+
79
+ 也可在网页配置文件中指定受浏览器信任的证书链与私钥:
80
+
81
+ ```dotenv
82
+ TLS_CERT=/absolute/path/to/fullchain.pem
83
+ TLS_KEY=/absolute/path/to/privkey.pem
84
+ AUTH_SESSION_DAYS=30
85
+ ```
86
+
87
+ 两项证书路径须同时设置,并允许服务用户读取;私钥权限应设为 600。域名、IP 或证书有效期变化时更新证书并在空闲时重启网页服务。需要重新生成自动证书时,在服务停止后将整个 `tls` 目录移至备份位置,再启动服务;客户端需重新核对和信任新证书。
88
+
89
+ 网页端口只接受 HTTPS。旧的 HTTP 书签应改为 HTTPS;切换地址前,请先保存旧页面中的未发送草稿;新地址会单独保存浏览器偏好。使用域名反向代理时,浏览器到代理及代理到网页服务两段都使用 TLS,代理应验证上游证书,并保留原始 Host、Origin 和 WebSocket 升级头。Codex 后端的 `ws://` 仅限本机回环地址,跨主机后端必须使用 `wss://`。
90
+
91
+ ### 登录故障
92
+
93
+ 用户名或密码错误、账户锁定或到期时,请确认用户名、密码和账户状态。提示“登录暂不可用”时,由管理员检查 `pamtester` 是否安装及服务日志。非标准安装路径可通过 `AUTH_PAMTESTER=/absolute/path/to/pamtester` 指定。尝试次数过多时,请按页面提示稍后重试。
94
+
95
+ ## 命令与前台运行
96
+
97
+ - `claudex-web` / `claudex-web start`:前台运行网页服务,连接已启用的 Codex 和 Claude Code。
98
+ - `claudex-web backend`:前台运行 Codex app-server。
99
+ - `claudex-web config init`:创建用户 `.env`,显示配置路径并保留已有文件。
100
+ - `claudex-web --version` / `claudex-web version --json`:查看版本或完整的版本来源信息。
101
+ - `claudex-web service install`:安装或更新服务文件,启动尚未运行的服务。
102
+ - `claudex-web service status`:查看网页与后端状态。
103
+ - `claudex-web service start` / `stop` / `restart`:启动、停止或重启网页服务;启动网页时也会拉起后端,停止网页时后端继续运行。
104
+ - `claudex-web service restart-when-idle`:等待当前任务和上下文整理结束后重启网页,打开的网页终端保持独立。
105
+
106
+ 前台运行时,在两个终端分别执行 `claudex-web backend` 和 `claudex-web`,并保持终端打开。已有可连接的后端时,直接运行 `claudex-web`。
107
+
108
+ ## Claude Code 与模型配置
109
+
110
+ 在设置的“模型与服务配置”中,点击 Codex 或 Claude Code 标题前的复选框即可启用或停用。程序自动检测当前服务账户的 CLI 安装,显示安装状态、当前 CLI 版本和 npm 官方包的最新版本;打开设置时自动检测,设置保持打开时每五分钟刷新,也可点击“重新检测”。
111
+
112
+ 未安装时点击“一键安装”,已安装时点击“一键更新”。安装任务由服务器执行,使用当前服务账户的 npm 全局安装 `@openai/codex@latest` 或 `@anthropic-ai/claude-code@latest`,关闭设置后继续执行,完成后自动刷新安装和版本状态。安装或更新前需等待所属后端任务结束;安装失败会显示错误,可重试。npm 全局目录需允许当前账户写入。也可在服务电脑执行:
113
+
114
+ ```bash
115
+ npm install -g @openai/codex
116
+ npm install -g @anthropic-ai/claude-code
117
+ ```
118
+
119
+ CLI 自动从当前 Node.js 的安装目录、服务 PATH 和用户 `~/.local/bin` 查找。systemd 服务安装时记录当前 Node.js 和 PATH;更换 Node.js 安装后重新执行 `claudex-web service install` 并在空闲时重启网页服务。Claude Code 复用 `CLAUDE_CONFIG_DIR`(默认 `~/.claude`)中的认证、技能、插件和历史;Codex 沿用 `CODEX_HOME`(默认 `~/.codex`)及既有 app-server 连接。使用原生账户时,先在服务电脑以同一账户完成 CLI 登录。
120
+
121
+ 在设置页 Claude Code 的供应商列表中添加服务名称、API 地址、凭据和模型标识。多个供应商共用此 Claude Code 后端。在输入框的模型菜单选择“供应商 · 模型”,新对话会使用对应后端;已有 Claude 对话可在任务结束后更换供应商或模型并继续。
122
+
123
+ API 地址需支持 Messages 请求及工具调用,填写服务基地址,例如 `https://model.example`,请求路径会追加 `/v1/messages`;服务有统一路径前缀时将其保留在基地址中。按服务提供的接口选择标准 Messages 或 Anthropic 协议。模型标识和支持的思考强度、速度档位以服务实际配置为准。API Key 保存在服务器,编辑时留空保留原凭据,勾选清除会移除已保存凭据。
124
+
125
+ 默认供应商 DeepSeek 仅提供 API Key 输入,接口、模型与能力参数由程序按官方文档配置,API Key 初始为空。点击“编辑”,填写 Key 并保存即可启用;编辑后保存空 Key 会清除已保存凭据并停用,模型菜单同步移除该供应商。DeepSeek 使用 `https://api.deepseek.com/anthropic`,预置 `deepseek-flash` 和 `deepseek-v4-pro`,上下文容量为 1,048,576 tokens,思考强度提供 low、high、max,支持思考开关,服务端默认强度为 high;接口与模型依据 [DeepSeek 官方文档](https://api-docs.deepseek.com/guides/anthropic_api/)。自行添加的供应商继续使用上述留空保留及勾选清除规则。
126
+
127
+ 自定义模型可填写可选的显示别名,留空沿用原名称。别名随供应商配置保存在服务器,其他浏览器连接同一服务后使用相同名称,实际调用使用原始模型标识。
128
+
129
+ 自定义模型可在“模型参数”中填写上下文容量,单位为 tokens。填写模型服务当前实际加载的容量,模型说明中的最大支持容量用于核对服务配置;重新加载模型并调整容量后,同步更新此值。网页底部的上下文用量采用当前对话的原生计量。
130
+
131
+ Claude Code 的对话、配置和原生账户状态继续保存在本机 CLI 原有目录。使用原生账户时,沿用本机 CLI 的认证;使用外部供应商时,任务使用网页配置的地址、凭据和模型。账户行按当前对话显示身份:原生账户可显示服务返回的额度窗口及额外用量,外部供应商显示外部计费状态。账户额度读取失败可重试,对话和文件操作继续使用各自的连接状态。
132
+
133
+ 两个后端均提供文件浏览、编辑及文件和目录模糊查询。网页手动终端统一运行在 Claudex Web 服务所在主机,终端按启动文件夹隔离,同目录切换模型后端保留已有进程,返回原文件夹恢复对应终端。Claude Code 同样提供计划与批准、代码审查、目标、后台终端清理、分支与消息编辑;原生技能、命令、插件和工具连接按当前工作目录加载。后台终端由 `/stop` 查看和停止,聊天区停止按钮中断当前轮次。切换供应商或修改配置前,先结束当前任务及需要继续保留的后台终端。
134
+
135
+ `/init` 检查并保留当前目录已有的 `AGENTS.md`,缺少时生成项目指令。Claude Code 每次提交读取当前目录及祖先目录的 `AGENTS.override.md` 或 `AGENTS.md`,同目录优先 override,更具体目录的规则优先;文件修改和删除从下一轮生效。已有的 `CLAUDE.md` 继续生效。
136
+
137
+ 后端和供应商配置默认保存至 `CLAUDEX_WEB_CONFIG_DIR/backends.json`,可通过 `CLAUDEX_WEB_BACKENDS_FILE` 指定文件位置。配置包含固定的 `codex`、`claude` 两项,网页保存启停选择和 Claude Code 网络代理。CLI 程序自动检测,原生配置目录和 Codex 连接地址由服务环境统一取得,旧网页记录中的程序路径、参数及目录覆盖会自动归一化。供应商配置独立保留。变更启停前等待所属后端的任务结束。
138
+
139
+ ## 配置
140
+
141
+ 全局命令从 `~/.config/claudex-web/.env` 读取配置;设置 `XDG_CONFIG_HOME` 时使用其下的 `claudex-web` 目录,设置 `CLAUDEX_WEB_CONFIG_DIR` 时优先使用该目录。外部环境变量优先于 `.env`。执行 `claudex-web config init` 可创建配置并显示路径,已有配置和 npm 升级后的配置均会保留。
142
+
143
+ systemd 服务会记录安装时的配置目录,后续启动继续使用该目录。更换配置目录时,用新的 `CLAUDEX_WEB_CONFIG_DIR` 执行 `claudex-web service install`,再按下文方法重启网页服务。
144
+
145
+ - `HOST`:HTTPS 监听地址,初始为 `0.0.0.0`,支持通过电脑 IP 访问;仅本机访问可设为 `127.0.0.1`。
146
+ - `PORT`:网页端口,初始为 `8766`。
147
+ - `CODEX_APP_SERVER_URL`:Codex 后端 WebSocket 地址,初始为 `ws://127.0.0.1:8765`;使用已有后端时填写其实际地址。
148
+ - `CLAUDEX_WEB_CONFIG_DIR`:Claudex Web 自身配置与状态目录,默认 `$XDG_CONFIG_HOME/claudex-web`,未设置 `XDG_CONFIG_HOME` 时为 `~/.config/claudex-web`。连接设置、网页登录、证书、项目选择和网页索引统一保存在其中。
149
+ - `CODEX_HOME`:本机 Codex CLI 已使用的配置目录,默认 `~/.codex`。
150
+ - `CLAUDE_CONFIG_DIR`:本机 Claude Code CLI 已使用的配置目录,默认 `~/.claude`。
151
+ - `DEFAULT_CWD`:首次打开网页时的默认目录,未设置时使用当前用户的主目录;浏览器已经选择的项目目录优先。
152
+ - `STATIC_DIR`:网页资源目录,未设置时自动定位到当前安装包中的网页资源;相对路径以用户配置目录为基准。
153
+
154
+ 相对 `DEFAULT_CWD` 同样以用户配置目录为基准。建议为工作目录填写绝对路径,便于核对任务实际使用的位置。
155
+
156
+ 修改配置前先等待任务结束并退出网页终端,保存后执行 `claudex-web service restart`;前台运行时重新启动网页进程。修改端口后使用新端口访问。
157
+
158
+ `CODEX_APP_SERVER_URL` 用于指定网页连接地址。已有后端服务的监听地址继续由其服务配置管理,修改连接地址时需与实际后端保持一致。Codex 后端的环境配置见下一节。
159
+
160
+ ## systemd 服务
161
+
162
+ 网页服务名为 `claudex-web.service`,后端服务名为 `codex-app-server.service`。`claudex-web service install` 保留已有后端配置,更新网页服务文件,并让正在运行的服务继续运行。切换到新安装路径或配置后,通过重启使新设置生效。
163
+
164
+ 安装脚本创建的后端服务从用户配置目录下的 `.env.backend` 读取环境变量,可在其中配置后端代理。已有后端服务的代理、登录环境和启动设置继续由原服务配置管理。更改后端配置后,在所有相关对话和终端空闲时重启后端服务。
165
+
166
+ 查看状态与日志:
167
+
168
+ ```bash
169
+ systemctl --user status claudex-web.service codex-app-server.service
170
+ journalctl --user -u claudex-web.service -n 100 --no-pager
171
+ journalctl --user -u codex-app-server.service -n 100 --no-pager
172
+ curl --cacert "${CLAUDEX_WEB_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/claudex-web}/tls/certificate.pem" https://127.0.0.1:8766/healthz
173
+ ```
174
+
175
+ 自定义网页端口时,相应替换健康检查地址。`/healthz` 在至少一个已启用后端就绪时返回 HTTP 200,全部后端未就绪时返回 HTTP 503;响应包含连接状态 `ready` 和正在运行的网页服务版本 `version`。
176
+
177
+ ### Claude Code 执行服务
178
+
179
+ Claude Code 的任务使用独立执行服务。关闭网页、重启网页服务或网页服务异常退出后,已提交的对话任务和后台终端继续运行,重新打开网页后恢复状态。网页交互终端仍由网页服务管理,重启前先保存其需要保留的工作。
180
+
181
+ 使用 systemd 用户服务部署时,Claude Code 首次启用后自动建立名称为 `claudex-web-claude-<标识>.service` 的执行服务,其中标识由 Claudex Web 保存的 Claude 执行状态目录确定。查看状态与日志:
182
+
183
+ ```bash
184
+ systemctl --user list-units --all 'claudex-web-claude-*'
185
+ journalctl --user -u 'claudex-web-claude-*' -n 100 --no-pager
186
+ ```
187
+
188
+ 修改 Claude Code 运行配置或升级程序后,新网页服务自动核对执行服务。仍有对话、提问、整理或后台任务时继续使用原服务,空闲后完成更新。需要完全停止或更换执行服务时,先结束任务、处理待答提问并通过 `/stop` 清理后台终端;普通网页重启只重新连接。前台运行且没有 systemd 用户管理器时,执行服务日志保存在 `CLAUDEX_WEB_CONFIG_DIR/backends/claude/worker.log`。
189
+
190
+ ## 升级和回退
191
+
192
+ 从目标版本的 Release 获取安装地址。当前版本的安装与服务更新命令为:
193
+
194
+ ```bash
195
+ npm install -g ./claudex-web-4.0.1.tgz
196
+ claudex-web service install
197
+ claudex-web service restart-when-idle
198
+ ```
199
+
200
+ 最后一个命令等待网页服务观察到的任务和上下文整理结束后自动重启,等待期间保持命令运行。Claude Code 独立执行服务继续保留后台任务,代码及配置更新在该服务完全空闲后完成。打开或隐藏的网页终端不会阻塞更新,等待程序只重启网页服务。切换 Node.js 版本或 npm prefix 后,也需重新安装服务并重启,以更新服务中的安装路径。
201
+
202
+ 日志显示实际等待的任务与上下文整理数量;执行重启后继续检查 `/healthz`,连接就绪时报告实际运行版本,重启或健康检查失败时保留失败状态。
203
+
204
+ 升级后刷新网页,在“设置 → 关于”核对产品版本。`claudex-web version --json` 查看当前磁盘安装包,`/healthz` 中的 `version` 查看实际运行的服务,便于确认重启是否生效。
205
+
206
+ 需要回退程序时,使用目标旧版本 Release 的 `.tgz` 安装地址重新安装,执行 `claudex-web service install`,再等待空闲后重启。用户配置继续保留;涉及配置或数据迁移的版本,先查看对应发布说明。
207
+
208
+ 服务安装会备份被覆盖的网页服务文件,默认位置为 `~/.local/state/claudex-web/service-backups/时间戳/`;设置 `XDG_STATE_HOME` 时采用其下的对应目录。回退服务路径时,将备份的 `claudex-web.service` 恢复到用户服务目录,默认 `~/.config/systemd/user/`;设置 `XDG_CONFIG_HOME` 时使用其下的 `systemd/user/`。执行 `systemctl --user daemon-reload`,确认原安装路径仍可用,再等待空闲后重启网页服务。
209
+
210
+ ## 数据保存与迁移
211
+
212
+ - Codex 和 Claude Code 的原生对话、配置及登录凭据继续由各自 CLI 管理。网页对话索引和供应商设置保存在 `CLAUDEX_WEB_CONFIG_DIR`;迁移网页时保留该目录,并将后端连接指向本机 CLI 的实际配置目录。网页登录与模型服务认证分别管理,系统密码仅用于登录验证,不会保存。
213
+ - 草稿、置顶、固定文件夹、项目快捷列表和主题保存在当前浏览器中。固定文件夹在全部对话归档后仍会在刷新或重新打开网页时显示;手动添加的项目自动固定,取消固定后在下次加载时按未归档对话重新确定是否显示。使用同一浏览器及站点地址可恢复固定记录,清除站点数据会清除这些记录。
214
+ - Codex 每个项目上次选择的模型和思考强度保存在服务所在电脑的 `CLAUDEX_WEB_CONFIG_DIR/project-models.json`。Claude Code 项目选择保存在 `CLAUDEX_WEB_CONFIG_DIR/backends/claude/project-models.json`,迁移服务时分别保留。同项目新建沿用当前选择,跨项目及重新打开网页时恢复目标项目设置,清空浏览器数据后可再次从服务端读取。保存失败时会提示重试。切换模型时保留当前思考强度,目标模型缺少该档位时采用最近的可用档位,距离相同时选较低档。
215
+ - “未分类”对话的文件保存在 `CLAUDEX_WEB_CONFIG_DIR/workspaces/chat-XXXXXX`,首次发送时分配。迁移电脑时随 Claudex Web 配置目录一起保留。
216
+ - 网页配置 `.env` 与新建后端服务使用的 `.env.backend` 位于用户配置目录,迁移时应一并保留;已有后端服务的配置按原部署方式迁移。
217
+ - 摘要翻译由服务所在电脑调用免费、免认证的 TranSmart 服务,浏览器仅访问当前网页服务;待译摘要会发送至 TranSmart,代码、路径和链接在发送前替换为占位符。
218
+ - 自动对话标题使用 Codex 模型,会产生少量额外模型用量。
219
+
220
+ ## 故障定位
221
+
222
+ 网页不可访问时,先检查网页服务状态、监听端口和主机网络。网页可打开但显示后端未连接时,按当前对话所属服务检查 Codex 后端日志与监听地址,或 Claude Code 可执行文件、原有配置目录和供应商连接。列表中某个后端读取失败时,已有对话会继续显示,按实际错误处理后点击重试。
223
+
224
+ 账户额度会自动更新。若额度变灰并显示“待更新”,可稍后重试并检查网络连接。恢复连接后会自动更新。外部供应商的账单及余额在所属服务中核对;输入区的上下文用量反映当前对话占用,与账户额度分别显示。
225
+
226
+ Claude Code 请求失败时,错误提示显示认证、额度、连接或接口协议等实际问题,并可展开诊断详情。检查并修改对应供应商配置后,可以编辑失败消息重新提交。模型执行期间的草稿和附件继续保留。
227
+
228
+ 摘要翻译失败时,页面保留原文并提供重试入口。检查服务所在电脑能否访问 `transmart.qq.com`,以及翻译服务是否正常响应。升级后翻译仍不可用时,等待任务与网页终端结束,再重启网页服务。
229
+
230
+ ### 对话被占用
231
+
232
+ 提示对话被占用时,先在另一个 Codex 窗口中结束该对话的任务并关闭对话,再返回网页点击“重试”。恢复后可继续编辑和发送,原有草稿及附件会保留。
233
+
234
+ 网页会在对话空闲时释放自身的占用,下一次发送时自动恢复。关闭页面后,已经提交的任务继续执行,结束后释放占用。独立 Codex 客户端的占用由对应客户端和后端管理,结束任务后仍被占用时,需检查该客户端是否继续加载对话。
235
+
236
+ 为使空闲对话及时释放,本项目启动的 Codex 后端使用以下命令,让无人使用的对话及时解除占用:
237
+
238
+ ```bash
239
+ codex -c thread_unload_delay_secs=0 app-server --listen ws://127.0.0.1:8765
240
+ ```
241
+
242
+ 已有 `codex-app-server.service` 会保留原配置。使用 `systemctl --user cat codex-app-server.service` 检查启动命令,在原 Codex 命令中加入 `-c thread_unload_delay_secs=0`,保留原可执行路径、代理、登录环境和监听地址。该参数在后端启动时生效。
243
+
244
+ 调整已有后端后,先确认所有连接到该后端的客户端均已结束相关任务和终端,再执行:
245
+
246
+ ```bash
247
+ systemctl --user daemon-reload
248
+ systemctl --user restart codex-app-server.service claudex-web.service
249
+ ```
250
+
251
+ `claudex-web service restart-when-idle` 检查网页服务观察到的任务和上下文整理。重启后端还需确认其他客户端以及网页终端、对话后台终端的运行状态。
252
+
253
+ ## 从 Codex Web 更名版本升级
254
+
255
+ Claudex Web 的命令为 `claudex-web`,网页服务为 `claudex-web.service`,默认配置目录为 `~/.config/claudex-web`;可用 `CLAUDEX_WEB_CONFIG_DIR` 指定其他位置,`CLAUDEX_WEB_BACKENDS_FILE` 指定后端配置文件。原生 Codex 与 Claude Code 的配置和历史沿用各自目录。
256
+
257
+ Claudex Web 4.0.0 使用本页顶部的正式版安装地址。已发布的 Codex Web 安装包继续使用原有名称与命令。
258
+
259
+ 升级前结束运行中的任务与终端,保存文件,再执行 `systemctl --user disable --now codex-lan-web.service` 停用旧网页服务。安装新包后执行 `claudex-web service install`。首次启动在新配置目录尚未建立时复制旧 `~/.config/codex-web`;曾自定义旧目录的部署可在此次升级时设置 `CODEX_WEB_CONFIG_DIR` 指向原目录。新目录已有配置优先,旧目录保留,已有自动工作目录继续可访问。配置包含供应商凭据、证书和会话,请保护备份权限。
260
+
261
+ ### 从 Claudex Web 4.x 回到 3.x
262
+
263
+ 升级前备份原 `codex-web` 网页配置和用户服务文件。首次迁移保留旧配置目录;4.x 对 `claudex-web` 配置的修改保存在新目录。回到 3.x 前结束两端任务及后台终端,停用 `claudex-web.service`,从稳定版本 Release 重新安装原 `codex-web` 包,再按该版本部署说明恢复旧网页服务。Claude Code 对话继续保存在原生目录,3.x 网页展示 Codex 对话。
264
+
265
+ ### Claude Code 网络代理
266
+
267
+ Claude Code 的网络代理使用服务器可访问的代理地址和端口,支持 HTTP 代理、关闭及跟随服务环境。HTTP 代理通过 CONNECT 访问 HTTPS 目标;旧 HTTPS 代理选项会迁移为 HTTP。服务器本机部署的代理可填写 `127.0.0.1`,远端代理填写其主机名或 IP。保存配置前结束 Claude 后端的活动任务及后台终端;保存成功后,后续会话使用新代理。
268
+
269
+ 首次升级沿用服务进程的代理环境;选择关闭会清除继承的代理。本机回环地址直接连接,以便访问本地模型服务。代理影响 Claude 执行服务、模型请求及其原生联网工具;WebFetch 的域名安全检查继续开启。WebSearch 还要求上游提供实际搜索能力,或通过搜索 MCP 接入独立搜索服务。